@neocompose/cli 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.1] - 2026-07-16
+
+### Added
+
+- Added `neo history inspect`, `undo`, `revert`, and `flatten` workflows with
+  interactive project and version selection.
+- Added deterministic `@current` and `@latest` version resolution for history
+  commands.
+
+### Changed
+
+- Reduced project synchronization I/O with incremental export manifests and
+  bounded snapshot retrieval.
+
 ## [0.3.0] - 2026-07-15
 
 ### Breaking

package/dist/neo.mjs

@@ -1390,7 +1390,7 @@ var init_source_protocol = __esm({
     SCHEMA_SOURCE_MANIFEST_NAME = "neo-schema-manifest-v3";
     SCHEMA_COMPILER_PROTOCOL_VERSION = 4;
     SCHEMA_SDK_VERSION = "3.0.0";
-    SCHEMA_CLI_VERSION = "0.3.0";
+    SCHEMA_CLI_VERSION = "0.3.1";
     SCHEMA_API_TARGET = "netstandard2.1";
     SCHEMA_REFERENCE_ASSEMBLY_SET = "NETStandard.Library.Ref/2.1.0";
     SCHEMA_REQUIRED_TOOLING_FILES = [
@@ -31121,10 +31121,15 @@ function appendBucketRecord(buckets, recordKind, data) {
   }
   buckets[bucket].push(data);
 }
-function readProjectDocument(value) {
+function readProjectDocument(value, options = {}) {
   if (!isObject2(value)) {
     throw new Error("Convex project document query returned a non-object.");
   }
+  const localizationConfig = options.localizationConfig === "nullable" ? readOptionalNullableField(
+    value,
+    "localizationConfig",
+    isProjectLocalizationConfig
+  ) : readField(value, "localizationConfig", isProjectLocalizationConfig);
   return {
     version: readField(value, "version", isProjectVersion),
     versions: readArrayField(value, "versions", isProjectVersion),
@@ -31176,11 +31181,7 @@ function readProjectDocument(value) {
       "audioClipTemplates",
       isUnityAudioClipImportSettingsTemplate
     ),
-    localizationConfig: readField(
-      value,
-      "localizationConfig",
-      isProjectLocalizationConfig
-    ),
+    localizationConfig,
     localizationStatuses: readArrayField(
       value,
       "localizationStatuses",
@@ -31221,6 +31222,14 @@ function readField(source, key, isValid) {
     `Convex project document field "${key}" has an invalid shape.`
   );
 }
+function readOptionalNullableField(source, key, isValid) {
+  const value = source[key];
+  if (value === void 0 || value === null) return null;
+  if (isValid(value)) return value;
+  throw new Error(
+    `Convex project document field "${key}" has an invalid shape.`
+  );
+}
 function readArrayField(source, key, isValid) {
   const value = source[key];
   if (!Array.isArray(value)) {
@@ -32162,6 +32171,565 @@ var init_init = __esm({
   }
 });
 
+// src/commands/history-selection.ts
+async function resolveHistoryScope(options) {
+  const projectSelector = await readHistorySelector({
+    command: options.command,
+    kind: "project",
+    provided: options.projectSelector
+  });
+  const project = await options.resolveProject(projectSelector);
+  console.log(`${sym.info} Project: ${project.name} (${project.id})`);
+  if (!options.requiresVersion) {
+    return { project, version: null };
+  }
+  const versionSelector = await readHistorySelector({
+    command: options.command,
+    kind: "version",
+    provided: options.versionSelector
+  });
+  const version = await options.resolveVersion(project.id, versionSelector);
+  console.log(`${sym.info} Version: ${version.name} (${version.id})`);
+  return { project, version };
+}
+async function readHistorySelector(args) {
+  if (args.provided !== null) return normalizeHistorySelector(args.provided);
+  const flag = args.kind === "project" ? "--project" : "--version";
+  if (!isInteractive()) {
+    throw new Error(
+      `neo history ${args.command} requires ${flag} <id|@latest|@current> outside an interactive terminal.`
+    );
+  }
+  const label = args.kind === "project" ? "Project" : "Version";
+  const value = await promptInput({
+    message: `${label} ID (@latest or @current; Enter for latest)`,
+    nonInteractiveHint: `Pass ${flag} <id|@latest|@current>.`
+  });
+  return normalizeHistorySelector(value);
+}
+function normalizeHistorySelector(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed === "@latest" || trimmed === "@current") {
+    return "@latest";
+  }
+  if (trimmed.startsWith("@")) {
+    throw new Error(
+      `Unknown history selector "${trimmed}". Use a stable ID, @latest, or @current.`
+    );
+  }
+  return trimmed;
+}
+var init_history_selection = __esm({
+  "src/commands/history-selection.ts"() {
+    "use strict";
+    init_ui();
+  }
+});
+
+// src/commands/history-inspect.ts
+function inspectHistoryDataset(dataset) {
+  const brokenReferences = [];
+  const projectSnapshots = new Map(
+    dataset["project-snapshots"].map((snapshot) => [snapshot.id, snapshot])
+  );
+  const projectTransactions = new Set(
+    dataset["project-transactions"].map((transaction) => transaction.id)
+  );
+  const reachableProjectSnapshots = walkAncestors({
+    roots: dataset["project-heads"].map((head) => ({
+      id: head.snapshotId,
+      source: `project head "${head.id}"`
+    })),
+    rows: projectSnapshots,
+    baseId: (snapshot) => snapshot.baseSnapshotId,
+    kind: "project snapshot",
+    brokenReferences
+  });
+  for (const snapshot of projectSnapshots.values()) {
+    if (!projectTransactions.has(snapshot.transactionId)) {
+      brokenReferences.push(
+        `Project snapshot "${snapshot.id}" references missing transaction "${snapshot.transactionId}".`
+      );
+    }
+  }
+  const reachableProjectTransactions = new Set(
+    [...reachableProjectSnapshots].map((id) => projectSnapshots.get(id)?.transactionId).filter(
+      (id) => id !== void 0 && projectTransactions.has(id)
+    )
+  );
+  const wikiSnapshots = new Map(
+    dataset["wiki-snapshots"].map((snapshot) => [snapshot.id, snapshot])
+  );
+  const wikiTransactions = new Set(
+    dataset["wiki-transactions"].map((transaction) => transaction.id)
+  );
+  const wikiDocuments = new Map(
+    dataset["wiki-documents"].map((document) => [document.id, document])
+  );
+  const reachableWikiSnapshots = walkAncestors({
+    roots: dataset["wiki-heads"].map((head) => ({
+      id: head.snapshotId,
+      source: `wiki head "${head.id}"`
+    })),
+    rows: wikiSnapshots,
+    baseId: (snapshot) => snapshot.baseSnapshotId,
+    kind: "wiki snapshot",
+    brokenReferences
+  });
+  const reachableWikiDocuments = walkAncestors({
+    roots: [...reachableWikiSnapshots].flatMap((snapshotId) => {
+      const snapshot = wikiSnapshots.get(snapshotId);
+      return snapshot === void 0 ? [] : [
+        {
+          id: snapshot.yjsDocumentId,
+          source: `wiki snapshot "${snapshot.id}"`
+        }
+      ];
+    }),
+    rows: wikiDocuments,
+    baseId: (document) => document.forkedFromDocumentId,
+    kind: "wiki document",
+    brokenReferences
+  });
+  const reachableWikiTransactions = /* @__PURE__ */ new Set();
+  for (const snapshotId of reachableWikiSnapshots) {
+    const snapshot = wikiSnapshots.get(snapshotId);
+    if (snapshot !== void 0 && wikiTransactions.has(snapshot.transactionId)) {
+      reachableWikiTransactions.add(snapshot.transactionId);
+    }
+  }
+  for (const snapshot of wikiSnapshots.values()) {
+    if (!wikiTransactions.has(snapshot.transactionId)) {
+      brokenReferences.push(
+        `Wiki snapshot "${snapshot.id}" references missing transaction "${snapshot.transactionId}".`
+      );
+    }
+    if (!wikiDocuments.has(snapshot.yjsDocumentId)) {
+      brokenReferences.push(
+        `Wiki snapshot "${snapshot.id}" references missing document "${snapshot.yjsDocumentId}".`
+      );
+    }
+  }
+  let unreachableWikiRevisions = 0;
+  for (const revision of dataset["wiki-revisions"]) {
+    const documentExists = wikiDocuments.has(revision.yjsDocumentId);
+    const transactionExists = wikiTransactions.has(revision.transactionId);
+    if (!documentExists) {
+      brokenReferences.push(
+        `Wiki revision "${revision.id}" references missing document "${revision.yjsDocumentId}".`
+      );
+    }
+    if (!transactionExists) {
+      brokenReferences.push(
+        `Wiki revision "${revision.id}" references missing transaction "${revision.transactionId}".`
+      );
+    }
+    if (transactionExists && reachableWikiDocuments.has(revision.yjsDocumentId)) {
+      reachableWikiTransactions.add(revision.transactionId);
+    } else {
+      unreachableWikiRevisions += 1;
+    }
+  }
+  return {
+    versions: {
+      total: dataset.versions.length,
+      archived: dataset.versions.filter((version) => version.archived).length
+    },
+    projectRecords: {
+      heads: dataset["project-heads"].length,
+      snapshots: projectSnapshots.size,
+      transactions: projectTransactions.size,
+      unreachableSnapshots: projectSnapshots.size - reachableProjectSnapshots.size,
+      unreachableTransactions: projectTransactions.size - reachableProjectTransactions.size,
+      duplicateSemanticSnapshots: duplicateCount(
+        dataset["project-snapshots"],
+        (snapshot) => `${snapshot.recordKind}:${snapshot.recordId}:${snapshot.contentHash}`
+      )
+    },
+    wiki: {
+      heads: dataset["wiki-heads"].length,
+      snapshots: wikiSnapshots.size,
+      transactions: wikiTransactions.size,
+      documents: wikiDocuments.size,
+      revisions: dataset["wiki-revisions"].length,
+      unreachableSnapshots: wikiSnapshots.size - reachableWikiSnapshots.size,
+      unreachableTransactions: wikiTransactions.size - reachableWikiTransactions.size,
+      unreachableDocuments: wikiDocuments.size - reachableWikiDocuments.size,
+      unreachableRevisions: unreachableWikiRevisions,
+      duplicateSemanticSnapshots: duplicateCount(
+        dataset["wiki-snapshots"],
+        (snapshot) => `${snapshot.pageId}:${snapshot.contentHash}`
+      ),
+      duplicateSemanticDocuments: duplicateCount(
+        dataset["wiki-documents"],
+        (document) => `${document.pageId}:${document.contentHash}`
+      )
+    },
+    brokenReferences
+  };
+}
+function walkAncestors(args) {
+  const reachable = /* @__PURE__ */ new Set();
+  const stack = [...args.roots];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (reachable.has(current.id)) continue;
+    const row = args.rows.get(current.id);
+    if (row === void 0) {
+      args.brokenReferences.push(
+        `${current.source} references missing ${args.kind} "${current.id}".`
+      );
+      continue;
+    }
+    reachable.add(current.id);
+    const baseId = args.baseId(row);
+    if (baseId !== null) {
+      stack.push({
+        id: baseId,
+        source: `${args.kind} "${current.id}"`
+      });
+    }
+  }
+  return reachable;
+}
+function duplicateCount(rows, key) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const value = key(row);
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  let duplicates = 0;
+  for (const count of counts.values()) {
+    if (count > 1) duplicates += count - 1;
+  }
+  return duplicates;
+}
+var HISTORY_INSPECT_PHASES;
+var init_history_inspect = __esm({
+  "src/commands/history-inspect.ts"() {
+    "use strict";
+    HISTORY_INSPECT_PHASES = [
+      "versions",
+      "project-heads",
+      "project-snapshots",
+      "project-transactions",
+      "wiki-heads",
+      "wiki-snapshots",
+      "wiki-transactions",
+      "wiki-documents",
+      "wiki-revisions"
+    ];
+  }
+});
+
+// src/commands/history.ts
+var history_exports = {};
+__export(history_exports, {
+  resolveHistoryScopeFromServer: () => resolveHistoryScopeFromServer,
+  runHistory: () => runHistory
+});
+async function resolveHistoryScopeFromServer(options) {
+  const convex = await createConvexClientForApi(options.apiBaseUrl);
+  return await resolveHistoryScope({
+    command: options.command,
+    projectSelector: options.projectSelector,
+    versionSelector: options.versionSelector,
+    requiresVersion: options.command === "log" || options.command === "flatten",
+    resolveProject: async (selector) => await convex.query(api2.projectHistory.resolveProjectSelector, {
+      selector
+    }),
+    resolveVersion: async (projectId, selector) => await convex.query(api2.projectHistory.resolveVersionSelector, {
+      projectId,
+      selector
+    })
+  });
+}
+async function runHistory(options) {
+  assertHistoryOptions(options);
+  const convex = await createConvexClientForApi(options.apiBaseUrl);
+  if (options.command === "inspect") {
+    const scope = await resolveScopeWithClient(convex, options);
+    await printHistoryInspection(convex, scope.project.id);
+    return;
+  }
+  if (options.command === "log") {
+    const scope = await resolveScopeWithClient(convex, options);
+    await printVersionLog(convex, scope);
+    return;
+  }
+  if (options.command === "flatten") {
+    const scope = await resolveScopeWithClient(convex, options);
+    if (scope.version === null) {
+      throw new Error("Flatten requires a resolved version.");
+    }
+    const started = await convex.mutation(api2.projectHistory.planFlatten, {
+      projectId: scope.project.id,
+      versionId: scope.version.id
+    });
+    console.log(`${sym.info} Plan: ${started.planId}`);
+    console.log(`${sym.info} Planning run: ${started.runId}`);
+    const plan = await waitForPlan(convex, started.planId);
+    printPlan(plan);
+    return;
+  }
+  if (options.command === "prune") {
+    const scope = await resolveScopeWithClient(convex, options);
+    const started = await convex.mutation(api2.projectHistory.planPrune, {
+      projectId: scope.project.id
+    });
+    console.log(`${sym.info} Plan: ${started.planId}`);
+    console.log(`${sym.info} Planning run: ${started.runId}`);
+    const plan = await waitForPlan(convex, started.planId);
+    printPlan(plan);
+    return;
+  }
+  if (options.command === "apply") {
+    const plan = await convex.query(api2.projectHistory.getPlan, {
+      planId: options.planId
+    });
+    const expectedScope = plan.versionId === null ? plan.projectId : `${plan.projectId}/${plan.versionId}`;
+    let confirmScope = options.confirmScope;
+    if (plan.productionConfirmationRequired && confirmScope === null) {
+      if (!isInteractive()) {
+        throw new Error(
+          `Production history apply requires --confirm-scope ${expectedScope}.`
+        );
+      }
+      confirmScope = await promptInput({
+        message: `Type ${expectedScope} to confirm production history rewrite`,
+        nonInteractiveHint: `Pass --confirm-scope ${expectedScope}.`,
+        validate: (value) => value === expectedScope ? true : `Confirmation must exactly match ${expectedScope}.`
+      });
+    }
+    const started = await convex.mutation(api2.projectHistory.applyPlan, {
+      planId: plan.id,
+      confirmScope
+    });
+    console.log(`${sym.info} Run: ${started.runId}`);
+    console.log(`${sym.info} State: ${started.state}`);
+    return;
+  }
+  if (options.command === "status") {
+    const status = await convex.query(api2.projectHistory.getRunStatus, {
+      runId: options.runId
+    });
+    printRunStatus(status);
+    return;
+  }
+  if (options.command === "resume") {
+    const resumed = await convex.mutation(api2.projectHistory.resumeRun, {
+      runId: options.runId
+    });
+    console.log(`${sym.info} Run: ${resumed.runId}`);
+    console.log(`${sym.info} State: ${resumed.state}`);
+    return;
+  }
+}
+async function resolveScopeWithClient(convex, options) {
+  if (options.command !== "inspect" && options.command !== "log" && options.command !== "prune" && options.command !== "flatten") {
+    throw new Error(`neo history ${options.command} has immutable scope.`);
+  }
+  return await resolveHistoryScope({
+    command: options.command,
+    projectSelector: options.projectSelector,
+    versionSelector: options.versionSelector,
+    requiresVersion: options.command === "log" || options.command === "flatten",
+    resolveProject: async (selector) => await convex.query(api2.projectHistory.resolveProjectSelector, {
+      selector
+    }),
+    resolveVersion: async (projectId, selector) => await convex.query(api2.projectHistory.resolveVersionSelector, {
+      projectId,
+      selector
+    })
+  });
+}
+async function waitForPlan(convex, planId) {
+  let lastState = null;
+  while (true) {
+    const plan = await convex.query(api2.projectHistory.getPlan, { planId });
+    if (plan.state !== lastState) {
+      console.log(`${sym.info} Plan state: ${plan.state}`);
+      lastState = plan.state;
+    }
+    if (plan.state === "sealed") return plan;
+    if (plan.state === "failed") {
+      throw new Error(
+        `History plan "${plan.id}" failed: ${plan.error ?? "unknown error"}`
+      );
+    }
+    await new Promise((resolve6) => setTimeout(resolve6, 500));
+  }
+}
+async function printVersionLog(convex, scope) {
+  if (scope.version === null) {
+    throw new Error("History log requires a resolved version.");
+  }
+  let cursor = null;
+  let count = 0;
+  while (true) {
+    const page = await convex.query(
+      api2.projectVersionHistory.getChangelog,
+      {
+        projectId: scope.project.id,
+        versionId: scope.version.id,
+        paginationOpts: { cursor, numItems: 50 }
+      }
+    );
+    if (page === null) {
+      throw new Error(
+        `Version "${scope.version.id}" no longer exists in project "${scope.project.id}".`
+      );
+    }
+    for (const transaction of page.transactions) {
+      count += 1;
+      console.log(
+        `${transaction.id}  ${new Date(transaction.createdAt).toISOString()}  ${transaction.operation}  ${transaction.summary ?? ""}`.trimEnd()
+      );
+    }
+    if (page.isDone) break;
+    cursor = page.continueCursor;
+  }
+  if (count === 0) console.log("No retained history entries.");
+}
+async function printHistoryInspection(convex, projectId) {
+  const dataset = {
+    versions: [],
+    "project-heads": [],
+    "project-snapshots": [],
+    "project-transactions": [],
+    "wiki-heads": [],
+    "wiki-snapshots": [],
+    "wiki-transactions": [],
+    "wiki-documents": [],
+    "wiki-revisions": []
+  };
+  for (const phase of HISTORY_INSPECT_PHASES) {
+    let cursor = null;
+    while (true) {
+      const page = await convex.query(api2.projectHistory.inspectPage, {
+        projectId,
+        phase,
+        paginationOpts: { cursor, numItems: 100 }
+      });
+      if (page.phase !== phase) {
+        throw new Error(
+          `History inspection requested phase "${phase}" but received "${page.phase}".`
+        );
+      }
+      dataset[phase].push(...page.rows);
+      if (page.isDone) break;
+      cursor = page.continueCursor;
+    }
+  }
+  const report = inspectHistoryDataset(dataset);
+  console.log(
+    `${sym.info} Versions: ${report.versions.total} total, ${report.versions.archived} archived`
+  );
+  console.log(
+    `${sym.info} Project records: ${report.projectRecords.heads} heads, ${report.projectRecords.snapshots} snapshots, ${report.projectRecords.transactions} transactions`
+  );
+  console.log(
+    `${sym.info} Project cleanup candidates: ${report.projectRecords.unreachableSnapshots} unreachable snapshots, ${report.projectRecords.unreachableTransactions} unreachable transactions, ${report.projectRecords.duplicateSemanticSnapshots} duplicate semantic snapshots`
+  );
+  console.log(
+    `${sym.info} Wiki: ${report.wiki.heads} heads, ${report.wiki.snapshots} snapshots, ${report.wiki.transactions} transactions, ${report.wiki.documents} documents, ${report.wiki.revisions} revisions`
+  );
+  console.log(
+    `${sym.info} Wiki cleanup candidates: ${report.wiki.unreachableSnapshots} unreachable snapshots, ${report.wiki.unreachableTransactions} unreachable transactions, ${report.wiki.unreachableDocuments} unreachable documents, ${report.wiki.unreachableRevisions} unreachable revisions`
+  );
+  console.log(
+    `${sym.info} Wiki duplicates: ${report.wiki.duplicateSemanticSnapshots} semantic snapshots, ${report.wiki.duplicateSemanticDocuments} semantic documents`
+  );
+  console.log(
+    `${sym.info} Broken references: ${report.brokenReferences.length}`
+  );
+  for (const broken of report.brokenReferences.slice(0, 20)) {
+    console.log(`  ${broken}`);
+  }
+  if (report.brokenReferences.length > 20) {
+    console.log(
+      `  ... ${report.brokenReferences.length - 20} additional broken references`
+    );
+  }
+}
+function printPlan(plan) {
+  const scope = plan.versionId === null ? plan.projectId : `${plan.projectId}/${plan.versionId}`;
+  console.log(`${sym.info} Scope: ${scope}`);
+  console.log(`${sym.info} Mode: ${plan.mode}`);
+  console.log(
+    `${sym.info} Project records: ${plan.counts.removableSnapshots} snapshots and ${plan.counts.removableTransactions} transactions removable`
+  );
+  if (plan.wikiCounts !== null) {
+    console.log(
+      `${sym.info} Wiki: ${plan.wikiCounts.removableSnapshots} snapshots, ${plan.wikiCounts.removableTransactions} transactions, and ${plan.wikiCounts.removableDocuments} documents removable`
+    );
+  }
+  console.log(
+    `${sym.info} Current baseline: project=${String(plan.compactionCurrent)} wiki=${String(plan.wikiCompactionCurrent)}`
+  );
+  console.log(`Apply with: neo history apply --plan ${plan.id}`);
+}
+function printRunStatus(status) {
+  const scope = status.versionId === null ? status.projectId : `${status.projectId}/${status.versionId}`;
+  console.log(`${sym.info} Run: ${status.runId}`);
+  console.log(`${sym.info} Plan: ${status.planId}`);
+  console.log(`${sym.info} Scope: ${scope}`);
+  console.log(`${sym.info} State: ${status.state} (${status.phase})`);
+  console.log(
+    `${sym.info} Correctness verification: ${status.verified ? "verified" : "pending"}`
+  );
+  if (status.lastError !== null) {
+    console.log(`${sym.info} Error: ${status.lastError}`);
+  }
+}
+function assertHistoryOptions(options) {
+  const planningOrRead = options.command === "inspect" || options.command === "log" || options.command === "prune" || options.command === "flatten";
+  if (planningOrRead) {
+    if (options.planId !== null || options.runId !== null) {
+      throw new Error(
+        `neo history ${options.command} does not accept --plan or --run.`
+      );
+    }
+    if (options.confirmScope !== null) {
+      throw new Error(
+        `neo history ${options.command} does not accept --confirm-scope.`
+      );
+    }
+    if ((options.command === "inspect" || options.command === "prune") && options.versionSelector !== null) {
+      throw new Error(
+        `neo history ${options.command} is project-scoped and does not accept --version.`
+      );
+    }
+    return;
+  }
+  if (options.command === "apply") {
+    if (options.planId === null) {
+      throw new Error("neo history apply requires --plan <plan-id>.");
+    }
+    if (options.runId !== null) {
+      throw new Error("neo history apply does not accept --run.");
+    }
+    return;
+  }
+  if (options.runId === null) {
+    throw new Error(`neo history ${options.command} requires --run <run-id>.`);
+  }
+  if (options.planId !== null || options.confirmScope !== null) {
+    throw new Error(
+      `neo history ${options.command} does not accept --plan or --confirm-scope.`
+    );
+  }
+}
+var init_history = __esm({
+  "src/commands/history.ts"() {
+    "use strict";
+    init_convex();
+    init_ui();
+    init_history_selection();
+    init_history_inspect();
+  }
+});
+
 // src/commands/doctor.ts
 var doctor_exports = {};
 __export(doctor_exports, {
@@ -44574,16 +45142,19 @@ var KNOWN_FLAGS = /* @__PURE__ */ new Set([
   "out",
   "profile",
   "project",
+  "plan",
   "push",
   "replace",
   "reset",
   "returns",
+  "run",
   "save",
   "save-project",
   "server",
   "skip-invalid",
   "status",
   "summary",
+  "confirm-scope",
   "target",
   "template",
   "theirs",
@@ -44681,6 +45252,7 @@ ${h("Branches & releases")}
   merge     ${d("[source] [--dry-run] [--migrate] [--mine|--theirs <kind>:<id>,...]")}
   release   ${d("cut [--bump ...] | publish <ref> | archive <ref> | restore <ref>")}
   channel   ${d("list | create | edit | delete")}
+  history   ${d("inspect | log | prune | flatten | apply | status | resume")}
 
 ${h("Content & scripts")}
   values    ${d("list | get | set | create | delete | ...")}          loc       ${d("locales | list | set | archive | restore | ...")}
@@ -44748,6 +45320,46 @@ ${h("Usage")}
 Neo checks Unity 6000's existing runtime first, then a compatible system
 dotnet. It never downloads or installs a runtime. Set NEO_DOTNET_HOST to use
 an explicit host.
+`;
+  }
+  if (command === "history") {
+    return `${h("neo history")} \u2014 inspect and deliberately rewrite project history
+
+${h("Usage")}
+  neo history inspect ${d("[--project <id|@latest|@current>]")}
+  neo history log ${d("[--project <id|@latest|@current>] [--version <id|@latest|@current>]")}
+  neo history prune ${d("[--project <id|@latest|@current>]")}
+  neo history flatten ${d("[--project <id|@latest|@current>] [--version <id|@latest|@current>]")}
+  neo history apply --plan <plan-id> ${d("[--confirm-scope <project-id>[/<version-id>]]")}
+  neo history status --run <run-id>
+  neo history resume --run <run-id>
+
+${h("Commands")}
+  inspect  ${d("Read-only project history audit; creates no plan.")}
+  log      ${d("Show retained history for exactly one version.")}
+  prune    ${d("Create an immutable plan for rows proven unreachable; writes nothing.")}
+  flatten  ${d("Create an immutable one-version baseline plan; writes nothing.")}
+  apply    ${d("Begin the destructive execution of an immutable plan.")}
+  status   ${d("Report execution phase, result, and correctness verification.")}
+  resume   ${d("Restart a stopped retryable execution.")}
+
+${h("Arguments")}
+  --project <id|@latest|@current>
+            ${d("Stable project ID, or latest authorized project. Blank interactive input uses latest.")}
+  --version <id|@latest|@current>
+            ${d("Stable version ID in the resolved project, or latest unarchived version. Blank interactive input uses latest.")}
+  --plan <id>
+            ${d("Immutable plan returned by prune or flatten.")}
+  --run <id>
+            ${d("Execution returned by apply.")}
+  --confirm-scope <project>[/<version>]
+            ${d("Exact resolved production scope acknowledgement.")}
+
+${h("Selection")}
+  ${d("Project resolution always happens before version resolution. @latest and @current are aliases. apply, status, and resume use immutable plan/run scope and do not accept project or version selectors.")}
+
+There is no --dry-run: prune and flatten are always non-mutating until apply.
+There is no --keep-current: preserving current semantic state defines flatten.
 `;
   }
   return usage();
@@ -44788,6 +45400,30 @@ async function main() {
         });
       }
       return;
+    case "history": {
+      const sub = args.positional[0];
+      if (sub !== "inspect" && sub !== "log" && sub !== "prune" && sub !== "flatten" && sub !== "apply" && sub !== "status" && sub !== "resume") {
+        throw new Error(
+          "neo history requires a subcommand: inspect | log | prune | flatten | apply | status | resume."
+        );
+      }
+      if ((sub === "apply" || sub === "status" || sub === "resume") && (stringFlag(args, "project") !== null || stringFlag(args, "version") !== null)) {
+        throw new Error(
+          `neo history ${sub} derives its immutable scope from the plan or run and does not accept --project or --version.`
+        );
+      }
+      const { runHistory: runHistory2 } = await Promise.resolve().then(() => (init_history(), history_exports));
+      await runHistory2({
+        apiBaseUrl,
+        command: sub,
+        projectSelector: stringFlag(args, "project"),
+        versionSelector: stringFlag(args, "version"),
+        planId: stringFlag(args, "plan"),
+        runId: stringFlag(args, "run"),
+        confirmScope: stringFlag(args, "confirm-scope")
+      });
+      return;
+    }
     case "pull": {
       const workspace = loadWorkspaceForCommand(args);
       const { runPull: runPull2 } = await Promise.resolve().then(() => (init_pull(), pull_exports));

package/dist/tooling/schema-contract.json

@@ -4,7 +4,7 @@
   "manifestName": "neo-schema-manifest-v3",
   "protocolVersion": 4,
   "sdkVersion": "3.0.0",
-  "cliVersion": "0.3.0",
+  "cliVersion": "0.3.1",
   "apiTarget": "netstandard2.1",
   "referenceAssemblySet": "NETStandard.Library.Ref/2.1.0",
   "requiredToolingFiles": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Neo Compose schema-as-code CLI with compiler-backed C# authoring and bidirectional sync.",
   "license": "MIT",
   "type": "module",