@slats/claude-assets-sync 0.2.0 → 0.3.1

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,125 @@
+# 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 `devDependencies`
+
+Not `dependencies`, not `peerDependencies`. Reasons:
+
+1. The engine is CLI-only. Declaring it in `dependencies` would
+   pull `commander`, `@inquirer/prompts`, and their transitive
+   trees into every end-user's production install even though the
+   consumer's runtime never imports the engine.
+2. The monorepo build chain still resolves `.bin/claude-build-hashes`
+   from `devDependencies` at `yarn install` time — yarn workspaces
+   link devDeps and deps identically for workspace-local builds.
+3. End users never rely on a hoisted `inject-claude-settings` bin.
+   The canonical invocation is `npx -p @slats/claude-assets-sync
+   inject-claude-settings --package=<THIS>`, which fetches the
+   engine on demand and caches it.
+4. Bundle isolation is enforced by the import graph (`src/**`
+   never references the engine), not by dependency-type.
+
+Every consumer's CLAUDE.md documents the single `npx -p` path.
+
+---
+
+## 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,150 @@
+# `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 `devDependencies`, so `node_modules/.bin/claude-build-hashes` is
+linked at workspace install time (yarn workspaces link devDeps and
+deps identically for workspace-local builds).
+
+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. `devDependencies."@slats/claude-assets-sync"`
+
+**Must be in `devDependencies`, never `dependencies` or
+`peerDependencies`.**
+
+```json
+"devDependencies": {
+  "@slats/claude-assets-sync": "workspace:^"
+}
+```
+
+Reasons:
+
+- The engine is CLI-only. Declaring it in `dependencies` would pull
+  `commander`, `@inquirer/prompts`, and their transitive trees into
+  every end-user's production install even though the consumer's
+  runtime never imports the engine.
+- The monorepo build chain still resolves `.bin/claude-build-hashes`
+  from `devDependencies` at `yarn install` time — yarn workspaces
+  link devDeps and deps identically for workspace-local builds.
+- End users invoke the engine via `npx -p @slats/claude-assets-sync
+  inject-claude-settings --package=<THIS>`, which fetches the engine
+  on demand and caches it. No transitive bin hoist is required.
+- Bundle isolation is enforced by the import graph (`src/**` never
+  references the engine), not by dependency-type.
+
+If the target already has it in `dependencies` or
+`peerDependencies`, move it to `devDependencies`. 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>`.
+  The engine is a consumer-side `devDependency` only, so end users
+  never get a hoisted bin; the `npx -p` form pulls the engine on
+  demand and caches it.
+- `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.

package/docs/claude/skills/claude-docs-asset-wiring/knowledge/smoke-tests.md

@@ -0,0 +1,111 @@
+# E2E Smoke Tests — 8-path matrix via engine dispatcher
+
+**Run from `/tmp/...` — never from the monorepo root or `${TARGET_PATH}/`.**
+
+`--scope=project` walks `cwd` upward looking for an existing `.claude`
+directory. Running from the monorepo would reuse or mutate the real
+repo's `.claude`, which is a destructive error.
+
+No fake `node_modules` needed — the engine uses
+`createRequire(import.meta.url).resolve(`${PACKAGE_NAME}/package.json`)`
+from the engine's own installed location.
+
+---
+
+## Setup
+
+```bash
+BIN="$PWD/packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs"
+DIR=/tmp/inject-smoke-${SHORTCUT:-target}
+[ -d "$DIR" ] && find "$DIR" -mindepth 1 -delete
+mkdir -p "$DIR" && cd "$DIR"
+```
+
+`[ -d ... ] && find -delete` keeps the setup idempotent. **Never** use
+`rm -rf` or unquoted `*` globs — too easy to nuke the wrong directory.
+
+---
+
+## Matrix
+
+Execute sequentially. `EXIT=$?` after each so the value is captured
+before the next command overwrites `$?`.
+
+| #  | Command                                                                                          | Expected exit | Purpose                                                      |
+|----|--------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------------|
+|  1 | `node "$BIN" --package=${PACKAGE_NAME} --scope=project --dry-run`                                | 0             | Dry run — previews actions, no writes.                       |
+|  2 | `node "$BIN" --package=${PACKAGE_NAME} --scope=project`                                          | 0             | First real install — writes `.claude/` under `$DIR`.         |
+|  3 | `node "$BIN" --package=${PACKAGE_NAME} --scope=project`                                          | 0             | Re-run — no-op (idempotent).                                 |
+|  4 | (after tampering) `CI=true node "$BIN" --package=${PACKAGE_NAME} --scope=project`                | **2**         | CI + tampered content → refuse to overwrite.                 |
+|  5 | `CI=true node "$BIN" --package=${PACKAGE_NAME} --scope=project --force`                          | 0             | `--force` overrides the refusal.                             |
+|  6 | `CI=true node "$BIN" --package=${PACKAGE_NAME}`                                                  | **2**         | Missing `--scope` in non-TTY context.                        |
+|  7 | `node "$BIN"`                                                                                    | **2**         | Missing `--package` (dispatcher-specific).                   |
+|  8 | `node "$BIN" --package=@does/not-exist`                                                          | **2**         | Unresolvable package (dispatcher-specific).                  |
+
+### Tamper step (between path 3 and path 4)
+
+```bash
+find .claude -name SKILL.md -exec sh -c 'echo tampered >> "$1"' _ {} \;
+```
+
+Appends `tampered` to every `SKILL.md` under the local `.claude/`.
+Simulates a human edit that the CI-mode dispatcher must detect and
+refuse to clobber.
+
+---
+
+## Execution Shape
+
+Split into **two bash calls** because `cwd` resets between Bash tool
+invocations.
+
+**First call** — paths 1–3:
+
+```bash
+BIN="$PWD/packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs"
+DIR=/tmp/inject-smoke-${SHORTCUT:-target}
+[ -d "$DIR" ] && find "$DIR" -mindepth 1 -delete
+mkdir -p "$DIR" && cd "$DIR"
+
+node "$BIN" --package=${PACKAGE_NAME} --scope=project --dry-run; echo "EXIT=$?"
+node "$BIN" --package=${PACKAGE_NAME} --scope=project;           echo "EXIT=$?"
+node "$BIN" --package=${PACKAGE_NAME} --scope=project;           echo "EXIT=$?"
+```
+
+**Second call** — paths 4–8:
+
+```bash
+DIR=/tmp/inject-smoke-${SHORTCUT:-target}
+BIN="$PWD/packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs"
+cd "$DIR"
+
+find .claude -name SKILL.md -exec sh -c 'echo tampered >> "$1"' _ {} \;
+CI=true node "$BIN" --package=${PACKAGE_NAME} --scope=project;         echo "EXIT=$?"
+CI=true node "$BIN" --package=${PACKAGE_NAME} --scope=project --force; echo "EXIT=$?"
+CI=true node "$BIN" --package=${PACKAGE_NAME};                         echo "EXIT=$?"
+node "$BIN";                                                            echo "EXIT=$?"
+node "$BIN" --package=@does/not-exist;                                 echo "EXIT=$?"
+```
+
+Note: `$PWD` in the second call is the parent shell's cwd (monorepo
+root), so `BIN` resolves correctly. `cd "$DIR"` then moves into the
+smoke directory before invoking.
+
+---
+
+## Failure Handling
+
+| Observed | Meaning                                                                 | Action                                                             |
+|----------|-------------------------------------------------------------------------|--------------------------------------------------------------------|
+| 1 ≠ 0    | Dry-run crashed. Likely an engine bug or bad `claude.assetPath`.        | Stop, capture stderr, report.                                      |
+| 2 ≠ 0    | First write failed. Permissions, engine bug, or manifest issue.         | Stop, inspect `dist/claude-hashes.json`, report.                   |
+| 3 ≠ 0    | Idempotency broken — re-run should be no-op.                            | Stop, diff `$DIR/.claude` before/after, report.                    |
+| 4 = 0    | CI mode did not refuse tampered files. Safety regression.               | Stop — the engine's CI gate is broken.                             |
+| 5 ≠ 0    | `--force` failed to override. Check engine.                             | Stop, report.                                                      |
+| 6 = 0    | Engine defaulted a scope in non-TTY context. Should require `--scope`.  | Stop, report.                                                      |
+| 7 = 0    | Dispatcher accepted no `--package`. Violates contract.                  | Stop — dispatcher bug.                                             |
+| 8 = 0    | Dispatcher succeeded on unresolvable package. Violates contract.        | Stop — dispatcher bug.                                             |
+
+Do not attempt to "make the tests pass" by altering expectations. The
+matrix encodes invariants of the engine — a mismatch is a real
+regression upstream.