@topogram/cli 0.3.85 → 0.3.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.85",
+  "version": "0.3.87",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/archive/unarchive.js

@@ -12,15 +12,15 @@
 //   - pitch: draft
 //   - document: draft
 
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import {
-  archiveDir,
   listArchiveFiles,
   parseArchiveFile,
   rewriteArchiveFile
 } from "./jsonl.js";
-import { resolveTopoRoot } from "../workspace-paths.js";
+import { isArchivableKind } from "./schema.js";
+import { sdlcRootForSdlc } from "../sdlc/paths.js";
 
 const REOPEN_STATUSES = {
   bug: "open",
@@ -30,6 +30,50 @@ const REOPEN_STATUSES = {
   document: "draft"
 };
 
+const SAFE_ARCHIVE_ID = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function recordDirForKind(kind) {
+  if (kind === "acceptance_criterion") return "acceptance_criteria";
+  return `${kind}s`;
+}
+
+function isContainedPath(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function validateArchivedEntry(entry) {
+  if (!entry || typeof entry !== "object") {
+    return "Archived entry is not an object";
+  }
+  if (!isArchivableKind(entry.kind)) {
+    return `Archived entry kind '${entry.kind}' is not supported for unarchive`;
+  }
+  if (typeof entry.id !== "string" || !SAFE_ARCHIVE_ID.test(entry.id)) {
+    return `Archived entry id '${entry.id}' is not a safe Topogram identifier`;
+  }
+  return null;
+}
+
+function resolveTargetFile(workspaceRoot, entry, options = {}) {
+  const recordRoot = path.resolve(sdlcRootForSdlc(workspaceRoot), recordDirForKind(entry.kind));
+  const targetDir = path.resolve(options.targetDir || recordRoot);
+  if (!isContainedPath(recordRoot, targetDir)) {
+    return {
+      ok: false,
+      error: `Target directory '${targetDir}' escapes SDLC ${entry.kind} record root '${recordRoot}'`
+    };
+  }
+  const targetFile = path.resolve(targetDir, `${entry.id}.tg`);
+  if (!isContainedPath(recordRoot, targetFile)) {
+    return {
+      ok: false,
+      error: `Archived entry id '${entry.id}' resolves outside SDLC ${entry.kind} record root '${recordRoot}'`
+    };
+  }
+  return { ok: true, recordRoot, targetDir, targetFile };
+}
+
 function findEntry(workspaceRoot, id) {
   for (const file of listArchiveFiles(workspaceRoot)) {
     const entries = parseArchiveFile(file);
@@ -109,10 +153,17 @@ export function unarchive(workspaceRoot, id, options = {}) {
   }
 
   const { file, entries, entry } = found;
+  const entryError = validateArchivedEntry(entry);
+  if (entryError) {
+    return { ok: false, error: entryError };
+  }
   const reopenStatus = options.status || REOPEN_STATUSES[entry.kind] || "draft";
-  const targetDir = options.targetDir || path.join(resolveTopoRoot(workspaceRoot), `${entry.kind}s`);
+  const target = resolveTargetFile(workspaceRoot, entry, options);
+  if (!target.ok) {
+    return target;
+  }
+  const { targetDir, targetFile } = target;
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
-  const targetFile = path.join(targetDir, `${entry.id}.tg`);
 
   if (existsSync(targetFile)) {
     return { ok: false, error: `Target file '${targetFile}' already exists; refuse to overwrite` };

package/src/catalog/source.js

@@ -5,22 +5,66 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { readGithubCatalogSourceText } from "../github-client.js";
+import { remotePayloadMaxBytes } from "../remote-payload-limits.js";
 import { defaultCatalogSource } from "../topogram-config.js";
 import { GITHUB_TOKEN_HOSTS } from "./constants.js";
 import { validateCatalog } from "./validation.js";
 
 const FETCH_URL_SCRIPT = `
 const source = process.argv[1];
+const maxBytes = Number.parseInt(process.env.TOPOGRAM_FETCH_MAX_BYTES || "", 10) || 5242880;
 const token = process.env.TOPOGRAM_FETCH_TOKEN || "";
 const tokenHosts = new Set(["github.com", "api.github.com", "raw.githubusercontent.com"]);
 function tokenAllowed(url) {
   const hostname = new URL(url).hostname.toLowerCase();
   return tokenHosts.has(hostname) || hostname.endsWith(".github.com");
 }
+async function readResponseText(response, url) {
+  const declaredLength = Number.parseInt(response.headers.get("content-length") || "", 10);
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    throw new Error("Response from " + url + " exceeded " + maxBytes + " byte limit.");
+  }
+  if (!response.body) {
+    const text = await response.text();
+    if (Buffer.byteLength(text, "utf8") > maxBytes) {
+      throw new Error("Response from " + url + " exceeded " + maxBytes + " byte limit.");
+    }
+    return text;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) {
+      break;
+    }
+    total += value.byteLength;
+    if (total > maxBytes) {
+      try {
+        await reader.cancel();
+      } catch {}
+      throw new Error("Response from " + url + " exceeded " + maxBytes + " byte limit.");
+    }
+    chunks.push(decoder.decode(value, { stream: true }));
+  }
+  chunks.push(decoder.decode());
+  return chunks.join("");
+}
 async function readUrl(url, redirects = 0) {
   if (redirects > 5) {
     throw new Error("Too many redirects.");
   }
+  if (process.env.TOPOGRAM_CATALOG_URL_FIXTURE_PATH) {
+    const fs = await import("node:fs");
+    const fixturePath = process.env.TOPOGRAM_CATALOG_URL_FIXTURE_PATH;
+    const fixtureSize = fs.statSync(fixturePath).size;
+    if (fixtureSize > maxBytes) {
+      throw new Error("Response from " + url + " exceeded " + maxBytes + " byte limit.");
+    }
+    return fs.readFileSync(fixturePath, "utf8");
+  }
   const headers = {};
   if (token && tokenAllowed(url)) {
     headers.authorization = "Bearer " + token;
@@ -30,7 +74,7 @@ async function readUrl(url, redirects = 0) {
     const next = new URL(response.headers.get("location"), url).toString();
     return readUrl(next, redirects + 1);
   }
-  const text = await response.text();
+  const text = await readResponseText(response, url);
   if (!response.ok) {
     const preview = text.trim().slice(0, 400);
     throw new Error(String(response.status) + " " + response.statusText + (preview ? "\\n" + preview : ""));
@@ -118,14 +162,21 @@ function readCatalogText(source) {
  */
 function readUrlText(source) {
   const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+  const maxBytes = remotePayloadMaxBytes(
+    ["TOPOGRAM_CATALOG_FETCH_MAX_BYTES", "TOPOGRAM_REMOTE_FETCH_MAX_BYTES"],
+    undefined,
+    ["catalogFetchMaxBytes", "remoteFetchMaxBytes"]
+  );
   const tokenEnv = token && githubTokenAllowedForCatalogUrl(source)
     ? { TOPOGRAM_FETCH_TOKEN: token }
     : {};
   const result = childProcess.spawnSync(process.execPath, ["--input-type=module", "-e", FETCH_URL_SCRIPT, source], {
     encoding: "utf8",
+    maxBuffer: maxBytes + 4096,
     env: {
       ...process.env,
       ...tokenEnv,
+      TOPOGRAM_FETCH_MAX_BYTES: String(maxBytes),
       PATH: process.env.PATH || ""
     }
   });

package/src/cli/commands/emit/snapshot-input.js

@@ -0,0 +1,111 @@
+// @ts-check
+
+import fs from "node:fs";
+
+const FORBIDDEN_SNAPSHOT_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function errorMessage(value) {
+  return value instanceof Error ? value.message : String(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function validateDbSchemaSnapshot(value) {
+  const errors = [];
+  if (!isRecord(value)) {
+    return ["snapshot must be a JSON object"];
+  }
+  if (value.type !== "db_schema_snapshot") {
+    errors.push("snapshot.type must be 'db_schema_snapshot'");
+  }
+  if (!Array.isArray(value.tables)) {
+    errors.push("snapshot.tables must be an array");
+  }
+  if (!Array.isArray(value.enums)) {
+    errors.push("snapshot.enums must be an array");
+  }
+  if (Array.isArray(value.tables)) {
+    for (const [index, table] of value.tables.entries()) {
+      if (!isRecord(table)) {
+        errors.push(`snapshot.tables[${index}] must be an object`);
+        continue;
+      }
+      if (typeof table.table !== "string" || table.table.length === 0) {
+        errors.push(`snapshot.tables[${index}].table must be a non-empty string`);
+      }
+      if (!Array.isArray(table.columns)) {
+        errors.push(`snapshot.tables[${index}].columns must be an array`);
+      }
+    }
+  }
+  if (Array.isArray(value.enums)) {
+    for (const [index, enumEntry] of value.enums.entries()) {
+      if (!isRecord(enumEntry)) {
+        errors.push(`snapshot.enums[${index}] must be an object`);
+        continue;
+      }
+      if (typeof enumEntry.id !== "string" || enumEntry.id.length === 0) {
+        errors.push(`snapshot.enums[${index}].id must be a non-empty string`);
+      }
+      if (!Array.isArray(enumEntry.values)) {
+        errors.push(`snapshot.enums[${index}].values must be an array`);
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * @param {string} snapshotPath
+ * @returns {{ ok: true, snapshot: Record<string, unknown> } | { ok: false, message: string }}
+ */
+export function readFromSnapshot(snapshotPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(snapshotPath, "utf8");
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Unable to read --from-snapshot '${snapshotPath}': ${errorMessage(error)}`
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw, (key, value) => {
+      if (FORBIDDEN_SNAPSHOT_KEYS.has(key)) {
+        throw new Error(`unsafe key '${key}' is not allowed in snapshot JSON`);
+      }
+      return value;
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      message: `Invalid --from-snapshot JSON at '${snapshotPath}': ${errorMessage(error)}`
+    };
+  }
+
+  const errors = validateDbSchemaSnapshot(parsed);
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      message: `Invalid --from-snapshot DB schema snapshot at '${snapshotPath}': ${errors.join("; ")}`
+    };
+  }
+
+  return { ok: true, snapshot: parsed };
+}

package/src/cli/commands/emit.js

@@ -22,6 +22,7 @@ import {
   generatedOutputSentinel,
   topogramInputPathForGeneration
 } from "../output-safety.js";
+import { readFromSnapshot } from "./emit/snapshot-input.js";
 
 const IMPLEMENTATION_PROVIDER_TARGETS = new Set([
   "persistence-scaffold",
@@ -78,6 +79,15 @@ function targetRequiresImplementationProvider(target) {
  */
 export async function runEmitCommand(options) {
   const ast = parsePath(options.inputPath);
+  let fromSnapshot = null;
+  if (options.fromSnapshotPath) {
+    const parsedSnapshot = readFromSnapshot(options.fromSnapshotPath);
+    if (!parsedSnapshot.ok) {
+      console.error(parsedSnapshot.message);
+      return 1;
+    }
+    fromSnapshot = parsedSnapshot.snapshot;
+  }
   const explicitProjectConfig = loadProjectConfig(options.projectRoot) || loadProjectConfig(options.inputPath);
   const shouldLoadImplementation = targetRequiresImplementationProvider(options.target) &&
     (!IMPLEMENTATION_OPTIONAL_TARGETS.has(options.target) || Boolean(explicitProjectConfig?.config?.implementation));
@@ -106,7 +116,7 @@ export async function runEmitCommand(options) {
     target: options.target,
     ...(options.selectors || {}),
     profileId: options.profileId,
-    fromSnapshot: options.fromSnapshotPath ? JSON.parse(fs.readFileSync(options.fromSnapshotPath, "utf8")) : null,
+    fromSnapshot,
     fromSnapshotPath: options.fromSnapshotPath,
     fromTopogramPath: options.fromTopogramPath,
     topogramInputPath: topogramInputPathForGeneration(options.inputPath),

package/src/cli/commands/extractor.js

@@ -44,6 +44,7 @@ export function printExtractorHelp() {
   console.log("  - extractor packages execute only during `topogram extract` or `topogram extractor check`.");
   console.log("  - extractor packages emit review-only candidates; core owns persistence, reconcile, and adoption.");
   console.log(`  - package-backed extractors are governed by ${EXTRACTOR_POLICY_FILE}; bundled topogram/* extractors are allowed.`);
+  console.log("  - safe loop: list/show -> install -> policy pin -> check -> extract -> plan/list -> adopt --dry-run -> adopt --write.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram extractor list");
@@ -121,17 +122,110 @@ function extractorPolicyPinCommand(packageName, version) {
 }
 
 /**
- * @param {string|null|undefined} packageName
+ * @param {string|null|undefined} extractorRef
  * @param {string[]} tracks
  * @param {string|null|undefined} exampleSource
  * @returns {string|null}
  */
-function extractorRunCommand(packageName, tracks, exampleSource) {
-  if (!packageName) {
+function extractorRunCommand(extractorRef, tracks, exampleSource) {
+  if (!extractorRef) {
     return null;
   }
   const trackList = tracks.length > 0 ? tracks.join(",") : "db,api,ui,cli";
-  return `topogram extract ${exampleSource || "./existing-app"} --out ./imported-topogram --from ${trackList} --extractor ${packageName}`;
+  return `topogram extract ${exampleSource || "./existing-app"} --out ./imported-topogram --from ${trackList} --extractor ${extractorRef}`;
+}
+
+/**
+ * @param {Record<string, any>|null|undefined} extractor
+ * @returns {Record<string, any>}
+ */
+function buildExtractorReviewWorkflow(extractor = null) {
+  const packageName = extractor?.package || extractor?.packageName || null;
+  const extractorRef = packageName || extractor?.id || "<extractor>";
+  const tracks = Array.isArray(extractor?.tracks) ? extractor.tracks : [];
+  const version = extractor?.version || "1";
+  const bundledExtractor = extractor?.source === "bundled" && !packageName;
+  const installCommand = extractor?.installCommand || (packageName ? packageExtractorInstallCommand(packageName) : null);
+  const policyPinCommand = extractor?.policyPinCommand || (packageName ? extractorPolicyPinCommand(packageName, version) : null);
+  const extractCommand = extractor?.extractCommand || extractorRunCommand(extractorRef, tracks, extractor?.exampleSource);
+  return {
+    type: "extractor_review_workflow",
+    packageCodeExecution: {
+      list: false,
+      show: false,
+      policy: false,
+      check: true,
+      extract: true
+    },
+    steps: [
+      {
+        id: "discover",
+        command: "topogram extractor list",
+        packageCodeExecution: false,
+        purpose: "Find bundled and first-party package-backed extractors by track."
+      },
+      {
+        id: "inspect",
+        command: `topogram extractor show ${extractorRef}`,
+        packageCodeExecution: false,
+        purpose: "Read manifest purpose, tracks, install command, policy pin command, and extract command."
+      },
+      ...(installCommand ? [{
+        id: "install",
+        command: installCommand,
+        packageCodeExecution: false,
+        purpose: "Install the extractor package explicitly; Topogram does not install it during extraction."
+      }] : []),
+      ...(policyPinCommand ? [{
+        id: "pin_policy",
+        command: policyPinCommand,
+        packageCodeExecution: false,
+        purpose: "Allow and pin the extractor manifest version before execution."
+      }] : []),
+      ...(!bundledExtractor ? [{
+        id: "check",
+        command: `topogram extractor check ${extractorRef}`,
+        packageCodeExecution: true,
+        purpose: "Load the adapter and run a minimal smoke extraction against a synthetic fixture."
+      }] : []),
+      ...(extractCommand ? [{
+        id: "extract",
+        command: extractCommand,
+        packageCodeExecution: true,
+        purpose: "Read brownfield source and write review-only candidates plus extraction provenance."
+      }] : []),
+      {
+        id: "review_plan",
+        command: "topogram extract plan ./imported-topogram",
+        packageCodeExecution: false,
+        purpose: "Review bundles, extractor provenance, candidate counts, and safety notes."
+      },
+      {
+        id: "list_selectors",
+        command: "topogram adopt --list ./imported-topogram",
+        packageCodeExecution: false,
+        purpose: "Choose an explicit adoption selector."
+      },
+      {
+        id: "dry_run_adoption",
+        command: "topogram adopt <selector> ./imported-topogram --dry-run",
+        packageCodeExecution: false,
+        purpose: "Preview canonical topo writes before changing project-owned records."
+      },
+      {
+        id: "write_reviewed_adoption",
+        command: "topogram adopt <selector> ./imported-topogram --write",
+        packageCodeExecution: false,
+        purpose: "Write only reviewed canonical records; extractor packages never own adoption semantics."
+      }
+    ],
+    safetyNotes: [
+      "topogram extractor list/show/policy do not load package adapter code.",
+      "topogram extractor check and topogram extract load package adapter code.",
+      "Extractor packages emit review-only candidates; core owns persistence, reconcile, adoption, and canonical topo writes.",
+      "Run dry-run adoption before --write."
+    ]
+  };
 }
 
 /**
@@ -188,8 +282,8 @@ function extractorManifestSummary(manifest, metadata = {}) {
   const version = manifest.version || firstParty?.version || "1";
   const installCommand = packageName ? packageExtractorInstallCommand(packageName) : null;
   const policyPinCommand = extractorPolicyPinCommand(packageName, version);
-  const extractCommand = extractorRunCommand(packageName, tracks, firstParty?.exampleSource);
-  return {
+  const extractCommand = extractorRunCommand(packageName || manifest.id, tracks, firstParty?.exampleSource);
+  const summary = {
     id: manifest.id,
     version,
     label: firstParty?.label || null,
@@ -215,6 +309,10 @@ function extractorManifestSummary(manifest, metadata = {}) {
     packageRoot: metadata.packageRoot || null,
     errors: metadata.errors || []
   };
+  return {
+    ...summary,
+    reviewWorkflow: buildExtractorReviewWorkflow(summary)
+  };
 }
 
 /**
@@ -222,7 +320,7 @@ function extractorManifestSummary(manifest, metadata = {}) {
  * @returns {Record<string, any>}
  */
 function firstPartyExtractorPlaceholder(info) {
-  return {
+  const summary = {
     id: info.id,
     version: info.version,
     label: info.label,
@@ -248,11 +346,15 @@ function firstPartyExtractorPlaceholder(info) {
     packageRoot: null,
     errors: []
   };
+  return {
+    ...summary,
+    reviewWorkflow: buildExtractorReviewWorkflow(summary)
+  };
 }
 
 /**
  * @param {string} cwd
- * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], groups: Record<string, ReturnType<typeof groupExtractorEntry>[]>, summary: Record<string, number> }}
+ * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], groups: Record<string, ReturnType<typeof groupExtractorEntry>[]>, reviewWorkflow: Record<string, any>, summary: Record<string, number> }}
  */
 export function buildExtractorListPayload(cwd) {
   const extractors = EXTRACTOR_MANIFESTS
@@ -314,6 +416,7 @@ export function buildExtractorListPayload(cwd) {
     cwd,
     extractors,
     groups,
+    reviewWorkflow: buildExtractorReviewWorkflow(),
     summary: {
       total: extractors.length,
       bundled: extractors.filter((extractor) => extractor.source === "bundled").length,
@@ -367,6 +470,7 @@ export function printExtractorList(payload) {
   console.log("Topogram extractors");
   console.log(`Bundled: ${payload.summary.bundled}; package-backed: ${payload.summary.package}; installed: ${payload.summary.installed}; first-party missing: ${payload.summary.missingFirstParty || 0}`);
   console.log("Package-backed extractors are listed for discovery even before they are installed.");
+  console.log("Selection loop: list/show (no package code) -> install -> policy pin -> extractor check (loads adapter) -> extract -> extract plan/adopt --list -> adopt --dry-run -> adopt --write.");
   console.log("");
   for (const track of EXTRACTOR_TRACK_ORDER) {
     const entries = (payload.groups || {})[track] || [];
@@ -426,10 +530,18 @@ export function printExtractorShow(payload) {
   console.log(`Extractors: ${extractor.extractors.join(", ") || "none"}`);
   console.log(`Candidate kinds: ${extractor.candidateKinds.join(", ") || "none"}`);
   console.log(`Evidence types: ${extractor.evidenceTypes.join(", ") || "none"}`);
+  if (extractor.reviewWorkflow?.steps?.length) {
+    console.log("");
+    console.log("Review loop:");
+    for (const step of extractor.reviewWorkflow.steps) {
+      console.log(`- ${step.id}: ${step.command}`);
+      console.log(`  ${step.purpose}`);
+    }
+  }
 }
 
 /**
- * @param {ReturnType<typeof checkExtractorPack>} payload
+ * @param {ReturnType<typeof checkExtractorPack> & { reviewWorkflow?: Record<string, any> }} payload
  * @returns {void}
  */
 export function printExtractorCheck(payload) {
@@ -453,12 +565,19 @@ export function printExtractorCheck(payload) {
     console.log("");
     console.log(`Smoke output: ${payload.smoke.extractors} extractor(s), ${payload.smoke.findings} finding(s), ${payload.smoke.candidateKeys} candidate bucket(s), ${payload.smoke.diagnostics} diagnostic(s)`);
   }
+  if (payload.reviewWorkflow?.steps?.length) {
+    console.log("");
+    console.log("Next review loop:");
+    for (const step of payload.reviewWorkflow.steps.filter((/** @type {Record<string, any>} */ step) => ["extract", "review_plan", "list_selectors", "dry_run_adoption", "write_reviewed_adoption"].includes(step.id))) {
+      console.log(`- ${step.command}`);
+    }
+  }
   for (const error of payload.errors || []) console.log(`Error: ${error}`);
 }
 
 /**
  * @param {string} projectPath
- * @returns {{ ok: boolean, path: string, exists: boolean, policy: any, defaulted: boolean, packages: any[], diagnostics: any[], errors: string[], summary: Record<string, number> }}
+ * @returns {{ ok: boolean, path: string, exists: boolean, policy: any, defaulted: boolean, packages: any[], diagnostics: any[], errors: string[], reviewWorkflow: Record<string, any>, summary: Record<string, number> }}
  */
 export function buildExtractorPolicyStatusPayload(projectPath) {
   const root = path.resolve(projectPath || ".");
@@ -504,6 +623,7 @@ export function buildExtractorPolicyStatusPayload(projectPath) {
     packages,
     diagnostics,
     errors,
+    reviewWorkflow: buildExtractorReviewWorkflow(packages[0] || null),
     summary: {
       enabledPackages: policy.enabledPackages.length,
       installed: packages.filter((item) => item.installed).length,
@@ -567,6 +687,7 @@ export function printExtractorPolicyStatus(payload) {
   console.log(`Enabled packages: ${payload.summary.enabledPackages}`);
   console.log("Default allowlist: bundled topogram/* extractors and first-party @topogram/extractor-* packages.");
   console.log("Install behavior: Topogram does not install extractor packages automatically.");
+  console.log("Review loop: install package -> pin policy -> extractor check -> extract -> extract plan/adopt --list -> adopt --dry-run -> adopt --write.");
   for (const item of payload.packages) {
     console.log(`- ${item.packageName}@${item.version}: ${item.installed ? "installed" : "missing"}, ${item.allowed ? "allowed" : "denied"}`);
     if (!item.installed && item.installCommand) console.log(`  Install: ${item.installCommand}`);
@@ -611,9 +732,25 @@ export function runExtractorCommand(context) {
   const { commandArgs, inputPath, json, cwd } = context;
   if (commandArgs.extractorCommand === "check") {
     const payload = checkExtractorPack(inputPath || "", { cwd });
-    if (json) console.log(stableStringify(payload));
-    else printExtractorCheck(payload);
-    return payload.ok ? 0 : 1;
+    const summary = payload.manifest
+      ? extractorManifestSummary(payload.manifest, {
+          installed: Boolean(payload.manifest),
+          manifestPath: payload.manifestPath,
+          packageRoot: payload.packageRoot,
+          errors: payload.errors
+        })
+      : null;
+    const augmentedPayload = /** @type {ReturnType<typeof checkExtractorPack> & { reviewWorkflow?: Record<string, any> }} */ (payload);
+    augmentedPayload.reviewWorkflow = buildExtractorReviewWorkflow(summary || {
+      id: inputPath || "<extractor>",
+      package: payload.packageName || null,
+      packageName: payload.packageName || null,
+      tracks: payload.manifest?.tracks || [],
+      version: payload.manifest?.version || "1"
+    });
+    if (json) console.log(stableStringify(augmentedPayload));
+    else printExtractorCheck(augmentedPayload);
+    return augmentedPayload.ok ? 0 : 1;
   }
   if (commandArgs.extractorCommand === "scaffold") {
     const payload = scaffoldExtractorPack(inputPath || "", {