@specforge/cli 0.1.0 → 0.2.5

package/dist/transport/remote.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/transport/remote.ts"],"sourcesContent":["/**\n * RemoteTransport — HTTP POST transport to SpecForge API Gateway\n *\n * Extracted from ApiClient.call() to implement ITransport.\n *\n * Endpoint resolution: when `config.apiUrl` matches `CHANNEL.endpoint.primary`\n * (i.e. no `SPECFORGE_API_URL` override is active), the transport delegates\n * to `resolveEndpoint` on the first call so the URL flows from the\n * canary-channel client probe (PLAN-canary-channel.md §D) — primary first,\n * fallback on DNS-class failure, cached for 5 min. On a 401/403 the cache\n * is invalidated so the next call re-probes.\n */\n\nimport type { ITransport, TransportOrigin } from './interface.js';\nimport { CHANNEL } from '../channel.js';\nimport {\n  resolveEndpoint,\n  invalidate,\n  shouldInvalidateOnStatus,\n} from './resolve-endpoint.js';\n\nexport interface RemoteTransportConfig {\n  apiUrl: string;\n  apiKey: string;\n  debug?: boolean;\n  timeout?: number;\n  /**\n   * Calling context, sent as the `X-SpecForge-Origin` header (M9.7). Defaults to\n   * `mcp` (agent traffic); the human CLI surface passes `cli`.\n   */\n  origin?: TransportOrigin;\n}\n\nconst DEFAULT_TIMEOUT = 30000;\nconst MCP_CACHE_KEY = 'mcp-endpoint-cache';\n\nexport class RemoteTransport implements ITransport {\n  private config: RemoteTransportConfig;\n  /** Resolved URL pinned for this transport instance after the first call. */\n  private resolvedUrl: string | null = null;\n\n  constructor(config: RemoteTransportConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Pick the URL for this call. When `config.apiUrl` is the channel default,\n   * defer to the resolver. Otherwise (env override / explicit test fixture),\n   * use the configured URL directly.\n   */\n  private async pickUrl(): Promise<string> {\n    if (this.resolvedUrl) return this.resolvedUrl;\n    const useResolver = this.config.apiUrl === CHANNEL.endpoint.primary;\n    if (!useResolver) {\n      this.resolvedUrl = this.config.apiUrl;\n      return this.resolvedUrl;\n    }\n    this.resolvedUrl = await resolveEndpoint({\n      ...CHANNEL.endpoint,\n      cacheKey: MCP_CACHE_KEY,\n    });\n    if (this.config.debug) {\n      console.log(`[RemoteTransport] Resolved MCP endpoint: ${this.resolvedUrl}`);\n    }\n    return this.resolvedUrl;\n  }\n\n  async execute<T = unknown>(\n    operation: string,\n    args: Record<string, unknown>\n  ): Promise<T> {\n    const timeout = this.config.timeout ?? DEFAULT_TIMEOUT;\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n    try {\n      if (this.config.debug) {\n        console.log(`[RemoteTransport] Calling operation: ${operation}`, {\n          args: Object.keys(args),\n        });\n      }\n\n      const url = await this.pickUrl();\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          Authorization: `Bearer ${this.config.apiKey}`,\n          // M9.7: server-derived feedback/telemetry provenance. The backend\n          // reads this header (never a request-body `source` field).\n          'X-SpecForge-Origin': this.config.origin ?? 'mcp',\n        },\n        body: JSON.stringify({ operation, args }),\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeoutId);\n\n      if (!response.ok) {\n        // Auth failures may indicate the channel was rotated under us;\n        // invalidate so the next call re-probes.\n        if (\n          shouldInvalidateOnStatus(response.status) &&\n          this.config.apiUrl === CHANNEL.endpoint.primary\n        ) {\n          await invalidate(MCP_CACHE_KEY);\n          this.resolvedUrl = null;\n        }\n        const errorText = await response.text();\n        const statusMessage = getStatusMessage(response.status);\n        throw new Error(\n          `API request failed: ${response.status} ${statusMessage}\\n${errorText}`\n        );\n      }\n\n      // Transport is a dumb pipe (M9, approach A): return the raw response body.\n      // Response-shape interpretation lives in the consumer that owns the\n      // contract — `ApiClient.call` unwraps the `/cli` `{ data } / { error }`\n      // shape; the agent `/local` path interprets the M8 envelope itself.\n      const body = (await response.json()) as T;\n\n      if (this.config.debug) {\n        console.log(`[RemoteTransport] Operation completed: ${operation}`);\n      }\n\n      return body;\n    } catch (error) {\n      clearTimeout(timeoutId);\n      if (error instanceof Error && error.name === 'AbortError') {\n        throw new Error(\n          `Request timed out after ${timeout}ms for operation: ${operation}`\n        );\n      }\n      throw error;\n    }\n  }\n}\n\nfunction getStatusMessage(status: number): string {\n  const messages: Record<number, string> = {\n    400: 'Bad Request',\n    401: 'Unauthorized - Check your API key',\n    403: 'Forbidden - Insufficient permissions',\n    404: 'Not Found',\n    429: 'Too Many Requests - Rate limit exceeded',\n    500: 'Internal Server Error',\n    501: 'Not Implemented',\n    502: 'Bad Gateway',\n    503: 'Service Unavailable',\n    504: 'Gateway Timeout',\n  };\n  return messages[status] || 'Unknown Error';\n}\n"],"mappings":"AAcA,SAAS,eAAe;AACxB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAcP,MAAM,kBAAkB;AACxB,MAAM,gBAAgB;AAEf,MAAM,gBAAsC;AAAA,EACzC;AAAA;AAAA,EAEA,cAA6B;AAAA,EAErC,YAAY,QAA+B;AACzC,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAc,UAA2B;AACvC,QAAI,KAAK,YAAa,QAAO,KAAK;AAClC,UAAM,cAAc,KAAK,OAAO,WAAW,QAAQ,SAAS;AAC5D,QAAI,CAAC,aAAa;AAChB,WAAK,cAAc,KAAK,OAAO;AAC/B,aAAO,KAAK;AAAA,IACd;AACA,SAAK,cAAc,MAAM,gBAAgB;AAAA,MACvC,GAAG,QAAQ;AAAA,MACX,UAAU;AAAA,IACZ,CAAC;AACD,QAAI,KAAK,OAAO,OAAO;AACrB,cAAQ,IAAI,4CAA4C,KAAK,WAAW,EAAE;AAAA,IAC5E;AACA,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAM,QACJ,WACA,MACY;AACZ,UAAM,UAAU,KAAK,OAAO,WAAW;AACvC,UAAM,aAAa,IAAI,gBAAgB;AACvC,UAAM,YAAY,WAAW,MAAM,WAAW,MAAM,GAAG,OAAO;AAE9D,QAAI;AACF,UAAI,KAAK,OAAO,OAAO;AACrB,gBAAQ,IAAI,wCAAwC,SAAS,IAAI;AAAA,UAC/D,MAAM,OAAO,KAAK,IAAI;AAAA,QACxB,CAAC;AAAA,MACH;AAEA,YAAM,MAAM,MAAM,KAAK,QAAQ;AAC/B,YAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,eAAe,UAAU,KAAK,OAAO,MAAM;AAAA;AAAA;AAAA,UAG3C,sBAAsB,KAAK,OAAO,UAAU;AAAA,QAC9C;AAAA,QACA,MAAM,KAAK,UAAU,EAAE,WAAW,KAAK,CAAC;AAAA,QACxC,QAAQ,WAAW;AAAA,MACrB,CAAC;AAED,mBAAa,SAAS;AAEtB,UAAI,CAAC,SAAS,IAAI;AAGhB,YACE,yBAAyB,SAAS,MAAM,KACxC,KAAK,OAAO,WAAW,QAAQ,SAAS,SACxC;AACA,gBAAM,WAAW,aAAa;AAC9B,eAAK,cAAc;AAAA,QACrB;AACA,cAAM,YAAY,MAAM,SAAS,KAAK;AACtC,cAAM,gBAAgB,iBAAiB,SAAS,MAAM;AACtD,cAAM,IAAI;AAAA,UACR,uBAAuB,SAAS,MAAM,IAAI,aAAa;AAAA,EAAK,SAAS;AAAA,QACvE;AAAA,MACF;AAMA,YAAM,OAAQ,MAAM,SAAS,KAAK;AAElC,UAAI,KAAK,OAAO,OAAO;AACrB,gBAAQ,IAAI,0CAA0C,SAAS,EAAE;AAAA,MACnE;AAEA,aAAO;AAAA,IACT,SAAS,OAAO;AACd,mBAAa,SAAS;AACtB,UAAI,iBAAiB,SAAS,MAAM,SAAS,cAAc;AACzD,cAAM,IAAI;AAAA,UACR,2BAA2B,OAAO,qBAAqB,SAAS;AAAA,QAClE;AAAA,MACF;AACA,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAEA,SAAS,iBAAiB,QAAwB;AAChD,QAAM,WAAmC;AAAA,IACvC,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,EACP;AACA,SAAO,SAAS,MAAM,KAAK;AAC7B;","names":[]}
+{"version":3,"sources":["../../src/transport/remote.ts"],"sourcesContent":["/**\n * RemoteTransport — HTTP POST transport to SpecForge API Gateway\n *\n * Extracted from ApiClient.call() to implement ITransport.\n *\n * Endpoint resolution: when `config.apiUrl` matches `CHANNEL.endpoint.primary`\n * (i.e. no `SPECFORGE_API_URL` override is active), the transport delegates\n * to `resolveEndpoint` on the first call so the URL flows from the\n * canary-channel client probe (PLAN-canary-channel.md §D) — primary first,\n * fallback on DNS-class failure, cached for 5 min. On a 401/403 the cache\n * is invalidated so the next call re-probes.\n */\n\nimport type { ITransport, TransportOrigin } from './interface.js';\nimport { CHANNEL } from '../channel.js';\nimport {\n  resolveEndpoint,\n  invalidate,\n  shouldInvalidateOnStatus,\n} from './resolve-endpoint.js';\n\nexport interface RemoteTransportConfig {\n  apiUrl: string;\n  apiKey: string;\n  debug?: boolean;\n  timeout?: number;\n  /**\n   * Calling context, sent as the `X-SpecForge-Origin` header (M9.7). Defaults to\n   * `mcp` (agent traffic); the human CLI surface passes `cli`.\n   */\n  origin?: TransportOrigin;\n}\n\nconst DEFAULT_TIMEOUT = 30000;\nconst MCP_CACHE_KEY = 'mcp-endpoint-cache';\n\n/** Parse a URL, returning null instead of throwing on malformed input. */\nfunction safeUrl(u: string): URL | null {\n  try {\n    return new URL(u);\n  } catch {\n    return null;\n  }\n}\n\n/** True when `apiUrl` targets one of the channel's hosts (on any surface path). */\nfunction isChannelHost(apiUrl: string): boolean {\n  const h = safeUrl(apiUrl)?.host;\n  if (!h) return false;\n  return (\n    h === safeUrl(CHANNEL.endpoint.primary)?.host ||\n    h === safeUrl(CHANNEL.endpoint.fallback)?.host\n  );\n}\n\nexport class RemoteTransport implements ITransport {\n  private config: RemoteTransportConfig;\n  /** Resolved URL pinned for this transport instance after the first call. */\n  private resolvedUrl: string | null = null;\n\n  constructor(config: RemoteTransportConfig) {\n    this.config = config;\n  }\n\n  /**\n   * Pick the URL for this call. When `config.apiUrl` is the channel default,\n   * defer to the resolver. Otherwise (env override / explicit test fixture),\n   * use the configured URL directly.\n   */\n  private async pickUrl(): Promise<string> {\n    if (this.resolvedUrl) return this.resolvedUrl;\n\n    // Match the channel by HOST, not by exact URL. `createCliClient` rewrites the\n    // default `/local` (MCP/agent) surface to `/cli` (human CLI), so an exact\n    // `=== CHANNEL.endpoint.primary` check wrongly classified the CLI surface as\n    // an \"override\" and skipped the resolver entirely — meaning `specforge login`\n    // hit the dead primary with NO fallback. Comparing hosts makes BOTH surfaces\n    // go through the primary→fallback probe.\n    const apiUrl = safeUrl(this.config.apiUrl);\n    if (!apiUrl || !isChannelHost(this.config.apiUrl)) {\n      // A genuine override (env var / explicit test fixture) — use it verbatim.\n      this.resolvedUrl = this.config.apiUrl;\n      return this.resolvedUrl;\n    }\n\n    // Resolve the live host via the /health probes (primary → fallback), then\n    // re-apply THIS transport's surface path (`/cli` or `/local`) onto the\n    // resolved host so the fallback works on either surface.\n    const resolvedBase = await resolveEndpoint({\n      ...CHANNEL.endpoint,\n      cacheKey: MCP_CACHE_KEY,\n    });\n    const resolved = safeUrl(resolvedBase);\n    if (resolved && apiUrl) {\n      resolved.pathname = apiUrl.pathname;\n      this.resolvedUrl = resolved.toString().replace(/\\/$/, '');\n    } else {\n      this.resolvedUrl = resolvedBase;\n    }\n    if (this.config.debug) {\n      console.log(`[RemoteTransport] Resolved MCP endpoint: ${this.resolvedUrl}`);\n    }\n    return this.resolvedUrl;\n  }\n\n  async execute<T = unknown>(\n    operation: string,\n    args: Record<string, unknown>\n  ): Promise<T> {\n    const timeout = this.config.timeout ?? DEFAULT_TIMEOUT;\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n    try {\n      if (this.config.debug) {\n        console.log(`[RemoteTransport] Calling operation: ${operation}`, {\n          args: Object.keys(args),\n        });\n      }\n\n      const url = await this.pickUrl();\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          Authorization: `Bearer ${this.config.apiKey}`,\n          // M9.7: server-derived feedback/telemetry provenance. The backend\n          // reads this header (never a request-body `source` field).\n          'X-SpecForge-Origin': this.config.origin ?? 'mcp',\n        },\n        body: JSON.stringify({ operation, args }),\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeoutId);\n\n      if (!response.ok) {\n        // Auth failures may indicate the channel was rotated under us;\n        // invalidate so the next call re-probes.\n        if (\n          shouldInvalidateOnStatus(response.status) &&\n          isChannelHost(this.config.apiUrl)\n        ) {\n          await invalidate(MCP_CACHE_KEY);\n          this.resolvedUrl = null;\n        }\n        const errorText = await response.text();\n        const statusMessage = getStatusMessage(response.status);\n        throw new Error(\n          `API request failed: ${response.status} ${statusMessage}\\n${errorText}`\n        );\n      }\n\n      // Transport is a dumb pipe (M9, approach A): return the raw response body.\n      // Response-shape interpretation lives in the consumer that owns the\n      // contract — `ApiClient.call` unwraps the `/cli` `{ data } / { error }`\n      // shape; the agent `/local` path interprets the M8 envelope itself.\n      const body = (await response.json()) as T;\n\n      if (this.config.debug) {\n        console.log(`[RemoteTransport] Operation completed: ${operation}`);\n      }\n\n      return body;\n    } catch (error) {\n      clearTimeout(timeoutId);\n      if (error instanceof Error && error.name === 'AbortError') {\n        throw new Error(\n          `Request timed out after ${timeout}ms for operation: ${operation}`\n        );\n      }\n      throw error;\n    }\n  }\n}\n\nfunction getStatusMessage(status: number): string {\n  const messages: Record<number, string> = {\n    400: 'Bad Request',\n    401: 'Unauthorized - Check your API key',\n    403: 'Forbidden - Insufficient permissions',\n    404: 'Not Found',\n    429: 'Too Many Requests - Rate limit exceeded',\n    500: 'Internal Server Error',\n    501: 'Not Implemented',\n    502: 'Bad Gateway',\n    503: 'Service Unavailable',\n    504: 'Gateway Timeout',\n  };\n  return messages[status] || 'Unknown Error';\n}\n"],"mappings":"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","names":[]}

package/dist/types/index.d.ts

@@ -1,19 +1,19 @@
 /**
  * SpecForge MCP Type Definitions
  *
- * Most wire-protocol types live in `@specforge/types` (the canonical source
- * of truth). This file re-exports them under stable CLI names and defines a
- * small set of CLI-internal shapes: work sessions, implementation context,
- * discovery/attempt summaries, git-link records, and structured acceptance
- * criteria with normalization helpers.
+ * Most wire-protocol types live in the surviving type packages
+ * (@specforge/spec-types for spec-domain schema/runtime, @specforge/api-types
+ * for API/wire entities, @specforge/report-types for status reports). This file
+ * re-exports them under stable CLI names and defines a small set of CLI-internal
+ * shapes: work sessions, implementation context, discovery/attempt summaries,
+ * git-link records, and structured acceptance criteria with normalization helpers.
  */
-export type { SpecificationStatus, EpicStatus, TicketStatus, DependencyType, } from '@specforge/types/schema';
-import type { TicketStatus } from '@specforge/types/schema';
-export type { Project, Specification, NamingConventions, SpecificationCodeStandards, ReturnTypes, Epic, EpicSharedPatterns, EpicCommonFiles, Ticket, TicketTechnicalDetails, TicketDependency, } from '@specforge/types/runtime';
-import type { Specification, Epic, Ticket } from '@specforge/types/runtime';
-export type { TicketImplementation } from '@specforge/types/schema';
-export type { ListResponse, DependencyTicketSummary, SpecificationStatusReport, EpicStatusReport, ImplementationSummary, TimeReport, BlockersReport, TicketUpdate, BulkUpdateRequest, BulkUpdateResult, BulkCreateTicketDefinition, BulkCreateDependencyDefinition, BulkCreateTicketsRequest, BulkCreatedTicketInfo, BulkCreateTicketsResult, BulkDependencyDefinition, BulkAddDependenciesRequest, BulkAddDependenciesResult, LookupProjectRequest, LookupProjectResult, LookupSpecificationRequest, LookupSpecificationResult, LookupEpicRequest, LookupEpicResult, LookupTicketRequest, LookupTicketResult, } from '@specforge/types/api';
-import type { DependencyTicketSummary } from '@specforge/types/api';
+export type { SpecificationStatus, EpicStatus, Specification, Epic, Ticket, TicketImplementation, NamingConventions, SpecificationCodeStandards, ReturnTypes, EpicSharedPatterns, EpicCommonFiles, TicketTechnicalDetails, } from '@specforge/spec-types';
+import type { Specification, Epic, Ticket } from '@specforge/spec-types';
+export type { TicketStatus, Project, DependencyTicketSummary, } from '@specforge/api-types';
+import type { TicketStatus, DependencyTicketSummary } from '@specforge/api-types';
+export type { SpecificationStatusReport, EpicStatusReport, ImplementationSummary, TimeReport, BlockersReport, } from '@specforge/report-types';
+export type { WorkSessionAcceptanceCheck, WorkSessionImplStepCompletion, } from '@specforge/session-types';
 /**
  * Structured acceptance criterion with validation state.
  */
@@ -140,16 +140,6 @@ export interface TicketAcceptanceCriterion {
     createdAt?: string;
     updatedAt?: string;
 }
-export interface WorkSessionACValidation {
-    id: string;
-    workSessionId: string;
-    criterionId: string;
-    validated: boolean;
-    validatedAt?: string;
-    notes?: string;
-    createdAt?: string;
-    updatedAt?: string;
-}
 export interface TicketImplementationStep {
     id: string;
     ticketId: string;
@@ -158,16 +148,6 @@ export interface TicketImplementationStep {
     createdAt?: string;
     updatedAt?: string;
 }
-export interface WorkSessionStepCompletion {
-    id: string;
-    workSessionId: string;
-    stepId: string;
-    completed: boolean;
-    completedAt?: string;
-    notes?: string;
-    createdAt?: string;
-    updatedAt?: string;
-}
 export type TestType = 'unit' | 'integration' | 'e2e' | 'manual' | 'typescript' | 'lint' | 'build' | 'typecheck' | 'format' | 'security' | 'custom';
 export interface WorkSessionTestResult {
     id: string;

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

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

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["/**\n * SpecForge MCP Type Definitions\n *\n * Most wire-protocol types live in `@specforge/types` (the canonical source\n * of truth). This file re-exports them under stable CLI names and defines a\n * small set of CLI-internal shapes: work sessions, implementation context,\n * discovery/attempt summaries, git-link records, and structured acceptance\n * criteria with normalization helpers.\n */\n\n// -----------------------------------------------------------------------------\n// Schema enums and primitive types — re-exported from @specforge/types/schema\n// -----------------------------------------------------------------------------\n\nexport type {\n  SpecificationStatus,\n  EpicStatus,\n  TicketStatus,\n  DependencyType,\n} from '@specforge/types/schema';\n\nimport type {\n  SpecificationStatus,\n  EpicStatus,\n  TicketStatus,\n} from '@specforge/types/schema';\n\n// -----------------------------------------------------------------------------\n// Runtime entity shapes — re-exported from @specforge/types/runtime\n// -----------------------------------------------------------------------------\n\nexport type {\n  Project,\n  Specification,\n  NamingConventions,\n  SpecificationCodeStandards,\n  ReturnTypes,\n  Epic,\n  EpicSharedPatterns,\n  EpicCommonFiles,\n  Ticket,\n  TicketTechnicalDetails,\n  TicketDependency,\n} from '@specforge/types/runtime';\n\nimport type {\n  Specification,\n  Epic,\n  Ticket,\n} from '@specforge/types/runtime';\n\nexport type { TicketImplementation } from '@specforge/types/schema';\n\n// -----------------------------------------------------------------------------\n// API wire types — re-exported from @specforge/types/api\n// -----------------------------------------------------------------------------\n\nexport type {\n  ListResponse,\n  DependencyTicketSummary,\n  SpecificationStatusReport,\n  EpicStatusReport,\n  ImplementationSummary,\n  TimeReport,\n  BlockersReport,\n  TicketUpdate,\n  BulkUpdateRequest,\n  BulkUpdateResult,\n  BulkCreateTicketDefinition,\n  BulkCreateDependencyDefinition,\n  BulkCreateTicketsRequest,\n  BulkCreatedTicketInfo,\n  BulkCreateTicketsResult,\n  BulkDependencyDefinition,\n  BulkAddDependenciesRequest,\n  BulkAddDependenciesResult,\n  LookupProjectRequest,\n  LookupProjectResult,\n  LookupSpecificationRequest,\n  LookupSpecificationResult,\n  LookupEpicRequest,\n  LookupEpicResult,\n  LookupTicketRequest,\n  LookupTicketResult,\n} from '@specforge/types/api';\n\nimport type { DependencyTicketSummary } from '@specforge/types/api';\n\n// =============================================================================\n// CLI-internal types below — no canonical equivalent in @specforge/types\n// =============================================================================\n\n// -----------------------------------------------------------------------------\n// Structured acceptance criteria (TS-001)\n// -----------------------------------------------------------------------------\n\n/**\n * Structured acceptance criterion with validation state.\n */\nexport interface AcceptanceCriterion {\n  id: string;\n  description: string;\n  validated: boolean;\n  validatedAt?: string;\n  validatedBy?: string;\n  notes?: string;\n}\n\n/**\n * Normalizes acceptance criteria from legacy string[] format to structured\n * `AcceptanceCriterion[]`. Provides backwards compatibility for old data\n * stored as string arrays.\n */\nexport function normalizeAcceptanceCriteria(\n  criteria: (string | AcceptanceCriterion)[]\n): AcceptanceCriterion[] {\n  return criteria.map((c, index) => {\n    if (typeof c === 'string') {\n      return {\n        id: `ac-${index}-${Date.now()}`,\n        description: c,\n        validated: false,\n      };\n    }\n    return c;\n  });\n}\n\n// -----------------------------------------------------------------------------\n// Implementation context (returned by get_implementation_context)\n// -----------------------------------------------------------------------------\n\nexport interface RelatedTicketSummary {\n  id: string;\n  title: string;\n  status: TicketStatus;\n  sameEpic: boolean;\n}\n\nexport interface TestResultSummary {\n  id: string;\n  testType?: string;\n  allPassed: boolean;\n  passed: number;\n  failed: number;\n  total: number;\n  runAt: string;\n}\n\nexport interface PreviousAttempt {\n  attemptNumber: number;\n  startedAt: string;\n  endedAt?: string;\n  result: 'completed' | 'failed' | 'in_progress';\n  testResults: TestResultSummary[];\n  summary?: string;\n}\n\nexport interface DiscoverySummary {\n  id: string;\n  type: string;\n  severity: string;\n  status: string;\n  title: string;\n  description: string;\n  createdAt: string;\n}\n\nexport interface ActiveSessionSummary {\n  id: string;\n  status: string;\n  startedAt: string;\n  config: unknown;\n  ticketsCompleted: string[];\n  ticketsFailed: string[];\n  ticketsSkipped: string[];\n  totalActiveMinutes: number;\n}\n\n/**\n * Implementation context returned by get_implementation_context.\n */\nexport interface ImplementationContext {\n  /** The ticket being implemented */\n  ticket: Ticket;\n  /** The epic containing the ticket */\n  epic: Epic;\n  /** The specification containing the epic */\n  specification: Specification;\n  /** Dependency information */\n  dependencies: {\n    /** Tickets that must be completed before this one */\n    blockedBy: DependencyTicketSummary[];\n    /** Tickets waiting on this one */\n    blocks: DependencyTicketSummary[];\n  };\n  /** Related tickets */\n  relatedTickets: RelatedTicketSummary[];\n  /** Patterns and conventions from the project */\n  patterns?: Record<string, unknown>;\n  /** Active implementation session (Phase 5) */\n  activeSession: ActiveSessionSummary | null;\n  /** Previous implementation attempts (Phase 5) */\n  previousAttempts: PreviousAttempt[];\n  /** Related discoveries (Phase 5) */\n  relatedDiscoveries: DiscoverySummary[];\n}\n\n// -----------------------------------------------------------------------------\n// Work session state (session-scoped tables)\n// -----------------------------------------------------------------------------\n\nexport interface WorkSession {\n  id: string;\n  ticketId: string;\n  specificationId: string;\n  projectId: string;\n  epicId: string;\n  implementationSessionId?: string;\n  status: 'active' | 'paused' | 'completed' | 'failed';\n  startedAt: string;\n  pausedAt?: string;\n  completedAt?: string;\n  actualHours?: number;\n  filesCreated?: string[];\n  filesModified?: string[];\n  filesDeleted?: string[];\n  testsPassed?: boolean;\n  retryCount: number;\n  retryLog?: unknown;\n  actions?: unknown;\n  completionAttempts?: unknown;\n  tokensUsed?: { inputTokens: number; outputTokens: number };\n  costUsd?: number;\n  durationMs?: number;\n  commitSha?: string;\n  modelUsed?: string;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface TicketAcceptanceCriterion {\n  id: string;\n  ticketId: string;\n  description: string;\n  order: number;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\nexport interface WorkSessionACValidation {\n  id: string;\n  workSessionId: string;\n  criterionId: string;\n  validated: boolean;\n  validatedAt?: string;\n  notes?: string;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\nexport interface TicketImplementationStep {\n  id: string;\n  ticketId: string;\n  text: string;\n  order: number;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\nexport interface WorkSessionStepCompletion {\n  id: string;\n  workSessionId: string;\n  stepId: string;\n  completed: boolean;\n  completedAt?: string;\n  notes?: string;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\n// -----------------------------------------------------------------------------\n// Test result types\n// -----------------------------------------------------------------------------\n\nexport type TestType =\n  | 'unit'\n  | 'integration'\n  | 'e2e'\n  | 'manual'\n  | 'typescript'\n  | 'lint'\n  | 'build'\n  | 'typecheck'\n  | 'format'\n  | 'security'\n  | 'custom';\n\nexport interface WorkSessionTestResult {\n  id: string;\n  workSessionId: string;\n  testType: TestType;\n  passed: boolean;\n  totalTests: number;\n  passedTests: number;\n  failedTests: number;\n  skippedTests: number;\n  coverage?: number;\n  errorDetails?: string;\n  command?: string;\n  exitCode?: number;\n  durationMs?: number;\n  errorCount?: number;\n  warningCount?: number;\n  summary?: string;\n  suites?: Array<{\n    name: string;\n    passed: number;\n    failed: number;\n    skipped?: number;\n    duration?: number;\n  }>;\n  runAt: string;\n}\n\n/** @deprecated Use WorkSessionTestResult instead */\nexport type TicketTestResult = WorkSessionTestResult;\n\n// -----------------------------------------------------------------------------\n// Git integration\n// -----------------------------------------------------------------------------\n\nexport type LinkType = 'commit' | 'pull_request' | 'branch';\n\nexport interface TicketLink {\n  id: string;\n  ticketId: string;\n  linkType: LinkType;\n  url: string;\n  sha?: string;\n  prNumber?: number;\n  title?: string;\n  status?: string;\n  createdAt: string;\n}\n\n// -----------------------------------------------------------------------------\n// Silence unused-import warnings for enum aliases referenced only by JSDoc\n// -----------------------------------------------------------------------------\n// (Each of these is re-exported above; the local `import type` pulls them\n//  in so that embedded JSDoc cross-references resolve in editors.)\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype _ReferencedEnums = SpecificationStatus | EpicStatus;\n"],"mappings":"AAiHO,SAAS,4BACd,UACuB;AACvB,SAAO,SAAS,IAAI,CAAC,GAAG,UAAU;AAChC,QAAI,OAAO,MAAM,UAAU;AACzB,aAAO;AAAA,QACL,IAAI,MAAM,KAAK,IAAI,KAAK,IAAI,CAAC;AAAA,QAC7B,aAAa;AAAA,QACb,WAAW;AAAA,MACb;AAAA,IACF;AACA,WAAO;AAAA,EACT,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["/**\n * SpecForge MCP Type Definitions\n *\n * Most wire-protocol types live in the surviving type packages\n * (@specforge/spec-types for spec-domain schema/runtime, @specforge/api-types\n * for API/wire entities, @specforge/report-types for status reports). This file\n * re-exports them under stable CLI names and defines a small set of CLI-internal\n * shapes: work sessions, implementation context, discovery/attempt summaries,\n * git-link records, and structured acceptance criteria with normalization helpers.\n */\n\n// -----------------------------------------------------------------------------\n// Spec-domain schema enums + entities + pattern shapes — from @specforge/spec-types\n// -----------------------------------------------------------------------------\n\nexport type {\n  SpecificationStatus,\n  EpicStatus,\n  Specification,\n  Epic,\n  Ticket,\n  TicketImplementation,\n  NamingConventions,\n  SpecificationCodeStandards,\n  ReturnTypes,\n  EpicSharedPatterns,\n  EpicCommonFiles,\n  TicketTechnicalDetails,\n} from '@specforge/spec-types';\n\nimport type {\n  SpecificationStatus,\n  EpicStatus,\n  Specification,\n  Epic,\n  Ticket,\n} from '@specforge/spec-types';\n\n// -----------------------------------------------------------------------------\n// Canonical 5-value TicketStatus + Project entity + dependency summary — from\n// @specforge/api-types (the API/wire entity home; TicketStatus carries `blocked`).\n// -----------------------------------------------------------------------------\n\nexport type {\n  TicketStatus,\n  Project,\n  DependencyTicketSummary,\n} from '@specforge/api-types';\n\nimport type {\n  TicketStatus,\n  DependencyTicketSummary,\n} from '@specforge/api-types';\n\n// -----------------------------------------------------------------------------\n// Status / analytic reports — from @specforge/report-types (the report family\n// embeds the spec-domain entities + Project; the CLI is its sole type-consumer).\n// -----------------------------------------------------------------------------\n\nexport type {\n  SpecificationStatusReport,\n  EpicStatusReport,\n  ImplementationSummary,\n  TimeReport,\n  BlockersReport,\n} from '@specforge/report-types';\n\n// -----------------------------------------------------------------------------\n// Canonical work-session child-state types — re-exported from\n// @specforge/session-types (the single source of truth after the M14\n// convergence + the M15.1a DDB rename). These replace the former divergent\n// CLI-local AC-validation / step-completion shapes (which had `validated`/\n// `completed` and were missing `ticketId`/`projectId`): one name + one shape\n// end-to-end (`checked`/`done` + `ticketId`/`projectId`), no aliases.\n// -----------------------------------------------------------------------------\n\nexport type {\n  WorkSessionAcceptanceCheck,\n  WorkSessionImplStepCompletion,\n} from '@specforge/session-types';\n\n// =============================================================================\n// CLI-internal types below — no canonical equivalent in the type packages\n// =============================================================================\n\n// -----------------------------------------------------------------------------\n// Structured acceptance criteria (TS-001)\n// -----------------------------------------------------------------------------\n\n/**\n * Structured acceptance criterion with validation state.\n */\nexport interface AcceptanceCriterion {\n  id: string;\n  description: string;\n  validated: boolean;\n  validatedAt?: string;\n  validatedBy?: string;\n  notes?: string;\n}\n\n/**\n * Normalizes acceptance criteria from legacy string[] format to structured\n * `AcceptanceCriterion[]`. Provides backwards compatibility for old data\n * stored as string arrays.\n */\nexport function normalizeAcceptanceCriteria(\n  criteria: (string | AcceptanceCriterion)[]\n): AcceptanceCriterion[] {\n  return criteria.map((c, index) => {\n    if (typeof c === 'string') {\n      return {\n        id: `ac-${index}-${Date.now()}`,\n        description: c,\n        validated: false,\n      };\n    }\n    return c;\n  });\n}\n\n// -----------------------------------------------------------------------------\n// Implementation context (returned by get_implementation_context)\n// -----------------------------------------------------------------------------\n\nexport interface RelatedTicketSummary {\n  id: string;\n  title: string;\n  status: TicketStatus;\n  sameEpic: boolean;\n}\n\nexport interface TestResultSummary {\n  id: string;\n  testType?: string;\n  allPassed: boolean;\n  passed: number;\n  failed: number;\n  total: number;\n  runAt: string;\n}\n\nexport interface PreviousAttempt {\n  attemptNumber: number;\n  startedAt: string;\n  endedAt?: string;\n  result: 'completed' | 'failed' | 'in_progress';\n  testResults: TestResultSummary[];\n  summary?: string;\n}\n\nexport interface DiscoverySummary {\n  id: string;\n  type: string;\n  severity: string;\n  status: string;\n  title: string;\n  description: string;\n  createdAt: string;\n}\n\nexport interface ActiveSessionSummary {\n  id: string;\n  status: string;\n  startedAt: string;\n  config: unknown;\n  ticketsCompleted: string[];\n  ticketsFailed: string[];\n  ticketsSkipped: string[];\n  totalActiveMinutes: number;\n}\n\n/**\n * Implementation context returned by get_implementation_context.\n */\nexport interface ImplementationContext {\n  /** The ticket being implemented */\n  ticket: Ticket;\n  /** The epic containing the ticket */\n  epic: Epic;\n  /** The specification containing the epic */\n  specification: Specification;\n  /** Dependency information */\n  dependencies: {\n    /** Tickets that must be completed before this one */\n    blockedBy: DependencyTicketSummary[];\n    /** Tickets waiting on this one */\n    blocks: DependencyTicketSummary[];\n  };\n  /** Related tickets */\n  relatedTickets: RelatedTicketSummary[];\n  /** Patterns and conventions from the project */\n  patterns?: Record<string, unknown>;\n  /** Active implementation session (Phase 5) */\n  activeSession: ActiveSessionSummary | null;\n  /** Previous implementation attempts (Phase 5) */\n  previousAttempts: PreviousAttempt[];\n  /** Related discoveries (Phase 5) */\n  relatedDiscoveries: DiscoverySummary[];\n}\n\n// -----------------------------------------------------------------------------\n// Work session state (session-scoped tables)\n// -----------------------------------------------------------------------------\n\nexport interface WorkSession {\n  id: string;\n  ticketId: string;\n  specificationId: string;\n  projectId: string;\n  epicId: string;\n  implementationSessionId?: string;\n  status: 'active' | 'paused' | 'completed' | 'failed';\n  startedAt: string;\n  pausedAt?: string;\n  completedAt?: string;\n  actualHours?: number;\n  filesCreated?: string[];\n  filesModified?: string[];\n  filesDeleted?: string[];\n  testsPassed?: boolean;\n  retryCount: number;\n  retryLog?: unknown;\n  actions?: unknown;\n  completionAttempts?: unknown;\n  tokensUsed?: { inputTokens: number; outputTokens: number };\n  costUsd?: number;\n  durationMs?: number;\n  commitSha?: string;\n  modelUsed?: string;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface TicketAcceptanceCriterion {\n  id: string;\n  ticketId: string;\n  description: string;\n  order: number;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\nexport interface TicketImplementationStep {\n  id: string;\n  ticketId: string;\n  text: string;\n  order: number;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\n// -----------------------------------------------------------------------------\n// Test result types\n// -----------------------------------------------------------------------------\n\nexport type TestType =\n  | 'unit'\n  | 'integration'\n  | 'e2e'\n  | 'manual'\n  | 'typescript'\n  | 'lint'\n  | 'build'\n  | 'typecheck'\n  | 'format'\n  | 'security'\n  | 'custom';\n\nexport interface WorkSessionTestResult {\n  id: string;\n  workSessionId: string;\n  testType: TestType;\n  passed: boolean;\n  totalTests: number;\n  passedTests: number;\n  failedTests: number;\n  skippedTests: number;\n  coverage?: number;\n  errorDetails?: string;\n  command?: string;\n  exitCode?: number;\n  durationMs?: number;\n  errorCount?: number;\n  warningCount?: number;\n  summary?: string;\n  suites?: Array<{\n    name: string;\n    passed: number;\n    failed: number;\n    skipped?: number;\n    duration?: number;\n  }>;\n  runAt: string;\n}\n\n/** @deprecated Use WorkSessionTestResult instead */\nexport type TicketTestResult = WorkSessionTestResult;\n\n// -----------------------------------------------------------------------------\n// Git integration\n// -----------------------------------------------------------------------------\n\nexport type LinkType = 'commit' | 'pull_request' | 'branch';\n\nexport interface TicketLink {\n  id: string;\n  ticketId: string;\n  linkType: LinkType;\n  url: string;\n  sha?: string;\n  prNumber?: number;\n  title?: string;\n  status?: string;\n  createdAt: string;\n}\n\n// -----------------------------------------------------------------------------\n// Silence unused-import warnings for enum aliases referenced only by JSDoc\n// -----------------------------------------------------------------------------\n// (Each of these is re-exported above; the local `import type` pulls them\n//  in so that embedded JSDoc cross-references resolve in editors.)\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype _ReferencedEnums = SpecificationStatus | EpicStatus;\n"],"mappings":"AA0GO,SAAS,4BACd,UACuB;AACvB,SAAO,SAAS,IAAI,CAAC,GAAG,UAAU;AAChC,QAAI,OAAO,MAAM,UAAU;AACzB,aAAO;AAAA,QACL,IAAI,MAAM,KAAK,IAAI,KAAK,IAAI,CAAC;AAAA,QAC7B,aAAa;AAAA,QACb,WAAW;AAAA,MACb;AAAA,IACF;AACA,WAAO;AAAA,EACT,CAAC;AACH;","names":[]}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,eAAe,EACf,cAAc,EACd,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAG/B,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,MAAM;gBAFnB,OAAO,EAAE,MAAM,EACR,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM;CAKtB;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAGxB,UAAU,EAAE,MAAM;IAClB,SAAS,CAAC,EAAE,MAAM;gBAFzB,OAAO,EAAE,MAAM,EACR,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,YAAA;CAK5B;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQxE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAUnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EAAE,GACtB,IAAI,CASN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,IAAI,CAeN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACrD,IAAI,CAsBN;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,IAAI,CAS1E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAUnE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,IAAI,CAeN;AAMD,KAAK,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CA2LtD,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,CAkB7D;AA2BD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAiCpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI,CAKN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,eAAe,EACf,cAAc,EACd,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAG/B,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,MAAM;gBAFnB,OAAO,EAAE,MAAM,EACR,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM;CAKtB;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAGxB,UAAU,EAAE,MAAM;IAClB,SAAS,CAAC,EAAE,MAAM;gBAFzB,OAAO,EAAE,MAAM,EACR,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,YAAA;CAK5B;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQxE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAUnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EAAE,GACtB,IAAI,CASN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,IAAI,CAeN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACrD,IAAI,CAsBN;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,IAAI,CAS1E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAUnE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,IAAI,CAeN;AAMD,KAAK,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAwKtD,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,CAkB7D;AA2BD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAiCpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI,CAKN"}

package/dist/validation/index.js

@@ -211,9 +211,6 @@ const toolValidators = {
     if (args.filesDeleted !== void 0) {
       validateArray(args.filesDeleted, "filesDeleted");
     }
-    if (args.blockReason !== void 0) {
-      validateStringLength(args.blockReason, "blockReason", 1, 5e3);
-    }
     if (args.clearBlockReason !== void 0 && typeof args.clearBlockReason !== "boolean") {
       throw new Error("clearBlockReason must be a boolean");
     }
@@ -234,15 +231,6 @@ const toolValidators = {
       validateArray(args.filesDeleted, "filesDeleted");
     }
   },
-  start_review_session: (args) => {
-    validateRequired(args.specificationId, "specificationId");
-  },
-  action_review_session: (args) => {
-    validateRequired(args.specificationId, "specificationId");
-  },
-  complete_review_session: (args) => {
-    validateRequired(args.specificationId, "specificationId");
-  },
   reopen_specification: (args) => {
     validateRequired(args.specificationId, "specificationId");
   },
@@ -254,9 +242,6 @@ const toolValidators = {
   // Utilities
   feedback: () => {
   },
-  reset_work_session: (args) => {
-    validateRequired(args.specificationId, "specificationId");
-  },
   link_pull_request: (args) => {
     validateRequired(args.ticketId, "ticketId");
     if (!args.prNumber && !args.prUrl) {

package/dist/validation/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/validation/index.ts"],"sourcesContent":["/**\n * Validation Utilities for MCP Tools\n *\n * Provides comprehensive input validation and error handling for all MCP tools.\n * Validation is run before each tool call to ensure proper argument types and formats.\n */\n\n// Re-export ticket validation utilities\nexport {\n  type TicketComplexity,\n  type WarningSeverity,\n  type StrictnessLevel,\n  type ValidationWarning,\n  type TicketValidationResult,\n  type ComplexityRules,\n  type TicketValidationInput,\n  validationRules,\n  validateTicket,\n  filterWarningsByStrictness,\n  getComplexityRules,\n  isValidComplexity,\n  getComplexityDescription,\n  suggestComplexity,\n} from './ticket-validation.js';\n\n/**\n * Custom error class for validation failures\n * Includes field name and error code for structured error handling\n */\nexport class ValidationError extends Error {\n  constructor(\n    message: string,\n    public field: string,\n    public code: string\n  ) {\n    super(message);\n    this.name = 'ValidationError';\n  }\n}\n\n/**\n * API Error class for handling HTTP errors from the backend\n */\nexport class ApiError extends Error {\n  constructor(\n    message: string,\n    public statusCode: number,\n    public errorCode?: string\n  ) {\n    super(message);\n    this.name = 'ApiError';\n  }\n}\n\n// ============================================================================\n// Basic Validators\n// ============================================================================\n\n/**\n * Validate that a value is present (not null, undefined, or empty string)\n */\nexport function validateRequired(value: unknown, fieldName: string): void {\n  if (value === undefined || value === null || value === '') {\n    throw new ValidationError(\n      `${fieldName} is required`,\n      fieldName,\n      'REQUIRED'\n    );\n  }\n}\n\n/**\n * Validate that a value is a valid UUID format\n */\nexport function validateUUID(value: string, fieldName: string): void {\n  validateRequired(value, fieldName);\n  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n  if (!uuidRegex.test(value)) {\n    throw new ValidationError(\n      `${fieldName} must be a valid UUID`,\n      fieldName,\n      'INVALID_UUID'\n    );\n  }\n}\n\n/**\n * Validate that a value is one of the allowed enum values\n */\nexport function validateEnum(\n  value: string,\n  fieldName: string,\n  allowedValues: string[]\n): void {\n  validateRequired(value, fieldName);\n  if (!allowedValues.includes(value)) {\n    throw new ValidationError(\n      `${fieldName} must be one of: ${allowedValues.join(', ')}`,\n      fieldName,\n      'INVALID_ENUM'\n    );\n  }\n}\n\n/**\n * Validate that a number is within a range\n */\nexport function validateRange(\n  value: number,\n  fieldName: string,\n  min: number,\n  max: number\n): void {\n  if (typeof value !== 'number' || isNaN(value)) {\n    throw new ValidationError(\n      `${fieldName} must be a number`,\n      fieldName,\n      'INVALID_NUMBER'\n    );\n  }\n  if (value < min || value > max) {\n    throw new ValidationError(\n      `${fieldName} must be between ${min} and ${max}`,\n      fieldName,\n      'OUT_OF_RANGE'\n    );\n  }\n}\n\n/**\n * Validate that a value is an array, with optional item validation\n */\nexport function validateArray(\n  value: unknown,\n  fieldName: string,\n  itemValidator?: (item: unknown, index: number) => void\n): void {\n  if (!Array.isArray(value)) {\n    throw new ValidationError(\n      `${fieldName} must be an array`,\n      fieldName,\n      'INVALID_ARRAY'\n    );\n  }\n  if (itemValidator) {\n    value.forEach((item, index) => {\n      try {\n        itemValidator(item, index);\n      } catch (error: unknown) {\n        const message = error instanceof Error ? error.message : String(error);\n        throw new ValidationError(\n          `${fieldName}[${index}]: ${message}`,\n          `${fieldName}[${index}]`,\n          'INVALID_ITEM'\n        );\n      }\n    });\n  }\n}\n\n/**\n * Validate a 40-character hex SHA\n */\nexport function validateSha(value: string, fieldName: string = 'sha'): void {\n  validateRequired(value, fieldName);\n  if (!/^[a-f0-9]{40}$/i.test(value)) {\n    throw new ValidationError(\n      `${fieldName} must be a 40-character hex string`,\n      fieldName,\n      'INVALID_SHA'\n    );\n  }\n}\n\n/**\n * Validate an ISO 8601 date string\n */\nexport function validateDate(value: string, fieldName: string): void {\n  validateRequired(value, fieldName);\n  const date = new Date(value);\n  if (isNaN(date.getTime())) {\n    throw new ValidationError(\n      `${fieldName} must be a valid ISO 8601 date`,\n      fieldName,\n      'INVALID_DATE'\n    );\n  }\n}\n\n/**\n * Validate a string length\n */\nexport function validateStringLength(\n  value: string,\n  fieldName: string,\n  minLength: number,\n  maxLength: number\n): void {\n  if (typeof value !== 'string') {\n    throw new ValidationError(\n      `${fieldName} must be a string`,\n      fieldName,\n      'INVALID_STRING'\n    );\n  }\n  if (value.length < minLength || value.length > maxLength) {\n    throw new ValidationError(\n      `${fieldName} must be between ${minLength} and ${maxLength} characters`,\n      fieldName,\n      'INVALID_LENGTH'\n    );\n  }\n}\n\n// ============================================================================\n// Tool-Specific Validators\n// ============================================================================\n\ntype ValidatorFn = (args: Record<string, unknown>) => void;\n\n/**\n * Validators for each tool (22 tools)\n * These are applied before the tool handler is called\n */\nexport const toolValidators: Record<string, ValidatorFn> = {\n  // Queries\n  get: (args) => {\n    validateRequired(args.type, 'type');\n    validateEnum(\n      args.type as string,\n      'type',\n      ['project', 'specification', 'epic', 'ticket', 'implementation_session']\n    );\n  },\n\n  list: (args) => {\n    validateRequired(args.type, 'type');\n    validateEnum(\n      args.type as string,\n      'type',\n      ['projects', 'specifications', 'epics', 'tickets']\n    );\n  },\n\n  search: (args) => {\n    if (!args.query && !args.files && !args.tags && !args.relatedTo) {\n      throw new ValidationError(\n        'At least one filter is required: query, files, tags, or relatedTo',\n        'query',\n        'REQUIRED_ONE_OF'\n      );\n    }\n    if (args.query) {\n      validateStringLength(args.query as string, 'query', 1, 500);\n    }\n    if (args.limit !== undefined) {\n      validateRange(args.limit as number, 'limit', 1, 100);\n    }\n    if (args.offset !== undefined) {\n      validateRange(args.offset as number, 'offset', 0, 10000);\n    }\n  },\n\n  get_next_actionable_tickets: (args) => {\n    // Either specificationId or projectId is required\n    if (!args.specificationId && !args.projectId) {\n      throw new ValidationError(\n        'Either specificationId or projectId is required',\n        'specificationId/projectId',\n        'REQUIRED_ONE_OF'\n      );\n    }\n    if (args.limit !== undefined) {\n      validateRange(args.limit as number, 'limit', 1, 100);\n    }\n  },\n\n  get_blocked_tickets: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  get_report: (args) => {\n    validateRequired(args.type, 'type');\n    validateRequired(args.scope, 'scope');\n    validateRequired(args.scopeId, 'scopeId');\n  },\n\n  // Lifecycle. Planning verbs inject identity from local config (M9): SPS takes\n  // an optional specificationId (falls back to config), APS takes only\n  // `operation` (sessionId injected), CPS takes nothing (sessionId injected).\n  // So no specificationId/sessionId requirements here — the handlers resolve\n  // and validate them.\n  start_planning_session: () => {\n    /* specificationId optional — handler falls back to config */\n  },\n\n  action_planning_session: (args) => {\n    validateRequired(args.operation, 'operation');\n  },\n\n  complete_planning_session: () => {\n    /* no args — sessionId injected from config */\n  },\n\n  start_work_session: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n  },\n\n  action_work_session: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n    if (args.filesCreated !== undefined) {\n      validateArray(args.filesCreated, 'filesCreated');\n    }\n    if (args.filesModified !== undefined) {\n      validateArray(args.filesModified, 'filesModified');\n    }\n    if (args.filesDeleted !== undefined) {\n      validateArray(args.filesDeleted, 'filesDeleted');\n    }\n    if (args.blockReason !== undefined) {\n      validateStringLength(args.blockReason as string, 'blockReason', 1, 5000);\n    }\n    if (args.clearBlockReason !== undefined && typeof args.clearBlockReason !== 'boolean') {\n      throw new Error('clearBlockReason must be a boolean');\n    }\n  },\n\n  complete_work_session: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n    validateRequired(args.summary, 'summary');\n    if (args.summary) {\n      validateStringLength(args.summary as string, 'summary', 1, 10000);\n    }\n    if (args.filesModified !== undefined) {\n      validateArray(args.filesModified, 'filesModified');\n    }\n    if (args.filesCreated !== undefined) {\n      validateArray(args.filesCreated, 'filesCreated');\n    }\n    if (args.filesDeleted !== undefined) {\n      validateArray(args.filesDeleted, 'filesDeleted');\n    }\n  },\n\n  start_review_session: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  action_review_session: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  complete_review_session: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  reopen_specification: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  // Mutation\n  create_specification: (args) => {\n    validateRequired(args.projectId, 'projectId');\n    validateRequired(args.title, 'title');\n  },\n\n  // Utilities\n  feedback: () => {\n    // Validated by feedback handler\n  },\n\n  reset_work_session: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  link_pull_request: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n    if (!args.prNumber && !args.prUrl) {\n      throw new ValidationError(\n        'Either prNumber or prUrl must be provided',\n        'prNumber',\n        'REQUIRED_ONE_OF'\n      );\n    }\n    if (args.prNumber !== undefined && typeof args.prNumber !== 'number') {\n      throw new ValidationError(\n        'prNumber must be a number',\n        'prNumber',\n        'INVALID_NUMBER'\n      );\n    }\n    if (args.prUrl !== undefined) {\n      const url = args.prUrl as string;\n      if (!url.includes('github.com') && !url.includes('gitlab.com') && !url.includes('bitbucket.org')) {\n        throw new ValidationError(\n          'prUrl must be a valid GitHub, GitLab, or Bitbucket URL',\n          'prUrl',\n          'INVALID_URL'\n        );\n      }\n    }\n  },\n\n  // Orchestration\n  get_critical_path: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  get_dependency_tree: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n};\n\n// ============================================================================\n// Error Transformation\n// ============================================================================\n\n/**\n * MCP error response format\n */\nexport interface MCPErrorResponse {\n  content: Array<{\n    type: 'text';\n    text: string;\n  }>;\n  isError: true;\n}\n\n/**\n * Transform an error into MCP error response format\n */\nexport function formatMCPError(error: Error): MCPErrorResponse {\n  let message = error.message;\n\n  if (error instanceof ValidationError) {\n    message = `Validation error for '${error.field}': ${error.message} (${error.code})`;\n  } else if (error instanceof ApiError) {\n    message = formatApiErrorMessage(error);\n  }\n\n  return {\n    content: [\n      {\n        type: 'text',\n        text: message,\n      },\n    ],\n    isError: true,\n  };\n}\n\n/**\n * Format API error message based on status code\n */\nfunction formatApiErrorMessage(error: ApiError): string {\n  switch (error.statusCode) {\n    case 400:\n      return `Bad request: ${error.message}`;\n    case 401:\n      return 'Authentication failed. Check your API key.';\n    case 403:\n      return 'Permission denied. Your API key may lack required permissions.';\n    case 404:\n      return `Resource not found: ${error.message}`;\n    case 429:\n      return 'Rate limit exceeded. Please wait before retrying.';\n    case 500:\n    case 502:\n    case 503:\n    case 504:\n      return 'Server error. Please try again later.';\n    default:\n      return error.message;\n  }\n}\n\n/**\n * Transform HTTP/network errors into ApiError\n */\nexport function transformError(error: unknown): Error {\n  if (error instanceof ValidationError || error instanceof ApiError) {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    // Network errors\n    if (error.message.includes('ECONNREFUSED')) {\n      return new ApiError(\n        'Unable to connect to SpecForge API. Check your network connection.',\n        0,\n        'NETWORK_ERROR'\n      );\n    }\n    if (error.message.includes('ETIMEDOUT')) {\n      return new ApiError(\n        'Request timed out. Please try again.',\n        0,\n        'TIMEOUT'\n      );\n    }\n    if (error.message.includes('ECONNRESET')) {\n      return new ApiError(\n        'Connection was reset. Please try again.',\n        0,\n        'CONNECTION_RESET'\n      );\n    }\n\n    return error;\n  }\n\n  return new Error(String(error));\n}\n\n/**\n * Run validation for a specific tool\n * @throws ValidationError if validation fails\n */\nexport function validateToolArgs(\n  toolName: string,\n  args: Record<string, unknown>\n): void {\n  const validator = toolValidators[toolName];\n  if (validator) {\n    validator(args);\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/validation/index.ts"],"sourcesContent":["/**\n * Validation Utilities for MCP Tools\n *\n * Provides comprehensive input validation and error handling for all MCP tools.\n * Validation is run before each tool call to ensure proper argument types and formats.\n */\n\n// Re-export ticket validation utilities\nexport {\n  type TicketComplexity,\n  type WarningSeverity,\n  type StrictnessLevel,\n  type ValidationWarning,\n  type TicketValidationResult,\n  type ComplexityRules,\n  type TicketValidationInput,\n  validationRules,\n  validateTicket,\n  filterWarningsByStrictness,\n  getComplexityRules,\n  isValidComplexity,\n  getComplexityDescription,\n  suggestComplexity,\n} from './ticket-validation.js';\n\n/**\n * Custom error class for validation failures\n * Includes field name and error code for structured error handling\n */\nexport class ValidationError extends Error {\n  constructor(\n    message: string,\n    public field: string,\n    public code: string\n  ) {\n    super(message);\n    this.name = 'ValidationError';\n  }\n}\n\n/**\n * API Error class for handling HTTP errors from the backend\n */\nexport class ApiError extends Error {\n  constructor(\n    message: string,\n    public statusCode: number,\n    public errorCode?: string\n  ) {\n    super(message);\n    this.name = 'ApiError';\n  }\n}\n\n// ============================================================================\n// Basic Validators\n// ============================================================================\n\n/**\n * Validate that a value is present (not null, undefined, or empty string)\n */\nexport function validateRequired(value: unknown, fieldName: string): void {\n  if (value === undefined || value === null || value === '') {\n    throw new ValidationError(\n      `${fieldName} is required`,\n      fieldName,\n      'REQUIRED'\n    );\n  }\n}\n\n/**\n * Validate that a value is a valid UUID format\n */\nexport function validateUUID(value: string, fieldName: string): void {\n  validateRequired(value, fieldName);\n  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n  if (!uuidRegex.test(value)) {\n    throw new ValidationError(\n      `${fieldName} must be a valid UUID`,\n      fieldName,\n      'INVALID_UUID'\n    );\n  }\n}\n\n/**\n * Validate that a value is one of the allowed enum values\n */\nexport function validateEnum(\n  value: string,\n  fieldName: string,\n  allowedValues: string[]\n): void {\n  validateRequired(value, fieldName);\n  if (!allowedValues.includes(value)) {\n    throw new ValidationError(\n      `${fieldName} must be one of: ${allowedValues.join(', ')}`,\n      fieldName,\n      'INVALID_ENUM'\n    );\n  }\n}\n\n/**\n * Validate that a number is within a range\n */\nexport function validateRange(\n  value: number,\n  fieldName: string,\n  min: number,\n  max: number\n): void {\n  if (typeof value !== 'number' || isNaN(value)) {\n    throw new ValidationError(\n      `${fieldName} must be a number`,\n      fieldName,\n      'INVALID_NUMBER'\n    );\n  }\n  if (value < min || value > max) {\n    throw new ValidationError(\n      `${fieldName} must be between ${min} and ${max}`,\n      fieldName,\n      'OUT_OF_RANGE'\n    );\n  }\n}\n\n/**\n * Validate that a value is an array, with optional item validation\n */\nexport function validateArray(\n  value: unknown,\n  fieldName: string,\n  itemValidator?: (item: unknown, index: number) => void\n): void {\n  if (!Array.isArray(value)) {\n    throw new ValidationError(\n      `${fieldName} must be an array`,\n      fieldName,\n      'INVALID_ARRAY'\n    );\n  }\n  if (itemValidator) {\n    value.forEach((item, index) => {\n      try {\n        itemValidator(item, index);\n      } catch (error: unknown) {\n        const message = error instanceof Error ? error.message : String(error);\n        throw new ValidationError(\n          `${fieldName}[${index}]: ${message}`,\n          `${fieldName}[${index}]`,\n          'INVALID_ITEM'\n        );\n      }\n    });\n  }\n}\n\n/**\n * Validate a 40-character hex SHA\n */\nexport function validateSha(value: string, fieldName: string = 'sha'): void {\n  validateRequired(value, fieldName);\n  if (!/^[a-f0-9]{40}$/i.test(value)) {\n    throw new ValidationError(\n      `${fieldName} must be a 40-character hex string`,\n      fieldName,\n      'INVALID_SHA'\n    );\n  }\n}\n\n/**\n * Validate an ISO 8601 date string\n */\nexport function validateDate(value: string, fieldName: string): void {\n  validateRequired(value, fieldName);\n  const date = new Date(value);\n  if (isNaN(date.getTime())) {\n    throw new ValidationError(\n      `${fieldName} must be a valid ISO 8601 date`,\n      fieldName,\n      'INVALID_DATE'\n    );\n  }\n}\n\n/**\n * Validate a string length\n */\nexport function validateStringLength(\n  value: string,\n  fieldName: string,\n  minLength: number,\n  maxLength: number\n): void {\n  if (typeof value !== 'string') {\n    throw new ValidationError(\n      `${fieldName} must be a string`,\n      fieldName,\n      'INVALID_STRING'\n    );\n  }\n  if (value.length < minLength || value.length > maxLength) {\n    throw new ValidationError(\n      `${fieldName} must be between ${minLength} and ${maxLength} characters`,\n      fieldName,\n      'INVALID_LENGTH'\n    );\n  }\n}\n\n// ============================================================================\n// Tool-Specific Validators\n// ============================================================================\n\ntype ValidatorFn = (args: Record<string, unknown>) => void;\n\n/**\n * Validators for each tool (22 tools)\n * These are applied before the tool handler is called\n */\nexport const toolValidators: Record<string, ValidatorFn> = {\n  // Queries\n  get: (args) => {\n    validateRequired(args.type, 'type');\n    validateEnum(\n      args.type as string,\n      'type',\n      ['project', 'specification', 'epic', 'ticket', 'implementation_session']\n    );\n  },\n\n  list: (args) => {\n    validateRequired(args.type, 'type');\n    validateEnum(\n      args.type as string,\n      'type',\n      ['projects', 'specifications', 'epics', 'tickets']\n    );\n  },\n\n  search: (args) => {\n    if (!args.query && !args.files && !args.tags && !args.relatedTo) {\n      throw new ValidationError(\n        'At least one filter is required: query, files, tags, or relatedTo',\n        'query',\n        'REQUIRED_ONE_OF'\n      );\n    }\n    if (args.query) {\n      validateStringLength(args.query as string, 'query', 1, 500);\n    }\n    if (args.limit !== undefined) {\n      validateRange(args.limit as number, 'limit', 1, 100);\n    }\n    if (args.offset !== undefined) {\n      validateRange(args.offset as number, 'offset', 0, 10000);\n    }\n  },\n\n  get_next_actionable_tickets: (args) => {\n    // Either specificationId or projectId is required\n    if (!args.specificationId && !args.projectId) {\n      throw new ValidationError(\n        'Either specificationId or projectId is required',\n        'specificationId/projectId',\n        'REQUIRED_ONE_OF'\n      );\n    }\n    if (args.limit !== undefined) {\n      validateRange(args.limit as number, 'limit', 1, 100);\n    }\n  },\n\n  get_blocked_tickets: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  get_report: (args) => {\n    validateRequired(args.type, 'type');\n    validateRequired(args.scope, 'scope');\n    validateRequired(args.scopeId, 'scopeId');\n  },\n\n  // Lifecycle. Planning verbs inject identity from local config (M9): SPS takes\n  // an optional specificationId (falls back to config), APS takes only\n  // `operation` (sessionId injected), CPS takes nothing (sessionId injected).\n  // So no specificationId/sessionId requirements here — the handlers resolve\n  // and validate them.\n  start_planning_session: () => {\n    /* specificationId optional — handler falls back to config */\n  },\n\n  action_planning_session: (args) => {\n    validateRequired(args.operation, 'operation');\n  },\n\n  complete_planning_session: () => {\n    /* no args — sessionId injected from config */\n  },\n\n  start_work_session: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n  },\n\n  action_work_session: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n    if (args.filesCreated !== undefined) {\n      validateArray(args.filesCreated, 'filesCreated');\n    }\n    if (args.filesModified !== undefined) {\n      validateArray(args.filesModified, 'filesModified');\n    }\n    if (args.filesDeleted !== undefined) {\n      validateArray(args.filesDeleted, 'filesDeleted');\n    }\n    if (args.clearBlockReason !== undefined && typeof args.clearBlockReason !== 'boolean') {\n      throw new Error('clearBlockReason must be a boolean');\n    }\n  },\n\n  complete_work_session: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n    validateRequired(args.summary, 'summary');\n    if (args.summary) {\n      validateStringLength(args.summary as string, 'summary', 1, 10000);\n    }\n    if (args.filesModified !== undefined) {\n      validateArray(args.filesModified, 'filesModified');\n    }\n    if (args.filesCreated !== undefined) {\n      validateArray(args.filesCreated, 'filesCreated');\n    }\n    if (args.filesDeleted !== undefined) {\n      validateArray(args.filesDeleted, 'filesDeleted');\n    }\n  },\n\n  reopen_specification: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  // Mutation\n  create_specification: (args) => {\n    validateRequired(args.projectId, 'projectId');\n    validateRequired(args.title, 'title');\n  },\n\n  // Utilities\n  feedback: () => {\n    // Validated by feedback handler\n  },\n\n  link_pull_request: (args) => {\n    validateRequired(args.ticketId, 'ticketId');\n    if (!args.prNumber && !args.prUrl) {\n      throw new ValidationError(\n        'Either prNumber or prUrl must be provided',\n        'prNumber',\n        'REQUIRED_ONE_OF'\n      );\n    }\n    if (args.prNumber !== undefined && typeof args.prNumber !== 'number') {\n      throw new ValidationError(\n        'prNumber must be a number',\n        'prNumber',\n        'INVALID_NUMBER'\n      );\n    }\n    if (args.prUrl !== undefined) {\n      const url = args.prUrl as string;\n      if (!url.includes('github.com') && !url.includes('gitlab.com') && !url.includes('bitbucket.org')) {\n        throw new ValidationError(\n          'prUrl must be a valid GitHub, GitLab, or Bitbucket URL',\n          'prUrl',\n          'INVALID_URL'\n        );\n      }\n    }\n  },\n\n  // Orchestration\n  get_critical_path: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n\n  get_dependency_tree: (args) => {\n    validateRequired(args.specificationId, 'specificationId');\n  },\n};\n\n// ============================================================================\n// Error Transformation\n// ============================================================================\n\n/**\n * MCP error response format\n */\nexport interface MCPErrorResponse {\n  content: Array<{\n    type: 'text';\n    text: string;\n  }>;\n  isError: true;\n}\n\n/**\n * Transform an error into MCP error response format\n */\nexport function formatMCPError(error: Error): MCPErrorResponse {\n  let message = error.message;\n\n  if (error instanceof ValidationError) {\n    message = `Validation error for '${error.field}': ${error.message} (${error.code})`;\n  } else if (error instanceof ApiError) {\n    message = formatApiErrorMessage(error);\n  }\n\n  return {\n    content: [\n      {\n        type: 'text',\n        text: message,\n      },\n    ],\n    isError: true,\n  };\n}\n\n/**\n * Format API error message based on status code\n */\nfunction formatApiErrorMessage(error: ApiError): string {\n  switch (error.statusCode) {\n    case 400:\n      return `Bad request: ${error.message}`;\n    case 401:\n      return 'Authentication failed. Check your API key.';\n    case 403:\n      return 'Permission denied. Your API key may lack required permissions.';\n    case 404:\n      return `Resource not found: ${error.message}`;\n    case 429:\n      return 'Rate limit exceeded. Please wait before retrying.';\n    case 500:\n    case 502:\n    case 503:\n    case 504:\n      return 'Server error. Please try again later.';\n    default:\n      return error.message;\n  }\n}\n\n/**\n * Transform HTTP/network errors into ApiError\n */\nexport function transformError(error: unknown): Error {\n  if (error instanceof ValidationError || error instanceof ApiError) {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    // Network errors\n    if (error.message.includes('ECONNREFUSED')) {\n      return new ApiError(\n        'Unable to connect to SpecForge API. Check your network connection.',\n        0,\n        'NETWORK_ERROR'\n      );\n    }\n    if (error.message.includes('ETIMEDOUT')) {\n      return new ApiError(\n        'Request timed out. Please try again.',\n        0,\n        'TIMEOUT'\n      );\n    }\n    if (error.message.includes('ECONNRESET')) {\n      return new ApiError(\n        'Connection was reset. Please try again.',\n        0,\n        'CONNECTION_RESET'\n      );\n    }\n\n    return error;\n  }\n\n  return new Error(String(error));\n}\n\n/**\n * Run validation for a specific tool\n * @throws ValidationError if validation fails\n */\nexport function validateToolArgs(\n  toolName: string,\n  args: Record<string, unknown>\n): void {\n  const validator = toolValidators[toolName];\n  if (validator) {\n    validator(args);\n  }\n}\n"],"mappings":"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","names":[]}

package/node_modules/@specforge/api-types/README.md

@@ -0,0 +1,38 @@
+# @specforge/api-types
+
+Catch-all type contracts for SpecForge.
+
+## Scope (catch-all rule)
+
+If a type is **not** a lifecycle session-type (those live in `@specforge/session-types`), it belongs here. spec-domain types — Spec, Epic, Ticket entities — live in `@specforge/spec-types`; everything else (User, Project, sharing, derived views, API helpers, and the store interfaces for non-session entities) lives in this package.
+
+## What's inside
+
+### Entity runtime types (`src/runtime/`)
+
+- `user.ts` — User entity
+- `project.ts` — Project entity (with denormalized counts)
+- `project-member.ts`, `project-invitation.ts` — sharing entities
+- `dependency-tree.ts` — derived view consumed by tree aggregator + webapp UI
+- `fields.ts` — field-selection helpers for list operations
+- `pagination.ts` — pagination input/info shapes + helpers
+- `summary.ts` — summary-mode response shapes
+- `response.ts` — response-mode types (full/minimal/id-only)
+- `status.ts` — ticket-status enums + transition helpers
+
+### Store interfaces (`src/stores/`)
+
+All non-session-types store contracts:
+
+- `i-user-store.ts`, `i-project-store.ts`, `i-sharing-store.ts` — user + sharing
+- `i-spec-store.ts`, `i-epic-store.ts`, `i-ticket-store.ts`, `i-ticket-dependency-store.ts`, `i-blueprint-store.ts` — spec hierarchy
+
+Sessions stay in `@specforge/session-types`. Read-only impls (planning) and full impls (spec hierarchy) live in `@specforge/operations`.
+
+## Rules
+
+- AWS SDK / smithy / sigv4 imports are forbidden (ESLint-enforced).
+- zod is allowed for entity schemas.
+- This package is consumed by `@specforge/lifecycle` and `@specforge/operations`.
+
+Per M4.7 milestone spec.

package/node_modules/@specforge/api-types/dist/client/appsync-client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structural contract for the AppSync GraphQL client.
+ *
+ * The concrete implementation (SigV4-signed, SSM-backed) lives in
+ * `@specforge/operations` and `implements` this interface. Relocated here in
+ * M7.4c so consumers that only need to *call* the client (e.g. the
+ * `@specforge/resolvers` notifier) can type against the contract without
+ * importing `@specforge/operations` — breaking the resolvers→operations
+ * arch-level cycle (monorepo-topology §2.1c).
+ */
+export interface AppSyncClient {
+    /** Resolve (and cache) the AppSync GraphQL endpoint URL. */
+    getApiUrl(): Promise<string>;
+    query<T>(query: string, variables?: Record<string, unknown>, options?: {
+        operationName?: string;
+    }): Promise<T>;
+    mutate<T>(mutation: string, variables?: Record<string, unknown>, options?: {
+        operationName?: string;
+    }): Promise<T>;
+}
+//# sourceMappingURL=appsync-client.d.ts.map

package/node_modules/@specforge/api-types/dist/client/appsync-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appsync-client.d.ts","sourceRoot":"","sources":["../../src/client/appsync-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,CAAC,EACL,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,MAAM,CAAC,CAAC,EACN,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,CAAC,CAAC,CAAC;CACf"}

package/node_modules/@specforge/api-types/dist/client/appsync-client.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=appsync-client.js.map

package/node_modules/@specforge/api-types/dist/client/appsync-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appsync-client.js","sourceRoot":"","sources":["../../src/client/appsync-client.ts"],"names":[],"mappings":""}

package/node_modules/@specforge/api-types/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export * from './appsync-client.js';
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@specforge/api-types/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/node_modules/@specforge/api-types/dist/client/index.js

@@ -0,0 +1,2 @@
+export * from './appsync-client.js';
+//# sourceMappingURL=index.js.map

package/node_modules/@specforge/api-types/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/node_modules/@specforge/api-types/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './runtime/index.js';
+export * from './stores/index.js';
+export * from './client/index.js';
+export * from './mcp/index.js';
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@specforge/api-types/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AAGnC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,gBAAgB,CAAC"}

package/node_modules/@specforge/api-types/dist/index.js

@@ -0,0 +1,9 @@
+// Entity records, derived views, and API-surface helpers.
+export * from './runtime/index.js';
+// Store contracts for non-session entities.
+export * from './stores/index.js';
+// Client contracts (structural interfaces; implementations live in operations).
+export * from './client/index.js';
+// MCP wire envelopes + error-guidance contract.
+export * from './mcp/index.js';
+//# sourceMappingURL=index.js.map

package/node_modules/@specforge/api-types/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,cAAc,oBAAoB,CAAC;AAEnC,4CAA4C;AAC5C,cAAc,mBAAmB,CAAC;AAElC,gFAAgF;AAChF,cAAc,mBAAmB,CAAC;AAElC,gDAAgD;AAChD,cAAc,gBAAgB,CAAC"}

package/node_modules/@specforge/api-types/dist/mcp/error-guidance.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared type contract for the error-guidance composer pipeline (ME.4).
+ *
+ * Mirrors the lifecycle guidance pipeline (`PlanningAgentResponse.guidance`),
+ * but for the failure modes that produce an `McpStandardErrorEnvelope` — auth,
+ * shape, not-found, conflict, precondition, unknown-tool, bare exceptions.
+ *
+ * This file is a PURE type contract: no runtime, no composer. The three
+ * composers (`composeCrudErrorGuidance` in `@specforge/core`,
+ * `composeAuthErrorGuidance` / `composeBasicErrorGuidance` in
+ * `@specforge/platform`) all consume `ErrorGuidanceInput` and return a non-null
+ * `ErrorGuidance` (MB.17.2 amended the ME.4 `INTERNAL → null` convention: every
+ * code now emits a recovery hint). The M8 dispatcher's `normaliseError` is the
+ * single place that assembles the envelope from the returned guidance — the
+ * composers never reference `McpStandardErrorEnvelope` (Option A, ME.4 §2 decision).
+ *
+ * Canonical reference: docs/architecture/lifecycle-response-convention.md
+ * §"Error envelope guidance".
+ */
+/**
+ * Output of the error-guidance composer pipeline. `prose` is the canonical
+ * agent-facing message — same convention as lifecycle's
+ * `PlanningAgentResponse.guidance` (clients read prose verbatim; never parse
+ * it). `next_actions` / `related` are structured accessories for UI clients
+ * that want to render tool affordances.
+ */
+export interface ErrorGuidance {
+    prose: string;
+    next_actions?: {
+        tool: string;
+        args?: Record<string, unknown>;
+        reason?: string;
+    }[];
+    related?: {
+        tool: string;
+        args?: Record<string, unknown>;
+    }[];
+}
+/**
+ * Closed set of entity types an error can reference. Declared here so both the
+ * CRUD error classes (operations) and the composers (core/platform) share one
+ * definition.
+ */
+export type ErrorGuidanceEntityType = 'spec' | 'epic' | 'ticket' | 'planning_session' | 'blueprint' | 'project' | 'pull_request' | 'dependency' | 'ticket_blueprint_ref';
+/** The seven MCP error codes a public tool can surface (ME.4 §2.5). */
+export type ErrorGuidanceCode = 'NOT_FOUND' | 'VALIDATION_FAILED' | 'CONFLICT' | 'PRECONDITION_FAILED' | 'UNAUTHORISED' | 'UNKNOWN_TOOL' | 'INTERNAL';
+/**
+ * Shared input shape consumed by all three composers. Materialised by each
+ * typed error class's `toGuidanceInput(ctx)` (CRUD/auth) or synthesised by the
+ * dispatcher (basic / unknown-tool).
+ */
+export interface ErrorGuidanceInput {
+    code: ErrorGuidanceCode;
+    /** Verb that threw. */
+    tool: string;
+    args?: Record<string, unknown>;
+    context: {
+        entityType?: ErrorGuidanceEntityType;
+        entityId?: string;
+        /** VALIDATION_FAILED — the field that failed the schema. */
+        failingField?: string;
+        /** PRECONDITION_FAILED — status the verb required. */
+        expectedStatus?: string;
+        /** PRECONDITION_FAILED — status the entity is actually in. */
+        actualStatus?: string;
+        /** CONFLICT — the pre-existing entity that collides. */
+        conflictingEntityId?: string;
+        /** UNAUTHORISED — the scope/permission that was missing. */
+        requiredScope?: string;
+        /** UNKNOWN_TOOL — the registered verbs, for the "did you mean" hint. */
+        availableTools?: string[];
+    };
+}
+//# sourceMappingURL=error-guidance.d.ts.map

package/node_modules/@specforge/api-types/dist/mcp/error-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-guidance.d.ts","sourceRoot":"","sources":["../../src/mcp/error-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnF,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;CAC9D;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,MAAM,GACN,QAAQ,GACR,kBAAkB,GAClB,WAAW,GACX,SAAS,GACT,cAAc,GACd,YAAY,GACZ,sBAAsB,CAAC;AAE3B,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,mBAAmB,GACnB,UAAU,GACV,qBAAqB,GACrB,cAAc,GACd,cAAc,GACd,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,CAAC;IACxB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE;QACP,UAAU,CAAC,EAAE,uBAAuB,CAAC;QACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,4DAA4D;QAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,sDAAsD;QACtD,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,8DAA8D;QAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,wDAAwD;QACxD,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,4DAA4D;QAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,wEAAwE;QACxE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;CACH"}

package/node_modules/@specforge/api-types/dist/mcp/error-guidance.js

@@ -0,0 +1,21 @@
+/**
+ * Shared type contract for the error-guidance composer pipeline (ME.4).
+ *
+ * Mirrors the lifecycle guidance pipeline (`PlanningAgentResponse.guidance`),
+ * but for the failure modes that produce an `McpStandardErrorEnvelope` — auth,
+ * shape, not-found, conflict, precondition, unknown-tool, bare exceptions.
+ *
+ * This file is a PURE type contract: no runtime, no composer. The three
+ * composers (`composeCrudErrorGuidance` in `@specforge/core`,
+ * `composeAuthErrorGuidance` / `composeBasicErrorGuidance` in
+ * `@specforge/platform`) all consume `ErrorGuidanceInput` and return a non-null
+ * `ErrorGuidance` (MB.17.2 amended the ME.4 `INTERNAL → null` convention: every
+ * code now emits a recovery hint). The M8 dispatcher's `normaliseError` is the
+ * single place that assembles the envelope from the returned guidance — the
+ * composers never reference `McpStandardErrorEnvelope` (Option A, ME.4 §2 decision).
+ *
+ * Canonical reference: docs/architecture/lifecycle-response-convention.md
+ * §"Error envelope guidance".
+ */
+export {};
+//# sourceMappingURL=error-guidance.js.map

package/node_modules/@specforge/api-types/dist/mcp/error-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-guidance.js","sourceRoot":"","sources":["../../src/mcp/error-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/node_modules/@specforge/api-types/dist/mcp/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lifecycle-envelope.js';
+export * from './error-guidance.js';
+export * from './standard-envelope.js';
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@specforge/api-types/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AACA,cAAc,yBAAyB,CAAC;AAIxC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,wBAAwB,CAAC"}

package/node_modules/@specforge/api-types/dist/mcp/index.js

@@ -0,0 +1,8 @@
+// MCP wire envelopes shared by CLI, webapp, and external MCP clients.
+export * from './lifecycle-envelope.js';
+// Error-guidance contract consumed by the composer pipeline (ME.4) and the
+// M8 standard-error envelope.
+export * from './error-guidance.js';
+// Standard (non-lifecycle) error envelope (M8).
+export * from './standard-envelope.js';
+//# sourceMappingURL=index.js.map

package/node_modules/@specforge/api-types/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,cAAc,yBAAyB,CAAC;AAExC,2EAA2E;AAC3E,8BAA8B;AAC9B,cAAc,qBAAqB,CAAC;AAEpC,gDAAgD;AAChD,cAAc,wBAAwB,CAAC"}