@slats/claude-assets-sync 0.1.4 → 0.3.0

package/docs/claude/skills/claude-docs-asset-wiring/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: claude-docs-asset-wiring
+description: "Wire a consumer package's docs/claude assets into the @slats/claude-assets-sync engine. Adds package.json.claude.assetPath, points scripts.build:hashes at claude-build-hashes, declares the engine as a dependency, updates CLAUDE.md, and runs the dispatcher smoke test. Idempotent — asks before clobbering."
+user-invocable: true
+disable-model-invocation: true
+argument-hint: <target-package-path>
+---
+
+# claude-docs-asset-wiring
+
+Wire a consumer package's `docs/claude/**` into `@slats/claude-assets-sync`
+so end users can inject those assets via the engine's `inject-claude-settings`
+bin. Reference consumer: `packages/canard/schema-form`.
+
+The engine is single-dispatcher. Consumers do NOT ship their own bin stubs
+— they declare `claude.assetPath` in `package.json` and let the engine's
+`claude-build-hashes` bin regenerate `dist/claude-hashes.json` during
+build. `src/core/**` never reads `package.json`; only the engine's `bin/`
+layer resolves a single explicitly-named target.
+
+**Outcome**
+
+```bash
+npx -p @slats/claude-assets-sync inject-claude-settings \
+  --package=<PACKAGE_NAME> \
+  --scope=user|project [--dry-run] [--force]
+```
+
+## Role
+
+You are a monorepo wiring specialist. Execute the 6 steps below as a
+single, idempotent procedure. On any conflicting existing value — ask
+the user before overwriting. Never clobber silently.
+
+## Knowledge Resources
+
+Consult these files as needed during execution. Do NOT preload everything;
+load on demand.
+
+- `knowledge/reference-files.md` — what the consumer should (and should not) own
+- `knowledge/package-json-patches.md` — every required `package.json` edit, with guard conditions
+- `knowledge/claude-md-template.md` — the `## Claude Docs Injector` section to inject into the target `CLAUDE.md`
+- `knowledge/smoke-tests.md` — E2E 8-path matrix via the engine dispatcher
+- `knowledge/dependency-cruiser.md` — optional CI-time isolation rule
+- `knowledge/gotchas.md` — invariants and pitfalls
+
+## Inputs
+
+Resolve these before starting. If any is missing, stop and ask.
+
+| Variable       | Source                                                                                                    |
+|----------------|-----------------------------------------------------------------------------------------------------------|
+| `TARGET_PATH`  | Skill argument (e.g. `packages/lerx/promise-modal`). If absent, ask the user.                             |
+| `PACKAGE_NAME` | `name` field of `${TARGET_PATH}/package.json`.                                                            |
+| `SHORTCUT`     | Root `package.json` `scripts` entry whose value equals `yarn workspace ${PACKAGE_NAME}`; else unset.      |
+
+`SHORTCUT` is a convenience only. When unset, fall back to full workspace
+syntax: `yarn workspace ${PACKAGE_NAME} <subcommand>`.
+
+## Pre-Flight
+
+Stop and report on any failure. Do not attempt to fix silently.
+
+- [ ] `${TARGET_PATH}/docs/claude/skills/<name>/SKILL.md` and `knowledge/*.md` exist — the docs to be injected.
+- [ ] `${TARGET_PATH}/package.json` has `"type": "module"` and `"sideEffects": false`.
+- [ ] Build pipeline uses `rollup -c && yarn build:types` where `build:types` runs `node ../../aileron/script/build/buildTypes.mjs`.
+- [ ] `git status` in `${TARGET_PATH}` is clean. Unrelated changes present → confirm with user before proceeding.
+
+## Steps
+
+Execute in order. Each step is idempotent; on conflict, ask rather than overwrite.
+
+### Step 1 — Patch `${TARGET_PATH}/package.json`
+
+See `knowledge/package-json-patches.md` for the complete patch list:
+
+- `claude.assetPath` — set to `docs/claude` (or the consumer's chosen path).
+- `scripts.build` — ensure the chain ends with `&& yarn build:hashes`.
+- `scripts.build:hashes` — set to `claude-build-hashes` (the engine's bin).
+- `scripts.prepublishOnly` — `yarn build` if not already present.
+- `dependencies."@slats/claude-assets-sync"` — add (NOT `devDependencies`, NOT `peerDependencies`).
+- `files` — ensure `"dist"`, `"docs"`, `"README.md"` are listed. Never include `"bin"` or `"scripts"`.
+
+Do NOT add any `bin` entry. Do NOT add `./bin/*` or `./docs/*` to `exports`.
+Do NOT create `bin/` or `scripts/` directories in the consumer.
+
+### Step 2 — Patch `${TARGET_PATH}/CLAUDE.md`
+
+If `CLAUDE.md` exists, append or replace the `## Claude Docs Injector`
+section from `knowledge/claude-md-template.md`, substituting
+`${PACKAGE_NAME}`. Skip if `CLAUDE.md` does not exist (do not create one).
+
+### Step 3 — (Optional) Dependency-cruiser isolation gate
+
+Skip unless `${TARGET_PATH}/.dependency-cruiser.cjs` already exists or the
+user explicitly asks. See `knowledge/dependency-cruiser.md` for the single
+remaining forbidden rule (`src/**` → `docs/**`) and the `depcheck` script.
+
+### Step 4 — Install and build
+
+```bash
+yarn install
+yarn ${SHORTCUT:-workspace ${PACKAGE_NAME}} build
+```
+
+Expected: `rollup` → `buildTypes` → `claude-build-hashes` succeed, and
+`${TARGET_PATH}/dist/claude-hashes.json` is written.
+
+### Step 5 — E2E smoke via engine dispatcher
+
+Run from `/tmp/...`, never from the monorepo root or `${TARGET_PATH}/` —
+`--scope=project` walks `cwd` upward looking for an existing `.claude`,
+which would mutate the real repo's. See `knowledge/smoke-tests.md` for
+the full 8-path matrix, expected exit codes, and rationale.
+
+### Step 6 — Report
+
+Summarize:
+
+- Files patched vs. skipped (with reason for each skip).
+- Manifest file count from `dist/claude-hashes.json`.
+- Smoke-test exit codes (all 8).
+- Recommendation: commit this change on its own, separate from other work.
+
+## Report Template
+
+```markdown
+## claude-docs-asset-wiring — ${PACKAGE_NAME}
+
+**Files patched**
+- package.json                 — patched: [claude.assetPath, scripts.build, scripts.build:hashes, dependencies, files]
+- CLAUDE.md                    — section added | skipped (no CLAUDE.md)
+- .dependency-cruiser.cjs      — updated | skipped (not present)
+
+**Manifest**
+- dist/claude-hashes.json: <N> files
+
+**Smoke tests**
+| # | command                                                     | expected | actual |
+|---|-------------------------------------------------------------|----------|--------|
+| 1 | --package=${PACKAGE_NAME} --scope=project --dry-run         | 0        | <n>    |
+| 2 | --package=${PACKAGE_NAME} --scope=project                   | 0        | <n>    |
+| 3 | --package=${PACKAGE_NAME} --scope=project (up-to-date)      | 0        | <n>    |
+| 4 | CI=true --package=${PACKAGE_NAME} --scope=project (tampered)| 2        | <n>    |
+| 5 | CI=true --package=${PACKAGE_NAME} --scope=project --force   | 0        | <n>    |
+| 6 | CI=true --package=${PACKAGE_NAME} (missing --scope)         | 2        | <n>    |
+| 7 | (missing --package)                                         | 2        | <n>    |
+| 8 | --package=@does/not-exist                                   | 2        | <n>    |
+
+**Next**: commit on its own — do not bundle with unrelated changes.
+```
+
+## Termination Conditions
+
+- **Pre-Flight fails** → stop, report the failing check. Do not proceed.
+- **Conflict during patch** → stop, show the diff, ask user whether to overwrite.
+- **Build fails at Step 4** → stop, report error. Do not run smoke tests on a broken build.
+- **Smoke test mismatch** → stop, report the failing path with captured exit code.
+- **All steps pass** → emit the report from the template above.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/claude-md-template.md

@@ -0,0 +1,86 @@
+# `CLAUDE.md` — `## Claude Docs Injector` section
+
+Reference: `packages/canard/schema-form/CLAUDE.md`.
+
+Append the section below to `${TARGET_PATH}/CLAUDE.md` if the file
+exists. Substitute the sample package name in the chosen template
+with `${PACKAGE_NAME}` — six occurrences. Skip the entire step if
+`CLAUDE.md` does not exist (do not create one).
+
+The template is intentionally terse: CLI usage + essential isolation
+warnings. Architectural rationale lives in `knowledge/gotchas.md` —
+do not duplicate it into every consumer's `CLAUDE.md`.
+
+---
+
+## Template (Korean — used by all consumers except `@winglet/style-utils`)
+
+````markdown
+## Claude Docs Injector
+
+`docs/claude/**` 자산을 사용자 `.claude/` 에 주입. 엔진: `@slats/claude-assets-sync` (bin: `inject-claude-settings`).
+
+```bash
+# universal — 모든 PM (pnpm strict / yarn-berry PnP 포함)
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=project
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user --dry-run
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user --force
+
+# 간편 — npm / yarn-classic 에서만 (transitive bin hoist 기반)
+npx inject-claude-settings --package=@canard/schema-form --scope=user
+```
+
+### Isolation Guardrails
+
+- `src/**` 는 `docs/**` 와 `@slats/claude-assets-sync` 어느 것도 import 금지.
+- **절대 `exports` 에 `./docs/*` 를 추가하지 말 것.**
+````
+
+---
+
+## Template (English — `@winglet/style-utils` convention)
+
+````markdown
+## Claude Docs Injector
+
+Inject `docs/claude/**` into the user's `.claude/`. Engine: `@slats/claude-assets-sync` (bin: `inject-claude-settings`).
+
+```bash
+# universal — every PM (pnpm strict / yarn-berry PnP included)
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=user
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=project
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=user --dry-run
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/style-utils --scope=user --force
+
+# simple — npm / yarn-classic only (relies on transitive bin hoist)
+npx inject-claude-settings --package=@winglet/style-utils --scope=user
+```
+
+### Isolation Guardrails
+
+- `src/**` MUST NOT import from `docs/**` or `@slats/claude-assets-sync`.
+- **Never add `./docs/*` to `exports`.**
+````
+
+---
+
+## Substitution Rules
+
+- Replace the sample package name in the chosen template with
+  `${PACKAGE_NAME}` — six occurrences.
+- Preserve the Isolation Guardrails bullets verbatim — these are
+  the sharp invariants that must stay consistent across consumers.
+
+---
+
+## Placement & Skip Conditions
+
+- Append to end of `CLAUDE.md`. Ensure one blank line before the
+  injected section.
+- `${TARGET_PATH}/CLAUDE.md` does not exist → skip, report
+  "skipped (no CLAUDE.md)".
+- Section already present with identical content → skip, report
+  "unchanged".
+- Section present with different content → ask user, do not
+  clobber.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/dependency-cruiser.md

@@ -0,0 +1,54 @@
+# Dependency-Cruiser Isolation Rule (optional)
+
+Skip this step unless `${TARGET_PATH}/.dependency-cruiser.cjs`
+already exists or the user explicitly asks. This guardrail is a
+CI-time check that the consumer's `src/**` never reaches the
+Claude assets tree.
+
+The post-v0.3.0 layout removes the bin stub entirely, so the
+former `src-no-bin` and `src-no-claude-assets-sync` rules are no
+longer load-bearing — the consumer no longer imports any of that
+from anywhere. The one remaining invariant is `src/**` must not
+import from `docs/**`.
+
+## Rule
+
+```javascript
+module.exports = {
+  forbidden: [
+    {
+      name: 'src-no-docs',
+      severity: 'error',
+      comment:
+        'src/ must not import from docs/. docs/claude/** contains pure markdown ' +
+        'assets meant only for the engine dispatcher, not for the library runtime.',
+      from: { path: '^src/' },
+      to: { path: '^docs/' },
+    },
+  ],
+  options: {
+    doNotFollow: { path: 'node_modules' },
+    includeOnly: '^(src|docs)',
+  },
+};
+```
+
+## Optional script
+
+```json
+"scripts": {
+  "depcheck": "depcruise src docs --config .dependency-cruiser.cjs --no-progress"
+}
+```
+
+Zero errors expected. Orphan warnings on `docs/**` are
+acceptable — the docs tree never imports anything.
+
+## Legacy rules removed
+
+Previous revisions of this skill had three forbidden rules
+(`src-no-bin`, `src-no-docs`, `src-no-claude-assets-sync`), a
+`no-orphans` adjustment excluding `^bin/`, and an `includeOnly`
+covering `^src` and `^bin`. All of those assumed the consumer
+owned a `bin/` directory. The new layout owns no `bin/`, so the
+extra rules are dead. Do not reintroduce them.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/gotchas.md

@@ -0,0 +1,122 @@
+# Invariants and Gotchas
+
+Hard-earned rules. Each one reflects a previous incident or a design
+constraint of the `@slats/claude-assets-sync` engine.
+
+---
+
+## The engine is the only CLI surface
+
+`inject-claude-settings` lives in one place: the engine package. No
+consumer has a bin. No consumer has a `bin/` directory. No consumer
+has a `scripts/` directory. If you find yourself "adapting" a stub
+for a new consumer, stop — wiring does not need code; it needs two
+fields in `package.json`.
+
+---
+
+## `claude.assetPath` is the opt-in marker
+
+The engine's `claude-build-hashes` bin silently no-ops when
+`claude.assetPath` is missing or not a string. The dispatcher
+(`inject-claude-settings`) exits 2 with a clear error when a target
+lacks the field. Both behaviors are intentional: missing = opt-out.
+
+Do not add "helpful" error messages at build time for the opt-out
+case — it would break silently-disabled packages.
+
+---
+
+## `@slats/claude-assets-sync` must be in `dependencies`
+
+Not `devDependencies`, not `peerDependencies`. Reasons:
+
+1. Monorepo build chain needs `.bin/claude-build-hashes` resolved,
+   which requires the engine as a direct dep of each consumer.
+2. For end users on npm / yarn-classic, listing the engine in
+   `dependencies` makes `inject-claude-settings` transitively
+   hoisted into `node_modules/.bin/`, enabling the short
+   invocation `npx inject-claude-settings --package=<THIS>`.
+3. Bundle isolation is enforced by the import graph (`src/**`
+   never references the engine), not by dependency-type.
+
+Pnpm strict users do not get the transitive hoist and must use the
+universal form `npx -p @slats/claude-assets-sync inject-claude-settings
+--package=<THIS>`. Every consumer's CLAUDE.md documents both paths.
+
+---
+
+## Never add `./bin/*` or `./docs/*` to `exports`
+
+The `exports` map in `package.json` controls which subpaths a
+consumer's bundler can resolve. Keeping `./docs/*` out of
+`exports` is what prevents a bundler from deep-importing the docs
+tree into app bundles.
+
+---
+
+## Do not commit `dist/claude-hashes.json`
+
+It is a build artifact. The `yarn build` chain regenerates it via
+`build:hashes`. It should be in `.gitignore` (usually via a
+catch-all `dist/` rule). If you see it in `git status`, stop —
+something is misconfigured.
+
+---
+
+## `yarn workspace ${PACKAGE_NAME} build` can fail with `rollup: command not found`
+
+Yarn v4 workspace dispatch does not always propagate the
+workspace-local PATH. Prefer `yarn ${SHORTCUT} build` from the
+monorepo root, where `${SHORTCUT}` is the root-level script alias
+(e.g. `yarn schemaForm`, `yarn claudeAssetsSync`).
+
+If no shortcut exists, the full form may still work depending on
+yarn version and cache state — but if it fails with `rollup:
+command not found`, add a shortcut to the root `package.json`
+rather than debugging the nested call.
+
+---
+
+## `--scope=project` walks upward
+
+`--scope=project` walks `process.cwd()` upward looking for an
+existing `.claude` directory. The first one found is reused; if
+none is found, the engine creates one at `cwd`.
+
+Consequence: running the smoke tests from the monorepo root would
+reuse the monorepo's real `.claude`, corrupting it. Always run
+smoke tests from `/tmp/...` with a fresh directory.
+
+---
+
+## Dispatcher exception to the `src/core` purity rule
+
+`src/core/**` never reads `package.json` or walks the filesystem.
+The engine's `bin/inject-claude-settings.mjs` and
+`src/commands/runCli/utils/resolvePackage.ts` are allowed to
+`createRequire().resolve(`${name}/package.json`)` for exactly one
+target — the one named in `--package=<name>`. The dispatcher never
+enumerates, never walks `node_modules` for siblings. Preserve this
+boundary: extensions like `--all` or workspace scan require
+explicit re-architecture.
+
+---
+
+## Commit this change alone
+
+The change set from this skill touches the consumer's
+`package.json` and possibly its `CLAUDE.md`. It should land in a
+single commit, with no unrelated changes interleaved.
+
+Reasons:
+
+- Easier to revert as a unit if an issue appears downstream.
+- The CI signal (smoke tests) is bound to the state of these files
+  and nothing else.
+- Reviewers can skim-verify against the reference consumer without
+  reviewing business logic.
+
+If the user asks to bundle with other work, push back once:
+recommend a separate commit. If they still want it bundled,
+proceed but note it in the Step 6 report.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/package-json-patches.md

@@ -0,0 +1,145 @@
+# `package.json` Patches
+
+All edits below are **additive**. Existing non-conflicting values
+remain untouched. On any conflicting existing value, stop and ask the
+user — do not overwrite.
+
+Reference: `packages/canard/schema-form/package.json`.
+
+---
+
+## 1. `claude.assetPath`
+
+```json
+"claude": {
+  "assetPath": "docs/claude"
+}
+```
+
+Consumer-side convention — the engine does not enforce it. Relative
+to the consumer's package root. If the field already exists with a
+non-default value, preserve it.
+
+A missing or non-string value is an intentional opt-out: the
+dispatcher will exit 2 with a clear error, and `claude-build-hashes`
+will silently no-op. Do not remove the opt-out path.
+
+---
+
+## 2. `scripts.build`
+
+Ensure the build chain invokes `yarn build:hashes` at the end:
+
+```json
+"scripts": {
+  "build": "rollup -c && yarn build:types && yarn build:hashes"
+}
+```
+
+**Guard against double-append.** If the existing value already
+contains `build:hashes`, leave it alone.
+
+---
+
+## 3. `scripts.build:hashes`
+
+Point to the engine's bin (NOT a local stub):
+
+```json
+"scripts": {
+  "build:hashes": "claude-build-hashes"
+}
+```
+
+`claude-build-hashes` reads `process.cwd()/package.json` and picks
+up `claude.assetPath`. Works because `@slats/claude-assets-sync` is
+in `dependencies`, so `node_modules/.bin/claude-build-hashes` is
+linked.
+
+If a different `build:hashes` script exists, ask.
+
+---
+
+## 4. `scripts.prepublishOnly`
+
+```json
+"scripts": {
+  "prepublishOnly": "yarn build"
+}
+```
+
+Guarantees `dist/claude-hashes.json` is regenerated before publish.
+If the target already has a `prepublishOnly` that calls `yarn build`
+(directly or transitively), leave it alone.
+
+---
+
+## 5. `dependencies."@slats/claude-assets-sync"`
+
+**Must be in `dependencies`, never `devDependencies` or
+`peerDependencies`.**
+
+```json
+"dependencies": {
+  "@slats/claude-assets-sync": "workspace:^"
+}
+```
+
+Reasons:
+
+- Monorepo build chain needs `.bin/claude-build-hashes` resolved,
+  which requires the engine as a direct dep.
+- On npm / yarn-classic, listing the engine in `dependencies` makes
+  `inject-claude-settings` transitively hoisted into
+  `node_modules/.bin/` for end users, enabling the short
+  invocation `npx inject-claude-settings --package=<THIS>`.
+- Bundle isolation is enforced by the import graph (`src/**` never
+  references the engine), not by dependency-type.
+
+If the target already has it in `devDependencies` or
+`peerDependencies`, move it to `dependencies`. Do not duplicate.
+
+---
+
+## 6. `files`
+
+Ship the published artifact surface. Keep `"dist"`, `"docs"`, and
+`"README.md"` (plus whatever else the package needs). Do NOT
+include `"bin"` or `"scripts"`:
+
+```json
+"files": [
+  "dist",
+  "docs",
+  "README.md"
+]
+```
+
+If `files` is absent, create it with at least `["dist", "docs", "README.md"]`.
+
+---
+
+## 7. `bin` — MUST be ABSENT
+
+Never add a `bin` field. Bin names collide across consumers under
+`node_modules/.bin/` and the engine is the sole CLI surface.
+
+---
+
+## 8. `exports` — never add `./bin/*` or `./docs/*`
+
+Exports control which subpaths a consumer's bundler can resolve.
+Keeping `./bin/*` and `./docs/*` out of `exports` is what prevents
+consumer bundlers from pulling the CLI or the asset tree into app
+bundles.
+
+---
+
+## Full Reference
+
+See `packages/canard/schema-form/package.json` for the canonical
+shape. The relevant keys are `scripts.build`,
+`scripts.build:hashes`, `scripts.prepublishOnly`,
+`dependencies."@slats/claude-assets-sync"`, `claude.assetPath`, and
+`files`. Everything else in that file is schema-form-specific and
+must not be copied.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/reference-files.md

@@ -0,0 +1,37 @@
+# Reference Files
+
+Consumers do **not** own any runtime files for the injector. The whole
+CLI surface lives in `@slats/claude-assets-sync`. A consumer is wired
+up by editing `package.json` and (optionally) `CLAUDE.md` — nothing
+else.
+
+Reference consumer: `packages/canard/schema-form`.
+
+## What the consumer MUST own
+
+- `docs/claude/**` — the assets to ship (skills / rules / commands).
+- `package.json.claude.assetPath` — string, usually `"docs/claude"`.
+
+## What the consumer MUST NOT own
+
+- Any `bin/` directory or stub file. The engine owns the dispatcher.
+- Any `scripts/build-hashes.mjs` wrapper. Use the engine's
+  `claude-build-hashes` bin directly in `scripts.build:hashes`.
+- Any `"bin"` entry in `package.json`.
+- `./bin/*` or `./docs/*` exposed in `exports`. Exposing them would
+  let bundlers pull CLI code or the docs tree into app bundles.
+
+## What the engine provides
+
+- `inject-claude-settings` bin — dispatcher. Invoked as
+  `npx -p @slats/claude-assets-sync inject-claude-settings --package=<name> --scope=<scope>`,
+  or (on npm / yarn-classic) `npx inject-claude-settings --package=<name> --scope=<scope>`
+  once the engine is installed as a transitive dependency of the
+  consumer.
+- `claude-build-hashes` bin — reads `process.cwd()/package.json`,
+  picks up `claude.assetPath`, hashes every file beneath it, and
+  writes `dist/claude-hashes.json`. Run via `yarn build:hashes` in
+  the consumer build chain.
+- `buildHashes()` + `injectDocs()` — headless programmatic APIs.
+
+No content mirroring across consumers. No stub drift to manage.