@topogram/cli 0.3.78 → 0.3.79

package/src/cli/commands/copy.js

@@ -0,0 +1,356 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  catalogEntryPackageSpec,
+  copyCatalogTopogramEntry,
+  findCatalogEntry,
+  loadCatalog,
+  TOPOGRAM_SOURCE_FILE
+} from "../../catalog.js";
+import { GENERATOR_POLICY_FILE } from "../../generator-policy.js";
+import { createNewProject } from "../../new-project.js";
+import { copyPath, ensureEmptyDirectory } from "../../catalog/files.js";
+import { writeTopogramSourceRecord } from "../../catalog/provenance.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH, resolvePackageWorkspace } from "../../workspace-paths.js";
+import { formatCatalogTemplateAliasError, suggestCatalogTemplateIds } from "../catalog-alias.js";
+import {
+  buildCatalogListPayload,
+  printCatalogList
+} from "./catalog/list.js";
+import { shellCommandArg } from "./catalog/shared.js";
+import { stableStringify } from "../../format.js";
+
+const ENGINE_ROOT = path.resolve(decodeURIComponent(new URL("../../../", import.meta.url).pathname));
+const TEMPLATES_ROOT = path.join(ENGINE_ROOT, "templates");
+
+/**
+ * @param {string} source
+ * @returns {boolean}
+ */
+function isCatalogIdCandidate(source) {
+  return Boolean(source) &&
+    !source.startsWith("@") &&
+    !source.startsWith("./") &&
+    !source.startsWith("../") &&
+    !path.isAbsolute(source) &&
+    !source.includes("/") &&
+    !source.endsWith(".tgz");
+}
+
+/**
+ * @param {ReturnType<typeof createNewProject>} result
+ * @param {string} cwd
+ * @returns {string}
+ */
+function displayProjectRootForCopy(result, cwd) {
+  const relativeProjectRoot = path.relative(cwd, result.projectRoot);
+  return !relativeProjectRoot || relativeProjectRoot.startsWith("..")
+    ? result.projectRoot
+    : relativeProjectRoot;
+}
+
+/**
+ * @param {string} targetPath
+ * @returns {void}
+ */
+function assertProjectTargetOutsideEngine(targetPath) {
+  const projectRoot = path.resolve(targetPath);
+  const relativeToEngine = path.relative(ENGINE_ROOT, projectRoot);
+  if (relativeToEngine === "" || (!relativeToEngine.startsWith("..") && !path.isAbsolute(relativeToEngine))) {
+    throw new Error(
+      `Refusing to copy a project inside the engine directory. Use a path outside engine, for example '../${path.basename(projectRoot)}'.`
+    );
+  }
+}
+
+/**
+ * @param {string} source
+ * @param {string} targetPath
+ * @param {{ catalogSource?: string|null, version?: string|null }} options
+ * @returns {{ ok: boolean, action: "copy_topogram", source: string, id: string, kind: "topogram", packageSpec: string, targetPath: string, provenancePath: string, files: string[], diagnostics: any[], errors: string[] }|null}
+ */
+function tryCopyCatalogTopogram(source, targetPath, options) {
+  if (!isCatalogIdCandidate(source)) {
+    return null;
+  }
+  const loaded = loadCatalog(options.catalogSource || null);
+  const entry = findCatalogEntry(loaded.catalog, source, "topogram");
+  if (!entry) {
+    return null;
+  }
+  const copied = copyCatalogTopogramEntry(entry, targetPath, {
+    catalogSource: loaded.source,
+    version: options.version || null
+  });
+  return {
+    action: "copy_topogram",
+    source: loaded.source,
+    ...copied,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+/**
+ * @param {string} source
+ * @param {string} targetPath
+ * @param {{ catalogSource?: string|null, version?: string|null }} options
+ * @returns {{ templateName: string, provenance: any|null }}
+ */
+function resolveCopyTemplateSource(source, targetPath, options) {
+  void targetPath;
+  if (!isCatalogIdCandidate(source)) {
+    return { templateName: source, provenance: null };
+  }
+  const loaded = loadCatalog(options.catalogSource || null);
+  const entry = findCatalogEntry(loaded.catalog, source, "template");
+  if (!entry) {
+    throw new Error(formatCatalogTemplateAliasError(source, loaded.source, null, {
+      suggestions: suggestCatalogTemplateIds(loaded.catalog, source)
+    }));
+  }
+  const packageSpec = catalogEntryPackageSpec(entry, options.version || null);
+  return {
+    templateName: packageSpec,
+    provenance: {
+      id: entry.id,
+      source: loaded.source,
+      package: entry.package,
+      version: options.version || entry.defaultVersion,
+      packageSpec,
+      includesExecutableImplementation: Boolean(entry.trust?.includesExecutableImplementation)
+    }
+  };
+}
+
+/**
+ * @param {string} sourcePath
+ * @param {string} targetPath
+ * @returns {{ ok: boolean, action: "copy_topogram", source: string, id: string, kind: "topogram", packageSpec: string, targetPath: string, provenancePath: string, files: string[], diagnostics: any[], errors: string[] }}
+ */
+function copyLocalTopogramSource(sourcePath, targetPath) {
+  const packageRoot = path.resolve(sourcePath);
+  if (!fs.existsSync(packageRoot) || !fs.statSync(packageRoot).isDirectory()) {
+    throw new Error(`Copy source '${sourcePath}' was not found.`);
+  }
+  if (fs.existsSync(path.join(packageRoot, "implementation"))) {
+    throw new Error(`Topogram source '${sourcePath}' contains implementation/, which is not allowed for pure topogram copy.`);
+  }
+  const packageWorkspace = resolvePackageWorkspace(packageRoot);
+  const resolvedTarget = path.resolve(targetPath);
+  ensureEmptyDirectory(resolvedTarget);
+  /** @type {string[]} */
+  const files = [];
+  copyPath(packageWorkspace.root, path.join(resolvedTarget, DEFAULT_TOPO_FOLDER_NAME), DEFAULT_TOPO_FOLDER_NAME, files);
+  for (const fileName of ["topogram.project.json", "README.md"]) {
+    const sourceFile = path.join(packageRoot, fileName);
+    if (!fs.existsSync(sourceFile) || !fs.statSync(sourceFile).isFile()) {
+      continue;
+    }
+    if (fileName === "topogram.project.json") {
+      const projectConfig = JSON.parse(fs.readFileSync(sourceFile, "utf8"));
+      projectConfig.workspace = DEFAULT_WORKSPACE_PATH;
+      fs.writeFileSync(path.join(resolvedTarget, fileName), `${JSON.stringify(projectConfig, null, 2)}\n`, "utf8");
+      files.push(fileName);
+    } else {
+      copyPath(sourceFile, path.join(resolvedTarget, fileName), fileName, files);
+    }
+  }
+  const sourceId = path.basename(packageRoot);
+  const provenance = writeTopogramSourceRecord(resolvedTarget, {
+    catalogSource: null,
+    entry: {
+      id: sourceId,
+      package: sourcePath,
+      defaultVersion: "local"
+    },
+    packageSpec: sourcePath,
+    version: "local"
+  });
+  return {
+    ok: true,
+    action: "copy_topogram",
+    source: sourcePath,
+    id: sourceId,
+    kind: "topogram",
+    packageSpec: sourcePath,
+    targetPath: resolvedTarget,
+    provenancePath: provenance.path,
+    files: files.sort((a, b) => a.localeCompare(b)),
+    diagnostics: [],
+    errors: []
+  };
+}
+
+/**
+ * @param {ReturnType<typeof createNewProject>} result
+ * @returns {Record<string, any>}
+ */
+function templateCopyPayload(result) {
+  return {
+    ok: true,
+    action: "copy_template",
+    kind: "template",
+    projectRoot: result.projectRoot,
+    templateName: result.templateName,
+    template: result.template,
+    topogramPath: result.topogramPath,
+    appPath: result.appPath,
+    warnings: result.warnings,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+/**
+ * @param {ReturnType<typeof createNewProject>} result
+ * @param {string} cwd
+ * @returns {void}
+ */
+export function printTemplateCopyResult(result, cwd) {
+  const template = result.template || {};
+  console.log(`Copied Topogram template to ${result.projectRoot}.`);
+  console.log(`Template: ${result.templateName}`);
+  console.log(`Source: ${template.source || "unknown"}`);
+  if (template.sourceSpec) {
+    console.log(`Source spec: ${template.sourceSpec}`);
+  }
+  if (template.catalog) {
+    console.log(`Catalog: ${template.catalog.id} from ${template.catalog.source}`);
+    console.log(`Package: ${template.catalog.packageSpec}`);
+  }
+  console.log(`Executable implementation: ${template.includesExecutableImplementation ? "yes" : "no"}`);
+  console.log("Policy: topogram.template-policy.json");
+  console.log(`Generator policy: ${GENERATOR_POLICY_FILE}`);
+  console.log("Template files: .topogram-template-files.json");
+  if (template.includesExecutableImplementation) {
+    console.log("Trust: .topogram-template-trust.json");
+  }
+  for (const warning of result.warnings) {
+    console.warn(`Warning: ${warning}`);
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${displayProjectRootForCopy(result, cwd)}`);
+  console.log("  npm install");
+  console.log("  npm run agent:brief");
+  console.log("  npm run doctor");
+  console.log("  npm run source:status");
+  console.log("  npm run template:explain");
+  console.log("  npm run check");
+  console.log("  npm run generator:policy:status");
+  console.log("  npm run generator:policy:check");
+  if (template.includesExecutableImplementation) {
+    console.log("  npm run template:policy:explain");
+    console.log("  npm run trust:status");
+  }
+  console.log("  npm run generate");
+  console.log("  npm run verify");
+}
+
+/**
+ * @param {any} payload
+ * @returns {void}
+ */
+export function printTopogramCopy(payload) {
+  console.log(`Copied topogram '${payload.id}' to ${payload.targetPath}.`);
+  console.log(`Package: ${payload.packageSpec}`);
+  console.log(`Source provenance: ${payload.provenancePath}`);
+  console.log(`Files: ${payload.files.length}`);
+  console.log(`${TOPOGRAM_SOURCE_FILE} records copy provenance only. Local edits are allowed.`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${shellCommandArg(path.relative(process.cwd(), payload.targetPath) || ".")}`);
+  console.log("  topogram source status --local");
+  console.log("  topogram check");
+  console.log("  topogram generate");
+}
+
+/**
+ * @param {{ commandArgs: Record<string, any>, catalogSource?: string|null, requestedVersion?: string|null, json?: boolean, cwd?: string }} context
+ * @returns {number}
+ */
+export function runCopyCommand(context) {
+  const {
+    commandArgs,
+    catalogSource = null,
+    requestedVersion = null,
+    json = false,
+    cwd = process.cwd()
+  } = context;
+
+  if (commandArgs.copyCommand === "list") {
+    const payload = buildCatalogListPayload(catalogSource || null);
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printCatalogList(payload);
+    }
+    return 0;
+  }
+
+  const source = commandArgs.copySource;
+  const targetPath = commandArgs.inputPath;
+  if (!source || String(source).startsWith("-")) {
+    throw new Error("topogram copy requires <source>.");
+  }
+  if (!targetPath || String(targetPath).startsWith("-")) {
+    throw new Error("topogram copy requires <target>.");
+  }
+  assertProjectTargetOutsideEngine(targetPath);
+
+  let catalogTopogram;
+  try {
+    catalogTopogram = tryCopyCatalogTopogram(source, targetPath, {
+      catalogSource,
+      version: requestedVersion
+    });
+  } catch (error) {
+    if (isCatalogIdCandidate(source)) {
+      throw new Error(formatCatalogTemplateAliasError(source, catalogSource || null, error));
+    }
+    throw error;
+  }
+  if (catalogTopogram) {
+    if (json) {
+      console.log(stableStringify(catalogTopogram));
+    } else {
+      printTopogramCopy(catalogTopogram);
+    }
+    return catalogTopogram.ok ? 0 : 1;
+  }
+
+  if (source === "." || source.startsWith("./") || source.startsWith("../") || path.isAbsolute(source)) {
+    const localRoot = path.resolve(source);
+    if (fs.existsSync(path.join(localRoot, DEFAULT_TOPO_FOLDER_NAME)) && !fs.existsSync(path.join(localRoot, "topogram-template.json"))) {
+      const payload = copyLocalTopogramSource(source, targetPath);
+      if (json) {
+        console.log(stableStringify(payload));
+      } else {
+        printTopogramCopy(payload);
+      }
+      return payload.ok ? 0 : 1;
+    }
+  }
+
+  const resolvedTemplate = resolveCopyTemplateSource(source, targetPath, {
+    catalogSource,
+    version: requestedVersion
+  });
+  const result = createNewProject({
+    targetPath,
+    templateName: resolvedTemplate.templateName,
+    templateProvenance: resolvedTemplate.provenance,
+    engineRoot: ENGINE_ROOT,
+    templatesRoot: TEMPLATES_ROOT
+  });
+  if (json) {
+    console.log(stableStringify(templateCopyPayload(result)));
+  } else {
+    printTemplateCopyResult(result, cwd);
+  }
+  return 0;
+}

package/src/cli/commands/doctor.js

@@ -37,7 +37,7 @@ export function printDoctorHelp() {
   console.log("  npm install --save-dev @topogram/cli");
   console.log("  npx topogram doctor");
   console.log("  npx topogram template list");
-  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("  npx topogram copy hello-web ./my-app");
   console.log("");
   console.log("Related setup commands:");
   console.log("  topogram setup package-auth");

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

@@ -42,7 +42,7 @@ export function writtenFileHashesForReceipt(outputRoot, writtenFiles) {
  */
 export function buildImportAdoptionReceipt({ artifacts, selector, options, importStatus, summary, writtenFiles, outputRoot }) {
   return {
-    type: "topogram_import_adoption_receipt",
+    type: "topogram_adoption_receipt",
     version: "0.1",
     timestamp: new Date().toISOString(),
     cli: {
@@ -87,18 +87,18 @@ export function buildImportAdoptionReceipt({ artifacts, selector, options, impor
  */
 export function buildBrownfieldImportAdoptPayload(selector, inputPath, options = {}) {
   if (!selector) {
-    throw new Error("Missing required <selector>. Example: topogram import adopt bundle:task --dry-run");
+    throw new Error("Missing required <selector>. Example: topogram 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>.");
+    throw new Error("Forced 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.`);
+    throw new Error(`Refusing to write adoption because brownfield source provenance is ${importStatus.status}. Run 'topogram extract check ${importProjectCommandPath(artifacts.projectRoot)}', review the changed source evidence, rerun extract, or pass --force --reason <text> after review.`);
   }
   const result = runWorkflow("reconcile", artifacts.projectRoot, {
     adopt: selector,
@@ -129,19 +129,19 @@ export function buildBrownfieldImportAdoptPayload(selector, inputPath, options =
     receipt,
     receiptPath,
     adoption: summary,
-    import: importStatus,
+    extract: 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 extract history ${importProjectCommandPath(artifacts.projectRoot)}`,
+          `topogram extract status ${importProjectCommandPath(artifacts.projectRoot)}`,
           `topogram check ${importProjectCommandPath(artifacts.projectRoot)}`
         ]
       : [
           importAdoptCommand(artifacts.projectRoot, selector, true),
-          `topogram import status ${importProjectCommandPath(artifacts.projectRoot)}`
+          `topogram extract status ${importProjectCommandPath(artifacts.projectRoot)}`
         ]
   };
 }
@@ -151,7 +151,7 @@ export function buildBrownfieldImportAdoptPayload(selector, inputPath, options =
  * @returns {void}
  */
 export function printBrownfieldImportAdopt(payload) {
-  console.log(`${payload.dryRun ? "Previewed" : "Applied"} import adoption for ${payload.selector}.`);
+  console.log(`${payload.dryRun ? "Previewed" : "Applied"} adoption for ${payload.selector}.`);
   console.log(`Project: ${payload.projectRoot}`);
   console.log(`Promoted canonical items: ${payload.promotedCanonicalItemCount}`);
   console.log(`Written files: ${payload.writtenFiles.length}`);

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

@@ -40,7 +40,7 @@ export function buildTopogramCheckPayloadForPath(inputPath) {
 
 /**
  * @param {string} projectRoot
- * @returns {{ ok: boolean, projectRoot: string, workspaceRoot: string, import: ReturnType<typeof buildTopogramImportStatus>, topogram: ReturnType<typeof buildTopogramCheckPayloadForPath>, errors: any[] }}
+ * @returns {{ ok: boolean, projectRoot: string, workspaceRoot: string, extract: ReturnType<typeof buildTopogramImportStatus>, topogram: ReturnType<typeof buildTopogramCheckPayloadForPath>, errors: any[] }}
  */
 export function buildBrownfieldImportCheckPayload(projectRoot) {
   const resolvedRoot = normalizeProjectRoot(projectRoot);
@@ -50,10 +50,10 @@ export function buildBrownfieldImportCheckPayload(projectRoot) {
     ok: importStatus.ok && topogramCheck.ok,
     projectRoot: resolvedRoot,
     workspaceRoot: normalizeTopogramPath(resolvedRoot),
-    import: importStatus,
+    extract: importStatus,
     topogram: topogramCheck,
     errors: [
-      ...(importStatus.errors || []).map((/** @type {string} */ message) => ({ source: "import", message })),
+      ...(importStatus.errors || []).map((/** @type {string} */ message) => ({ source: "extract", message })),
       ...(topogramCheck.errors || [])
     ]
   };
@@ -64,23 +64,23 @@ export function buildBrownfieldImportCheckPayload(projectRoot) {
  * @returns {void}
  */
 export function printBrownfieldImportCheck(payload) {
-  console.log(`Topogram import check: ${payload.import.status}`);
+  console.log(`Topogram extract check: ${payload.extract.status}`);
   console.log(`Project: ${payload.projectRoot}`);
-  if (payload.import.source?.source?.path) {
-    console.log(`Imported source: ${payload.import.source.source.path}`);
+  if (payload.extract.source?.source?.path) {
+    console.log(`Extracted source: ${payload.extract.source.source.path}`);
   }
-  console.log(`Provenance: ${payload.import.path}`);
-  if (payload.import.source?.files) {
-    console.log(`Trusted source files: ${payload.import.source.files.length}`);
+  console.log(`Provenance: ${payload.extract.path}`);
+  if (payload.extract.source?.files) {
+    console.log(`Trusted source files: ${payload.extract.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}`);
+  if (payload.extract.status === "changed") {
+    console.log(`Changed source files: ${payload.extract.content.changed.length}`);
+    console.log(`Added source files: ${payload.extract.content.added.length}`);
+    console.log(`Removed source files: ${payload.extract.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 || []) {
+  console.log("Extracted Topogram artifacts are project-owned; extract check compares only the brownfield source hashes trusted at extraction time plus normal Topogram validity.");
+  for (const diagnostic of payload.extract.diagnostics || []) {
     const label = diagnostic.severity === "warning" ? "Warning" : "Error";
     console.log(`${label}: ${diagnostic.message}`);
     if (diagnostic.suggestedFix) {

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

@@ -21,7 +21,7 @@ export function buildBrownfieldImportDiffPayload(inputPath, options = {}) {
     topogramRoot: analysis.topogramRoot,
     sourcePath: analysis.sourcePath,
     provenancePath: analysis.provenancePath,
-    importStatus: analysis.previousImportStatus,
+    extractStatus: analysis.previousImportStatus,
     sourceDiff: analysis.sourceDiff,
     tracks: analysis.tracks,
     sourceFiles: analysis.sourceFiles,
@@ -31,9 +31,9 @@ export function buildBrownfieldImportDiffPayload(inputPath, options = {}) {
     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)}`
+      `topogram extract refresh ${importProjectCommandPath(analysis.projectRoot)} --dry-run`,
+      `topogram extract refresh ${importProjectCommandPath(analysis.projectRoot)}`,
+      `topogram extract plan ${importProjectCommandPath(analysis.projectRoot)}`
     ]
   };
 }
@@ -43,9 +43,9 @@ export function buildBrownfieldImportDiffPayload(inputPath, options = {}) {
  * @returns {void}
  */
 export function printBrownfieldImportDiff(payload) {
-  console.log(`Import diff for ${payload.projectRoot}`);
+  console.log(`Extraction diff for ${payload.projectRoot}`);
   console.log(`Source: ${payload.sourcePath}`);
-  console.log(`Source status: ${payload.importStatus}`);
+  console.log(`Source status: ${payload.extractStatus}`);
   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)

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

@@ -3,46 +3,55 @@
 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]");
+export function printExtractHelp() {
+  console.log("Usage: topogram extract <app-path> --out <target> [--from <track[,track]>] [--json]");
+  console.log("   or: topogram extract refresh [path] [--from <app-path>] [--dry-run] [--json]");
+  console.log("   or: topogram extract diff [path] [--json]");
+  console.log("   or: topogram extract check [path] [--json]");
+  console.log("   or: topogram extract plan [path] [--json]");
+  console.log("   or: topogram extract status [path] [--json]");
+  console.log("   or: topogram extract history [path] [--verify] [--json]");
   console.log("");
-  console.log("Creates an editable Topogram workspace from a brownfield app without modifying the app.");
+  console.log("Extracts reviewable Topogram candidates from a brownfield app without modifying the app.");
   console.log("");
   console.log("Behavior:");
-  console.log("  - writes raw import candidates under topo/candidates/app");
+  console.log("  - writes raw extraction candidates under topo/candidates/app");
   console.log("  - writes reconcile proposal bundles under topo/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(`  - writes ${TOPOGRAM_IMPORT_FILE} with source file hashes from extraction time`);
+  console.log("  - extracted 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 ./existing-cli --out ./imported-topogram --from cli");
-  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");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram --from db,api,ui");
+  console.log("  topogram extract ./existing-cli --out ./extracted-topogram --from cli");
+  console.log("  topogram extract diff ./extracted-topogram");
+  console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app --dry-run");
+  console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app");
+  console.log("  topogram extract check ./extracted-topogram");
+  console.log("  topogram extract plan ./extracted-topogram");
+  console.log("  topogram extract status ./extracted-topogram");
+  console.log("  topogram extract history ./extracted-topogram");
+  console.log("  topogram extract history ./extracted-topogram --verify");
+  console.log("  topogram extract check --json");
+}
+
+export function printAdoptHelp() {
+  console.log("Usage: topogram adopt --list [path] [--json]");
+  console.log("   or: topogram adopt <selector> [path] [--dry-run|--write] [--force --reason <text>] [--json]");
+  console.log("");
+  console.log("Promotes reviewed extraction candidates into canonical topo/ files.");
+  console.log("");
+  console.log("Behavior:");
+  console.log("  - previews never write canonical Topogram files unless --write is passed");
+  console.log("  - writes refuse dirty brownfield source provenance unless --force is passed");
+  console.log(`  - writes append audit receipts to ${TOPOGRAM_IMPORT_ADOPTIONS_FILE}`);
+  console.log("  - forced writes require --reason <text>");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram adopt --list ./extracted-topogram");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --dry-run");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --write");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --write --force --reason \"Reviewed source drift\"");
 }

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

@@ -9,7 +9,7 @@ import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { shellCommandArg } from "../catalog.js";
 import { resolveTopoRoot, resolveWorkspaceContext } from "../../../workspace-paths.js";
 
-export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-import-adoptions.jsonl";
+export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-adoptions.jsonl";
 
 /**
  * @typedef {Record<string, any>} AnyRecord
@@ -219,7 +219,7 @@ export function readImportAdoptionReceipts(projectRoot) {
       try {
         return JSON.parse(line);
       } catch (error) {
-        throw new Error(`Invalid import adoption receipt JSON at ${historyPath}:${index + 1}.`);
+        throw new Error(`Invalid adoption receipt JSON at ${historyPath}:${index + 1}.`);
       }
     });
 }
@@ -265,5 +265,5 @@ export function importProjectCommandPath(projectRoot) {
  * @returns {string}
  */
 export function importAdoptCommand(projectRoot, selector, write = false) {
-  return `topogram import adopt ${selector} ${importProjectCommandPath(projectRoot)} ${write ? "--write" : "--dry-run"}`;
+  return `topogram adopt ${selector} ${importProjectCommandPath(projectRoot)} ${write ? "--write" : "--dry-run"}`;
 }