ai-delivery-workflow 0.2.2

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/viewer/server.mjs

@@ -0,0 +1,780 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const viewerRoot = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const vendoredYaml = path.join(viewerRoot, "..", "state", "vendor", "yaml", "dist", "index.js");
+const yaml = require(fs.existsSync(vendoredYaml) ? vendoredYaml : "yaml");
+const publicRoot = path.join(viewerRoot, "public");
+const defaultProjectRoot = path.resolve(viewerRoot, "..", "..", "..");
+const MAX_PREVIEW_BYTES = 2 * 1024 * 1024;
+const MAX_SCAN_FILES = 10_000;
+const TEXT_EXTENSIONS = new Set([
+  ".csv", ".html", ".ini", ".json", ".jsonl", ".md", ".mdx", ".properties",
+  ".rst", ".toml", ".txt", ".xml", ".yaml", ".yml",
+]);
+const IMAGE_EXTENSIONS = new Set([".gif", ".jpeg", ".jpg", ".png", ".webp"]);
+
+const DEVELOPMENT_NODE_DEFINITIONS = [
+  ["00-bootstrap", "引导"],
+  ["01-product-discovery", "产品发现"],
+  ["02-product-definition", "产品定义"],
+  ["03-architecture-initial", "初始架构"],
+  ["04-experience-design", "体验设计"],
+  ["05-architecture-reconcile", "架构校准"],
+  ["06-platform-preparation", "平台准备"],
+  ["07-iteration-planning", "迭代规划"],
+  ["08-test-design", "测试设计"],
+  ["09-development", "开发实现"],
+  ["10-change-review", "变更审查"],
+  ["11-candidate-verification", "候选验证"],
+  ["12-version-closeout", "版本收尾"],
+].map(([id, label], sequence) => ({ id, label, sequence, group: "development" }));
+
+const RELEASE_NODE_DEFINITIONS = [
+  ["R00-release-request", "发布请求"],
+  ["R01-version-selection", "版本选择"],
+  ["R02-release-eligibility", "发布资格"],
+  ["R03-material-aggregation", "物料整合"],
+  ["R04-release-candidate", "发布候选"],
+  ["R05-release-verification", "发布验证"],
+  ["R06-release-preparation", "发布准备"],
+  ["R07-production-approval", "生产审批"],
+  ["R08-production-deployment", "生产部署"],
+  ["R09-production-verification", "生产验证"],
+  ["R10-release-archive", "发布归档"],
+].map(([id, label], sequence) => ({ id, label, sequence, group: "release" }));
+
+const LEGACY_NODE_DEFINITIONS = [
+  ["12-release-preparation", "历史发布准备"],
+  ["13-production-approval", "历史生产审批"],
+  ["14-production-deployment", "历史生产部署"],
+  ["15-production-verification", "历史生产验证"],
+  ["16-version-archive", "历史版本归档"],
+].map(([id, label], sequence) => ({ id, label, sequence, group: "legacy" }));
+
+const NODE_DEFINITIONS = [
+  ...DEVELOPMENT_NODE_DEFINITIONS,
+  ...RELEASE_NODE_DEFINITIONS,
+  ...LEGACY_NODE_DEFINITIONS,
+];
+
+const NODE_ALIASES = new Map([
+  ["bootstrap", "00-bootstrap"],
+  ["product-discovery", "01-product-discovery"],
+  ["product", "02-product-definition"],
+  ["product-definition", "02-product-definition"],
+  ["architecture-initial", "03-architecture-initial"],
+  ["experience", "04-experience-design"],
+  ["experience-design", "04-experience-design"],
+  ["architecture", "05-architecture-reconcile"],
+  ["architecture-reconcile", "05-architecture-reconcile"],
+  ["platform-preparation", "06-platform-preparation"],
+  ["iteration-planning", "07-iteration-planning"],
+  ["planning", "07-iteration-planning"],
+  ["test-design", "08-test-design"],
+  ["development", "09-development"],
+  ["change-review", "10-change-review"],
+  ["review", "10-change-review"],
+  ["candidate-verification", "11-candidate-verification"],
+  ["version-closeout", "12-version-closeout"],
+  ["release-request", "R00-release-request"],
+  ["version-selection", "R01-version-selection"],
+  ["release-eligibility", "R02-release-eligibility"],
+  ["material-aggregation", "R03-material-aggregation"],
+  ["release-candidate", "R04-release-candidate"],
+  ["release-verification", "R05-release-verification"],
+  ["R06-release-preparation", "R06-release-preparation"],
+  ["R07-production-approval", "R07-production-approval"],
+  ["R08-production-deployment", "R08-production-deployment"],
+  ["R09-production-verification", "R09-production-verification"],
+  ["release-archive", "R10-release-archive"],
+  ["release-preparation", "12-release-preparation"],
+  ["production-approval", "13-production-approval"],
+  ["production-deployment", "14-production-deployment"],
+  ["production-verification", "15-production-verification"],
+  ["version-archive", "16-version-archive"],
+  ["standards", "standards"],
+  ["delivery", "governance"],
+]);
+
+const STATUS_META = {
+  approved: { label: "已批准", tone: "success" },
+  valid: { label: "有效", tone: "success" },
+  frozen: { label: "已冻结", tone: "success" },
+  immutable: { label: "不可变", tone: "success" },
+  deployed: { label: "已部署", tone: "success" },
+  released: { label: "已发布", tone: "success" },
+  "release-ready": { label: "待发布", tone: "success" },
+  "included-in-release": { label: "已纳入发布", tone: "success" },
+  completed: { label: "已完成", tone: "success" },
+  passed: { label: "已通过", tone: "success" },
+  ready: { label: "已就绪", tone: "success" },
+  draft: { label: "草稿", tone: "neutral" },
+  "review-draft": { label: "审阅草稿", tone: "neutral" },
+  planned: { label: "已规划", tone: "neutral" },
+  queued: { label: "待执行", tone: "neutral" },
+  pending: { label: "待确认", tone: "warning" },
+  "pending-approval": { label: "待批准", tone: "warning" },
+  "pending-review": { label: "待审阅", tone: "warning" },
+  running: { label: "进行中", tone: "warning" },
+  observed: { label: "已观察", tone: "neutral" },
+  proposed: { label: "已提案", tone: "warning" },
+  trial: { label: "试运行", tone: "warning" },
+  active: { label: "已启用", tone: "success" },
+  disabled: { label: "已禁用", tone: "warning" },
+  rejected: { label: "已拒绝", tone: "danger" },
+  expired: { label: "已失效", tone: "neutral" },
+  checkpointed: { label: "已检查点", tone: "warning" },
+  stale: { label: "已过期", tone: "warning" },
+  "rolled-back": { label: "已回滚", tone: "warning" },
+  superseded: { label: "已替代", tone: "neutral" },
+  archived: { label: "已归档", tone: "success" },
+  changed: { label: "已变更", tone: "warning" },
+  blocked: { label: "已阻塞", tone: "danger" },
+  invalid: { label: "无效", tone: "danger" },
+  failed: { label: "失败", tone: "danger" },
+  missing: { label: "缺失", tone: "danger" },
+  abandoned: { label: "已放弃", tone: "danger" },
+  unknown: { label: "未标记", tone: "muted" },
+};
+
+function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+function parseArguments(argv) {
+  const readValue = (flag, fallback) => {
+    const index = argv.indexOf(flag);
+    return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+  };
+  const port = Number(readValue("--port", process.env.AI_DELIVERY_VIEWER_PORT || "4173"));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${port}`);
+  }
+  return {
+    host: readValue("--host", process.env.AI_DELIVERY_VIEWER_HOST || "127.0.0.1"),
+    port,
+    projectRoot: path.resolve(readValue("--project", defaultProjectRoot)),
+    open: !argv.includes("--no-open"),
+  };
+}
+
+function isInside(candidate, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function readText(file, limit = MAX_PREVIEW_BYTES) {
+  const stat = fs.statSync(file);
+  if (stat.size > limit) return null;
+  return fs.readFileSync(file, "utf8");
+}
+
+function scalar(text, keys) {
+  if (!text) return null;
+  for (const key of keys) {
+    const expression = new RegExp(`^\\s*${key}\\s*:\\s*[\"']?([^\\r\\n#\"']+)`, "im");
+    const match = text.match(expression);
+    if (match?.[1]?.trim()) return match[1].trim();
+  }
+  return null;
+}
+
+function structuredData(text, extension) {
+  if (!text) return null;
+  try {
+    if (extension === ".yaml" || extension === ".yml") return yaml.parse(text);
+    if (extension === ".json") return JSON.parse(text);
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function normalizeStatus(value, changed) {
+  if (changed) return { key: "changed", ...STATUS_META.changed };
+  const raw = String(value || "").trim().toLowerCase().replaceAll("_", "-");
+  const aliases = {
+    accepted: "valid",
+    "changes-required": "invalid",
+    pass: "passed",
+    success: "completed",
+  };
+  const key = STATUS_META[raw] ? raw : aliases[raw] || "unknown";
+  return { key, ...STATUS_META[key] };
+}
+
+function fileType(extension) {
+  const types = {
+    ".md": "Markdown", ".mdx": "Markdown", ".csv": "CSV", ".yaml": "YAML",
+    ".yml": "YAML", ".json": "JSON", ".jsonl": "JSONL", ".html": "原型",
+    ".png": "图片", ".jpg": "图片", ".jpeg": "图片", ".webp": "图片",
+    ".pdf": "PDF", ".txt": "文本", ".toml": "TOML",
+  };
+  return types[extension] || (extension ? extension.slice(1).toUpperCase() : "文件");
+}
+
+function titleFor(relativePath, text) {
+  const extension = path.extname(relativePath).toLowerCase();
+  if (extension === ".md" || extension === ".mdx") {
+    const heading = text?.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    if (heading) return heading;
+  }
+  return scalar(text, ["title", "name", "artifact_id", "baseline_id", "release_id"])
+    || path.basename(relativePath);
+}
+
+function normalizeNode(value) {
+  if (!value) return null;
+  if (NODE_DEFINITIONS.some((node) => node.id === value)) return value;
+  if (value === "00-governance") return "governance";
+  const withoutSequence = value.replace(/^\d{2}-/, "");
+  return NODE_ALIASES.get(value) || NODE_ALIASES.get(withoutSequence) || value;
+}
+
+function nodeFor(relativePath, text) {
+  const parts = relativePath.split("/");
+  if (parts[1] === "iterations" && parts[3]) {
+    return normalizeNode(parts[3]);
+  }
+  if (parts[1] === "releases" && parts[3]) {
+    return normalizeNode(parts[3]);
+  }
+  if (parts[1] === "product") return "02-product-definition";
+  if (parts[1] === "architecture") return "05-architecture-reconcile";
+  if (parts[1] === "experience") return "04-experience-design";
+  if (parts[1] === "standards") return "standards";
+  if (parts[1] === "evolution" || parts[1] === "extensions") return "evolution";
+  if (parts[1] === "delivery") {
+    if (parts[2] === "bootstrap") return "00-bootstrap";
+    if (parts[2] === "runtime" && parts.includes("archive")) return "16-version-archive";
+    return "governance";
+  }
+  const declared = scalar(text, ["node", "node_id", "stage"]);
+  return normalizeNode(declared) || "unassigned";
+}
+
+function releaseFor(relativePath, text) {
+  const parts = relativePath.split("/");
+  if (parts[1] === "releases" && parts[2]) return parts[2];
+  return scalar(text, ["release_id"]) || null;
+}
+
+function iterationFor(relativePath, text) {
+  const parts = relativePath.split("/");
+  if (parts[1] === "iterations" && parts[2]) return parts[2];
+  return scalar(text, ["iteration_id", "current_iteration_id"]) || null;
+}
+
+function gitChanges(projectRoot) {
+  const result = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all", "--", ".workflow"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) return new Map();
+  const changes = new Map();
+  for (const line of result.stdout.split(/\r?\n/).filter(Boolean)) {
+    const code = line.slice(0, 2).trim() || "M";
+    let file = line.slice(3).trim();
+    if (file.includes(" -> ")) file = file.split(" -> ").at(-1);
+    file = file.replace(/^"|"$/g, "").replaceAll("\\", "/");
+    changes.set(file, code);
+  }
+  return changes;
+}
+
+function repositoryStatus(repositoryRoot, tagPattern) {
+  const run = (args) => spawnSync("git", args, {
+    cwd: repositoryRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  const top = run(["rev-parse", "--show-toplevel"]);
+  if (top.status !== 0 || path.resolve(top.stdout.trim()).toLowerCase() !== path.resolve(repositoryRoot).toLowerCase()) {
+    return { repository: false, root: toPosix(repositoryRoot), tags: [] };
+  }
+  const branch = run(["branch", "--show-current"]);
+  const head = run(["rev-parse", "HEAD"]);
+  const status = run(["status", "--porcelain=v1", "--untracked-files=all"]);
+  const upstream = run(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+  let ahead = null;
+  let behind = null;
+  if (upstream.status === 0) {
+    const divergence = run(["rev-list", "--left-right", "--count", "HEAD...@{upstream}"]);
+    if (divergence.status === 0) [ahead, behind] = divergence.stdout.trim().split(/\s+/).map(Number);
+  }
+  const dirtyPaths = status.stdout.split(/\r?\n/).filter(Boolean).map((line) => toPosix(line.slice(3)));
+  const tags = run(["tag", "--list", tagPattern, "--sort=version:refname"]);
+  return {
+    repository: true,
+    root: toPosix(repositoryRoot),
+    branch: branch.stdout.trim() || "main",
+    head: head.status === 0 ? head.stdout.trim() : null,
+    dirty_paths: dirtyPaths,
+    upstream: upstream.status === 0 ? upstream.stdout.trim() : null,
+    ahead,
+    behind,
+    sync_status: dirtyPaths.length ? "uncommitted"
+      : ahead > 0 ? "unpushed"
+        : behind > 0 ? "behind"
+          : upstream.status === 0 ? "synchronized" : "no-upstream",
+    tags: tags.status === 0 ? tags.stdout.split(/\r?\n/).filter(Boolean) : [],
+  };
+}
+
+function workspaceStatus(projectRoot) {
+  const configFile = path.join(projectRoot, ".workflow", "config", "workspace.yaml");
+  let configuration = null;
+  try {
+    configuration = yaml.parse(fs.readFileSync(configFile, "utf8"));
+  } catch {
+    configuration = { code_repository: { repo_id: "app", path: "code" } };
+  }
+  const codePath = configuration?.code_repository?.path || "code";
+  const codeRoot = path.resolve(projectRoot, codePath);
+  const relative = path.relative(projectRoot, codeRoot);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Invalid code repository path in workspace configuration: ${codePath}`);
+  }
+  const tasksRoot = path.join(projectRoot, ".workflow", "control", "tasks");
+  const checkpointsRoot = path.join(projectRoot, ".workflow", "control", "checkpoints");
+  const taskFiles = fs.existsSync(tasksRoot)
+    ? fs.readdirSync(tasksRoot).filter((name) => /\.(json|ya?ml)$/i.test(name)) : [];
+  const checkpointFiles = [];
+  const visit = (directory) => {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && /\.(json|ya?ml)$/i.test(entry.name)) checkpointFiles.push(absolute);
+    }
+  };
+  visit(checkpointsRoot);
+  return {
+    configuration,
+    workflow_git: repositoryStatus(projectRoot, "workflow-ready/*"),
+    code_git: repositoryStatus(codeRoot, "version-ready/*"),
+    shared_state: {
+      task_count: taskFiles.length,
+      checkpoint_count: checkpointFiles.length,
+      latest_checkpoint: checkpointFiles
+        .map((file) => ({ path: toPosix(path.relative(projectRoot, file)), mtime: fs.statSync(file).mtimeMs }))
+        .sort((left, right) => right.mtime - left.mtime)[0]?.path || null,
+    },
+  };
+}
+
+function walkWorkflow(workflowRoot) {
+  const files = [];
+  let truncated = false;
+  const visit = (directory) => {
+    if (truncated) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (files.length >= MAX_SCAN_FILES) {
+        truncated = true;
+        break;
+      }
+      const absolute = path.join(directory, entry.name);
+      const relativeParts = path.relative(workflowRoot, absolute).split(path.sep);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory() && (
+        relativeParts[0] === "tools"
+        || (relativeParts[0] === "delivery" && relativeParts[1] === "runtime")
+      )) continue;
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile() && entry.name !== ".gitkeep") files.push(absolute);
+    }
+  };
+  if (fs.existsSync(workflowRoot)) visit(workflowRoot);
+  return { files, truncated };
+}
+
+function referencesFor(relativePath, text, knownPaths) {
+  if (!text) return [];
+  const references = new Set();
+  const tokens = text.match(/(?:\.workflow\/|(?:\.\.\/|\.\/)+)[A-Za-z0-9._/@-]+/g) || [];
+  for (const token of tokens) {
+    const cleaned = token.replace(/[),.;:'"]+$/g, "");
+    const resolved = cleaned.startsWith(".workflow/")
+      ? cleaned
+      : toPosix(path.normalize(path.join(path.dirname(relativePath), cleaned)));
+    if (knownPaths.has(resolved)) references.add(resolved);
+  }
+  return [...references].sort();
+}
+
+function artifactRegistry(workflowRoot) {
+  const registryFile = path.join(workflowRoot, "delivery", "artifact-registry.yaml");
+  if (!fs.existsSync(registryFile)) return new Map();
+  try {
+    const parsed = yaml.parse(fs.readFileSync(registryFile, "utf8"));
+    const entries = Array.isArray(parsed?.artifacts) ? parsed.artifacts : [];
+    return new Map(entries
+      .filter((artifact) => artifact && typeof artifact.path === "string")
+      .map((artifact) => [artifact.path.replaceAll("\\", "/"), artifact]));
+  } catch {
+    return new Map();
+  }
+}
+
+function evolutionSummary(workflowRoot) {
+  const indexFile = path.join(workflowRoot, "evolution", "index.yaml");
+  const empty = {
+    schema_version: 1, revision: 0, feedback_count: 0, proposal_count: 0,
+    trial_count: 0, active_count: 0, high_risk_count: 0, rollback_count: 0,
+    hook_result_count: 0, updated_at: null,
+  };
+  if (!fs.existsSync(indexFile)) return empty;
+  try {
+    const index = yaml.parse(fs.readFileSync(indexFile, "utf8")) || {};
+    const extensions = Array.isArray(index.extensions) ? index.extensions : [];
+    const hookRoot = path.join(workflowRoot, "evolution", "experiments", "hook-results");
+    return {
+      schema_version: index.schema_version || 1,
+      revision: index.revision || 0,
+      feedback_count: Array.isArray(index.feedback) ? index.feedback.length : 0,
+      proposal_count: Array.isArray(index.proposals) ? index.proposals.filter((item) => item.status === "proposed").length : 0,
+      trial_count: extensions.filter((item) => item.state === "trial").length,
+      active_count: extensions.filter((item) => item.state === "active").length,
+      high_risk_count: extensions.filter((item) => item.effective_risk === "high" && ["trial", "active"].includes(item.state)).length,
+      rollback_count: extensions.filter((item) => item.state === "rolled-back").length,
+      hook_result_count: fs.existsSync(hookRoot)
+        ? fs.readdirSync(hookRoot, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name !== ".gitkeep").length
+        : 0,
+      updated_at: index.updated_at || null,
+    };
+  } catch {
+    return { ...empty, invalid: true };
+  }
+}
+
+export function buildCatalog(projectRoot) {
+  const workflowRoot = path.join(projectRoot, ".workflow");
+  const { files, truncated } = walkWorkflow(workflowRoot);
+  const changes = gitChanges(projectRoot);
+  const registeredArtifacts = artifactRegistry(workflowRoot);
+  const prepared = files.map((absolute) => {
+    const relativePath = toPosix(path.relative(projectRoot, absolute));
+    const extension = path.extname(absolute).toLowerCase();
+    const stat = fs.statSync(absolute);
+    const text = TEXT_EXTENSIONS.has(extension) ? readText(absolute) : null;
+    const data = structuredData(text, extension);
+    const changedCode = changes.get(relativePath) || null;
+    const registered = registeredArtifacts.get(relativePath);
+    const declaredStatus = registered?.status
+      || scalar(text, ["status", "decision", "version_status", "state"]);
+    const status = normalizeStatus(declaredStatus, Boolean(changedCode));
+    return {
+      path: relativePath,
+      title: titleFor(relativePath, text),
+      file_name: path.basename(relativePath),
+      extension,
+      type: fileType(extension),
+      node_id: normalizeNode(registered?.node) || nodeFor(relativePath, text),
+      iteration_id: iterationFor(relativePath, text),
+      release_id: releaseFor(relativePath, text),
+      release_mode: data?.mode || scalar(text, ["mode"]) || null,
+      target_version_id: data?.target_version || data?.target_version_id
+        || scalar(text, ["target_version", "target_version_id"]) || null,
+      current_production_version: data?.current_production_version
+        || scalar(text, ["current_production_version"]) || null,
+      newly_included_versions: Array.isArray(data?.newly_included_versions)
+        ? data.newly_included_versions.map(String) : [],
+      status,
+      declared_status: declaredStatus,
+      version: registered?.version
+        || scalar(text, ["version", "artifact_version", "schema_version"]) || null,
+      artifact_id: registered?.artifact_id || registered?.id
+        || scalar(text, ["artifact_id", "baseline_id", "release_id", "deployment_id"]) || null,
+      standards: [...new Set(text?.match(/STD-[A-Z0-9-]+/g) || [])].sort(),
+      modified_at: stat.mtime.toISOString(),
+      size_bytes: stat.size,
+      checksum: crypto.createHash("sha256").update(fs.readFileSync(absolute)).digest("hex"),
+      git_status: changedCode,
+      preview_kind: TEXT_EXTENSIONS.has(extension) && stat.size <= MAX_PREVIEW_BYTES
+        ? "text"
+        : IMAGE_EXTENSIONS.has(extension) ? "image" : "none",
+      previewable: (TEXT_EXTENSIONS.has(extension) && stat.size <= MAX_PREVIEW_BYTES)
+        || IMAGE_EXTENSIONS.has(extension),
+      _text: text,
+    };
+  });
+  const knownPaths = new Set(prepared.map((item) => item.path));
+  const inbound = new Map(prepared.map((item) => [item.path, []]));
+  for (const item of prepared) {
+    item.outbound = referencesFor(item.path, item._text, knownPaths);
+    for (const target of item.outbound) inbound.get(target)?.push(item.path);
+  }
+  for (const item of prepared) {
+    item.inbound = (inbound.get(item.path) || []).sort();
+    delete item._text;
+  }
+  prepared.sort((left, right) =>
+    left.node_id.localeCompare(right.node_id)
+    || right.modified_at.localeCompare(left.modified_at)
+    || left.path.localeCompare(right.path));
+
+  const projectText = fs.existsSync(path.join(workflowRoot, "delivery", "project.yaml"))
+    ? readText(path.join(workflowRoot, "delivery", "project.yaml"))
+    : "";
+  const workflowText = fs.existsSync(path.join(workflowRoot, "delivery", "workflow-state.yaml"))
+    ? readText(path.join(workflowRoot, "delivery", "workflow-state.yaml"))
+    : "";
+  const formalState = structuredData(workflowText, ".yaml") || {};
+  const currentIteration = formalState.development_state?.scope_id
+    || scalar(workflowText, ["iteration_id"])
+    || scalar(projectText, ["current_iteration_id"])
+    || prepared.map((item) => item.iteration_id).filter(Boolean).sort().at(-1)
+    || null;
+  const iterations = [...new Set([
+    ...(currentIteration ? [currentIteration] : []),
+    ...prepared.map((item) => item.iteration_id).filter(Boolean),
+  ])].sort().reverse();
+  const releaseNodeIds = new Set(RELEASE_NODE_DEFINITIONS.map((node) => node.id));
+  const releaseDocuments = prepared.filter((item) => item.release_id && releaseNodeIds.has(item.node_id))
+    .sort((left, right) => right.modified_at.localeCompare(left.modified_at));
+  const activeReleaseId = formalState.release_state?.scope_id
+    || releaseDocuments[0]?.release_id
+    || null;
+  const activeReleaseDocuments = releaseDocuments.filter((item) => item.release_id === activeReleaseId);
+  const releaseSelection = activeReleaseDocuments.find((item) => item.node_id === "R01-version-selection")
+    || activeReleaseDocuments.find((item) => item.target_version_id)
+    || null;
+  const releases = [...new Set(releaseDocuments.map((item) => item.release_id))];
+  const nodes = [
+    { id: "governance", label: "流程治理", sequence: -2, group: "governance" },
+    { id: "standards", label: "项目规范", sequence: -1, group: "governance" },
+    { id: "evolution", label: "自进化", sequence: 0, group: "governance" },
+    ...NODE_DEFINITIONS,
+  ].map((node) => {
+    const documents = prepared.filter((item) => {
+      if (item.node_id !== node.id) return false;
+      if (node.group === "development") {
+        return !currentIteration || !item.iteration_id || item.iteration_id === currentIteration;
+      }
+      if (node.group === "release") return !activeReleaseId || item.release_id === activeReleaseId;
+      return true;
+    });
+    const tones = documents.map((item) => item.status.tone);
+    const tone = tones.includes("danger") ? "danger"
+      : tones.includes("warning") ? "warning"
+        : tones.includes("success") ? "success" : "muted";
+    return { ...node, document_count: documents.length, tone };
+  });
+  const counts = Object.fromEntries(["success", "warning", "danger", "neutral", "muted"]
+    .map((tone) => [tone, prepared.filter((item) => item.status.tone === tone).length]));
+  const workspace = workspaceStatus(projectRoot);
+  const traceability = prepared.filter((item) => item.node_id === "12-version-closeout")
+    .map((item) => ({
+      version_id: item.iteration_id || item.artifact_id,
+      manifest_path: item.path,
+      manifest_sha256: item.checksum,
+      code_tag: scalar(fs.readFileSync(path.join(projectRoot, item.path), "utf8"), ["code_tag", "version_ready_tag"]),
+      workflow_tag: scalar(fs.readFileSync(path.join(projectRoot, item.path), "utf8"), ["workflow_tag", "workflow_ready_tag"]),
+    }))
+    .filter((item) => item.code_tag || item.workflow_tag);
+  return {
+    schema_version: 1,
+    scanned_at: new Date().toISOString(),
+    project: {
+      id: scalar(projectText, ["project_id"]) || path.basename(projectRoot),
+      name: scalar(projectText, ["name", "project_name"]) || path.basename(projectRoot),
+      root: toPosix(projectRoot),
+      workflow_root: ".workflow",
+      current_iteration_id: currentIteration,
+      production_version_id: scalar(workflowText, ["production_version_id"])
+        || scalar(projectText, ["production_version_id"]) || null,
+      production_release_id: scalar(workflowText, ["production_release_id"])
+        || scalar(projectText, ["production_release_id"]) || null,
+      latest_line_version_id: scalar(workflowText, ["latest_line_version_id"])
+        || scalar(projectText, ["latest_line_version_id"]) || null,
+      release_ready_count: new Set(prepared
+        .filter((item) => item.node_id === "12-version-closeout" && item.status.key === "release-ready")
+        .map((item) => item.iteration_id || item.artifact_id || item.path)).size,
+      active_release_id: activeReleaseId,
+      selected_target_version: releaseSelection?.target_version_id || null,
+      release_mode: releaseSelection?.release_mode || null,
+      newly_included_versions: releaseSelection?.newly_included_versions || [],
+    },
+    iterations,
+    releases,
+    nodes,
+    documents: prepared,
+    counts,
+    repositories: {
+      workflow: workspace.workflow_git,
+      code: workspace.code_git,
+      code_repo_id: workspace.configuration?.code_repository?.repo_id || "app",
+    },
+    shared_state: workspace.shared_state,
+    traceability,
+    evolution: evolutionSummary(workflowRoot),
+    truncated,
+  };
+}
+
+function sendJson(response, status, value) {
+  const body = `${JSON.stringify(value)}\n`;
+  response.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+    "Content-Length": Buffer.byteLength(body),
+  });
+  response.end(body);
+}
+
+function serveStatic(response, pathname) {
+  const relative = pathname === "/" ? "index.html" : pathname.slice(1);
+  const file = path.resolve(publicRoot, relative);
+  if (!isInside(file, publicRoot) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    sendJson(response, 404, { error: "Not found" });
+    return;
+  }
+  const types = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+  };
+  const body = fs.readFileSync(file);
+  response.writeHead(200, {
+    "Content-Type": types[path.extname(file)] || "application/octet-stream",
+    "Content-Length": body.length,
+    "Cache-Control": "no-cache",
+    "Content-Security-Policy": "default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+  });
+  response.end(body);
+}
+
+export function createViewerServer(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const workflowRoot = path.join(root, ".workflow");
+  return http.createServer((request, response) => {
+    try {
+      const url = new URL(request.url || "/", "http://localhost");
+      if (request.method !== "GET") {
+        sendJson(response, 405, { error: "Method not allowed" });
+        return;
+      }
+      if (url.pathname === "/api/health") {
+        sendJson(response, 200, { ok: true, project_root: toPosix(root) });
+        return;
+      }
+      if (url.pathname === "/api/catalog") {
+        sendJson(response, 200, buildCatalog(root));
+        return;
+      }
+      if (url.pathname === "/api/document") {
+        const requested = url.searchParams.get("path") || "";
+        const absolute = path.resolve(root, requested);
+        if (!requested.startsWith(".workflow/") || !isInside(absolute, workflowRoot)) {
+          sendJson(response, 403, { error: "Only .workflow documents may be read" });
+          return;
+        }
+        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) {
+          sendJson(response, 404, { error: "Document not found" });
+          return;
+        }
+        const stat = fs.statSync(absolute);
+        if (stat.size > MAX_PREVIEW_BYTES) {
+          sendJson(response, 413, { error: "Document is larger than the 2 MiB preview limit" });
+          return;
+        }
+        const extension = path.extname(absolute).toLowerCase();
+        if (!TEXT_EXTENSIONS.has(extension)) {
+          sendJson(response, 415, { error: "This file type has no text preview" });
+          return;
+        }
+        sendJson(response, 200, {
+          path: requested,
+          extension,
+          content: fs.readFileSync(absolute, "utf8"),
+        });
+        return;
+      }
+      if (url.pathname === "/api/file") {
+        const requested = url.searchParams.get("path") || "";
+        const absolute = path.resolve(root, requested);
+        if (!requested.startsWith(".workflow/") || !isInside(absolute, workflowRoot)) {
+          sendJson(response, 403, { error: "Only .workflow files may be read" });
+          return;
+        }
+        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) {
+          sendJson(response, 404, { error: "File not found" });
+          return;
+        }
+        const extension = path.extname(absolute).toLowerCase();
+        if (!IMAGE_EXTENSIONS.has(extension)) {
+          sendJson(response, 415, { error: "Only image previews are served by this endpoint" });
+          return;
+        }
+        const contentTypes = {
+          ".gif": "image/gif",
+          ".jpeg": "image/jpeg",
+          ".jpg": "image/jpeg",
+          ".png": "image/png",
+          ".webp": "image/webp",
+        };
+        const body = fs.readFileSync(absolute);
+        response.writeHead(200, {
+          "Content-Type": contentTypes[extension],
+          "Content-Length": body.length,
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+        });
+        response.end(body);
+        return;
+      }
+      serveStatic(response, url.pathname);
+    } catch (error) {
+      sendJson(response, 500, { error: error.message });
+    }
+  });
+}
+
+function openBrowser(url) {
+  const command = process.platform === "win32"
+    ? ["cmd", ["/c", "start", "", url]]
+    : process.platform === "darwin"
+      ? ["open", [url]]
+      : ["xdg-open", [url]];
+  try {
+    spawn(command[0], command[1], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    }).unref();
+  } catch {
+    // The printed URL remains usable when no desktop browser opener is available.
+  }
+}
+
+if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {
+  try {
+    const options = parseArguments(process.argv.slice(2));
+    if (!fs.existsSync(options.projectRoot) || !fs.statSync(options.projectRoot).isDirectory()) {
+      throw new Error(`Project directory does not exist: ${options.projectRoot}`);
+    }
+    const server = createViewerServer(options.projectRoot);
+    server.listen(options.port, options.host, () => {
+      const url = `http://${options.host}:${options.port}`;
+      process.stdout.write(`AI Delivery Viewer\nProject: ${options.projectRoot}\nURL: ${url}\nPress Ctrl+C to stop.\n`);
+      if (options.open) openBrowser(url);
+    });
+  } catch (error) {
+    process.stderr.write(`ai-delivery-viewer: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}