@slats/claude-assets-sync 0.3.1 → 0.3.3

package/README.md

@@ -4,9 +4,9 @@ Engine + dispatcher CLI that lets any npm package ship its own Claude Code docs
 
 ## Overview
 
-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.
+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 @slats/claude-assets-sync --package=<name>` and this engine resolves each consumer's metadata, compares its 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.
+`--package` accepts a scoped name (`@scope/pkg`), an unscoped name (`pkg`), or a **scope alias** (`@scope` with no slash) that fans out to every installed `node_modules/@scope/*` package declaring `claude.assetPath`. Single-target resolution uses `createRequire`; scope-alias enumeration walks ancestor `node_modules/@<scope>/` directories from `cwd` upward and is isolated to `runCli/utils/resolveScopeAlias.ts`.
 
 No GitHub fetch, no `.sync-meta.json`, no migrations — the consumer's `dist/claude-hashes.json` is the single source of truth.
 
@@ -21,21 +21,48 @@ yarn add -D @slats/claude-assets-sync
 ## CLI Surface
 
 ```
-inject-claude-settings --package=<name> [--scope=user|project] [--dry-run] [--force] [--root=<cwd>]
+<bin> --package=<name> [--scope=user|project] [--dry-run] [--force] [--root=<cwd>]
 claude-build-hashes
 ```
 
+`<bin>` is one of three entry points that all dispatch to the same engine:
+
+| Bin | Use when |
+|---|---|
+| `claude-assets-sync` | invoking via `npx` — matches the package's unscoped name so `npx @slats/claude-assets-sync ...` works directly |
+| `inject-claude-settings` | the engine is installed (`yarn add -D` / `npm i -g`) and you prefer a descriptive command name |
+| `claude-build-hashes` | build-time helper for consumer packages (run from `package.json` scripts) |
+
 ### 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.
+The engine is not shipped as a runtime dependency of consumers. The canonical npx form is:
+
+```bash
+# Single consumer:
+npx @slats/claude-assets-sync --package=@canard/schema-form --scope=user
+
+# Scope alias — every installed @winglet/* that declares claude.assetPath:
+npx @slats/claude-assets-sync --package=@winglet --scope=user
+```
+
+The dispatcher walks `node_modules` from the current working directory (or `--root <path>`) up to the filesystem root, so it works as long as the target package is installed somewhere in the host project's hoisting chain.
+
+#### Installed CLI (alternative)
 
 ```bash
-npx -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user
+yarn add -D @slats/claude-assets-sync
+yarn inject-claude-settings --package=@canard/schema-form --scope=user
+
+# or globally:
+npm i -g @slats/claude-assets-sync
+inject-claude-settings --package=@canard/schema-form --scope=user
 ```
 
+The legacy explicit form `npx -p @slats/claude-assets-sync inject-claude-settings ...` continues to work for backward compatibility.
+
 | Flag | Meaning |
 |---|---|
-| `--package <name>` | **Required.** Scoped npm name of a consumer that declares `claude.assetPath`. |
+| `--package <name>` | **Required.** Repeatable/comma-separable. Accepts `@scope/pkg`, `pkg`, or a scope alias `@scope` (fans out to every installed `node_modules/@scope/*` with `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. |
@@ -85,7 +112,7 @@ Ship the resulting `dist/` (including `claude-hashes.json`) alongside `docs/` wh
 - 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.
+- End users never rely on a hoisted `inject-claude-settings` bin. The canonical invocation is `npx @slats/claude-assets-sync --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/`

package/dist/claude-hashes.json

@@ -2,9 +2,9 @@
   "schemaVersion": 1,
   "package": {
     "name": "@slats/claude-assets-sync",
-    "version": "0.3.1"
+    "version": "0.3.3"
   },
-  "generatedAt": "2026-04-24T16:37:59.339Z",
+  "generatedAt": "2026-04-26T11:57:30.854Z",
   "algorithm": "sha256",
   "assetRoot": "docs/claude",
   "files": {

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

@@ -3,12 +3,14 @@
  *
  * The `inject-claude-settings` dispatcher parses `--package <name...>`
  * from argv and classifies each value:
- * - `@<scope>` — enumerate every workspace package under that scope
+ * - `@<scope>` — enumerate every installed `node_modules/@<scope>/*`
+ *   package that declares `claude.assetPath`
  * - `@<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`.
+ * `node_modules` siblings — that exception is isolated to
+ * `resolveScopeAlias.ts`.
  */
 export declare function runCli(argv?: readonly string[]): Promise<void>;

package/dist/commands/runCli/runCli.mjs

@@ -1,3 +1,4 @@
+import { basename } from 'node:path';
 import { Command } from 'commander';
 import { logger } from '../../utils/logger.mjs';
 import { VERSION } from '../../utils/version.mjs';
@@ -5,10 +6,11 @@ import { renderOrFallback } from './utils/renderOrFallback.mjs';
 import { resolveTargets } from './utils/resolveTargets.mjs';
 import { toConsumerPackages } from './utils/toConsumerPackages.mjs';
 
+const FALLBACK_PROGRAM_NAME = 'inject-claude-settings';
 async function runCli(argv = process.argv) {
     const cmd = new Command();
     cmd
-        .name('inject-claude-settings')
+        .name(deriveProgramName(argv))
         .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, [])
@@ -52,5 +54,13 @@ function collectPackageValues(value, previous = []) {
             .filter(Boolean),
     ];
 }
+function deriveProgramName(argv) {
+    const argv1 = argv[1];
+    if (typeof argv1 !== 'string' || argv1.length === 0) {
+        return FALLBACK_PROGRAM_NAME;
+    }
+    const base = basename(argv1).replace(/\.(mjs|cjs|js)$/, '');
+    return base.length > 0 ? base : FALLBACK_PROGRAM_NAME;
+}
 
 export { runCli };

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

@@ -13,4 +13,4 @@ export interface ResolvePackageOptions {
      */
     skipMissingAsset?: boolean;
 }
-export declare function resolvePackage(name: string, options?: ResolvePackageOptions): Promise<ResolvedMetadata | null>;
+export declare function resolvePackage(name: string, options?: ResolvePackageOptions, originCwd?: string): Promise<ResolvedMetadata | null>;

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

@@ -2,10 +2,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { logger } from '../../../utils/logger.mjs';
 
-async function resolvePackage(name, options = {}) {
-    const pkgJsonPath = resolvePackageJsonPath(name);
+async function resolvePackage(name, options = {}, originCwd = process.cwd()) {
+    const pkgJsonPath = resolvePackageJsonPath(name, originCwd);
     if (!pkgJsonPath) {
         logger.error(`cannot resolve package "${name}". Install it in the current project or pass the correct name.`);
         process.exit(2);
@@ -37,8 +38,14 @@ async function resolvePackage(name, options = {}) {
         assetPath,
     };
 }
-function resolvePackageJsonPath(name) {
-    const require = createRequire(import.meta.url);
+function resolvePackageJsonPath(name, originCwd) {
+    const fromCwd = tryResolveFrom(name, resolve(originCwd, '__resolve-base__'));
+    if (fromCwd)
+        return fromCwd;
+    return tryResolveFrom(name, fileURLToPath(import.meta.url));
+}
+function tryResolveFrom(name, baseFilename) {
+    const require = createRequire(baseFilename);
     try {
         return require.resolve(`${name}/package.json`);
     }

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

@@ -1,27 +1,45 @@
 import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
-import { join, resolve, dirname } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { logger } from '../../../utils/logger.mjs';
 import { resolvePackage } from './resolvePackage.mjs';
 
 async function resolveScopeAlias(scope, rootCwd) {
-    const packagesRoot = findPackagesRoot(rootCwd);
-    if (!packagesRoot) {
-        logger.error(`cannot locate a monorepo root with a "packages/" directory starting from "${rootCwd}". Scope alias "@${scope}" requires a workspace root.`);
+    const expectedPrefix = `@${scope}/`;
+    const seen = new Set();
+    const matchedNames = [];
+    let cur = resolve(rootCwd);
+    while (true) {
+        const scopeDir = join(cur, 'node_modules', `@${scope}`);
+        await collectScopeDir(scopeDir, expectedPrefix, seen, matchedNames);
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    if (matchedNames.length === 0) {
+        logger.error(`scope alias "@${scope}" matched no installed packages in any ancestor "node_modules/@${scope}/" walking up from ${rootCwd}.`);
         process.exit(2);
     }
-    const scopeDir = join(packagesRoot, 'packages', scope);
+    const resolved = [];
+    for (const name of matchedNames) {
+        const meta = await resolvePackage(name, { skipMissingAsset: true }, rootCwd);
+        if (meta)
+            resolved.push(meta);
+    }
+    return resolved;
+}
+async function collectScopeDir(scopeDir, expectedPrefix, seen, matchedNames) {
     let entries;
     try {
         entries = await readdir(scopeDir);
     }
     catch {
-        logger.error(`scope alias "@${scope}" has no matching directory at ${scopeDir}.`);
-        process.exit(2);
+        return;
     }
-    const matchedNames = [];
-    const expectedPrefix = `@${scope}/`;
     for (const entry of entries) {
+        if (entry.startsWith('.'))
+            continue;
         const pkgJsonPath = join(scopeDir, entry, 'package.json');
         if (!existsSync(pkgJsonPath))
             continue;
@@ -35,33 +53,12 @@ async function resolveScopeAlias(scope, rootCwd) {
         }
         if (typeof parsed.name === 'string' &&
             parsed.name.startsWith(expectedPrefix) &&
-            parsed.name.length > expectedPrefix.length) {
+            parsed.name.length > expectedPrefix.length &&
+            !seen.has(parsed.name)) {
+            seen.add(parsed.name);
             matchedNames.push(parsed.name);
         }
     }
-    if (matchedNames.length === 0) {
-        logger.warn(`scope alias "@${scope}" matched no workspace packages under ${scopeDir}.`);
-        return [];
-    }
-    const resolved = [];
-    for (const name of matchedNames) {
-        const meta = await resolvePackage(name, { skipMissingAsset: true });
-        if (meta)
-            resolved.push(meta);
-    }
-    return resolved;
-}
-function findPackagesRoot(start) {
-    let cur = resolve(start);
-    while (true) {
-        if (existsSync(join(cur, 'package.json')) && existsSync(join(cur, 'packages'))) {
-            return cur;
-        }
-        const parent = dirname(cur);
-        if (parent === cur)
-            return null;
-        cur = parent;
-    }
 }
 
 export { resolveScopeAlias };

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

@@ -20,9 +20,7 @@ async function resolveTargets(targets, rootCwd) {
             candidates = await resolveScopeAlias(classification.scope, rootCwd);
         }
         else {
-            const meta = await resolvePackage(classification.name, {
-                skipMissingAsset: !isSingleTarget,
-            });
+            const meta = await resolvePackage(classification.name, { skipMissingAsset: !isSingleTarget }, rootCwd);
             candidates = meta ? [meta] : [];
         }
         for (const meta of candidates) {

package/dist/ui/InjectApp/InjectApp.mjs

@@ -1,6 +1,7 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
-import { useCallback } from 'react';
 import { Box, Text } from 'ink';
+import { useCallback } from 'react';
+import { VERSION } from '../../utils/version.mjs';
 import { Banner } from '../components/Banner.mjs';
 import { ConfirmForce } from '../components/ConfirmForce.mjs';
 import { ErrorPanel } from '../components/ErrorPanel.mjs';
@@ -18,7 +19,6 @@ import { colors } from '../theme/colors.mjs';
 import { icons } from '../theme/icons.mjs';
 import { scopeLabel, etaSeconds } from './utils/eventSelectors.mjs';
 
-const VERSION = '0.3.0';
 function InjectApp(props) {
     const { targets, flags, originCwd, onExit } = props;
     const [phase, dispatch] = usePhase({ kind: 'resolving', targets });

package/dist/ui/InjectApp/utils/phaseReducer.mjs

@@ -14,7 +14,10 @@ function phaseReducer(phase, event) {
             return phase;
         }
         case 'planning-started': {
-            const progress = new Map(event.targets.map((t) => [t.name, { packageName: t.name, status: 'pending' }]));
+            const progress = new Map(event.targets.map((t) => [
+                t.name,
+                { packageName: t.name, status: 'pending' },
+            ]));
             return {
                 kind: 'planning',
                 targets: event.targets,

package/dist/ui/hooks/useExitApp.mjs

@@ -1,5 +1,5 @@
-import { useEffect } from 'react';
 import { useApp } from 'ink';
+import { useEffect } from 'react';
 
 function useExitApp({ enabled, exitCode, onExit, delayMs = 0, }) {
     const { exit } = useApp();

package/dist/ui/hooks/usePlanStep.mjs

@@ -46,7 +46,8 @@ function usePlanStep({ targets, scope, originCwd, force, dispatch, onPlansReady,
                     });
                     results.push({ target, scope: scopeResolution, plan });
                     for (const action of plan.actions) {
-                        if (action.kind === 'warn-diverged' || action.kind === 'warn-orphan') {
+                        if (action.kind === 'warn-diverged' ||
+                            action.kind === 'warn-orphan') {
                             warnings.push({
                                 packageName: target.name,
                                 kind: action.kind,

package/dist/ui/index.mjs

@@ -1,7 +1,7 @@
 import { renderInjectApp } from './InjectApp/utils/renderInjectApp.mjs';
 import 'react/jsx-runtime';
-import 'react';
 import 'ink';
+import 'react';
 import 'ink-select-input';
 import 'ink-spinner';
 import 'node:fs/promises';

package/dist/ui/types/target.d.ts

@@ -1,6 +1,6 @@
+import type { ConsumerPackage } from '../../commands/runCli/type.js';
 import type { InjectPlan } from '../../core/buildPlan/index.js';
 import type { ScopeResolution } from '../../core/index.js';
-import type { ConsumerPackage } from '../../commands/runCli/type.js';
 export interface PlanStepState {
     readonly packageName: string;
     readonly status: 'pending' | 'running' | 'done' | 'failed';

package/dist/utils/version.d.ts

@@ -2,4 +2,4 @@
  * Current package version from package.json
  * Automatically synchronized during build process
  */
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.3.3";

package/dist/utils/version.mjs

@@ -1,3 +1,3 @@
-const VERSION = '0.3.1';
+const VERSION = '0.3.3';
 
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slats/claude-assets-sync",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",
@@ -36,6 +36,7 @@
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "bin": {
+    "claude-assets-sync": "./bin/inject-claude-settings.mjs",
     "claude-build-hashes": "./scripts/claude-build-hashes.mjs",
     "inject-claude-settings": "./bin/inject-claude-settings.mjs"
   },

package/scripts/dev-ui.tsx

@@ -15,11 +15,10 @@ import { TargetCard } from '../src/ui/components/TargetCard.js';
 import { colors } from '../src/ui/theme/colors.js';
 import { icons } from '../src/ui/theme/icons.js';
 import type { Phase } from '../src/ui/types/index.js';
+import { VERSION } from '../src/utils/version.js';
 
 import { buildPhase, PHASES, type PhaseKey } from './dev-ui-fixtures.js';
 
-const VERSION = '0.3.0-dev';
-
 interface CliArgs {
   mode: 'usage' | 'phase' | 'tour';
   phase?: PhaseKey;