unspaghettit 0.2.0 → 0.4.0

package/mcp-server/migrate-defaults.ts

@@ -1,164 +1,164 @@
-#!/usr/bin/env node
-/**
- * One-shot migration: walks every `unspa/*.feature.json` snapshot,
- * coerces every `defaultValue` (state definitions + action parameters)
- * into a value that matches its declared `type`, and writes the result back
- * atomically. Idempotent. Already-clean files are skipped.
- *
- * Why this exists: early snapshots stored defaults as JSON-encoded strings
- * (`"365"` for `type: number`, `"\"helper\""` for `type: enum`, etc.). The
- * runtime validator now rejects that shape, so this script brings legacy
- * snapshots up to spec before the stricter validator catches them.
- *
- * Run with: `npm run migrate:defaults` (uses tsx).
- */
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import writeFileAtomic from 'write-file-atomic';
-import type { Action } from '../src/features/behavior-model/domain/entities/Action';
-import type { Feature } from '../src/features/behavior-model/domain/entities/Feature';
-import type { Parameter } from '../src/features/behavior-model/domain/entities/Parameter';
-import type { StateDefinition } from '../src/features/behavior-model/domain/entities/StateDefinition';
-import type { Surface } from '../src/features/behavior-model/domain/entities/Surface';
-import { coerceDefaultValue } from '../src/features/behavior-model/domain/services/StateValueCoercion';
-import { discoverSnapshotDirectory } from '../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
-
-const SNAPSHOT_SUFFIX = '.feature.json';
-
-type FileReport = {
-  readonly file: string;
-  readonly stateDefsFixed: number;
-  readonly parametersFixed: number;
-};
-
-const migrateStateDefinition = (
-  def: StateDefinition
-): { readonly next: StateDefinition; readonly changed: boolean } => {
-  const result = coerceDefaultValue(def.defaultValue, def.type, def.enumValues);
-  return {
-    next: result.changed ? { ...def, defaultValue: result.value } : def,
-    changed: result.changed
-  };
-};
-
-const migrateParameter = (
-  p: Parameter
-): { readonly next: Parameter; readonly changed: boolean } => {
-  if (p.defaultValue === undefined) return { next: p, changed: false };
-  const result = coerceDefaultValue(p.defaultValue, p.type, p.enumValues);
-  return {
-    next: result.changed ? { ...p, defaultValue: result.value } : p,
-    changed: result.changed
-  };
-};
-
-const migrateCapability = (
-  cap: Action
-): { readonly next: Action; readonly fixed: number } => {
-  let fixed = 0;
-  const parameters = cap.parameters.map((p) => {
-    const r = migrateParameter(p);
-    if (r.changed) fixed += 1;
-    return r.next;
-  });
-  return {
-    next: fixed > 0 ? { ...cap, parameters } : cap,
-    fixed
-  };
-};
-
-const migrateSurface = (
-  surface: Surface
-): { readonly next: Surface; readonly stateDefsFixed: number; readonly parametersFixed: number } => {
-  let stateDefsFixed = 0;
-  const stateDefinitions = surface.stateDefinitions.map((d) => {
-    const r = migrateStateDefinition(d);
-    if (r.changed) stateDefsFixed += 1;
-    return r.next;
-  });
-  let parametersFixed = 0;
-  const actions = surface.actions.map((c) => {
-    const r = migrateCapability(c);
-    parametersFixed += r.fixed;
-    return r.next;
-  });
-  const changed = stateDefsFixed > 0 || parametersFixed > 0;
-  return {
-    next: changed ? { ...surface, stateDefinitions, actions } : surface,
-    stateDefsFixed,
-    parametersFixed
-  };
-};
-
-const migrateFeature = (
-  exp: Feature
-): { readonly next: Feature; readonly stateDefsFixed: number; readonly parametersFixed: number } => {
-  let stateDefsFixed = 0;
-  let parametersFixed = 0;
-  const surfaces = exp.surfaces.map((s) => {
-    const r = migrateSurface(s);
-    stateDefsFixed += r.stateDefsFixed;
-    parametersFixed += r.parametersFixed;
-    return r.next;
-  });
-  const changed = stateDefsFixed > 0 || parametersFixed > 0;
-  return {
-    next: changed ? { ...exp, surfaces } : exp,
-    stateDefsFixed,
-    parametersFixed
-  };
-};
-
-const migrateFile = async (path: string): Promise<FileReport> => {
-  const raw = readFileSync(path, 'utf8');
-  const parsed = JSON.parse(raw) as { readonly feature: Feature };
-  if (!parsed.feature) {
-    return { file: path, stateDefsFixed: 0, parametersFixed: 0 };
-  }
-  const result = migrateFeature(parsed.feature);
-  if (result.stateDefsFixed === 0 && result.parametersFixed === 0) {
-    return { file: path, stateDefsFixed: 0, parametersFixed: 0 };
-  }
-  const nextEnvelope = { ...parsed, feature: result.next };
-  await writeFileAtomic(path, JSON.stringify(nextEnvelope, null, 2), 'utf8');
-  return {
-    file: path,
-    stateDefsFixed: result.stateDefsFixed,
-    parametersFixed: result.parametersFixed
-  };
-};
-
-const main = async (): Promise<void> => {
-  const { directory } = discoverSnapshotDirectory({});
-  if (!existsSync(directory)) {
-    process.stderr.write(`[migrate-defaults] no snapshot directory at ${directory}\n`);
-    process.exit(1);
-  }
-  const files = readdirSync(directory).filter((f) => f.endsWith(SNAPSHOT_SUFFIX));
-  process.stderr.write(
-    `[migrate-defaults] scanning ${files.length} file(s) in ${directory}\n`
-  );
-
-  let totalStateDefs = 0;
-  let totalParams = 0;
-  let touched = 0;
-  for (const file of files) {
-    const report = await migrateFile(join(directory, file));
-    if (report.stateDefsFixed > 0 || report.parametersFixed > 0) {
-      touched += 1;
-      totalStateDefs += report.stateDefsFixed;
-      totalParams += report.parametersFixed;
-      process.stderr.write(
-        `  fixed ${file}: ${report.stateDefsFixed} state default(s), ${report.parametersFixed} parameter default(s)\n`
-      );
-    }
-  }
-  process.stderr.write(
-    `[migrate-defaults] done. ${touched}/${files.length} file(s) touched, ${totalStateDefs} state default(s) + ${totalParams} parameter default(s) coerced.\n`
-  );
-};
-
-main().catch((err) => {
-  process.stderr.write(`[migrate-defaults] fatal: ${(err as Error).message}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+/**
+ * One-shot migration: walks every `unspa/*.feature.json` snapshot,
+ * coerces every `defaultValue` (state definitions + action parameters)
+ * into a value that matches its declared `type`, and writes the result back
+ * atomically. Idempotent. Already-clean files are skipped.
+ *
+ * Why this exists: early snapshots stored defaults as JSON-encoded strings
+ * (`"365"` for `type: number`, `"\"helper\""` for `type: enum`, etc.). The
+ * runtime validator now rejects that shape, so this script brings legacy
+ * snapshots up to spec before the stricter validator catches them.
+ *
+ * Run with: `npm run migrate:defaults` (uses tsx).
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import writeFileAtomic from 'write-file-atomic';
+import type { Action } from '../src/features/behavior-model/domain/entities/Action';
+import type { Feature } from '../src/features/behavior-model/domain/entities/Feature';
+import type { Parameter } from '../src/features/behavior-model/domain/entities/Parameter';
+import type { StateDefinition } from '../src/features/behavior-model/domain/entities/StateDefinition';
+import type { Surface } from '../src/features/behavior-model/domain/entities/Surface';
+import { coerceDefaultValue } from '../src/features/behavior-model/domain/services/StateValueCoercion';
+import { discoverSnapshotDirectory } from '../src/features/behavior-model/infrastructure/persistence/snapshot-discovery';
+
+const SNAPSHOT_SUFFIX = '.feature.json';
+
+type FileReport = {
+  readonly file: string;
+  readonly stateDefsFixed: number;
+  readonly parametersFixed: number;
+};
+
+const migrateStateDefinition = (
+  def: StateDefinition
+): { readonly next: StateDefinition; readonly changed: boolean } => {
+  const result = coerceDefaultValue(def.defaultValue, def.type, def.enumValues);
+  return {
+    next: result.changed ? { ...def, defaultValue: result.value } : def,
+    changed: result.changed
+  };
+};
+
+const migrateParameter = (
+  p: Parameter
+): { readonly next: Parameter; readonly changed: boolean } => {
+  if (p.defaultValue === undefined) return { next: p, changed: false };
+  const result = coerceDefaultValue(p.defaultValue, p.type, p.enumValues);
+  return {
+    next: result.changed ? { ...p, defaultValue: result.value } : p,
+    changed: result.changed
+  };
+};
+
+const migrateCapability = (
+  cap: Action
+): { readonly next: Action; readonly fixed: number } => {
+  let fixed = 0;
+  const parameters = cap.parameters.map((p) => {
+    const r = migrateParameter(p);
+    if (r.changed) fixed += 1;
+    return r.next;
+  });
+  return {
+    next: fixed > 0 ? { ...cap, parameters } : cap,
+    fixed
+  };
+};
+
+const migrateSurface = (
+  surface: Surface
+): { readonly next: Surface; readonly stateDefsFixed: number; readonly parametersFixed: number } => {
+  let stateDefsFixed = 0;
+  const stateDefinitions = surface.stateDefinitions.map((d) => {
+    const r = migrateStateDefinition(d);
+    if (r.changed) stateDefsFixed += 1;
+    return r.next;
+  });
+  let parametersFixed = 0;
+  const actions = surface.actions.map((c) => {
+    const r = migrateCapability(c);
+    parametersFixed += r.fixed;
+    return r.next;
+  });
+  const changed = stateDefsFixed > 0 || parametersFixed > 0;
+  return {
+    next: changed ? { ...surface, stateDefinitions, actions } : surface,
+    stateDefsFixed,
+    parametersFixed
+  };
+};
+
+const migrateFeature = (
+  exp: Feature
+): { readonly next: Feature; readonly stateDefsFixed: number; readonly parametersFixed: number } => {
+  let stateDefsFixed = 0;
+  let parametersFixed = 0;
+  const surfaces = exp.surfaces.map((s) => {
+    const r = migrateSurface(s);
+    stateDefsFixed += r.stateDefsFixed;
+    parametersFixed += r.parametersFixed;
+    return r.next;
+  });
+  const changed = stateDefsFixed > 0 || parametersFixed > 0;
+  return {
+    next: changed ? { ...exp, surfaces } : exp,
+    stateDefsFixed,
+    parametersFixed
+  };
+};
+
+const migrateFile = async (path: string): Promise<FileReport> => {
+  const raw = readFileSync(path, 'utf8');
+  const parsed = JSON.parse(raw) as { readonly feature: Feature };
+  if (!parsed.feature) {
+    return { file: path, stateDefsFixed: 0, parametersFixed: 0 };
+  }
+  const result = migrateFeature(parsed.feature);
+  if (result.stateDefsFixed === 0 && result.parametersFixed === 0) {
+    return { file: path, stateDefsFixed: 0, parametersFixed: 0 };
+  }
+  const nextEnvelope = { ...parsed, feature: result.next };
+  await writeFileAtomic(path, JSON.stringify(nextEnvelope, null, 2), 'utf8');
+  return {
+    file: path,
+    stateDefsFixed: result.stateDefsFixed,
+    parametersFixed: result.parametersFixed
+  };
+};
+
+const main = async (): Promise<void> => {
+  const { directory } = discoverSnapshotDirectory({});
+  if (!existsSync(directory)) {
+    process.stderr.write(`[migrate-defaults] no snapshot directory at ${directory}\n`);
+    process.exit(1);
+  }
+  const files = readdirSync(directory).filter((f) => f.endsWith(SNAPSHOT_SUFFIX));
+  process.stderr.write(
+    `[migrate-defaults] scanning ${files.length} file(s) in ${directory}\n`
+  );
+
+  let totalStateDefs = 0;
+  let totalParams = 0;
+  let touched = 0;
+  for (const file of files) {
+    const report = await migrateFile(join(directory, file));
+    if (report.stateDefsFixed > 0 || report.parametersFixed > 0) {
+      touched += 1;
+      totalStateDefs += report.stateDefsFixed;
+      totalParams += report.parametersFixed;
+      process.stderr.write(
+        `  fixed ${file}: ${report.stateDefsFixed} state default(s), ${report.parametersFixed} parameter default(s)\n`
+      );
+    }
+  }
+  process.stderr.write(
+    `[migrate-defaults] done. ${touched}/${files.length} file(s) touched, ${totalStateDefs} state default(s) + ${totalParams} parameter default(s) coerced.\n`
+  );
+};
+
+main().catch((err) => {
+  process.stderr.write(`[migrate-defaults] fatal: ${(err as Error).message}\n`);
+  process.exit(1);
+});

package/mcp-server/repo-link.ts

@@ -1,134 +1,142 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, parse, resolve } from 'node:path';
-
-const LINK_FILENAME = '.unspa.json';
-
-export type IndexEntryStatus = 'implemented' | 'partial' | 'missing';
-
-export type IndexEntry = {
-  readonly status: IndexEntryStatus;
-  /** Relative path from the repo root (or the folder containing .unspa.json). */
-  readonly file: string;
-  readonly line: number;
-  /** The function/class/component signature. One meaningful line that identifies the implementation. */
-  readonly signature: string;
-  /** ISO timestamp of the last audit pass for this entry. */
-  readonly auditedAt?: string;
-  /** Git commit SHA of the implementation file when this entry was last audited. */
-  readonly gitCommit?: string;
-  /** Feature updatedAt (ISO) when this entry was last audited. Detects spec drift. */
-  readonly specVersion?: string;
-  /**
-   * Pattern hint so the LLM knows what to expect before reading the file.
-   * Known values: svelte-route | svelte-store | svelte-component | mcp-tool |
-   *               mcp-entrypoint | domain-service
-   */
-  readonly kind?: string;
-  /** Additional files involved in this entity's implementation. */
-  readonly relatedFiles?: readonly { readonly file: string; readonly line: number; readonly role: string }[];
-  /** Path to the test file covering this entity. Run with `vitest run <testFile>`. */
-  readonly testFile?: string;
-  /** Structured list of spec elements that are not yet implemented. */
-  readonly knownGaps?: readonly string[];
-  readonly notes?: string;
-};
-
-/**
- * Keyed by "<type>:<id-or-path>":
- *   action:<actionId>   surface:<surfaceId>    state:<dotted.path>
- *   rule:<ruleId>               invariant:<id>         event:<eventName>
- *   transition:<transitionId>
- */
-export type BehavioralIndex = Record<string, IndexEntry>;
-
-/**
- * Shape of `.unspa.json`. Kept in sync with the CLI's writer
- * (cli/util/link.ts). Mirrored here rather than imported to keep the MCP
- * server's deps independent of the CLI bundle.
- *
- * Bound to a **project**, not a feature: a repo is one codebase, which holds
- * one or more features. The LLM picks the right feature from the project's
- * member list based on context (file paths being edited, action being
- * implemented, the user prompt).
- */
-export type RepoLink = {
-  readonly projectId: string;
-  readonly projectName?: string;
-  readonly index?: BehavioralIndex;
-  /**
-   * When set, write tools that mutate the spec (apply_batch and generate_types
-   * itself) regenerate the TypeScript types module here on success. Path is
-   * resolved relative to the directory containing this `.unspa.json`.
-   * Populated automatically on the first generate_types call so subsequent
-   * spec edits don't drift away from the codegen output.
-   */
-  readonly generatedTypesPath?: string;
-};
-
-export type RepoLinkLookup = {
-  readonly link: RepoLink | null;
-  readonly path: string | null;
-  readonly cwd: string;
-};
-
-const readLinkFile = (candidate: string): RepoLink | null => {
-  try {
-    const raw = JSON.parse(readFileSync(candidate, 'utf8')) as RepoLink;
-    if (raw && typeof raw.projectId === 'string' && raw.projectId.length > 0) {
-      return raw;
-    }
-  } catch {
-    // Malformed file. Treat as if no link existed rather than crash.
-  }
-  return null;
-};
-
-/**
- * Walk up from `cwd` looking for the first `.unspa.json`. Returns the link
- * + the file path it was found at, or null link when no file exists in any
- * ancestor. Mirrors the discovery semantics of `discoverSnapshotDirectory`
- * so a repo is detected the same way regardless of which sub-dir the MCP
- * server was started from.
- *
- * When `explicitPath` is provided (via --link flag or UNSPA_LINK env var),
- * discovery is skipped and that file is used directly. The path may point
- * at a `.unspa.json` file or a directory containing one.
- */
-export const discoverRepoLink = (
-  cwd: string = process.cwd(),
-  explicitPath?: string
-): RepoLinkLookup => {
-  if (explicitPath) {
-    const resolved = resolve(cwd, explicitPath);
-    const candidate = resolved.endsWith(LINK_FILENAME) ? resolved : join(resolved, LINK_FILENAME);
-    if (!existsSync(candidate)) {
-      throw new Error(`No .unspa.json found at ${candidate}`);
-    }
-    const link = readLinkFile(candidate);
-    if (!link) throw new Error(`Malformed .unspa.json at ${candidate}`);
-    return { link, path: candidate, cwd };
-  }
-
-  let current = resolve(cwd);
-  const { root } = parse(current);
-  while (true) {
-    const candidate = join(current, LINK_FILENAME);
-    if (existsSync(candidate)) {
-      const link = readLinkFile(candidate);
-      if (link) return { link, path: candidate, cwd };
-    }
-    if (current === root) break;
-    const parent = resolve(current, '..');
-    if (parent === current) break;
-    current = parent;
-  }
-  return { link: null, path: null, cwd };
-};
-
-/**
- * Write an updated RepoLink back to the given path, preserving field order
- * and pretty-printing so the file remains human-readable.
- */
-export const writeRepoLink = (filePath: string, link: RepoLink): void => {
-  writeFileSync(filePath, JSON.stringify(link, null, 2) + '\n', 'utf8');
-};
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, parse, resolve } from 'node:path';
+
+const LINK_FILENAME = '.unspa.json';
+
+export type IndexEntryStatus = 'implemented' | 'partial' | 'missing';
+
+export type IndexEntry = {
+  readonly status: IndexEntryStatus;
+  /** Relative path from the repo root (or the folder containing .unspa.json). */
+  readonly file: string;
+  readonly line: number;
+  /** The function/class/component signature. One meaningful line that identifies the implementation. */
+  readonly signature: string;
+  /** ISO timestamp of the last audit pass for this entry. */
+  readonly auditedAt?: string;
+  /** Git commit SHA of the implementation file when this entry was last audited. */
+  readonly gitCommit?: string;
+  /** Feature updatedAt (ISO) when this entry was last audited. Detects spec drift. */
+  readonly specVersion?: string;
+  /**
+   * ISO timestamp of the last time this entity's scenarios PASSED against the
+   * real implementation (stamped by `unspa coverage ingest` from a vitest run).
+   * Distinguishes "claimed implemented" from "proven against the spec".
+   */
+  readonly verifiedAt?: string;
+  /** Number of scenarios that passed at the last verification. */
+  readonly verifiedScenarios?: number;
+  /**
+   * Pattern hint so the LLM knows what to expect before reading the file.
+   * Known values: svelte-route | svelte-store | svelte-component | mcp-tool |
+   *               mcp-entrypoint | domain-service
+   */
+  readonly kind?: string;
+  /** Additional files involved in this entity's implementation. */
+  readonly relatedFiles?: readonly { readonly file: string; readonly line: number; readonly role: string }[];
+  /** Path to the test file covering this entity. Run with `vitest run <testFile>`. */
+  readonly testFile?: string;
+  /** Structured list of spec elements that are not yet implemented. */
+  readonly knownGaps?: readonly string[];
+  readonly notes?: string;
+};
+
+/**
+ * Keyed by "<type>:<id-or-path>":
+ *   action:<actionId>   surface:<surfaceId>    state:<dotted.path>
+ *   rule:<ruleId>               invariant:<id>         event:<eventName>
+ *   transition:<transitionId>
+ */
+export type BehavioralIndex = Record<string, IndexEntry>;
+
+/**
+ * Shape of `.unspa.json`. Kept in sync with the CLI's writer
+ * (cli/util/link.ts). Mirrored here rather than imported to keep the MCP
+ * server's deps independent of the CLI bundle.
+ *
+ * Bound to a **project**, not a feature: a repo is one codebase, which holds
+ * one or more features. The LLM picks the right feature from the project's
+ * member list based on context (file paths being edited, action being
+ * implemented, the user prompt).
+ */
+export type RepoLink = {
+  readonly projectId: string;
+  readonly projectName?: string;
+  readonly index?: BehavioralIndex;
+  /**
+   * When set, write tools that mutate the spec (apply_batch and generate_types
+   * itself) regenerate the TypeScript types module here on success. Path is
+   * resolved relative to the directory containing this `.unspa.json`.
+   * Populated automatically on the first generate_types call so subsequent
+   * spec edits don't drift away from the codegen output.
+   */
+  readonly generatedTypesPath?: string;
+};
+
+export type RepoLinkLookup = {
+  readonly link: RepoLink | null;
+  readonly path: string | null;
+  readonly cwd: string;
+};
+
+const readLinkFile = (candidate: string): RepoLink | null => {
+  try {
+    const raw = JSON.parse(readFileSync(candidate, 'utf8')) as RepoLink;
+    if (raw && typeof raw.projectId === 'string' && raw.projectId.length > 0) {
+      return raw;
+    }
+  } catch {
+    // Malformed file. Treat as if no link existed rather than crash.
+  }
+  return null;
+};
+
+/**
+ * Walk up from `cwd` looking for the first `.unspa.json`. Returns the link
+ * + the file path it was found at, or null link when no file exists in any
+ * ancestor. Mirrors the discovery semantics of `discoverSnapshotDirectory`
+ * so a repo is detected the same way regardless of which sub-dir the MCP
+ * server was started from.
+ *
+ * When `explicitPath` is provided (via --link flag or UNSPA_LINK env var),
+ * discovery is skipped and that file is used directly. The path may point
+ * at a `.unspa.json` file or a directory containing one.
+ */
+export const discoverRepoLink = (
+  cwd: string = process.cwd(),
+  explicitPath?: string
+): RepoLinkLookup => {
+  if (explicitPath) {
+    const resolved = resolve(cwd, explicitPath);
+    const candidate = resolved.endsWith(LINK_FILENAME) ? resolved : join(resolved, LINK_FILENAME);
+    if (!existsSync(candidate)) {
+      throw new Error(`No .unspa.json found at ${candidate}`);
+    }
+    const link = readLinkFile(candidate);
+    if (!link) throw new Error(`Malformed .unspa.json at ${candidate}`);
+    return { link, path: candidate, cwd };
+  }
+
+  let current = resolve(cwd);
+  const { root } = parse(current);
+  while (true) {
+    const candidate = join(current, LINK_FILENAME);
+    if (existsSync(candidate)) {
+      const link = readLinkFile(candidate);
+      if (link) return { link, path: candidate, cwd };
+    }
+    if (current === root) break;
+    const parent = resolve(current, '..');
+    if (parent === current) break;
+    current = parent;
+  }
+  return { link: null, path: null, cwd };
+};
+
+/**
+ * Write an updated RepoLink back to the given path, preserving field order
+ * and pretty-printing so the file remains human-readable.
+ */
+export const writeRepoLink = (filePath: string, link: RepoLink): void => {
+  writeFileSync(filePath, JSON.stringify(link, null, 2) + '\n', 'utf8');
+};