@stoneforge/quarry 0.1.0

package/dist/cli/parser.js

@@ -0,0 +1,256 @@
+/**
+ * CLI Argument Parser
+ *
+ * Parses command-line arguments into structured command and options.
+ */
+import { DEFAULT_GLOBAL_OPTIONS } from './types.js';
+// ============================================================================
+// Shell Escape Handling
+// ============================================================================
+/**
+ * Unescapes common shell escape sequences that shells may add.
+ *
+ * Shells like bash and zsh often escape exclamation marks (!) with backslashes
+ * to disable history expansion. When running commands through nested shells or
+ * through tools like Claude Code, multiple layers of escaping can occur,
+ * resulting in sequences like \\! or even \\\\!
+ *
+ * This function removes those unnecessary escapes to provide the expected user input.
+ *
+ * @param value - The string value to unescape
+ * @returns The unescaped string
+ */
+export function unescapeShellArtifacts(value) {
+    // Unescape any sequence of one or more backslashes followed by exclamation mark
+    // to just the exclamation mark. This handles:
+    // - \! -> !  (single escape from shell history expansion)
+    // - \\! -> ! (double escape from nested shells)
+    // - \\\\! -> ! (quadruple escape from multiple layers)
+    return value.replace(/\\+!/g, '!');
+}
+// ============================================================================
+// Global Option Definitions
+// ============================================================================
+const GLOBAL_OPTIONS = {
+    '--db': { hasValue: true, key: 'db' },
+    '--actor': { hasValue: true, key: 'actor' },
+    '--from': { hasValue: true, key: 'actor' }, // Alias for --actor
+    '--sign-key': { hasValue: true, key: 'signKey' },
+    '--sign-key-file': { hasValue: true, key: 'signKeyFile' },
+    '--json': { key: 'json' },
+    '--quiet': { short: '-q', key: 'quiet' },
+    '--verbose': { short: '-v', key: 'verbose' },
+    '--help': { short: '-h', key: 'help' },
+    '--version': { short: '-V', key: 'version' },
+};
+// Build reverse lookup for short options
+const SHORT_TO_LONG = {};
+for (const [long, def] of Object.entries(GLOBAL_OPTIONS)) {
+    if (def.short) {
+        SHORT_TO_LONG[def.short] = long;
+    }
+}
+// ============================================================================
+// Parse Function
+// ============================================================================
+/**
+ * Parses command-line arguments
+ *
+ * @param argv - Raw arguments (typically process.argv.slice(2))
+ * @param commandOptions - Optional command-specific option definitions
+ * @param parserOptions - Parser options
+ * @param parserOptions.strict - If false, unknown options are skipped instead of throwing (default: true)
+ * @returns Parsed command line structure
+ */
+export function parseArgs(argv, commandOptions = [], parserOptions = {}) {
+    const { strict = true } = parserOptions;
+    const command = [];
+    const args = [];
+    const options = { ...DEFAULT_GLOBAL_OPTIONS };
+    const cmdOptions = {};
+    // Build command option lookup
+    const cmdOptDefs = {};
+    for (const opt of commandOptions) {
+        cmdOptDefs[`--${opt.name}`] = { hasValue: opt.hasValue, key: opt.name, array: opt.array };
+        if (opt.short) {
+            cmdOptDefs[`-${opt.short}`] = { hasValue: opt.hasValue, key: opt.name, array: opt.array };
+        }
+        // Set defaults
+        if (opt.defaultValue !== undefined) {
+            cmdOptions[opt.name] = opt.defaultValue;
+        }
+    }
+    let i = 0;
+    let parsingOptions = true;
+    while (i < argv.length) {
+        const arg = argv[i];
+        // -- stops option parsing, remaining args are positional
+        if (arg === '--') {
+            i++;
+            // Add all remaining arguments as positional args
+            while (i < argv.length) {
+                args.push(unescapeShellArtifacts(argv[i]));
+                i++;
+            }
+            break;
+        }
+        // Options
+        if (parsingOptions && arg.startsWith('-')) {
+            // Handle combined short options (e.g., -qv)
+            if (arg.length > 2 && arg[1] !== '-' && !arg.includes('=')) {
+                // Expand combined short options
+                const shorts = arg.slice(1).split('');
+                for (const s of shorts) {
+                    const shortOpt = `-${s}`;
+                    const longOpt = SHORT_TO_LONG[shortOpt];
+                    if (longOpt) {
+                        const def = GLOBAL_OPTIONS[longOpt];
+                        if (!def.hasValue) {
+                            options[def.key] = true;
+                        }
+                    }
+                }
+                i++;
+                continue;
+            }
+            // Handle --option=value syntax
+            let optName = arg;
+            let optValue;
+            const eqIndex = arg.indexOf('=');
+            if (eqIndex !== -1) {
+                optName = arg.slice(0, eqIndex);
+                optValue = arg.slice(eqIndex + 1);
+            }
+            // Normalize short to long
+            const normalizedOpt = SHORT_TO_LONG[optName] || optName;
+            // Check global options
+            const globalDef = GLOBAL_OPTIONS[normalizedOpt];
+            if (globalDef) {
+                if (globalDef.hasValue) {
+                    const value = optValue ?? argv[++i];
+                    if (value === undefined || value.startsWith('-')) {
+                        throw new Error(`Option ${optName} requires a value`);
+                    }
+                    options[globalDef.key] = unescapeShellArtifacts(value);
+                }
+                else {
+                    options[globalDef.key] = true;
+                }
+                i++;
+                continue;
+            }
+            // Check command-specific options
+            const cmdDef = cmdOptDefs[optName];
+            if (cmdDef) {
+                if (cmdDef.hasValue) {
+                    const value = optValue ?? argv[++i];
+                    if (value === undefined || (value.startsWith('-') && value !== '-')) {
+                        throw new Error(`Option ${optName} requires a value`);
+                    }
+                    const unescapedValue = unescapeShellArtifacts(value);
+                    if (cmdDef.array) {
+                        // Accumulate values into an array for array options
+                        const existing = cmdOptions[cmdDef.key];
+                        if (Array.isArray(existing)) {
+                            existing.push(unescapedValue);
+                        }
+                        else {
+                            cmdOptions[cmdDef.key] = [unescapedValue];
+                        }
+                    }
+                    else {
+                        cmdOptions[cmdDef.key] = unescapedValue;
+                    }
+                }
+                else {
+                    cmdOptions[cmdDef.key] = true;
+                }
+                i++;
+                continue;
+            }
+            // Unknown option
+            if (strict) {
+                throw new Error(`Unknown option: ${optName}`);
+            }
+            // In non-strict mode, skip unknown options (and their values if using = syntax)
+            i++;
+            continue;
+        }
+        // Commands and positional arguments
+        // First non-option args are commands/subcommands, subsequent are positional args
+        // Once we've started collecting positional args, don't add more to command path
+        if ((command.length === 0 || isSubcommand(arg)) && args.length === 0) {
+            command.push(arg);
+        }
+        else {
+            args.push(unescapeShellArtifacts(arg));
+        }
+        i++;
+    }
+    return { command, args, options, commandOptions: cmdOptions };
+}
+/**
+ * Checks if an argument looks like a subcommand (not an ID or path)
+ */
+function isSubcommand(arg) {
+    // Element IDs start with 'el-'
+    if (arg.startsWith('el-'))
+        return false;
+    // Paths contain slashes
+    if (arg.includes('/'))
+        return false;
+    // Numbers are not subcommands
+    if (/^\d+$/.test(arg))
+        return false;
+    // Otherwise likely a subcommand
+    return true;
+}
+// ============================================================================
+// Option Validation
+// ============================================================================
+/**
+ * Validates that required options are present
+ */
+export function validateRequiredOptions(commandOptions, definitions) {
+    for (const opt of definitions) {
+        if (opt.required && commandOptions[opt.name] === undefined) {
+            throw new Error(`Required option --${opt.name} is missing`);
+        }
+    }
+}
+// ============================================================================
+// Help Text Generation
+// ============================================================================
+/**
+ * Generates help text for global options
+ */
+export function getGlobalOptionsHelp() {
+    return `Global Options:
+  --db <path>            Database file path
+  --actor <name>         Actor name for operations
+  --from <name>          Alias for --actor
+  --sign-key <key>       Private key for signing (base64 PKCS8)
+  --sign-key-file <path> Path to file containing private key
+  --json                 Output in JSON format
+  -q, --quiet            Minimal output (IDs only)
+  -v, --verbose          Enable debug output
+  -h, --help             Show help
+  -V, --version          Show version`;
+}
+/**
+ * Generates help text for command-specific options
+ */
+export function getCommandOptionsHelp(options) {
+    if (options.length === 0)
+        return '';
+    const lines = ['Command Options:'];
+    for (const opt of options) {
+        const shortPart = opt.short ? `-${opt.short}, ` : '    ';
+        const valuePart = opt.hasValue ? ` <${opt.name}>` : '';
+        const requiredPart = opt.required ? ' (required)' : '';
+        lines.push(`  ${shortPart}--${opt.name}${valuePart}${requiredPart}`);
+        lines.push(`        ${opt.description}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=parser.js.map

package/dist/cli/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"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"}

package/dist/cli/plugin-loader.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CLI Plugin Loader
+ *
+ * Discovers and loads CLI plugins from known packages and user configuration.
+ *
+ * Discovery strategies:
+ * 1. Known packages: Auto-detect first-party packages (e.g., @stoneforge/smithy)
+ * 2. Config-based: User-specified packages in .stoneforge/config.yaml plugins.packages
+ */
+import type { PluginsConfig, PluginDiscoveryResult } from './plugin-types.js';
+/**
+ * Gets the list of known plugin packages
+ */
+export declare function getKnownPluginPackages(): readonly string[];
+/**
+ * Options for plugin discovery
+ */
+export interface DiscoverPluginsOptions {
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Discovers and loads all plugins from known packages and config.
+ *
+ * @param config - Optional user plugin configuration
+ * @param options - Discovery options
+ * @returns Discovery result with loaded plugins and status
+ */
+export declare function discoverPlugins(config?: PluginsConfig, options?: DiscoverPluginsOptions): Promise<PluginDiscoveryResult>;
+/**
+ * Logs warnings for failed plugin loads.
+ *
+ * @param result - Discovery result
+ * @param options - Logging options
+ */
+export declare function logPluginWarnings(result: PluginDiscoveryResult, options?: {
+    verbose?: boolean;
+}): void;
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/cli/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../src/cli/plugin-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEV,aAAa,EACb,qBAAqB,EAEtB,MAAM,mBAAmB,CAAC;AAa3B;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,MAAM,EAAE,CAE1D;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,CAAC,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAoChC;AA+FD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9B,IAAI,CAmBN"}

package/dist/cli/plugin-loader.js

@@ -0,0 +1,165 @@
+/**
+ * CLI Plugin Loader
+ *
+ * Discovers and loads CLI plugins from known packages and user configuration.
+ *
+ * Discovery strategies:
+ * 1. Known packages: Auto-detect first-party packages (e.g., @stoneforge/smithy)
+ * 2. Config-based: User-specified packages in .stoneforge/config.yaml plugins.packages
+ */
+import { isValidCLIPlugin } from './plugin-types.js';
+// ============================================================================
+// Known Plugin Packages
+// ============================================================================
+/**
+ * First-party packages that are automatically discovered if installed.
+ * These are tried silently - if not installed, they're skipped without warning.
+ */
+const KNOWN_PLUGIN_PACKAGES = ['@stoneforge/smithy'];
+/**
+ * Gets the list of known plugin packages
+ */
+export function getKnownPluginPackages() {
+    return KNOWN_PLUGIN_PACKAGES;
+}
+/**
+ * Discovers and loads all plugins from known packages and config.
+ *
+ * @param config - Optional user plugin configuration
+ * @param options - Discovery options
+ * @returns Discovery result with loaded plugins and status
+ */
+export async function discoverPlugins(config, options) {
+    const verbose = options?.verbose ?? false;
+    // Combine known packages with user-configured packages (deduplicated)
+    const allPackages = new Set([
+        ...KNOWN_PLUGIN_PACKAGES,
+        ...(config?.packages ?? []),
+    ]);
+    // Load all plugins in parallel
+    const loadPromises = Array.from(allPackages).map((pkg) => loadPlugin(pkg, verbose));
+    const results = await Promise.all(loadPromises);
+    // Categorize results
+    const plugins = [];
+    const notFoundPackages = [];
+    const failedPackages = [];
+    for (const result of results) {
+        if (result.success && result.plugin) {
+            plugins.push(result.plugin);
+        }
+        else if (result.notFound) {
+            notFoundPackages.push(result.packageName);
+        }
+        else {
+            failedPackages.push(result.packageName);
+        }
+    }
+    return {
+        plugins,
+        results,
+        notFoundPackages,
+        failedPackages,
+    };
+}
+/**
+ * Attempts to load a plugin from a package.
+ *
+ * @param packageName - Package to load
+ * @param verbose - Enable verbose logging
+ * @returns Load result
+ */
+async function loadPlugin(packageName, verbose) {
+    try {
+        // Try to import the package
+        const module = await import(packageName);
+        // Look for cliPlugin export
+        const plugin = module.cliPlugin;
+        if (!plugin) {
+            // Package exists but doesn't export cliPlugin - silent skip
+            if (verbose) {
+                console.error(`[plugin] ${packageName}: no cliPlugin export found`);
+            }
+            return {
+                packageName,
+                success: false,
+                notFound: true, // Treat as "not a plugin package"
+            };
+        }
+        // Validate plugin structure
+        if (!isValidCLIPlugin(plugin)) {
+            return {
+                packageName,
+                success: false,
+                error: 'Invalid plugin structure',
+            };
+        }
+        if (verbose) {
+            console.error(`[plugin] Loaded ${plugin.name}@${plugin.version}`);
+        }
+        return {
+            packageName,
+            success: true,
+            plugin,
+        };
+    }
+    catch (err) {
+        // Check if it's a "module not found" error
+        const isNotFound = isModuleNotFoundError(err, packageName);
+        if (isNotFound) {
+            return {
+                packageName,
+                success: false,
+                notFound: true,
+            };
+        }
+        // Actual load error
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        return {
+            packageName,
+            success: false,
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Checks if an error is a "module not found" error for the given package.
+ */
+function isModuleNotFoundError(err, packageName) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    // Node.js ERR_MODULE_NOT_FOUND
+    const errCode = err.code;
+    if (errCode === 'ERR_MODULE_NOT_FOUND') {
+        // Make sure it's for the specific package, not a transitive dependency
+        return err.message.includes(packageName);
+    }
+    // CommonJS MODULE_NOT_FOUND
+    if (errCode === 'MODULE_NOT_FOUND') {
+        return err.message.includes(packageName);
+    }
+    return false;
+}
+/**
+ * Logs warnings for failed plugin loads.
+ *
+ * @param result - Discovery result
+ * @param options - Logging options
+ */
+export function logPluginWarnings(result, options) {
+    const verbose = options?.verbose ?? false;
+    // Log warnings for packages that failed to load (not just "not found")
+    for (const loadResult of result.results) {
+        if (!loadResult.success && !loadResult.notFound && loadResult.error) {
+            console.error(`[plugin] Warning: Failed to load ${loadResult.packageName}: ${loadResult.error}`);
+        }
+    }
+    // In verbose mode, also report on successful loads
+    if (verbose && result.plugins.length > 0) {
+        const pluginList = result.plugins
+            .map((p) => `${p.name}@${p.version}`)
+            .join(', ');
+        console.error(`[plugin] Loaded plugins: ${pluginList}`);
+    }
+}
+//# sourceMappingURL=plugin-loader.js.map

package/dist/cli/plugin-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.js","sourceRoot":"","sources":["../../src/cli/plugin-loader.ts"],"names":[],"mappings":"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"}

package/dist/cli/plugin-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CLI Plugin Registry
+ *
+ * Handles registration of plugin commands and aliases with conflict detection.
+ * Built-in commands always take precedence over plugin commands.
+ */
+import type { CLIPlugin, PluginRegistrationResult } from './plugin-types.js';
+/**
+ * Options for command registration
+ */
+export interface RegisterPluginOptions {
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Registers all commands and aliases from a single plugin.
+ *
+ * Built-in commands always take precedence - plugin commands that conflict
+ * with existing commands are skipped with a warning.
+ *
+ * @param plugin - The plugin to register
+ * @param options - Registration options
+ * @returns Registration result
+ */
+export declare function registerPluginCommands(plugin: CLIPlugin, options?: RegisterPluginOptions): PluginRegistrationResult;
+/**
+ * Registers all plugins' commands and aliases.
+ *
+ * Plugins are registered in order, so earlier plugins take precedence
+ * for command names. Built-in commands always take precedence over all plugins.
+ *
+ * @param plugins - Plugins to register
+ * @param options - Registration options
+ * @returns Array of registration results
+ */
+export declare function registerAllPlugins(plugins: CLIPlugin[], options?: RegisterPluginOptions): Promise<PluginRegistrationResult[]>;
+/**
+ * Logs conflict warnings from registration results.
+ *
+ * @param results - Registration results to check for conflicts
+ */
+export declare function logConflictWarnings(results: PluginRegistrationResult[]): void;
+/**
+ * Gets a summary of registered plugin commands for the help menu.
+ *
+ * @param results - Registration results
+ * @returns Map of plugin name to registered command names
+ */
+export declare function getPluginCommandSummary(results: PluginRegistrationResult[]): Map<string, string[]>;
+//# sourceMappingURL=plugin-registry.d.ts.map

package/dist/cli/plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../src/cli/plugin-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,wBAAwB,EAAoD,MAAM,mBAAmB,CAAC;AAQ/H;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA2CD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,wBAAwB,CA0G1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,SAAS,EAAE,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAoBrC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,wBAAwB,EAAE,GAAG,IAAI,CAsB7E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,EAAE,GAClC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUvB"}