@kynetic-ai/spec 0.1.0

package/dist/cli/introspection.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Commander.js introspection - extracts command tree from program definition
+ *
+ * This module provides the foundation for auto-generated CLI documentation
+ * by extracting command metadata directly from Commander.js definitions.
+ */
+import { Command } from 'commander';
+/**
+ * Metadata for a single command option
+ */
+export interface OptionMeta {
+    /** Option flags (e.g., "-n, --name <value>") */
+    flags: string;
+    /** Option description */
+    description: string;
+    /** Whether option is required */
+    required: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Whether option can be repeated */
+    variadic: boolean;
+}
+/**
+ * Metadata for a command argument
+ */
+export interface ArgumentMeta {
+    /** Argument name */
+    name: string;
+    /** Argument description */
+    description: string;
+    /** Whether argument is required */
+    required: boolean;
+    /** Whether argument can be repeated */
+    variadic: boolean;
+}
+/**
+ * Complete metadata for a command
+ */
+export interface CommandMeta {
+    /** Command name */
+    name: string;
+    /** Full command path from root (e.g., ["task", "add"]) */
+    fullPath: string[];
+    /** Command description */
+    description: string;
+    /** Command aliases */
+    aliases: string[];
+    /** Command arguments */
+    arguments: ArgumentMeta[];
+    /** Command options */
+    options: OptionMeta[];
+    /** Subcommands */
+    subcommands: CommandMeta[];
+    /** Whether this command is hidden */
+    hidden: boolean;
+}
+/**
+ * Extract complete command tree from a Commander program
+ *
+ * @param command - Commander command to introspect
+ * @param parentPath - Parent command path (for recursion)
+ * @returns Complete command metadata tree
+ */
+export declare function extractCommandTree(command: Command, parentPath?: string[]): CommandMeta;
+/**
+ * Find a command in the tree by path
+ *
+ * @param tree - Command tree to search
+ * @param path - Command path (e.g., ["task", "add"])
+ * @returns Command metadata if found, null otherwise
+ */
+export declare function findCommand(tree: CommandMeta, path: string[]): CommandMeta | null;
+/**
+ * Flatten command tree into a list of all commands
+ *
+ * @param tree - Command tree to flatten
+ * @returns Array of all commands in the tree
+ */
+export declare function flattenCommandTree(tree: CommandMeta): CommandMeta[];
+/**
+ * Format command usage string
+ *
+ * @param command - Command metadata
+ * @returns Usage string (e.g., "kspec task add [options]")
+ */
+export declare function formatCommandUsage(command: CommandMeta): string;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/cli/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/cli/introspection.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAA6B,MAAM,WAAW,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wBAAwB;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,sBAAsB;IACtB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,kBAAkB;IAClB,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;CACjB;AA6BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,MAAM,EAAO,GACxB,WAAW,CA6Bb;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,IAAI,CAuBjF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAkB/D"}

package/dist/cli/introspection.js

@@ -0,0 +1,127 @@
+// AC: @auto-cli-docs ac-1
+/**
+ * Commander.js introspection - extracts command tree from program definition
+ *
+ * This module provides the foundation for auto-generated CLI documentation
+ * by extracting command metadata directly from Commander.js definitions.
+ */
+/**
+ * Extract metadata for a single option
+ */
+function extractOptionMeta(option) {
+    return {
+        flags: option.flags,
+        description: option.description || '',
+        required: option.required,
+        defaultValue: option.defaultValue,
+        variadic: option.variadic,
+    };
+}
+/**
+ * Extract metadata for command arguments
+ */
+function extractArgumentsMeta(command) {
+    // Commander stores processed arguments with metadata
+    const args = command.registeredArguments || [];
+    return args.map((arg) => ({
+        name: arg.name(),
+        description: arg.description || '',
+        required: arg.required,
+        variadic: arg.variadic,
+    }));
+}
+/**
+ * Extract complete command tree from a Commander program
+ *
+ * @param command - Commander command to introspect
+ * @param parentPath - Parent command path (for recursion)
+ * @returns Complete command metadata tree
+ */
+export function extractCommandTree(command, parentPath = []) {
+    // Get command name - use first name if command has multiple
+    const commandName = command.name();
+    const fullPath = [...parentPath, commandName];
+    // Extract options (filter out help option if needed)
+    const options = command.options.map(extractOptionMeta);
+    // Extract arguments
+    const args = extractArgumentsMeta(command);
+    // Recursively extract subcommands
+    // Cast to any to access _hidden private property
+    const isHidden = (cmd) => cmd._hidden || false;
+    const subcommands = command.commands
+        .filter((cmd) => !isHidden(cmd)) // Filter hidden commands
+        .map((cmd) => extractCommandTree(cmd, fullPath));
+    return {
+        name: commandName,
+        fullPath,
+        description: command.description() || '',
+        aliases: command.aliases(),
+        arguments: args,
+        options,
+        subcommands,
+        hidden: isHidden(command),
+    };
+}
+/**
+ * Find a command in the tree by path
+ *
+ * @param tree - Command tree to search
+ * @param path - Command path (e.g., ["task", "add"])
+ * @returns Command metadata if found, null otherwise
+ */
+export function findCommand(tree, path) {
+    if (path.length === 0) {
+        return tree;
+    }
+    // If we're at the right level
+    if (path.length === 1 && path[0] === tree.name) {
+        return tree;
+    }
+    // Search in subcommands
+    const [first, ...rest] = path;
+    const subcommand = tree.subcommands.find((cmd) => cmd.name === first);
+    if (!subcommand) {
+        return null;
+    }
+    if (rest.length === 0) {
+        return subcommand;
+    }
+    return findCommand(subcommand, rest);
+}
+/**
+ * Flatten command tree into a list of all commands
+ *
+ * @param tree - Command tree to flatten
+ * @returns Array of all commands in the tree
+ */
+export function flattenCommandTree(tree) {
+    const result = [tree];
+    for (const subcommand of tree.subcommands) {
+        result.push(...flattenCommandTree(subcommand));
+    }
+    return result;
+}
+/**
+ * Format command usage string
+ *
+ * @param command - Command metadata
+ * @returns Usage string (e.g., "kspec task add [options]")
+ */
+export function formatCommandUsage(command) {
+    const parts = ['kspec', ...command.fullPath.slice(1)]; // Skip root 'kspec'
+    // Add arguments
+    for (const arg of command.arguments) {
+        if (arg.required) {
+            parts.push(`<${arg.name}${arg.variadic ? '...' : ''}>`);
+        }
+        else {
+            parts.push(`[${arg.name}${arg.variadic ? '...' : ''}]`);
+        }
+    }
+    // Add [options] if command has options
+    if (command.options.length > 0) {
+        parts.push('[options]');
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=introspection.js.map

package/dist/cli/introspection.js.map

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

package/dist/cli/output.d.ts

@@ -0,0 +1,56 @@
+import type { Task } from '../schema/index.js';
+import type { ReferenceIndex } from '../parser/index.js';
+/**
+ * Output options
+ */
+export interface OutputOptions {
+    json?: boolean;
+}
+export declare function setJsonMode(enabled: boolean): void;
+export declare function isJsonMode(): boolean;
+export declare function setVerboseMode(enabled: boolean): void;
+export declare function getVerboseMode(): boolean;
+/**
+ * Output data - JSON if --json flag, otherwise formatted
+ */
+export declare function output(data: unknown, formatter?: () => void): void;
+/**
+ * Output success message
+ */
+export declare function success(message: string, data?: Record<string, unknown>): void;
+/**
+ * Output error message
+ */
+export declare function error(message: string, details?: unknown): void;
+/**
+ * Output warning message
+ */
+export declare function warn(message: string): void;
+/**
+ * Output info message
+ */
+export declare function info(message: string): void;
+/**
+ * Format a task reference (short ULID + slug if available)
+ * @param task The task to format
+ * @param index Optional ReferenceIndex for dynamic short ULID computation
+ */
+export declare function formatTaskRef(task: Task, index?: ReferenceIndex): string;
+/**
+ * Format task for display
+ */
+export declare function formatTask(task: Task, verbose?: boolean, index?: ReferenceIndex, full?: boolean): string;
+/**
+ * Format a list of tasks with automation status
+ * AC: @task-automation-eligibility ac-14
+ */
+export declare function formatTaskListWithAutomation(tasks: Task[], verbose?: boolean, index?: ReferenceIndex, grepPattern?: string, full?: boolean): void;
+/**
+ * Format a list of tasks
+ */
+export declare function formatTaskList(tasks: Task[], verbose?: boolean, index?: ReferenceIndex, grepPattern?: string, full?: boolean): void;
+/**
+ * Format task details
+ */
+export declare function formatTaskDetails(task: Task, index?: ReferenceIndex): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAOD,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAOD,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAErD;AAED,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAQlE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAM7E;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAgB9D;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAM1C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAM1C;AAsBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,MAAM,CAMxE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,UAAQ,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,IAAI,UAAQ,GAAG,MAAM,CAqBpG;AAqGD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,UAAQ,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,IAAI,CA8C7I;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,UAAQ,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,IAAI,CA4B/H;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CA4J1E"}