frontend-project-context 1.0.0

package/src/project-context/cli.mjs

@@ -0,0 +1,409 @@
+import path from "node:path";
+import { approvePendingItems, approveProposal } from "./approver.mjs";
+import { buildItemProposal, registerSource } from "./authoring.mjs";
+import { blockingContextFindings, checkExitCode, checkProject } from "./checker.mjs";
+import { digestJson, prettyCanonicalJson } from "./canonical-json.mjs";
+import { validateProposal } from "./contract-schema.mjs";
+import { buildDashboardModel } from "./dashboard-model.mjs";
+import { renderDashboardHtml } from "./dashboard-renderer.mjs";
+import { discoverProject } from "./discovery.mjs";
+import { ProjectContextError, fail } from "./errors.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 { publishProjection } from "./projection-store.mjs";
+import { renderContextBundle } from "./renderer.mjs";
+
+const HELP = `project-context — model-neutral project contract compiler
+
+Usage:
+  project-context init --project PATH --id ID --name NAME [--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]
+  project-context accept-source-change --project PATH --id SOURCE_ID --expected-digest SHA256 [--affected-items ITEM_ID...] [--write] [--json]
+  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --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] [--write] [--json]
+  project-context deprecate --project PATH --id ITEM_ID [--expected-item-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
+  project-context deprecate-source --project PATH --id SOURCE_ID [--expected-source-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
+  project-context discover --project PATH [--output FILE --write] [--json]
+  project-context approve --project PATH (--proposal FILE | --pending) --ids ID... --by NAME [--rationale TEXT] [--write] [--json | --full-json]
+  project-context context --project PATH --path RELATIVE_PATH... [--task TEXT] [--locale zh-CN|en|all] [--json]
+  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]
+
+All commands are read-only unless their own --write flag is present.
+`;
+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",
+]);
+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"])],
+  ["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",
+    "overrides", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
+  ])],
+  ["review-source", new Set(["project", "id", "json", "help"])],
+  ["accept-source-change", new Set([
+    "project", "id", "expected-digest", "affected-items", "write", "json", "help",
+  ])],
+  ["revise", new Set([
+    "project", "id", "expected-item-digest", "kind", "subject", "value", "value-json", "statement", "sources",
+    "scope", "scope-path", "overrides", "verification", "verification-source", "verification-expected-json",
+    "write", "json", "help",
+  ])],
+  ["deprecate", new Set([
+    "project", "id", "expected-item-digest", "by", "rationale", "write", "json", "help",
+  ])],
+  ["deprecate-source", new Set([
+    "project", "id", "expected-source-digest", "by", "rationale", "write", "json", "help",
+  ])],
+  ["discover", new Set(["project", "output", "write", "json", "help"])],
+  ["approve", new Set(["project", "proposal", "pending", "ids", "by", "rationale", "write", "json", "full-json", "help"])],
+  ["context", new Set(["project", "path", "task", "locale", "json", "help"])],
+  ["publish", new Set(["project", "target", "output", "path", "write", "json", "help"])],
+  ["check", new Set(["project", "json", "help"])],
+  ["dashboard", new Set(["project", "json", "help"])],
+]);
+
+export function parseArgs(argv) {
+  const args = [...argv];
+  const command = args.shift();
+  if (command === "--help") return { command: "help", options: { help: true } };
+  const options = {};
+  while (args.length > 0) {
+    const token = args.shift();
+    if (!token.startsWith("--")) fail("argument-invalid", `unexpected argument: ${token}`);
+    const key = token.slice(2);
+    if (BOOLEAN_FLAGS.has(key)) {
+      options[key] = true;
+      continue;
+    }
+    if (LIST_FLAGS.has(key)) {
+      const values = [];
+      while (args.length > 0 && !args[0].startsWith("--")) values.push(args.shift());
+      if (values.length === 0) fail("argument-missing", `--${key} requires at least one value`);
+      options[key] = [...(options[key] ?? []), ...values];
+      continue;
+    }
+    if (VALUE_FLAGS.has(key)) {
+      const value = args.shift();
+      if (value === undefined || value.startsWith("--")) fail("argument-missing", `--${key} requires a value`);
+      options[key] = value;
+      continue;
+    }
+    fail("argument-unknown", `unknown option: --${key}`);
+  }
+  return { command, options };
+}
+
+function required(options, name) {
+  if (options[name] === undefined) fail("argument-missing", `--${name} is required`);
+  return options[name];
+}
+
+function oneListValue(options, name) {
+  const values = required(options, name);
+  if (!Array.isArray(values) || values.length !== 1) fail("argument-conflict", `--${name} requires exactly one value for this command`);
+  return values[0];
+}
+
+function optionalOneListValue(options, name) {
+  if (options[name] === undefined) return undefined;
+  return oneListValue(options, name);
+}
+
+function parseJsonArgument(value, name) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    fail("value-json-invalid", `--${name} must contain valid JSON`, { cause: error });
+  }
+}
+
+function rejectUnsupportedOptions(command, options, allowed) {
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) fail("argument-unknown", `${command} does not accept --${key}`);
+  }
+}
+
+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/");
+  }
+  return normalized;
+}
+
+function jsonOrText(options, value, text) {
+  return options.json ? prettyCanonicalJson(value) : text;
+}
+
+function contextLocale(options) {
+  const locale = options.locale ?? "zh-CN";
+  if (!["zh-CN", "en", "all"].includes(locale)) {
+    fail("argument-invalid", "--locale must be zh-CN, en, or all");
+  }
+  return locale;
+}
+
+function approvalReceipt(project, result, mode) {
+  return {
+    action: "approve",
+    mode,
+    approvedIds: result.approvedIds,
+    previousContractDigest: project.contractDigest,
+    nextContractDigest: digestJson(result.contract),
+    nextSourcesLockDigest: digestJson(result.sourcesLock),
+    written: result.written,
+  };
+}
+
+function itemInput(options) {
+  const hasValue = options.value !== undefined;
+  const hasJsonValue = options["value-json"] !== undefined;
+  if (hasValue === hasJsonValue) fail("argument-conflict", "exactly one of --value or --value-json is required");
+  const hasExpected = options["verification-expected-json"] !== undefined;
+  return {
+    id: required(options, "id"),
+    kind: required(options, "kind"),
+    subject: required(options, "subject"),
+    value: hasValue ? options.value : parseJsonArgument(options["value-json"], "value-json"),
+    statement: required(options, "statement"),
+    sources: required(options, "sources"),
+    scope: required(options, "scope"),
+    scopePath: options["scope-path"],
+    overrides: options.overrides ?? [],
+    verification: options.verification,
+    verificationSource: options["verification-source"],
+    verificationExpectedPresent: hasExpected,
+    verificationExpected: hasExpected
+      ? parseJsonArgument(options["verification-expected-json"], "verification-expected-json")
+      : undefined,
+  };
+}
+
+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 === "init") {
+    const result = await initializeProject(root, required(options, "id"), required(options, "name"), options.write);
+    return {
+      exitCode: 0,
+      stdout: jsonOrText(options, result.preview, options.write ? "Initialized .project-context/.\n" : prettyCanonicalJson(result.preview)),
+      stderr: "",
+    };
+  }
+  const project = await loadProject(root);
+  if (command === "register") {
+    const result = await registerSource(root, project, {
+      id: required(options, "id"),
+      kind: required(options, "kind"),
+      path: optionalOneListValue(options, "path"),
+      pointer: options.pointer,
+      reference: options.reference,
+    }, { write: options.write });
+    const summary = result.action === "unchanged"
+      ? `Source unchanged: ${result.source.id}.\n`
+      : options.write
+        ? `Registered source: ${result.source.id}.\n`
+        : `Preview source registration: ${result.source.id}.\n`;
+    return { exitCode: 0, stdout: jsonOrText(options, result, summary), stderr: "" };
+  }
+  if (command === "propose") {
+    const proposal = buildItemProposal(project, itemInput(options));
+    if (options.write && !options.output) fail("argument-missing", "--output is required with --write for propose");
+    let action = "preview";
+    if (options.output && options.write) {
+      const output = validateProposalOutput(options.output);
+      const resolved = await resolveWritableInside(root, output);
+      action = await atomicCreateFileOrSame(resolved.absolute, prettyCanonicalJson(proposal));
+    }
+    const result = { action, proposal, written: Boolean(options.output && options.write && action === "create") };
+    const text = options.output && options.write
+      ? `${action === "create" ? "Created" : "Unchanged"} proposal: ${options.output}.\n`
+      : prettyCanonicalJson(proposal);
+    return {
+      exitCode: 0,
+      stdout: jsonOrText(options, result, text),
+      stderr: options.output && !options.write ? `Preview only; ${options.output} was not written.\n` : "",
+    };
+  }
+  if (command === "review-source") {
+    const result = await reviewSource(root, project, required(options, "id"));
+    const exitCode = result.status === "unchanged" || result.status === "deprecated" ? 0 : 1;
+    const summary = [
+      `Source ${result.source.id}: ${result.status}.`,
+      `Checkpoint: ${result.lockedDigest ?? "missing"}`,
+      `Current: ${result.currentDigest ?? "unavailable"}`,
+      `Affected items: ${result.impact.items.map((item) => item.id).join(", ") || "none"}`,
+    ].join("\n") + "\n";
+    return { exitCode, stdout: jsonOrText(options, result, summary), stderr: "" };
+  }
+  if (command === "accept-source-change") {
+    const result = await acceptSourceChange(root, project, {
+      id: required(options, "id"),
+      expectedDigest: required(options, "expected-digest"),
+      affectedItems: options["affected-items"] ?? [],
+    }, { write: options.write });
+    const summary = options.write
+      ? `Accepted source change: ${result.source}; ${result.affectedItems.length} item(s) now pending approval.\n`
+      : `Preview source acceptance: ${result.source}; ${result.affectedItems.length} item(s) would become pending.\n`;
+    return { exitCode: 0, stdout: jsonOrText(options, result, summary), stderr: "" };
+  }
+  if (command === "revise") {
+    if (options.write && options["expected-item-digest"] === undefined) {
+      fail("argument-missing", "--expected-item-digest is required with --write for revise");
+    }
+    const result = await reviseItem(root, project, {
+      ...itemInput(options),
+      expectedItemDigest: options["expected-item-digest"],
+    }, { write: options.write });
+    const summary = options.write
+      ? `Revised item into pending approval: ${result.proposedItem.id}.\n`
+      : `Preview item revision: ${result.proposedItem.id}; current digest ${result.currentItemDigest}.\n`;
+    return { exitCode: 0, stdout: jsonOrText(options, result, summary), stderr: "" };
+  }
+  if (command === "deprecate") {
+    if (options.write && options["expected-item-digest"] === undefined) {
+      fail("argument-missing", "--expected-item-digest is required with --write for deprecate");
+    }
+    const result = await deprecateItem(project, {
+      id: required(options, "id"),
+      expectedItemDigest: options["expected-item-digest"],
+      by: required(options, "by"),
+      rationale: required(options, "rationale"),
+    }, { write: options.write });
+    const summary = options.write
+      ? `Deprecated item: ${result.deprecatedItem.id}.\n`
+      : `Preview item deprecation: ${result.deprecatedItem.id}; current digest ${result.currentItemDigest}.\n`;
+    return { exitCode: 0, stdout: jsonOrText(options, result, summary), stderr: "" };
+  }
+  if (command === "deprecate-source") {
+    if (options.write && options["expected-source-digest"] === undefined) {
+      fail("argument-missing", "--expected-source-digest is required with --write for deprecate-source");
+    }
+    const result = await deprecateSource(project, {
+      id: required(options, "id"),
+      expectedSourceDigest: options["expected-source-digest"],
+      by: required(options, "by"),
+      rationale: required(options, "rationale"),
+    }, { write: options.write });
+    const summary = options.write
+      ? `Deprecated source: ${result.deprecatedSource.id}.\n`
+      : `Preview source deprecation: ${result.currentSource.id}; current digest ${result.currentSourceDigest}.\n`;
+    return { exitCode: 0, stdout: jsonOrText(options, result, summary), stderr: "" };
+  }
+  if (command === "discover") {
+    const proposal = validateProposal(await discoverProject(root, project.contract));
+    if (options.output && options.write) {
+      const output = validateProposalOutput(options.output);
+      const resolved = await resolveWritableInside(root, output);
+      await atomicWriteFile(resolved.absolute, prettyCanonicalJson(proposal));
+    }
+    return {
+      exitCode: 0,
+      stdout: jsonOrText(options, proposal, prettyCanonicalJson(proposal)),
+      stderr: options.output && !options.write ? `Preview only; ${options.output} was not written.\n` : "",
+    };
+  }
+  if (command === "approve") {
+    if (options.json && options["full-json"]) fail("argument-conflict", "approve accepts either --json or --full-json, not both");
+    if (Boolean(options.pending) === Boolean(options.proposal)) {
+      fail("argument-conflict", "approve requires exactly one of --proposal or --pending");
+    }
+    const approvalOptions = {
+      ids: required(options, "ids"),
+      by: required(options, "by"),
+      rationale: options.rationale,
+      write: options.write,
+    };
+    let result;
+    if (options.pending) {
+      result = await approvePendingItems(root, project, approvalOptions);
+    } else {
+      const proposalPath = normalizeRelativePath(options.proposal, { label: "proposal path" });
+      const resolved = await resolveExistingInside(root, proposalPath);
+      const proposal = await readJsonFile(resolved.absolute, "proposal");
+      result = await approveProposal(root, project, proposal, approvalOptions);
+    }
+    const summary = options.write
+      ? `Approved ${result.approvedIds.join(", ")} and updated the contract.\n`
+      : `Preview approval: ${result.approvedIds.join(", ")}.\n`;
+    const output = options["full-json"] ? result : approvalReceipt(project, result, options.pending ? "pending" : "proposal");
+    return { exitCode: 0, stdout: options.json || options["full-json"] ? prettyCanonicalJson(output) : summary, stderr: "" };
+  }
+  if (command === "check") {
+    const findings = await checkProject(root, project);
+    const exitCode = checkExitCode(findings);
+    const summary = findings.length === 0
+      ? "No contract, source, scope, or projection findings.\n"
+      : `${findings.length} finding(s):\n${findings.map((finding) => `- ${finding.code}: ${finding.path ?? finding.source ?? finding.item ?? finding.subject ?? "project"}`).join("\n")}\n`;
+    return { exitCode, stdout: jsonOrText(options, { findings }, summary), stderr: "" };
+  }
+  if (command === "dashboard") {
+    const model = await buildDashboardModel(root, project);
+    return {
+      exitCode: model.health.exitCode,
+      stdout: options.json ? prettyCanonicalJson(model) : renderDashboardHtml(model),
+      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 } });
+    const paths = required(options, "path");
+    const content = renderContextBundle(project.contract, paths, options.task, { locale: contextLocale(options) });
+    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson({ content }) : content, stderr: "" };
+  }
+  if (command === "publish") {
+    const findings = blockingContextFindings(await checkProject(root, project));
+    if (findings.length > 0) fail("publish-blocked", "projection is blocked by contract or source findings", { exitCode: 1, details: { findings } });
+    const result = await publishProjection(root, project, {
+      target: required(options, "target"),
+      output: required(options, "output"),
+      paths: options.path ?? ["."],
+      write: options.write,
+    });
+    const summary = options.write ? `${result.action}: ${result.entry.path}\n` : `Preview ${result.action}: ${result.entry.path}\n\n${result.content}`;
+    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson(result) : summary, stderr: "" };
+  }
+  fail("command-unknown", `unknown command: ${command}`);
+}
+
+export async function runCli(argv) {
+  try {
+    const { command, options } = parseArgs(argv);
+    return await runCommand(command, options);
+  } catch (error) {
+    const known = error instanceof ProjectContextError;
+    const payload = {
+      code: known ? error.code : "internal-error",
+      message: error.message,
+      ...(known && Object.keys(error.details).length > 0 ? { details: error.details } : {}),
+    };
+    const wantsJson = argv.includes("--json") || argv.includes("--full-json");
+    const schemaFinding = argv[0] === "check" && known && (
+      error.code.startsWith("schema-") || error.code === "source-reference-deprecated"
+    );
+    return {
+      exitCode: schemaFinding ? 1 : known ? error.exitCode : 4,
+      stdout: "",
+      stderr: wantsJson ? prettyCanonicalJson(payload) : `${payload.code}: ${payload.message}\n`,
+    };
+  }
+}