@specforge/cli 0.1.0

package/dist/transport/resolve-endpoint.js

@@ -0,0 +1,146 @@
+import { promises as fs } from "node:fs";
+import { mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { CHANNEL } from "../channel.js";
+const DEFAULT_PROBE_TIMEOUT_MS = 2e3;
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+function cacheDir(opts) {
+  const base = opts.cacheBaseDir ?? os.homedir();
+  const dir = opts.configDir ?? CHANNEL.configDir;
+  return path.join(base, dir);
+}
+function cachePath(input, opts) {
+  return path.join(cacheDir(opts), `${input.cacheKey}.json`);
+}
+async function readCache(input, opts) {
+  const file = cachePath(input, opts);
+  let raw;
+  try {
+    raw = await readFile(file, "utf-8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed?.url !== "string" || typeof parsed?.timestamp !== "number") {
+    return null;
+  }
+  const ttl = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  if (Date.now() - parsed.timestamp > ttl) {
+    return null;
+  }
+  if (parsed.url !== input.primary && parsed.url !== input.fallback) {
+    return null;
+  }
+  return parsed.url;
+}
+async function writeCache(input, url, opts) {
+  const dir = cacheDir(opts);
+  await mkdir(dir, { recursive: true, mode: 448 });
+  const entry = { url, timestamp: Date.now() };
+  await writeFile(cachePath(input, opts), JSON.stringify(entry), { mode: 384 });
+}
+function isDnsClassError(err) {
+  if (!err) return false;
+  if (err instanceof Error) {
+    if (err.name === "AbortError") return true;
+    const msg = err.message;
+    if (msg.includes("ENOTFOUND")) return true;
+    if (msg.includes("ENETUNREACH")) return true;
+    if (msg.includes("EAI_AGAIN")) return true;
+    if (msg.includes("ECONNREFUSED")) return true;
+    if (msg.includes("CERT_") || msg.includes("TLS") || msg.includes("handshake")) return true;
+    const cause = err.cause;
+    if (cause) return isDnsClassError(cause);
+  }
+  const code = err.code;
+  if (typeof code === "string") {
+    if (code === "ENOTFOUND" || code === "ENETUNREACH" || code === "EAI_AGAIN" || code === "ECONNREFUSED") {
+      return true;
+    }
+    if (code.startsWith("ERR_TLS_") || code.startsWith("CERT_")) return true;
+  }
+  return false;
+}
+async function probeOnce(url, opts) {
+  const timeoutMs = opts.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const probe = opts.probe ?? ((u, signal) => fetch(u, { method: "GET", signal }));
+    const res = await probe(url, controller.signal);
+    return { ok: res.ok, status: res.status };
+  } catch (err) {
+    return { ok: false, error: err };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function resolveEndpoint(input, opts = {}) {
+  const cached = await readCache(input, opts);
+  if (cached) return cached;
+  const primaryRes = await probeOnce(input.healthPrimary, opts);
+  if (primaryRes.ok) {
+    await writeCache(input, input.primary, opts);
+    return input.primary;
+  }
+  if (!isDnsClassError(primaryRes.error)) {
+    if (primaryRes.status) {
+      throw new Error(
+        `Endpoint probe of ${input.healthPrimary} returned ${primaryRes.status}; backend reachable but unhealthy. Not falling over.`
+      );
+    }
+    throw new Error(
+      `Endpoint probe of ${input.healthPrimary} failed but the backend was reachable (${describeProbe(primaryRes)}). Not falling over.`
+    );
+  }
+  const fallbackRes = await probeOnce(input.healthFallback, opts);
+  if (fallbackRes.ok) {
+    await writeCache(input, input.fallback, opts);
+    return input.fallback;
+  }
+  throw new Error(
+    `Both endpoint probes failed.
+  primary  ${input.healthPrimary}: ${describeProbe(primaryRes)}
+  fallback ${input.healthFallback}: ${describeProbe(fallbackRes)}
+Check your network connection.`
+  );
+}
+async function invalidate(cacheKey, opts = {}) {
+  const file = path.join(cacheDir(opts), `${cacheKey}.json`);
+  try {
+    await unlink(file);
+  } catch {
+  }
+}
+function describeProbe(res) {
+  if (res.error) {
+    const err = res.error;
+    if (err instanceof Error) {
+      const cause = err.cause;
+      const causeMsg = cause instanceof Error ? ` (cause: ${cause.message})` : "";
+      return `${err.name}: ${err.message}${causeMsg}`;
+    }
+    return String(err);
+  }
+  return `HTTP ${res.status ?? "?"}`;
+}
+function shouldInvalidateOnStatus(status) {
+  return status === 401 || status === 403;
+}
+import { CHANNEL as CHANNEL2 } from "../channel.js";
+void fs;
+export {
+  CHANNEL2 as CHANNEL,
+  DEFAULT_CACHE_TTL_MS,
+  DEFAULT_PROBE_TIMEOUT_MS,
+  invalidate,
+  resolveEndpoint,
+  shouldInvalidateOnStatus
+};
+//# sourceMappingURL=resolve-endpoint.js.map

package/dist/transport/resolve-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/transport/resolve-endpoint.ts"],"sourcesContent":["/**\n * Endpoint resolver — picks `primary` or `fallback` per the canary-channel\n * client probe contract (PLAN-canary-channel.md §D).\n *\n * Cache file: `${homedir}/${CHANNEL.configDir}/${cacheKey}.json`. TTL: 5 min.\n *\n * Probe: GET `healthPrimary` with a 2 s timeout. On success → cache `primary`\n * and return it. On a DNS-class failure (`ENOTFOUND`, `ENETUNREACH`, TLS\n * handshake, `AbortError` from the timeout) → probe `healthFallback`. On\n * success → cache `fallback` and return it. Both fail → throw a clear\n * network error.\n *\n * `5xx`, `429`, `401`, `403` from the real call do NOT trigger fallover —\n * those mean the backend is reachable but rejecting. Callers handle them\n * directly and may invalidate the cache via `invalidate(cacheKey)` on\n * auth-class failures so the next call re-probes.\n */\n\nimport { promises as fs } from 'node:fs';\nimport { mkdir, readFile, writeFile, unlink } from 'node:fs/promises';\nimport path from 'node:path';\nimport os from 'node:os';\nimport { CHANNEL } from '../channel.js';\n\nexport interface ResolveEndpointInput {\n  /** Primary URL — production target on stable, dev target on canary. */\n  primary: string;\n  /** Fallback URL — used on DNS-class failure of primary. */\n  fallback: string;\n  /** `GET`-able probe target on the primary surface. */\n  healthPrimary: string;\n  /** `GET`-able probe target on the fallback surface. */\n  healthFallback: string;\n  /** Filename stem for the cache file under `~/${CHANNEL.configDir}/`. */\n  cacheKey: string;\n}\n\nexport interface ResolveEndpointOptions {\n  /** Override the per-call probe timeout (ms). Default 2000. */\n  probeTimeoutMs?: number;\n  /** Override the cache TTL (ms). Default 5 minutes. */\n  cacheTtlMs?: number;\n  /** Override the cache directory (testing). Default `os.homedir()`. */\n  cacheBaseDir?: string;\n  /** Override the channel config dir (testing). Default `CHANNEL.configDir`. */\n  configDir?: string;\n  /** Inject a custom probe function (testing). Default uses `fetch`. */\n  probe?: (url: string, signal: AbortSignal) => Promise<Response>;\n}\n\nexport const DEFAULT_PROBE_TIMEOUT_MS = 2_000;\nexport const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1_000;\n\ninterface CacheEntry {\n  url: string;\n  /** Epoch ms when the cache entry was written. */\n  timestamp: number;\n}\n\nfunction cacheDir(opts: ResolveEndpointOptions): string {\n  const base = opts.cacheBaseDir ?? os.homedir();\n  const dir = opts.configDir ?? CHANNEL.configDir;\n  return path.join(base, dir);\n}\n\nfunction cachePath(input: ResolveEndpointInput, opts: ResolveEndpointOptions): string {\n  return path.join(cacheDir(opts), `${input.cacheKey}.json`);\n}\n\nasync function readCache(input: ResolveEndpointInput, opts: ResolveEndpointOptions): Promise<string | null> {\n  const file = cachePath(input, opts);\n  let raw: string;\n  try {\n    raw = await readFile(file, 'utf-8');\n  } catch {\n    return null;\n  }\n  let parsed: CacheEntry;\n  try {\n    parsed = JSON.parse(raw) as CacheEntry;\n  } catch {\n    return null;\n  }\n  if (typeof parsed?.url !== 'string' || typeof parsed?.timestamp !== 'number') {\n    return null;\n  }\n  const ttl = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;\n  if (Date.now() - parsed.timestamp > ttl) {\n    return null;\n  }\n  // Only honor cache entries that match one of the current spec's URLs;\n  // otherwise the channel changed underneath us.\n  if (parsed.url !== input.primary && parsed.url !== input.fallback) {\n    return null;\n  }\n  return parsed.url;\n}\n\nasync function writeCache(\n  input: ResolveEndpointInput,\n  url: string,\n  opts: ResolveEndpointOptions,\n): Promise<void> {\n  const dir = cacheDir(opts);\n  await mkdir(dir, { recursive: true, mode: 0o700 });\n  const entry: CacheEntry = { url, timestamp: Date.now() };\n  await writeFile(cachePath(input, opts), JSON.stringify(entry), { mode: 0o600 });\n}\n\n/**\n * DNS-class failure: errors that mean the request never reached a backend.\n * Treat as \"primary unreachable, try fallback\". Errors that DO reach a\n * backend (TLS-validated 5xx/4xx, ECONNRESET mid-stream) are NOT DNS-class.\n */\nfunction isDnsClassError(err: unknown): boolean {\n  if (!err) return false;\n  if (err instanceof Error) {\n    if (err.name === 'AbortError') return true;\n    const msg = err.message;\n    if (msg.includes('ENOTFOUND')) return true;\n    if (msg.includes('ENETUNREACH')) return true;\n    if (msg.includes('EAI_AGAIN')) return true;\n    if (msg.includes('ECONNREFUSED')) return true;\n    // TLS handshake failures are DNS-class for our purposes (fallback is\n    // a different cert / different ALB which may be healthy).\n    if (msg.includes('CERT_') || msg.includes('TLS') || msg.includes('handshake')) return true;\n    // node fetch wraps DNS errors as \"fetch failed\" with a `cause` property.\n    const cause = (err as Error & { cause?: unknown }).cause;\n    if (cause) return isDnsClassError(cause);\n  }\n  // System errors carry `code` directly.\n  const code = (err as { code?: unknown }).code;\n  if (typeof code === 'string') {\n    if (code === 'ENOTFOUND' || code === 'ENETUNREACH' || code === 'EAI_AGAIN' || code === 'ECONNREFUSED') {\n      return true;\n    }\n    if (code.startsWith('ERR_TLS_') || code.startsWith('CERT_')) return true;\n  }\n  return false;\n}\n\nasync function probeOnce(\n  url: string,\n  opts: ResolveEndpointOptions,\n): Promise<{ ok: boolean; status?: number; error?: unknown }> {\n  const timeoutMs = opts.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), timeoutMs);\n  try {\n    const probe = opts.probe ?? ((u, signal) => fetch(u, { method: 'GET', signal }));\n    const res = await probe(url, controller.signal);\n    return { ok: res.ok, status: res.status };\n  } catch (err) {\n    return { ok: false, error: err };\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Resolve a usable endpoint URL by checking the cache, then probing.\n * Throws when both probes fail.\n */\nexport async function resolveEndpoint(\n  input: ResolveEndpointInput,\n  opts: ResolveEndpointOptions = {},\n): Promise<string> {\n  const cached = await readCache(input, opts);\n  if (cached) return cached;\n\n  // Probe primary first.\n  const primaryRes = await probeOnce(input.healthPrimary, opts);\n  if (primaryRes.ok) {\n    await writeCache(input, input.primary, opts);\n    return input.primary;\n  }\n\n  // Anything that ISN'T DNS-class means primary is reachable — either an\n  // HTTP response (4xx/5xx) or a post-connect error (ECONNRESET, etc.).\n  // Bubble up; do not fall over.\n  if (!isDnsClassError(primaryRes.error)) {\n    if (primaryRes.status) {\n      throw new Error(\n        `Endpoint probe of ${input.healthPrimary} returned ${primaryRes.status}; ` +\n          `backend reachable but unhealthy. Not falling over.`,\n      );\n    }\n    throw new Error(\n      `Endpoint probe of ${input.healthPrimary} failed but the backend was ` +\n        `reachable (${describeProbe(primaryRes)}). Not falling over.`,\n    );\n  }\n\n  // DNS-class failure on primary → probe fallback.\n  const fallbackRes = await probeOnce(input.healthFallback, opts);\n  if (fallbackRes.ok) {\n    await writeCache(input, input.fallback, opts);\n    return input.fallback;\n  }\n\n  throw new Error(\n    `Both endpoint probes failed.\\n` +\n      `  primary  ${input.healthPrimary}: ${describeProbe(primaryRes)}\\n` +\n      `  fallback ${input.healthFallback}: ${describeProbe(fallbackRes)}\\n` +\n      `Check your network connection.`,\n  );\n}\n\n/** Wipe the cache for a given key — call on auth-class failures. */\nexport async function invalidate(cacheKey: string, opts: ResolveEndpointOptions = {}): Promise<void> {\n  const file = path.join(cacheDir(opts), `${cacheKey}.json`);\n  try {\n    await unlink(file);\n  } catch {\n    // No cache file → already invalidated.\n  }\n}\n\nfunction describeProbe(res: { ok: boolean; status?: number; error?: unknown }): string {\n  if (res.error) {\n    const err = res.error;\n    if (err instanceof Error) {\n      const cause = (err as Error & { cause?: unknown }).cause;\n      const causeMsg = cause instanceof Error ? ` (cause: ${cause.message})` : '';\n      return `${err.name}: ${err.message}${causeMsg}`;\n    }\n    return String(err);\n  }\n  return `HTTP ${res.status ?? '?'}`;\n}\n\n/**\n * Helper: should the caller invalidate the cache after this status?\n * 401/403 from a real call are auth-class; tomorrow's call should re-probe\n * in case the operator pointed the channel elsewhere.\n */\nexport function shouldInvalidateOnStatus(status: number): boolean {\n  return status === 401 || status === 403;\n}\n\n// Re-export for convenience so callers get all symbols from one module.\nexport { CHANNEL } from '../channel.js';\n\n// Suppress lint about unused promises import (kept for future use in tests).\nvoid fs;\n"],"mappings":"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","names":["CHANNEL"]}

package/dist/types/index.d.ts

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ */
+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';
+/**
+ * Structured acceptance criterion with validation state.
+ */
+export interface AcceptanceCriterion {
+    id: string;
+    description: string;
+    validated: boolean;
+    validatedAt?: string;
+    validatedBy?: string;
+    notes?: string;
+}
+/**
+ * Normalizes acceptance criteria from legacy string[] format to structured
+ * `AcceptanceCriterion[]`. Provides backwards compatibility for old data
+ * stored as string arrays.
+ */
+export declare function normalizeAcceptanceCriteria(criteria: (string | AcceptanceCriterion)[]): AcceptanceCriterion[];
+export interface RelatedTicketSummary {
+    id: string;
+    title: string;
+    status: TicketStatus;
+    sameEpic: boolean;
+}
+export interface TestResultSummary {
+    id: string;
+    testType?: string;
+    allPassed: boolean;
+    passed: number;
+    failed: number;
+    total: number;
+    runAt: string;
+}
+export interface PreviousAttempt {
+    attemptNumber: number;
+    startedAt: string;
+    endedAt?: string;
+    result: 'completed' | 'failed' | 'in_progress';
+    testResults: TestResultSummary[];
+    summary?: string;
+}
+export interface DiscoverySummary {
+    id: string;
+    type: string;
+    severity: string;
+    status: string;
+    title: string;
+    description: string;
+    createdAt: string;
+}
+export interface ActiveSessionSummary {
+    id: string;
+    status: string;
+    startedAt: string;
+    config: unknown;
+    ticketsCompleted: string[];
+    ticketsFailed: string[];
+    ticketsSkipped: string[];
+    totalActiveMinutes: number;
+}
+/**
+ * Implementation context returned by get_implementation_context.
+ */
+export interface ImplementationContext {
+    /** The ticket being implemented */
+    ticket: Ticket;
+    /** The epic containing the ticket */
+    epic: Epic;
+    /** The specification containing the epic */
+    specification: Specification;
+    /** Dependency information */
+    dependencies: {
+        /** Tickets that must be completed before this one */
+        blockedBy: DependencyTicketSummary[];
+        /** Tickets waiting on this one */
+        blocks: DependencyTicketSummary[];
+    };
+    /** Related tickets */
+    relatedTickets: RelatedTicketSummary[];
+    /** Patterns and conventions from the project */
+    patterns?: Record<string, unknown>;
+    /** Active implementation session (Phase 5) */
+    activeSession: ActiveSessionSummary | null;
+    /** Previous implementation attempts (Phase 5) */
+    previousAttempts: PreviousAttempt[];
+    /** Related discoveries (Phase 5) */
+    relatedDiscoveries: DiscoverySummary[];
+}
+export interface WorkSession {
+    id: string;
+    ticketId: string;
+    specificationId: string;
+    projectId: string;
+    epicId: string;
+    implementationSessionId?: string;
+    status: 'active' | 'paused' | 'completed' | 'failed';
+    startedAt: string;
+    pausedAt?: string;
+    completedAt?: string;
+    actualHours?: number;
+    filesCreated?: string[];
+    filesModified?: string[];
+    filesDeleted?: string[];
+    testsPassed?: boolean;
+    retryCount: number;
+    retryLog?: unknown;
+    actions?: unknown;
+    completionAttempts?: unknown;
+    tokensUsed?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    costUsd?: number;
+    durationMs?: number;
+    commitSha?: string;
+    modelUsed?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TicketAcceptanceCriterion {
+    id: string;
+    ticketId: string;
+    description: string;
+    order: number;
+    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;
+    text: string;
+    order: number;
+    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;
+    workSessionId: string;
+    testType: TestType;
+    passed: boolean;
+    totalTests: number;
+    passedTests: number;
+    failedTests: number;
+    skippedTests: number;
+    coverage?: number;
+    errorDetails?: string;
+    command?: string;
+    exitCode?: number;
+    durationMs?: number;
+    errorCount?: number;
+    warningCount?: number;
+    summary?: string;
+    suites?: Array<{
+        name: string;
+        passed: number;
+        failed: number;
+        skipped?: number;
+        duration?: number;
+    }>;
+    runAt: string;
+}
+/** @deprecated Use WorkSessionTestResult instead */
+export type TicketTestResult = WorkSessionTestResult;
+export type LinkType = 'commit' | 'pull_request' | 'branch';
+export interface TicketLink {
+    id: string;
+    ticketId: string;
+    linkType: LinkType;
+    url: string;
+    sha?: string;
+    prNumber?: number;
+    title?: string;
+    status?: string;
+    createdAt: string;
+}
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/types/index.js

@@ -0,0 +1,16 @@
+function normalizeAcceptanceCriteria(criteria) {
+  return criteria.map((c, index) => {
+    if (typeof c === "string") {
+      return {
+        id: `ac-${index}-${Date.now()}`,
+        description: c,
+        validated: false
+      };
+    }
+    return c;
+  });
+}
+export {
+  normalizeAcceptanceCriteria
+};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +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":[]}

package/dist/validation/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Validation Utilities for MCP Tools
+ *
+ * Provides comprehensive input validation and error handling for all MCP tools.
+ * Validation is run before each tool call to ensure proper argument types and formats.
+ */
+export { type TicketComplexity, type WarningSeverity, type StrictnessLevel, type ValidationWarning, type TicketValidationResult, type ComplexityRules, type TicketValidationInput, validationRules, validateTicket, filterWarningsByStrictness, getComplexityRules, isValidComplexity, getComplexityDescription, suggestComplexity, } from './ticket-validation.js';
+/**
+ * Custom error class for validation failures
+ * Includes field name and error code for structured error handling
+ */
+export declare class ValidationError extends Error {
+    field: string;
+    code: string;
+    constructor(message: string, field: string, code: string);
+}
+/**
+ * API Error class for handling HTTP errors from the backend
+ */
+export declare class ApiError extends Error {
+    statusCode: number;
+    errorCode?: string | undefined;
+    constructor(message: string, statusCode: number, errorCode?: string | undefined);
+}
+/**
+ * Validate that a value is present (not null, undefined, or empty string)
+ */
+export declare function validateRequired(value: unknown, fieldName: string): void;
+/**
+ * Validate that a value is a valid UUID format
+ */
+export declare function validateUUID(value: string, fieldName: string): void;
+/**
+ * Validate that a value is one of the allowed enum values
+ */
+export declare function validateEnum(value: string, fieldName: string, allowedValues: string[]): void;
+/**
+ * Validate that a number is within a range
+ */
+export declare function validateRange(value: number, fieldName: string, min: number, max: number): void;
+/**
+ * Validate that a value is an array, with optional item validation
+ */
+export declare function validateArray(value: unknown, fieldName: string, itemValidator?: (item: unknown, index: number) => void): void;
+/**
+ * Validate a 40-character hex SHA
+ */
+export declare function validateSha(value: string, fieldName?: string): void;
+/**
+ * Validate an ISO 8601 date string
+ */
+export declare function validateDate(value: string, fieldName: string): void;
+/**
+ * Validate a string length
+ */
+export declare function validateStringLength(value: string, fieldName: string, minLength: number, maxLength: number): void;
+type ValidatorFn = (args: Record<string, unknown>) => void;
+/**
+ * Validators for each tool (22 tools)
+ * These are applied before the tool handler is called
+ */
+export declare const toolValidators: Record<string, ValidatorFn>;
+/**
+ * MCP error response format
+ */
+export interface MCPErrorResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: true;
+}
+/**
+ * Transform an error into MCP error response format
+ */
+export declare function formatMCPError(error: Error): MCPErrorResponse;
+/**
+ * Transform HTTP/network errors into ApiError
+ */
+export declare function transformError(error: unknown): Error;
+/**
+ * Run validation for a specific tool
+ * @throws ValidationError if validation fails
+ */
+export declare function validateToolArgs(toolName: string, args: Record<string, unknown>): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}