@slats/claude-assets-sync 0.1.3 → 0.2.0

package/dist/index.cjs

@@ -1,14 +1,20 @@
 'use strict';
 
-var sync = require('./core/sync.cjs');
-var cli = require('./core/cli.cjs');
-var migration = require('./core/migration.cjs');
+var runCli = require('./commands/runCli/runCli.cjs');
+require('node:crypto');
+require('node:fs/promises');
+var hashManifest = require('./core/hashManifest/hashManifest.cjs');
+var injectDocs = require('./core/injectDocs/injectDocs.cjs');
+require('node:path');
+var scope = require('./core/scope/scope.cjs');
 
 
 
-exports.syncPackage = sync.syncPackage;
-exports.syncPackages = sync.syncPackages;
-exports.createProgram = cli.createProgram;
-exports.run = cli.run;
-exports.migrateToFlat = migration.migrateToFlat;
-exports.needsMigration = migration.needsMigration;
+exports.runCli = runCli.runCli;
+exports.HASH_MANIFEST_FILENAME = hashManifest.HASH_MANIFEST_FILENAME;
+exports.computeNamespacePrefixes = hashManifest.computeNamespacePrefixes;
+exports.readHashManifest = hashManifest.readHashManifest;
+exports.injectDocs = injectDocs.injectDocs;
+exports.isInteractive = scope.isInteractive;
+exports.isValidScope = scope.isValidScope;
+exports.resolveScope = scope.resolveScope;

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-export { syncPackage, syncPackages } from './core/sync';
-export { createProgram, run } from './core/cli.js';
-export { migrateToFlat, needsMigration } from './core/migration';
-export type { MigrationResult } from './core/migration';
-export type { AssetType, CliOptions, ClaudeConfig, GitHubRepoInfo, PackageInfo, SyncMeta, SyncResult, UnifiedSyncMeta, PackageSyncInfo, FileMapping, } from './utils/types';
+export { runCli, type RunCliOptions } from './commands/index.js';
+export { HASH_MANIFEST_FILENAME, computeNamespacePrefixes, injectDocs, isInteractive, isValidScope, readHashManifest, resolveScope, type HashManifest, type InjectOptions, type InjectReport, type Scope, type ScopeResolution, } from './core/index.js';
+export type { AssetType } from './utils/types.js';

package/dist/index.mjs

@@ -1,3 +1,7 @@
-export { syncPackage, syncPackages } from './core/sync.mjs';
-export { createProgram, run } from './core/cli.mjs';
-export { migrateToFlat, needsMigration } from './core/migration.mjs';
+export { runCli } from './commands/runCli/runCli.mjs';
+import 'node:crypto';
+import 'node:fs/promises';
+export { HASH_MANIFEST_FILENAME, computeNamespacePrefixes, readHashManifest } from './core/hashManifest/hashManifest.mjs';
+export { injectDocs } from './core/injectDocs/injectDocs.mjs';
+import 'node:path';
+export { isInteractive, isValidScope, resolveScope } from './core/scope/scope.mjs';

package/dist/prompts/confirmForce.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+var prompts = require('@inquirer/prompts');
+var pc = require('picocolors');
+
+async function confirmForceAsync(divergedCount, orphanCount, relPaths) {
+    const extra = Math.max(0, divergedCount + orphanCount - relPaths.length);
+    const divergedPart = pc.red(pc.bold(`${divergedCount} diverged file(s)`));
+    const orphanPart = orphanCount > 0
+        ? ` and ${pc.red(pc.bold(`delete ${orphanCount} orphan(s)`))}`
+        : '';
+    process.stderr.write(`${pc.yellow(pc.bold('!'))} This will overwrite ${divergedPart}${orphanPart}:\n`);
+    for (const p of relPaths) {
+        process.stderr.write(`  ${pc.dim('-')} ${p}\n`);
+    }
+    if (extra > 0) {
+        process.stderr.write(`  ${pc.dim(`... and ${extra} more`)}\n`);
+    }
+    process.stderr.write('\n');
+    const answer = await prompts.confirm({
+        message: pc.bold('Do you have these in git? Proceed?'),
+        default: false,
+    });
+    return answer;
+}
+
+exports.confirmForceAsync = confirmForceAsync;

package/dist/prompts/confirmForce.d.ts

@@ -0,0 +1 @@
+export declare function confirmForceAsync(divergedCount: number, orphanCount: number, relPaths: string[]): Promise<boolean>;

package/dist/prompts/confirmForce.mjs

@@ -0,0 +1,25 @@
+import { confirm } from '@inquirer/prompts';
+import pc from 'picocolors';
+
+async function confirmForceAsync(divergedCount, orphanCount, relPaths) {
+    const extra = Math.max(0, divergedCount + orphanCount - relPaths.length);
+    const divergedPart = pc.red(pc.bold(`${divergedCount} diverged file(s)`));
+    const orphanPart = orphanCount > 0
+        ? ` and ${pc.red(pc.bold(`delete ${orphanCount} orphan(s)`))}`
+        : '';
+    process.stderr.write(`${pc.yellow(pc.bold('!'))} This will overwrite ${divergedPart}${orphanPart}:\n`);
+    for (const p of relPaths) {
+        process.stderr.write(`  ${pc.dim('-')} ${p}\n`);
+    }
+    if (extra > 0) {
+        process.stderr.write(`  ${pc.dim(`... and ${extra} more`)}\n`);
+    }
+    process.stderr.write('\n');
+    const answer = await confirm({
+        message: pc.bold('Do you have these in git? Proceed?'),
+        default: false,
+    });
+    return answer;
+}
+
+export { confirmForceAsync };

package/dist/prompts/index.d.ts

@@ -0,0 +1,2 @@
+export { selectScopeAsync } from './selectScope.js';
+export { confirmForceAsync } from './confirmForce.js';

package/dist/prompts/selectScope.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+var prompts = require('@inquirer/prompts');
+var pc = require('picocolors');
+
+const CHOICES = [
+    {
+        name: 'user',
+        value: 'user',
+        description: '~/.claude (applies globally to every project)',
+    },
+    {
+        name: 'project',
+        value: 'project',
+        description: 'nearest ancestor .claude (or <cwd>/.claude)',
+    },
+];
+async function selectScopeAsync() {
+    const answer = await prompts.select({
+        message: pc.bold(pc.cyan('Select injection scope:')),
+        choices: CHOICES.map((c) => ({
+            name: c.name,
+            value: c.value,
+            description: pc.dim(c.description),
+        })),
+    });
+    return answer;
+}
+
+exports.selectScopeAsync = selectScopeAsync;

package/dist/prompts/selectScope.d.ts

@@ -0,0 +1,2 @@
+import type { Scope } from '../core/scope/index.js';
+export declare function selectScopeAsync(): Promise<Scope>;

package/dist/prompts/selectScope.mjs

@@ -0,0 +1,28 @@
+import { select } from '@inquirer/prompts';
+import pc from 'picocolors';
+
+const CHOICES = [
+    {
+        name: 'user',
+        value: 'user',
+        description: '~/.claude (applies globally to every project)',
+    },
+    {
+        name: 'project',
+        value: 'project',
+        description: 'nearest ancestor .claude (or <cwd>/.claude)',
+    },
+];
+async function selectScopeAsync() {
+    const answer = await select({
+        message: pc.bold(pc.cyan('Select injection scope:')),
+        choices: CHOICES.map((c) => ({
+            name: c.name,
+            value: c.value,
+            description: pc.dim(c.description),
+        })),
+    });
+    return answer;
+}
+
+export { selectScopeAsync };

package/dist/utils/heartbeat.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+var pc = require('picocolors');
+
+function startHeartbeat(options = {}) {
+    const intervalMs = options.intervalMs ?? 500;
+    const label = options.label ?? 'working';
+    const emit = options.emit ??
+        ((line) => {
+            process.stderr.write(line);
+        });
+    const startedAt = Date.now();
+    const timer = setInterval(() => {
+        const elapsedMs = Date.now() - startedAt;
+        const seconds = (elapsedMs / 1000).toFixed(1);
+        emit(`${pc.dim(`[${seconds}s]`)} ${pc.cyan(`${label}...`)}\n`);
+    }, intervalMs);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    return () => {
+        clearInterval(timer);
+    };
+}
+
+exports.startHeartbeat = startHeartbeat;

package/dist/utils/heartbeat.d.ts

@@ -0,0 +1,16 @@
+export interface HeartbeatOptions {
+    intervalMs?: number;
+    emit?: (line: string) => void;
+    label?: string;
+}
+export type StopHeartbeat = () => void;
+/**
+ * Wall-clock heartbeat ticker for long-running async operations.
+ *
+ * Wraps operations at the command layer (NOT core) to provide in-flight
+ * visibility when stdout is quiet for several hundred milliseconds.
+ *
+ * The emitted line is written via the provided `emit` (default: stderr) so
+ * it never interferes with programmatic stdout output.
+ */
+export declare function startHeartbeat(options?: HeartbeatOptions): StopHeartbeat;

package/dist/utils/heartbeat.mjs

@@ -0,0 +1,23 @@
+import pc from 'picocolors';
+
+function startHeartbeat(options = {}) {
+    const intervalMs = options.intervalMs ?? 500;
+    const label = options.label ?? 'working';
+    const emit = options.emit ??
+        ((line) => {
+            process.stderr.write(line);
+        });
+    const startedAt = Date.now();
+    const timer = setInterval(() => {
+        const elapsedMs = Date.now() - startedAt;
+        const seconds = (elapsedMs / 1000).toFixed(1);
+        emit(`${pc.dim(`[${seconds}s]`)} ${pc.cyan(`${label}...`)}\n`);
+    }, intervalMs);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    return () => {
+        clearInterval(timer);
+    };
+}
+
+export { startHeartbeat };

package/dist/utils/logger.cjs

@@ -62,6 +62,13 @@ const logger = {
         console.log(pc.yellow(pc.bold('[DRY RUN] No files will be created or modified.')));
         console.log();
     },
+    heading(message) {
+        console.log();
+        console.log(pc.bold(pc.cyan(`▸ ${message}`)));
+    },
+    accent(message) {
+        return pc.cyan(pc.bold(message));
+    },
 };
 
 exports.logger = logger;

package/dist/utils/logger.d.ts

@@ -54,4 +54,12 @@ export declare const logger: {
      * Log dry-run notice
      */
     dryRunNotice(): void;
+    /**
+     * Top-level section heading with a distinct accent.
+     */
+    heading(message: string): void;
+    /**
+     * Inline accent — cyan bold, for short labels interleaved with content.
+     */
+    accent(message: string): string;
 };

package/dist/utils/logger.mjs

@@ -60,6 +60,13 @@ const logger = {
         console.log(pc.yellow(pc.bold('[DRY RUN] No files will be created or modified.')));
         console.log();
     },
+    heading(message) {
+        console.log();
+        console.log(pc.bold(pc.cyan(`▸ ${message}`)));
+    },
+    accent(message) {
+        return pc.cyan(pc.bold(message));
+    },
 };
 
 export { logger };

package/dist/utils/types.d.ts

@@ -1,252 +1 @@
-/**
- * Asset structure type (nested or flat)
- */
-export type AssetStructure = 'nested' | 'flat';
-/**
- * Configuration for a specific asset type
- */
-export interface AssetTypeConfig {
-    structure: AssetStructure;
-}
-/**
- * Configuration mapping asset types to their structure
- */
-export interface AssetsConfig {
-    [assetType: string]: AssetTypeConfig;
-}
-/**
- * Claude configuration in package.json
- */
-export interface ClaudeConfig {
-    /** Path to Claude assets directory (e.g., "docs/claude") */
-    assetPath: string;
-    /** Optional configuration for asset types */
-    assets?: AssetsConfig;
-}
-/**
- * Repository information from package.json
- */
-export interface RepositoryInfo {
-    type: string;
-    url: string;
-    directory?: string;
-}
-/**
- * Parsed package information
- */
-export interface PackageInfo {
-    name: string;
-    version: string;
-    repository: RepositoryInfo;
-    claude?: ClaudeConfig;
-}
-/**
- * Parsed GitHub repository details
- */
-export interface GitHubRepoInfo {
-    owner: string;
-    repo: string;
-    directory?: string;
-}
-/**
- * GitHub API file/directory entry
- */
-export interface GitHubEntry {
-    name: string;
-    path: string;
-    type: 'file' | 'dir';
-    download_url: string | null;
-    sha: string;
-}
-/**
- * Sync metadata stored in .sync-meta.json
- */
-export interface SyncMeta {
-    /** Package version at sync time */
-    version: string;
-    /** ISO timestamp of last sync */
-    syncedAt: string;
-    /** List of synced file names */
-    files: string[];
-}
-/**
- * Asset type (can be any string, not limited to commands/skills/agents)
- */
-export type AssetType = string;
-/**
- * Sync result for a single package
- */
-export interface SyncResult {
-    packageName: string;
-    success: boolean;
-    skipped: boolean;
-    reason?: string;
-    syncedFiles?: Record<string, string[]>;
-}
-/**
- * CLI options
- */
-export interface CliOptions {
-    package: string[];
-    force: boolean;
-    dryRun: boolean;
-    local: boolean;
-    /** Custom git ref (branch, tag, or commit) to fetch from */
-    ref?: string;
-    /** Use flat structure (default: true in v2) */
-    flat?: boolean;
-}
-/**
- * Workspace info from yarn workspaces
- */
-export interface WorkspaceInfo {
-    name: string;
-    location: string;
-}
-/**
- * Unified sync metadata for all packages (flat structure)
- */
-export interface UnifiedSyncMeta {
-    /** Schema version for migration support */
-    schemaVersion: string;
-    /** Last sync timestamp */
-    syncedAt: string;
-    /** Package metadata keyed by transformed name (e.g., "canard-schemaForm") */
-    packages: Record<string, PackageSyncInfo>;
-    /** SkillUnit format version marker. Present when data uses SkillUnit[] format. */
-    skillUnitFormat?: string;
-}
-/**
- * Individual package sync info within unified meta
- */
-export interface PackageSyncInfo {
-    /** Original package name (e.g., "@canard/schema-form") */
-    originalName: string;
-    /** Package version at sync time */
-    version: string;
-    /** Whether this package is from local workspace (true) or remote npm (false/undefined) */
-    local?: boolean;
-    /** Synced skill units per asset type. Each entry is a SkillUnit (atomic unit of selection). */
-    files: Record<string, SkillUnit[]>;
-    /** Optional exclusions for selective syncing */
-    exclusions?: {
-        /** Excluded directory paths (e.g., ["skills/deprecated"]) */
-        directories: string[];
-        /** Excluded file paths (e.g., ["commands/old-cmd.md"]) */
-        files: string[];
-    };
-}
-/**
- * File name mapping (original to transformed)
- */
-export interface FileMapping {
-    /** Original file name (e.g., "guide.md") */
-    original: string;
-    /** Transformed file name (e.g., "canard-schemaForm_guide.md") */
-    transformed: string;
-}
-/**
- * Represents an atomic skill unit in sync metadata.
- * A skill unit is either a single .md file or a directory skill (containing SKILL.md).
- */
-export interface SkillUnit {
-    /** Skill name (file name without extension, or directory name) */
-    name: string;
-    /** Whether this is a directory-based skill */
-    isDirectory: boolean;
-    /** For flat structure: transformed file/directory name */
-    transformed?: string;
-    /** Internal files within directory skill (for tree browsing, not individual selection).
-     *  Only present when isDirectory is true.
-     *  Stores relative paths within the skill directory (e.g., ["SKILL.md", "knowledge/api.md"]) */
-    internalFiles?: string[];
-}
-/**
- * Add command selection result
- */
-export interface AddCommandSelection {
-    /** Package name */
-    packageName: string;
-    /** Source type */
-    source: 'local' | 'npm';
-    /** Git ref (branch, tag, or commit) */
-    ref?: string;
-    /** Included skill units by asset type (skill unit names, not individual file paths) */
-    includedAssets: Record<string, string[]>;
-    /** Excluded skill units by asset type (skill unit names, not individual file paths) */
-    excludedAssets: Record<string, string[]>;
-}
-/**
- * Tree node for asset selection
- */
-export interface TreeNode {
-    /** Unique identifier */
-    id: string;
-    /** Node label */
-    label: string;
-    /** Full path */
-    path: string;
-    /** Node type */
-    type: 'directory' | 'file' | 'skill-directory';
-    /** Child nodes */
-    children?: TreeNode[];
-    /** Selection state */
-    selected: boolean;
-    /** Expanded state */
-    expanded: boolean;
-    /** Disabled state */
-    disabled?: boolean;
-    /** If true, this node's children are view-only (cannot be individually selected) */
-    viewOnly?: boolean;
-    /** Additional metadata */
-    metadata?: {
-        assetType: string;
-        originalName?: string;
-        transformedName?: string;
-    };
-}
-/**
- * Re-export asset structure utilities from core module
- *
- * @deprecated These exports are kept for backward compatibility only.
- * Please update your imports to use the recommended paths below.
- *
- * Migration Guide:
- * ================
- *
- * ❌ OLD (Deprecated - will be removed in v1.0.0)
- * ```typescript
- * import {
- *   DEFAULT_ASSET_TYPES,
- *   DEFAULT_ASSET_STRUCTURES,
- *   getAssetStructure,
- *   detectStructureType,
- *   validateAssetStructure,
- *   normalizeAssetStructure,
- * } from './utils/types';
- * ```
- *
- * ✅ NEW (Recommended)
- * ```typescript
- * import {
- *   DEFAULT_ASSET_TYPES,
- *   DEFAULT_ASSET_STRUCTURES,
- *   getAssetStructure,
- *   detectStructureType,
- *   validateAssetStructure,
- *   normalizeAssetStructure,
- * } from './core/assetStructure';
- * ```
- *
- * Why the change?
- * - Clearer module organization (asset structure logic lives in core/)
- * - Direct imports are more maintainable and tree-shake friendly
- * - Reduces coupling between utils and core modules
- *
- * Timeline:
- * - v0.x: Old imports work (with deprecation warnings)
- * - v1.0.0: Re-exports removed
- *
- * @see ../core/assetStructure for the actual implementations
- */
-export { DEFAULT_ASSET_TYPES, DEFAULT_ASSET_STRUCTURES, getAssetStructure, detectStructureType, validateAssetStructure, normalizeAssetStructure, } from '../core/assetStructure';
+export type AssetType = 'skills' | 'commands' | 'rules' | string;

package/dist/utils/version.cjs

@@ -1,17 +1,5 @@
 'use strict';
 
-function compareVersions(v1, v2) {
-    return v1 === v2;
-}
-function needsVersionSync(currentVersion, syncedVersion) {
-    if (syncedVersion === undefined) {
-        return true;
-    }
-    if (currentVersion === '' || syncedVersion === '') {
-        return true;
-    }
-    return !compareVersions(currentVersion, syncedVersion);
-}
+const VERSION = '0.2.0';
 
-exports.compareVersions = compareVersions;
-exports.needsVersionSync = needsVersionSync;
+exports.VERSION = VERSION;

package/dist/utils/version.d.ts

@@ -1,55 +1,5 @@
 /**
- * Version comparison utilities
- *
- * These functions provide exact string-based version comparison
- * for semantic versioning with pre-release and build metadata support.
+ * Current package version from package.json
+ * Automatically synchronized during build process
  */
-/**
- * Compare two semantic versions for exact equality
- *
- * Performs case-sensitive exact string comparison of version strings.
- * Supports semver format including pre-release and build metadata:
- * - Major.Minor.Patch (e.g., "1.2.3")
- * - Pre-release (e.g., "1.0.0-alpha", "1.0.0-rc.1")
- * - Build metadata (e.g., "1.0.0+build.123")
- * - Combined (e.g., "1.0.0-rc.1+build.456")
- *
- * @param v1 - First version string
- * @param v2 - Second version string
- * @returns true if versions are exactly equal (case-sensitive)
- *
- * @example
- * compareVersions('1.0.0', '1.0.0') // true
- * compareVersions('1.0.0', '1.0.1') // false
- * compareVersions('1.0.0-alpha', '1.0.0-Alpha') // false (case-sensitive)
- * compareVersions('1.0.0+build.1', '1.0.0+build.1') // true
- */
-export declare function compareVersions(v1: string, v2: string): boolean;
-/**
- * Check if version synchronization is needed
- *
- * Determines whether assets need to be re-synced based on version comparison.
- * Sync is needed in the following cases:
- * - First sync (syncedVersion is undefined)
- * - Empty version strings (currentVersion or syncedVersion is empty)
- * - Version mismatch (versions are not exactly equal)
- *
- * @param currentVersion - Current package version from package.json
- * @param syncedVersion - Previously synced version from .sync-meta.json (undefined if never synced)
- * @returns true if sync is needed, false if versions match
- *
- * @example
- * // First sync
- * needsVersionSync('1.0.0', undefined) // true
- *
- * // Version mismatch
- * needsVersionSync('1.0.1', '1.0.0') // true
- *
- * // Versions match
- * needsVersionSync('1.0.0', '1.0.0') // false
- *
- * // Empty strings
- * needsVersionSync('', '1.0.0') // true
- * needsVersionSync('1.0.0', '') // true
- */
-export declare function needsVersionSync(currentVersion: string, syncedVersion?: string): boolean;
+export declare const VERSION = "0.2.0";

package/dist/utils/version.mjs

@@ -1,14 +1,3 @@
-function compareVersions(v1, v2) {
-    return v1 === v2;
-}
-function needsVersionSync(currentVersion, syncedVersion) {
-    if (syncedVersion === undefined) {
-        return true;
-    }
-    if (currentVersion === '' || syncedVersion === '') {
-        return true;
-    }
-    return !compareVersions(currentVersion, syncedVersion);
-}
+const VERSION = '0.2.0';
 
-export { compareVersions, needsVersionSync };
+export { VERSION };

package/docs/bundle-size-decision.md

@@ -0,0 +1,36 @@
+# Phase 0 — Prompt Library Bundle-Size Decision
+
+**Gate threshold**: tree-shaken footprint for `select` + `confirm` ≤ 200 KB.
+
+## Measurement setup
+
+- Entry: `import { select, confirm } from '@inquirer/prompts'; export { select, confirm };`
+- Bundler: esbuild 0.28.0 via `yarn dlx esbuild`
+- Flags: `--bundle --format=esm --platform=node --external:node:*`
+- Measured from `packages/slats/claude-assets-sync/` with `@inquirer/prompts@^8.4.2` resolved via yarn workspaces.
+
+## Results
+
+| Variant | Size |
+|---|---|
+| Bundled + minified | **28.5 KB** (29,215 bytes) |
+| Bundled, no minify | 62.0 KB (63,522 bytes) |
+| Raw `node_modules/@inquirer` footprint | 1.6 MB (includes unused prompt families) |
+
+The minified bundle represents the realistic runtime cost after slats's Rollup build. The raw node_modules number is not representative because tree-shaking and dead-code elimination eliminate unused prompts from the published `dist/`.
+
+## Decision
+
+**Pinned**: `@inquirer/prompts@^8.4.2` in `dependencies`.
+
+**Pinned**: `@inquirer/testing@^3.3.5` in `devDependencies`.
+
+The 28.5 KB minified footprint is **7× under the 200 KB threshold**. No fallback to `@clack/prompts` needed.
+
+## Fallback plan (unused)
+
+If a future `@inquirer/prompts` major release inflates the bundle past 200 KB (e.g., new default imports that resist tree-shaking), replace with `@clack/prompts@^0.7.0` (~30 KB, zero deps) and re-run this measurement. `@clack` lacks a first-party testing kit, so `tests/prompts/*.test.ts` would need to switch to raw stdin mocking.
+
+## Artifacts
+
+Scratch files removed after measurement: `scratch-entry.mjs`, `scratch-bundle.mjs`, `scratch-bundle-raw.mjs`.