@seamapp/core 0.1.0

package/migrations/001_seam_init.sql

@@ -0,0 +1,31 @@
+-- Seam v1 schema
+-- Run in Supabase SQL editor or via `npx seam migrate`
+
+create table if not exists seam_snapshots (
+  id             uuid primary key default gen_random_uuid(),
+  session_token  text not null unique,
+  project_id     text not null,
+  created_at     timestamptz default now(),
+  files          jsonb not null,
+  change_request text,
+  risk_tier      text check (risk_tier in ('A', 'B', 'C')),
+  status         text check (status in ('before', 'after', 'rolled_back')),
+  parent_token   text
+);
+
+create index if not exists seam_snapshots_project_idx on seam_snapshots (project_id, created_at desc);
+create index if not exists seam_snapshots_token_idx   on seam_snapshots (session_token);
+
+create table if not exists seam_changes (
+  id             uuid primary key default gen_random_uuid(),
+  project_id     text not null,
+  created_at     timestamptz default now(),
+  request        text not null,
+  risk_tier      text,
+  files_changed  text[],
+  before_token   text references seam_snapshots(session_token),
+  after_token    text references seam_snapshots(session_token),
+  status         text check (status in ('completed', 'rolled_back', 'failed'))
+);
+
+create index if not exists seam_changes_project_idx on seam_changes (project_id, created_at desc);

package/migrations/002_seam_tickets.sql

@@ -0,0 +1,15 @@
+-- Seam v1 — visitor ticket table
+-- Visitors submit feedback/bugs via SeamTicketWidget (production mode)
+-- Dashboard reads from this table under the Tickets tab
+
+create table if not exists seam_tickets (
+  id          uuid primary key default gen_random_uuid(),
+  project_id  text not null,
+  created_at  timestamptz default now(),
+  description text not null,
+  page_url    text,
+  status      text check (status in ('open', 'in_progress', 'resolved')) default 'open'
+);
+
+create index if not exists seam_tickets_project_idx on seam_tickets (project_id, created_at desc);
+create index if not exists seam_tickets_status_idx  on seam_tickets (status, created_at desc);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@seamapp/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/server.js",
+  "files": [
+    "src/",
+    "migrations/"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@seamapp/graphify-bridge": "*",
+    "@supabase/supabase-js": "^2.43.0",
+    "cors": "^2.8.5",
+    "diff": "^5.2.0",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "fs-extra": "^11.2.0",
+    "multer": "^1.4.5-lts.1",
+    "ws": "^8.17.1"
+  }
+}

package/src/attachmentProcessor.js

@@ -0,0 +1,133 @@
+/**
+ * Seam Attachment Processor
+ * Categorizes uploaded files and prepares them for the change pipeline
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+
+const IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml'];
+const VIDEO_TYPES = ['video/mp4', 'video/mov', 'video/quicktime', 'video/webm'];
+const DOCUMENT_TYPES = ['application/pdf', 'text/plain', 'text/markdown'];
+const CODE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.css', '.scss', '.json', '.md', '.html', '.py', '.sh'];
+
+export async function processAttachments(rawFiles, config) {
+  const processed = [];
+
+  for (const file of rawFiles) {
+    const ext = path.extname(file.originalname).toLowerCase();
+    const mime = file.mimetype;
+
+    if (IMAGE_TYPES.includes(mime)) {
+      // Images = vision context by default (reference screenshots, mockups, logos)
+      // UI allows user to override to 'asset_drop' before submitting
+      const base64 = await fs.readFile(file.path, 'base64');
+      processed.push({
+        role: 'vision',
+        filename: file.originalname,
+        mediaType: mime,
+        base64,
+        size: file.size,
+        tempPath: file.path
+      });
+
+    } else if (VIDEO_TYPES.includes(mime)) {
+      // Videos = always asset drops (too large for Claude context)
+      processed.push({
+        role: 'asset',
+        filename: file.originalname,
+        mediaType: mime,
+        tempPath: file.path,
+        size: file.size,
+        suggestedPath: `/public/videos/${file.originalname}`
+      });
+
+    } else if (DOCUMENT_TYPES.includes(mime)) {
+      // Documents = text extracted and added as Claude context
+      let textContent = '';
+      if (mime === 'text/plain' || mime === 'text/markdown') {
+        textContent = await fs.readFile(file.path, 'utf8');
+      } else if (mime === 'application/pdf') {
+        // PDF text extraction placeholder — implement with pdf-parse in full build
+        textContent = '[PDF content — extract with pdf-parse in full build]';
+      }
+      processed.push({
+        role: 'context',
+        filename: file.originalname,
+        textContent,
+        size: file.size,
+        tempPath: file.path
+      });
+
+    } else if (CODE_EXTENSIONS.includes(ext)) {
+      // Code/config files = code drop — placed directly in the project
+      const textContent = await fs.readFile(file.path, 'utf8');
+      processed.push({
+        role: 'code_drop',
+        filename: file.originalname,
+        textContent,
+        size: file.size,
+        tempPath: file.path,
+        suggestedPath: inferCodeDropPath(file.originalname, config)
+      });
+
+    } else {
+      // Unknown type — treat as generic asset
+      processed.push({
+        role: 'asset',
+        filename: file.originalname,
+        mediaType: mime,
+        tempPath: file.path,
+        size: file.size,
+        suggestedPath: `/public/${file.originalname}`
+      });
+    }
+  }
+
+  return processed;
+}
+
+/**
+ * Suggests a destination path for code drop files based on extension
+ */
+function inferCodeDropPath(filename, config) {
+  const ext = path.extname(filename).toLowerCase();
+  const root = config.projectRoot || './';
+
+  const pathMap = {
+    '.tsx': `${root}src/components/${filename}`,
+    '.ts': `${root}src/lib/${filename}`,
+    '.jsx': `${root}src/components/${filename}`,
+    '.js': `${root}src/lib/${filename}`,
+    '.css': `${root}src/styles/${filename}`,
+    '.scss': `${root}src/styles/${filename}`,
+    '.json': `${root}${filename}`,
+    '.md': `${root}docs/${filename}`,
+    '.py': `${root}scripts/${filename}`,
+    '.sh': `${root}scripts/${filename}`,
+    '.html': `${root}public/${filename}`
+  };
+
+  return pathMap[ext] || `${root}${filename}`;
+}
+
+/**
+ * Prepares asset drop confirmation payload for the UI
+ * UI shows this to the user before writing
+ */
+export function buildAssetDropConfirmation(attachment) {
+  return {
+    filename: attachment.filename,
+    size: formatBytes(attachment.size),
+    suggestedPath: attachment.suggestedPath,
+    role: attachment.role,
+    requiresConfirmation: true,
+    message: `This file will be written to ${attachment.suggestedPath}. Confirm placement?`
+  };
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return bytes + ' B';
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}

package/src/fileWriter.js

@@ -0,0 +1,121 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { createPatch } from 'diff';
+
+const FORBIDDEN_PATTERNS = [
+  /^node_modules(\/|\\|$)/,
+  /^\.git(\/|\\|$)/,
+  /^\.env/,
+  /^seam\.config\.json$/,
+  /(\/|\\)(node_modules|\.git)(\/|\\|$)/
+];
+
+export function validateWritePath(filepath, projectRoot) {
+  // Normalize to absolute
+  const abs = path.resolve(projectRoot, filepath);
+  const root = path.resolve(projectRoot);
+
+  // Ensure the resolved path stays inside the project root
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (!abs.startsWith(rootWithSep) && abs !== root) {
+    throw new Error(`Path "${filepath}" is outside project root — write forbidden`);
+  }
+
+  // Check against forbidden patterns using forward-slash normalized relative path
+  const rel = path.relative(root, abs).replace(/\\/g, '/');
+  if (FORBIDDEN_PATTERNS.some(p => p.test(rel))) {
+    throw new Error(`Path "${filepath}" matches a forbidden pattern — write forbidden`);
+  }
+}
+
+export function applyPatchToContent(originalContent, originalSnippet, replacementSnippet) {
+  if (!originalContent.includes(originalSnippet)) {
+    const preview = originalSnippet.length > 60 ? originalSnippet.slice(0, 60) + '...' : originalSnippet;
+    throw new Error(`Original snippet not found in file: "${preview}"`);
+  }
+  const updated = originalContent.replace(originalSnippet, replacementSnippet);
+  if (updated.includes(originalSnippet)) {
+    const preview = originalSnippet.length > 60 ? originalSnippet.slice(0, 60) + '...' : originalSnippet;
+    throw new Error(`Original snippet appears more than once — cannot apply change unambiguously: "${preview}"`);
+  }
+  return updated;
+}
+
+export function buildDiff(filepath, before, after) {
+  return createPatch(filepath, before, after, 'before', 'after');
+}
+
+/**
+ * Apply a change plan to disk.
+ * For 'restore' type (rollback), replacementSnippet is the full file content.
+ * Returns the list of written file paths.
+ * Throws on any write failure — caller must rollback already-written files.
+ */
+export async function applyChangePlan(changePlan, config, opts = {}) {
+  const projectRoot = path.resolve(process.cwd(), config.projectRoot || '.');
+  const writtenFiles = [];
+
+  for (const change of changePlan.changes) {
+    validateWritePath(change.filepath, projectRoot);
+    const absPath = path.resolve(projectRoot, change.filepath);
+
+    if (change.type === 'create' || change.type === 'restore') {
+      await fs.outputFile(absPath, change.replacementSnippet, 'utf8');
+
+    } else if (change.type === 'modify') {
+      const existing = await fs.readFile(absPath, 'utf8');
+      const updated = applyPatchToContent(existing, change.originalSnippet, change.replacementSnippet);
+      await fs.writeFile(absPath, updated, 'utf8');
+
+    } else if (change.type === 'asset_place') {
+      validateWritePath(change.destinationPath, projectRoot);
+      await fs.outputFile(path.resolve(projectRoot, change.destinationPath), change.replacementSnippet);
+    }
+
+    writtenFiles.push(change.type === 'asset_place' ? change.destinationPath : change.filepath);
+  }
+
+  return writtenFiles;
+}
+
+/**
+ * Build a dry-run preview: diff for each modified file.
+ * Does NOT write anything. Returns array of { filepath, diff } objects.
+ */
+export async function buildDryRunPreview(changePlan, config) {
+  const projectRoot = path.resolve(process.cwd(), config.projectRoot || '.');
+  const previews = [];
+
+  for (const change of changePlan.changes) {
+    if (change.type === 'modify') {
+      const absPath = path.resolve(projectRoot, change.filepath);
+      const existing = await fs.readFile(absPath, 'utf8').catch(() => null);
+      if (existing === null) {
+        previews.push({ filepath: change.filepath, diff: `[file not found — will be created or skipped]` });
+        continue;
+      }
+      const updated = applyPatchToContent(existing, change.originalSnippet, change.replacementSnippet);
+      previews.push({ filepath: change.filepath, diff: buildDiff(change.filepath, existing, updated) });
+    } else {
+      previews.push({ filepath: change.filepath, diff: `[${change.type}] ${change.destinationPath || change.filepath}` });
+    }
+  }
+
+  return previews;
+}
+
+/**
+ * Read only the files referenced by graph nodes — returns { filepath: content }.
+ * Hard-capped at 10 files per COST_AND_SAFETY.md rules.
+ */
+export async function readRelevantFiles(graphNodes, projectRoot) {
+  const files = {};
+  const nodes = graphNodes.slice(0, 10);
+  for (const node of nodes) {
+    const absPath = path.resolve(projectRoot || process.cwd(), node.file);
+    if (await fs.pathExists(absPath)) {
+      files[node.file] = await fs.readFile(absPath, 'utf8');
+    }
+  }
+  return files;
+}

package/src/requestHandler.js

@@ -0,0 +1,292 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { queryGraph, getBlastRadius } from '../../graphify-bridge/src/index.js';
+import { classifyRisk } from './riskClassifier.js';
+import { createSnapshot, logChange, rollbackToToken } from './snapshotManager.js';
+import { applyChangePlan, buildDryRunPreview, readRelevantFiles } from './fileWriter.js';
+import { processAttachments } from './attachmentProcessor.js';
+import { logTokenUsage } from './tokenLogger.js';
+
+const client = new Anthropic({ apiKey: process.env.SEAM_ANTHROPIC_KEY });
+
+const pendingPlans = new Map();
+
+function timeout(ms, label) {
+  return new Promise((_, reject) =>
+    setTimeout(() => reject(new Error(`TIMEOUT: ${label} exceeded ${ms}ms`)), ms)
+  );
+}
+
+export async function handleChangeRequest({ request, attachments, config, broadcast }) {
+  const requestId = crypto.randomUUID();
+
+  // 60-second hard wall for entire request
+  try {
+    await Promise.race([
+      _handleChangeRequest({ requestId, request, attachments, config, broadcast }),
+      timeout(60_000, 'Total request wall time')
+    ]);
+  } catch (err) {
+    broadcast({ type: 'FAILED', requestId, message: err.message });
+    pendingPlans.delete(requestId);
+    pendingPlans.delete(requestId + '-apply');
+  }
+}
+
+async function _handleChangeRequest({ requestId, request, attachments, config, broadcast }) {
+  if (request.length > 2000) {
+    broadcast({ type: 'FAILED', requestId, message: 'Request text is too long (max 2000 characters). Please be more concise.' });
+    return;
+  }
+
+  broadcast({ type: 'STATUS', status: 'analyzing', requestId, message: 'Reading the graph...' });
+
+  const processedAttachments = await processAttachments(attachments, config);
+
+  // Graph query — 5s timeout per COST_AND_SAFETY.md
+  const graphNodes = await Promise.race([
+    queryGraph(request, config.graphifyOut),
+    timeout(5_000, 'Graph query')
+  ]);
+
+  if (!graphNodes.length) {
+    broadcast({
+      type: 'FAILED', requestId,
+      message: "Seam couldn't find the relevant files in your codebase graph. Try rebuilding the graph (Settings → Rebuild Graph) or be more specific about what you want to change."
+    });
+    return;
+  }
+
+  const blastRadius = getBlastRadius(graphNodes);
+  const tier = classifyRisk(request, graphNodes, blastRadius);
+
+  broadcast({
+    type: 'RISK_ASSESSMENT', requestId, tier, blastRadius,
+    affectedFiles: graphNodes.map(n => n.file),
+    message: getRiskMessage(tier, blastRadius)
+  });
+
+  if (tier === 'B' || tier === 'C') {
+    pendingPlans.set(requestId, {
+      request, graphNodes, blastRadius, tier,
+      processedAttachments, config,
+      state: 'awaiting_confirmation'
+    });
+    return;
+  }
+
+  await executePlan({ requestId, request, graphNodes, processedAttachments, tier, config, broadcast });
+}
+
+export async function executeConfirmedPlan(planId, broadcast) {
+  try {
+    await Promise.race([
+      _executeConfirmedPlan(planId, broadcast),
+      timeout(60_000, 'executeConfirmedPlan wall time')
+    ]);
+  } catch (err) {
+    broadcast({ type: 'FAILED', message: err.message });
+    pendingPlans.delete(planId);
+    pendingPlans.delete(planId + '-apply');
+  }
+}
+
+async function _executeConfirmedPlan(planId, broadcast) {
+  const pending = pendingPlans.get(planId);
+  if (!pending) throw new Error('Plan not found or already executed');
+  pendingPlans.delete(planId);
+  await executePlan({
+    requestId: planId,
+    request: pending.request,
+    graphNodes: pending.graphNodes,
+    processedAttachments: pending.processedAttachments,
+    tier: pending.tier,
+    config: pending.config,
+    broadcast
+  });
+}
+
+async function executePlan({ requestId, request, graphNodes, processedAttachments, tier, config, broadcast }) {
+  broadcast({ type: 'STATUS', status: 'planning', requestId, message: 'Planning changes...' });
+
+  const fileContents = await readRelevantFiles(graphNodes, config.projectRoot);
+
+  // One Claude call — 30s timeout per COST_AND_SAFETY.md
+  let claudeResponse;
+  try {
+    claudeResponse = await Promise.race([
+      callClaude({ request, fileContents, processedAttachments }),
+      timeout(30_000, 'Claude response')
+    ]);
+  } catch (err) {
+    throw new Error(`Claude didn't respond in time. Try simplifying your request or try again in a moment.`);
+  }
+
+  const { changePlan, usage } = claudeResponse;
+
+  // Log tokens immediately
+  await logTokenUsage({
+    requestId, request, tier,
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    status: 'planned'
+  });
+
+  // Dry-run preview
+  const previews = await buildDryRunPreview(changePlan, config);
+  broadcast({ type: 'DRY_RUN', requestId, changePlan, previews, message: 'Preview ready — review and apply' });
+
+  if (tier !== 'A') {
+    pendingPlans.set(requestId + '-apply', { changePlan, fileContents, config, tier, request });
+    return;
+  }
+
+  await _applyApprovedPlan({ requestId, changePlan, fileContents, tier, request, config, broadcast });
+}
+
+export async function applyApprovedPlan({ requestId, broadcast }) {
+  try {
+    await Promise.race([
+      _applyApprovedPlanOuter({ requestId, broadcast }),
+      timeout(60_000, 'applyApprovedPlan wall time')
+    ]);
+  } catch (err) {
+    broadcast({ type: 'FAILED', message: err.message });
+    pendingPlans.delete(requestId + '-apply');
+  }
+}
+
+async function _applyApprovedPlanOuter({ requestId, broadcast }) {
+  const key = requestId + '-apply';
+  const pending = pendingPlans.get(key);
+  if (!pending) throw new Error(`No pending plan for requestId ${requestId}`);
+  pendingPlans.delete(key);
+  await _applyApprovedPlan({ requestId, ...pending, broadcast });
+}
+
+async function _applyApprovedPlan({ requestId, changePlan, fileContents, tier, request, config, broadcast }) {
+  broadcast({ type: 'STATUS', status: 'snapshotting', requestId, message: 'Saving snapshot...' });
+
+  // Circuit breaker: snapshot must succeed before any write
+  let beforeToken;
+  try {
+    beforeToken = await createSnapshot({
+      changePlan, status: 'before', projectId: config.projectId,
+      request, tier, fileContents
+    });
+  } catch (err) {
+    broadcast({
+      type: 'FAILED', requestId,
+      message: "Couldn't save a snapshot — Seam stopped before making any changes to protect your codebase. Check your Supabase connection."
+    });
+    return;
+  }
+
+  broadcast({ type: 'STATUS', status: 'writing', requestId, message: 'Applying changes...' });
+
+  let writtenFiles;
+  try {
+    writtenFiles = await applyChangePlan(changePlan, config);
+  } catch (err) {
+    // Write failed — rollback any partial writes using the before snapshot
+    await rollbackToToken(beforeToken, config, broadcast);
+    broadcast({
+      type: 'FAILED', requestId,
+      message: `Write failed on ${err.filepath || 'a file'}. All changes from this request have been rolled back. Your codebase is unchanged.`
+    });
+    return;
+  }
+
+  const afterToken = await createSnapshot({
+    changePlan, status: 'after', projectId: config.projectId,
+    request, tier, fileContents: {}, parentToken: beforeToken
+  });
+
+  await logChange({
+    projectId: config.projectId, request, tier,
+    filesChanged: writtenFiles, beforeToken, afterToken, status: 'completed'
+  });
+
+  broadcast({ type: 'COMPLETE', requestId, beforeToken, afterToken, filesChanged: writtenFiles, message: 'Done' });
+}
+
+async function callClaude({ request, fileContents, processedAttachments }) {
+  const systemPrompt = `You are Seam, a senior software engineer making precise, minimal changes to a codebase.
+You will receive:
+- The user's change request
+- The contents of only the relevant files (identified by a knowledge graph)
+- Any attachments the user has provided
+
+Your job is to return a JSON change plan ONLY — no explanation, no markdown, no preamble.
+
+The JSON must be this exact shape:
+{
+  "originalRequest": "the user's request verbatim",
+  "summary": "one sentence: what this change does",
+  "changes": [
+    {
+      "filepath": "relative/path/to/file.tsx",
+      "type": "modify | create | asset_place",
+      "originalSnippet": "exact text to find and replace (for modify)",
+      "replacementSnippet": "the new text",
+      "destinationPath": "for asset_place type only"
+    }
+  ]
+}
+
+Rules:
+- Make the MINIMUM change that satisfies the request
+- Do not refactor unrelated code
+- Do not add features not asked for
+- originalSnippet must be unique enough to find exactly once in the file`;
+
+  const messageContent = [];
+
+  for (const att of processedAttachments.filter(a => a.role === 'vision')) {
+    messageContent.push({ type: 'image', source: { type: 'base64', media_type: att.mediaType, data: att.base64 } });
+  }
+
+  const docContext = processedAttachments
+    .filter(a => a.role === 'context')
+    .map(a => `--- Attached document: ${a.filename} ---\n${a.textContent}`)
+    .join('\n\n');
+
+  const userMessage = [
+    `Change request: ${request}`,
+    docContext ? `\nAttached context:\n${docContext}` : '',
+    `\nRelevant files:\n${JSON.stringify(fileContents, null, 2)}`
+  ].filter(Boolean).join('\n');
+
+  messageContent.push({ type: 'text', text: userMessage });
+
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 4096,
+    system: systemPrompt,
+    messages: [{ role: 'user', content: messageContent }]
+  });
+
+  const raw = response.content[0].text;
+  let changePlan;
+  try {
+    changePlan = JSON.parse(raw.replace(/```json|```/g, '').trim());
+  } catch {
+    throw new Error('Seam received an unexpected response and stopped to be safe. No files were changed.');
+  }
+
+  if (!Array.isArray(changePlan?.changes)) {
+    throw new Error('Claude returned a malformed change plan. No files were changed.');
+  }
+  for (const change of changePlan.changes) {
+    if (typeof change.filepath !== 'string' || change.filepath.startsWith('/') || change.filepath.includes('..')) {
+      throw new Error(`Claude returned an unsafe file path: "${change.filepath}". No files were changed.`);
+    }
+  }
+
+  return { changePlan, usage: response.usage };
+}
+
+function getRiskMessage(tier, blastRadius) {
+  if (tier === 'A') return 'Safe change — ready to apply.';
+  if (tier === 'B') return `Logic change — affects ${blastRadius.affectedNodes} file(s) across ${blastRadius.communities} section(s). Review before applying.`;
+  return `High risk — touches ${blastRadius.godNodes.length || 'core'} critical module(s) across ${blastRadius.communities} section(s). Read carefully.`;
+}

package/src/riskClassifier.js

@@ -0,0 +1,29 @@
+const TIER_C_KEYWORDS = ['auth', 'authenticat', 'login', 'schema', 'database', 'db', 'migration',
+  'routing', 'middleware', 'env', 'environment', 'config', 'layout', 'root', 'core'];
+const TIER_B_KEYWORDS = ['delete', 'remove', 'drop'];
+
+export function classifyRisk(request, nodes, blastRadius) {
+  const req = request.toLowerCase();
+
+  // Tier C: semantic keywords — word-boundary match to avoid "debug"→"db", "score"→"core"
+  const tierCRe = new RegExp(`\\b(${TIER_C_KEYWORDS.join('|')})\\b`);
+  if (tierCRe.test(req)) return 'C';
+
+  // Tier C: structural signals
+  if (blastRadius.godNodes.length > 0) return 'C';
+  if (blastRadius.communities >= 3) return 'C';
+  if (blastRadius.affectedNodes >= 9) return 'C';
+  if (blastRadius.maxInboundEdges >= 11) return 'C';
+
+  // Tier B: semantic keywords — word-boundary match
+  const tierBRe = new RegExp(`\\b(${TIER_B_KEYWORDS.join('|')})\\b`);
+  if (tierBRe.test(req)) return 'B';
+
+  // Tier B: structural signals
+  if (blastRadius.affectedNodes >= 2) return 'B';
+  if (blastRadius.communities >= 2) return 'B';
+  if (blastRadius.maxInboundEdges >= 3) return 'B';
+
+  // Tier A: everything else
+  return 'A';
+}

package/src/server.js

@@ -0,0 +1,153 @@
+import dotenv from 'dotenv';
+dotenv.config({ path: '.env.seam' });
+import express from 'express';
+import cors from 'cors';
+import { WebSocketServer } from 'ws';
+import { createServer } from 'http';
+import multer from 'multer';
+import path from 'path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'url';
+
+import { handleChangeRequest, executeConfirmedPlan, applyApprovedPlan } from './requestHandler.js';
+import { rollbackToToken, getChangeHistory } from './snapshotManager.js';
+import { rebuildGraph } from '../../graphify-bridge/src/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+if (process.env.NODE_ENV === 'production') {
+  console.error('[Seam] ❌ Seam will not run in production. Exiting.');
+  process.exit(1);
+}
+
+const configPath = path.join(process.cwd(), 'seam.config.json');
+if (!await fs.pathExists(configPath)) {
+  console.error('[Seam] ❌ seam.config.json not found. Run npx seam init first.');
+  process.exit(1);
+}
+
+const config = await fs.readJson(configPath);
+const PORT = config.seamServer?.port || 7337;
+
+const app = express();
+const allowedOrigins = config.seamServer?.allowedOrigins ?? [
+  'http://localhost:3000',
+  'http://localhost:5173',
+  'http://127.0.0.1:3000',
+  'http://127.0.0.1:5173',
+];
+app.use(cors({ origin: allowedOrigins }));
+app.use(express.json({ limit: '50mb' }));
+
+const upload = multer({
+  dest: path.join(process.cwd(), '.seam/uploads/'),
+  limits: { fileSize: 25 * 1024 * 1024 }
+});
+
+const server = createServer(app);
+const wss = new WebSocketServer({ server });
+const clients = new Set();
+
+wss.on('connection', (ws) => {
+  clients.add(ws);
+  ws.on('close', () => clients.delete(ws));
+});
+
+export function broadcast(event) {
+  const msg = JSON.stringify(event);
+  clients.forEach(ws => { if (ws.readyState === 1) ws.send(msg); });
+}
+
+app.get('/api/health', (req, res) => {
+  res.json({ status: 'ok', version: '0.1.0', project: config.projectId });
+});
+
+// One active request at a time — reject concurrent requests
+let activeRequest = false;
+
+app.post('/api/request', upload.array('attachments', 10), async (req, res) => {
+  if (activeRequest) {
+    return res.status(409).json({
+      error: 'A change is already in progress. Wait for it to complete or fail.'
+    });
+  }
+  const { request } = req.body;
+  const attachments = req.files || [];
+  if (!request?.trim()) return res.status(400).json({ error: 'Request text is required' });
+
+  activeRequest = true;
+  res.json({ status: 'accepted', message: 'Request received — analyzing...' });
+  try {
+    await handleChangeRequest({ request: request.trim(), attachments, config, broadcast });
+  } finally {
+    activeRequest = false;
+    // Clean up multer temp files
+    for (const file of attachments) {
+      fs.unlink(file.path).catch(() => {});
+    }
+  }
+});
+
+app.post('/api/apply', async (req, res) => {
+  const { planId } = req.body;
+  if (!planId) return res.status(400).json({ error: 'planId required' });
+  if (activeRequest) return res.status(409).json({ error: 'A change is already in progress.' });
+  activeRequest = true;
+  res.json({ status: 'applying' });
+  try {
+    await executeConfirmedPlan(planId, broadcast);
+  } finally {
+    activeRequest = false;
+  }
+});
+
+app.post('/api/apply-plan', async (req, res) => {
+  const { requestId } = req.body;
+  if (!requestId) return res.status(400).json({ error: 'requestId required' });
+  if (activeRequest) return res.status(409).json({ error: 'A change is already in progress.' });
+  activeRequest = true;
+  res.json({ status: 'applying' });
+  try {
+    await applyApprovedPlan({ requestId, broadcast });
+  } finally {
+    activeRequest = false;
+  }
+});
+
+app.post('/api/rollback', async (req, res) => {
+  const { beforeToken } = req.body;
+  if (!beforeToken) return res.status(400).json({ error: 'beforeToken required' });
+  if (activeRequest) return res.status(409).json({ error: 'A change is already in progress.' });
+  activeRequest = true;
+  res.json({ status: 'rolling_back' });
+  try {
+    await rollbackToToken(beforeToken, config, broadcast);
+  } catch (err) {
+    broadcast({ type: 'FAILED', message: err.message });
+  } finally {
+    activeRequest = false;
+  }
+});
+
+app.get('/api/history', async (req, res) => {
+  const history = await getChangeHistory(config.projectId);
+  res.json({ history });
+});
+
+app.post('/api/graph/rebuild', async (req, res) => {
+  res.json({ status: 'rebuilding' });
+  broadcast({ type: 'STATUS', status: 'rebuilding_graph' });
+  try {
+    await rebuildGraph(config.graphifyOut);
+    broadcast({ type: 'STATUS', status: 'graph_ready' });
+  } catch (err) {
+    broadcast({ type: 'FAILED', message: `Graph rebuild failed: ${err.message}` });
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`\n⚡ Seam running on localhost:${PORT}`);
+  console.log(`   Project: ${config.projectId}`);
+  console.log(`   Graph:   ${config.graphifyOut}/graph.json`);
+  console.log(`   Panel:   Open your app and press Cmd+Shift+S\n`);
+});

package/src/snapshotManager.js

@@ -0,0 +1,118 @@
+import { createClient } from '@supabase/supabase-js';
+
+function getClient() {
+  const url = process.env.SEAM_SUPABASE_URL;
+  const key = process.env.SEAM_SUPABASE_ANON_KEY;
+  if (!url || !key) throw new Error('Missing SEAM_SUPABASE_URL or SEAM_SUPABASE_ANON_KEY');
+  return createClient(url, key);
+}
+
+/**
+ * Save a snapshot to Supabase.
+ * fileContents: { [filepath]: string } — only the files Seam touched.
+ * Returns the session_token UUID.
+ */
+export async function createSnapshot({ changePlan, status, projectId, request, tier, fileContents, parentToken }) {
+  const supabase = getClient();
+  const token = crypto.randomUUID();
+
+  const { error } = await supabase.from('seam_snapshots').insert({
+    session_token: token,
+    project_id: projectId,
+    status,
+    risk_tier: tier,
+    change_request: request,
+    files: fileContents || {},
+    parent_token: parentToken || null
+  });
+
+  if (error) throw new Error(`Snapshot failed: ${error.message}`);
+  return token;
+}
+
+/**
+ * Load a snapshot by token.
+ */
+export async function loadSnapshot(token) {
+  const supabase = getClient();
+  const { data, error } = await supabase
+    .from('seam_snapshots')
+    .select('*')
+    .eq('session_token', token)
+    .single();
+
+  if (error) throw new Error(`Could not load snapshot ${token}: ${error.message}`);
+  return data;
+}
+
+/**
+ * Mark a snapshot as rolled_back.
+ */
+export async function markRolledBack(token) {
+  const supabase = getClient();
+  const { error } = await supabase
+    .from('seam_snapshots')
+    .update({ status: 'rolled_back' })
+    .eq('session_token', token);
+  if (error) throw new Error(`markRolledBack failed: ${error.message}`);
+}
+
+/**
+ * Get the last 20 change history entries for a project.
+ */
+export async function getChangeHistory(projectId) {
+  const supabase = getClient();
+  const { data, error } = await supabase
+    .from('seam_changes')
+    .select('*')
+    .eq('project_id', projectId)
+    .order('created_at', { ascending: false })
+    .limit(20);
+
+  if (error) throw new Error(`History fetch failed: ${error.message}`);
+  return data || [];
+}
+
+/**
+ * Log a completed change to seam_changes.
+ */
+export async function logChange({ projectId, request, tier, filesChanged, beforeToken, afterToken, status }) {
+  const supabase = getClient();
+  const { error } = await supabase.from('seam_changes').insert({
+    project_id: projectId,
+    request,
+    risk_tier: tier,
+    files_changed: filesChanged,
+    before_token: beforeToken,
+    after_token: afterToken,
+    status
+  });
+  if (error) throw new Error(`logChange failed: ${error.message}`);
+}
+
+/**
+ * Full rollback: restore files from a before_token snapshot.
+ * Returns the list of restored file paths.
+ */
+export async function rollbackToToken(beforeToken, config, broadcast) {
+  const snapshot = await loadSnapshot(beforeToken);
+
+  const { applyChangePlan } = await import('./fileWriter.js');
+  const restoredFiles = Object.keys(snapshot.files);
+
+  const rollbackPlan = {
+    originalRequest: `Rollback to ${beforeToken}`,
+    tier: snapshot.risk_tier,
+    changes: restoredFiles.map(filepath => ({
+      filepath,
+      type: 'restore',
+      replacementSnippet: snapshot.files[filepath]
+    }))
+  };
+
+  await applyChangePlan(rollbackPlan, config);
+  await markRolledBack(beforeToken);
+
+  if (broadcast) broadcast({ type: 'STATUS', status: 'rolled_back', message: `Rolled back to ${beforeToken.slice(0, 8)}...` });
+  return { restoredFiles, beforeToken };
+}

package/src/tokenLogger.js

@@ -0,0 +1,37 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+const LOG_PATH = path.join(process.cwd(), '.seam', 'logs', 'token_usage.log');
+
+// Sonnet pricing (per-million tokens as of 2025)
+const INPUT_COST_PER_TOKEN  = 3.00 / 1_000_000;
+const OUTPUT_COST_PER_TOKEN = 15.00 / 1_000_000;
+
+export function calcCost(inputTokens, outputTokens) {
+  return (inputTokens * INPUT_COST_PER_TOKEN) + (outputTokens * OUTPUT_COST_PER_TOKEN);
+}
+
+export function formatCost(usd) {
+  return '$' + usd.toFixed(4);
+}
+
+/**
+ * Append one usage line to .seam/logs/token_usage.log.
+ * Called after every Claude API call (or failed attempt).
+ */
+export async function logTokenUsage({ requestId, request, tier, inputTokens, outputTokens, status }) {
+  await fs.ensureFile(LOG_PATH);
+  const cost = calcCost(inputTokens || 0, outputTokens || 0);
+  const line = JSON.stringify({
+    ts: new Date().toISOString(),
+    requestId,
+    request: (request || '').slice(0, 80),
+    tier: tier || '—',
+    inputTokens: inputTokens || 0,
+    outputTokens: outputTokens || 0,
+    costUsd: cost,
+    status
+  }) + '\n';
+  await fs.appendFile(LOG_PATH, line, 'utf8');
+  return { inputTokens, outputTokens, cost };
+}