@topogram/cli 0.3.83 → 0.3.85

package/package.json

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

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

@@ -2,6 +2,17 @@
 
 import { commandPath } from "./shared.js";
 
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {string|null}
+ */
+function optionValue(args, flag) {
+  const index = args.indexOf(flag);
+  const value = index >= 0 ? args[index + 1] : null;
+  return value && !value.startsWith("-") ? value : null;
+}
+
 /**
  * @param {string[]} args
  * @returns {import("./shared.js").SplitCommandArgs|null}
@@ -16,6 +27,15 @@ export function parseExtractorCommandArgs(args) {
   if (args[0] === "extractor" && args[1] === "check") {
     return { extractorCommand: "check", inputPath: args[2] };
   }
+  if (args[0] === "extractor" && args[1] === "scaffold") {
+    return {
+      extractorCommand: "scaffold",
+      inputPath: args[2],
+      extractorScaffoldTrack: optionValue(args, "--track"),
+      extractorScaffoldPackage: optionValue(args, "--package"),
+      extractorScaffoldId: optionValue(args, "--id")
+    };
+  }
   if (args[0] === "extractor" && args[1] === "policy" && args[2] === "init") {
     return { extractorPolicyCommand: "init", inputPath: commandPath(args, 3, ".") };
   }
@@ -37,4 +57,3 @@ export function parseExtractorCommandArgs(args) {
   }
   return null;
 }
-

package/src/cli/commands/extractor.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { stableStringify } from "../../format.js";
 import { checkExtractorPack } from "../../extractor/check.js";
 import { FIRST_PARTY_EXTRACTOR_PACKAGES, firstPartyExtractorInfo } from "../../extractor/first-party.js";
+import { scaffoldExtractorPack } from "../../extractor/scaffold.js";
 import {
   EXTRACTOR_MANIFESTS,
   getExtractorManifest,
@@ -30,6 +31,7 @@ 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 scaffold <target> [--track <track>] [--package <name>] [--id <manifest-id>] [--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]");
@@ -48,11 +50,37 @@ export function printExtractorHelp() {
   console.log("  topogram extractor show topogram/api-extractors");
   console.log("  topogram extractor show @topogram/extractor-prisma-db");
   console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor scaffold ./topogram-extractor-node-cli --track cli --package @scope/topogram-extractor-node-cli");
   console.log("  topogram extractor policy init");
   console.log("  topogram extractor policy pin @topogram/extractor-node-cli@1");
   console.log("  topogram extract ./express-api --out ./imported-topogram --from api --extractor @topogram/extractor-express-api");
 }
 
+/**
+ * @param {ReturnType<typeof scaffoldExtractorPack>} payload
+ * @returns {void}
+ */
+export function printExtractorScaffold(payload) {
+  console.log(payload.ok ? "Extractor scaffold created." : "Extractor scaffold failed.");
+  console.log(`Target: ${payload.target}`);
+  if (payload.packageName) console.log(`Package: ${payload.packageName}`);
+  if (payload.manifestId) console.log(`Manifest id: ${payload.manifestId}`);
+  if (payload.track) console.log(`Track: ${payload.track}`);
+  if (payload.files.length > 0) {
+    console.log("Files:");
+    for (const file of payload.files) {
+      console.log(`- ${file}`);
+    }
+  }
+  if (payload.nextCommands.length > 0) {
+    console.log("Next commands:");
+    for (const command of payload.nextCommands) {
+      console.log(`- ${command}`);
+    }
+  }
+  for (const error of payload.errors || []) console.log(`Error: ${error}`);
+}
+
 /**
  * @param {string} cwd
  * @returns {string[]}
@@ -587,6 +615,16 @@ export function runExtractorCommand(context) {
     else printExtractorCheck(payload);
     return payload.ok ? 0 : 1;
   }
+  if (commandArgs.extractorCommand === "scaffold") {
+    const payload = scaffoldExtractorPack(inputPath || "", {
+      track: commandArgs.extractorScaffoldTrack,
+      packageName: commandArgs.extractorScaffoldPackage,
+      manifestId: commandArgs.extractorScaffoldId
+    });
+    if (json) console.log(stableStringify(payload));
+    else printExtractorScaffold(payload);
+    return payload.ok ? 0 : 1;
+  }
   if (commandArgs.extractorCommand === "list") {
     const payload = buildExtractorListPayload(cwd);
     if (json) console.log(stableStringify(payload));

package/src/cli/help.js

@@ -71,6 +71,7 @@ export function printUsage(options = {}) {
   console.log("   or: 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 scaffold <target> [--track <track>] [--package <name>] [--id <manifest-id>] [--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]");
@@ -111,6 +112,7 @@ export function printUsage(options = {}) {
   console.log("  topogram extractor list");
   console.log("  topogram extractor show @topogram/extractor-prisma-db");
   console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor scaffold ./topogram-extractor-node-cli --track cli --package @scope/topogram-extractor-node-cli");
   console.log("  topogram extractor policy check");
   console.log("  topogram extract ./express-api --out ./extracted-topogram --from api --extractor @topogram/extractor-express-api");
   console.log("  topogram generate");

package/src/extractor/check.js

@@ -5,6 +5,7 @@ import {
   loadExtractorPackageAdapterForSpec,
   validateExtractorAdapter
 } from "./packages.js";
+import { validateExtractorResult } from "./output.js";
 
 /**
  * @typedef {import("./registry.js").ExtractorManifest} ExtractorManifest
@@ -25,39 +26,6 @@ import {
  * @property {boolean} executesPackageCode
  */
 
-/**
- * @param {any} result
- * @returns {{ ok: boolean, message: string, smoke: { findings: number, candidateKeys: number, diagnostics: number }|null }}
- */
-function validateExtractResult(result) {
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    return { ok: false, message: "extract(context) must return an object", smoke: null };
-  }
-  if (result.findings != null && !Array.isArray(result.findings)) {
-    return { ok: false, message: "extract(context) findings must be an array when present", smoke: null };
-  }
-  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
-    return { ok: false, message: "extract(context) diagnostics must be an array when present", smoke: null };
-  }
-  if (!result.candidates || typeof result.candidates !== "object" || Array.isArray(result.candidates)) {
-    return { ok: false, message: "extract(context) result must include a candidates object", smoke: null };
-  }
-  for (const [key, value] of Object.entries(result.candidates)) {
-    if (!Array.isArray(value)) {
-      return { ok: false, message: `extract(context) candidates.${key} must be an array`, smoke: null };
-    }
-  }
-  return {
-    ok: true,
-    message: `extract(context) returned ${Object.keys(result.candidates).length} candidate bucket(s)`,
-    smoke: {
-      findings: Array.isArray(result.findings) ? result.findings.length : 0,
-      candidateKeys: Object.keys(result.candidates).length,
-      diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.length : 0
-    }
-  };
-}
-
 /**
  * @param {string} sourceSpec
  * @param {{ cwd?: string }} [options]
@@ -126,9 +94,9 @@ export function checkExtractorPack(sourceSpec, options = {}) {
         continue;
       }
       const result = extractor.extract(context) || { findings: [], candidates: {} };
-      const validation = validateExtractResult(result);
+      const validation = validateExtractorResult(result, { track: extractor.track, strictCandidates: true });
       if (!validation.ok || !validation.smoke) {
-        payload.errors.push(`Extractor '${extractor.id}' ${validation.message}.`);
+        payload.errors.push(...validation.errors.map((message) => `Extractor '${extractor.id}' ${message}.`));
         continue;
       }
       totalFindings += validation.smoke.findings;
@@ -152,4 +120,3 @@ export function checkExtractorPack(sourceSpec, options = {}) {
   payload.ok = payload.errors.length === 0;
   return payload;
 }
-

package/src/extractor/output.js

@@ -0,0 +1,220 @@
+// @ts-check
+
+/**
+ * @typedef {Object} ExtractorResultValidationOptions
+ * @property {string} [track]
+ * @property {boolean} [strictCandidates]
+ */
+
+/**
+ * @typedef {Object} ExtractorResultValidation
+ * @property {boolean} ok
+ * @property {string[]} errors
+ * @property {{ findings: number, candidateKeys: number, diagnostics: number }|null} smoke
+ */
+
+/** @type {Record<string, Set<string>>} */
+const TRACK_CANDIDATE_BUCKETS = {
+  db: new Set(["entities", "enums", "relations", "indexes", "maintained_seams"]),
+  api: new Set(["capabilities", "routes", "stacks"]),
+  ui: new Set(["screens", "routes", "actions", "flows", "widgets", "shapes", "stacks"]),
+  cli: new Set(["commands", "capabilities", "surfaces"]),
+  workflows: new Set(["workflows", "workflow_states", "workflow_transitions"]),
+  verification: new Set(["verifications", "scenarios", "frameworks", "scripts"])
+};
+
+const DISALLOWED_BUCKETS = new Set([
+  "adoption",
+  "adoption_plan",
+  "adoptionPlan",
+  "canonical",
+  "canonical_files",
+  "canonicalFiles",
+  "files",
+  "patches",
+  "project_config",
+  "projectConfig",
+  "topo",
+  "topogram",
+  "topogram_project",
+  "topogramProject",
+  "writeFiles",
+  "writes",
+  "writtenFiles"
+]);
+
+const DISALLOWED_RECORD_KEYS = new Set([
+  "adoption",
+  "adoptionPlan",
+  "canonical",
+  "canonicalFiles",
+  "files",
+  "patches",
+  "receipt",
+  "topo",
+  "topogram",
+  "write",
+  "writeFiles",
+  "writes",
+  "writtenFiles"
+]);
+
+/**
+ * Keys that carry local source/package file references. Deliberately excludes
+ * command/route `path` and config target dotted `path` values.
+ */
+const PATH_KEYS = new Set([
+  "configFile",
+  "configPath",
+  "file",
+  "filePath",
+  "migrationPath",
+  "migrationsPath",
+  "schemaPath",
+  "snapshotPath",
+  "sourceFile",
+  "sourcePath",
+  "source_path",
+  "targetFile",
+  "targetPath"
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {string} candidatePath
+ * @returns {boolean}
+ */
+function isUnsafeRelativePath(candidatePath) {
+  return candidatePath.startsWith("/") || candidatePath === ".." || candidatePath.startsWith("../") || candidatePath.includes("/../");
+}
+
+/**
+ * @param {string} bucket
+ * @param {Record<string, unknown>} candidate
+ * @returns {string[]}
+ */
+function identityFieldsForBucket(bucket, candidate) {
+  if (bucket === "commands") return ["command_id", "id_hint"];
+  if (bucket === "routes") {
+    if (typeof candidate.method === "string" && typeof candidate.path === "string") {
+      return [];
+    }
+    return ["id_hint", "id"];
+  }
+  return ["id_hint", "id", "name"];
+}
+
+/**
+ * @param {string} bucket
+ * @param {Record<string, unknown>} candidate
+ * @param {string} pathLabel
+ * @returns {string[]}
+ */
+function validateCandidateIdentity(bucket, candidate, pathLabel) {
+  const fields = identityFieldsForBucket(bucket, candidate);
+  if (fields.length === 0) return [];
+  if (fields.some((field) => typeof candidate[field] === "string" && String(candidate[field]).trim().length > 0)) {
+    return [];
+  }
+  return [`${pathLabel} must include an identity field: ${fields.join(" or ")}`];
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} pathLabel
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function validateNoUnsafeRecords(value, pathLabel, errors) {
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      validateNoUnsafeRecords(value[index], `${pathLabel}[${index}]`, errors);
+    }
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${pathLabel}.${key}`;
+    if (DISALLOWED_RECORD_KEYS.has(key)) {
+      errors.push(`${childPath} is not allowed in extractor candidate output; extractors emit review candidates, not adoption plans or files.`);
+      continue;
+    }
+    if (PATH_KEYS.has(key) && typeof child === "string" && isUnsafeRelativePath(child)) {
+      errors.push(`${childPath} must be a safe project-relative path.`);
+      continue;
+    }
+    validateNoUnsafeRecords(child, childPath, errors);
+  }
+}
+
+/**
+ * @param {unknown} result
+ * @param {ExtractorResultValidationOptions} [options]
+ * @returns {ExtractorResultValidation}
+ */
+export function validateExtractorResult(result, options = {}) {
+  const errors = [];
+  if (!isPlainObject(result)) {
+    return { ok: false, errors: ["extract(context) must return an object"], smoke: null };
+  }
+  if (result.findings != null && !Array.isArray(result.findings)) {
+    errors.push("extract(context) findings must be an array when present");
+  }
+  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
+    errors.push("extract(context) diagnostics must be an array when present");
+  }
+  if (!isPlainObject(result.candidates)) {
+    errors.push("extract(context) result must include a candidates object");
+    return { ok: false, errors, smoke: null };
+  }
+
+  const allowedBuckets = options.track ? TRACK_CANDIDATE_BUCKETS[options.track] : null;
+  const candidateKeys = Object.keys(result.candidates);
+  for (const [bucket, value] of Object.entries(result.candidates)) {
+    const bucketLabel = `extract(context) candidates.${bucket}`;
+    if (DISALLOWED_BUCKETS.has(bucket)) {
+      errors.push(`${bucketLabel} is not allowed; extractors must not return adoption plans, canonical files, patches, or topo writes.`);
+      continue;
+    }
+    if (options.strictCandidates && allowedBuckets && !allowedBuckets.has(bucket)) {
+      errors.push(`${bucketLabel} is not allowed for track '${options.track}'.`);
+      continue;
+    }
+    if (!Array.isArray(value)) {
+      errors.push(`${bucketLabel} must be an array`);
+      continue;
+    }
+    if (!options.strictCandidates) continue;
+    for (let index = 0; index < value.length; index += 1) {
+      const candidate = value[index];
+      const candidateLabel = `${bucketLabel}[${index}]`;
+      if (!isPlainObject(candidate)) {
+        errors.push(`${candidateLabel} must be an object.`);
+        continue;
+      }
+      errors.push(...validateCandidateIdentity(bucket, candidate, candidateLabel));
+      validateNoUnsafeRecords(candidate, candidateLabel, errors);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    smoke: errors.length === 0
+      ? {
+          findings: Array.isArray(result.findings) ? result.findings.length : 0,
+          candidateKeys: candidateKeys.length,
+          diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.length : 0
+        }
+      : null
+  };
+}
+
+export { TRACK_CANDIDATE_BUCKETS };

package/src/extractor/scaffold.js

@@ -0,0 +1,487 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../format.js";
+import { EXTRACTOR_TRACKS } from "./registry.js";
+
+const DEFAULT_TRACK = "cli";
+
+/**
+ * @typedef {Object} ExtractorScaffoldOptions
+ * @property {string|null|undefined} [packageName]
+ * @property {string|null|undefined} [manifestId]
+ * @property {string|null|undefined} [track]
+ */
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function slugify(value) {
+  return String(value || "extractor")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "extractor";
+}
+
+/**
+ * @param {string} target
+ * @returns {string}
+ */
+function defaultPackageName(target) {
+  const basename = slugify(path.basename(path.resolve(target)));
+  return basename.startsWith("topogram-extractor-") ? basename : `topogram-extractor-${basename}`;
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isValidPackageName(value) {
+  return /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+
+/**
+ * @returns {string}
+ */
+function currentCliVersion() {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return typeof packageJson.version === "string" && packageJson.version ? packageJson.version : "latest";
+  } catch {
+    return "latest";
+  }
+}
+
+/**
+ * @param {string} packageName
+ * @param {string} track
+ * @returns {string}
+ */
+function extractorId(packageName, track) {
+  const bareName = packageName.split("/").pop() || packageName;
+  return `${track}.${slugify(bareName.replace(/^topogram-extractor-/, "").replace(/^extractor-/, ""))}`;
+}
+
+/**
+ * @param {string} track
+ * @returns {{ stack: Record<string, string>, capabilities: Record<string, boolean>, candidateKinds: string[], fixtureFiles: Record<string, string> }}
+ */
+function trackDefaults(track) {
+  if (track === "db") {
+    return {
+      stack: { domain: "database", framework: "scaffold" },
+      capabilities: { schema: true },
+      candidateKinds: ["entity"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-db", private: true })}\n`,
+        "src/schema.sql": "create table scaffold_records (id text primary key, name text not null);\n"
+      }
+    };
+  }
+  if (track === "api") {
+    return {
+      stack: { runtime: "node", framework: "scaffold" },
+      capabilities: { routes: true },
+      candidateKinds: ["capability", "route", "stack"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-api", private: true })}\n`,
+        "src/server.js": "app.get('/scaffold-records', listScaffoldRecords);\n"
+      }
+    };
+  }
+  if (track === "ui") {
+    return {
+      stack: { framework: "scaffold-ui" },
+      capabilities: { screens: true, flows: true },
+      candidateKinds: ["screen", "route", "flow"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-ui", private: true })}\n`,
+        "src/routes/scaffold-records.jsx": "export default function ScaffoldRecords() { return <main>Scaffold records</main>; }\n"
+      }
+    };
+  }
+  if (track === "workflows") {
+    return {
+      stack: { domain: "workflow" },
+      capabilities: { workflows: true },
+      candidateKinds: ["workflow"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-workflows", private: true })}\n`,
+        "docs/workflows.md": "# Scaffold workflow\n\n- draft\n- review\n- complete\n"
+      }
+    };
+  }
+  if (track === "verification") {
+    return {
+      stack: { domain: "verification" },
+      capabilities: { verifications: true },
+      candidateKinds: ["verification"],
+      fixtureFiles: {
+        "package.json": `${stableStringify({ name: "topogram-extractor-fixture-verification", private: true, scripts: { test: "node test.js" } })}\n`,
+        "test.js": "console.log('scaffold verification fixture');\n"
+      }
+    };
+  }
+  return {
+    stack: { runtime: "node", framework: "generic-cli" },
+    capabilities: { commands: true, options: true, effects: true },
+    candidateKinds: ["command", "capability", "cli_surface"],
+    fixtureFiles: {
+      "package.json": `${stableStringify({ name: "topogram-extractor-fixture-cli", private: true, bin: { scaffold: "./bin/scaffold.js" } })}\n`,
+      "bin/scaffold.js": "#!/usr/bin/env node\nconsole.log('Usage: scaffold check --json');\n"
+    }
+  };
+}
+
+/**
+ * @param {string} track
+ * @returns {string}
+ */
+function candidateSourceForTrack(track) {
+  if (track === "db") {
+    return `{
+        entities: [{
+          id_hint: "entity_scaffold_record",
+          label: "Scaffold Record",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"],
+          fields: [{ name: "id", field_type: "string", required: true }]
+        }]
+      }`;
+  }
+  if (track === "api") {
+    return `{
+        capabilities: [{
+          id_hint: "cap_list_scaffold_records",
+          label: "List scaffold records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        routes: [{
+          method: "GET",
+          path: "/scaffold-records",
+          capability_hint: "cap_list_scaffold_records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        stacks: ["scaffold-api"]
+      }`;
+  }
+  if (track === "ui") {
+    return `{
+        screens: [{
+          id_hint: "screen_scaffold_records",
+          label: "Scaffold Records",
+          screen_kind: "list",
+          route_path: "/scaffold-records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        routes: [{
+          id_hint: "route_scaffold_records",
+          path: "/scaffold-records",
+          screen_id: "screen_scaffold_records",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        flows: [],
+        stacks: ["scaffold-ui"]
+      }`;
+  }
+  if (track === "workflows") {
+    return `{
+        workflows: [{
+          id_hint: "workflow_scaffold_review",
+          label: "Scaffold Review",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }]
+      }`;
+  }
+  if (track === "verification") {
+    return `{
+        verifications: [{
+          id_hint: "verification_scaffold_check",
+          label: "Scaffold Check",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        frameworks: ["scaffold"],
+        scripts: [{
+          id_hint: "script_scaffold_check",
+          command: "npm test",
+          confidence: "low",
+          provenance: ["package-extractor-scaffold"]
+        }]
+      }`;
+  }
+  return `{
+        commands: [{
+          command_id: "scaffold_check",
+          label: "Scaffold Check",
+          usage: "scaffold check --json",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        capabilities: [{
+          id_hint: "cap_scaffold_check",
+          label: "Run scaffold check",
+          command_id: "scaffold_check",
+          provenance: ["package-extractor-scaffold"]
+        }],
+        surfaces: [{
+          id_hint: "proj_cli_surface",
+          commands: ["scaffold_check"],
+          options: [{ command_id: "scaffold_check", name: "json", flag: "--json", type: "boolean", required: false }],
+          effects: [{ command_id: "scaffold_check", effect: "read_only" }],
+          provenance: ["package-extractor-scaffold"]
+        }]
+      }`;
+}
+
+/**
+ * @param {string} track
+ * @param {string} extractor
+ * @returns {string}
+ */
+function adapterSource(track, extractor) {
+  return `const manifest = require("./topogram-extractor.json");
+
+exports.manifest = manifest;
+exports.extractors = [{
+  id: ${JSON.stringify(extractor)},
+  track: ${JSON.stringify(track)},
+  detect(context) {
+    return { score: 1, reasons: ["Scaffold extractor runs against the included fixture."] };
+  },
+  extract(context) {
+    return {
+      findings: [{
+        kind: "scaffold_finding",
+        message: "Replace this scaffold extractor with precise framework evidence.",
+        evidence: ["fixtures/basic-source"]
+      }],
+      candidates: ${candidateSourceForTrack(track)},
+      diagnostics: []
+    };
+  }
+}];
+`;
+}
+
+/**
+ * @param {string} packageName
+ * @param {string} track
+ * @returns {string}
+ */
+function checkScriptSource(packageName, track) {
+  return `import childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const packageName = packageJson.name || ${JSON.stringify(packageName)};
+const track = ${JSON.stringify(track)};
+const topogramBin = process.env.TOPOGRAM_BIN || "topogram";
+const root = process.cwd();
+
+function run(args, options = {}) {
+  const result = childProcess.spawnSync(topogramBin, args, {
+    cwd: options.cwd || root,
+    encoding: "utf8",
+    env: { ...process.env, FORCE_COLOR: "0" },
+    maxBuffer: 1024 * 1024 * 10
+  });
+  if (result.status !== 0) {
+    process.stderr.write(result.stdout || "");
+    process.stderr.write(result.stderr || "");
+    throw new Error(\`Command failed: \${topogramBin} \${args.join(" ")}\`);
+  }
+  return result.stdout;
+}
+
+function snapshotFixture() {
+  const fixtureRoot = path.join(root, "fixtures", "basic-source");
+  const files = [];
+  function visit(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push([path.relative(fixtureRoot, absolute), fs.readFileSync(absolute, "utf8")]);
+    }
+  }
+  visit(fixtureRoot);
+  return JSON.stringify(files.sort());
+}
+
+run(["extractor", "check", "."]);
+
+const before = snapshotFixture();
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "topogram-extractor-smoke."));
+const policyPath = path.join(tmp, "topogram.extractor-policy.json");
+fs.writeFileSync(policyPath, JSON.stringify({
+  version: "0.1",
+  allowedPackageScopes: [],
+  allowedPackages: [packageName],
+  pinnedVersions: { [packageName]: "1" },
+  enabledPackages: []
+}, null, 2) + "\\n", "utf8");
+
+const extracted = path.join(tmp, "extracted");
+run([
+  "extract",
+  path.join(root, "fixtures", "basic-source"),
+  "--out",
+  extracted,
+  "--from",
+  track,
+  "--extractor",
+  ".",
+  "--extractor-policy",
+  policyPath,
+  "--json"
+]);
+run(["extract", "plan", extracted, "--json"]);
+run(["query", "extract-plan", path.join(extracted, "topo"), "--json"]);
+run(["adopt", "--list", extracted, "--json"]);
+
+const after = snapshotFixture();
+if (after !== before) {
+  throw new Error("Extractor smoke mutated fixture source files.");
+}
+
+console.log(\`Extractor package smoke passed for \${packageName}.\`);
+`;
+}
+
+/**
+ * @param {Record<string, string>} files
+ * @returns {string[]}
+ */
+function writeFiles(files) {
+  const written = [];
+  for (const [filePath, contents] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, contents, "utf8");
+    written.push(filePath);
+  }
+  return written.sort();
+}
+
+/**
+ * @param {string} target
+ * @param {ExtractorScaffoldOptions} [options]
+ * @returns {{ ok: boolean, target: string, packageName: string|null, manifestId: string|null, track: string|null, files: string[], nextCommands: string[], errors: string[] }}
+ */
+export function scaffoldExtractorPack(target, options = {}) {
+  const absoluteTarget = path.resolve(target || "");
+  if (!target || target.startsWith("-")) {
+    return { ok: false, target: absoluteTarget, packageName: null, manifestId: null, track: null, files: [], nextCommands: [], errors: ["Usage: topogram extractor scaffold <target> [--track <track>] [--package <name>] [--id <manifest-id>]"] };
+  }
+  if (fs.existsSync(absoluteTarget) && fs.readdirSync(absoluteTarget).length > 0) {
+    return { ok: false, target: absoluteTarget, packageName: null, manifestId: null, track: null, files: [], nextCommands: [], errors: [`Extractor scaffold target '${absoluteTarget}' already exists and is not empty.`] };
+  }
+
+  const track = options.track || DEFAULT_TRACK;
+  if (!EXTRACTOR_TRACKS.includes(track)) {
+    return { ok: false, target: absoluteTarget, packageName: null, manifestId: null, track, files: [], nextCommands: [], errors: [`Extractor track '${track}' is not supported. Expected one of: ${EXTRACTOR_TRACKS.join(", ")}.`] };
+  }
+
+  const packageName = options.packageName || defaultPackageName(absoluteTarget);
+  if (!isValidPackageName(packageName)) {
+    return { ok: false, target: absoluteTarget, packageName, manifestId: null, track, files: [], nextCommands: [], errors: [`Extractor package name '${packageName}' is invalid. Use a lowercase npm package name such as @scope/topogram-extractor-example.`] };
+  }
+  const manifestId = options.manifestId || packageName;
+  const extractor = extractorId(packageName, track);
+  const defaults = trackDefaults(track);
+  const manifest = {
+    id: manifestId,
+    version: "1",
+    tracks: [track],
+    source: "package",
+    package: packageName,
+    stack: defaults.stack,
+    capabilities: defaults.capabilities,
+    candidateKinds: defaults.candidateKinds,
+    evidenceTypes: ["runtime_source"],
+    extractors: [extractor]
+  };
+  const packageJson = {
+    name: packageName,
+    version: "0.1.0",
+    private: true,
+    description: "Topogram extractor pack scaffold.",
+    main: "index.cjs",
+    files: [
+      "index.cjs",
+      "topogram-extractor.json",
+      "README.md",
+      "scripts",
+      "fixtures"
+    ],
+    scripts: {
+      check: "node ./scripts/check-extractor.mjs"
+    },
+    devDependencies: {
+      "@topogram/cli": `^${currentCliVersion()}`
+    }
+  };
+  const files = {
+    [path.join(absoluteTarget, "package.json")]: `${stableStringify(packageJson)}\n`,
+    [path.join(absoluteTarget, "topogram-extractor.json")]: `${stableStringify(manifest)}\n`,
+    [path.join(absoluteTarget, "index.cjs")]: adapterSource(track, extractor),
+    [path.join(absoluteTarget, "scripts", "check-extractor.mjs")]: checkScriptSource(packageName, track),
+    [path.join(absoluteTarget, "README.md")]: `# ${packageName}
+
+This is a Topogram extractor pack scaffold for the \`${track}\` track.
+
+## Author Loop
+
+\`\`\`bash
+npm install
+npm run check
+\`\`\`
+
+\`npm run check\` runs:
+
+- \`topogram extractor check .\`
+- \`topogram extract ./fixtures/basic-source --out <tmp> --from ${track} --extractor .\`
+- \`topogram extract plan <tmp>\`
+- \`topogram query extract-plan <tmp>/topo\`
+- \`topogram adopt --list <tmp>\`
+
+Replace the scaffold adapter in \`index.cjs\` with precise, read-only source evidence.
+Extractor packages must not mutate source files, write canonical \`topo/**\`, install
+packages, perform network access, or define adoption semantics.
+
+Candidate output is validated by track. Return only review candidate buckets for
+the declared track, give each candidate a stable identity, keep file evidence
+project-relative, and never return files, patches, adoption plans, or write
+instructions.
+`
+  };
+  for (const [relative, contents] of Object.entries(defaults.fixtureFiles)) {
+    files[path.join(absoluteTarget, "fixtures", "basic-source", relative)] = contents;
+  }
+
+  const written = writeFiles(files);
+  return {
+    ok: true,
+    target: absoluteTarget,
+    packageName,
+    manifestId,
+    track,
+    files: written.map((filePath) => path.relative(absoluteTarget, filePath).replace(/\\/g, "/")),
+    nextCommands: [
+      `cd ${absoluteTarget}`,
+      "npm install",
+      "npm run check",
+      "topogram extractor check ."
+    ],
+    errors: []
+  };
+}

package/src/import/core/runner/tracks.js

@@ -3,6 +3,7 @@
 import { getEnrichersForTrack, getExtractorsForTrack } from "../registry.js";
 import { normalizeCandidatesForTrack } from "./candidates.js";
 import { packageExtractorsForContext } from "../../../extractor/packages.js";
+import { validateExtractorResult } from "../../../extractor/output.js";
 
 /**
  * @param {any} context
@@ -140,25 +141,12 @@ function initialCandidatesForTrack(track) {
  */
 function assertExtractorResultShape(extractor, result) {
   const label = extractor?.id || "unknown";
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    throw new Error(`Extractor '${label}' extract(context) must return an object.`);
-  }
-  if (result.findings != null && !Array.isArray(result.findings)) {
-    throw new Error(`Extractor '${label}' extract(context) findings must be an array when present.`);
-  }
-  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
-    throw new Error(`Extractor '${label}' extract(context) diagnostics must be an array when present.`);
-  }
-  if (result.candidates == null) {
-    result.candidates = {};
-  }
-  if (!result.candidates || typeof result.candidates !== "object" || Array.isArray(result.candidates)) {
-    throw new Error(`Extractor '${label}' extract(context) candidates must be an object.`);
-  }
-  for (const [key, value] of Object.entries(result.candidates)) {
-    if (!Array.isArray(value)) {
-      throw new Error(`Extractor '${label}' extract(context) candidates.${key} must be an array.`);
-    }
+  const validation = validateExtractorResult(result, {
+    track: extractor?.track,
+    strictCandidates: extractor?.source === "package"
+  });
+  if (!validation.ok) {
+    throw new Error(validation.errors.map((message) => `Extractor '${label}' ${message}.`).join("\n"));
   }
 }