@slats/claude-assets-sync 0.3.0 → 0.3.1

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

@@ -4,7 +4,7 @@ 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
+with `${PACKAGE_NAME}` — four occurrences. Skip the entire step if
 `CLAUDE.md` does not exist (do not create one).
 
 The template is intentionally terse: CLI usage + essential isolation
@@ -18,17 +18,13 @@ do not duplicate it into every consumer's `CLAUDE.md`.
 ````markdown
 ## Claude Docs Injector
 
-`docs/claude/**` 자산을 사용자 `.claude/` 에 주입. 엔진: `@slats/claude-assets-sync` (bin: `inject-claude-settings`).
+`docs/claude/**` 자산을 사용자 `.claude/` 에 주입. 엔진: `@slats/claude-assets-sync` (bin: `inject-claude-settings`). 엔진은 `devDependencies` 에만 있으므로 항상 `npx -p @slats/claude-assets-sync ...` 로 호출합니다.
 
 ```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
@@ -44,17 +40,13 @@ npx inject-claude-settings --package=@canard/schema-form --scope=user
 ````markdown
 ## Claude Docs Injector
 
-Inject `docs/claude/**` into the user's `.claude/`. Engine: `@slats/claude-assets-sync` (bin: `inject-claude-settings`).
+Inject `docs/claude/**` into the user's `.claude/`. Engine: `@slats/claude-assets-sync` (bin: `inject-claude-settings`). The engine is declared only in `devDependencies`, so always invoke via `npx -p @slats/claude-assets-sync ...`.
 
 ```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
@@ -68,7 +60,7 @@ npx inject-claude-settings --package=@winglet/style-utils --scope=user
 ## Substitution Rules
 
 - Replace the sample package name in the chosen template with
-  `${PACKAGE_NAME}` — six occurrences.
+  `${PACKAGE_NAME}` — four occurrences.
 - Preserve the Isolation Guardrails bullets verbatim — these are
   the sharp invariants that must stay consistent across consumers.
 

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

@@ -27,22 +27,25 @@ 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/**`
+## `@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.
 
-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.
+Every consumer's CLAUDE.md documents the single `npx -p` path.
 
 ---
 

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

@@ -53,8 +53,9 @@ Point to the engine's bin (NOT a local stub):
 
 `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.
+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.
 
@@ -74,30 +75,34 @@ If the target already has a `prepublishOnly` that calls `yarn build`
 
 ---
 
-## 5. `dependencies."@slats/claude-assets-sync"`
+## 5. `devDependencies."@slats/claude-assets-sync"`
 
-**Must be in `dependencies`, never `devDependencies` or
+**Must be in `devDependencies`, never `dependencies` or
 `peerDependencies`.**
 
 ```json
-"dependencies": {
+"devDependencies": {
   "@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>`.
+- 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 `devDependencies` or
-`peerDependencies`, move it to `dependencies`. Do not duplicate.
+If the target already has it in `dependencies` or
+`peerDependencies`, move it to `devDependencies`. Do not duplicate.
 
 ---
 

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

@@ -24,10 +24,10 @@ Reference consumer: `packages/canard/schema-form`.
 ## 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.
+  `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

package/docs/consumer-integration.md

@@ -12,7 +12,7 @@ How to make a package ship Claude Code assets through the `inject-claude-setting
     "build": "… && yarn build:hashes",
     "build:hashes": "claude-build-hashes"
   },
-  "dependencies": {
+  "devDependencies": {
     "@slats/claude-assets-sync": "workspace:^"
   },
   "files": ["dist", "docs", "README.md"],
@@ -22,10 +22,10 @@ How to make a package ship Claude Code assets through the `inject-claude-setting
 }
 ```
 
-- `@slats/claude-assets-sync` MUST be in `dependencies`, not `devDependencies` or `peerDependencies`.
+- `@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/`) handles build-time hashing.
+- 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.
 
 ## 2. `docs/claude/` authoring
 
@@ -65,12 +65,13 @@ The legacy `src-no-bin` and `src-no-claude-assets-sync` rules are no longer load
 
 ## 4. End-user invocations
 
-| Install topology | Invocation |
+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 |
 |---|---|
-| End user installs consumer as a **direct dep** on npm / yarn-classic | `npx inject-claude-settings --package=@your-scope/your-package --scope=user` |
-| End user installs consumer as a **direct dep** on pnpm strict / yarn-berry PnP | `npx -p @slats/claude-assets-sync inject-claude-settings --package=@your-scope/your-package --scope=user` |
-| End user has **no consumer installed** yet | `npx -p @slats/claude-assets-sync inject-claude-settings --package=@your-scope/your-package --scope=user` (resolves to whatever is on the registry under that exact name) |
-| End user has **multiple consumers installed** | Call `inject-claude-settings --package=<one-name>` per target. There is no `--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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slats/claude-assets-sync",
-  "version": "0.3.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,14 +27,12 @@
     ".": {
       "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": {
@@ -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 [];
+}