@topogram/cli 0.3.64 → 0.3.65

package/src/cli/commands/import/adopt.js

@@ -0,0 +1,170 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { buildTopogramImportStatus } from "../../../import/provenance.js";
+import { runWorkflow } from "../../../workflows.js";
+import { CLI_PACKAGE_NAME, readInstalledCliPackageVersion } from "../package.js";
+import {
+  appendImportAdoptionReceipt,
+  importAdoptCommand,
+  importProjectCommandPath,
+  projectFileHash
+} from "./paths.js";
+import { readImportAdoptionArtifacts } from "./plan.js";
+import { writeRelativeFiles } from "./workspace.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {string} outputRoot
+ * @param {string[]} writtenFiles
+ * @returns {AnyRecord[]}
+ */
+export function writtenFileHashesForReceipt(outputRoot, writtenFiles) {
+  return (writtenFiles || []).map((relativePath) => {
+    const filePath = path.join(outputRoot, relativePath);
+    const hash = fs.existsSync(filePath) ? projectFileHash(filePath) : null;
+    return {
+      path: relativePath,
+      sha256: hash?.sha256 || null,
+      size: hash?.size || null
+    };
+  });
+}
+
+/**
+ * @param {{ artifacts: AnyRecord, selector: string, options: AnyRecord, importStatus: AnyRecord, summary: AnyRecord, writtenFiles: string[], outputRoot: string }} input
+ * @returns {AnyRecord}
+ */
+export function buildImportAdoptionReceipt({ artifacts, selector, options, importStatus, summary, writtenFiles, outputRoot }) {
+  return {
+    type: "topogram_import_adoption_receipt",
+    version: "0.1",
+    timestamp: new Date().toISOString(),
+    cli: {
+      packageName: CLI_PACKAGE_NAME,
+      version: readInstalledCliPackageVersion()
+    },
+    projectRoot: artifacts.projectRoot,
+    topogramRoot: artifacts.topogramRoot,
+    selector,
+    mode: "write",
+    dryRun: false,
+    forced: Boolean(options.force),
+    reason: options.reason || null,
+    sourceProvenance: {
+      ok: importStatus.ok,
+      status: importStatus.status,
+      path: importStatus.path || null,
+      changed: importStatus.content?.changed || [],
+      added: importStatus.content?.added || [],
+      removed: importStatus.content?.removed || []
+    },
+    promotedCanonicalItems: (summary.promoted_canonical_items || []).map((/** @type {AnyRecord} */ item) => ({
+      bundle: item.bundle || null,
+      kind: item.kind || null,
+      item: item.item || null,
+      canonicalRelPath: item.canonical_rel_path || null,
+      sourcePath: item.source_path || null,
+      changeType: item.change_type || null
+    })),
+    writtenFiles,
+    writtenFileHashes: writtenFileHashesForReceipt(outputRoot, writtenFiles),
+    outputRoot
+  };
+}
+
+/**
+ * @param {string} selector
+ * @param {string} inputPath
+ * @param {{ write?: boolean, dryRun?: boolean, force?: boolean, reason?: string|null, refreshAdopted?: boolean }} [options]
+ * @returns {AnyRecord}
+ */
+export function buildBrownfieldImportAdoptPayload(selector, inputPath, options = {}) {
+  if (!selector) {
+    throw new Error("Missing required <selector>. Example: topogram import adopt bundle:task --dry-run");
+  }
+  if (options.write && options.dryRun) {
+    throw new Error("Use either --dry-run or --write, not both.");
+  }
+  if (options.write && options.force && !options.reason) {
+    throw new Error("Forced import adoption writes require --reason <text>.");
+  }
+  const artifacts = readImportAdoptionArtifacts(inputPath);
+  const importStatus = buildTopogramImportStatus(artifacts.projectRoot);
+  if (options.write && !options.force && !importStatus.ok) {
+    throw new Error(`Refusing to write import adoption because brownfield source provenance is ${importStatus.status}. Run 'topogram import check ${importProjectCommandPath(artifacts.projectRoot)}', review the changed source evidence, rerun import, or pass --force --reason <text> after review.`);
+  }
+  const result = runWorkflow("reconcile", artifacts.projectRoot, {
+    adopt: selector,
+    write: Boolean(options.write),
+    refreshAdopted: Boolean(options.refreshAdopted)
+  });
+  const outputRoot = path.resolve(result.defaultOutDir || artifacts.topogramRoot);
+  const writtenFiles = options.write ? writeRelativeFiles(outputRoot, result.files || {}) : [];
+  const summary = result.summary || {};
+  const receipt = options.write
+    ? buildImportAdoptionReceipt({ artifacts, selector, options, importStatus, summary, writtenFiles, outputRoot })
+    : null;
+  const receiptPath = receipt ? appendImportAdoptionReceipt(artifacts.projectRoot, receipt) : null;
+  return {
+    ok: true,
+    projectRoot: artifacts.projectRoot,
+    topogramRoot: artifacts.topogramRoot,
+    selector,
+    dryRun: !options.write,
+    write: Boolean(options.write),
+    forced: Boolean(options.force),
+    reason: options.reason || null,
+    outputRoot,
+    promotedCanonicalItemCount: (summary.promoted_canonical_items || []).length,
+    promotedCanonicalItems: summary.promoted_canonical_items || [],
+    writtenFiles,
+    receipt,
+    receiptPath,
+    adoption: summary,
+    import: importStatus,
+    warnings: options.write && options.force && !importStatus.ok
+      ? [`Brownfield source provenance is ${importStatus.status}; adoption write was forced with reason: ${options.reason}.`]
+      : [],
+    nextCommands: options.write
+      ? [
+          `topogram import history ${importProjectCommandPath(artifacts.projectRoot)}`,
+          `topogram import status ${importProjectCommandPath(artifacts.projectRoot)}`,
+          `topogram check ${importProjectCommandPath(artifacts.projectRoot)}`
+        ]
+      : [
+          importAdoptCommand(artifacts.projectRoot, selector, true),
+          `topogram import status ${importProjectCommandPath(artifacts.projectRoot)}`
+        ]
+  };
+}
+
+/**
+ * @param {AnyRecord} payload
+ * @returns {void}
+ */
+export function printBrownfieldImportAdopt(payload) {
+  console.log(`${payload.dryRun ? "Previewed" : "Applied"} import adoption for ${payload.selector}.`);
+  console.log(`Project: ${payload.projectRoot}`);
+  console.log(`Promoted canonical items: ${payload.promotedCanonicalItemCount}`);
+  console.log(`Written files: ${payload.writtenFiles.length}`);
+  if (payload.receiptPath) {
+    console.log(`Receipt: ${payload.receiptPath}`);
+  }
+  if (payload.dryRun) {
+    console.log("No files were written. Re-run with --write to promote these candidates.");
+  }
+  for (const warning of payload.warnings || []) {
+    console.log(`Warning: ${warning}`);
+  }
+  console.log("");
+  console.log("Next steps:");
+  for (const command of payload.nextCommands) {
+    console.log(`  ${command}`);
+  }
+}

package/src/cli/commands/import/check.js

@@ -0,0 +1,91 @@
+// @ts-check
+
+import { parsePath } from "../../../parser.js";
+import {
+  loadProjectConfig,
+  validateProjectConfig,
+  validateProjectOutputOwnership
+} from "../../../project-config.js";
+import { resolveWorkspace } from "../../../resolver.js";
+import { validateProjectImplementationTrust } from "../../../template-trust.js";
+import { buildTopogramImportStatus } from "../../../import/provenance.js";
+import {
+  checkSummaryPayload,
+  combineProjectValidationResults,
+  normalizeProjectRoot
+} from "./paths.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {string} inputPath
+ * @returns {ReturnType<typeof checkSummaryPayload>}
+ */
+export function buildTopogramCheckPayloadForPath(inputPath) {
+  const ast = parsePath(inputPath);
+  const resolved = resolveWorkspace(ast);
+  const explicitProjectConfig = loadProjectConfig(inputPath);
+  const projectValidation = explicitProjectConfig
+    ? combineProjectValidationResults(
+        validateProjectConfig(explicitProjectConfig.config, resolved.ok ? resolved.graph : null, { configDir: explicitProjectConfig.configDir }),
+        validateProjectOutputOwnership(explicitProjectConfig),
+        validateProjectImplementationTrust(explicitProjectConfig)
+      )
+    : { ok: false, errors: [{ message: "Missing topogram.project.json or compatible topogram.implementation.json", loc: null }] };
+  return checkSummaryPayload({ inputPath, ast, resolved, projectConfigInfo: explicitProjectConfig, projectValidation });
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, projectRoot: string, import: ReturnType<typeof buildTopogramImportStatus>, topogram: ReturnType<typeof buildTopogramCheckPayloadForPath>, errors: any[] }}
+ */
+export function buildBrownfieldImportCheckPayload(projectRoot) {
+  const resolvedRoot = normalizeProjectRoot(projectRoot);
+  const importStatus = buildTopogramImportStatus(resolvedRoot);
+  const topogramCheck = buildTopogramCheckPayloadForPath(resolvedRoot);
+  return {
+    ok: importStatus.ok && topogramCheck.ok,
+    projectRoot: resolvedRoot,
+    import: importStatus,
+    topogram: topogramCheck,
+    errors: [
+      ...(importStatus.errors || []).map((/** @type {string} */ message) => ({ source: "import", message })),
+      ...(topogramCheck.errors || [])
+    ]
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildBrownfieldImportCheckPayload>} payload
+ * @returns {void}
+ */
+export function printBrownfieldImportCheck(payload) {
+  console.log(`Topogram import check: ${payload.import.status}`);
+  console.log(`Project: ${payload.projectRoot}`);
+  if (payload.import.source?.source?.path) {
+    console.log(`Imported source: ${payload.import.source.source.path}`);
+  }
+  console.log(`Provenance: ${payload.import.path}`);
+  if (payload.import.source?.files) {
+    console.log(`Trusted source files: ${payload.import.source.files.length}`);
+  }
+  if (payload.import.status === "changed") {
+    console.log(`Changed source files: ${payload.import.content.changed.length}`);
+    console.log(`Added source files: ${payload.import.content.added.length}`);
+    console.log(`Removed source files: ${payload.import.content.removed.length}`);
+  }
+  console.log(`Topogram check: ${payload.topogram.ok ? "passed" : "failed"}`);
+  console.log("Imported Topogram artifacts are project-owned; import check compares only the brownfield source hashes trusted at import time plus normal Topogram validity.");
+  for (const diagnostic of payload.import.diagnostics || []) {
+    const label = diagnostic.severity === "warning" ? "Warning" : "Error";
+    console.log(`${label}: ${diagnostic.message}`);
+    if (diagnostic.suggestedFix) {
+      console.log(`Fix: ${diagnostic.suggestedFix}`);
+    }
+  }
+  for (const error of payload.topogram.errors || []) {
+    console.log(`Error: ${error.message}`);
+  }
+}

package/src/cli/commands/import/diff.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+import { importProjectCommandPath } from "./paths.js";
+import { buildBrownfieldImportRefreshAnalysis } from "./refresh.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {string} inputPath
+ * @param {{ sourcePath?: string|null }} [options]
+ * @returns {AnyRecord}
+ */
+export function buildBrownfieldImportDiffPayload(inputPath, options = {}) {
+  const analysis = buildBrownfieldImportRefreshAnalysis(inputPath, options);
+  return {
+    ok: true,
+    projectRoot: analysis.projectRoot,
+    topogramRoot: analysis.topogramRoot,
+    sourcePath: analysis.sourcePath,
+    provenancePath: analysis.provenancePath,
+    importStatus: analysis.previousImportStatus,
+    sourceDiff: analysis.sourceDiff,
+    tracks: analysis.tracks,
+    sourceFiles: analysis.sourceFiles,
+    candidateCounts: analysis.candidateCounts,
+    candidateCountDeltas: analysis.candidateCountDeltas,
+    adoptionPlanDeltas: analysis.adoptionPlanDeltas,
+    receiptVerification: analysis.receiptVerification,
+    plannedFiles: analysis.plannedFiles,
+    nextCommands: [
+      `topogram import refresh ${importProjectCommandPath(analysis.projectRoot)} --dry-run`,
+      `topogram import refresh ${importProjectCommandPath(analysis.projectRoot)}`,
+      `topogram import plan ${importProjectCommandPath(analysis.projectRoot)}`
+    ]
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildBrownfieldImportDiffPayload>} payload
+ * @returns {void}
+ */
+export function printBrownfieldImportDiff(payload) {
+  console.log(`Import diff for ${payload.projectRoot}`);
+  console.log(`Source: ${payload.sourcePath}`);
+  console.log(`Source status: ${payload.importStatus}`);
+  console.log(`Source diff: changed=${payload.sourceDiff.counts.changed}, added=${payload.sourceDiff.counts.added}, removed=${payload.sourceDiff.counts.removed}`);
+  for (const filePath of [...payload.sourceDiff.changed, ...payload.sourceDiff.added, ...payload.sourceDiff.removed].slice(0, 12)) {
+    const status = payload.sourceDiff.changed.includes(filePath)
+      ? "changed"
+      : payload.sourceDiff.added.includes(filePath)
+        ? "added"
+        : "removed";
+    console.log(`- ${filePath}: ${status}`);
+  }
+  console.log("");
+  console.log("Candidate count changes:");
+  const candidateChanges = payload.candidateCountDeltas.changed || [];
+  if (candidateChanges.length === 0) {
+    console.log("- None");
+  } else {
+    for (const item of candidateChanges) {
+      const sign = item.delta > 0 ? "+" : "";
+      console.log(`- ${item.key}: ${item.previous} -> ${item.next} (${sign}${item.delta})`);
+    }
+  }
+  console.log("");
+  console.log(`Adoption plan changes: added=${payload.adoptionPlanDeltas.added.length}, removed=${payload.adoptionPlanDeltas.removed.length}, changed=${payload.adoptionPlanDeltas.changed.length}`);
+  for (const item of payload.adoptionPlanDeltas.added.slice(0, 8)) {
+    console.log(`- added ${item.bundle}/${item.kind}/${item.item}`);
+  }
+  for (const item of payload.adoptionPlanDeltas.removed.slice(0, 8)) {
+    console.log(`- removed ${item.bundle}/${item.kind}/${item.item}`);
+  }
+  console.log(`Receipt verification: ${payload.receiptVerification.status}`);
+  const receiptSummary = payload.receiptVerification.summary;
+  console.log(`Adopted file audit: changed=${receiptSummary.changedFileCount}, removed=${receiptSummary.removedFileCount}, unverifiable=${receiptSummary.unverifiableFileCount}`);
+  console.log("");
+  console.log("Next steps:");
+  for (const command of payload.nextCommands) {
+    console.log(`  ${command}`);
+  }
+}

package/src/cli/commands/import/help.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
+import { TOPOGRAM_IMPORT_ADOPTIONS_FILE } from "./paths.js";
+
+export function printImportHelp() {
+  console.log("Usage: topogram import <app-path> --out <target> [--from <track[,track]>] [--json]");
+  console.log("   or: topogram import refresh [path] [--from <app-path>] [--dry-run] [--json]");
+  console.log("   or: topogram import diff [path] [--json]");
+  console.log("   or: topogram import check [path] [--json]");
+  console.log("   or: topogram import plan [path] [--json]");
+  console.log("   or: topogram import adopt --list [path] [--json]");
+  console.log("   or: topogram import adopt <selector> [path] [--dry-run|--write] [--force --reason <text>] [--json]");
+  console.log("   or: topogram import status [path] [--json]");
+  console.log("   or: topogram import history [path] [--verify] [--json]");
+  console.log("");
+  console.log("Creates an editable Topogram workspace from a brownfield app without modifying the app.");
+  console.log("");
+  console.log("Behavior:");
+  console.log("  - writes raw import candidates under topogram/candidates/app");
+  console.log("  - writes reconcile proposal bundles under topogram/candidates/reconcile");
+  console.log("  - writes topogram.project.json with maintained ownership and no generated stack binding");
+  console.log(`  - writes ${TOPOGRAM_IMPORT_FILE} with source file hashes from import time`);
+  console.log("  - imported Topogram artifacts are project-owned after creation");
+  console.log("  - refresh rewrites only candidate/reconcile artifacts and source provenance");
+  console.log("  - adoption previews never write canonical Topogram files unless --write is passed");
+  console.log("  - adoption writes refuse dirty brownfield source provenance unless --force is passed");
+  console.log(`  - adoption writes append audit receipts to ${TOPOGRAM_IMPORT_ADOPTIONS_FILE}`);
+  console.log("  - forced adoption writes require --reason <text>");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram import ./existing-app --out ./imported-topogram");
+  console.log("  topogram import ./existing-app --out ./imported-topogram --from db,api,ui");
+  console.log("  topogram import diff ./imported-topogram");
+  console.log("  topogram import refresh ./imported-topogram --from ./existing-app --dry-run");
+  console.log("  topogram import refresh ./imported-topogram --from ./existing-app");
+  console.log("  topogram import check ./imported-topogram");
+  console.log("  topogram import plan ./imported-topogram");
+  console.log("  topogram import adopt --list ./imported-topogram");
+  console.log("  topogram import adopt bundle:task ./imported-topogram --dry-run");
+  console.log("  topogram import adopt bundle:task ./imported-topogram --write");
+  console.log("  topogram import adopt bundle:task ./imported-topogram --write --force --reason \"Reviewed source drift\"");
+  console.log("  topogram import status ./imported-topogram");
+  console.log("  topogram import history ./imported-topogram");
+  console.log("  topogram import history ./imported-topogram --verify");
+  console.log("  topogram import check --json");
+}

package/src/cli/commands/import/paths.js

@@ -0,0 +1,277 @@
+// @ts-check
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../../format.js";
+import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
+import { shellCommandArg } from "../catalog.js";
+
+export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-import-adoptions.jsonl";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function normalizeTopogramPath(inputPath) {
+  const absolute = path.resolve(inputPath);
+  if (path.basename(absolute) === "topogram") {
+    return absolute;
+  }
+  const candidate = path.join(absolute, "topogram");
+  return fs.existsSync(candidate) ? candidate : absolute;
+}
+
+/**
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function normalizeProjectRoot(inputPath) {
+  const absolute = path.resolve(inputPath);
+  if (path.basename(absolute) === "topogram") {
+    return path.dirname(absolute);
+  }
+  return absolute;
+}
+
+/**
+ * @param  {...{ ok: boolean, errors?: any[] }|null|undefined} results
+ * @returns {{ ok: boolean, errors: any[] }}
+ */
+export function combineProjectValidationResults(...results) {
+  const errors = [];
+  for (const result of results) {
+    errors.push(...(result?.errors || []));
+  }
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * @param {AnyRecord} component
+ * @returns {{ uses_api: string|null, uses_database: string|null }}
+ */
+export function topologyComponentReferences(component) {
+  return {
+    uses_api: component.uses_api || null,
+    uses_database: component.uses_database || null
+  };
+}
+
+/**
+ * @param {AnyRecord} component
+ * @returns {any}
+ */
+export function topologyComponentPort(component) {
+  return Object.prototype.hasOwnProperty.call(component, "port") ? component.port : null;
+}
+
+/**
+ * @param {AnyRecord|null|undefined} config
+ * @returns {{ outputs: any[], runtimes: any[], edges: any[] }}
+ */
+export function summarizeProjectTopology(config) {
+  const outputs = Object.entries(config?.outputs || {})
+    .map(([name, output]) => ({
+      name,
+      path: output?.path || null,
+      ownership: output?.ownership || null
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const runtimes = (config?.topology?.runtimes || [])
+    .map((/** @type {AnyRecord} */ component) => ({
+      id: component.id,
+      kind: component.kind,
+      projection: component.projection,
+      generator: {
+        id: component.generator?.id || null,
+        version: component.generator?.version || null
+      },
+      port: topologyComponentPort(component),
+      references: topologyComponentReferences(component)
+    }))
+    .sort((/** @type {AnyRecord} */ left, /** @type {AnyRecord} */ right) => left.id.localeCompare(right.id));
+  const edges = runtimes.flatMap((/** @type {AnyRecord} */ component) => {
+    const references = [];
+    if (component.references.uses_api) {
+      references.push({
+        from: component.id,
+        to: component.references.uses_api,
+        type: "calls_api"
+      });
+    }
+    if (component.references.uses_database) {
+      references.push({
+        from: component.id,
+        to: component.references.uses_database,
+        type: "uses_database"
+      });
+    }
+    return references;
+  }).sort((/** @type {AnyRecord} */ left, /** @type {AnyRecord} */ right) => `${left.from}:${left.type}:${left.to}`.localeCompare(`${right.from}:${right.type}:${right.to}`));
+  return {
+    outputs,
+    runtimes,
+    edges
+  };
+}
+
+/**
+ * @param {AnyRecord|null|undefined} topology
+ * @returns {AnyRecord|null}
+ */
+export function publicProjectTopology(topology) {
+  if (!topology || typeof topology !== "object") {
+    return topology || null;
+  }
+  return {
+    ...Object.fromEntries(Object.entries(topology).filter(([key]) => key !== "components")),
+    runtimes: topology.runtimes || []
+  };
+}
+
+/**
+ * @param {{ inputPath: string, ast: AnyRecord, resolved: AnyRecord, projectConfigInfo: AnyRecord|null, projectValidation: { ok: boolean, errors: any[] } }} input
+ * @returns {AnyRecord}
+ */
+export function checkSummaryPayload({ inputPath, ast, resolved, projectConfigInfo, projectValidation }) {
+  const statementCount = ast.files.flatMap((/** @type {{ statements: any[] }} */ file) => file.statements).length;
+  const projectInfo = projectConfigInfo || {
+    configPath: null,
+    compatibility: false,
+    config: { topology: null }
+  };
+  const resolvedTopology = summarizeProjectTopology(projectInfo.config);
+  return {
+    ok: resolved.ok && projectValidation.ok,
+    inputPath,
+    topogram: {
+      files: ast.files.length,
+      statements: statementCount,
+      valid: resolved.ok
+    },
+    project: {
+      configPath: projectInfo.configPath,
+      compatibility: Boolean(projectInfo.compatibility),
+      valid: projectValidation.ok,
+      topology: publicProjectTopology(projectInfo.config.topology),
+      resolvedTopology
+    },
+    errors: [
+      ...(resolved.ok ? [] : resolved.validation.errors.map((/** @type {AnyRecord} */ error) => ({
+        source: "topogram",
+        message: error.message,
+        loc: error.loc
+      }))),
+      ...projectValidation.errors.map((error) => ({
+        source: "project",
+        message: error.message,
+        loc: error.loc
+      }))
+    ]
+  };
+}
+
+/**
+ * @param {string} filePath
+ * @returns {{ sha256: string, size: number }}
+ */
+export function projectFileHash(filePath) {
+  const bytes = fs.readFileSync(filePath);
+  return {
+    sha256: crypto.createHash("sha256").update(bytes).digest("hex"),
+    size: bytes.length
+  };
+}
+
+/**
+ * @param {string} filePath
+ * @returns {AnyRecord|null}
+ */
+export function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function importAdoptionsPath(projectRoot) {
+  return path.join(normalizeProjectRoot(projectRoot), TOPOGRAM_IMPORT_ADOPTIONS_FILE);
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {AnyRecord[]}
+ */
+export function readImportAdoptionReceipts(projectRoot) {
+  const historyPath = importAdoptionsPath(projectRoot);
+  if (!fs.existsSync(historyPath)) {
+    return [];
+  }
+  return fs.readFileSync(historyPath, "utf8")
+    .split(/\r?\n/)
+    .map((/** @type {string} */ line) => line.trim())
+    .filter(Boolean)
+    .map((/** @type {string} */ line, /** @type {number} */ index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`Invalid import adoption receipt JSON at ${historyPath}:${index + 1}.`);
+      }
+    });
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {AnyRecord} receipt
+ * @returns {string}
+ */
+export function appendImportAdoptionReceipt(projectRoot, receipt) {
+  const historyPath = importAdoptionsPath(projectRoot);
+  fs.appendFileSync(historyPath, `${JSON.stringify(receipt)}\n`, "utf8");
+  return historyPath;
+}
+
+/**
+ * @param {AnyRecord[]} items
+ * @param {string} fieldName
+ * @returns {Record<string, number>}
+ */
+export function countByField(items, fieldName) {
+  /** @type {Record<string, number>} */
+  const counts = {};
+  for (const item of items || []) {
+    const key = item?.[fieldName] || "unknown";
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function importProjectCommandPath(projectRoot) {
+  return shellCommandArg(path.relative(process.cwd(), projectRoot) || ".");
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} selector
+ * @param {boolean} [write]
+ * @returns {string}
+ */
+export function importAdoptCommand(projectRoot, selector, write = false) {
+  return `topogram import adopt ${selector} ${importProjectCommandPath(projectRoot)} ${write ? "--write" : "--dry-run"}`;
+}