jumbo-cli 1.0.0-beta.0

package/dist/presentation/cli/shared/components/UserDetection.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * User Detection Utilities
+ *
+ * Detects first-time users vs returning users based on .jumbo directory.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFirstTimeUser = isFirstTimeUser;
+exports.isJumboProject = isJumboProject;
+exports.shouldShowAnimatedBanner = shouldShowAnimatedBanner;
+exports.getProjectName = getProjectName;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Check if this is the user's first time running Jumbo
+ * (no .jumbo directory in current working directory)
+ */
+async function isFirstTimeUser() {
+    const jumboRoot = path_1.default.join(process.cwd(), ".jumbo");
+    return !(await fs_extra_1.default.pathExists(jumboRoot));
+}
+/**
+ * Check if user is in a Jumbo project (has .jumbo directory)
+ */
+async function isJumboProject() {
+    const jumboRoot = path_1.default.join(process.cwd(), ".jumbo");
+    return await fs_extra_1.default.pathExists(jumboRoot);
+}
+/**
+ * Check if we should show the flashy animated banner
+ * - First-time users: YES (no .jumbo directory)
+ * - Returning users: NO (show static banner)
+ * - Agent mode (non-TTY): NO (suppress banner entirely)
+ */
+async function shouldShowAnimatedBanner() {
+    // Never animate in non-TTY mode
+    if (!process.stdout.isTTY) {
+        return false;
+    }
+    // Animate for first-time users
+    return await isFirstTimeUser();
+}
+/**
+ * Get the current project name if project is initialized
+ * Returns null if project doesn't exist or hasn't been initialized
+ */
+async function getProjectName() {
+    const jumboRoot = path_1.default.join(process.cwd(), ".jumbo");
+    // Quick check: does .jumbo directory exist?
+    if (!(await fs_extra_1.default.pathExists(jumboRoot))) {
+        return null;
+    }
+    try {
+        // Bootstrap infrastructure to access projection store
+        const { bootstrap } = await Promise.resolve().then(() => __importStar(require("../../../../infrastructure/composition/bootstrap.js")));
+        const container = bootstrap(jumboRoot);
+        try {
+            // Get project from projection store
+            const projectView = await container.projectContextReader.getProject();
+            // Return project name if found
+            return projectView?.name ?? null;
+        }
+        finally {
+            // Clean up database connection
+            await container.dbConnectionManager.dispose();
+        }
+    }
+    catch (error) {
+        // If any error occurs (db not found, table doesn't exist, etc.), return null
+        return null;
+    }
+}
+//# sourceMappingURL=UserDetection.js.map

package/dist/presentation/cli/shared/components/UserDetection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserDetection.js","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/components/UserDetection.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASH,0CAGC;AAKD,wCAGC;AAQD,4DAQC;AAMD,wCA2BC;AAnED,wDAA0B;AAC1B,gDAAwB;AAExB;;;GAGG;AACI,KAAK,UAAU,eAAe;IACnC,MAAM,SAAS,GAAG,cAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;IACrD,OAAO,CAAC,CAAC,MAAM,kBAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,cAAc;IAClC,MAAM,SAAS,GAAG,cAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;IACrD,OAAO,MAAM,kBAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,wBAAwB;IAC5C,gCAAgC;IAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+BAA+B;IAC/B,OAAO,MAAM,eAAe,EAAE,CAAC;AACjC,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,cAAc;IAClC,MAAM,SAAS,GAAG,cAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;IAErD,4CAA4C;IAC5C,IAAI,CAAC,CAAC,MAAM,kBAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,sDAAsD;QACtD,MAAM,EAAE,SAAS,EAAE,GAAG,wDAAa,qDAAqD,GAAC,CAAC;QAC1F,MAAM,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QAEvC,IAAI,CAAC;YACH,oCAAoC;YACpC,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,oBAAoB,CAAC,UAAU,EAAE,CAAC;YAEtE,+BAA+B;YAC/B,OAAO,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC;QACnC,CAAC;gBAAS,CAAC;YACT,+BAA+B;YAC/B,MAAM,SAAS,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6EAA6E;QAC7E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/presentation/cli/shared/errors/ErrorFormatter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Error Formatter
+ *
+ * Consistent error formatting across all output modes.
+ * Extracts error message, stack trace, and optional error codes.
+ */
+export interface FormattedError {
+    message: string;
+    stack?: string;
+    code?: string | number;
+}
+/**
+ * Format an error for display
+ */
+export declare function formatError(error: Error | string | unknown): FormattedError;
+/**
+ * Check if an error is a "not found" type error
+ */
+export declare function isNotFoundError(error: Error | unknown): boolean;
+/**
+ * Check if an error is a validation error
+ */
+export declare function isValidationError(error: Error | unknown): boolean;
+/**
+ * Check if an error is a permission/access error
+ */
+export declare function isPermissionError(error: Error | unknown): boolean;
+//# sourceMappingURL=ErrorFormatter.d.ts.map

package/dist/presentation/cli/shared/errors/ErrorFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorFormatter.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/errors/ErrorFormatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CA4B3E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAM/D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAKjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAMjE"}

package/dist/presentation/cli/shared/errors/ErrorFormatter.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Error Formatter
+ *
+ * Consistent error formatting across all output modes.
+ * Extracts error message, stack trace, and optional error codes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatError = formatError;
+exports.isNotFoundError = isNotFoundError;
+exports.isValidationError = isValidationError;
+exports.isPermissionError = isPermissionError;
+/**
+ * Format an error for display
+ */
+function formatError(error) {
+    // String errors
+    if (typeof error === "string") {
+        return { message: error };
+    }
+    // Error objects
+    if (error instanceof Error) {
+        const formatted = {
+            message: error.message,
+        };
+        if (error.stack) {
+            formatted.stack = error.stack;
+        }
+        // Check for error codes (common in Node.js errors)
+        if ("code" in error && (typeof error.code === "string" || typeof error.code === "number")) {
+            formatted.code = error.code;
+        }
+        return formatted;
+    }
+    // Unknown error types
+    return {
+        message: String(error),
+    };
+}
+/**
+ * Check if an error is a "not found" type error
+ */
+function isNotFoundError(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "NOT_FOUND";
+    }
+    return false;
+}
+/**
+ * Check if an error is a validation error
+ */
+function isValidationError(error) {
+    if (error instanceof Error) {
+        return error.name === "ValidationError" || error.message.toLowerCase().includes("invalid");
+    }
+    return false;
+}
+/**
+ * Check if an error is a permission/access error
+ */
+function isPermissionError(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        return code === "EACCES" || code === "EPERM" || code === "FORBIDDEN";
+    }
+    return false;
+}
+//# sourceMappingURL=ErrorFormatter.js.map

package/dist/presentation/cli/shared/errors/ErrorFormatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorFormatter.js","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/errors/ErrorFormatter.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAWH,kCA4BC;AAKD,0CAMC;AAKD,8CAKC;AAKD,8CAMC;AA/DD;;GAEG;AACH,SAAgB,WAAW,CAAC,KAA+B;IACzD,gBAAgB;IAChB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,gBAAgB;IAChB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAmB;YAChC,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;QAEF,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAChC,CAAC;QAED,mDAAmD;QACnD,IAAI,MAAM,IAAI,KAAK,IAAI,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC1F,SAAS,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAC9B,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,sBAAsB;IACtB,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;KACvB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,KAAsB;IACpD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAI,KAAa,CAAC,IAAI,CAAC;QACjC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,WAAW,CAAC;IACnD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,KAAsB;IACtD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,KAAsB;IACtD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAI,KAAa,CAAC,IAAI,CAAC;QACjC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,WAAW,CAAC;IACvE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/presentation/cli/shared/formatting/YamlFormatter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * YamlFormatter - Converts data structures to YAML format
+ *
+ * Uses the 'yaml' library for robust YAML serialization.
+ * YAML is preferred over JSON for LLM context because it's more readable
+ * and has less syntactic noise (no quotes, commas, braces everywhere).
+ *
+ * Configuration:
+ * - indent: 2 spaces (standard YAML convention)
+ * - No document markers (---) for cleaner output
+ * - Preserves null values (important for optional fields)
+ */
+export declare class YamlFormatter {
+    /**
+     * Convert data to YAML string
+     *
+     * @param data - Any serializable data structure
+     * @param options - Formatting options (currently supports indent)
+     * @returns YAML string representation
+     */
+    toYaml(data: any, options?: {
+        indent?: number;
+    }): string;
+}
+//# sourceMappingURL=YamlFormatter.d.ts.map

package/dist/presentation/cli/shared/formatting/YamlFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlFormatter.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/formatting/YamlFormatter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;CAYzD"}

package/dist/presentation/cli/shared/formatting/YamlFormatter.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YamlFormatter = void 0;
+const yaml_1 = __importDefault(require("yaml"));
+/**
+ * YamlFormatter - Converts data structures to YAML format
+ *
+ * Uses the 'yaml' library for robust YAML serialization.
+ * YAML is preferred over JSON for LLM context because it's more readable
+ * and has less syntactic noise (no quotes, commas, braces everywhere).
+ *
+ * Configuration:
+ * - indent: 2 spaces (standard YAML convention)
+ * - No document markers (---) for cleaner output
+ * - Preserves null values (important for optional fields)
+ */
+class YamlFormatter {
+    /**
+     * Convert data to YAML string
+     *
+     * @param data - Any serializable data structure
+     * @param options - Formatting options (currently supports indent)
+     * @returns YAML string representation
+     */
+    toYaml(data, options) {
+        const indent = options?.indent ?? 2;
+        return yaml_1.default.stringify(data, {
+            indent,
+            lineWidth: 0, // Disable line wrapping
+            minContentWidth: 0, // Allow content at any width
+            defaultStringType: "PLAIN", // Use plain strings when possible (no quotes)
+            defaultKeyType: "PLAIN", // Use plain keys when possible
+            nullStr: "null", // Explicit null representation
+        });
+    }
+}
+exports.YamlFormatter = YamlFormatter;
+//# sourceMappingURL=YamlFormatter.js.map

package/dist/presentation/cli/shared/formatting/YamlFormatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlFormatter.js","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/formatting/YamlFormatter.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AAExB;;;;;;;;;;;GAWG;AACH,MAAa,aAAa;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,IAAS,EAAE,OAA6B;QAC7C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC;QAEpC,OAAO,cAAI,CAAC,SAAS,CAAC,IAAI,EAAE;YAC1B,MAAM;YACN,SAAS,EAAE,CAAC,EAAE,wBAAwB;YACtC,eAAe,EAAE,CAAC,EAAE,6BAA6B;YACjD,iBAAiB,EAAE,OAAO,EAAE,8CAA8C;YAC1E,cAAc,EAAE,OAAO,EAAE,+BAA+B;YACxD,OAAO,EAAE,MAAM,EAAE,+BAA+B;SACjD,CAAC,CAAC;IACL,CAAC;CACF;AApBD,sCAoBC"}

package/dist/presentation/cli/shared/guards/ProjectGuard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Project Guard
+ *
+ * Validates whether a command requires an initialized Jumbo project.
+ * Uses command metadata to determine project requirements instead of hard-coded logic.
+ */
+import { RegisteredCommand } from "../registry/CommandMetadata.js";
+/**
+ * Result of project requirement validation
+ */
+export interface ProjectRequirementResult {
+    /** Whether this command requires an initialized project */
+    requiresProject: boolean;
+    /** The resolved command path (e.g., "project init"), or null if not resolved */
+    commandPath: string | null;
+}
+/**
+ * Validates whether the current command requires an initialized Jumbo project.
+ *
+ * @param argv - Process arguments (process.argv)
+ * @param commands - Registered commands from the command registry
+ * @returns Object indicating if project is required and the resolved command path
+ */
+export declare function validateProjectRequirement(argv: string[], commands: RegisteredCommand[]): ProjectRequirementResult;
+//# sourceMappingURL=ProjectGuard.d.ts.map

package/dist/presentation/cli/shared/guards/ProjectGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectGuard.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/guards/ProjectGuard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,eAAe,EAAE,OAAO,CAAC;IAEzB,gFAAgF;IAChF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,iBAAiB,EAAE,GAC5B,wBAAwB,CAyB1B"}

package/dist/presentation/cli/shared/guards/ProjectGuard.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Project Guard
+ *
+ * Validates whether a command requires an initialized Jumbo project.
+ * Uses command metadata to determine project requirements instead of hard-coded logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateProjectRequirement = validateProjectRequirement;
+/**
+ * Validates whether the current command requires an initialized Jumbo project.
+ *
+ * @param argv - Process arguments (process.argv)
+ * @param commands - Registered commands from the command registry
+ * @returns Object indicating if project is required and the resolved command path
+ */
+function validateProjectRequirement(argv, commands) {
+    // Utility commands bypass project requirement
+    if (isUtilityCommand(argv)) {
+        return { requiresProject: false, commandPath: null };
+    }
+    // Resolve command path from args (handling aliases)
+    const commandPath = resolveCommandPath(argv, commands);
+    if (!commandPath) {
+        // Unknown command or no command specified
+        // Let Commander handle the error - don't require project
+        return { requiresProject: false, commandPath: null };
+    }
+    // Look up metadata
+    const command = commands.find((c) => c.path === commandPath);
+    if (!command) {
+        return { requiresProject: false, commandPath };
+    }
+    // Default to true if requiresProject not specified
+    const requiresProject = command.metadata.requiresProject ?? true;
+    return { requiresProject, commandPath };
+}
+/**
+ * Checks if this is a utility command that should bypass project validation.
+ * Utility commands include --help, -h, --version, -V which should work from any directory.
+ */
+function isUtilityCommand(argv) {
+    return (argv.includes("--help") ||
+        argv.includes("-h") ||
+        argv.includes("--version") ||
+        argv.includes("-V"));
+}
+/**
+ * Resolves the command path from process arguments, handling top-level aliases.
+ *
+ * Examples:
+ * - ["node", "cli.js", "project", "init"] -> "project init"
+ * - ["node", "cli.js", "init"] -> "project init" (via alias)
+ * - ["node", "cli.js", "goal", "start", "--goal-id", "123"] -> "goal start"
+ */
+function resolveCommandPath(argv, commands) {
+    // Remove node and script path
+    const args = argv.slice(2);
+    if (args.length === 0) {
+        return null;
+    }
+    // Filter out flags to get positional args
+    const positionalArgs = args.filter((arg) => !arg.startsWith("-"));
+    if (positionalArgs.length === 0) {
+        return null;
+    }
+    // First, check if this is a top-level alias
+    const firstArg = positionalArgs[0];
+    const aliasedCommand = commands.find((c) => c.metadata.topLevelAliases?.includes(firstArg));
+    if (aliasedCommand) {
+        return aliasedCommand.path;
+    }
+    // Otherwise, try to match as "parent subcommand"
+    if (positionalArgs.length >= 2) {
+        const commandPath = `${positionalArgs[0]} ${positionalArgs[1]}`;
+        const matchingCommand = commands.find((c) => c.path === commandPath);
+        if (matchingCommand) {
+            return commandPath;
+        }
+    }
+    // Could be just a parent command (e.g., "jumbo goal" to show help)
+    // Return null to let Commander handle it
+    return null;
+}
+//# sourceMappingURL=ProjectGuard.js.map

package/dist/presentation/cli/shared/guards/ProjectGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectGuard.js","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/guards/ProjectGuard.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAsBH,gEA4BC;AAnCD;;;;;;GAMG;AACH,SAAgB,0BAA0B,CACxC,IAAc,EACd,QAA6B;IAE7B,8CAA8C;IAC9C,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,oDAAoD;IACpD,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAEvD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,0CAA0C;QAC1C,yDAAyD;QACzD,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,mBAAmB;IACnB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACjD,CAAC;IAED,mDAAmD;IACnD,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,eAAe,IAAI,IAAI,CAAC;IAEjE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,IAAc;IACtC,OAAO,CACL,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QACnB,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC1B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CACpB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,kBAAkB,CACzB,IAAc,EACd,QAA6B;IAE7B,8BAA8B;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0CAA0C;IAC1C,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAElE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4CAA4C;IAC5C,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CACzC,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAC/C,CAAC;IAEF,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,cAAc,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,iDAAiD;IACjD,IAAI,cAAc,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;QACrE,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,yCAAyC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/presentation/cli/shared/help/CategoryFormatter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Category-Based Help Formatter
+ *
+ * Formats command help output in gh-style with hierarchical grouping.
+ * Categories, generous whitespace, and clean alignment.
+ */
+import { RegisteredCommand } from "../registry/CommandMetadata.js";
+/**
+ * Format all commands grouped by category (gh-style)
+ */
+export declare function formatCategorizedCommands(commands: RegisteredCommand[]): string;
+//# sourceMappingURL=CategoryFormatter.d.ts.map

package/dist/presentation/cli/shared/help/CategoryFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CategoryFormatter.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/help/CategoryFormatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AA8EnE;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAoB/E"}

package/dist/presentation/cli/shared/help/CategoryFormatter.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Category-Based Help Formatter
+ *
+ * Formats command help output in gh-style with hierarchical grouping.
+ * Categories, generous whitespace, and clean alignment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCategorizedCommands = formatCategorizedCommands;
+/**
+ * Category display configuration
+ */
+const CATEGORY_LABELS = {
+    "project-knowledge": "PROJECT",
+    "work": "WORK",
+    "solution": "SOLUTION",
+    "relations": "GRAPH",
+};
+/**
+ * Category display order (controls section ordering in help)
+ */
+const CATEGORY_ORDER = [
+    "project-knowledge",
+    "work",
+    "solution",
+    "relations",
+];
+/**
+ * Group commands by category
+ */
+function groupByCategory(commands) {
+    const grouped = new Map();
+    for (const command of commands) {
+        const category = command.metadata.category || "uncategorized";
+        if (!grouped.has(category)) {
+            grouped.set(category, []);
+        }
+        grouped.get(category).push(command);
+    }
+    return grouped;
+}
+/**
+ * Fixed column where descriptions start (0-indexed)
+ * This ensures consistent alignment across all categories
+ */
+const DESCRIPTION_START_COLUMN = 26;
+/**
+ * Format a single command line with alignment
+ * Descriptions always start at column 26 for consistent alignment
+ */
+function formatCommandLine(path, description) {
+    // 2 spaces indent + path padded to fill remaining space before description column
+    const paddedPath = path.padEnd(DESCRIPTION_START_COLUMN - 2);
+    return `  ${paddedPath}${description}`;
+}
+/**
+ * Format commands in a category
+ */
+function formatCategory(category, commands) {
+    // Sort commands alphabetically by path
+    const sorted = [...commands].sort((a, b) => a.path.localeCompare(b.path));
+    // Build output
+    const lines = [];
+    // Category header (ALL CAPS, no indentation)
+    const header = category === "uncategorized" ? "OTHER COMMANDS" : CATEGORY_LABELS[category];
+    lines.push(header);
+    // Command list
+    for (const command of sorted) {
+        lines.push(formatCommandLine(command.path, command.metadata.description));
+    }
+    return lines.join("\n");
+}
+/**
+ * Format all commands grouped by category (gh-style)
+ */
+function formatCategorizedCommands(commands) {
+    const grouped = groupByCategory(commands);
+    const sections = [];
+    // Add categories in defined order
+    for (const category of CATEGORY_ORDER) {
+        const categoryCommands = grouped.get(category);
+        if (categoryCommands && categoryCommands.length > 0) {
+            sections.push(formatCategory(category, categoryCommands));
+        }
+    }
+    // Add uncategorized commands at the end (if any)
+    const uncategorized = grouped.get("uncategorized");
+    if (uncategorized && uncategorized.length > 0) {
+        sections.push(formatCategory("uncategorized", uncategorized));
+    }
+    // Join sections with generous whitespace (blank line between sections)
+    return sections.join("\n\n");
+}
+//# sourceMappingURL=CategoryFormatter.js.map

package/dist/presentation/cli/shared/help/CategoryFormatter.js.map

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

package/dist/presentation/cli/shared/program/GlobalOptionsHandler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Global Options Handler
+ *
+ * Attaches global CLI options and configures the Renderer based on user flags.
+ * Handles --format, --quiet, and --verbose options.
+ */
+import { Command } from "commander";
+/**
+ * Attaches global options to the program and configures the Renderer
+ * via a preAction hook.
+ *
+ * Global options:
+ * - --format <format>: Output format (text, json, yaml, ndjson)
+ * - --quiet: Minimal output (suppress info messages)
+ * - --verbose: Verbose output (show detailed info)
+ *
+ * @param program - Commander program instance
+ */
+export declare function attachGlobalOptions(program: Command): void;
+//# sourceMappingURL=GlobalOptionsHandler.d.ts.map

package/dist/presentation/cli/shared/program/GlobalOptionsHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalOptionsHandler.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/program/GlobalOptionsHandler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAW1D"}

package/dist/presentation/cli/shared/program/GlobalOptionsHandler.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Global Options Handler
+ *
+ * Attaches global CLI options and configures the Renderer based on user flags.
+ * Handles --format, --quiet, and --verbose options.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachGlobalOptions = attachGlobalOptions;
+const Renderer_js_1 = require("../rendering/Renderer.js");
+/**
+ * Attaches global options to the program and configures the Renderer
+ * via a preAction hook.
+ *
+ * Global options:
+ * - --format <format>: Output format (text, json, yaml, ndjson)
+ * - --quiet: Minimal output (suppress info messages)
+ * - --verbose: Verbose output (show detailed info)
+ *
+ * @param program - Commander program instance
+ */
+function attachGlobalOptions(program) {
+    program
+        .option("--format <format>", "Output format: text, json, yaml, ndjson (default: auto-detect)")
+        .option("--quiet", "Minimal output (suppress info messages)")
+        .option("--verbose", "Verbose output (show detailed info)")
+        .hook("preAction", (thisCommand) => {
+        configureRendererFromOptions(thisCommand);
+    });
+}
+/**
+ * Configures the Renderer singleton based on command options.
+ *
+ * @param command - The command with parsed options
+ */
+function configureRendererFromOptions(command) {
+    const opts = command.opts();
+    // Determine verbosity
+    let verbosity = "normal";
+    if (opts.quiet)
+        verbosity = "quiet";
+    else if (opts.verbose)
+        verbosity = "verbose";
+    // Determine format
+    const format = opts.format;
+    // Configure renderer singleton
+    Renderer_js_1.Renderer.configure({ format, verbosity });
+}
+//# sourceMappingURL=GlobalOptionsHandler.js.map

package/dist/presentation/cli/shared/program/GlobalOptionsHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalOptionsHandler.js","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/program/GlobalOptionsHandler.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAiBH,kDAWC;AAzBD,0DAAoD;AAGpD;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,MAAM,CACL,mBAAmB,EACnB,gEAAgE,CACjE;SACA,MAAM,CAAC,SAAS,EAAE,yCAAyC,CAAC;SAC5D,MAAM,CAAC,WAAW,EAAE,qCAAqC,CAAC;SAC1D,IAAI,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE;QACjC,4BAA4B,CAAC,WAAW,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,SAAS,4BAA4B,CAAC,OAAgB;IACpD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAE5B,sBAAsB;IACtB,IAAI,SAAS,GAAmB,QAAQ,CAAC;IACzC,IAAI,IAAI,CAAC,KAAK;QAAE,SAAS,GAAG,OAAO,CAAC;SAC/B,IAAI,IAAI,CAAC,OAAO;QAAE,SAAS,GAAG,SAAS,CAAC;IAE7C,mBAAmB;IACnB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAkC,CAAC;IAEvD,+BAA+B;IAC/B,sBAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAC5C,CAAC"}

package/dist/presentation/cli/shared/program/ProgramFactory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Program Factory
+ *
+ * Creates and configures the Commander.js program instance.
+ * Centralizes CLI structure: name, version, usage, and help formatting.
+ */
+import { Command } from "commander";
+import { RegisteredCommand } from "../registry/CommandMetadata.js";
+/**
+ * Creates a configured Commander program instance.
+ *
+ * @param version - CLI version string
+ * @param commands - Registered commands for categorized help
+ * @returns Configured Commander program
+ */
+export declare function createProgram(version: string, commands: RegisteredCommand[]): Command;
+//# sourceMappingURL=ProgramFactory.d.ts.map

package/dist/presentation/cli/shared/program/ProgramFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgramFactory.d.ts","sourceRoot":"","sources":["../../../../../src/presentation/cli/shared/program/ProgramFactory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGnE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAAE,GAC5B,OAAO,CAmCT"}