@slats/claude-assets-sync 0.2.0 → 0.3.0

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
+
+```bash
+# universal — every PM (pnpm strict / yarn-berry PnP included)
+npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user
+
+# simple — npm / yarn-classic only (relies on transitive bin hoist from the consumer's dependencies)
+npx 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": {
     "@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 `dependencies`, not `devDependencies` — 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: `dependencies`, not `devDependencies`
 
-`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 monorepo build chain needs `.bin/claude-build-hashes` resolved, which requires the engine as a direct dep.
+- 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>`. 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>`.
+- 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.0"
   },
-  "generatedAt": "2026-04-24T04:25:43.386Z",
+  "generatedAt": "2026-04-24T14:51:13.873Z",
   "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": "1984ed9ea93be0e7b8eec8f77d57c455e670989c3948546d017343e321fe1b80",
+    "skills/claude-docs-asset-wiring/knowledge/claude-md-template.md": "affd92189e9d367c8717068695aca8acbadf68989a4073a8c4b1e2f4a622b72d",
+    "skills/claude-docs-asset-wiring/knowledge/dependency-cruiser.md": "18e994bd16242f72a4dc6cfa508493f4b63853a7a16c4910c7b7abd0368bd103",
+    "skills/claude-docs-asset-wiring/knowledge/gotchas.md": "9957464329cc970f6717179fad907ffad45ee4433b1d6151e20b5b3bee75b775",
+    "skills/claude-docs-asset-wiring/knowledge/package-json-patches.md": "426dcfdfdd5c02405c3d8a753b800fc90e1e9286d6f1c3c29320cf13e2645878",
+    "skills/claude-docs-asset-wiring/knowledge/reference-files.md": "3a63a095826bbfd07fae232568faf4d415dbdae0970ee4466c962ba285c3a01d",
+    "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.cjs

@@ -3,20 +3,33 @@
 var commander = require('commander');
 var logger = require('../../utils/logger.cjs');
 var version = require('../../utils/version.cjs');
+var resolveTargets = require('./utils/resolveTargets.cjs');
 var runInject = require('./utils/runInject.cjs');
 
-async function runCli(argv = process.argv, options) {
+async function runCli(argv = process.argv) {
     const cmd = new commander.Command();
     cmd
-        .name('claude-sync')
-        .description("Inject this package's assets into the target .claude directory")
-        .version(options.version ?? version.VERSION)
+        .name('inject-claude-settings')
+        .description("Inject target consumer(s)' Claude assets into the selected .claude directory")
+        .version(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)')
         .action(async (flags) => {
-        await runInject.runInject(flags, options);
+        const targets = flags.package ?? [];
+        if (targets.length === 0) {
+            logger.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.resolveTargets(targets, originCwd);
+        if (metadataList.length === 0) {
+            logger.logger.warn(`no packages resolved from --package target(s): ${targets.join(', ')}`);
+            return;
+        }
+        await runInject.runInject(flags, metadataList);
     });
     try {
         await cmd.parseAsync([...argv]);
@@ -27,5 +40,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),
+    ];
+}
 
 exports.runCli = runCli;

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,33 @@
 import { Command } from 'commander';
 import { logger } from '../../utils/logger.mjs';
 import { VERSION } from '../../utils/version.mjs';
+import { resolveTargets } from './utils/resolveTargets.mjs';
 import { runInject } from './utils/runInject.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)')
         .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;
+        }
+        await runInject(flags, metadataList);
     });
     try {
         await cmd.parseAsync([...argv]);
@@ -25,5 +38,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,14 @@
-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[];
 }
 /**
  * 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.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+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 };
+}
+
+exports.classifyTarget = classifyTarget;

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/injectOne.cjs

@@ -15,7 +15,7 @@ var logger = require('../../../utils/logger.cjs');
 async function injectOne(target, scope, flags, originCwd) {
     if (!target.hashesPresent) {
         logger.logger.warn(`${target.name}: dist/claude-hashes.json missing — build the package (e.g. yarn build) to regenerate the hash manifest first.`);
-        return;
+        return 0;
     }
     logger.logger.heading(`${target.name}@${target.version}`);
     const stopHeartbeat = heartbeat.startHeartbeat({
@@ -37,8 +37,7 @@ async function injectOne(target, scope, flags, originCwd) {
                 return confirmForce.confirmForceAsync(diverged.length, orphans.length, [...diverged, ...orphans].map((a) => a.relPath).slice(0, 3));
             },
         });
-        if (report.exitCode !== 0)
-            process.exit(report.exitCode);
+        return report.exitCode;
     }
     finally {
         stopHeartbeat();

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

@@ -1,3 +1,3 @@
 import { type Scope } from '../../../core/index.js';
 import type { ConsumerPackage, DefaultFlags } from '../type.js';
-export declare function injectOne(target: ConsumerPackage, scope: Scope, flags: DefaultFlags, originCwd: string): Promise<void>;
+export declare function injectOne(target: ConsumerPackage, scope: Scope, flags: DefaultFlags, originCwd: string): Promise<number>;

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

@@ -13,7 +13,7 @@ import { logger } from '../../../utils/logger.mjs';
 async function injectOne(target, scope, flags, originCwd) {
     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.`);
-        return;
+        return 0;
     }
     logger.heading(`${target.name}@${target.version}`);
     const stopHeartbeat = startHeartbeat({
@@ -35,8 +35,7 @@ async function injectOne(target, scope, flags, originCwd) {
                 return confirmForceAsync(diverged.length, orphans.length, [...diverged, ...orphans].map((a) => a.relPath).slice(0, 3));
             },
         });
-        if (report.exitCode !== 0)
-            process.exit(report.exitCode);
+        return report.exitCode;
     }
     finally {
         stopHeartbeat();

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

@@ -0,0 +1,77 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var promises = require('node:fs/promises');
+var node_module = require('node:module');
+var node_path = require('node:path');
+var logger = require('../../../utils/logger.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+async function resolvePackage(name, options = {}) {
+    const pkgJsonPath = resolvePackageJsonPath(name);
+    if (!pkgJsonPath) {
+        logger.logger.error(`cannot resolve package "${name}". Install it in the current project or pass the correct name.`);
+        process.exit(2);
+    }
+    const packageRoot = node_path.dirname(pkgJsonPath);
+    const raw = await promises.readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.name !== 'string' || typeof pkg.version !== 'string') {
+        if (options.skipMissingAsset) {
+            logger.logger.warn(`"${name}" package.json is missing a string "name" or "version" — skipping.`);
+            return null;
+        }
+        logger.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.logger.warn(`"${name}" is missing "claude.assetPath" — skipping (the package does not ship Claude assets).`);
+            return null;
+        }
+        logger.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$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('commands/runCli/utils/resolvePackage.cjs', document.baseURI).href)));
+    try {
+        return require$1.resolve(`${name}/package.json`);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+            return null;
+    }
+    let mainEntry;
+    try {
+        mainEntry = require$1.resolve(name);
+    }
+    catch {
+        return null;
+    }
+    let dir = node_path.dirname(mainEntry);
+    while (dir && dir !== node_path.dirname(dir)) {
+        const candidate = node_path.resolve(dir, 'package.json');
+        if (node_fs.existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(node_fs.readFileSync(candidate, 'utf-8'));
+                if (pkg.name === name)
+                    return candidate;
+            }
+            catch {
+            }
+        }
+        dir = node_path.dirname(dir);
+    }
+    return null;
+}
+
+exports.resolvePackage = resolvePackage;

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>;