sdtk-design-kit 0.1.1 → 0.2.0

package/src/lib/design-input-contract.js

@@ -0,0 +1,683 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { describeDesignPaths, resolveProjectPath } = require("./design-paths");
+const { resolveProfile } = require("./design-profiles");
+const { ValidationError } = require("./errors");
+
+const EVALUATION_REFERENCE_SEGMENTS = ["docs", "ui"];
+const TEMPLATE_ROLES = new Set([
+  "home",
+  "category",
+  "product-detail",
+  "search",
+  "cart",
+  "checkout",
+  "order-history",
+  "order-detail",
+  "account-info",
+  "configurator-bom",
+  "generic",
+]);
+
+function toPosixRelative(basePath, targetPath) {
+  return path.relative(basePath, targetPath).split(path.sep).join("/");
+}
+
+function evaluationReferenceLabel() {
+  return EVALUATION_REFERENCE_SEGMENTS.join("/");
+}
+
+function hasEvaluationReferenceSegments(value) {
+  const normalized = path
+    .normalize(String(value || ""))
+    .split(/[\\/]+/)
+    .map((segment) => segment.toLowerCase())
+    .filter(Boolean);
+  for (let index = 0; index < normalized.length - 1; index++) {
+    if (
+      normalized[index] === EVALUATION_REFERENCE_SEGMENTS[0] &&
+      normalized[index + 1] === EVALUATION_REFERENCE_SEGMENTS[1]
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function findArtifactByPattern(rootPath, relativeDir, pattern) {
+  const absoluteDir = path.join(rootPath, relativeDir);
+  if (!fs.existsSync(absoluteDir) || !fs.statSync(absoluteDir).isDirectory()) {
+    return null;
+  }
+  const entries = fs
+    .readdirSync(absoluteDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && pattern.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  if (entries.length === 0) {
+    return null;
+  }
+  const fileName = entries[0];
+  const absolutePath = path.join(absoluteDir, fileName);
+  return {
+    relativePath: `${relativeDir.replace(/\\/g, "/")}/${fileName}`,
+    absolutePath,
+  };
+}
+
+function resolveReferenceDirectory(value, projectPath) {
+  if (!value) {
+    return { provided: false, status: "NOT_PROVIDED", absolutePath: null };
+  }
+  if (hasEvaluationReferenceSegments(value)) {
+    throw new ValidationError(
+      `--reference-dir cannot point at ${evaluationReferenceLabel()}; that folder is evaluation-only and not a generation input. No project files were changed.`
+    );
+  }
+  const absolutePath = path.resolve(projectPath, value);
+  if (hasEvaluationReferenceSegments(absolutePath)) {
+    throw new ValidationError(
+      `--reference-dir cannot point at ${evaluationReferenceLabel()}; that folder is evaluation-only and not a generation input. No project files were changed.`
+    );
+  }
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isDirectory()) {
+    throw new ValidationError(`--reference-dir is not a valid directory: ${absolutePath}. No project files were changed.`);
+  }
+  return {
+    provided: true,
+    status: "READY_READ_ONLY",
+    absolutePath,
+  };
+}
+
+function listFilesRecursive(rootDirectory) {
+  const results = [];
+  const stack = [rootDirectory];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(absolutePath);
+        continue;
+      }
+      if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  results.sort();
+  return results;
+}
+
+function tokenSet(value) {
+  return new Set(
+    String(value || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, " ")
+      .split(" ")
+      .map((token) => token.trim())
+      .filter(Boolean)
+  );
+}
+
+function readHtmlHints(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const titleMatch = raw.match(/<title[^>]*>(.*?)<\/title>/i);
+    const headingMatch = raw.match(/<h[1-2][^>]*>(.*?)<\/h[1-2]>/i);
+    return {
+      title: titleMatch ? titleMatch[1].replace(/<[^>]+>/g, " ").trim() : "",
+      heading: headingMatch ? headingMatch[1].replace(/<[^>]+>/g, " ").trim() : "",
+    };
+  } catch (_err) {
+    return { title: "", heading: "" };
+  }
+}
+
+function confidenceFromScore(score) {
+  if (score >= 4) return "high";
+  if (score >= 2) return "medium";
+  if (score >= 1) return "low";
+  return "low";
+}
+
+function mapReferenceFiles({ referenceDir, screens }) {
+  const files = listFilesRecursive(referenceDir);
+  const entries = [];
+  const screenTargets = Array.isArray(screens) ? screens : [];
+  const supportedExtensions = new Set([".html", ".htm", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"]);
+  for (const absolutePath of files) {
+    const relativePath = toPosixRelative(referenceDir, absolutePath);
+    const extension = path.extname(absolutePath).toLowerCase();
+    if (!supportedExtensions.has(extension)) {
+      entries.push({
+        sourceFileRelativePath: relativePath,
+        fileType: extension || "unknown",
+        mappedScreenId: null,
+        mappedScreenTitle: null,
+        confidence: "low",
+        evidenceNotes: ["unsupported file type"],
+        status: "unmapped",
+      });
+      continue;
+    }
+
+    const baseTokens = tokenSet(path.basename(absolutePath, extension));
+    const htmlHints = extension === ".html" || extension === ".htm" ? readHtmlHints(absolutePath) : { title: "", heading: "" };
+    const titleTokens = tokenSet(htmlHints.title);
+    const headingTokens = tokenSet(htmlHints.heading);
+
+    let bestMatch = null;
+    for (const screen of screenTargets) {
+      const screenTokens = tokenSet(`${screen.screenId} ${screen.title}`);
+      let score = 0;
+      const evidence = [];
+      for (const token of screenTokens) {
+        if (baseTokens.has(token)) {
+          score += 2;
+          evidence.push(`filename token match: ${token}`);
+        }
+        if (titleTokens.has(token)) {
+          score += 1;
+          evidence.push(`title token match: ${token}`);
+        }
+        if (headingTokens.has(token)) {
+          score += 1;
+          evidence.push(`heading token match: ${token}`);
+        }
+      }
+      if (!bestMatch || score > bestMatch.score) {
+        bestMatch = { score, screen, evidence };
+      }
+    }
+
+    if (!bestMatch || bestMatch.score <= 0) {
+      entries.push({
+        sourceFileRelativePath: relativePath,
+        fileType: extension,
+        mappedScreenId: null,
+        mappedScreenTitle: null,
+        confidence: "low",
+        evidenceNotes: ["no deterministic filename/title/heading match"],
+        status: "unmapped",
+      });
+      continue;
+    }
+
+    entries.push({
+      sourceFileRelativePath: relativePath,
+      fileType: extension,
+      mappedScreenId: bestMatch.screen.screenId,
+      mappedScreenTitle: bestMatch.screen.title,
+      confidence: confidenceFromScore(bestMatch.score),
+      evidenceNotes: bestMatch.evidence,
+      status: "mapped",
+    });
+  }
+
+  return {
+    totalFiles: entries.length,
+    mappedCount: entries.filter((entry) => entry.status === "mapped").length,
+    unmappedCount: entries.filter((entry) => entry.status !== "mapped").length,
+    entries,
+  };
+}
+
+function writeInputContractState(projectPath, statePayload) {
+  const paths = describeDesignPaths(projectPath);
+  fs.mkdirSync(paths.designStatePath, { recursive: true });
+  fs.writeFileSync(paths.designStartInputStatePath, `${JSON.stringify(statePayload, null, 2)}\n`, "utf-8");
+  return paths.designStartInputStatePath;
+}
+
+function toScreenId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function compactString(value) {
+  return typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+}
+
+function firstString(raw, fieldNames) {
+  for (const fieldName of fieldNames) {
+    const value = raw && raw[fieldName];
+    const compacted = compactString(value);
+    if (compacted) {
+      return compacted;
+    }
+  }
+  return "";
+}
+
+function normalizeStringList(value) {
+  if (!Array.isArray(value)) {
+    const single = compactString(value);
+    return single ? [single] : [];
+  }
+  return value
+    .map((item) => {
+      if (typeof item === "string") {
+        return compactString(item);
+      }
+      if (item && typeof item === "object") {
+        return compactString(item.title || item.name || item.label || item.id || item.description);
+      }
+      return "";
+    })
+    .filter(Boolean);
+}
+
+function firstStringList(raw, fieldNames) {
+  for (const fieldName of fieldNames) {
+    const values = normalizeStringList(raw && raw[fieldName]);
+    if (values.length > 0) {
+      return values;
+    }
+  }
+  return [];
+}
+
+function normalizeSectionRecord(value, index) {
+  if (typeof value === "string") {
+    const title = compactString(value);
+    return title
+      ? {
+          id: toScreenId(title) || `section-${index + 1}`,
+          title,
+          purpose: null,
+          components: [],
+          states: [],
+          interactions: [],
+          data_slots: [],
+        }
+      : null;
+  }
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const title = firstString(value, ["title", "name", "label", "heading"]);
+  if (!title) {
+    return null;
+  }
+  return {
+    id: toScreenId(firstString(value, ["id", "slug"]) || title) || `section-${index + 1}`,
+    title,
+    purpose: firstString(value, ["purpose", "intent", "description"]) || null,
+    components: firstStringList(value, ["components", "requiredComponents", "required_components"]),
+    states: firstStringList(value, ["states", "requiredStates", "required_states"]),
+    interactions: firstStringList(value, ["interactions", "interactionNotes", "interaction_notes"]),
+    data_slots: firstStringList(value, ["dataSlots", "data_slots", "contentSlots", "content_slots"]),
+  };
+}
+
+function firstSectionList(raw) {
+  const sectionCandidates = [
+    raw && raw.sections,
+    raw && raw.majorSections,
+    raw && raw.major_sections,
+    raw && raw.sectionsTopToBottom,
+    raw && raw.sections_top_to_bottom,
+  ].filter(Array.isArray);
+  for (const candidate of sectionCandidates) {
+    const sections = candidate.map((item, index) => normalizeSectionRecord(item, index)).filter(Boolean);
+    if (sections.length > 0) {
+      return sections;
+    }
+  }
+  return [];
+}
+
+function normalizeVisualTokenUsage(value) {
+  const payload = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return {
+    palette_keys: firstStringList(payload, ["palette_keys", "paletteKeys"]),
+    typography_keys: firstStringList(payload, ["typography_keys", "typographyKeys"]),
+    spacing_keys: firstStringList(payload, ["spacing_keys", "spacingKeys"]),
+    radius_keys: firstStringList(payload, ["radius_keys", "radiusKeys"]),
+  };
+}
+
+function normalizeTemplateRole(value) {
+  const normalized = toScreenId(value);
+  if (!normalized) {
+    return "";
+  }
+  const aliases = {
+    product: "product-detail",
+    pdp: "product-detail",
+    productdetail: "product-detail",
+    orders: "order-history",
+    order: "order-detail",
+    account: "account-info",
+    configurator: "configurator-bom",
+    bom: "configurator-bom",
+    "mode-b-configurator": "configurator-bom",
+  };
+  const role = aliases[normalized] || normalized;
+  return TEMPLATE_ROLES.has(role) ? role : "";
+}
+
+function inferTemplateRole(raw, screenId, title) {
+  const explicit = normalizeTemplateRole(
+    firstString(raw, ["templateRole", "template_role", "screenRole", "screen_role", "role"])
+  );
+  if (explicit) {
+    return explicit;
+  }
+  const combined = toScreenId(`${screenId} ${title}`);
+  const roleMatchers = [
+    ["product-detail", ["product-detail", "productdetail", "pdp"]],
+    ["order-history", ["order-history", "orderhistory", "orders"]],
+    ["order-detail", ["order-detail", "orderdetail"]],
+    ["account-info", ["account-info", "accountinfo", "account"]],
+    ["configurator-bom", ["configurator", "bom", "mode-b"]],
+    ["checkout", ["checkout"]],
+    ["category", ["category", "catalog"]],
+    ["search", ["search"]],
+    ["cart", ["cart"]],
+    ["home", ["home", "landing"]],
+  ];
+  for (const [role, needles] of roleMatchers) {
+    if (needles.some((needle) => combined.includes(needle))) {
+      return role;
+    }
+  }
+  return "generic";
+}
+
+function normalizeSourceEvidence(raw, sourceArtifact) {
+  const payload =
+    raw && raw.sourceEvidence && typeof raw.sourceEvidence === "object"
+      ? raw.sourceEvidence
+      : raw && raw.source_evidence && typeof raw.source_evidence === "object"
+        ? raw.source_evidence
+        : {};
+  return {
+    source_artifact: firstString(payload, ["source_artifact", "sourceArtifact"]) || sourceArtifact || null,
+    source_status: firstString(raw, ["sourceStatus", "source_status"]) || "explicit",
+    source_quote: firstString(raw, ["source_quote", "sourceQuote"]) || firstString(payload, ["source_quote", "sourceQuote"]) || null,
+    source_line_range: Array.isArray(raw && raw.source_line_range)
+      ? raw.source_line_range
+      : Array.isArray(raw && raw.sourceLineRange)
+        ? raw.sourceLineRange
+        : Array.isArray(payload.source_line_range)
+          ? payload.source_line_range
+          : Array.isArray(payload.sourceLineRange)
+            ? payload.sourceLineRange
+            : null,
+  };
+}
+
+function normalizedScreenRecord(raw, sourceArtifact, fallbackTitle) {
+  const title = String(
+    (raw && (raw.title || raw.name || raw.screen || raw.label || raw.id)) || fallbackTitle || ""
+  ).trim();
+  if (!title) {
+    return null;
+  }
+  const screenId = toScreenId((raw && (raw.id || raw.slug)) || title);
+  const route = firstString(raw, ["route", "path", "url"]);
+  const purpose = firstString(raw, ["purpose", "screenPurpose", "screen_purpose", "goal"]);
+  const userIntent = firstString(raw, ["userIntent", "user_intent", "intent"]);
+  const primaryAction = firstString(raw, ["primaryAction", "primary_action", "cta"]);
+  const sections = firstSectionList(raw);
+  const majorSections = sections.map((section) => section.title);
+  const layoutModel = firstString(raw, ["layoutModel", "layout_model"]);
+  const density = firstString(raw, ["density", "layoutDensity", "layout_density"]);
+  const requiredComponents = firstStringList(raw, ["components", "requiredComponents", "required_components", "componentRequirements", "component_requirements"]);
+  const requiredStates = firstStringList(raw, ["states", "requiredStates", "required_states"]);
+  const interactions = firstStringList(raw, ["interactions", "interactionNotes", "interaction_notes"]);
+  const dataSlots = firstStringList(raw, ["dataSlots", "data_slots", "contentSlots", "content_slots"]);
+  const accessibilityNotes = firstStringList(raw, ["accessibilityNotes", "accessibility_notes", "a11y"]);
+  const visualTokenUsage = normalizeVisualTokenUsage((raw && (raw.visualTokenUsage || raw.visual_token_usage)) || {});
+  const acceptanceCriteria = firstStringList(raw, ["acceptanceCriteria", "acceptance_criteria", "criteria"]);
+  const templateRole = inferTemplateRole(raw || {}, screenId, title);
+  const sourceEvidence = normalizeSourceEvidence(raw || {}, sourceArtifact);
+  const populatedCount =
+    [route, purpose, userIntent, primaryAction, layoutModel, density].filter(Boolean).length +
+    (sections.length > 0 ? 1 : 0) +
+    (requiredComponents.length > 0 ? 1 : 0) +
+    (requiredStates.length > 0 ? 1 : 0) +
+    (interactions.length > 0 ? 1 : 0) +
+    (dataSlots.length > 0 ? 1 : 0) +
+    (accessibilityNotes.length > 0 ? 1 : 0) +
+    (acceptanceCriteria.length > 0 ? 1 : 0) +
+    (sourceEvidence.source_quote ? 1 : 0);
+  const confidence = populatedCount >= 3 ? "high" : populatedCount >= 1 ? "medium" : "low";
+  return {
+    screenId,
+    title,
+    route: route || null,
+    purpose: purpose || null,
+    userIntent: userIntent || null,
+    primaryAction: primaryAction || null,
+    sections,
+    majorSections,
+    layoutModel: layoutModel || null,
+    density: density || null,
+    requiredComponents,
+    requiredStates,
+    interactions,
+    dataSlots,
+    accessibilityNotes,
+    visualTokenUsage,
+    acceptanceCriteria,
+    templateRole,
+    sourceEvidence,
+    sourceArtifact,
+    sourceStatus: "explicit",
+    confidence,
+  };
+}
+
+function extractScreensFromHandoffJson(handoffPath, relativePath) {
+  const raw = fs.readFileSync(handoffPath, "utf-8");
+  let payload = null;
+  try {
+    payload = JSON.parse(raw);
+  } catch (_err) {
+    return [];
+  }
+  const candidateArrays = [
+    payload && payload.screens,
+    payload && payload.screenInventory,
+    payload && payload.screen_inventory,
+    payload && payload.screenList,
+    payload && payload.screen_list,
+  ].filter(Array.isArray);
+  const screens = [];
+  for (const candidateArray of candidateArrays) {
+    for (const item of candidateArray) {
+      const record =
+        typeof item === "string"
+          ? normalizedScreenRecord({ title: item }, relativePath, item)
+          : normalizedScreenRecord(item || {}, relativePath, "");
+      if (record) {
+        screens.push(record);
+      }
+    }
+  }
+  return screens;
+}
+
+function extractScreensFromInventoryMarkdown(inventoryPath, relativePath) {
+  const lines = fs.readFileSync(inventoryPath, "utf-8").split(/\r?\n/);
+  const screens = [];
+  for (const line of lines) {
+    const headingMatch = line.match(/^###\s+(.+?)\s*$/);
+    if (headingMatch) {
+      const record = normalizedScreenRecord({ title: headingMatch[1] }, relativePath, headingMatch[1]);
+      if (record) screens.push(record);
+      continue;
+    }
+    const listMatch = line.match(/^\s*-\s+(.+?)\s*$/);
+    if (listMatch) {
+      const candidate = listMatch[1].replace(/`/g, "").trim();
+      if (!candidate || candidate.includes(":")) {
+        continue;
+      }
+      const record = normalizedScreenRecord({ title: candidate }, relativePath, candidate);
+      if (record) screens.push(record);
+    }
+  }
+  return screens;
+}
+
+function dedupeScreens(screens) {
+  const byId = new Map();
+  for (const screen of screens) {
+    if (!screen || !screen.screenId) {
+      continue;
+    }
+    if (!byId.has(screen.screenId)) {
+      byId.set(screen.screenId, screen);
+      continue;
+    }
+    const existing = byId.get(screen.screenId);
+    const existingScore = (existing.route ? 1 : 0) + (existing.purpose ? 1 : 0) + (existing.primaryAction ? 1 : 0) + existing.majorSections.length + existing.requiredStates.length;
+    const newScore = (screen.route ? 1 : 0) + (screen.purpose ? 1 : 0) + (screen.primaryAction ? 1 : 0) + screen.majorSections.length + screen.requiredStates.length;
+    if (newScore > existingScore) {
+      byId.set(screen.screenId, screen);
+    }
+  }
+  return Array.from(byId.values());
+}
+
+function buildInputContractState({
+  fromSpecPath,
+  projectPath,
+  designBriefPath,
+  referenceDir,
+  profile,
+}) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  const resolvedSpecPath = resolveProjectPath(fromSpecPath || resolvedProjectPath);
+  if (!fs.existsSync(resolvedSpecPath) || !fs.statSync(resolvedSpecPath).isDirectory()) {
+    throw new ValidationError(`--from-spec is not a valid directory: ${resolvedSpecPath}. No project files were changed.`);
+  }
+
+  const selectedProfile = resolveProfile(profile);
+
+  const artifactRules = [
+    { key: "designHandoff", relativeDir: "docs/design", pattern: /^SPEC_TO_DESIGN_HANDOFF_.*\.json$/i, blocker: "NEEDS_DESIGN_HANDOFF" },
+    { key: "screenInventory", relativeDir: "docs/design", pattern: /^SCREEN_INVENTORY_.*\.md$/i, blocker: null },
+    { key: "userFlows", relativeDir: "docs/design", pattern: /^USER_FLOWS_.*\.md$/i, blocker: "NEEDS_USER_FLOWS" },
+    { key: "domainModel", relativeDir: "docs/specs", pattern: /^DOMAIN_MODEL_.*\.md$/i, blocker: "NEEDS_DOMAIN_MODEL" },
+    { key: "archDesign", relativeDir: "docs/architecture", pattern: /^ARCH_DESIGN_.*\.md$/i, blocker: null },
+    { key: "baSpec", relativeDir: "docs/specs", pattern: /^BA_SPEC_.*\.md$/i, blocker: null },
+  ];
+
+  const artifacts = {};
+  for (const rule of artifactRules) {
+    artifacts[rule.key] = findArtifactByPattern(resolvedSpecPath, rule.relativeDir, rule.pattern);
+  }
+
+  let explicitDesignBrief = null;
+  if (designBriefPath) {
+    const absoluteDesignBrief = path.resolve(resolvedProjectPath, designBriefPath);
+    if (!fs.existsSync(absoluteDesignBrief) || !fs.statSync(absoluteDesignBrief).isFile()) {
+      throw new ValidationError(`--design-brief is not a valid file: ${absoluteDesignBrief}. No project files were changed.`);
+    }
+    explicitDesignBrief = {
+      absolutePath: absoluteDesignBrief,
+      relativeToProject: toPosixRelative(resolvedProjectPath, absoluteDesignBrief),
+    };
+  }
+
+  const reference = resolveReferenceDirectory(referenceDir, resolvedProjectPath);
+  const parsedScreens = [];
+  if (artifacts.designHandoff) {
+    parsedScreens.push(
+      ...extractScreensFromHandoffJson(artifacts.designHandoff.absolutePath, artifacts.designHandoff.relativePath)
+    );
+  }
+  if (artifacts.screenInventory) {
+    parsedScreens.push(
+      ...extractScreensFromInventoryMarkdown(artifacts.screenInventory.absolutePath, artifacts.screenInventory.relativePath)
+    );
+  }
+  const screens = dedupeScreens(parsedScreens);
+
+  const blockers = artifactRules.filter((rule) => rule.blocker && !artifacts[rule.key]).map((rule) => rule.blocker);
+  if (screens.length === 0) {
+    blockers.push("NEEDS_SCREEN_INVENTORY");
+  }
+  const analysisStatus = blockers.length === 0 ? "INPUT_CONTRACT_READY" : "INPUT_CONTRACT_BLOCKED";
+
+  const artifactSummary = {};
+  for (const rule of artifactRules) {
+    const value = artifacts[rule.key];
+    artifactSummary[rule.key] = value
+      ? {
+          found: true,
+          relativeToSpecRoot: value.relativePath,
+          absolutePath: value.absolutePath,
+        }
+      : {
+          found: false,
+          relativeToSpecRoot: null,
+          absolutePath: null,
+        };
+  }
+
+  return {
+    schema: "sdtk.design.input-contract.v1",
+    mode: "from-spec",
+    projectPath: resolvedProjectPath,
+    fromSpecPath: resolvedSpecPath,
+    profileSelection: selectedProfile ? selectedProfile.name : null,
+    profilePrimitives: selectedProfile
+      ? {
+          name: selectedProfile.name,
+          summary: selectedProfile.summary,
+          primitives: selectedProfile.primitives,
+          screenRoleHints: selectedProfile.screenRoleHints,
+        }
+      : null,
+    explicitDesignBrief,
+    referenceDirectory: {
+      provided: reference.provided,
+      status: reference.status,
+      absolutePath: reference.absolutePath,
+    },
+    referenceMap: reference.provided
+      ? mapReferenceFiles({ referenceDir: reference.absolutePath, screens })
+      : { totalFiles: 0, mappedCount: 0, unmappedCount: 0, entries: [] },
+    artifacts: artifactSummary,
+    screenModel: {
+      totalScreens: screens.length,
+      missingMetadataCount: screens.filter(
+        (screen) =>
+          !screen.route ||
+          !screen.purpose ||
+          !screen.userIntent ||
+          screen.sections.length === 0 ||
+          screen.requiredComponents.length === 0 ||
+          screen.requiredStates.length === 0 ||
+          screen.interactions.length === 0 ||
+          screen.dataSlots.length === 0 ||
+          screen.acceptanceCriteria.length === 0
+      ).length,
+      legacyFallbackUsed: false,
+      readiness: screens.length > 0 ? "MULTI_SCREEN_READY" : "NEEDS_EXPLICIT_SCREEN_INPUT",
+      screens,
+    },
+    blockers,
+    analysisStatus,
+    nextRecommendedCommand:
+      blockers.length > 0 ? "Provide missing explicit SPEC/design artifacts and re-run sdtk-design start --from-spec." : "sdtk-design prototype",
+  };
+}
+
+module.exports = {
+  buildInputContractState,
+  writeInputContractState,
+};