@slats/claude-assets-sync 0.2.0 → 0.3.0

package/docs/claude/skills/claude-sync-applier/knowledge/gotchas.md

@@ -1,139 +0,0 @@
-# Invariants and Gotchas
-
-Hard-earned rules. Each one reflects a previous incident or a design
-constraint of the `@slats/claude-assets-sync` engine.
-
----
-
-## Stubs are verbatim
-
-The `bin/claude-sync.mjs` and `scripts/build-hashes.mjs` files are
-**identical across all consumers** in this monorepo. No per-package
-substitution. Runtime `import.meta.url` (in the bin) and `process.cwd()` (in
-the build script) discover the package root; package metadata is parsed from
-the adjacent `package.json`.
-
-If you find yourself "adapting" the stub for a new consumer, stop — that's a
-sign you misread the design. The engine is generic; the consumer-specific
-convention is the `claude.assetPath` field inside `package.json`.
-
----
-
-## Silent no-op on missing `claude.assetPath`
-
-Both stubs guard with `if (typeof pkg.claude?.assetPath === 'string')`.
-
-- Missing field → exit 0, produce no output.
-- Non-string value → exit 0, produce no output.
-
-This is the intentional opt-out path: a package can ship the bin and script
-but disable the feature by removing the config field. Do not add "helpful"
-error messages for this case — it would break the opt-out.
-
----
-
-## `@slats/claude-assets-sync` must be in `dependencies`
-
-**Not** `devDependencies`, **not** `peerDependencies`.
-
-Isolation from the library bundle is enforced by:
-
-1. The import graph (`src/**` never references the engine), and
-2. Optionally, dependency-cruiser static rules.
-
-It is **not** enforced by dependency-type. Placing the engine in
-`devDependencies` would break `npx <pkg> claude-sync` when a downstream
-consumer installs the package — their `npm install` omits dev deps.
-
----
-
-## Never add `./bin/*` to `exports`
-
-The `exports` map in `package.json` controls which subpaths a consumer's
-bundler can resolve. Leaving `./bin/*` out of `exports` is what prevents a
-bundler from deep-importing the CLI by accident.
-
-Adding `./bin/claude-sync.mjs` to `exports` — even with `"default"` —
-creates a path for a careless `import "@canard/schema-form/bin/claude-sync"`
-to pull the CLI engine (and `@slats/claude-assets-sync`) into the library
-consumer's production bundle. Three-layer isolation collapses to zero.
-
----
-
-## 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`).
-
-If no shortcut exists, the full form `yarn workspace ${PACKAGE_NAME} build`
-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.
-
----
-
-## Bin paths are orphans on purpose
-
-`bin/claude-sync.mjs` is an executable entry point. It is never imported from
-`src/`. That makes it an orphan in dependency-cruiser's eyes.
-
-Step 4 explicitly excludes `^bin/` from the `no-orphans` rule to silence this
-warning. If you add new bin entry points, extend the `pathNot` pattern — do
-not disable the rule wholesale.
-
----
-
-## Three-layer isolation — why
-
-1. **Import graph** — `src/**` never references `bin/**`, `docs/**`, or
-   `@slats/claude-assets-sync`. Primary defense.
-2. **`sideEffects: false`** — allows the bundler to tree-shake any accidental
-   reference.
-3. **No `./bin/*` in `exports`** — consumer bundlers cannot reach the bin
-   through subpath imports.
-4. **(Optional) dependency-cruiser** — CI-time regression check that layer 1
-   stays intact.
-
-Step 8 (`grep` on `dist/index.{mjs,cjs}`) is the post-build verification that
-all three primary layers held. Any match → one of them is broken.
-
----
-
-## Commit this change alone
-
-The change set from this skill touches `bin/`, `scripts/`, `package.json`,
-and possibly `CLAUDE.md` + `.dependency-cruiser.cjs`. 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, bundle grep) is bound to the state of these
-  files and nothing else.
-- The change is almost entirely mechanical — 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 10 report.

package/docs/claude/skills/claude-sync-applier/knowledge/package-json-patches.md

@@ -1,130 +0,0 @@
-# `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. `bin`
-
-```json
-"bin": {
-  "claude-sync": "./bin/claude-sync.mjs"
-}
-```
-
-If `bin` already exists with other entries, merge in the `claude-sync` key;
-preserve siblings. If `bin.claude-sync` already points elsewhere, ask.
-
----
-
-## 2. `files`
-
-Append `"bin"` to the `files` array if not already present. Order within the
-array is not load-bearing, but to match the reference:
-
-```json
-"files": [
-  "dist",
-  "docs",
-  "bin",
-  "README.md"
-]
-```
-
-If `files` is absent, create it with at least `["dist", "bin"]`, preserving
-any conventions already present in sibling packages.
-
----
-
-## 3. `scripts.build`
-
-Append ` && yarn build:hashes` to whatever the package currently has.
-
-**Guard against double-append.** If the existing value already ends with
-`yarn build:hashes` or already contains `build:hashes`, leave it alone.
-
-Reference value:
-
-```json
-"build": "rollup -c && yarn build:types && yarn build:hashes"
-```
-
----
-
-## 4. `scripts.build:hashes`
-
-```json
-"build:hashes": "node scripts/build-hashes.mjs"
-```
-
-If a different `build:hashes` script exists, ask.
-
----
-
-## 5. `scripts.prepublishOnly`
-
-```json
-"prepublishOnly": "yarn build"
-```
-
-If the target already has a `prepublishOnly` that calls `yarn build`
-(directly or transitively), leave it alone.
-
----
-
-## 6. `dependencies."@slats/claude-assets-sync"`
-
-**Must be in `dependencies`, never `devDependencies`.**
-
-```json
-"dependencies": {
-  "@slats/claude-assets-sync": "workspace:^"
-}
-```
-
-Rationale: isolation from the library bundle is enforced by the import graph
-(and optionally by dependency-cruiser), not by dependency-type. Placing it in
-`devDependencies` would make `npm install` on a published package fail when a
-consumer runs `npx <pkg> claude-sync`.
-
-If the target already has it in `devDependencies`, move it. Do not duplicate.
-
----
-
-## 7. `claude.assetPath`
-
-Default value (used when the field is absent):
-
-```json
-"claude": {
-  "assetPath": "docs/claude"
-}
-```
-
-**If `claude.assetPath` already exists with a non-default value, preserve it.**
-The convention lives in the consumer, not the library.
-
-The bin stub guards on `typeof pkg.claude?.assetPath === 'string'` — a missing
-or non-string value is a silent no-op. That is the intentional opt-out path.
-
----
-
-## Must-NOT
-
-- **Never** add `./bin/*` (or any bin path) to the `exports` field. Leaving bin
-  subpaths unexported is what prevents a consumer bundler from accidentally
-  reaching into the CLI assets via deep imports.
-
----
-
-## Full Reference
-
-See `packages/canard/schema-form/package.json` for the canonical shape. The
-relevant keys are `bin`, `files`, `scripts.build`, `scripts.build:hashes`,
-`scripts.prepublishOnly`, `dependencies."@slats/claude-assets-sync"`, and
-`claude.assetPath`. Everything else in that file is schema-form-specific and
-must not be copied.

package/docs/claude/skills/claude-sync-applier/knowledge/reference-files.md

@@ -1,120 +0,0 @@
-# Reference Files
-
-The two stub files are **identical across all consumers**. Copy verbatim, do
-no substitution — the stubs discover package metadata at runtime via
-`import.meta.url`.
-
-Reference consumer: `packages/canard/schema-form`.
-
----
-
-## `bin/claude-sync.mjs`
-
-Source of truth: `packages/canard/schema-form/bin/claude-sync.mjs`.
-
-Expected content (must match exactly):
-
-```js
-#!/usr/bin/env node
-import { runCli } from '@slats/claude-assets-sync';
-import { readFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const pkg = JSON.parse(
-  await readFile(resolve(packageRoot, 'package.json'), 'utf-8'),
-);
-
-if (typeof pkg.claude?.assetPath === 'string') {
-  runCli(process.argv, {
-    packageRoot,
-    packageName: pkg.name,
-    packageVersion: pkg.version,
-    assetPath: pkg.claude.assetPath,
-  }).catch((err) => {
-    process.stderr.write(
-      `[${pkg.name}] claude-sync failed: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    process.exit(1);
-  });
-}
-```
-
-**Notes**
-
-- `import.meta.url` is resolved at runtime to the installed file path, so
-  `packageRoot` works both during local development and when consumed as a
-  dependency.
-- `pkg.claude?.assetPath` missing → the stub is a silent no-op. That is the
-  feature that lets a package opt out without shipping broken bins.
-- Emit to stderr on failure and exit 1. Do not `throw` — the CLI is the
-  process boundary.
-
-After writing, make it executable:
-
-```bash
-chmod +x ${TARGET_PATH}/bin/claude-sync.mjs
-```
-
----
-
-## `scripts/build-hashes.mjs`
-
-Source of truth: `packages/canard/schema-form/scripts/build-hashes.mjs`.
-
-Expected content (must match exactly):
-
-```js
-#!/usr/bin/env node
-// Thin wrapper — parses this package's package.json and delegates to
-// @slats/claude-assets-sync/buildHashes. The `claude.assetPath` convention
-// lives here, in the consumer; the library is generic.
-import { buildHashes } from '@slats/claude-assets-sync/buildHashes';
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-
-const packageRoot = process.cwd();
-const pkg = JSON.parse(
-  await readFile(resolve(packageRoot, 'package.json'), 'utf-8'),
-);
-
-if (typeof pkg.claude?.assetPath === 'string') {
-  try {
-    const { outPath, fileCount } = await buildHashes({
-      packageRoot,
-      packageName: pkg.name,
-      packageVersion: pkg.version,
-      assetPath: pkg.claude.assetPath,
-    });
-    console.log(
-      `✓ claude-hashes.json written: ${fileCount} file(s) → ${outPath}`,
-    );
-  } catch (err) {
-    console.error('❌ build-hashes failed:', err?.message ?? err);
-    process.exit(1);
-  }
-}
-```
-
-**Notes**
-
-- `packageRoot = process.cwd()` intentionally — this script runs via
-  `yarn <shortcut> build:hashes` from the package directory.
-- Same no-op behavior when `claude.assetPath` is missing.
-- Emits to stdout on success (humans read it during the build).
-
-No `chmod +x` needed — it's invoked via `node scripts/build-hashes.mjs`.
-
----
-
-## Verification
-
-Before declaring Step 1/Step 2 complete, diff against the reference:
-
-```bash
-diff packages/canard/schema-form/bin/claude-sync.mjs ${TARGET_PATH}/bin/claude-sync.mjs
-diff packages/canard/schema-form/scripts/build-hashes.mjs ${TARGET_PATH}/scripts/build-hashes.mjs
-```
-
-Both diffs must be empty.

package/docs/claude/skills/claude-sync-applier/knowledge/smoke-tests.md

@@ -1,102 +0,0 @@
-# E2E Smoke Tests — 6-path matrix
-
-**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 bin resolves everything via
-`import.meta.url`.
-
----
-
-## Setup
-
-```bash
-BIN=$PWD/${TARGET_PATH}/bin/claude-sync.mjs
-DIR=/tmp/claude-sync-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" --scope=project --dry-run`                                     | 0             | Dry run on empty dir — previews actions, no writes.      |
-| 2 | `node "$BIN" --scope=project`                                               | 0             | First real install — writes `.claude/` under `$DIR`.     |
-| 3 | `node "$BIN" --scope=project`                                               | 0             | Re-run — no-op because everything is already up-to-date. |
-| 4 | (after tampering) `CI=true node "$BIN" --scope=project`                     | **2**         | CI + tampered content → refuse to overwrite.             |
-| 5 | `CI=true node "$BIN" --scope=project --force`                               | 0             | `--force` overrides the refusal.                         |
-| 6 | `CI=true node "$BIN"`                                                       | **2**         | Missing `--scope` in non-TTY context → exit 2.           |
-
-### 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/`. This
-simulates a human edit that the CI-mode bin 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/${TARGET_PATH}/bin/claude-sync.mjs
-DIR=/tmp/claude-sync-smoke-${SHORTCUT:-target}
-[ -d "$DIR" ] && find "$DIR" -mindepth 1 -delete
-mkdir -p "$DIR" && cd "$DIR"
-
-node "$BIN" --scope=project --dry-run; echo "EXIT=$?"   # expect 0
-node "$BIN" --scope=project;           echo "EXIT=$?"   # expect 0
-node "$BIN" --scope=project;           echo "EXIT=$?"   # expect 0
-```
-
-**Second call** — paths 4–6 (re-enter `$DIR`, reuse state from first call):
-
-```bash
-DIR=/tmp/claude-sync-smoke-${SHORTCUT:-target}
-BIN=$PWD/${TARGET_PATH}/bin/claude-sync.mjs
-cd "$DIR"
-
-find .claude -name SKILL.md -exec sh -c 'echo tampered >> "$1"' _ {} \;
-CI=true node "$BIN" --scope=project;         echo "EXIT=$?"   # expect 2
-CI=true node "$BIN" --scope=project --force; echo "EXIT=$?"   # expect 0
-CI=true node "$BIN";                         echo "EXIT=$?"   # expect 2
-```
-
-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 a stub or engine bug.                           | Stop, capture stderr, report.                                      |
-| 2 ≠ 0    | First write failed. Likely 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.                                                      |
-
-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.