@slats/claude-assets-sync 0.2.0 → 0.3.1

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.