@specforge/cli 0.1.0

package/dist/cli/middleware/auth-guard.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Auth Guard Middleware
+ *
+ * Checks for valid API key authentication before executing protected commands.
+ * Provides helpful error messages directing users to authenticate.
+ */
+/**
+ * Check if a command requires authentication
+ *
+ * @param command - Command name or flag to check
+ * @returns true if command requires authentication
+ *
+ * @example
+ * ```typescript
+ * requiresAuth('status');  // true
+ * requiresAuth('login');   // false
+ * requiresAuth('--help');  // false
+ * ```
+ */
+export declare function requiresAuth(command: string): boolean;
+/**
+ * Get the list of public commands
+ *
+ * @returns Array of command names that don't require auth
+ */
+export declare function getPublicCommands(): string[];
+/**
+ * Add a command to the public (no-auth-required) list
+ *
+ * Useful for plugins or extensions that add unauthenticated commands.
+ *
+ * @param command - Command name to add
+ */
+export declare function addPublicCommand(command: string): void;
+/**
+ * Authentication guard - checks auth and exits if not authenticated
+ *
+ * Call this at the start of protected command handlers.
+ * Exits the process with code 1 if not authenticated.
+ *
+ * @param command - Command name being executed (for logging)
+ *
+ * @example
+ * ```typescript
+ * // In a command handler
+ * export function statusCommand() {
+ *   authGuard('status');
+ *   // ... rest of command (only runs if authenticated)
+ * }
+ * ```
+ */
+export declare function authGuard(command: string): void;
+/**
+ * Check authentication without exiting
+ *
+ * Use this for conditional logic where you don't want to exit.
+ *
+ * @returns Object with auth status and config
+ *
+ * @example
+ * ```typescript
+ * const { authenticated, config } = checkAuth();
+ * if (!authenticated) {
+ *   // Handle gracefully without exiting
+ * }
+ * ```
+ */
+export declare function checkAuth(): {
+    authenticated: boolean;
+    apiKeySource: 'env' | 'global' | null;
+};
+/**
+ * Validate API key format
+ *
+ * Checks that the API key matches expected format without making API calls.
+ *
+ * @param apiKey - API key to validate
+ * @returns Object with validity and any error message
+ *
+ * @example
+ * ```typescript
+ * const { valid, error } = validateApiKeyFormat('sf_live_abc123');
+ * if (!valid) {
+ *   console.error(error);
+ * }
+ * ```
+ */
+export declare function validateApiKeyFormat(apiKey: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Commander.js pre-action hook for auth guard
+ *
+ * Use this with Commander's hook system for automatic auth checking.
+ *
+ * @param thisCommand - Commander command object
+ *
+ * @example
+ * ```typescript
+ * program.hook('preAction', authGuardHook);
+ * ```
+ */
+export declare function authGuardHook(thisCommand: {
+    name: () => string;
+}): void;
+//# sourceMappingURL=auth-guard.d.ts.map

package/dist/cli/middleware/auth-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-guard.d.ts","sourceRoot":"","sources":["../../../src/cli/middleware/auth-guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAc/C;AA8BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,IAAI;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;CACvC,CAOA;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CA2BA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,MAAM,CAAA;CAAE,GAAG,IAAI,CAGvE"}

package/dist/cli/middleware/auth-guard.js

@@ -0,0 +1,97 @@
+import chalk from "chalk";
+import { isAuthenticated, resolveConfig } from "../config/loader.js";
+const PUBLIC_COMMANDS = /* @__PURE__ */ new Set([
+  "login",
+  "help",
+  "--help",
+  "-h",
+  "version",
+  "--version",
+  "-v",
+  "doctor",
+  "tools",
+  "docs"
+]);
+function requiresAuth(command) {
+  return !PUBLIC_COMMANDS.has(command);
+}
+function getPublicCommands() {
+  return Array.from(PUBLIC_COMMANDS);
+}
+function addPublicCommand(command) {
+  PUBLIC_COMMANDS.add(command);
+}
+function authGuard(command) {
+  if (!requiresAuth(command)) {
+    return;
+  }
+  if (isAuthenticated()) {
+    return;
+  }
+  printAuthError();
+  process.exit(1);
+}
+function printAuthError() {
+  console.error(chalk.red("Error: Not authenticated.\n"));
+  console.error(
+    "You need to authenticate before running this command.\n"
+  );
+  console.error(chalk.bold("To authenticate:"));
+  console.error(
+    `  ${chalk.cyan("specforge login")}  - Interactive login
+`
+  );
+  console.error(chalk.bold("Or set environment variable:"));
+  console.error(
+    `  ${chalk.cyan("export SPECFORGE_API_KEY=sf_live_your_key")}
+`
+  );
+  console.error(chalk.bold("Get your API key:"));
+  console.error(
+    `  ${chalk.underline("https://specforge.com.br/settings/api-keys")}
+`
+  );
+}
+function checkAuth() {
+  const config = resolveConfig();
+  return {
+    authenticated: config.apiKey !== null,
+    apiKeySource: config.sources.apiKey
+  };
+}
+function validateApiKeyFormat(apiKey) {
+  if (!apiKey.startsWith("sf_live_")) {
+    return {
+      valid: false,
+      error: 'API key must start with "sf_live_"'
+    };
+  }
+  if (apiKey.length < 28) {
+    return {
+      valid: false,
+      error: "API key is too short. Make sure you copied the complete key."
+    };
+  }
+  const keyPart = apiKey.slice(8);
+  if (!/^[a-zA-Z0-9_-]+$/.test(keyPart)) {
+    return {
+      valid: false,
+      error: "API key contains invalid characters."
+    };
+  }
+  return { valid: true };
+}
+function authGuardHook(thisCommand) {
+  const commandName = thisCommand.name();
+  authGuard(commandName);
+}
+export {
+  addPublicCommand,
+  authGuard,
+  authGuardHook,
+  checkAuth,
+  getPublicCommands,
+  requiresAuth,
+  validateApiKeyFormat
+};
+//# sourceMappingURL=auth-guard.js.map

package/dist/cli/middleware/auth-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/middleware/auth-guard.ts"],"sourcesContent":["/**\n * Auth Guard Middleware\n *\n * Checks for valid API key authentication before executing protected commands.\n * Provides helpful error messages directing users to authenticate.\n */\n\nimport chalk from 'chalk';\nimport { isAuthenticated, resolveConfig } from '../config/loader.js';\n\n/**\n * Commands that do not require authentication\n *\n * These commands can be run without an API key:\n * - login: Obviously needs to work to set up auth\n * - help: Should always be accessible\n * - version: Should always be accessible\n * - doctor: Diagnostic tool should work without auth\n * - tools: Lists locally defined tools (no API access needed)\n * - docs: Documentation is available offline without auth\n */\nconst PUBLIC_COMMANDS = new Set([\n  'login',\n  'help',\n  '--help',\n  '-h',\n  'version',\n  '--version',\n  '-v',\n  'doctor',\n  'tools',\n  'docs',\n]);\n\n/**\n * Check if a command requires authentication\n *\n * @param command - Command name or flag to check\n * @returns true if command requires authentication\n *\n * @example\n * ```typescript\n * requiresAuth('status');  // true\n * requiresAuth('login');   // false\n * requiresAuth('--help');  // false\n * ```\n */\nexport function requiresAuth(command: string): boolean {\n  return !PUBLIC_COMMANDS.has(command);\n}\n\n/**\n * Get the list of public commands\n *\n * @returns Array of command names that don't require auth\n */\nexport function getPublicCommands(): string[] {\n  return Array.from(PUBLIC_COMMANDS);\n}\n\n/**\n * Add a command to the public (no-auth-required) list\n *\n * Useful for plugins or extensions that add unauthenticated commands.\n *\n * @param command - Command name to add\n */\nexport function addPublicCommand(command: string): void {\n  PUBLIC_COMMANDS.add(command);\n}\n\n/**\n * Authentication guard - checks auth and exits if not authenticated\n *\n * Call this at the start of protected command handlers.\n * Exits the process with code 1 if not authenticated.\n *\n * @param command - Command name being executed (for logging)\n *\n * @example\n * ```typescript\n * // In a command handler\n * export function statusCommand() {\n *   authGuard('status');\n *   // ... rest of command (only runs if authenticated)\n * }\n * ```\n */\nexport function authGuard(command: string): void {\n  // Skip auth check for public commands\n  if (!requiresAuth(command)) {\n    return;\n  }\n\n  // Check if authenticated\n  if (isAuthenticated()) {\n    return;\n  }\n\n  // Not authenticated - show helpful error and exit\n  printAuthError();\n  process.exit(1);\n}\n\n/**\n * Print authentication error message with instructions\n *\n * Provides clear guidance on how to authenticate.\n */\nfunction printAuthError(): void {\n  console.error(chalk.red('Error: Not authenticated.\\n'));\n\n  console.error(\n    'You need to authenticate before running this command.\\n'\n  );\n\n  console.error(chalk.bold('To authenticate:'));\n  console.error(\n    `  ${chalk.cyan('specforge login')}  - Interactive login\\n`\n  );\n\n  console.error(chalk.bold('Or set environment variable:'));\n  console.error(\n    `  ${chalk.cyan('export SPECFORGE_API_KEY=sf_live_your_key')}\\n`\n  );\n\n  console.error(chalk.bold('Get your API key:'));\n  console.error(\n    `  ${chalk.underline('https://specforge.com.br/settings/api-keys')}\\n`\n  );\n}\n\n/**\n * Check authentication without exiting\n *\n * Use this for conditional logic where you don't want to exit.\n *\n * @returns Object with auth status and config\n *\n * @example\n * ```typescript\n * const { authenticated, config } = checkAuth();\n * if (!authenticated) {\n *   // Handle gracefully without exiting\n * }\n * ```\n */\nexport function checkAuth(): {\n  authenticated: boolean;\n  apiKeySource: 'env' | 'global' | null;\n} {\n  const config = resolveConfig();\n\n  return {\n    authenticated: config.apiKey !== null,\n    apiKeySource: config.sources.apiKey,\n  };\n}\n\n/**\n * Validate API key format\n *\n * Checks that the API key matches expected format without making API calls.\n *\n * @param apiKey - API key to validate\n * @returns Object with validity and any error message\n *\n * @example\n * ```typescript\n * const { valid, error } = validateApiKeyFormat('sf_live_abc123');\n * if (!valid) {\n *   console.error(error);\n * }\n * ```\n */\nexport function validateApiKeyFormat(apiKey: string): {\n  valid: boolean;\n  error?: string;\n} {\n  // Check prefix\n  if (!apiKey.startsWith('sf_live_')) {\n    return {\n      valid: false,\n      error: 'API key must start with \"sf_live_\"',\n    };\n  }\n\n  // Check minimum length (prefix + at least 20 chars)\n  if (apiKey.length < 28) {\n    return {\n      valid: false,\n      error: 'API key is too short. Make sure you copied the complete key.',\n    };\n  }\n\n  // Check for invalid characters (should be alphanumeric after prefix)\n  const keyPart = apiKey.slice(8); // Remove 'sf_live_' prefix\n  if (!/^[a-zA-Z0-9_-]+$/.test(keyPart)) {\n    return {\n      valid: false,\n      error: 'API key contains invalid characters.',\n    };\n  }\n\n  return { valid: true };\n}\n\n/**\n * Commander.js pre-action hook for auth guard\n *\n * Use this with Commander's hook system for automatic auth checking.\n *\n * @param thisCommand - Commander command object\n *\n * @example\n * ```typescript\n * program.hook('preAction', authGuardHook);\n * ```\n */\nexport function authGuardHook(thisCommand: { name: () => string }): void {\n  const commandName = thisCommand.name();\n  authGuard(commandName);\n}\n"],"mappings":"AAOA,OAAO,WAAW;AAClB,SAAS,iBAAiB,qBAAqB;AAa/C,MAAM,kBAAkB,oBAAI,IAAI;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAeM,SAAS,aAAa,SAA0B;AACrD,SAAO,CAAC,gBAAgB,IAAI,OAAO;AACrC;AAOO,SAAS,oBAA8B;AAC5C,SAAO,MAAM,KAAK,eAAe;AACnC;AASO,SAAS,iBAAiB,SAAuB;AACtD,kBAAgB,IAAI,OAAO;AAC7B;AAmBO,SAAS,UAAU,SAAuB;AAE/C,MAAI,CAAC,aAAa,OAAO,GAAG;AAC1B;AAAA,EACF;AAGA,MAAI,gBAAgB,GAAG;AACrB;AAAA,EACF;AAGA,iBAAe;AACf,UAAQ,KAAK,CAAC;AAChB;AAOA,SAAS,iBAAuB;AAC9B,UAAQ,MAAM,MAAM,IAAI,6BAA6B,CAAC;AAEtD,UAAQ;AAAA,IACN;AAAA,EACF;AAEA,UAAQ,MAAM,MAAM,KAAK,kBAAkB,CAAC;AAC5C,UAAQ;AAAA,IACN,KAAK,MAAM,KAAK,iBAAiB,CAAC;AAAA;AAAA,EACpC;AAEA,UAAQ,MAAM,MAAM,KAAK,8BAA8B,CAAC;AACxD,UAAQ;AAAA,IACN,KAAK,MAAM,KAAK,2CAA2C,CAAC;AAAA;AAAA,EAC9D;AAEA,UAAQ,MAAM,MAAM,KAAK,mBAAmB,CAAC;AAC7C,UAAQ;AAAA,IACN,KAAK,MAAM,UAAU,4CAA4C,CAAC;AAAA;AAAA,EACpE;AACF;AAiBO,SAAS,YAGd;AACA,QAAM,SAAS,cAAc;AAE7B,SAAO;AAAA,IACL,eAAe,OAAO,WAAW;AAAA,IACjC,cAAc,OAAO,QAAQ;AAAA,EAC/B;AACF;AAkBO,SAAS,qBAAqB,QAGnC;AAEA,MAAI,CAAC,OAAO,WAAW,UAAU,GAAG;AAClC,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAGA,MAAI,OAAO,SAAS,IAAI;AACtB,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAGA,QAAM,UAAU,OAAO,MAAM,CAAC;AAC9B,MAAI,CAAC,mBAAmB,KAAK,OAAO,GAAG;AACrC,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO,EAAE,OAAO,KAAK;AACvB;AAcO,SAAS,cAAc,aAA2C;AACvE,QAAM,cAAc,YAAY,KAAK;AACrC,YAAU,WAAW;AACvB;","names":[]}

package/dist/cli/middleware/error-handler.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Error Handler Middleware
+ *
+ * Provides consistent error handling and formatting across all CLI commands.
+ * Supports debug mode for detailed stack traces.
+ */
+/**
+ * Standard exit codes
+ */
+export declare const EXIT_CODES: {
+    /** Successful execution */
+    readonly SUCCESS: 0;
+    /** General error */
+    readonly ERROR: 1;
+    /** Authentication error */
+    readonly AUTH_ERROR: 2;
+    /** Configuration error */
+    readonly CONFIG_ERROR: 3;
+    /** Network/API error */
+    readonly NETWORK_ERROR: 4;
+    /** Not found error */
+    readonly NOT_FOUND: 5;
+    /** Validation error */
+    readonly VALIDATION_ERROR: 6;
+};
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+/**
+ * Custom error class for CLI errors with exit codes
+ */
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    readonly hint?: string | undefined;
+    constructor(message: string, exitCode?: ExitCode, hint?: string | undefined);
+}
+/**
+ * Authentication error
+ */
+export declare class AuthError extends CliError {
+    constructor(message?: string);
+}
+/**
+ * Configuration error
+ */
+export declare class ConfigError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Network/API error
+ */
+export declare class NetworkError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Not found error
+ */
+export declare class NotFoundError extends CliError {
+    constructor(resource: string, identifier?: string);
+}
+/**
+ * Validation error
+ */
+export declare class ValidationError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Check if debug mode is enabled
+ */
+export declare function isDebugMode(): boolean;
+/**
+ * Format error for display
+ *
+ * @param error - Error to format
+ * @returns Formatted error string
+ */
+export declare function formatError(error: unknown): string;
+/**
+ * Handle error and exit process
+ *
+ * @param error - Error to handle
+ */
+export declare function handleError(error: unknown): never;
+/**
+ * Wrap an async function with error handling
+ *
+ * Use this to wrap command action handlers for automatic error handling.
+ *
+ * @param fn - Async function to wrap
+ * @returns Wrapped function that handles errors
+ *
+ * @example
+ * ```typescript
+ * program
+ *   .command('status')
+ *   .action(withErrorHandler(async () => {
+ *     // If this throws, error is caught and formatted
+ *     const data = await api.getStatus();
+ *   }));
+ * ```
+ */
+export declare function withErrorHandler<T extends unknown[], R>(fn: (...args: T) => Promise<R>): (...args: T) => Promise<void>;
+/**
+ * Wrap a sync function with error handling
+ *
+ * @param fn - Sync function to wrap
+ * @returns Wrapped function that handles errors
+ */
+export declare function withErrorHandlerSync<T extends unknown[], R>(fn: (...args: T) => R): (...args: T) => void;
+/**
+ * Log debug information (only in debug mode)
+ *
+ * @param message - Message to log
+ * @param data - Optional data to log
+ */
+export declare function debugLog(message: string, data?: unknown): void;
+/**
+ * Log warning message
+ *
+ * @param message - Warning message
+ */
+export declare function warnLog(message: string): void;
+/**
+ * Log success message
+ *
+ * @param message - Success message
+ */
+export declare function successLog(message: string): void;
+/**
+ * Log info message
+ *
+ * @param message - Info message
+ */
+export declare function infoLog(message: string): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/cli/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/cli/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;GAEG;AACH,eAAO,MAAM,UAAU;IACrB,2BAA2B;;IAE3B,oBAAoB;;IAEpB,2BAA2B;;IAE3B,0BAA0B;;IAE1B,wBAAwB;;IAExB,sBAAsB;;IAEtB,uBAAuB;;CAEf,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAElE;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,QAAQ;aAClB,IAAI,CAAC,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM,EACC,QAAQ,GAAE,QAA2B,EACrC,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,QAAQ;gBACzB,OAAO,GAAE,MAA4B;CAGlD;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAG3C;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,QAAQ;gBAC5B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAO3C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAMlD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAG3C;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA0BlD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAOjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EACrD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAQ/B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EACzD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GACpB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAQtB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAU9D;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C"}

package/dist/cli/middleware/error-handler.js

@@ -0,0 +1,139 @@
+import chalk from "chalk";
+import { CONFIG_ENV_VARS } from "../config/types.js";
+const EXIT_CODES = {
+  /** Successful execution */
+  SUCCESS: 0,
+  /** General error */
+  ERROR: 1,
+  /** Authentication error */
+  AUTH_ERROR: 2,
+  /** Configuration error */
+  CONFIG_ERROR: 3,
+  /** Network/API error */
+  NETWORK_ERROR: 4,
+  /** Not found error */
+  NOT_FOUND: 5,
+  /** Validation error */
+  VALIDATION_ERROR: 6
+};
+class CliError extends Error {
+  constructor(message, exitCode = EXIT_CODES.ERROR, hint) {
+    super(message);
+    this.exitCode = exitCode;
+    this.hint = hint;
+    this.name = "CliError";
+  }
+}
+class AuthError extends CliError {
+  constructor(message = "Not authenticated") {
+    super(message, EXIT_CODES.AUTH_ERROR, "Run `specforge login` to authenticate");
+  }
+}
+class ConfigError extends CliError {
+  constructor(message, hint) {
+    super(message, EXIT_CODES.CONFIG_ERROR, hint);
+  }
+}
+class NetworkError extends CliError {
+  constructor(message, hint) {
+    super(
+      message,
+      EXIT_CODES.NETWORK_ERROR,
+      hint || "Check your internet connection and try again"
+    );
+  }
+}
+class NotFoundError extends CliError {
+  constructor(resource, identifier) {
+    const message = identifier ? `${resource} not found: ${identifier}` : `${resource} not found`;
+    super(message, EXIT_CODES.NOT_FOUND);
+  }
+}
+class ValidationError extends CliError {
+  constructor(message, hint) {
+    super(message, EXIT_CODES.VALIDATION_ERROR, hint);
+  }
+}
+function isDebugMode() {
+  return process.env[CONFIG_ENV_VARS.DEBUG] === "true";
+}
+function formatError(error) {
+  if (error instanceof CliError) {
+    let output = chalk.red(`Error: ${error.message}`);
+    if (error.hint) {
+      output += "\n" + chalk.yellow(`Hint: ${error.hint}`);
+    }
+    if (isDebugMode() && error.stack) {
+      output += "\n\n" + chalk.gray(error.stack);
+    }
+    return output;
+  }
+  if (error instanceof Error) {
+    let output = chalk.red(`Error: ${error.message}`);
+    if (isDebugMode() && error.stack) {
+      output += "\n\n" + chalk.gray(error.stack);
+    }
+    return output;
+  }
+  return chalk.red(`Error: ${String(error)}`);
+}
+function handleError(error) {
+  console.error(formatError(error));
+  const exitCode = error instanceof CliError ? error.exitCode : EXIT_CODES.ERROR;
+  process.exit(exitCode);
+}
+function withErrorHandler(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      handleError(error);
+    }
+  };
+}
+function withErrorHandlerSync(fn) {
+  return (...args) => {
+    try {
+      fn(...args);
+    } catch (error) {
+      handleError(error);
+    }
+  };
+}
+function debugLog(message, data) {
+  if (!isDebugMode()) {
+    return;
+  }
+  console.error(chalk.gray(`[DEBUG] ${message}`));
+  if (data !== void 0) {
+    console.error(chalk.gray(JSON.stringify(data, null, 2)));
+  }
+}
+function warnLog(message) {
+  console.error(chalk.yellow(`Warning: ${message}`));
+}
+function successLog(message) {
+  console.log(chalk.green(message));
+}
+function infoLog(message) {
+  console.log(chalk.cyan(message));
+}
+export {
+  AuthError,
+  CliError,
+  ConfigError,
+  EXIT_CODES,
+  NetworkError,
+  NotFoundError,
+  ValidationError,
+  debugLog,
+  formatError,
+  handleError,
+  infoLog,
+  isDebugMode,
+  successLog,
+  warnLog,
+  withErrorHandler,
+  withErrorHandlerSync
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/cli/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/middleware/error-handler.ts"],"sourcesContent":["/**\n * Error Handler Middleware\n *\n * Provides consistent error handling and formatting across all CLI commands.\n * Supports debug mode for detailed stack traces.\n */\n\nimport chalk from 'chalk';\nimport { CONFIG_ENV_VARS } from '../config/types.js';\n\n/**\n * Standard exit codes\n */\nexport const EXIT_CODES = {\n  /** Successful execution */\n  SUCCESS: 0,\n  /** General error */\n  ERROR: 1,\n  /** Authentication error */\n  AUTH_ERROR: 2,\n  /** Configuration error */\n  CONFIG_ERROR: 3,\n  /** Network/API error */\n  NETWORK_ERROR: 4,\n  /** Not found error */\n  NOT_FOUND: 5,\n  /** Validation error */\n  VALIDATION_ERROR: 6,\n} as const;\n\nexport type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];\n\n/**\n * Custom error class for CLI errors with exit codes\n */\nexport class CliError extends Error {\n  constructor(\n    message: string,\n    public readonly exitCode: ExitCode = EXIT_CODES.ERROR,\n    public readonly hint?: string\n  ) {\n    super(message);\n    this.name = 'CliError';\n  }\n}\n\n/**\n * Authentication error\n */\nexport class AuthError extends CliError {\n  constructor(message: string = 'Not authenticated') {\n    super(message, EXIT_CODES.AUTH_ERROR, 'Run `specforge login` to authenticate');\n  }\n}\n\n/**\n * Configuration error\n */\nexport class ConfigError extends CliError {\n  constructor(message: string, hint?: string) {\n    super(message, EXIT_CODES.CONFIG_ERROR, hint);\n  }\n}\n\n/**\n * Network/API error\n */\nexport class NetworkError extends CliError {\n  constructor(message: string, hint?: string) {\n    super(\n      message,\n      EXIT_CODES.NETWORK_ERROR,\n      hint || 'Check your internet connection and try again'\n    );\n  }\n}\n\n/**\n * Not found error\n */\nexport class NotFoundError extends CliError {\n  constructor(resource: string, identifier?: string) {\n    const message = identifier\n      ? `${resource} not found: ${identifier}`\n      : `${resource} not found`;\n    super(message, EXIT_CODES.NOT_FOUND);\n  }\n}\n\n/**\n * Validation error\n */\nexport class ValidationError extends CliError {\n  constructor(message: string, hint?: string) {\n    super(message, EXIT_CODES.VALIDATION_ERROR, hint);\n  }\n}\n\n/**\n * Check if debug mode is enabled\n */\nexport function isDebugMode(): boolean {\n  return process.env[CONFIG_ENV_VARS.DEBUG] === 'true';\n}\n\n/**\n * Format error for display\n *\n * @param error - Error to format\n * @returns Formatted error string\n */\nexport function formatError(error: unknown): string {\n  if (error instanceof CliError) {\n    let output = chalk.red(`Error: ${error.message}`);\n\n    if (error.hint) {\n      output += '\\n' + chalk.yellow(`Hint: ${error.hint}`);\n    }\n\n    if (isDebugMode() && error.stack) {\n      output += '\\n\\n' + chalk.gray(error.stack);\n    }\n\n    return output;\n  }\n\n  if (error instanceof Error) {\n    let output = chalk.red(`Error: ${error.message}`);\n\n    if (isDebugMode() && error.stack) {\n      output += '\\n\\n' + chalk.gray(error.stack);\n    }\n\n    return output;\n  }\n\n  return chalk.red(`Error: ${String(error)}`);\n}\n\n/**\n * Handle error and exit process\n *\n * @param error - Error to handle\n */\nexport function handleError(error: unknown): never {\n  console.error(formatError(error));\n\n  const exitCode =\n    error instanceof CliError ? error.exitCode : EXIT_CODES.ERROR;\n\n  process.exit(exitCode);\n}\n\n/**\n * Wrap an async function with error handling\n *\n * Use this to wrap command action handlers for automatic error handling.\n *\n * @param fn - Async function to wrap\n * @returns Wrapped function that handles errors\n *\n * @example\n * ```typescript\n * program\n *   .command('status')\n *   .action(withErrorHandler(async () => {\n *     // If this throws, error is caught and formatted\n *     const data = await api.getStatus();\n *   }));\n * ```\n */\nexport function withErrorHandler<T extends unknown[], R>(\n  fn: (...args: T) => Promise<R>\n): (...args: T) => Promise<void> {\n  return async (...args: T): Promise<void> => {\n    try {\n      await fn(...args);\n    } catch (error) {\n      handleError(error);\n    }\n  };\n}\n\n/**\n * Wrap a sync function with error handling\n *\n * @param fn - Sync function to wrap\n * @returns Wrapped function that handles errors\n */\nexport function withErrorHandlerSync<T extends unknown[], R>(\n  fn: (...args: T) => R\n): (...args: T) => void {\n  return (...args: T): void => {\n    try {\n      fn(...args);\n    } catch (error) {\n      handleError(error);\n    }\n  };\n}\n\n/**\n * Log debug information (only in debug mode)\n *\n * @param message - Message to log\n * @param data - Optional data to log\n */\nexport function debugLog(message: string, data?: unknown): void {\n  if (!isDebugMode()) {\n    return;\n  }\n\n  console.error(chalk.gray(`[DEBUG] ${message}`));\n\n  if (data !== undefined) {\n    console.error(chalk.gray(JSON.stringify(data, null, 2)));\n  }\n}\n\n/**\n * Log warning message\n *\n * @param message - Warning message\n */\nexport function warnLog(message: string): void {\n  console.error(chalk.yellow(`Warning: ${message}`));\n}\n\n/**\n * Log success message\n *\n * @param message - Success message\n */\nexport function successLog(message: string): void {\n  console.log(chalk.green(message));\n}\n\n/**\n * Log info message\n *\n * @param message - Info message\n */\nexport function infoLog(message: string): void {\n  console.log(chalk.cyan(message));\n}\n"],"mappings":"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","names":[]}

package/dist/cli/middleware/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CLI Middleware Module
+ */
+export * from './auth-guard.js';
+export * from './error-handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/middleware/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC"}

package/dist/cli/middleware/index.js

@@ -0,0 +1,3 @@
+export * from "./auth-guard.js";
+export * from "./error-handler.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/middleware/index.ts"],"sourcesContent":["/**\n * CLI Middleware Module\n */\n\nexport * from './auth-guard.js';\nexport * from './error-handler.js';\n"],"mappings":"AAIA,cAAc;AACd,cAAc;","names":[]}

package/dist/cli/templates/agents/content/core/sfag-orchestrator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SFAG-Orchestrator Agent Template v2
+ *
+ * Strategic task decomposition with concrete decision trees.
+ * Knows when to delegate, to whom, and in what order.
+ */
+import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
+export declare const SFAG_ORCHESTRATOR: AgentTemplate;
+//# sourceMappingURL=sfag-orchestrator.d.ts.map

package/dist/cli/templates/agents/content/core/sfag-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfag-orchestrator.d.ts","sourceRoot":"","sources":["../../../../../../src/cli/templates/agents/content/core/sfag-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8CAA8C,CAAC;AAElF,eAAO,MAAM,iBAAiB,EAAE,aA2J/B,CAAC"}