@slats/claude-assets-sync 0.2.0 → 0.3.1

package/docs/consumer-integration.md

@@ -1,6 +1,6 @@
 # Consumer Integration Template
 
-How to make a package "claude-sync aware" so `claude-sync` discovers and injects its `docs/claude/` tree into end-user `.claude` directories.
+How to make a package ship Claude Code assets through the `inject-claude-settings` dispatcher. Two fields in `package.json`; no stub code.
 
 ## 1. `package.json` additions
 
@@ -8,146 +8,88 @@ How to make a package "claude-sync aware" so `claude-sync` discovers and injects
 {
   "name": "@your-scope/your-package",
   "version": "…",
-  "bin": {
-    "claude-sync": "./bin/claude-sync.mjs"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "dist/claude-hashes.json",
-    "bin",
-    "README.md"
-  ],
   "scripts": {
     "build": "… && yarn build:hashes",
-    "build:hashes": "node scripts/build-hashes.mjs"
+    "build:hashes": "claude-build-hashes"
   },
-  "dependencies": {
-    "@slats/claude-assets-sync": "workspace:^",
+  "devDependencies": {
+    "@slats/claude-assets-sync": "workspace:^"
   },
+  "files": ["dist", "docs", "README.md"],
   "claude": {
     "assetPath": "docs/claude"
   }
 }
 ```
 
-Do **not** expose `./bin/*` in `exports`. That would let consumer bundlers accidentally pull CLI code into app bundles.
-
-## 2. `bin/claude-sync.mjs` (3-line re-export stub)
-
-```javascript
-#!/usr/bin/env node
-import { runCli } from '@slats/claude-assets-sync';
-
-runCli(process.argv, { invokedFromBin: import.meta.url }).catch((err) => {
-  process.stderr.write(
-    `[@your-scope/your-package] claude-sync failed: ${err instanceof Error ? err.message : String(err)}\n`,
-  );
-  process.exit(1);
-});
-```
-
-`runCli` determines the implicit `--package` target in this priority order:
+- `@slats/claude-assets-sync` MUST be in `devDependencies`. The engine is a CLI-only tool; 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.
+- Do **not** add any `bin` field. Bin names collide across consumers under `node_modules/.bin/` and the engine is the sole CLI surface.
+- Do **not** expose `./bin/*` or `./docs/*` in `exports`. Exposing them would let bundlers pull CLI code or the docs tree into app bundles.
+- Do **not** create a `bin/` or `scripts/` directory in the consumer. The engine's `claude-build-hashes` bin (resolved via `node_modules/.bin/` from `devDependencies` at workspace install time) handles build-time hashing.
 
-1. `--all` or `--package=<name>` (explicit)
-2. The consumer that owns `process.cwd()` (i.e. the terminal you launched from). When you `cd` into a consumer's package directory and run `yarn claude-sync`, that consumer is picked automatically.
-3. The consumer that owns `invokedFromBin` (fallback). This keeps bare `npx <pkg> claude-sync` working from arbitrary cwds — including from inside another consumer's directory where option 2 would have picked a different package.
-4. The sole discovered consumer, if exactly one exists.
-5. Otherwise an error asking for `--package=<name>` or `--all`.
+## 2. `docs/claude/` authoring
 
-Passing `invokedFromBin: import.meta.url` remains the mechanism for the fallback case. Omit it in slats's own global bin so it behaves as a cross-consumer dispatcher.
-
-Remember `chmod +x bin/claude-sync.mjs` (or rely on `files` entry to ship executable bit via npm).
-
-## 3. `scripts/build-hashes.mjs` (one line import)
+Any file tree works, but the recommended layout is:
 
-```javascript
-#!/usr/bin/env node
-import { buildHashes } from '@slats/claude-assets-sync/buildHashes';
-
-try {
-  const { outPath, fileCount } = await buildHashes();
-  console.log(`✓ claude-hashes.json written: ${fileCount} file(s) → ${outPath}`);
-} catch (err) {
-  console.error('❌ buildHashes failed:', err?.message ?? err);
-  process.exit(1);
-}
+```
+docs/claude/
+├── skills/
+│   └── <skill-name>/
+│       ├── SKILL.md
+│       └── knowledge/...
+├── rules/...
+└── commands/...
 ```
 
-This reads the current `package.json` + its `claude.assetPath`, hashes every file under the asset root (ignoring `.omc/**`, `*.log`, `.DS_Store`), and writes `dist/claude-hashes.json`.
+The build step (`yarn build:hashes` → `claude-build-hashes`) hashes every file under `docs/claude/` relative to the asset root and writes `dist/claude-hashes.json`. On inject, the CLI copies `skills`/`rules`/`commands` into the matching subtree under `.claude/`.
 
-## 4. Isolation guardrails (optional but recommended)
+## 3. Isolation guardrails (optional but recommended)
 
 In a `.dependency-cruiser.cjs`:
 
 ```javascript
-{
-  name: 'src-no-bin',
-  severity: 'error',
-  from: { path: '^src/' },
-  to: { path: '^bin/' },
-},
 {
   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/' },
 },
-{
-  name: 'src-no-claude-assets-sync',
-  severity: 'error',
-  from: { path: '^src/' },
-  to: { path: 'node_modules/@slats/claude-assets-sync' },
-},
 ```
 
-Plus `"sideEffects": false` in `package.json`. The guardrails ensure the CLI engine never leaks into consumer runtime bundles.
+Plus `"sideEffects": false` in `package.json`. These ensure the docs tree never leaks into consumer runtime bundles.
+
+The legacy `src-no-bin` and `src-no-claude-assets-sync` rules are no longer load-bearing — the consumer owns no `bin/`, and the engine isn't referenced from `src/` anyway. Do not reintroduce them.
 
-## 5. End-user invocations
+## 4. End-user invocations
 
-| Install topology | Working invocations |
+The engine is not shipped as a runtime dependency of any consumer, so end users never get a hoisted `inject-claude-settings` bin. Always invoke via `npx -p @slats/claude-assets-sync ...`; the package manager fetches and caches the engine on demand.
+
+| Scenario | Invocation |
 |---|---|
-| Consumer is a **direct dep** of the user's project | `npx claude-sync --scope=user` *(bare)* |
-| Always works (preferred in docs) | `npx -p @your-scope/your-package claude-sync --scope=user` |
-| Consumer is a **transitive dep** | `npx -p @your-scope/your-package claude-sync --scope=user` |
-| User has no consumer installed | `npx @slats/claude-assets-sync --package=@your-scope/your-package --scope=user` |
-| Multiple consumers discovered | `npx claude-sync --package=@your-scope/your-package` *or* `npx claude-sync --all` |
+| Single consumer target | `npx -p @slats/claude-assets-sync inject-claude-settings --package=@your-scope/your-package --scope=user` |
+| All packages under one npm scope | `npx -p @slats/claude-assets-sync inject-claude-settings --package=@your-scope --scope=user` (scope alias — no slash) |
+| Multiple specific targets | Repeat `--package` or comma-separate: `--package=@scope-a --package=@scope-b/pkg`. There is no `--all`. |
 
 ### Scope resolution (project)
 
-For `--scope=project`, the target `.claude` directory is resolved by walking up from `process.cwd()` and reusing the first existing `.claude` directory found. Only if no ancestor owns a `.claude` does the CLI fall back to `process.cwd()/.claude`.
+For `--scope=project`, the target `.claude` directory is resolved by walking up from `process.cwd()` and reusing the first existing `.claude` directory found. Only if no ancestor owns a `.claude` does the CLI fall back to `process.cwd()/.claude`. The CLI logs `(auto-located)` when this happens.
 
 ```
 workspace/
-  .claude/                            ← reused target (auto-located)
+  .claude/                        ← reused target (auto-located)
   packages/
-    @your-scope/your-package/         ← cd here and run claude-sync
-      bin/claude-sync.mjs
-```
-
-Running `yarn claude-sync --scope=project` from `packages/@your-scope/your-package/` injects into `workspace/.claude`, not `packages/@your-scope/your-package/.claude`. The CLI logs `(auto-located)` in its resolution line when this happens.
-
-## 6. Authoring `docs/claude/`
-
-Any file tree works, but the recommended layout is:
-
-```
-docs/claude/
-├── skills/
-│   └── <skill-name>/
-│       ├── SKILL.md
-│       └── knowledge/...
-├── rules/...
-└── commands/...
+    @your-scope/your-package/     ← cd here and run inject-claude-settings
 ```
 
-The hash manifest tracks every file under `docs/claude/` relative to the asset root. On inject, the CLI copies skills/rules/commands into the matching subtree under `.claude/`.
+Running `inject-claude-settings --package=@your-scope/your-package --scope=project` from `packages/@your-scope/your-package/` injects into `workspace/.claude`, not `packages/@your-scope/your-package/.claude`.
 
-## 7. Verification checklist
+## 5. Verification checklist
 
 - [ ] `yarn build` succeeds and emits `dist/claude-hashes.json` alongside the rest of `dist/`.
-- [ ] `node bin/claude-sync.mjs --help` prints the `claude-sync` subcommand tree.
-- [ ] `node bin/claude-sync.mjs list --json` emits an entry for your package with `hashesPresent: true`.
-- [ ] `node bin/claude-sync.mjs --scope=project --dry-run --package=@your-scope/your-package` emits a copy plan.
-- [ ] `yarn depcheck` (or whatever your dep-cruiser invocation is named) reports zero new violations.
-- [ ] Consumer bundler tree-shakes away CLI code (verify by greping the built bundle: should contain zero references to `@slats/claude-assets-sync`).
+- [ ] `node packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs --help` prints the dispatcher usage.
+- [ ] `node packages/slats/claude-assets-sync/bin/inject-claude-settings.mjs --package=@your-scope/your-package --scope=project --dry-run` emits a copy plan when run from `/tmp/...`.
+- [ ] If you enabled Section 3's depcheck, `yarn depcheck` reports zero violations.
+- [ ] Consumer bundler tree-shakes away docs — grep the built bundle for `@slats/claude-assets-sync`, `inject-claude-settings`, and `docs/claude`; all three should be absent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slats/claude-assets-sync",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Shared CLI engine that lets consumer packages inject their Claude docs (skills, rules, commands) into a user's .claude directory via a thin bin/inject-docs wrapper.",
   "keywords": [
     "claude",
@@ -27,19 +27,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "source": "./src/index.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.mjs"
     },
     "./buildHashes": {
       "import": "./scripts/buildHashes.mjs"
     }
   },
-  "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "bin": {
     "claude-build-hashes": "./scripts/claude-build-hashes.mjs",
-    "claude-sync": "./bin/claude-sync.mjs"
+    "inject-claude-settings": "./bin/inject-claude-settings.mjs"
   },
   "files": [
     "dist",
@@ -54,6 +52,8 @@
     "build:publish:npm": "yarn build && yarn publish:npm",
     "build:types": "node ../../aileron/script/build/buildTypes.mjs",
     "dev": "node scripts/inject-version.js && tsx src/main.ts",
+    "dev:ui": "tsx scripts/dev-ui.tsx",
+    "dev:cli": "tsx bin/inject-claude-settings.mjs",
     "format": "prettier --write \"src/**/*.ts\"",
     "lint": "eslint \"src/**/*.ts\"",
     "prepublishOnly": "yarn build",
@@ -64,12 +64,17 @@
     "version:patch": "yarn version patch"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.4.2",
     "commander": "^12.1.0",
-    "picocolors": "^1.1.1"
+    "ink": "^7.0.0",
+    "ink-gradient": "^4.0.0",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "picocolors": "^1.1.1",
+    "react": "^19.2.0"
   },
   "devDependencies": {
-    "@inquirer/testing": "^3.3.5"
+    "@types/react": "^19.2.0",
+    "ink-testing-library": "^4.0.0"
   },
   "claude": {
     "assetPath": "docs/claude"

package/scripts/dev-ui-fixtures.ts

@@ -0,0 +1,288 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import type { ConsumerPackage } from '../src/commands/runCli/type.js';
+import type { InjectPlan, Action } from '../src/core/buildPlan/index.js';
+import type { InjectReport, ScopeResolution } from '../src/core/index.js';
+import type {
+  ApplyProgress,
+  InjectEvent,
+  Phase,
+  PlanStepState,
+  TargetPlan,
+  Warning,
+} from '../src/ui/types/index.js';
+
+export const PHASES = [
+  'resolving',
+  'scope-select',
+  'planning',
+  'diff-review',
+  'force-confirm',
+  'applying',
+  'summary',
+  'summary-dry',
+  'error',
+] as const;
+
+export type PhaseKey = (typeof PHASES)[number];
+
+const MOCK_TARGETS: ConsumerPackage[] = [
+  {
+    name: '@canard/schema-form',
+    version: '0.12.1',
+    packageRoot: '/workspace/packages/canard/schema-form',
+    assetRoot: '/workspace/packages/canard/schema-form/docs/claude',
+    hashesPresent: true,
+  },
+  {
+    name: '@canard/schema-form-antd-plugin',
+    version: '0.12.1',
+    packageRoot: '/workspace/packages/canard/schema-form-antd-plugin',
+    assetRoot: '/workspace/packages/canard/schema-form-antd-plugin/docs/claude',
+    hashesPresent: true,
+  },
+  {
+    name: '@winglet/common-utils',
+    version: '0.12.1',
+    packageRoot: '/workspace/packages/winglet/common-utils',
+    assetRoot: '/workspace/packages/winglet/common-utils/docs/claude',
+    hashesPresent: true,
+  },
+];
+
+const scopeFixture: ScopeResolution = {
+  scope: 'user',
+  targetRoot: join(homedir(), '.claude'),
+  description: '~/.claude (user)',
+};
+
+function makeActions(
+  baseDstRoot: string,
+  options: {
+    copy?: number;
+    skip?: number;
+    diverged?: number;
+    orphan?: number;
+    del?: number;
+  },
+): Action[] {
+  const actions: Action[] = [];
+  let fileIdx = 0;
+  for (let i = 0; i < (options.copy ?? 0); i += 1) {
+    fileIdx += 1;
+    actions.push({
+      kind: 'copy',
+      relPath: `skills/expert/doc-${fileIdx}.md`,
+      dstAbs: `${baseDstRoot}/skills/expert/doc-${fileIdx}.md`,
+    });
+  }
+  for (let i = 0; i < (options.skip ?? 0); i += 1) {
+    fileIdx += 1;
+    actions.push({
+      kind: 'skip-uptodate',
+      relPath: `skills/expert/existing-${fileIdx}.md`,
+      dstAbs: `${baseDstRoot}/skills/expert/existing-${fileIdx}.md`,
+    });
+  }
+  for (let i = 0; i < (options.diverged ?? 0); i += 1) {
+    fileIdx += 1;
+    actions.push({
+      kind: 'warn-diverged',
+      relPath: `skills/expert/edited-${fileIdx}.md`,
+      dstAbs: `${baseDstRoot}/skills/expert/edited-${fileIdx}.md`,
+    });
+  }
+  for (let i = 0; i < (options.orphan ?? 0); i += 1) {
+    fileIdx += 1;
+    actions.push({
+      kind: 'warn-orphan',
+      relPath: `skills/expert/ghost-${fileIdx}.md`,
+      dstAbs: `${baseDstRoot}/skills/expert/ghost-${fileIdx}.md`,
+    });
+  }
+  for (let i = 0; i < (options.del ?? 0); i += 1) {
+    fileIdx += 1;
+    actions.push({
+      kind: 'delete',
+      relPath: `skills/expert/stale-${fileIdx}.md`,
+      dstAbs: `${baseDstRoot}/skills/expert/stale-${fileIdx}.md`,
+    });
+  }
+  return actions;
+}
+
+function makeTargetPlan(
+  target: ConsumerPackage,
+  actions: Action[],
+  requiresForce = false,
+): TargetPlan {
+  const plan: InjectPlan = { actions, requiresForce };
+  return { target, scope: scopeFixture, plan };
+}
+
+const TP_CLEAN = makeTargetPlan(
+  MOCK_TARGETS[0],
+  makeActions(scopeFixture.targetRoot, { copy: 4, skip: 2 }),
+  false,
+);
+
+const TP_WARN = makeTargetPlan(
+  MOCK_TARGETS[1],
+  makeActions(scopeFixture.targetRoot, {
+    copy: 2,
+    skip: 1,
+    diverged: 1,
+    orphan: 1,
+  }),
+  true,
+);
+
+const TP_THIRD = makeTargetPlan(
+  MOCK_TARGETS[2],
+  makeActions(scopeFixture.targetRoot, { copy: 3, skip: 5 }),
+  false,
+);
+
+const PLAN_SET: readonly TargetPlan[] = [TP_CLEAN, TP_WARN, TP_THIRD];
+
+const MOCK_WARNINGS: Warning[] = [
+  {
+    packageName: MOCK_TARGETS[1].name,
+    kind: 'warn-diverged',
+    relPath: 'skills/expert/edited-4.md',
+    description: 'local differs from source',
+  },
+  {
+    packageName: MOCK_TARGETS[1].name,
+    kind: 'warn-orphan',
+    relPath: 'skills/expert/ghost-5.md',
+    description: 'exists locally but not in manifest',
+  },
+];
+
+const MOCK_REPORTS: InjectReport[] = PLAN_SET.map((tp) => {
+  const report: InjectReport = {
+    created: [],
+    updated: [],
+    skipped: [],
+    warnings: [],
+    deleted: [],
+    exitCode: 0,
+  };
+  for (const action of tp.plan.actions) {
+    if (action.kind === 'copy') report.created.push(action.relPath);
+    else if (action.kind === 'skip-uptodate') report.skipped.push(action.relPath);
+    else if (action.kind === 'warn-diverged')
+      report.warnings.push({ relPath: action.relPath, reason: 'diverged' });
+    else if (action.kind === 'warn-orphan')
+      report.warnings.push({ relPath: action.relPath, reason: 'orphan' });
+    else if (action.kind === 'delete') report.deleted.push(action.relPath);
+  }
+  return report;
+});
+
+const MOCK_APPLY_PROGRESS: ApplyProgress = {
+  total: 18,
+  done: 7,
+  current: 'skills/expert/doc-8.md',
+  startedAt: Date.now() - 2500,
+};
+
+function makePlanningProgress(): ReadonlyMap<string, PlanStepState> {
+  return new Map([
+    [
+      MOCK_TARGETS[0].name,
+      { packageName: MOCK_TARGETS[0].name, status: 'done' },
+    ],
+    [
+      MOCK_TARGETS[1].name,
+      { packageName: MOCK_TARGETS[1].name, status: 'running' },
+    ],
+    [
+      MOCK_TARGETS[2].name,
+      { packageName: MOCK_TARGETS[2].name, status: 'pending' },
+    ],
+  ]);
+}
+
+export function buildPhase(kind: PhaseKey): Phase {
+  switch (kind) {
+    case 'resolving':
+      return { kind: 'resolving', targets: MOCK_TARGETS };
+    case 'scope-select':
+      return {
+        kind: 'scope-select',
+        targets: MOCK_TARGETS,
+        pending: () => {
+          /* noop */
+        },
+      };
+    case 'planning':
+      return {
+        kind: 'planning',
+        targets: MOCK_TARGETS,
+        scope: 'user',
+        progress: makePlanningProgress(),
+      };
+    case 'diff-review':
+      return {
+        kind: 'diff-review',
+        plans: PLAN_SET,
+        focusedIndex: 0,
+        scope: 'user',
+      };
+    case 'force-confirm':
+      return {
+        kind: 'force-confirm',
+        plans: PLAN_SET,
+        warnings: MOCK_WARNINGS,
+        pending: () => {
+          /* noop */
+        },
+        scope: 'user',
+      };
+    case 'applying':
+      return {
+        kind: 'applying',
+        plans: PLAN_SET,
+        progress: MOCK_APPLY_PROGRESS,
+        scope: 'user',
+      };
+    case 'summary':
+      return {
+        kind: 'summary',
+        reports: MOCK_REPORTS,
+        plans: PLAN_SET,
+        exitCode: 0,
+        scope: 'user',
+        dryRun: false,
+      };
+    case 'summary-dry':
+      return {
+        kind: 'summary',
+        reports: MOCK_REPORTS,
+        plans: PLAN_SET,
+        exitCode: 0,
+        scope: 'user',
+        dryRun: true,
+      };
+    case 'error':
+      return {
+        kind: 'error',
+        error: new Error(
+          'Sample fatal: dist/claude-hashes.json missing at /workspace/packages/canard/schema-form',
+        ),
+      };
+    default: {
+      const _exhaustive: never = kind;
+      void _exhaustive;
+      throw new Error('unknown phase');
+    }
+  }
+}
+
+export function fixtureEvents(kind: PhaseKey): InjectEvent[] {
+  void kind;
+  return [];
+}