frontend-project-context 1.0.1 → 1.2.0

package/src/project-context/assist.mjs

@@ -0,0 +1,422 @@
+import { digestJson } from "./canonical-json.mjs";
+import { checkProject } from "./checker.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { reviewSource } from "./maintenance.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+import { effectiveItems, scopeApplies } from "./scope-compiler.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+const LARGE_IMPACT_THRESHOLD = 100;
+export const ASSIST_BUNDLE_SCHEMA_VERSION = 1;
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function snapshots(project) {
+  return {
+    contract: project.contractDigest ?? digestJson(project.contract),
+    sourcesLock: project.sourcesLockDigest ?? digestJson(project.sourcesLock),
+    projectionsLock: project.projectionsLockDigest ?? digestJson(project.projectionsLock),
+  };
+}
+
+function sourceLocator(source) {
+  if (source.kind === "json-pointer") return { path: source.path, pointer: source.pointer };
+  if (LOCAL_SOURCE_KINDS.has(source.kind)) return { path: source.path };
+  return { reference: source.reference };
+}
+
+function sourceTarget(source, reason, priority) {
+  return {
+    sourceId: source.id,
+    kind: source.kind,
+    locator: sourceLocator(source),
+    reason,
+    priority,
+  };
+}
+
+function stableFindings(findings) {
+  const seen = new Set();
+  return findings.filter((finding) => {
+    const key = JSON.stringify(finding);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function setupWorkUnits(proposal) {
+  const factAndReferenceItems = proposal.items
+    .filter((item) => item.kind === "fact" || item.kind === "reference")
+    .map((item) => item.id);
+  const guidanceItems = proposal.items.filter((item) => item.kind === "reference");
+  const units = [];
+  if (factAndReferenceItems.length > 0) {
+    units.push({
+      id: "onboarding-facts",
+      kind: "onboarding-facts",
+      sourceIds: uniqueSorted(proposal.items
+        .filter((item) => factAndReferenceItems.includes(item.id))
+        .flatMap((item) => item.sources)),
+      itemIds: uniqueSorted(factAndReferenceItems),
+    });
+  }
+  if (guidanceItems.length > 0) {
+    units.push({
+      id: "authoritative-guidance",
+      kind: "authoritative-guidance",
+      sourceIds: uniqueSorted(guidanceItems.flatMap((item) => item.sources)),
+      itemIds: uniqueSorted(guidanceItems.map((item) => item.id)),
+    });
+  }
+  return units;
+}
+
+function pendingSourceIds(items) {
+  return uniqueSorted(items.flatMap((item) => [
+    ...item.sources,
+    ...(item.verification?.source ? [item.verification.source] : []),
+  ]));
+}
+
+function pendingReviewUnit(items) {
+  return {
+    id: "pending-review",
+    kind: "pending-review",
+    sourceIds: pendingSourceIds(items),
+    itemIds: items.map((item) => item.id),
+  };
+}
+
+function mergeReadTargets(targets) {
+  const bySource = new Map();
+  for (const target of targets) {
+    const existing = bySource.get(target.sourceId);
+    if (!existing || target.priority < existing.priority) bySource.set(target.sourceId, target);
+  }
+  return [...bySource.values()].sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+}
+
+export function buildSetupAssistBundle(project, proposal, options = {}) {
+  const guidanceSourceIds = new Set(
+    proposal.items.filter((item) => item.kind === "reference").flatMap((item) => item.sources),
+  );
+  const pending = project.contract.items
+    .filter((item) => item.status === "proposed")
+    .map(pendingItem)
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const sourceById = new Map([
+    ...project.contract.sources.map((source) => [source.id, source]),
+    ...proposal.sources.map((source) => [source.id, source]),
+  ]);
+  const guidanceTargets = [...guidanceSourceIds]
+    .map((id) => sourceById.get(id))
+    .filter(Boolean)
+    .map((source) => sourceTarget(source, "authoritative-guidance", 1));
+  const pendingTargets = pendingSourceIds(pending)
+    .map((id) => sourceById.get(id))
+    .filter((source) => source && sourceStatus(source) === "active" && LOCAL_SOURCE_KINDS.has(source.kind))
+    .map((source) => sourceTarget(source, "pending-review", 2));
+  const workUnits = setupWorkUnits(proposal);
+  if (pending.length > 0) workUnits.push(pendingReviewUnit(pending));
+  return {
+    schemaVersion: ASSIST_BUNDLE_SCHEMA_VERSION,
+    mode: "setup",
+    project: {
+      id: project.contract.project.id,
+      name: project.contract.project.name,
+      initialized: Boolean(options.initialized),
+    },
+    snapshots: snapshots(project),
+    summary: {
+      candidateSources: proposal.sources.length,
+      candidateItems: proposal.items.length,
+      changedSources: 0,
+      affectedItems: 0,
+      pendingItems: pending.length,
+      affectedProjections: 0,
+    },
+    sourceChanges: [],
+    affectedItems: [],
+    pendingItems: pending,
+    pathSignals: [],
+    projectionPaths: [],
+    findings: [],
+    readTargets: mergeReadTargets([...guidanceTargets, ...pendingTargets]),
+    workUnits: workUnits.sort((left, right) => left.id.localeCompare(right.id)),
+    proposal: structuredClone(proposal),
+    artifacts: [{
+      kind: "proposal",
+      path: options.proposalPath ?? ".project-context/setup.proposal.json",
+      action: options.proposalAction ?? "preview",
+      persisted: Boolean(options.proposalPersisted),
+    }],
+  };
+}
+
+function syncPath(value) {
+  try {
+    return normalizeRelativePath(value, { allowRoot: true, label: "changed path" });
+  } catch (error) {
+    fail("sync-path-invalid", `changed path is invalid: ${value}`, {
+      details: { path: value, reason: error.code ?? "invalid-path" },
+    });
+  }
+}
+
+function registeredSourcesForPath(contract, targetPath) {
+  return contract.sources
+    .filter((source) => sourceStatus(source) === "active" && LOCAL_SOURCE_KINDS.has(source.kind))
+    .filter((source) => {
+      if (source.kind === "json-pointer") return targetPath === source.path;
+      return targetPath === source.path || targetPath.startsWith(`${source.path}/`);
+    })
+    .map((source) => source.id)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function pathSignals(contract, changedPaths) {
+  return uniqueSorted(changedPaths.map(syncPath)).map((targetPath) => {
+    const registeredSourceIds = registeredSourcesForPath(contract, targetPath);
+    let approvedItemIds = [];
+    try {
+      approvedItemIds = effectiveItems(contract.items, targetPath).map((item) => item.id);
+    } catch (error) {
+      if (error?.code !== "contract-conflict" && !error?.code?.startsWith("scope-")) throw error;
+      approvedItemIds = contract.items
+        .filter((item) => item.status === "approved" && scopeApplies(item.scope, targetPath))
+        .map((item) => item.id)
+        .sort((left, right) => left.localeCompare(right));
+    }
+    return {
+      path: targetPath,
+      approvedItemIds,
+      registeredSourceIds,
+      classification: registeredSourceIds.length > 0
+        ? "registered-source"
+        : approvedItemIds.length > 0
+          ? "scope-only"
+          : "unrelated",
+    };
+  });
+}
+
+function impactReasonsByItem(reviews) {
+  const byItem = new Map();
+  for (const review of reviews) {
+    if (!["changed", "missing", "unreadable"].includes(review.status)) continue;
+    for (const item of review.impact.items) {
+      if (!byItem.has(item.id)) byItem.set(item.id, []);
+      byItem.get(item.id).push({ sourceId: review.source.id, reasons: uniqueSorted(item.reasons ?? []) });
+    }
+  }
+  for (const impacts of byItem.values()) impacts.sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+  return byItem;
+}
+
+function affectedItem(item, sourceImpacts, largeImpact) {
+  const base = {
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    status: item.status,
+    itemDigest: digestJson(item),
+    sourceImpacts: structuredClone(sourceImpacts),
+  };
+  if (largeImpact) return { ...base, largeImpact: true };
+  return {
+    ...base,
+    value: structuredClone(item.value),
+    statement: item.statement,
+    sources: [...item.sources],
+    overrides: [...item.overrides],
+    ...(item.verification ? { verification: structuredClone(item.verification) } : {}),
+  };
+}
+
+function pendingItem(item) {
+  return {
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    status: item.status,
+    itemDigest: digestJson(item),
+    value: structuredClone(item.value),
+    statement: item.statement,
+    sources: [...item.sources],
+    overrides: [...item.overrides],
+    ...(item.verification ? { verification: structuredClone(item.verification) } : {}),
+  };
+}
+
+function sourceChange(review) {
+  const hasProblem = ["changed", "missing", "unreadable"].includes(review.status);
+  const itemIds = hasProblem ? review.impact.items.map((item) => item.id) : [];
+  const largeImpact = itemIds.length > LARGE_IMPACT_THRESHOLD;
+  return {
+    sourceId: review.source.id,
+    kind: review.source.kind,
+    locator: sourceLocator(review.source),
+    status: review.status,
+    lockedDigest: review.lockedDigest,
+    currentDigest: review.currentDigest,
+    ...(review.reason ? { reason: review.reason } : {}),
+    affectedItemIds: itemIds,
+    itemRelations: hasProblem && !largeImpact
+      ? review.impact.items.map((item) => ({ id: item.id, reasons: uniqueSorted(item.reasons ?? []) }))
+      : [],
+    fallbackItemIds: hasProblem ? review.impact.fallbackItems.map((item) => item.id) : [],
+    directProjectionPaths: hasProblem ? [...review.impact.directProjectionPaths] : [],
+    staleProjectionPaths: hasProblem ? [...review.impact.staleProjectionPaths] : [],
+    ...(largeImpact ? { largeImpact: true } : {}),
+  };
+}
+
+function nonLocalSourceChange(source) {
+  const deprecated = sourceStatus(source) === "deprecated";
+  return {
+    sourceId: source.id,
+    kind: source.kind,
+    locator: sourceLocator(source),
+    status: deprecated ? "deprecated" : "not-local-checkable",
+    lockedDigest: null,
+    currentDigest: null,
+    affectedItemIds: [],
+    itemRelations: [],
+    fallbackItemIds: [],
+    directProjectionPaths: [],
+    staleProjectionPaths: [],
+  };
+}
+
+function syncWorkUnits(problemReviews, signals, findings, pendingItems) {
+  const units = problemReviews.map((review) => ({
+    id: `source-change:${review.source.id}`,
+    kind: "source-change",
+    sourceIds: [review.source.id],
+    itemIds: review.impact.items.map((item) => item.id),
+    fallbackItemIds: review.impact.fallbackItems.map((item) => item.id),
+    projectionPaths: uniqueSorted([
+      ...review.impact.directProjectionPaths,
+      ...review.impact.staleProjectionPaths,
+    ]),
+    ...(review.impact.items.length > LARGE_IMPACT_THRESHOLD ? { largeImpact: true } : {}),
+  }));
+  for (const signal of signals) {
+    units.push({
+      id: `path-signal:${signal.path}`,
+      kind: "path-signal",
+      paths: [signal.path],
+      sourceIds: [...signal.registeredSourceIds],
+      itemIds: [...signal.approvedItemIds],
+    });
+  }
+  if (pendingItems.length > 0) {
+    units.push(pendingReviewUnit(pendingItems));
+  }
+  const projectionFindings = findings.filter((finding) => finding.code.startsWith("projection-") && finding.path);
+  for (const projectionPath of uniqueSorted(projectionFindings.map((finding) => finding.path))) {
+    units.push({
+      id: `projection-review:${projectionPath}`,
+      kind: "projection-review",
+      projectionPaths: [projectionPath],
+      findingCodes: uniqueSorted(projectionFindings
+        .filter((finding) => finding.path === projectionPath)
+        .map((finding) => finding.code)),
+    });
+  }
+  const conflictFindings = findings.filter((finding) =>
+    finding.code.includes("conflict") || finding.code.startsWith("scope-") || finding.code.startsWith("verification-"),
+  );
+  if (conflictFindings.length > 0) {
+    units.push({
+      id: "conflicts",
+      kind: "conflict",
+      findingCodes: uniqueSorted(conflictFindings.map((finding) => finding.code)),
+      itemIds: uniqueSorted(conflictFindings.flatMap((finding) => finding.items ?? (finding.item ? [finding.item] : []))),
+      sourceIds: uniqueSorted(conflictFindings.flatMap((finding) => finding.source ? [finding.source] : [])),
+      paths: uniqueSorted(conflictFindings.flatMap((finding) => finding.path ? [finding.path] : [])),
+    });
+  }
+  return units.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export async function buildSyncAssistBundle(root, project, changedPaths = []) {
+  const reviewResults = await Promise.all(project.contract.sources.map(async (source) => {
+    if (sourceStatus(source) === "deprecated" || !LOCAL_SOURCE_KINDS.has(source.kind)) {
+      return { source, nonLocal: nonLocalSourceChange(source) };
+    }
+    return { source, review: await reviewSource(root, project, source.id) };
+  }));
+  const reviews = reviewResults.filter((entry) => entry.review).map((entry) => entry.review);
+  const problemReviews = reviews.filter((review) => ["changed", "missing", "unreadable"].includes(review.status));
+  const sourceChanges = reviewResults
+    .filter((entry) => !entry.review || entry.review.status !== "unchanged")
+    .map((entry) => entry.review ? sourceChange(entry.review) : entry.nonLocal)
+    .sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+  const sourceImpacts = impactReasonsByItem(problemReviews);
+  const largeImpactIds = new Set(problemReviews
+    .filter((review) => review.impact.items.length > LARGE_IMPACT_THRESHOLD)
+    .flatMap((review) => review.impact.items.map((item) => item.id)));
+  const itemById = new Map(project.contract.items.map((item) => [item.id, item]));
+  const affectedItems = [...sourceImpacts.keys()]
+    .map((id) => affectedItem(itemById.get(id), sourceImpacts.get(id), largeImpactIds.has(id)))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const signals = pathSignals(project.contract, changedPaths);
+  const findings = stableFindings(await checkProject(root, project));
+  const pending = project.contract.items
+    .filter((item) => item.status === "proposed")
+    .map(pendingItem)
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const projectionPaths = uniqueSorted([
+    ...problemReviews.flatMap((review) => [
+      ...review.impact.directProjectionPaths,
+      ...review.impact.staleProjectionPaths,
+    ]),
+    ...findings
+      .filter((finding) => finding.code.startsWith("projection-") && finding.path)
+      .map((finding) => finding.path),
+  ]);
+  const changedTargets = problemReviews
+    .filter((review) => review.status === "changed")
+    .map((review) => sourceTarget(review.source, "source-change", 1));
+  const sourceById = new Map(project.contract.sources.map((source) => [source.id, source]));
+  const pendingTargets = pendingSourceIds(pending)
+    .map((id) => sourceById.get(id))
+    .filter((source) => source && sourceStatus(source) === "active" && LOCAL_SOURCE_KINDS.has(source.kind))
+    .map((source) => sourceTarget(source, "pending-review", 2));
+  const readTargets = mergeReadTargets([...changedTargets, ...pendingTargets]);
+  return {
+    schemaVersion: ASSIST_BUNDLE_SCHEMA_VERSION,
+    mode: "sync",
+    project: {
+      id: project.contract.project.id,
+      name: project.contract.project.name,
+      initialized: true,
+    },
+    snapshots: snapshots(project),
+    summary: {
+      candidateSources: 0,
+      candidateItems: 0,
+      changedSources: problemReviews.length,
+      affectedItems: affectedItems.length,
+      pendingItems: pending.length,
+      affectedProjections: projectionPaths.length,
+    },
+    sourceChanges,
+    affectedItems,
+    pendingItems: pending,
+    pathSignals: signals,
+    projectionPaths,
+    findings,
+    readTargets,
+    workUnits: syncWorkUnits(problemReviews, signals, findings, pending),
+    proposal: null,
+    artifacts: [],
+  };
+}

package/src/project-context/cli.mjs

@@ -1,4 +1,4 @@
-import path from "node:path";
+import { buildSetupAssistBundle, buildSyncAssistBundle } from "./assist.mjs";
 import { approvePendingItems, approveProposal } from "./approver.mjs";
 import { buildItemProposal, registerSource } from "./authoring.mjs";
 import { blockingContextFindings, checkExitCode, checkProject } from "./checker.mjs";
@@ -8,10 +8,12 @@ import { buildDashboardModel } from "./dashboard-model.mjs";
 import { renderDashboardHtml } from "./dashboard-renderer.mjs";
 import { discoverProject } from "./discovery.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
+import { buildCapabilities, preflightActionPlanFile } from "./exchange.mjs";
+import { normalizeProposalPath } from "./exchange-schema.mjs";
 import { atomicCreateFileOrSame, atomicWriteFile, readJsonFile } from "./io.mjs";
 import { acceptSourceChange, deprecateItem, deprecateSource, reviewSource, reviseItem } from "./maintenance.mjs";
 import { normalizeRelativePath, resolveExistingInside, resolveProjectRoot, resolveWritableInside } from "./path-policy.mjs";
-import { CONTRACT_FILE, initializeProject, loadProject, PROJECTIONS_LOCK_FILE, SOURCES_LOCK_FILE } from "./project-store.mjs";
+import { initializeProject, inspectProjectInitialization, loadProject } from "./project-store.mjs";
 import { publishProjection } from "./projection-store.mjs";
 import { renderContextBundle } from "./renderer.mjs";
 
@@ -19,6 +21,8 @@ const HELP = `project-context — model-neutral project contract compiler
 
 Usage:
   project-context init --project PATH --id ID --name NAME [--write] [--json]
+  project-context capabilities --project PATH [--json]
+  project-context setup --project PATH --id ID --name NAME [--output FILE] [--write] [--json]
   project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--write] [--json]
   project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
   project-context review-source --project PATH --id SOURCE_ID [--json]
@@ -32,6 +36,8 @@ Usage:
   project-context publish --project PATH --target agents|ruler --output FILE [--path RELATIVE_PATH...] [--write] [--json]
   project-context check --project PATH [--json]
   project-context dashboard --project PATH [--json]
+  project-context sync --project PATH [--changed-path RELATIVE_PATH...] [--json]
+  project-context preflight --project PATH --plan FILE [--json]
 
 All commands are read-only unless their own --write flag is present.
 `;
@@ -39,12 +45,14 @@ const VALUE_FLAGS = new Set([
   "project", "id", "name", "output", "proposal", "by", "task", "target", "rationale",
   "kind", "pointer", "reference", "subject", "value", "value-json", "statement", "scope", "scope-path",
   "verification", "verification-source", "verification-expected-json",
-  "expected-digest", "expected-item-digest", "expected-source-digest", "locale",
+  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan",
 ]);
-const LIST_FLAGS = new Set(["ids", "path", "sources", "overrides", "affected-items"]);
+const LIST_FLAGS = new Set(["ids", "path", "changed-path", "sources", "overrides", "affected-items"]);
 const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending"]);
 const COMMAND_OPTIONS = new Map([
   ["init", new Set(["project", "id", "name", "write", "json", "help"])],
+  ["capabilities", new Set(["project", "json", "help"])],
+  ["setup", new Set(["project", "id", "name", "output", "write", "json", "help"])],
   ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "write", "json", "help"])],
   ["propose", new Set([
     "project", "id", "kind", "subject", "value", "value-json", "statement", "sources", "scope", "scope-path",
@@ -71,6 +79,8 @@ const COMMAND_OPTIONS = new Map([
   ["publish", new Set(["project", "target", "output", "path", "write", "json", "help"])],
   ["check", new Set(["project", "json", "help"])],
   ["dashboard", new Set(["project", "json", "help"])],
+  ["sync", new Set(["project", "changed-path", "json", "help"])],
+  ["preflight", new Set(["project", "plan", "json", "help"])],
 ]);
 
 export function parseArgs(argv) {
@@ -135,16 +145,14 @@ function rejectUnsupportedOptions(command, options, allowed) {
 }
 
 function validateProposalOutput(output) {
-  const normalized = normalizeRelativePath(output, { label: "proposal output" });
-  const reserved = new Set([
-    `.project-context/${CONTRACT_FILE}`,
-    `.project-context/${SOURCES_LOCK_FILE}`,
-    `.project-context/${PROJECTIONS_LOCK_FILE}`,
-  ]);
-  if (!normalized.startsWith(".project-context/") || path.posix.extname(normalized) !== ".json" || reserved.has(normalized)) {
-    fail("invalid-proposal-output", "proposals must be non-store JSON files inside .project-context/");
+  try {
+    return normalizeProposalPath(output, "proposal output");
+  } catch (error) {
+    if (error?.code === "action-plan-schema-invalid") {
+      fail("invalid-proposal-output", "proposals must be non-store JSON files inside .project-context/");
+    }
+    throw error;
   }
-  return normalized;
 }
 
 function jsonOrText(options, value, text) {
@@ -195,11 +203,119 @@ function itemInput(options) {
   };
 }
 
+function inMemoryProject(files, initial) {
+  return {
+    files,
+    contract: initial.contract,
+    sourcesLock: initial.sourcesLock,
+    projectionsLock: initial.projectionsLock,
+    contractDigest: digestJson(initial.contract),
+    sourcesLockDigest: digestJson(initial.sourcesLock),
+    projectionsLockDigest: digestJson(initial.projectionsLock),
+  };
+}
+
+async function createSetupProposal(root, output, proposal) {
+  const normalized = validateProposalOutput(output);
+  const resolved = await resolveWritableInside(root, normalized);
+  try {
+    return await atomicCreateFileOrSame(resolved.absolute, prettyCanonicalJson(proposal));
+  } catch (error) {
+    if (error instanceof ProjectContextError && error.code === "proposal-output-conflict") {
+      fail("setup-proposal-conflict", `refusing to overwrite a different setup proposal: ${normalized}`, {
+        details: { path: normalized },
+      });
+    }
+    throw error;
+  }
+}
+
+async function runSetup(root, options) {
+  const id = required(options, "id");
+  const name = required(options, "name");
+  const output = options.output ?? ".project-context/setup.proposal.json";
+  if (options.write || options.output) validateProposalOutput(output);
+  const initialization = await inspectProjectInitialization(root);
+  if (initialization.status === "partial") {
+    fail("setup-state-partial", "project context stores are incomplete; setup will not guess or repair state", {
+      details: { present: initialization.present, missing: initialization.missing },
+    });
+  }
+
+  let project;
+  let initialized;
+  if (initialization.status === "initialized") {
+    project = await loadProject(root);
+    if (project.contract.project.id !== id || project.contract.project.name !== name) {
+      fail("setup-project-mismatch", "setup id and name must match the initialized project", {
+        details: {
+          expected: project.contract.project,
+          actual: { id, name },
+        },
+      });
+    }
+    initialized = true;
+  } else if (options.write) {
+    await initializeProject(root, id, name, true);
+    project = await loadProject(root);
+    initialized = true;
+  } else {
+    const preview = await initializeProject(root, id, name, false);
+    project = inMemoryProject(preview.files, preview.preview);
+    initialized = false;
+  }
+
+  const proposal = validateProposal(await discoverProject(root, project.contract));
+  let proposalAction = "preview";
+  if (options.write) proposalAction = await createSetupProposal(root, output, proposal);
+  else if (options.output) validateProposalOutput(options.output);
+
+  const bundle = buildSetupAssistBundle(project, proposal, {
+    initialized,
+    proposalPath: output,
+    proposalAction,
+    proposalPersisted: Boolean(options.write),
+  });
+  const summary = [
+    `Setup ${initialized ? "initialized" : "preview"}: ${bundle.project.id}.`,
+    `Candidate sources: ${bundle.summary.candidateSources}`,
+    `Candidate items: ${bundle.summary.candidateItems}`,
+    `Proposal: ${options.write ? `${proposalAction} ${output}` : "not written"}`,
+    "Approval: required before any candidate becomes normative.",
+  ].join("\n") + "\n";
+  return {
+    exitCode: 0,
+    stdout: jsonOrText(options, bundle, summary),
+    stderr: options.output && !options.write ? `Preview only; ${options.output} was not written.\n` : "",
+  };
+}
+
+function syncSummary(bundle) {
+  const changed = bundle.sourceChanges.filter((source) => ["changed", "missing", "unreadable"].includes(source.status));
+  const lines = [
+    `Sync: ${bundle.summary.changedSources} changed source(s), ${bundle.summary.affectedItems} affected item(s), ${bundle.summary.pendingItems} pending item(s), ${bundle.summary.affectedProjections} affected projection(s).`,
+  ];
+  for (const source of changed) lines.push(`- ${source.sourceId}: ${source.status}; ${source.affectedItemIds.join(", ") || "no affected items"}`);
+  if (bundle.findings.length === 0) lines.push("No contract, source, scope, or projection findings.");
+  else lines.push(`${bundle.findings.length} finding(s) require review.`);
+  return `${lines.join("\n")}\n`;
+}
+
 async function runCommand(command, options) {
   if (!command || command === "help" || options.help) return { exitCode: 0, stdout: HELP, stderr: "" };
   if (!COMMAND_OPTIONS.has(command)) fail("command-unknown", `unknown command: ${command}`);
   rejectUnsupportedOptions(command, options, COMMAND_OPTIONS.get(command));
   const root = await resolveProjectRoot(required(options, "project"));
+  if (command === "capabilities") {
+    const capabilities = await buildCapabilities(root);
+    const summary = [
+      `Frontend Project Context ${capabilities.package.version}; exchange protocol ${capabilities.exchangeProtocolVersion}.`,
+      `Initialization: ${capabilities.initialization}.`,
+      `Action kinds: ${capabilities.actionKinds.join(", ")}.`,
+      "No Provider, Agent Runtime, automatic approval, Git, network, or business-code writes.",
+    ].join("\n") + "\n";
+    return { exitCode: 0, stdout: jsonOrText(options, capabilities, summary), stderr: "" };
+  }
   if (command === "init") {
     const result = await initializeProject(root, required(options, "id"), required(options, "name"), options.write);
     return {
@@ -208,6 +324,12 @@ async function runCommand(command, options) {
       stderr: "",
     };
   }
+  if (command === "setup") return runSetup(root, options);
+  if (command === "preflight") {
+    const bundle = await preflightActionPlanFile(root, required(options, "plan"));
+    const summary = `Preflight ${bundle.status}: ${bundle.summary.reviewable} reviewable, ${bundle.summary.blocked} blocked action(s).\n`;
+    return { exitCode: bundle.status === "reviewable" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
+  }
   const project = await loadProject(root);
   if (command === "register") {
     const result = await registerSource(root, project, {
@@ -363,6 +485,14 @@ async function runCommand(command, options) {
       stderr: "",
     };
   }
+  if (command === "sync") {
+    const bundle = await buildSyncAssistBundle(root, project, options["changed-path"] ?? []);
+    return {
+      exitCode: checkExitCode(bundle.findings),
+      stdout: jsonOrText(options, bundle, syncSummary(bundle)),
+      stderr: "",
+    };
+  }
   if (command === "context") {
     const findings = blockingContextFindings(await checkProject(root, project));
     if (findings.length > 0) fail("context-blocked", "context generation is blocked by contract or source findings", { exitCode: 1, details: { findings } });