obsidian-plugin-config/docs/LLM-GUIDE.md

Global CLI injection tool for Obsidian plugins

# LLM Guide — obsidian-plugin-config

## What this tool does

**obsidian-plugin-config** is a **pure injection tool** that copies scripts and configuration files into Obsidian plugins, making them 100% standalone.

---

## Architecture

### templates/ — Source of truth

`templates/` contains everything that gets injected into target plugins:

- `templates/scripts/` — scripts copied into `<target>/scripts/`
- `templates/package.json.template` — base deps/scripts merged into `<target>/package.json`
- `templates/tsconfig.json.template` — TypeScript config injected as `<target>/tsconfig.json`
- `templates/eslint.config.mts` — ESLint config injected into target
- `templates/.editorconfig`, `templates/.prettierrc`, etc. — config files injected into target
- `templates/.github/workflows/` — GitHub Actions workflows

### scripts/ — Injection logic

- `scripts/inject-core.ts` — main injection logic
- `scripts/inject-path.ts` — CLI entry point (parses flags)
- `scripts/inject-prompt.ts` — interactive injection
- `scripts/build-npm.ts` — NPM publish workflow
- `scripts/acp.ts`, `scripts/help.ts`, `scripts/update-version-config.ts`, `scripts/utils.ts` — utilities

### bin/ — Global CLI

- `bin/obsidian-inject.js` — global CLI entry point (generated by build-npm.ts)

---

## What injection does

### 1. Package.json merge

`inject-core.ts → updatePackageJson()` reads `templates/package.json.template` and merges into the target plugin's `package.json`:

- All `scripts` are overwritten with template values
- All `devDependencies` from template are added/updated
- `engines` and `type` are set from template
- Target plugin's own specific deps are preserved

### 2. File copying

`inject-core.ts → injectScripts()` copies files from `templates/` into the target:

- `templates/scripts/*` → `<target>/scripts/`
- `templates/tsconfig.json` → `<target>/tsconfig.json`
- `templates/eslint.config.mts` → `<target>/eslint.config.mts`
- `templates/.editorconfig`, `.prettierrc`, `.npmrc`, `.env`, `.gitattributes` → `<target>/`
- `templates/.vscode/*` → `<target>/.vscode/`
- `templates/.github/workflows/*` → `<target>/.github/workflows/`
- `templates/gitignore.template` → `<target>/.gitignore`

### 3. Traceability

Creates `.injection-info.json` in target with version and date.

---

## Template scripts

Scripts in `templates/scripts/` that get copied to target plugins:

**Build system (modular):**
- `esbuild.config.ts` — build entry point, orchestrates all build modules
- `constants.ts` — shared constants (external deps list, banner, REST port)
- `env.ts` — environment validation, manifest check, build path resolution
- `reload.ts` — Obsidian hot-reload via Local REST API
- `typingsPlugin.ts` — esbuild plugin for obsidian-typings resolution
- `utils.ts` — shared utilities (readline, file ops, git, vault path helpers)

**Workflow scripts:**
- `acp.ts` — add, commit, push workflow
- `update-version.ts` — version bump utility
- `release.ts` — GitHub release automation
- `help.ts` — help documentation

---

## SASS support

SCSS is handled automatically by the injected `esbuild.config.ts`:

1. The build detects `.scss` files (e.g. `src/styles.scss`)
2. When found, it dynamically imports `esbuild-sass-plugin` and compiles the SCSS
3. The generated `main.css` is cleaned up after compilation

The `esbuild-sass-plugin` dependency is **not** injected automatically. If a plugin uses SCSS, install it once with `yarn add -D esbuild-sass-plugin` (the build prints a clear warning if it is missing). Plugins without `.scss` files build normally with no extra dependency.

---

## What NOT to do

- ❌ Do not hardcode deps/scripts in `inject-core.ts` — they must come from `templates/package.json.template`
- ❌ Do not modify root config files thinking it will affect injected plugins — always modify `templates/`
- ❌ Do not add `obsidian-plugin-config` as a dependency in `templates/package.json.template` — injected plugins are standalone
- ❌ Do not inject `esbuild.config.ts` without its dependencies (`constants.ts`, `env.ts`, `reload.ts`, `typingsPlugin.ts`, `utils.ts`) — they are all required

---

## Updating injected content

To change what gets injected:

1. Modify files in `templates/`
2. Test locally: `yarn inject-path ../test-plugin`
3. Publish: `yarn npm-publish`
4. Re-inject into existing plugins to update them

---

## obsidian-typings paths

The correct paths for `obsidian-typings` in `templates/tsconfig.json.template`:

```json
"types": ["obsidian-typings"],
"paths": {
  "obsidian-typings/implementations": [
    "./node_modules/obsidian-typings/dist/cjs/implementations.d.cts",
    "./node_modules/obsidian-typings/dist/esm/implementations.mjs"
  ]
}
```

These must stay in sync with the actual `obsidian-typings` package structure.