unspaghettit 0.2.0 → 0.4.0

package/mcp-server/tools/surface.ts

@@ -1,106 +1,106 @@
-import { z } from 'zod';
-import {
-  addSurface,
-  removeSurface,
-  renameSurface,
-  setSurfaceParent
-} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
-import type { Surface, SurfaceType } from '../../src/features/behavior-model/domain/entities/Surface';
-import { ALL_SURFACE_TYPES } from '../../src/features/behavior-model/domain/entities/Surface';
-import {
-  asFeatureId,
-  asSurfaceId
-} from '../../src/features/behavior-model/domain/value-objects/ids';
-import { runMutation, type ToolDeps } from './_shared';
-
-export const registerSurfaceTools = (deps: ToolDeps): void => {
-  const { server, ids } = deps;
-
-  server.registerTool(
-    'add_surface',
-    {
-      description: 'Append empty Surface. Types: screen, canvas, terminal, board, workflow, command_palette, api_playground, map, dialog_area, custom.',
-      inputSchema: {
-        featureId: z.string(),
-        name: z.string().min(1),
-        type: z.enum(ALL_SURFACE_TYPES as unknown as [SurfaceType, ...SurfaceType[]]),
+import { z } from 'zod';
+import {
+  addSurface,
+  removeSurface,
+  renameSurface,
+  setSurfaceParent
+} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
+import type { Surface, SurfaceType } from '../../src/features/behavior-model/domain/entities/Surface';
+import { ALL_SURFACE_TYPES } from '../../src/features/behavior-model/domain/entities/Surface';
+import {
+  asFeatureId,
+  asSurfaceId
+} from '../../src/features/behavior-model/domain/value-objects/ids';
+import { runMutation, type ToolDeps } from './_shared';
+
+export const registerSurfaceTools = (deps: ToolDeps): void => {
+  const { server, ids } = deps;
+
+  server.registerTool(
+    'add_surface',
+    {
+      description: 'Append empty Surface. Types: screen, canvas, terminal, board, workflow, command_palette, api_playground, map, dialog_area, custom.',
+      inputSchema: {
+        featureId: z.string(),
+        name: z.string().min(1),
+        type: z.enum(ALL_SURFACE_TYPES as unknown as [SurfaceType, ...SurfaceType[]]),
         description: z.string().min(1),
-        parentSurfaceId: z.string().optional()
-      }
-    },
-    async ({ featureId, name, type, description, parentSurfaceId }) => {
-      const surface: Surface = {
-        id: asSurfaceId(ids()),
-        name,
-        type,
-        description,
-        stateDefinitions: [],
-        actions: [],
-        rules: [],
-        invariants: [],
-        transitions: [],
-        ...(parentSurfaceId ? { parentSurfaceId: asSurfaceId(parentSurfaceId) } : {})
-      };
-      return runMutation(
-        deps,
-        {
-          featureId: asFeatureId(featureId),
-          transform: (exp) => addSurface(exp, surface)
-        },
-        { createdId: surface.id }
-      );
-    }
-  );
-
-  server.registerTool(
-    'update_surface',
-    {
+        parentSurfaceId: z.string().optional()
+      }
+    },
+    async ({ featureId, name, type, description, parentSurfaceId }) => {
+      const surface: Surface = {
+        id: asSurfaceId(ids()),
+        name,
+        type,
+        description,
+        stateDefinitions: [],
+        actions: [],
+        rules: [],
+        invariants: [],
+        transitions: [],
+        ...(parentSurfaceId ? { parentSurfaceId: asSurfaceId(parentSurfaceId) } : {})
+      };
+      return runMutation(
+        deps,
+        {
+          featureId: asFeatureId(featureId),
+          transform: (exp) => addSurface(exp, surface)
+        },
+        { createdId: surface.id }
+      );
+    }
+  );
+
+  server.registerTool(
+    'update_surface',
+    {
       description: 'Patch name/type/description/parent. Description cannot be cleared; null parentSurfaceId unparents.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        name: z.string().min(1).optional(),
-        type: z.enum(ALL_SURFACE_TYPES as unknown as [SurfaceType, ...SurfaceType[]]).optional(),
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        name: z.string().min(1).optional(),
+        type: z.enum(ALL_SURFACE_TYPES as unknown as [SurfaceType, ...SurfaceType[]]).optional(),
         description: z.string().min(1).optional(),
-        parentSurfaceId: z.string().nullable().optional()
-      }
-    },
-    async ({ featureId, surfaceId, name, type, description, parentSurfaceId }) => {
-      const sId = asSurfaceId(surfaceId);
-      const eId = asFeatureId(featureId);
-      // Two transforms composed: meta patch via renameSurface, then parent via
-      // setSurfaceParent if explicitly passed (null clears).
-      return runMutation(deps, {
-        featureId: eId,
-        transform: (exp) => {
-          let next = renameSurface(exp, sId, {
-            ...(name !== undefined ? { name } : {}),
-            ...(type !== undefined ? { type } : {}),
+        parentSurfaceId: z.string().nullable().optional()
+      }
+    },
+    async ({ featureId, surfaceId, name, type, description, parentSurfaceId }) => {
+      const sId = asSurfaceId(surfaceId);
+      const eId = asFeatureId(featureId);
+      // Two transforms composed: meta patch via renameSurface, then parent via
+      // setSurfaceParent if explicitly passed (null clears).
+      return runMutation(deps, {
+        featureId: eId,
+        transform: (exp) => {
+          let next = renameSurface(exp, sId, {
+            ...(name !== undefined ? { name } : {}),
+            ...(type !== undefined ? { type } : {}),
             ...(description !== undefined ? { description } : {})
-          });
-          if (parentSurfaceId !== undefined) {
-            next = setSurfaceParent(
-              next,
-              sId,
-              parentSurfaceId === null ? null : asSurfaceId(parentSurfaceId)
-            );
-          }
-          return next;
-        }
-      });
-    }
-  );
-
-  server.registerTool(
-    'remove_surface',
-    {
-      description: 'Delete Surface + all it contains. Transitions targeting it must be cleaned up first.',
-      inputSchema: { featureId: z.string(), surfaceId: z.string() }
-    },
-    async ({ featureId, surfaceId }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) => removeSurface(exp, asSurfaceId(surfaceId))
-      })
-  );
-};
+          });
+          if (parentSurfaceId !== undefined) {
+            next = setSurfaceParent(
+              next,
+              sId,
+              parentSurfaceId === null ? null : asSurfaceId(parentSurfaceId)
+            );
+          }
+          return next;
+        }
+      });
+    }
+  );
+
+  server.registerTool(
+    'remove_surface',
+    {
+      description: 'Delete Surface + all it contains. Transitions targeting it must be cleaned up first.',
+      inputSchema: { featureId: z.string(), surfaceId: z.string() }
+    },
+    async ({ featureId, surfaceId }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) => removeSurface(exp, asSurfaceId(surfaceId))
+      })
+  );
+};

package/mcp-server/tools/transition.ts

@@ -1,99 +1,99 @@
-import { z } from 'zod';
-import {
-  addTransitionToSurface,
-  removeTransitionFromSurface,
-  updateTransitionOnSurface
-} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
-import type { Transition } from '../../src/features/behavior-model/domain/entities/Transition';
-import {
-  asFeatureId,
-  asSurfaceId,
-  asTransitionId
-} from '../../src/features/behavior-model/domain/value-objects/ids';
-import { runMutation, type ToolDeps } from './_shared';
-
-export const registerTransitionTools = (deps: ToolDeps): void => {
-  const { server, ids } = deps;
-
-  server.registerTool(
-    'add_transition',
-    {
-      description: 'Add Transition from one Surface (surfaceId=source) to another (target). Target must exist.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        target: z.string(),
-        label: z.string().optional(),
+import { z } from 'zod';
+import {
+  addTransitionToSurface,
+  removeTransitionFromSurface,
+  updateTransitionOnSurface
+} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
+import type { Transition } from '../../src/features/behavior-model/domain/entities/Transition';
+import {
+  asFeatureId,
+  asSurfaceId,
+  asTransitionId
+} from '../../src/features/behavior-model/domain/value-objects/ids';
+import { runMutation, type ToolDeps } from './_shared';
+
+export const registerTransitionTools = (deps: ToolDeps): void => {
+  const { server, ids } = deps;
+
+  server.registerTool(
+    'add_transition',
+    {
+      description: 'Add Transition from one Surface (surfaceId=source) to another (target). Target must exist.',
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        target: z.string(),
+        label: z.string().optional(),
         description: z.string().min(1)
-      }
-    },
-    async ({ featureId, surfaceId, target, label, description }) => {
-      const transition: Transition = {
-        id: asTransitionId(ids()),
-        target: asSurfaceId(target),
-        ...(label ? { label } : {}),
+      }
+    },
+    async ({ featureId, surfaceId, target, label, description }) => {
+      const transition: Transition = {
+        id: asTransitionId(ids()),
+        target: asSurfaceId(target),
+        ...(label ? { label } : {}),
         description
-      };
-      return runMutation(
-        deps,
-        {
-          featureId: asFeatureId(featureId),
-          transform: (exp) => addTransitionToSurface(exp, asSurfaceId(surfaceId), transition)
-        },
-        { createdId: transition.id }
-      );
-    }
-  );
-
-  server.registerTool(
-    'update_transition',
-    {
-      description: 'Patch target/label/description. Id fixed.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        transitionId: z.string(),
-        target: z.string().optional(),
-        label: z.string().optional(),
+      };
+      return runMutation(
+        deps,
+        {
+          featureId: asFeatureId(featureId),
+          transform: (exp) => addTransitionToSurface(exp, asSurfaceId(surfaceId), transition)
+        },
+        { createdId: transition.id }
+      );
+    }
+  );
+
+  server.registerTool(
+    'update_transition',
+    {
+      description: 'Patch target/label/description. Id fixed.',
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        transitionId: z.string(),
+        target: z.string().optional(),
+        label: z.string().optional(),
         description: z.string().min(1).optional()
-      }
-    },
-    async ({ featureId, surfaceId, transitionId, target, label, description }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) =>
-          updateTransitionOnSurface(
-            exp,
-            asSurfaceId(surfaceId),
-            asTransitionId(transitionId),
-            {
-              ...(target !== undefined ? { target: asSurfaceId(target) } : {}),
-              ...(label !== undefined ? { label } : {}),
-              ...(description !== undefined ? { description } : {})
-            }
-          )
-      })
-  );
-
-  server.registerTool(
-    'remove_transition',
-    {
-      description: 'Delete Transition.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        transitionId: z.string()
-      }
-    },
-    async ({ featureId, surfaceId, transitionId }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) =>
-          removeTransitionFromSurface(
-            exp,
-            asSurfaceId(surfaceId),
-            asTransitionId(transitionId)
-          )
-      })
-  );
-};
+      }
+    },
+    async ({ featureId, surfaceId, transitionId, target, label, description }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) =>
+          updateTransitionOnSurface(
+            exp,
+            asSurfaceId(surfaceId),
+            asTransitionId(transitionId),
+            {
+              ...(target !== undefined ? { target: asSurfaceId(target) } : {}),
+              ...(label !== undefined ? { label } : {}),
+              ...(description !== undefined ? { description } : {})
+            }
+          )
+      })
+  );
+
+  server.registerTool(
+    'remove_transition',
+    {
+      description: 'Delete Transition.',
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        transitionId: z.string()
+      }
+    },
+    async ({ featureId, surfaceId, transitionId }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) =>
+          removeTransitionFromSurface(
+            exp,
+            asSurfaceId(surfaceId),
+            asTransitionId(transitionId)
+          )
+      })
+  );
+};

package/mcp-server/tools/verification.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import type { Feature } from '../../src/features/behavior-model/domain/entities/Feature';
+import type { Invariant } from '../../src/features/behavior-model/domain/entities/Invariant';
+import { asFeatureId } from '../../src/features/behavior-model/domain/value-objects/ids';
+import { asProjectId } from '../../src/features/projects/domain/value-objects/ids';
+import { detectDrift } from '../../src/features/verification/domain/detectDrift';
+import { verifyFeaturesUseCase } from '../../src/features/verification/application/use-cases/VerifyFeatures';
+import { fileBehavioralIndexReader } from '../../src/features/verification/infrastructure/persistence/FileBehavioralIndexReader';
+import { staticBehavioralIndexReader } from '../../src/features/verification/infrastructure/persistence/StaticBehavioralIndexReader';
+import type { BehavioralIndexReader } from '../../src/features/verification/application/ports/BehavioralIndexReader';
+import { trackTokens } from '../metrics';
+import { errorText, text, type ToolDeps } from './_shared';
+import { expandFeatureId } from './short-ids';
+
+/**
+ * Read the index from the same `.unspa.json` the CLI bound this repo to. When
+ * the repo isn't linked, there is no index, and an empty reader keeps drift /
+ * verify working (they just report no implementations to check).
+ */
+const indexReader = (repoContext: ToolDeps['repoContext']): BehavioralIndexReader =>
+  repoContext?.linkPath
+    ? fileBehavioralIndexReader({ path: repoContext.linkPath })
+    : staticBehavioralIndexReader([]);
+
+/**
+ * The cohort to verify plus the owning project's cross-feature invariants: one
+ * feature when named, otherwise the linked project's features (so cross-feature
+ * cascades + project invariants resolve), otherwise everything. Mirrors the
+ * CLI's `unspa check` scoping so chat and CI verify the same thing.
+ */
+const resolveCohort = async (
+  deps: ToolDeps,
+  featureId?: string
+): Promise<{ features: Feature[]; projectInvariants: readonly Invariant[] }> => {
+  const { repo, projectRepo, repoContext } = deps;
+
+  if (featureId) {
+    const id = await expandFeatureId(repo, featureId);
+    const feature = await repo.get(asFeatureId(id));
+    let projectInvariants: readonly Invariant[] = [];
+    if (feature) {
+      for (const summary of await projectRepo.list()) {
+        const project = await projectRepo.get(summary.id);
+        if (project?.featureIds.some((f) => String(f) === String(feature.id))) {
+          projectInvariants = project.projectInvariants ?? [];
+          break;
+        }
+      }
+    }
+    return { features: feature ? [feature] : [], projectInvariants };
+  }
+
+  const projectId = repoContext?.link?.projectId;
+  const project = projectId ? await projectRepo.get(asProjectId(projectId)) : null;
+  const ids = project?.featureIds ?? null;
+
+  const summaries = ids ?? (await repo.list()).map((s) => s.id);
+  const out: Feature[] = [];
+  for (const id of summaries) {
+    const feature = await repo.get(id);
+    if (feature) out.push(feature);
+  }
+  return { features: out, projectInvariants: project?.projectInvariants ?? [] };
+};
+
+export const registerVerificationTools = (deps: ToolDeps): void => {
+  const { server, repo, repoContext } = deps;
+
+  server.registerTool(
+    'get_drift',
+    {
+      description:
+        'Spec→code drift: which implementations were audited against an OLDER version of the spec than the one now on disk, so the code may no longer match. Compares each `.unspa.json` entry\'s recorded specVersion against the owning feature\'s current updatedAt. Returns `stale` (re-audit these — the spec changed under them), `unversioned` (audited but never stamped, so drift can\'t be judged), and `orphans` (index keys that no longer resolve to any spec entity — renamed/removed). Scopes to a feature when given, else the linked project, else all. Run after editing a spec whose code you previously mapped, and in CI to block on silent drift.',
+      inputSchema: { featureId: z.string().optional() }
+    },
+    async ({ featureId }) => {
+      try {
+        const { features } = await resolveCohort(deps, featureId);
+        const entries = await indexReader(repoContext).read();
+        return text(trackTokens('get_drift', detectDrift(features, entries)));
+      } catch (e) {
+        return errorText(`get_drift failed: ${(e as Error).message}`);
+      }
+    }
+  );
+
+  server.registerTool(
+    'verify',
+    {
+      description:
+        'Run the whole verification spine and return a gated verdict — the in-chat form of `unspa check`. Per feature: runs every scenario as an executable spec test, scores maturity, analyses surface (navigation) reachability, optionally model-checks the reachable state space, and folds in spec→code drift. Each check is pass / warn / fail; `passed` is true when nothing failed (warnings are advisory — bounded-search caveats, drift, ungated maturity). Defaults fail only on the unambiguous things (a failing scenario, a reachable invariant violation). Use after a build/edit pass to confirm the spec is sound before claiming done.',
+      inputSchema: {
+        featureId: z.string().optional(),
+        modelCheck: z.boolean().optional(),
+        maxDepth: z.number().int().positive().optional(),
+        maxStates: z.number().int().positive().optional(),
+        minMaturity: z.number().int().min(0).max(100).optional(),
+        minVerified: z.number().int().min(0).max(100).optional(),
+        requireScenarios: z.boolean().optional(),
+        failOnDrift: z.boolean().optional(),
+        failOnUnmetGoals: z.boolean().optional()
+      }
+    },
+    async (args) => {
+      try {
+        const { features, projectInvariants } = await resolveCohort(deps, args.featureId);
+        const verify = verifyFeaturesUseCase({ features: repo, index: indexReader(repoContext) });
+        const report = await verify({
+          featureIds: features.map((f) => f.id),
+          projectInvariants,
+          thresholds: {
+            minMaturity: args.minMaturity ?? 0,
+            minVerified: args.minVerified ?? 0,
+            requireScenarios: args.requireScenarios === true,
+            allowDrift: args.failOnDrift !== true,
+            failOnUnmetGoals: args.failOnUnmetGoals === true
+          },
+          modelCheck: args.modelCheck
+            ? {
+                ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
+                ...(args.maxStates !== undefined ? { maxStates: args.maxStates } : {})
+              }
+            : false
+        });
+        return text(trackTokens('verify', report));
+      } catch (e) {
+        return errorText(`verify failed: ${(e as Error).message}`);
+      }
+    }
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unspaghettit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Executable specifications for AI-assisted software development. Local-first and MCP-native.",
   "author": {
@@ -39,6 +39,10 @@
     "preview": "vite preview",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
@@ -50,7 +54,7 @@
     "skills:check": "node scripts/sync-skills.cjs --check",
     "bom:strip": "node scripts/strip-bom.cjs",
     "bom:check": "node scripts/strip-bom.cjs --check",
-    "prepublishOnly": "npm run skills:check && npm run bom:check && npm run build && npm test"
+    "prepublishOnly": "npm run skills:check && npm run bom:check && npm run lint && npm run build && npm test"
   },
   "bin": {
     "unspa": "./cli/unspa.cjs",
@@ -82,6 +86,7 @@
     "cookie": ">=0.7.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.17.0",
     "@playwright/test": "^1.60.0",
     "@sveltejs/adapter-node": "^5.5.4",
     "@sveltejs/kit": "^2.60.1",
@@ -91,11 +96,18 @@
     "@types/prompts": "^2.4.9",
     "@types/write-file-atomic": "^4.0.3",
     "@types/ws": "^8.18.1",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-svelte": "^2.46.1",
+    "globals": "^15.14.0",
+    "prettier": "^3.4.2",
+    "prettier-plugin-svelte": "^3.3.2",
     "svelte": "^5.1.9",
     "svelte-check": "^4.0.5",
     "tailwindcss": "^4.0.0",
     "tslib": "^2.8.0",
     "typescript": "^5.6.3",
+    "typescript-eslint": "^8.19.1",
     "vite": "^8.0.13",
     "vitest": "^4.1.7"
   },
@@ -107,6 +119,7 @@
     "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
     "tsx": "^4.21.0",
+    "vis-network": "^10.1.0",
     "write-file-atomic": "^7.0.1",
     "ws": "^8.20.1",
     "y-protocols": "^1.0.7",