@specforge/cli 0.1.0

package/dist/client/api-client.js

@@ -0,0 +1,105 @@
+import { RemoteTransport } from "../transport/remote.js";
+const DEFAULT_TIMEOUT = 3e4;
+class ApiClient {
+  config;
+  transport;
+  sessionId;
+  /**
+   * @param config - resolved MCP config (URL, key, debug)
+   * @param options - optional client options; `origin` sets the
+   *   `X-SpecForge-Origin` header (M9.7), defaulting to `mcp` (agent traffic).
+   *   The human CLI surface ({@link createCliClient} / the feedback command)
+   *   passes `cli`.
+   */
+  constructor(config, options = {}) {
+    this.config = config;
+    this.transport = new RemoteTransport({
+      apiUrl: config.apiUrl,
+      apiKey: config.apiKey,
+      debug: config.debug,
+      origin: options.origin
+    });
+    this.sessionId = crypto.randomUUID();
+  }
+  /**
+   * Get the underlying transport for direct use by tool handlers
+   */
+  getTransport() {
+    return this.transport;
+  }
+  /**
+   * Get the session ID for this MCP connection
+   * Used for working context management
+   */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Make an API call to SpecForge
+   *
+   * @param operation - Name of the operation to execute
+   * @param args - Arguments for the operation
+   * @param options - Optional request configuration
+   * @returns Promise resolving to the operation result
+   * @throws {Error} If the request fails or returns an error
+   *
+   * @example
+   * ```typescript
+   * // List projects
+   * const result = await client.call('list_projects');
+   *
+   * // Get a specific ticket
+   * const ticket = await client.call('get_ticket', { ticketId: 'ticket123' });
+   * ```
+   */
+  async call(operation, args = {}, _options = {}) {
+    const body = await this.transport.execute(operation, args);
+    if (body && typeof body === "object") {
+      const rec = body;
+      if (rec.error !== void 0 && rec.error !== null) {
+        throw new Error(`Operation failed: ${String(rec.error)}`);
+      }
+      if ("data" in rec) {
+        return rec.data;
+      }
+    }
+    return body;
+  }
+  /**
+   * Validate the configured API key
+   *
+   * Makes a lightweight call to verify the API key is valid and
+   * returns the associated user information.
+   *
+   * @returns Promise resolving to validation result
+   *
+   * @example
+   * ```typescript
+   * const result = await client.validateApiKey();
+   * if (result.valid) {
+   *   console.log('Authenticated as:', result.userId);
+   * } else {
+   *   console.error('Invalid API key:', result.message);
+   * }
+   * ```
+   */
+  async validateApiKey() {
+    try {
+      const result = await this.call("validate_api_key");
+      return {
+        valid: true,
+        userId: result.userId,
+        permissions: result.permissions
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+}
+export {
+  ApiClient
+};
+//# sourceMappingURL=api-client.js.map

package/dist/client/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/api-client.ts"],"sourcesContent":["/**\n * SpecForge API Client\n *\n * HTTP client for communicating with the SpecForge API Gateway.\n * Handles authentication, request/response formatting, and error handling.\n */\n\nimport { McpConfig } from '../config/index.js';\nimport type { ITransport, TransportOrigin } from '../transport/interface.js';\nimport { RemoteTransport } from '../transport/remote.js';\n\n/**\n * API response structure returned by SpecForge API\n */\nexport interface ApiResponse<T = unknown> {\n  /** Response data on success */\n  data?: T;\n  /** Error message on failure */\n  error?: string;\n}\n\n/**\n * Result of API key validation\n */\nexport interface ApiKeyValidationResult {\n  /** Whether the API key is valid */\n  valid: boolean;\n  /** User ID associated with the key (if valid) */\n  userId?: string;\n  /** Permissions granted to the key (if valid) */\n  permissions?: {\n    read?: boolean;\n    write?: boolean;\n    admin?: boolean;\n  };\n  /** Error message (if invalid) */\n  message?: string;\n}\n\n/**\n * Options for API requests\n */\nexport interface ApiRequestOptions {\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Additional headers to include */\n  headers?: Record<string, string>;\n  /** Signal for aborting the request */\n  signal?: AbortSignal;\n}\n\n/**\n * Default request timeout (30 seconds)\n */\nconst DEFAULT_TIMEOUT = 30000;\n\n/**\n * API Client for SpecForge\n *\n * @example\n * ```typescript\n * import { getConfig } from './config/index.js';\n * import { ApiClient } from './client/api-client.js';\n *\n * const config = getConfig();\n * const client = new ApiClient(config);\n *\n * // Make an API call\n * const projects = await client.call('list_projects', { userId: 'user123' });\n * ```\n */\nexport class ApiClient {\n  private config: McpConfig;\n  private transport: ITransport;\n  private sessionId: string;\n\n  /**\n   * @param config - resolved MCP config (URL, key, debug)\n   * @param options - optional client options; `origin` sets the\n   *   `X-SpecForge-Origin` header (M9.7), defaulting to `mcp` (agent traffic).\n   *   The human CLI surface ({@link createCliClient} / the feedback command)\n   *   passes `cli`.\n   */\n  constructor(config: McpConfig, options: { origin?: TransportOrigin } = {}) {\n    this.config = config;\n    this.transport = new RemoteTransport({\n      apiUrl: config.apiUrl,\n      apiKey: config.apiKey,\n      debug: config.debug,\n      origin: options.origin,\n    });\n    // Generate a unique session ID for this MCP connection\n    this.sessionId = crypto.randomUUID();\n  }\n\n  /**\n   * Get the underlying transport for direct use by tool handlers\n   */\n  getTransport(): ITransport {\n    return this.transport;\n  }\n\n  /**\n   * Get the session ID for this MCP connection\n   * Used for working context management\n   */\n  getSessionId(): string {\n    return this.sessionId;\n  }\n\n  /**\n   * Make an API call to SpecForge\n   *\n   * @param operation - Name of the operation to execute\n   * @param args - Arguments for the operation\n   * @param options - Optional request configuration\n   * @returns Promise resolving to the operation result\n   * @throws {Error} If the request fails or returns an error\n   *\n   * @example\n   * ```typescript\n   * // List projects\n   * const result = await client.call('list_projects');\n   *\n   * // Get a specific ticket\n   * const ticket = await client.call('get_ticket', { ticketId: 'ticket123' });\n   * ```\n   */\n  async call<T = unknown>(\n    operation: string,\n    args: Record<string, unknown> = {},\n    _options: ApiRequestOptions = {}\n  ): Promise<T> {\n    // `/cli` semantics (M9, approach A): the transport returns the raw body;\n    // unwrap the `{ data }` envelope and surface `{ error }` as a throw. A raw\n    // body without `data`/`error` (e.g. a /local M8 envelope read via the agent\n    // path) passes through untouched.\n    const body = await this.transport.execute<unknown>(operation, args);\n    if (body && typeof body === 'object') {\n      const rec = body as { data?: unknown; error?: unknown };\n      if (rec.error !== undefined && rec.error !== null) {\n        throw new Error(`Operation failed: ${String(rec.error)}`);\n      }\n      if ('data' in rec) {\n        return rec.data as T;\n      }\n    }\n    return body as T;\n  }\n\n  /**\n   * Validate the configured API key\n   *\n   * Makes a lightweight call to verify the API key is valid and\n   * returns the associated user information.\n   *\n   * @returns Promise resolving to validation result\n   *\n   * @example\n   * ```typescript\n   * const result = await client.validateApiKey();\n   * if (result.valid) {\n   *   console.log('Authenticated as:', result.userId);\n   * } else {\n   *   console.error('Invalid API key:', result.message);\n   * }\n   * ```\n   */\n  async validateApiKey(): Promise<ApiKeyValidationResult> {\n    try {\n      const result = await this.call<{\n        userId: string;\n        permissions: {\n          read?: boolean;\n          write?: boolean;\n          admin?: boolean;\n        };\n      }>('validate_api_key');\n\n      return {\n        valid: true,\n        userId: result.userId,\n        permissions: result.permissions,\n      };\n    } catch (error) {\n      return {\n        valid: false,\n        message: error instanceof Error ? error.message : 'Unknown error',\n      };\n    }\n  }\n\n}\n"],"mappings":"AASA,SAAS,uBAAuB;AA6ChC,MAAM,kBAAkB;AAiBjB,MAAM,UAAU;AAAA,EACb;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASR,YAAY,QAAmB,UAAwC,CAAC,GAAG;AACzE,SAAK,SAAS;AACd,SAAK,YAAY,IAAI,gBAAgB;AAAA,MACnC,QAAQ,OAAO;AAAA,MACf,QAAQ,OAAO;AAAA,MACf,OAAO,OAAO;AAAA,MACd,QAAQ,QAAQ;AAAA,IAClB,CAAC;AAED,SAAK,YAAY,OAAO,WAAW;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA,EAKA,eAA2B;AACzB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,eAAuB;AACrB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBA,MAAM,KACJ,WACA,OAAgC,CAAC,GACjC,WAA8B,CAAC,GACnB;AAKZ,UAAM,OAAO,MAAM,KAAK,UAAU,QAAiB,WAAW,IAAI;AAClE,QAAI,QAAQ,OAAO,SAAS,UAAU;AACpC,YAAM,MAAM;AACZ,UAAI,IAAI,UAAU,UAAa,IAAI,UAAU,MAAM;AACjD,cAAM,IAAI,MAAM,qBAAqB,OAAO,IAAI,KAAK,CAAC,EAAE;AAAA,MAC1D;AACA,UAAI,UAAU,KAAK;AACjB,eAAO,IAAI;AAAA,MACb;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBA,MAAM,iBAAkD;AACtD,QAAI;AACF,YAAM,SAAS,MAAM,KAAK,KAOvB,kBAAkB;AAErB,aAAO;AAAA,QACL,OAAO;AAAA,QACP,QAAQ,OAAO;AAAA,QACf,aAAa,OAAO;AAAA,MACtB;AAAA,IACF,SAAS,OAAO;AACd,aAAO;AAAA,QACL,OAAO;AAAA,QACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MACpD;AAAA,IACF;AAAA,EACF;AAEF;","names":[]}

package/dist/client/cli-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CLI-direct client (M9 `/cli`)
+ *
+ * The SpecForge CLI's HUMAN commands (`switch` / `doctor` / `init` / `debug` /
+ * `members` / `invitations`) talk to the mcp-handler `/cli` route — plain,
+ * guidance-free ops that return `{ data }` (which the shared transport unwraps
+ * to the raw result). This is distinct from the AGENT path: the stdio MCP
+ * server proxies the 21 agent tools to `/local` (envelopes).
+ *
+ * `/cli` lives on the same host as `/local`, on the `/cli` path — so the client
+ * is just an {@link ApiClient} pointed at the derived URL.
+ */
+import { ApiClient } from './api-client.js';
+/** Derive the `/cli` REST URL from the `/local` MCP URL (same host, `/cli` path). */
+export declare function resolveCliUrl(apiUrl: string): string;
+/**
+ * Build a client for the CLI's human commands → mcp-handler `/cli` route.
+ *
+ * @param config - resolved config carrying the authenticated key + `/local` URL
+ */
+export declare function createCliClient(config: {
+    apiKey: string;
+    apiUrl: string;
+    debug?: boolean;
+}): ApiClient;
+//# sourceMappingURL=cli-client.d.ts.map

package/dist/client/cli-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-client.d.ts","sourceRoot":"","sources":["../../src/client/cli-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,SAAS,CAUZ"}

package/dist/client/cli-client.js

@@ -0,0 +1,20 @@
+import { ApiClient } from "./api-client.js";
+function resolveCliUrl(apiUrl) {
+  return apiUrl.replace(/\/local\/?$/, "/cli");
+}
+function createCliClient(config) {
+  return new ApiClient(
+    {
+      apiKey: config.apiKey,
+      apiUrl: resolveCliUrl(config.apiUrl),
+      debug: config.debug ?? false
+    },
+    // M9.7: human CLI surface → `X-SpecForge-Origin: cli`.
+    { origin: "cli" }
+  );
+}
+export {
+  createCliClient,
+  resolveCliUrl
+};
+//# sourceMappingURL=cli-client.js.map

package/dist/client/cli-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/cli-client.ts"],"sourcesContent":["/**\n * CLI-direct client (M9 `/cli`)\n *\n * The SpecForge CLI's HUMAN commands (`switch` / `doctor` / `init` / `debug` /\n * `members` / `invitations`) talk to the mcp-handler `/cli` route — plain,\n * guidance-free ops that return `{ data }` (which the shared transport unwraps\n * to the raw result). This is distinct from the AGENT path: the stdio MCP\n * server proxies the 21 agent tools to `/local` (envelopes).\n *\n * `/cli` lives on the same host as `/local`, on the `/cli` path — so the client\n * is just an {@link ApiClient} pointed at the derived URL.\n */\n\nimport { ApiClient } from './api-client.js';\n\n/** Derive the `/cli` REST URL from the `/local` MCP URL (same host, `/cli` path). */\nexport function resolveCliUrl(apiUrl: string): string {\n  return apiUrl.replace(/\\/local\\/?$/, '/cli');\n}\n\n/**\n * Build a client for the CLI's human commands → mcp-handler `/cli` route.\n *\n * @param config - resolved config carrying the authenticated key + `/local` URL\n */\nexport function createCliClient(config: {\n  apiKey: string;\n  apiUrl: string;\n  debug?: boolean;\n}): ApiClient {\n  return new ApiClient(\n    {\n      apiKey: config.apiKey,\n      apiUrl: resolveCliUrl(config.apiUrl),\n      debug: config.debug ?? false,\n    },\n    // M9.7: human CLI surface → `X-SpecForge-Origin: cli`.\n    { origin: 'cli' },\n  );\n}\n"],"mappings":"AAaA,SAAS,iBAAiB;AAGnB,SAAS,cAAc,QAAwB;AACpD,SAAO,OAAO,QAAQ,eAAe,MAAM;AAC7C;AAOO,SAAS,gBAAgB,QAIlB;AACZ,SAAO,IAAI;AAAA,IACT;AAAA,MACE,QAAQ,OAAO;AAAA,MACf,QAAQ,cAAc,OAAO,MAAM;AAAA,MACnC,OAAO,OAAO,SAAS;AAAA,IACzB;AAAA;AAAA,IAEA,EAAE,QAAQ,MAAM;AAAA,EAClB;AACF;","names":[]}

package/dist/config/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MCP Configuration Module
+ *
+ * Loads and validates configuration from environment variables for
+ * the SpecForge MCP server.
+ */
+import type { OutputFormat } from '../cli/config/types.js';
+/**
+ * MCP Server configuration
+ */
+export interface McpConfig {
+    /** API key for authentication (format: sf_live_*) */
+    apiKey: string;
+    /** API Gateway URL for the SpecForge backend */
+    apiUrl: string;
+    /** Enable debug logging */
+    debug: boolean;
+    /**
+     * Wire encoding for the server's responses to the agent (TOON default, JSON
+     * when configured). Resolved at the entry point from the CLI config
+     * (env > project > global > default); `createServer` falls back to `'toon'`.
+     */
+    mcpOutputFormat?: OutputFormat;
+}
+/**
+ * Environment variable names
+ */
+export declare const ENV_VARS: {
+    readonly API_KEY: "SPECFORGE_API_KEY";
+    readonly API_URL: "SPECFORGE_API_URL";
+    readonly DEBUG: "SPECFORGE_DEBUG";
+};
+/**
+ * Load configuration from environment variables
+ *
+ * @throws {Error} If required environment variables are missing
+ * @returns {McpConfig} Loaded configuration
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * console.log(config.apiUrl);
+ * ```
+ */
+export declare function loadConfig(): McpConfig;
+/**
+ * Validate configuration values
+ *
+ * @param config - Configuration to validate
+ * @throws {Error} If configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfig();
+ * validateConfig(config); // Throws if invalid
+ * ```
+ */
+export declare function validateConfig(config: McpConfig): void;
+/**
+ * Load and validate configuration in one step
+ *
+ * @throws {Error} If configuration is missing or invalid
+ * @returns {McpConfig} Validated configuration
+ *
+ * @example
+ * ```typescript
+ * const config = getConfig();
+ * // Configuration is guaranteed to be valid
+ * ```
+ */
+export declare function getConfig(): McpConfig;
+/**
+ * Check if configuration is available without throwing
+ *
+ * @returns {boolean} True if all required environment variables are set
+ */
+export declare function isConfigured(): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,eAAe,CAAC,EAAE,YAAY,CAAC;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;CAIX,CAAC;AAOX;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,IAAI,SAAS,CAqBtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuCtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAIrC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/dist/config/index.js

@@ -0,0 +1,79 @@
+import { CHANNEL } from "../channel.js";
+const ENV_VARS = {
+  API_KEY: "SPECFORGE_API_KEY",
+  API_URL: "SPECFORGE_API_URL",
+  // Optional - for self-hosted deployments
+  DEBUG: "SPECFORGE_DEBUG"
+};
+const API_KEY_PREFIX = "sf_live_";
+function loadConfig() {
+  const apiKey = process.env[ENV_VARS.API_KEY];
+  const apiUrl = process.env[ENV_VARS.API_URL] || CHANNEL.endpoint.primary;
+  const debug = process.env[ENV_VARS.DEBUG] === "true";
+  if (!apiKey) {
+    throw new Error(
+      `${ENV_VARS.API_KEY} environment variable is required.
+Get your API key from the SpecForge webapp:
+  1. Go to Settings > API Keys
+  2. Create a new API key
+  3. Copy the key (starts with sf_live_)
+  4. Set: export ${ENV_VARS.API_KEY}="your_key"`
+    );
+  }
+  return {
+    apiKey,
+    apiUrl,
+    debug
+  };
+}
+function validateConfig(config) {
+  if (!config.apiKey.startsWith(API_KEY_PREFIX)) {
+    throw new Error(
+      `Invalid API key format.
+  Expected: Key starting with "${API_KEY_PREFIX}"
+  Got: "${config.apiKey.substring(0, 10)}..."
+
+Make sure you copied the full API key from the SpecForge webapp.`
+    );
+  }
+  if (config.apiKey.length < API_KEY_PREFIX.length + 20) {
+    throw new Error(
+      `Invalid API key length.
+  API keys should be at least 28 characters long.
+  Make sure you copied the full key.`
+    );
+  }
+  try {
+    const url = new URL(config.apiUrl);
+    if (url.protocol !== "https:" && !config.debug) {
+      console.warn(
+        `Warning: API URL is not using HTTPS: ${config.apiUrl}
+  This is allowed in debug mode but not recommended for production.`
+      );
+    }
+  } catch {
+    throw new Error(
+      `Invalid API URL format.
+  Expected: Valid URL (e.g., https://api.example.com/prod)
+  Got: "${config.apiUrl}"
+
+Make sure you copied the full URL including the protocol.`
+    );
+  }
+}
+function getConfig() {
+  const config = loadConfig();
+  validateConfig(config);
+  return config;
+}
+function isConfigured() {
+  return !!process.env[ENV_VARS.API_KEY];
+}
+export {
+  ENV_VARS,
+  getConfig,
+  isConfigured,
+  loadConfig,
+  validateConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/index.ts"],"sourcesContent":["/**\n * MCP Configuration Module\n *\n * Loads and validates configuration from environment variables for\n * the SpecForge MCP server.\n */\n\nimport { CHANNEL } from '../channel.js';\nimport type { OutputFormat } from '../cli/config/types.js';\n\n/**\n * MCP Server configuration\n */\nexport interface McpConfig {\n  /** API key for authentication (format: sf_live_*) */\n  apiKey: string;\n  /** API Gateway URL for the SpecForge backend */\n  apiUrl: string;\n  /** Enable debug logging */\n  debug: boolean;\n  /**\n   * Wire encoding for the server's responses to the agent (TOON default, JSON\n   * when configured). Resolved at the entry point from the CLI config\n   * (env > project > global > default); `createServer` falls back to `'toon'`.\n   */\n  mcpOutputFormat?: OutputFormat;\n}\n\n/**\n * Environment variable names\n */\nexport const ENV_VARS = {\n  API_KEY: 'SPECFORGE_API_KEY',\n  API_URL: 'SPECFORGE_API_URL', // Optional - for self-hosted deployments\n  DEBUG: 'SPECFORGE_DEBUG',\n} as const;\n\n/**\n * API key prefix for validation\n */\nconst API_KEY_PREFIX = 'sf_live_';\n\n/**\n * Load configuration from environment variables\n *\n * @throws {Error} If required environment variables are missing\n * @returns {McpConfig} Loaded configuration\n *\n * @example\n * ```typescript\n * const config = loadConfig();\n * console.log(config.apiUrl);\n * ```\n */\nexport function loadConfig(): McpConfig {\n  const apiKey = process.env[ENV_VARS.API_KEY];\n  const apiUrl = process.env[ENV_VARS.API_URL] || CHANNEL.endpoint.primary;\n  const debug = process.env[ENV_VARS.DEBUG] === 'true';\n\n  if (!apiKey) {\n    throw new Error(\n      `${ENV_VARS.API_KEY} environment variable is required.\\n` +\n        'Get your API key from the SpecForge webapp:\\n' +\n        '  1. Go to Settings > API Keys\\n' +\n        '  2. Create a new API key\\n' +\n        '  3. Copy the key (starts with sf_live_)\\n' +\n        `  4. Set: export ${ENV_VARS.API_KEY}=\"your_key\"`\n    );\n  }\n\n  return {\n    apiKey,\n    apiUrl,\n    debug,\n  };\n}\n\n/**\n * Validate configuration values\n *\n * @param config - Configuration to validate\n * @throws {Error} If configuration is invalid\n *\n * @example\n * ```typescript\n * const config = loadConfig();\n * validateConfig(config); // Throws if invalid\n * ```\n */\nexport function validateConfig(config: McpConfig): void {\n  // Validate API key format\n  if (!config.apiKey.startsWith(API_KEY_PREFIX)) {\n    throw new Error(\n      `Invalid API key format.\\n` +\n        `  Expected: Key starting with \"${API_KEY_PREFIX}\"\\n` +\n        `  Got: \"${config.apiKey.substring(0, 10)}...\"\\n` +\n        '\\nMake sure you copied the full API key from the SpecForge webapp.'\n    );\n  }\n\n  // Validate API key minimum length (prefix + at least 20 chars)\n  if (config.apiKey.length < API_KEY_PREFIX.length + 20) {\n    throw new Error(\n      `Invalid API key length.\\n` +\n        '  API keys should be at least 28 characters long.\\n' +\n        '  Make sure you copied the full key.'\n    );\n  }\n\n  // Validate API URL format\n  try {\n    const url = new URL(config.apiUrl);\n\n    // Must be HTTPS in production\n    if (url.protocol !== 'https:' && !config.debug) {\n      console.warn(\n        `Warning: API URL is not using HTTPS: ${config.apiUrl}\\n` +\n          '  This is allowed in debug mode but not recommended for production.'\n      );\n    }\n  } catch {\n    throw new Error(\n      `Invalid API URL format.\\n` +\n        `  Expected: Valid URL (e.g., https://api.example.com/prod)\\n` +\n        `  Got: \"${config.apiUrl}\"\\n` +\n        '\\nMake sure you copied the full URL including the protocol.'\n    );\n  }\n}\n\n/**\n * Load and validate configuration in one step\n *\n * @throws {Error} If configuration is missing or invalid\n * @returns {McpConfig} Validated configuration\n *\n * @example\n * ```typescript\n * const config = getConfig();\n * // Configuration is guaranteed to be valid\n * ```\n */\nexport function getConfig(): McpConfig {\n  const config = loadConfig();\n  validateConfig(config);\n  return config;\n}\n\n/**\n * Check if configuration is available without throwing\n *\n * @returns {boolean} True if all required environment variables are set\n */\nexport function isConfigured(): boolean {\n  return !!process.env[ENV_VARS.API_KEY];\n}\n"],"mappings":"AAOA,SAAS,eAAe;AAwBjB,MAAM,WAAW;AAAA,EACtB,SAAS;AAAA,EACT,SAAS;AAAA;AAAA,EACT,OAAO;AACT;AAKA,MAAM,iBAAiB;AAchB,SAAS,aAAwB;AACtC,QAAM,SAAS,QAAQ,IAAI,SAAS,OAAO;AAC3C,QAAM,SAAS,QAAQ,IAAI,SAAS,OAAO,KAAK,QAAQ,SAAS;AACjE,QAAM,QAAQ,QAAQ,IAAI,SAAS,KAAK,MAAM;AAE9C,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR,GAAG,SAAS,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA,mBAKG,SAAS,OAAO;AAAA,IACxC;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAcO,SAAS,eAAe,QAAyB;AAEtD,MAAI,CAAC,OAAO,OAAO,WAAW,cAAc,GAAG;AAC7C,UAAM,IAAI;AAAA,MACR;AAAA,iCACoC,cAAc;AAAA,UACrC,OAAO,OAAO,UAAU,GAAG,EAAE,CAAC;AAAA;AAAA;AAAA,IAE7C;AAAA,EACF;AAGA,MAAI,OAAO,OAAO,SAAS,eAAe,SAAS,IAAI;AACrD,UAAM,IAAI;AAAA,MACR;AAAA;AAAA;AAAA,IAGF;AAAA,EACF;AAGA,MAAI;AACF,UAAM,MAAM,IAAI,IAAI,OAAO,MAAM;AAGjC,QAAI,IAAI,aAAa,YAAY,CAAC,OAAO,OAAO;AAC9C,cAAQ;AAAA,QACN,wCAAwC,OAAO,MAAM;AAAA;AAAA,MAEvD;AAAA,IACF;AAAA,EACF,QAAQ;AACN,UAAM,IAAI;AAAA,MACR;AAAA;AAAA,UAEa,OAAO,MAAM;AAAA;AAAA;AAAA,IAE5B;AAAA,EACF;AACF;AAcO,SAAS,YAAuB;AACrC,QAAM,SAAS,WAAW;AAC1B,iBAAe,MAAM;AACrB,SAAO;AACT;AAOO,SAAS,eAAwB;AACtC,SAAO,CAAC,CAAC,QAAQ,IAAI,SAAS,OAAO;AACvC;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SpecForge MCP Server
+ *
+ * This is the main entry point for the SpecForge MCP (Model Context Protocol) server.
+ * It provides tools for AI agents to interact with SpecForge projects, specifications,
+ * epics, and tickets.
+ *
+ * @module @specforge/cli
+ */
+export { McpConfig, loadConfig, validateConfig, getConfig, isConfigured, ENV_VARS } from './config/index.js';
+export { ApiClient, ApiResponse, ApiKeyValidationResult, ApiRequestOptions } from './client/api-client.js';
+export { createServer, startServer } from './server.js';
+export { getTools, handleToolCall, handleToolCallSafe, Tool } from './tools/index.js';
+export { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, MCPErrorResponse, } from './validation/index.js';
+export * from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7G,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3G,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGtF,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAG/B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,73 @@
+import { McpConfig, loadConfig, validateConfig, getConfig, isConfigured, ENV_VARS } from "./config/index.js";
+import { ApiClient, ApiResponse, ApiKeyValidationResult, ApiRequestOptions } from "./client/api-client.js";
+import { createServer, startServer } from "./server.js";
+import { getTools, handleToolCall, handleToolCallSafe, Tool } from "./tools/index.js";
+import {
+  ValidationError,
+  ApiError,
+  validateToolArgs,
+  formatMCPError,
+  transformError,
+  MCPErrorResponse
+} from "./validation/index.js";
+export * from "./types/index.js";
+async function main() {
+  console.error("[INFO] SpecForge MCP server initializing...");
+  console.error("[INFO] Node version:", process.version);
+  console.error("[INFO] argv[1]:", process.argv[1]);
+  const { loadConfig: loadConfig2, validateConfig: validateConfig2 } = await import("./config/index.js");
+  const { createServer: createServer2, startServer: startServer2 } = await import("./server.js");
+  const { resolveConfig } = await import("./cli/config/index.js");
+  try {
+    console.error("[INFO] Loading configuration...");
+    const config = loadConfig2();
+    validateConfig2(config);
+    config.mcpOutputFormat = resolveConfig().mcpOutputFormat;
+    console.error("[INFO] Configuration loaded:", {
+      apiUrl: config.apiUrl,
+      apiKey: config.apiKey.substring(0, 15) + "...",
+      debug: config.debug
+    });
+    console.error("[INFO] Creating MCP server...");
+    const server = await createServer2(config);
+    console.error("[INFO] Starting MCP server (connecting to stdio transport)...");
+    await startServer2(server);
+    console.error("[INFO] MCP server started and connected successfully");
+  } catch (error) {
+    console.error("[ERROR] Failed to start MCP server:", error);
+    process.exit(1);
+  }
+}
+const entry = process.argv[1] ?? "";
+const isDirectRun = entry.endsWith("index.js") || entry.endsWith("index.ts") || entry.endsWith("specforge") || entry.endsWith("specforge-canary") || entry.includes("@specforge/cli") || entry.includes("@specforge/canary-cli");
+if (isDirectRun && !process.env.VITEST) {
+  main().catch((error) => {
+    console.error("[ERROR] Unhandled error:", error);
+    process.exit(1);
+  });
+}
+export {
+  ApiClient,
+  ApiError,
+  ApiKeyValidationResult,
+  ApiRequestOptions,
+  ApiResponse,
+  ENV_VARS,
+  MCPErrorResponse,
+  McpConfig,
+  Tool,
+  ValidationError,
+  createServer,
+  formatMCPError,
+  getConfig,
+  getTools,
+  handleToolCall,
+  handleToolCallSafe,
+  isConfigured,
+  loadConfig,
+  startServer,
+  transformError,
+  validateConfig,
+  validateToolArgs
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * SpecForge MCP Server\n *\n * This is the main entry point for the SpecForge MCP (Model Context Protocol) server.\n * It provides tools for AI agents to interact with SpecForge projects, specifications,\n * epics, and tickets.\n *\n * @module @specforge/cli\n */\n\n// Export configuration\nexport { McpConfig, loadConfig, validateConfig, getConfig, isConfigured, ENV_VARS } from './config/index.js';\n\n// Export API client\nexport { ApiClient, ApiResponse, ApiKeyValidationResult, ApiRequestOptions } from './client/api-client.js';\n\n// Export server\nexport { createServer, startServer } from './server.js';\n\n// Export tools\nexport { getTools, handleToolCall, handleToolCallSafe, Tool } from './tools/index.js';\n\n// Export validation\nexport {\n  ValidationError,\n  ApiError,\n  validateToolArgs,\n  formatMCPError,\n  transformError,\n  MCPErrorResponse,\n} from './validation/index.js';\n\n// Export types\nexport * from './types/index.js';\n\n// Main entry point\nasync function main(): Promise<void> {\n  // Always log startup info to stderr (MCP clients read stdout for protocol)\n  console.error('[INFO] SpecForge MCP server initializing...');\n  console.error('[INFO] Node version:', process.version);\n  console.error('[INFO] argv[1]:', process.argv[1]);\n\n  // Import dynamically to avoid circular dependency issues\n  const { loadConfig, validateConfig } = await import('./config/index.js');\n  const { createServer, startServer } = await import('./server.js');\n  const { resolveConfig } = await import('./cli/config/index.js');\n\n  try {\n    console.error('[INFO] Loading configuration...');\n    const config = loadConfig();\n    validateConfig(config);\n    // Honor the resolved MCP output format (env > project > global > default).\n    config.mcpOutputFormat = resolveConfig().mcpOutputFormat;\n\n    console.error('[INFO] Configuration loaded:', {\n      apiUrl: config.apiUrl,\n      apiKey: config.apiKey.substring(0, 15) + '...',\n      debug: config.debug,\n    });\n\n    console.error('[INFO] Creating MCP server...');\n    const server = await createServer(config);\n\n    console.error('[INFO] Starting MCP server (connecting to stdio transport)...');\n    await startServer(server);\n\n    console.error('[INFO] MCP server started and connected successfully');\n  } catch (error) {\n    console.error('[ERROR] Failed to start MCP server:', error);\n    process.exit(1);\n  }\n}\n\n// Run if executed directly (not when imported as a library).\n// In ESM, check via process.argv: matches node on dist/src entry, the\n// specforge / specforge-canary bins, and npx invocations via the published\n// packages (@specforge/cli stable, @specforge/canary-cli canary).\nconst entry = process.argv[1] ?? '';\nconst isDirectRun = entry.endsWith('index.js') ||\n                    entry.endsWith('index.ts') ||\n                    entry.endsWith('specforge') ||\n                    entry.endsWith('specforge-canary') ||\n                    entry.includes('@specforge/cli') ||\n                    entry.includes('@specforge/canary-cli');\n\nif (isDirectRun && !process.env.VITEST) {\n  main().catch((error) => {\n    console.error('[ERROR] Unhandled error:', error);\n    process.exit(1);\n  });\n}\n"],"mappings":"AAWA,SAAS,WAAW,YAAY,gBAAgB,WAAW,cAAc,gBAAgB;AAGzF,SAAS,WAAW,aAAa,wBAAwB,yBAAyB;AAGlF,SAAS,cAAc,mBAAmB;AAG1C,SAAS,UAAU,gBAAgB,oBAAoB,YAAY;AAGnE;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP,cAAc;AAGd,eAAe,OAAsB;AAEnC,UAAQ,MAAM,6CAA6C;AAC3D,UAAQ,MAAM,wBAAwB,QAAQ,OAAO;AACrD,UAAQ,MAAM,mBAAmB,QAAQ,KAAK,CAAC,CAAC;AAGhD,QAAM,EAAE,YAAAA,aAAY,gBAAAC,gBAAe,IAAI,MAAM,OAAO,mBAAmB;AACvE,QAAM,EAAE,cAAAC,eAAc,aAAAC,aAAY,IAAI,MAAM,OAAO,aAAa;AAChE,QAAM,EAAE,cAAc,IAAI,MAAM,OAAO,uBAAuB;AAE9D,MAAI;AACF,YAAQ,MAAM,iCAAiC;AAC/C,UAAM,SAASH,YAAW;AAC1B,IAAAC,gBAAe,MAAM;AAErB,WAAO,kBAAkB,cAAc,EAAE;AAEzC,YAAQ,MAAM,gCAAgC;AAAA,MAC5C,QAAQ,OAAO;AAAA,MACf,QAAQ,OAAO,OAAO,UAAU,GAAG,EAAE,IAAI;AAAA,MACzC,OAAO,OAAO;AAAA,IAChB,CAAC;AAED,YAAQ,MAAM,+BAA+B;AAC7C,UAAM,SAAS,MAAMC,cAAa,MAAM;AAExC,YAAQ,MAAM,+DAA+D;AAC7E,UAAMC,aAAY,MAAM;AAExB,YAAQ,MAAM,sDAAsD;AAAA,EACtE,SAAS,OAAO;AACd,YAAQ,MAAM,uCAAuC,KAAK;AAC1D,YAAQ,KAAK,CAAC;AAAA,EAChB;AACF;AAMA,MAAM,QAAQ,QAAQ,KAAK,CAAC,KAAK;AACjC,MAAM,cAAc,MAAM,SAAS,UAAU,KACzB,MAAM,SAAS,UAAU,KACzB,MAAM,SAAS,WAAW,KAC1B,MAAM,SAAS,kBAAkB,KACjC,MAAM,SAAS,gBAAgB,KAC/B,MAAM,SAAS,uBAAuB;AAE1D,IAAI,eAAe,CAAC,QAAQ,IAAI,QAAQ;AACtC,OAAK,EAAE,MAAM,CAAC,UAAU;AACtB,YAAQ,MAAM,4BAA4B,KAAK;AAC/C,YAAQ,KAAK,CAAC;AAAA,EAChB,CAAC;AACH;","names":["loadConfig","validateConfig","createServer","startServer"]}

package/dist/lib/format.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Format Utility Module
+ *
+ * Provides utilities for formatting response data as JSON or TOON format.
+ * TOON (Token Optimized Object Notation) is a human-readable format that
+ * uses fewer tokens than JSON while maintaining semantic clarity.
+ *
+ * @see MCI-014-03-format-utility-module
+ */
+/**
+ * Supported output formats for response data
+ */
+export type OutputFormat = 'json' | 'toon';
+/**
+ * Format response data as JSON or TOON.
+ *
+ * JSON format (default) returns the original data object unchanged,
+ * allowing the MCP protocol to handle JSON serialization.
+ *
+ * TOON format returns a human-readable string optimized for token efficiency.
+ *
+ * @param data - The data to format
+ * @param format - Output format ('json' or 'toon'), defaults to 'json'
+ * @returns Formatted data - original object for JSON, string for TOON
+ *
+ * @example
+ * ```typescript
+ * // JSON (default) - returns unchanged
+ * formatResponse({ id: "123" }) // returns { id: "123" }
+ *
+ * // TOON - returns formatted string
+ * formatResponse({ id: "123" }, 'toon')
+ * // returns "id: 123"
+ *
+ * // Complex objects
+ * formatResponse({
+ *   ticket: { id: "T-001", title: "Task", status: "done" }
+ * }, 'toon')
+ * // returns:
+ * // ticket.id: T-001
+ * // ticket.title: Task
+ * // ticket.status: done
+ * ```
+ */
+export declare function formatResponse<T>(data: T, format?: OutputFormat): string | T;
+/**
+ * Encode any value as a TOON string — always returns a string (M9 §2.6d.2).
+ *
+ * Unlike {@link formatResponse} (which returns the original object for the
+ * `'json'` branch), `formatToon` is the canonical wire encoder for the local
+ * MCP server: agent-bound responses over stdio are ALWAYS TOON. On encoder
+ * failure it logs once and falls back to pretty JSON — failing to encode a
+ * response is worse than slightly larger output, so it never throws.
+ *
+ * @param value - The value to encode (success envelope, error envelope, or stub)
+ * @returns A TOON string (or JSON string on encoder exception)
+ */
+export declare function formatToon<T>(value: T): string;
+/**
+ * Format an array of items with optional TOON tabular formatting
+ *
+ * For TOON format, arrays with homogeneous objects can be rendered
+ * in a more compact tabular format. This is useful for lists of
+ * tickets, epics, etc.
+ *
+ * @param items - Array of items to format
+ * @param format - Output format
+ * @returns Formatted items
+ *
+ * @example
+ * ```typescript
+ * formatArrayResponse([
+ *   { id: '1', status: 'done' },
+ *   { id: '2', status: 'pending' }
+ * ], 'toon')
+ * // Returns:
+ * // []:
+ * //   - id: 1
+ * //     status: done
+ * //   - id: 2
+ * //     status: pending
+ * ```
+ */
+export declare function formatArrayResponse<T>(items: T[], format?: OutputFormat): string | T[];
+/**
+ * Format an error response with consistent structure
+ *
+ * @param error - Error message or Error object
+ * @param code - Optional error code
+ * @param format - Output format
+ * @returns Formatted error response
+ *
+ * @example
+ * ```typescript
+ * formatErrorResponse('Not found', 'NOT_FOUND', 'toon')
+ * // Returns:
+ * // error: Not found
+ * // code: NOT_FOUND
+ * ```
+ */
+export declare function formatErrorResponse(error: string | Error, code?: string, format?: OutputFormat): string | {
+    error: string;
+    code?: string;
+};
+/**
+ * Format a success response with optional data
+ *
+ * @param message - Success message
+ * @param data - Optional additional data
+ * @param format - Output format
+ * @returns Formatted success response
+ *
+ * @example
+ * ```typescript
+ * formatSuccessResponse('Created', { id: '123' }, 'toon')
+ * // Returns:
+ * // success: true
+ * // message: Created
+ * // id: 123
+ * ```
+ */
+export declare function formatSuccessResponse<T extends Record<string, unknown>>(message: string, data?: T, format?: OutputFormat): string | {
+    success: true;
+    message: string;
+} & T;
+//# sourceMappingURL=format.d.ts.map

package/dist/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAmE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAE,YAAqB,GAAG,MAAM,GAAG,CAAC,CAcpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAW9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,GAAE,YAAqB,GAAG,MAAM,GAAG,CAAC,EAAE,CAE9F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,KAAK,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,MAAM,GAAE,YAAqB,GAC5B,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAO3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,CAAC,EACR,MAAM,GAAE,YAAqB,GAC5B,MAAM,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC,CAGjD"}

package/dist/lib/format.js

@@ -0,0 +1,71 @@
+import { encode as toonEncode } from "@toon-format/toon";
+const TOON_OPTIONS = {
+  indent: 2,
+  keyFolding: "safe"
+};
+function preprocessForToon(data) {
+  if (data === null || data === void 0) {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map(preprocessForToon);
+  }
+  if (typeof data === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (value === void 0) {
+        continue;
+      }
+      result[key] = preprocessForToon(value);
+    }
+    return result;
+  }
+  return data;
+}
+function formatResponse(data, format = "json") {
+  if (format === "json") {
+    return data;
+  }
+  try {
+    const processed = preprocessForToon(data);
+    return toonEncode(processed, TOON_OPTIONS);
+  } catch (error) {
+    console.error("TOON formatting failed, falling back to JSON:", error);
+    return data;
+  }
+}
+function formatToon(value) {
+  try {
+    const processed = preprocessForToon(value);
+    return toonEncode(processed, TOON_OPTIONS);
+  } catch (err) {
+    console.error(
+      `[toon] encode failed for value type ${typeof value}; falling back to JSON`,
+      err
+    );
+    return JSON.stringify(value, null, 2);
+  }
+}
+function formatArrayResponse(items, format = "json") {
+  return formatResponse(items, format);
+}
+function formatErrorResponse(error, code, format = "json") {
+  const errorMessage = error instanceof Error ? error.message : error;
+  const response = { error: errorMessage };
+  if (code) {
+    response.code = code;
+  }
+  return formatResponse(response, format);
+}
+function formatSuccessResponse(message, data, format = "json") {
+  const response = { success: true, message, ...data };
+  return formatResponse(response, format);
+}
+export {
+  formatArrayResponse,
+  formatErrorResponse,
+  formatResponse,
+  formatSuccessResponse,
+  formatToon
+};
+//# sourceMappingURL=format.js.map