@slats/claude-assets-sync 0.3.2 → 0.3.3

package/README.md

@@ -4,7 +4,7 @@ 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 each consumer's metadata, compares its 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.
 
 `--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`.
 
@@ -21,22 +21,45 @@ 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 -p @slats/claude-assets-sync inject-claude-settings --package=@canard/schema-form --scope=user
+npx @slats/claude-assets-sync --package=@canard/schema-form --scope=user
 
 # Scope alias — every installed @winglet/* that declares claude.assetPath:
-npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet --scope=user
+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
+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.** Repeatable/comma-separable. Accepts `@scope/pkg`, `pkg`, or a scope alias `@scope` (fans out to every installed `node_modules/@scope/*` with `claude.assetPath`). |
@@ -89,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.2"
+    "version": "0.3.3"
   },
-  "generatedAt": "2026-04-24T17:08:31.012Z",
+  "generatedAt": "2026-04-26T11:57:30.854Z",
   "algorithm": "sha256",
   "assetRoot": "docs/claude",
   "files": {

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

@@ -23,7 +23,7 @@ async function resolveScopeAlias(scope, rootCwd) {
     }
     const resolved = [];
     for (const name of matchedNames) {
-        const meta = await resolvePackage(name, { skipMissingAsset: true });
+        const meta = await resolvePackage(name, { skipMissingAsset: true }, rootCwd);
         if (meta)
             resolved.push(meta);
     }

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/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.2";
+export declare const VERSION = "0.3.3";

package/dist/utils/version.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slats/claude-assets-sync",
-  "version": "0.3.2",
+  "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"
   },