@topogram/cli 0.3.79 → 0.3.80

package/package.json

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

package/src/cli/command-parser.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { parseCoreCommandArgs } from "./command-parsers/core.js";
+import { parseExtractorCommandArgs } from "./command-parsers/extractor.js";
 import { parseGeneratorCommandArgs } from "./command-parsers/generator.js";
 import { parseImportCommandArgs } from "./command-parsers/import.js";
 import { parseLegacyWorkflowCommandArgs } from "./command-parsers/legacy-workflow.js";
@@ -10,6 +11,7 @@ import { parseTemplateCommandArgs } from "./command-parsers/template.js";
 
 const COMMAND_PARSERS = [
   parseCoreCommandArgs,
+  parseExtractorCommandArgs,
   parseGeneratorCommandArgs,
   parseTemplateCommandArgs,
   parseProjectCommandArgs,

package/src/cli/command-parsers/extractor.js

@@ -0,0 +1,40 @@
+// @ts-check
+
+import { commandPath } from "./shared.js";
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseExtractorCommandArgs(args) {
+  if (args[0] === "extractor" && args[1] === "list") {
+    return { extractorCommand: "list", inputPath: null };
+  }
+  if (args[0] === "extractor" && args[1] === "show") {
+    return { extractorCommand: "show", inputPath: args[2] };
+  }
+  if (args[0] === "extractor" && args[1] === "check") {
+    return { extractorCommand: "check", inputPath: args[2] };
+  }
+  if (args[0] === "extractor" && args[1] === "policy" && args[2] === "init") {
+    return { extractorPolicyCommand: "init", inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "extractor" && args[1] === "policy" && args[2] === "status") {
+    return { extractorPolicyCommand: "status", inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "extractor" && args[1] === "policy" && args[2] === "check") {
+    return { extractorPolicyCommand: "check", inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "extractor" && args[1] === "policy" && args[2] === "explain") {
+    return { extractorPolicyCommand: "explain", inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "extractor" && args[1] === "policy" && args[2] === "pin") {
+    return {
+      extractorPolicyCommand: "pin",
+      extractorPolicyPinSpec: args[3] && !args[3].startsWith("-") ? args[3] : null,
+      inputPath: commandPath(args, 4, ".")
+    };
+  }
+  return null;
+}
+

package/src/cli/commands/extractor.js

@@ -0,0 +1,451 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import { checkExtractorPack } from "../../extractor/check.js";
+import {
+  EXTRACTOR_MANIFESTS,
+  getExtractorManifest,
+  loadPackageExtractorManifest,
+  packageExtractorInstallCommand
+} from "../../extractor/registry.js";
+import {
+  defaultExtractorPolicy,
+  effectiveExtractorPolicy,
+  EXTRACTOR_POLICY_FILE,
+  extractorPackageAllowed,
+  extractorPolicyDiagnosticsForPackages,
+  loadExtractorPolicy,
+  packageScopeFromName,
+  parseExtractorPolicyPin,
+  writeExtractorPolicy
+} from "../../extractor-policy.js";
+
+export function printExtractorHelp() {
+  console.log("Usage: topogram extractor list [--json]");
+  console.log("   or: topogram extractor show <id-or-package> [--json]");
+  console.log("   or: topogram extractor check <path-or-package> [--json]");
+  console.log("   or: topogram extractor policy init [path] [--json]");
+  console.log("   or: topogram extractor policy status [path] [--json]");
+  console.log("   or: topogram extractor policy check [path] [--json]");
+  console.log("   or: topogram extractor policy explain [path] [--json]");
+  console.log("   or: topogram extractor policy pin [package@version] [path] [--json]");
+  console.log("");
+  console.log("Inspects extractor manifests and checks extractor pack conformance.");
+  console.log("");
+  console.log("Notes:");
+  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("");
+  console.log("Examples:");
+  console.log("  topogram extractor list");
+  console.log("  topogram extractor show topogram/api-extractors");
+  console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor policy init");
+  console.log("  topogram extractor policy pin @topogram/extractor-node-cli@1");
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function declaredExtractorPackages(cwd) {
+  const packagePath = path.join(cwd, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return [];
+  }
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  const dependencyBuckets = [
+    packageJson.dependencies,
+    packageJson.devDependencies,
+    packageJson.optionalDependencies,
+    packageJson.peerDependencies
+  ];
+  const packages = new Set();
+  for (const dependencies of dependencyBuckets) {
+    if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) {
+      continue;
+    }
+    for (const name of Object.keys(dependencies)) {
+      if (name.includes("topogram-extractor") || name.startsWith("@topogram/extractor-")) {
+        packages.add(name);
+      }
+    }
+  }
+  return [...packages].sort();
+}
+
+/**
+ * @param {any} manifest
+ * @param {{ installed?: boolean, manifestPath?: string|null, packageRoot?: string|null, errors?: string[] }} [metadata]
+ * @returns {Record<string, any>}
+ */
+function extractorManifestSummary(manifest, metadata = {}) {
+  const installCommand = manifest.package ? packageExtractorInstallCommand(manifest.package) : null;
+  return {
+    id: manifest.id,
+    version: manifest.version,
+    tracks: manifest.tracks || [],
+    extractors: manifest.extractors || [],
+    stack: manifest.stack || {},
+    capabilities: manifest.capabilities || {},
+    candidateKinds: manifest.candidateKinds || [],
+    evidenceTypes: manifest.evidenceTypes || [],
+    source: manifest.source,
+    loadsAdapter: false,
+    executesPackageCode: false,
+    ...(manifest.package ? { package: manifest.package } : {}),
+    ...(installCommand ? { installCommand } : {}),
+    installed: metadata.installed !== false,
+    manifestPath: metadata.manifestPath || null,
+    packageRoot: metadata.packageRoot || null,
+    errors: metadata.errors || []
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], summary: Record<string, number> }}
+ */
+export function buildExtractorListPayload(cwd) {
+  const extractors = EXTRACTOR_MANIFESTS
+    .map((manifest) => extractorManifestSummary(manifest))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  for (const packageName of declaredExtractorPackages(cwd)) {
+    const loaded = loadPackageExtractorManifest(packageName, cwd);
+    if (loaded.manifest) {
+      extractors.push(extractorManifestSummary(loaded.manifest, {
+        installed: true,
+        manifestPath: loaded.manifestPath,
+        packageRoot: loaded.packageRoot,
+        errors: loaded.errors
+      }));
+    } else {
+      extractors.push({
+        id: null,
+        version: null,
+        tracks: [],
+        extractors: [],
+        stack: {},
+        capabilities: {},
+        candidateKinds: [],
+        evidenceTypes: [],
+        source: "package",
+        package: packageName,
+        installCommand: packageExtractorInstallCommand(packageName),
+        installed: false,
+        manifestPath: loaded.manifestPath,
+        packageRoot: loaded.packageRoot,
+        errors: loaded.errors
+      });
+    }
+  }
+  extractors.sort((left, right) => String(left.id || left.package || "").localeCompare(String(right.id || right.package || "")));
+  return {
+    ok: extractors.every((extractor) => extractor.errors.length === 0),
+    cwd,
+    extractors,
+    summary: {
+      total: extractors.length,
+      bundled: extractors.filter((extractor) => extractor.source === "bundled").length,
+      package: extractors.filter((extractor) => extractor.source === "package").length,
+      installed: extractors.filter((extractor) => extractor.installed).length
+    }
+  };
+}
+
+/**
+ * @param {string} spec
+ * @param {string} cwd
+ * @returns {{ ok: boolean, sourceSpec: string, extractor: Record<string, any>|null, errors: string[] }}
+ */
+export function buildExtractorShowPayload(spec, cwd) {
+  if (!spec || spec.startsWith("-")) {
+    return { ok: false, sourceSpec: spec || "", extractor: null, errors: ["Usage: topogram extractor show <id-or-package>"] };
+  }
+  const bundled = getExtractorManifest(spec);
+  if (bundled) {
+    return { ok: true, sourceSpec: spec, extractor: extractorManifestSummary(bundled), errors: [] };
+  }
+  const loaded = loadPackageExtractorManifest(spec, cwd);
+  if (loaded.manifest) {
+    return {
+      ok: true,
+      sourceSpec: spec,
+      extractor: extractorManifestSummary(loaded.manifest, {
+        installed: true,
+        manifestPath: loaded.manifestPath,
+        packageRoot: loaded.packageRoot,
+        errors: loaded.errors
+      }),
+      errors: []
+    };
+  }
+  return { ok: false, sourceSpec: spec, extractor: null, errors: loaded.errors };
+}
+
+/**
+ * @param {ReturnType<typeof buildExtractorListPayload>} payload
+ * @returns {void}
+ */
+export function printExtractorList(payload) {
+  console.log("Topogram extractors");
+  console.log(`Bundled: ${payload.summary.bundled}; package-backed: ${payload.summary.package}; installed: ${payload.summary.installed}`);
+  console.log("");
+  for (const extractor of payload.extractors) {
+    const id = extractor.id || extractor.package || "unknown";
+    const status = extractor.errors.length > 0
+      ? "invalid"
+      : extractor.source === "package"
+        ? (extractor.installed ? "package installed" : "package missing")
+        : "bundled";
+    console.log(`- ${id}${extractor.version ? `@${extractor.version}` : ""} (${extractor.tracks.join(", ") || "unknown"}, ${status})`);
+    console.log(`  Source: ${extractor.source}`);
+    console.log("  Adapter loaded: no");
+    console.log("  Executes package code: no");
+    console.log(`  Extractors: ${extractor.extractors.join(", ") || "none"}`);
+    if (extractor.package) console.log(`  Package: ${extractor.package}`);
+    if (extractor.installCommand) console.log(`  Install: ${extractor.installCommand}`);
+    for (const error of extractor.errors || []) console.log(`  Error: ${error}`);
+  }
+}
+
+/**
+ * @param {ReturnType<typeof buildExtractorShowPayload>} payload
+ * @returns {void}
+ */
+export function printExtractorShow(payload) {
+  if (!payload.ok || !payload.extractor) {
+    console.log("Extractor pack not found.");
+    for (const error of payload.errors || []) console.log(`- ${error}`);
+    return;
+  }
+  const extractor = payload.extractor;
+  console.log(`Extractor pack: ${extractor.id}@${extractor.version}`);
+  console.log(`Tracks: ${extractor.tracks.join(", ") || "none"}`);
+  console.log(`Source: ${extractor.source}`);
+  console.log("Adapter loaded: no");
+  console.log("Executes package code: no");
+  if (extractor.package) console.log(`Package: ${extractor.package}`);
+  if (extractor.installCommand) console.log(`Install: ${extractor.installCommand}`);
+  if (extractor.manifestPath) console.log(`Manifest: ${extractor.manifestPath}`);
+  console.log(`Extractors: ${extractor.extractors.join(", ") || "none"}`);
+  console.log(`Candidate kinds: ${extractor.candidateKinds.join(", ") || "none"}`);
+  console.log(`Evidence types: ${extractor.evidenceTypes.join(", ") || "none"}`);
+}
+
+/**
+ * @param {ReturnType<typeof checkExtractorPack>} payload
+ * @returns {void}
+ */
+export function printExtractorCheck(payload) {
+  console.log(payload.ok ? "Extractor check passed." : "Extractor check found issues.");
+  console.log(`Source: ${payload.sourceSpec}`);
+  console.log(`Type: ${payload.source}`);
+  if (payload.packageName) console.log(`Package: ${payload.packageName}`);
+  if (payload.manifestPath) console.log(`Manifest: ${payload.manifestPath}`);
+  if (payload.manifest) {
+    console.log(`Extractor pack: ${payload.manifest.id}@${payload.manifest.version}`);
+    console.log(`Tracks: ${payload.manifest.tracks.join(", ")}`);
+    console.log(`Source mode: ${payload.manifest.source}`);
+  }
+  console.log("Executes package code: yes (loads adapter and runs smoke extract)");
+  console.log("");
+  console.log("Checks:");
+  for (const check of payload.checks || []) {
+    console.log(`- ${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.message}`);
+  }
+  if (payload.smoke) {
+    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)`);
+  }
+  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> }}
+ */
+export function buildExtractorPolicyStatusPayload(projectPath) {
+  const root = path.resolve(projectPath || ".");
+  const policyInfo = loadExtractorPolicy(root);
+  const policy = effectiveExtractorPolicy(policyInfo);
+  const packages = policy.enabledPackages.map((packageName) => {
+    const loaded = loadPackageExtractorManifest(packageName, root);
+    const version = loaded.manifest?.version || "unknown";
+    const diagnostics = extractorPolicyDiagnosticsForPackages(policyInfo, [{ packageName, version }], "extractor-policy");
+    return {
+      packageName,
+      version,
+      allowed: extractorPackageAllowed(policy, packageName),
+      installed: Boolean(loaded.manifest),
+      manifestPath: loaded.manifestPath,
+      packageRoot: loaded.packageRoot,
+      errors: [...loaded.errors, ...diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message)]
+    };
+  });
+  const diagnostics = [
+    ...policyInfo.diagnostics,
+    ...packages.flatMap((item) => item.errors.map((message) => ({
+      code: "extractor_package_failed",
+      severity: "error",
+      message,
+      path: item.manifestPath,
+      suggestedFix: `Review or remove '${item.packageName}' from ${EXTRACTOR_POLICY_FILE}.`,
+      step: "extractor-policy",
+      packageName: item.packageName,
+      version: item.version
+    })))
+  ];
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message);
+  return {
+    ok: errors.length === 0,
+    path: policyInfo.path,
+    exists: policyInfo.exists,
+    policy,
+    defaulted: !policyInfo.exists,
+    packages,
+    diagnostics,
+    errors,
+    summary: {
+      enabledPackages: policy.enabledPackages.length,
+      installed: packages.filter((item) => item.installed).length,
+      allowed: packages.filter((item) => item.allowed).length,
+      denied: packages.filter((item) => !item.allowed).length
+    }
+  };
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {{ ok: boolean, path: string, policy: any, diagnostics: any[], errors: string[] }}
+ */
+export function buildExtractorPolicyInitPayload(projectPath) {
+  const root = path.resolve(projectPath || ".");
+  const policy = writeExtractorPolicy(root, defaultExtractorPolicy());
+  return { ok: true, path: path.join(root, EXTRACTOR_POLICY_FILE), policy, diagnostics: [], errors: [] };
+}
+
+/**
+ * @param {string} projectPath
+ * @param {string|null|undefined} spec
+ * @returns {{ ok: boolean, path: string, policy: any, pinned: Array<{ packageName: string, version: string }>, diagnostics: any[], errors: string[] }}
+ */
+export function buildExtractorPolicyPinPayload(projectPath, spec) {
+  const root = path.resolve(projectPath || ".");
+  const policyInfo = loadExtractorPolicy(root);
+  const policy = policyInfo.policy || defaultExtractorPolicy();
+  let pin;
+  try {
+    pin = parseExtractorPolicyPin(spec || "");
+  } catch (error) {
+    return {
+      ok: false,
+      path: policyInfo.path,
+      policy,
+      pinned: [],
+      diagnostics: [{ severity: "error", code: "extractor_policy_pin_invalid", message: error instanceof Error ? error.message : String(error), path: policyInfo.path }],
+      errors: [error instanceof Error ? error.message : String(error)]
+    };
+  }
+  const nextPolicy = {
+    ...policy,
+    allowedPackages: policy.allowedPackages.includes(pin.packageName) ? policy.allowedPackages : [...policy.allowedPackages, pin.packageName],
+    enabledPackages: policy.enabledPackages.includes(pin.packageName) ? policy.enabledPackages : [...policy.enabledPackages, pin.packageName],
+    pinnedVersions: { ...policy.pinnedVersions, [pin.packageName]: pin.version }
+  };
+  writeExtractorPolicy(root, nextPolicy);
+  return { ok: true, path: path.join(root, EXTRACTOR_POLICY_FILE), policy: nextPolicy, pinned: [pin], diagnostics: [], errors: [] };
+}
+
+/**
+ * @param {ReturnType<typeof buildExtractorPolicyStatusPayload>} payload
+ * @returns {void}
+ */
+export function printExtractorPolicyStatus(payload) {
+  console.log(payload.ok ? "Extractor policy status: allowed" : "Extractor policy status: denied");
+  console.log(`Policy file: ${payload.path}`);
+  console.log(`Policy file exists: ${payload.exists ? "yes" : "no"}`);
+  console.log(`Default policy active: ${payload.defaulted ? "yes" : "no"}`);
+  console.log(`Enabled packages: ${payload.summary.enabledPackages}`);
+  for (const item of payload.packages) {
+    console.log(`- ${item.packageName}@${item.version}: ${item.installed ? "installed" : "missing"}, ${item.allowed ? "allowed" : "denied"}`);
+  }
+  for (const diagnostic of payload.diagnostics) {
+    console.log(`[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`);
+  }
+}
+
+/**
+ * @param {ReturnType<typeof buildExtractorPolicyInitPayload>} payload
+ * @returns {void}
+ */
+export function printExtractorPolicyInit(payload) {
+  console.log(`Wrote extractor policy: ${payload.path}`);
+  console.log(`Allowed package scopes: ${payload.policy.allowedPackageScopes.join(", ") || "(none)"}`);
+  console.log(`Allowed packages: ${payload.policy.allowedPackages.join(", ") || "(none)"}`);
+  console.log(`Enabled packages: ${payload.policy.enabledPackages.join(", ") || "(none)"}`);
+}
+
+/**
+ * @param {ReturnType<typeof buildExtractorPolicyPinPayload>} payload
+ * @returns {void}
+ */
+export function printExtractorPolicyPin(payload) {
+  console.log(payload.ok ? "Extractor policy pin updated" : "Extractor policy pin failed");
+  console.log(`Policy: ${payload.path}`);
+  for (const pin of payload.pinned || []) {
+    console.log(`Pinned: ${pin.packageName}@${pin.version}`);
+  }
+  for (const diagnostic of payload.diagnostics || []) {
+    console.log(`[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`);
+  }
+}
+
+/**
+ * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, json: boolean, cwd: string }} context
+ * @returns {number}
+ */
+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;
+  }
+  if (commandArgs.extractorCommand === "list") {
+    const payload = buildExtractorListPayload(cwd);
+    if (json) console.log(stableStringify(payload));
+    else printExtractorList(payload);
+    return payload.ok ? 0 : 1;
+  }
+  if (commandArgs.extractorCommand === "show") {
+    const payload = buildExtractorShowPayload(inputPath || "", cwd);
+    if (json) console.log(stableStringify(payload));
+    else printExtractorShow(payload);
+    return payload.ok ? 0 : 1;
+  }
+  if (commandArgs.extractorPolicyCommand === "init") {
+    const payload = buildExtractorPolicyInitPayload(inputPath || ".");
+    if (json) console.log(stableStringify(payload));
+    else printExtractorPolicyInit(payload);
+    return 0;
+  }
+  if (commandArgs.extractorPolicyCommand === "status" || commandArgs.extractorPolicyCommand === "check" || commandArgs.extractorPolicyCommand === "explain") {
+    const payload = buildExtractorPolicyStatusPayload(inputPath || ".");
+    if (json) console.log(stableStringify(payload));
+    else printExtractorPolicyStatus(payload);
+    return payload.ok ? 0 : 1;
+  }
+  if (commandArgs.extractorPolicyCommand === "pin") {
+    const payload = buildExtractorPolicyPinPayload(inputPath || ".", commandArgs.extractorPolicyPinSpec);
+    if (json) console.log(stableStringify(payload));
+    else printExtractorPolicyPin(payload);
+    return payload.ok ? 0 : 1;
+  }
+  throw new Error(`Unknown extractor command '${commandArgs.extractorCommand || commandArgs.extractorPolicyCommand}'`);
+}

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

@@ -4,7 +4,7 @@ import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { TOPOGRAM_IMPORT_ADOPTIONS_FILE } from "./paths.js";
 
 export function printExtractHelp() {
-  console.log("Usage: topogram extract <app-path> --out <target> [--from <track[,track]>] [--json]");
+  console.log("Usage: topogram extract <app-path> --out <target> [--from <track[,track]>] [--extractor <id-or-package-or-path>] [--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]");
@@ -26,6 +26,8 @@ export function printExtractHelp() {
   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 ./existing-cli --out ./extracted-topogram --from cli --extractor @topogram/extractor-node-cli");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram --extractor-policy ./topogram.extractor-policy.json");
   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");

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

@@ -149,7 +149,7 @@ export function countFilesRecursive(rootPath) {
 /**
  * @param {string} sourcePath
  * @param {string} targetPath
- * @param {{ from?: string|null }} [options]
+ * @param {{ from?: string|null, extractorSpecs?: string[], extractorPolicyPath?: string|null, cwd?: string|null }} [options]
  * @returns {{ ok: boolean, sourcePath: string, targetPath: string, workspaceRoot: string, topogramRoot: string, projectConfigPath: string, provenancePath: string, tracks: string[], sourceFiles: number, rawCandidateFiles: number, reconcileFiles: number, writtenFiles: string[], candidateCounts: Record<string, number>, nextCommands: string[] }}
  */
 export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, options = {}) {
@@ -166,7 +166,12 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
   const topogramRoot = path.join(targetRoot, DEFAULT_TOPO_FOLDER_NAME);
   fs.mkdirSync(topogramRoot, { recursive: true });
   const sourceFiles = collectImportSourceFileRecords(sourceRoot, { excludeRoots: [targetRoot] });
-  const importResult = runWorkflow("import-app", sourceRoot, { from: options.from || null });
+  const importResult = runWorkflow("import-app", sourceRoot, {
+    from: options.from || null,
+    extractorSpecs: options.extractorSpecs || [],
+    extractorPolicyPath: options.extractorPolicyPath || null,
+    cwd: options.cwd || process.cwd()
+  });
   const rawCandidateFiles = writeRelativeFiles(topogramRoot, importResult.files || {});
 
   const projectConfigPath = path.join(targetRoot, "topogram.project.json");
@@ -182,6 +187,7 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
     tracks: importResult.summary.tracks || [],
     findingsCount: importResult.summary.findings_count || 0,
     candidateCounts,
+    extractorPackages: importResult.summary.package_extractors || [],
     files: sourceFiles
   });
   const writtenFiles = [

package/src/cli/commands/import-runner.js

@@ -25,7 +25,7 @@ import {
 } from "./import.js";
 
 /**
- * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
+ * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, extractorSpecs?: string[], extractorPolicyPath?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
  * @returns {number}
  */
 export function runImportCommand(context) {
@@ -34,6 +34,8 @@ export function runImportCommand(context) {
     inputPath,
     outPath = null,
     fromValue = null,
+    extractorSpecs = [],
+    extractorPolicyPath = null,
     reasonValue = null,
     refreshAdopted = false,
     dryRun = false,
@@ -49,7 +51,7 @@ export function runImportCommand(context) {
       printExtractHelp();
       return 1;
     }
-    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue });
+    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue, extractorSpecs, extractorPolicyPath, cwd: process.cwd() });
     if (json) {
       console.log(stableStringify(payload));
     } else {

package/src/cli/dispatcher.js

@@ -8,6 +8,7 @@ import { runCheckCommand } from "./commands/check.js";
 import { runCopyCommand } from "./commands/copy.js";
 import { runEmitCommand } from "./commands/emit.js";
 import { runGenerateAppCommand } from "./commands/generate.js";
+import { runExtractorCommand } from "./commands/extractor.js";
 import { runGeneratorCommand } from "./commands/generator.js";
 import { runGeneratorPolicyCommand } from "./commands/generator-policy.js";
 import { runImportCommand } from "./commands/import-runner.js";
@@ -81,6 +82,8 @@ export async function runCliDispatch(context) {
     workflowName,
     workflowId,
     fromValue,
+    extractorSpecs,
+    extractorPolicyPath,
     adoptValue,
     reasonValue,
     modeId,
@@ -225,6 +228,15 @@ export async function runCliDispatch(context) {
     });
   }
 
+  if (commandArgs?.extractorCommand || commandArgs?.extractorPolicyCommand) {
+    return runExtractorCommand({
+      commandArgs,
+      inputPath,
+      json: emitJson,
+      cwd: process.cwd()
+    });
+  }
+
   if (commandArgs?.generatorPolicyCommand) {
     return runGeneratorPolicyCommand({ commandArgs, inputPath, json: emitJson });
   }
@@ -259,6 +271,8 @@ export async function runCliDispatch(context) {
       inputPath,
       outPath,
       fromValue,
+      extractorSpecs,
+      extractorPolicyPath,
       reasonValue,
       refreshAdopted,
       dryRun: args.includes("--dry-run"),

package/src/cli/help-dispatch.js

@@ -12,6 +12,9 @@ import {
 import {
   printDoctorHelp
 } from "./commands/doctor.js";
+import {
+  printExtractorHelp
+} from "./commands/extractor.js";
 import {
   printGeneratorHelp
 } from "./commands/generator.js";
@@ -86,6 +89,10 @@ export function printCommandHelp(command) {
     printGeneratorHelp();
     return true;
   }
+  if (command === "extractor") {
+    printExtractorHelp();
+    return true;
+  }
   if (command === "template") {
     printTemplateHelp();
     return true;
@@ -176,6 +183,10 @@ export function handleUnparsedCommandHelp(args) {
     printGeneratorHelp();
     return args[1] ? 1 : 0;
   }
+  if (args[0] === "extractor") {
+    printExtractorHelp();
+    return args[1] ? 1 : 0;
+  }
   if (args[0] === "template") {
     printTemplateHelp();
     return args[1] ? 1 : 0;