frontend-project-context 1.0.1 → 1.3.0

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,17 +8,22 @@ 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";
+import { buildIntegrationReviewBundleFiles, buildStageContextBundleFiles } from "./task-context.mjs";
 
 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 +37,10 @@ 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]
+  project-context stage-context --project PATH --plan FILE --stage STAGE_ID [--receipt FILE...] [--changed-path RELATIVE_PATH...] [--json]
+  project-context integration-review --project PATH --plan FILE [--receipt FILE...] [--main-changed-path RELATIVE_PATH...] [--branch-changed-path RELATIVE_PATH...] [--json]
 
 All commands are read-only unless their own --write flag is present.
 `;
@@ -39,12 +48,16 @@ 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", "stage",
+]);
+const LIST_FLAGS = new Set([
+  "ids", "path", "changed-path", "sources", "overrides", "affected-items", "receipt", "main-changed-path", "branch-changed-path",
 ]);
-const LIST_FLAGS = new Set(["ids", "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 +84,10 @@ 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"])],
+  ["stage-context", new Set(["project", "plan", "stage", "receipt", "changed-path", "json", "help"])],
+  ["integration-review", new Set(["project", "plan", "receipt", "main-changed-path", "branch-changed-path", "json", "help"])],
 ]);
 
 export function parseArgs(argv) {
@@ -135,16 +152,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 +210,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 +331,30 @@ 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: "" };
+  }
+  if (command === "stage-context") {
+    const bundle = await buildStageContextBundleFiles(root, required(options, "plan"), {
+      stageId: required(options, "stage"),
+      receiptPaths: options.receipt ?? [],
+      changedPaths: options["changed-path"] ?? [],
+    });
+    const summary = `Stage context ${bundle.status}: ${bundle.stage.id}; ${bundle.contractItems.length} contract item(s), ${bundle.readTargets.length} read target(s), ${bundle.budget.usedUtf8Bytes}/${bundle.budget.maxUtf8Bytes} UTF-8 bytes.\n`;
+    return { exitCode: bundle.status === "ready" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
+  }
+  if (command === "integration-review") {
+    const bundle = await buildIntegrationReviewBundleFiles(root, required(options, "plan"), {
+      receiptPaths: options.receipt ?? [],
+      mainChangedPaths: options["main-changed-path"] ?? [],
+      branchChangedPaths: options["branch-changed-path"] ?? [],
+    });
+    const summary = `Integration review ${bundle.status}: ${bundle.findings.length} finding(s), ${bundle.contractOverlapItemIds.length} contract overlap(s), ${bundle.decisionCandidates.length} decision candidate(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 +510,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 } });