@slats/claude-assets-sync 0.2.0 → 0.3.1

package/README.md

@@ -1,10 +1,12 @@
 # @slats/claude-assets-sync
 
-Shared CLI engine that lets any npm package ship its own Claude Code docs (skills, rules, commands) and inject them into a user's `.claude/` directory through a thin `claude-sync` bin stub.
+Engine + dispatcher CLI that lets any npm package ship its own Claude Code docs (skills, rules, commands) and inject them into a user's `.claude/` directory. Consumers declare `claude.assetPath` in `package.json` and the engine's `inject-claude-settings` bin handles the rest.
 
 ## Overview
 
-A consumer package ships a thin `bin/claude-sync.mjs` stub that reads its own `package.json` and calls `runCli(argv, { packageRoot, packageName, packageVersion, assetPath })`. End users run `npx claude-sync` (or the consumer's own bin alias) and this engine compares a per-file SHA-256 manifest against the target `.claude/`, copying only what is out of date. The library operates on exactly one consumer per invocation — the one supplied by the caller; it never walks `node_modules` or yarn workspaces.
+A consumer package declares `claude.assetPath` in `package.json` and runs `claude-build-hashes` during build to emit `dist/claude-hashes.json`. End users run `npx -p @slats/claude-assets-sync inject-claude-settings --package=<name>` and this engine resolves that single package's metadata via `createRequire`, compares the hash manifest against the target `.claude/`, and copies only what is out of date.
+
+The library operates on exactly one consumer per invocation — the one named in `--package`. It never walks `node_modules` for siblings; it never enumerates workspaces.
 
 No GitHub fetch, no `.sync-meta.json`, no migrations — the consumer's `dist/claude-hashes.json` is the single source of truth.
 
@@ -19,96 +21,72 @@ yarn add -D @slats/claude-assets-sync
 ## CLI Surface
 
 ```
-claude-sync [--scope=user|project] [--dry-run] [--force]
+inject-claude-settings --package=<name> [--scope=user|project] [--dry-run] [--force] [--root=<cwd>]
+claude-build-hashes
 ```
 
-Each consumer package exposes its own `claude-sync` bin entry (see [Consumer Integration](#consumer-integration-3-steps) below). When invoked, the engine operates on exactly one consumer — the one whose metadata was passed by the stub. There is no cross-package discovery.
+### End-user invocation
+
+The engine is not shipped as a runtime dependency of consumers. Always invoke via `npx -p @slats/claude-assets-sync ...`; the package manager fetches and caches the engine on demand.
+
+```bash
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user
+```
 
 | Flag | Meaning |
 |---|---|
-| `--scope=user` | `~/.claude` (applies globally) |
-| `--scope=project` | nearest ancestor `.claude` directory, or `<cwd>/.claude` if none found |
-| `--dry-run` | print the copy / skip / warn plan, no writes |
-| `--force` | overwrite diverged files & delete orphans (interactive confirm on TTY) |
+| `--package <name>` | **Required.** Scoped npm name of a consumer that declares `claude.assetPath`. |
+| `--scope=user` | `~/.claude` (applies globally). |
+| `--scope=project` | Nearest ancestor `.claude` directory, or `<cwd>/.claude` if none found. |
+| `--dry-run` | Print the copy / skip / warn plan, no writes. |
+| `--force` | Overwrite diverged files & delete orphans (interactive confirm on TTY). |
+| `--root <path>` | Override scope-resolution cwd. |
 
-**Exit codes**: `0` success / up-to-date / dry-run, `1` runtime error, `2` user / configuration error (e.g. missing `--scope` in non-TTY, invalid `assetPath`).
+**Exit codes**: `0` success / up-to-date / dry-run, `1` runtime error, `2` user / configuration error (missing `--package`, missing `--scope` in non-TTY, unresolvable package, missing `claude.assetPath`).
 
 For `--scope=project` the target `.claude` directory is resolved by walking up from `process.cwd()` to the nearest existing `.claude` ancestor; the CLI logs `(auto-located)` when this happens.
 
-## Consumer Integration (3 steps)
+## Consumer Integration (2 steps)
 
 ### 1. `package.json`
 
 ```jsonc
 {
   "name": "@your-scope/your-package",
-  "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": {
+  "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 pull CLI code into app bundles.
-
-### 2. `bin/claude-sync.mjs`
-
-```javascript
-#!/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'),
-);
+- `@slats/claude-assets-sync` MUST be in `devDependencies` — the engine is a CLI-only tool and must not leak into end-user production installs. See Rationale below.
+- Do **not** add any `bin` field. The engine is the sole CLI surface; per-consumer bins would collide under `node_modules/.bin/`.
+- Do **not** expose `./bin/*` or `./docs/*` in `exports`. That would let consumer bundlers pull CLI code or the asset tree into app bundles.
+- Do **not** create a `bin/` or `scripts/` directory in the consumer.
 
-if (typeof pkg.claude?.assetPath !== 'string') {
-  process.stderr.write(
-    `[claude-sync] missing or invalid "claude.assetPath" in ${resolve(packageRoot, 'package.json')}\n`,
-  );
-  process.exit(2);
-}
+### 2. Build
 
-await 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);
-});
+```bash
+yarn build
+# rolls up the library, emits types, then `claude-build-hashes` hashes every
+# file under `claude.assetPath` and writes dist/claude-hashes.json
 ```
 
-The `claude.assetPath` field in the consumer's `package.json` is a **consumer-side convention**; the library does not enforce or read it. Consumers are free to resolve `assetPath` in any way they choose and pass the result to `runCli`.
-
-### 3. `scripts/build-hashes.mjs`
-
-```javascript
-#!/usr/bin/env node
-import { buildHashes } from '@slats/claude-assets-sync/buildHashes';
+Ship the resulting `dist/` (including `claude-hashes.json`) alongside `docs/` when you publish.
 
-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);
-}
-```
+### Rationale: `devDependencies`, not `dependencies`
 
-`buildHashes` reads the current `package.json`'s `claude.assetPath`, hashes every file beneath it (ignoring `.omc/**`, `*.log`, `.DS_Store`), and writes `dist/claude-hashes.json`.
+- The engine is used at two moments only: (1) the consumer's own build, where `claude-build-hashes` produces `dist/claude-hashes.json`, and (2) the end user's one-off `inject-claude-settings` invocation. Neither is runtime behaviour of the consumer library.
+- Putting the engine in `dependencies` would force every downstream installer of the consumer to pull `commander`, `@inquirer/prompts`, and their transitive trees into their production `node_modules` — dead weight for anyone who never sets up Claude Code assets.
+- The workspace 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 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.
+- Bundle isolation is enforced by the import graph (`src/**` in the consumer never references the engine), not by dependency-type.
 
 ## Authoring `docs/claude/`
 
@@ -138,6 +116,12 @@ Every file under the asset root is hashed and tracked in `dist/claude-hashes.jso
 - `--force` on TTY opens an interactive confirm via `@inquirer/prompts.confirm`, listing up to 3 diverged/orphan paths.
 - `--force` on non-TTY prints the divergent list to stderr and proceeds.
 
+## Architectural Invariants
+
+- `src/core/**` never reads `package.json` or walks the filesystem. Only the `bin/` layer (and `src/commands/runCli/utils/resolvePackage.ts`, invoked from that dispatcher) is allowed to resolve a single explicitly-named target via `createRequire().resolve('${name}/package.json')`. Cross-package discovery (`--all`, workspace scan) is not supported.
+- Prompts go through `@inquirer/prompts` only. No ink, no React.
+- The engine assumes one consumer per invocation. That is the stable contract — extensions require explicit re-architecture.
+
 ## Programmatic API
 
 ```ts
@@ -156,7 +140,7 @@ See `src/index.ts` and `src/DETAIL.md` for the full export surface.
 
 ## Additional Docs
 
-- `docs/consumer-integration.md` — complete consumer checklist (dep-cruiser rules, verification steps, end-user install topologies)
+- `docs/consumer-integration.md` — complete consumer checklist (package.json patches, verification steps, end-user install topologies)
 - `docs/bundle-size-decision.md` — why `@inquirer/prompts` over ink
 
 ## License

package/bin/inject-claude-settings.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '@slats/claude-assets-sync';
+
+await runCli(process.argv);

package/dist/claude-hashes.json

@@ -2,19 +2,19 @@
   "schemaVersion": 1,
   "package": {
     "name": "@slats/claude-assets-sync",
-    "version": "0.2.0"
+    "version": "0.3.1"
   },
-  "generatedAt": "2026-04-24T04:25:43.386Z",
+  "generatedAt": "2026-04-24T16:37:59.339Z",
   "algorithm": "sha256",
   "assetRoot": "docs/claude",
   "files": {
-    "skills/claude-sync-applier/SKILL.md": "1c846b7ff7b127217a3201028ec4e1476857e5a5bb38b92d863b92a16ac4c7d0",
-    "skills/claude-sync-applier/knowledge/claude-md-template.md": "966fcc668b0e8f43ae83a6111ba1887d5504182e0b138e19937abb1fb43b3318",
-    "skills/claude-sync-applier/knowledge/dependency-cruiser.md": "058de112be3c03999846a66d066be540f72f2b1c40f5a1d04a82d36236a3c562",
-    "skills/claude-sync-applier/knowledge/gotchas.md": "310ffb416cbcaaf4b9162d0e6004dead6a8d658ff693ffe9e8580a8b83f7b6ea",
-    "skills/claude-sync-applier/knowledge/package-json-patches.md": "3ef1c39800e541e6390575a5296a8a247772b58c126c30149cd1efa61ead5dcc",
-    "skills/claude-sync-applier/knowledge/reference-files.md": "d0d42df1f90b17d8a35e914bfd16fe381890d71e0ea6a767d1e5e14874f2b95f",
-    "skills/claude-sync-applier/knowledge/smoke-tests.md": "76c396e2c7d410920139c894fc52d74e9914ea59d0e41dc30ebfe106e99c4be3"
+    "skills/claude-docs-asset-wiring/SKILL.md": "4864a5a1aba0813fb64ad19111f3db4369df6cc025e485d03d17cdc9d245bce5",
+    "skills/claude-docs-asset-wiring/knowledge/claude-md-template.md": "b0274c5a37076a7e80bd7beccd739b10cc91ca5395fe425be25d9129206c684a",
+    "skills/claude-docs-asset-wiring/knowledge/dependency-cruiser.md": "18e994bd16242f72a4dc6cfa508493f4b63853a7a16c4910c7b7abd0368bd103",
+    "skills/claude-docs-asset-wiring/knowledge/gotchas.md": "70a6c75ea09816ec457615c060e6a87197bc5ed332a377452b3cacd974b44eee",
+    "skills/claude-docs-asset-wiring/knowledge/package-json-patches.md": "063469932191843a2f7f9156a513717947bcad584c4084a0c8300897683885e7",
+    "skills/claude-docs-asset-wiring/knowledge/reference-files.md": "1b5f76d262f47835c4d0150a48fa25dfc644609fd4ecad260273a4cab57e41a2",
+    "skills/claude-docs-asset-wiring/knowledge/smoke-tests.md": "c90fc82d46bf4b55d794c2ce463b4c1e199d13d6b1161028486fb4bbbd6a60fe"
   },
   "previousVersions": {}
 }

package/dist/commands/index.d.ts

@@ -1 +1 @@
-export { runCli, type DefaultFlags, type RunCliOptions, } from './runCli/index.js';
+export { runCli, type DefaultFlags } from './runCli/index.js';

package/dist/commands/runCli/index.d.ts

@@ -1,2 +1,2 @@
 export { runCli } from './runCli.js';
-export type { DefaultFlags, RunCliOptions } from './type.js';
+export type { DefaultFlags } from './type.js';

package/dist/commands/runCli/runCli.d.ts

@@ -1,10 +1,14 @@
-import type { RunCliOptions } from './type.js';
 /**
  * CLI entry for `@slats/claude-assets-sync`.
  *
- * The caller passes its own package metadata (`packageRoot`, `packageName`,
- * `packageVersion`, `assetPath`) so the library never walks the filesystem
- * looking for consumers. Consumer bin stubs read their own `package.json`
- * and forward the resolved values here.
+ * The `inject-claude-settings` dispatcher parses `--package <name...>`
+ * from argv and classifies each value:
+ * - `@<scope>` — enumerate every workspace package under that scope
+ * - `@<scope>/<name>` — one scoped package
+ * - `<name>` — one unscoped package
+ *
+ * Targets are resolved via Node module resolution (`resolvePackage`)
+ * except for scope aliases, which are the only path allowed to walk
+ * the monorepo — that exception is isolated to `resolveScopeAlias.ts`.
  */
-export declare function runCli(argv: readonly string[] | undefined, options: RunCliOptions): Promise<void>;
+export declare function runCli(argv?: readonly string[]): Promise<void>;

package/dist/commands/runCli/runCli.mjs

@@ -1,20 +1,38 @@
 import { Command } from 'commander';
 import { logger } from '../../utils/logger.mjs';
 import { VERSION } from '../../utils/version.mjs';
-import { runInject } from './utils/runInject.mjs';
+import { renderOrFallback } from './utils/renderOrFallback.mjs';
+import { resolveTargets } from './utils/resolveTargets.mjs';
+import { toConsumerPackages } from './utils/toConsumerPackages.mjs';
 
-async function runCli(argv = process.argv, options) {
+async function runCli(argv = process.argv) {
     const cmd = new Command();
     cmd
-        .name('claude-sync')
-        .description("Inject this package's assets into the target .claude directory")
-        .version(options.version ?? VERSION)
+        .name('inject-claude-settings')
+        .description("Inject target consumer(s)' Claude assets into the selected .claude directory")
+        .version(VERSION)
+        .option('--package <name...>', 'Target(s). "@<scope>" = whole npm scope; "@<scope>/<name>" or "<name>" = one package. Repeat the flag or comma-separate values.', collectPackageValues, [])
         .option('--scope <scope>', 'Target scope: user (~/.claude) | project (nearest ancestor .claude or <cwd>/.claude)')
         .option('--dry-run', 'Preview without writing', false)
         .option('--force', 'Overwrite user modifications', false)
         .option('--root <path>', 'Override scope resolution cwd (default: cwd)')
+        .option('--json', 'Emit structured JSON output (forces non-interactive legacy logger path)', false)
         .action(async (flags) => {
-        await runInject(flags, options);
+        const targets = flags.package ?? [];
+        if (targets.length === 0) {
+            logger.error('missing required flag: --package <name> (e.g. --package=@canard/schema-form or --package=@canard)');
+            process.exit(2);
+        }
+        const originCwd = flags.root ?? process.cwd();
+        const metadataList = await resolveTargets(targets, originCwd);
+        if (metadataList.length === 0) {
+            logger.warn(`no packages resolved from --package target(s): ${targets.join(', ')}`);
+            return;
+        }
+        const consumerPackages = await toConsumerPackages(metadataList);
+        const exitCode = await renderOrFallback(consumerPackages, flags, originCwd);
+        if (exitCode !== 0)
+            process.exit(exitCode);
     });
     try {
         await cmd.parseAsync([...argv]);
@@ -25,5 +43,14 @@ async function runCli(argv = process.argv, options) {
         process.exit(1);
     }
 }
+function collectPackageValues(value, previous = []) {
+    return [
+        ...previous,
+        ...value
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean),
+    ];
+}
 
 export { runCli };

package/dist/commands/runCli/type.d.ts

@@ -1,23 +1,15 @@
-export interface RunCliOptions {
-    version?: string;
-    /** Absolute filesystem path to the consumer package root. */
-    packageRoot: string;
-    /** Consumer package name used in logs and error messages. */
-    packageName: string;
-    /** Consumer package version used in logs. */
-    packageVersion: string;
-    /** Asset directory path relative to `packageRoot`. */
-    assetPath: string;
-}
 export interface DefaultFlags {
     scope?: string;
     dryRun?: boolean;
     force?: boolean;
     root?: string;
+    package?: string[];
+    json?: boolean;
 }
 /**
  * Resolved consumer metadata passed to the injection pipeline.
- * The caller owns the definition; the library does not read `package.json`.
+ * The dispatcher bin populates this by resolving a single explicitly-named
+ * target package — `core/**` still never reads `package.json` itself.
  */
 export interface ConsumerPackage {
     name: string;

package/dist/commands/runCli/utils/classifyTarget.d.ts

@@ -0,0 +1,19 @@
+export type ClassifiedTarget = {
+    kind: 'scope';
+    scope: string;
+} | {
+    kind: 'package';
+    name: string;
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+/**
+ * Classify a `--package` value as a scope alias, a package name, or invalid.
+ *
+ * - `@<scope>` (no slash) — all packages under that npm scope
+ * - `@<scope>/<name>` — one scoped package
+ * - `<name>` (no `@`, no slash) — one unscoped package
+ * - anything else → invalid
+ */
+export declare function classifyTarget(target: string): ClassifiedTarget;

package/dist/commands/runCli/utils/classifyTarget.mjs

@@ -0,0 +1,46 @@
+const NPM_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+function classifyTarget(target) {
+    if (typeof target !== 'string' || target.length === 0) {
+        return { kind: 'invalid', reason: 'empty --package value' };
+    }
+    if (target.startsWith('@')) {
+        const body = target.slice(1);
+        const slashIndex = body.indexOf('/');
+        if (slashIndex === -1) {
+            if (!NPM_NAME_PATTERN.test(body)) {
+                return {
+                    kind: 'invalid',
+                    reason: `invalid scope alias "${target}" — expected "@<scope>" with lowercase alphanumerics, ".", "-", or "_"`,
+                };
+            }
+            return { kind: 'scope', scope: body };
+        }
+        const scopePart = body.slice(0, slashIndex);
+        const namePart = body.slice(slashIndex + 1);
+        if (!NPM_NAME_PATTERN.test(scopePart) ||
+            namePart.length === 0 ||
+            namePart.includes('/') ||
+            !NPM_NAME_PATTERN.test(namePart)) {
+            return {
+                kind: 'invalid',
+                reason: `invalid scoped package "${target}" — expected "@<scope>/<name>"`,
+            };
+        }
+        return { kind: 'package', name: target };
+    }
+    if (target.includes('/')) {
+        return {
+            kind: 'invalid',
+            reason: `invalid target "${target}" — unscoped package names cannot contain "/"`,
+        };
+    }
+    if (!NPM_NAME_PATTERN.test(target)) {
+        return {
+            kind: 'invalid',
+            reason: `invalid package name "${target}" — expected lowercase alphanumerics, ".", "-", or "_"`,
+        };
+    }
+    return { kind: 'package', name: target };
+}
+
+export { classifyTarget };

package/dist/commands/runCli/utils/renderOrFallback.d.ts

@@ -0,0 +1,6 @@
+import type { ConsumerPackage, DefaultFlags } from '../type.js';
+interface RenderEnv {
+    readonly isTTY?: boolean;
+}
+export declare function renderOrFallback(targets: readonly ConsumerPackage[], flags: DefaultFlags, originCwd: string, env?: RenderEnv): Promise<number>;
+export {};

package/dist/commands/runCli/utils/renderOrFallback.mjs

@@ -0,0 +1,12 @@
+import { renderPlain } from './renderPlain.mjs';
+
+async function renderOrFallback(targets, flags, originCwd, env = {}) {
+    const isTTY = env.isTTY ?? Boolean(process.stdout.isTTY);
+    if (flags.json || !isTTY) {
+        return renderPlain(targets, flags, originCwd);
+    }
+    const ui = (await import('../../../ui/index.mjs'));
+    return ui.renderInjectApp({ targets, flags, originCwd });
+}
+
+export { renderOrFallback };

package/dist/commands/runCli/utils/renderPlain.d.ts

@@ -0,0 +1,11 @@
+import type { ConsumerPackage, DefaultFlags } from '../type.js';
+/**
+ * Plain (picocolors) renderer for non-TTY / `--json` invocations.
+ *
+ * Composes the same `core/**` primitives that the Ink `useInjectSession`
+ * pipeline uses — no legacy `injectDocs` orchestrator in between.
+ * Missing `--scope` on non-TTY exits via `resolveScopeFlag` with code 2.
+ * Divergent/orphan files still respect `--force`: absence of `--force`
+ * returns 2; presence logs the list to stderr and proceeds.
+ */
+export declare function renderPlain(targets: readonly ConsumerPackage[], flags: DefaultFlags, originCwd: string): Promise<number>;

package/dist/commands/runCli/utils/renderPlain.mjs

@@ -0,0 +1,89 @@
+import 'node:crypto';
+import 'node:fs/promises';
+import { readHashManifest, computeNamespacePrefixes } from '../../../core/hashManifest/hashManifest.mjs';
+import { applyAction } from '../../../core/injectDocs/utils/applyAction.mjs';
+import { summarize } from '../../../core/injectDocs/utils/summarize.mjs';
+import { buildPlan } from '../../../core/buildPlan/buildPlan.mjs';
+import { resolveScope } from '../../../core/scope/scope.mjs';
+import { asyncPool } from '../../../utils/asyncPool.mjs';
+import { logger } from '../../../utils/logger.mjs';
+import { resolveScopeFlag } from './resolveScopeFlag.mjs';
+
+async function renderPlain(targets, flags, originCwd) {
+    if (targets.length === 0)
+        return 0;
+    const scope = resolveScopeFlag(flags.scope);
+    const fatalOnError = targets.length === 1;
+    let failureCount = 0;
+    for (const target of targets) {
+        if (!target.hashesPresent) {
+            logger.warn(`${target.name}: dist/claude-hashes.json missing — build the package (e.g. yarn build) to regenerate the hash manifest first.`);
+            continue;
+        }
+        logger.heading(`${target.name}@${target.version}`);
+        let exitCode;
+        try {
+            exitCode = await renderOneTarget(target, scope, flags, originCwd);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`${target.name}: ${msg}`);
+            exitCode = 1;
+        }
+        if (exitCode !== 0) {
+            if (fatalOnError)
+                return exitCode;
+            failureCount += 1;
+        }
+    }
+    return failureCount > 0 ? 1 : 0;
+}
+async function renderOneTarget(target, scope, flags, originCwd) {
+    const manifest = await readHashManifest(target.packageRoot);
+    const resolution = resolveScope(scope, originCwd);
+    const plan = await buildPlan({
+        sourceHashes: manifest.files,
+        targetRoot: resolution.targetRoot,
+        namespacePrefixes: computeNamespacePrefixes(manifest),
+        force: flags.force ?? false,
+    });
+    logger.info(`${target.name}@${target.version} → ${resolution.description}`);
+    printPlan(plan);
+    if (plan.requiresForce && !flags.force) {
+        logger.error('Re-run with --force to proceed, or inspect with --dry-run.');
+        return 2;
+    }
+    if (flags.force &&
+        plan.actions.some((a) => a.kind === 'warn-diverged' || a.kind === 'warn-orphan')) {
+        emitForceList(plan);
+    }
+    if (flags.dryRun) {
+        logger.warn('[DRY RUN] No files will be created, overwritten, or deleted.');
+        return 0;
+    }
+    await asyncPool(8, plan.actions, (action) => applyAction(action, target.assetRoot));
+    const report = summarize(plan, 0);
+    return report.exitCode;
+}
+function printPlan(plan) {
+    for (const action of plan.actions) {
+        if (action.kind === 'copy')
+            logger.file('create', action.relPath);
+        else if (action.kind === 'skip-uptodate')
+            logger.file('skip', `${action.relPath} (up-to-date)`);
+        else if (action.kind === 'warn-diverged')
+            logger.warn(`${action.relPath} — local differs from source (user edit or version change)`);
+        else if (action.kind === 'warn-orphan')
+            logger.warn(`${action.relPath} — present locally, absent in source`);
+        else if (action.kind === 'delete')
+            logger.file('update', `${action.relPath} (deleting)`);
+    }
+}
+function emitForceList(plan) {
+    const divergent = plan.actions.filter((action) => action.kind === 'warn-diverged' || action.kind === 'warn-orphan');
+    process.stderr.write(`[claude-assets-sync] --force overwriting ${divergent.length} file(s) in non-TTY mode:\n`);
+    for (const action of divergent)
+        process.stderr.write(`  ${action.relPath}\n`);
+}
+
+export { renderPlain };

package/dist/commands/runCli/utils/resolvePackage.d.ts

@@ -0,0 +1,16 @@
+export interface ResolvedMetadata {
+    packageRoot: string;
+    packageName: string;
+    packageVersion: string;
+    assetPath: string;
+}
+export interface ResolvePackageOptions {
+    /**
+     * When `true`, a package without `claude.assetPath` is warned and the
+     * function returns `null` instead of calling `process.exit`. Default
+     * `false` preserves the v0.3.0 strict behavior for single-target
+     * dispatcher calls.
+     */
+    skipMissingAsset?: boolean;
+}
+export declare function resolvePackage(name: string, options?: ResolvePackageOptions): Promise<ResolvedMetadata | null>;

package/dist/commands/runCli/utils/resolvePackage.mjs

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { logger } from '../../../utils/logger.mjs';
+
+async function resolvePackage(name, options = {}) {
+    const pkgJsonPath = resolvePackageJsonPath(name);
+    if (!pkgJsonPath) {
+        logger.error(`cannot resolve package "${name}". Install it in the current project or pass the correct name.`);
+        process.exit(2);
+    }
+    const packageRoot = dirname(pkgJsonPath);
+    const raw = await readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.name !== 'string' || typeof pkg.version !== 'string') {
+        if (options.skipMissingAsset) {
+            logger.warn(`"${name}" package.json is missing a string "name" or "version" — skipping.`);
+            return null;
+        }
+        logger.error(`${pkgJsonPath} must define string "name" and "version".`);
+        process.exit(2);
+    }
+    const assetPath = pkg.claude?.assetPath;
+    if (typeof assetPath !== 'string' || assetPath.length === 0) {
+        if (options.skipMissingAsset) {
+            logger.warn(`"${name}" is missing "claude.assetPath" — skipping (the package does not ship Claude assets).`);
+            return null;
+        }
+        logger.error(`"${name}" is missing "claude.assetPath" in its package.json — the package does not ship Claude assets.`);
+        process.exit(2);
+    }
+    return {
+        packageRoot,
+        packageName: pkg.name,
+        packageVersion: pkg.version,
+        assetPath,
+    };
+}
+function resolvePackageJsonPath(name) {
+    const require = createRequire(import.meta.url);
+    try {
+        return require.resolve(`${name}/package.json`);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+            return null;
+    }
+    let mainEntry;
+    try {
+        mainEntry = require.resolve(name);
+    }
+    catch {
+        return null;
+    }
+    let dir = dirname(mainEntry);
+    while (dir && dir !== dirname(dir)) {
+        const candidate = resolve(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                if (pkg.name === name)
+                    return candidate;
+            }
+            catch {
+            }
+        }
+        dir = dirname(dir);
+    }
+    return null;
+}
+
+export { resolvePackage };

package/dist/commands/runCli/utils/resolveScopeAlias.d.ts

@@ -0,0 +1,2 @@
+import { type ResolvedMetadata } from './resolvePackage.js';
+export declare function resolveScopeAlias(scope: string, rootCwd: string): Promise<ResolvedMetadata[]>;