@topogram/cli 0.3.78 → 0.3.80

package/src/generator/context/slice/sdlc.js

@@ -49,9 +49,16 @@ import {
 export function journeySlice(graph, journeyId) {
   const journey = getJourneyDoc(graph, journeyId);
   const capabilities = [...(journey.relatedCapabilities || [])].sort();
+  const entities = [...(journey.relatedEntities || [])].sort();
+  const rules = [...(journey.relatedRules || [])].sort();
   const workflows = [...(journey.relatedWorkflows || [])].sort();
   const projections = [...(journey.relatedProjections || [])].sort();
-  const verifications = verificationIdsForTarget(graph, [...capabilities, ...workflows, ...projections, journeyId]);
+  const widgets = [...(journey.relatedWidgets || [])].sort();
+  const declaredVerifications = [...(journey.relatedVerifications || [])].sort();
+  const verifications = [...new Set([
+    ...declaredVerifications,
+    ...verificationIdsForTarget(graph, [...capabilities, ...workflows, ...projections, ...widgets, journeyId])
+  ])].sort();
 
   return {
     type: "context_slice",
@@ -63,14 +70,36 @@ export function journeySlice(graph, journeyId) {
     summary: summarizeById(graph, journeyId),
     depends_on: {
       capabilities,
+      entities,
+      rules,
       workflows,
       projections,
+      widgets,
       verifications
     },
+    steps: (journey.steps || []).map(/** @param {any} step */ (step) => ({
+      id: step.id,
+      intent: step.intent,
+      commands: [...(step.commands || [])],
+      expects: [...(step.expects || [])],
+      after: [...(step.after || [])],
+      notes: step.notes || null
+    })),
+    alternates: (journey.alternates || []).map(/** @param {any} alternate */ (alternate) => ({
+      id: alternate.id,
+      from: alternate.from,
+      condition: alternate.condition,
+      commands: [...(alternate.commands || [])],
+      expects: [...(alternate.expects || [])],
+      notes: alternate.notes || null
+    })),
     related: {
       capabilities: summarizeStatementsByIds(graph, capabilities),
+      entities: summarizeStatementsByIds(graph, entities),
+      rules: summarizeStatementsByIds(graph, rules),
       workflows: summarizeDocsByIds(graph, workflows),
-      projections: summarizeStatementsByIds(graph, projections)
+      projections: summarizeStatementsByIds(graph, projections),
+      widgets: summarizeStatementsByIds(graph, widgets)
     },
     verification: summarizeStatementsByIds(graph, verifications),
     verification_targets: recommendedVerificationTargets(graph, [...capabilities, ...workflows, ...projections, journeyId], {

package/src/generator/context/task-mode.js

@@ -325,7 +325,7 @@ function importAdoptMode(graph, options = {}) {
   return {
     type: "context_task_mode",
     version: 1,
-    mode: "import-adopt",
+    mode: "extract-adopt",
     summary: {
       focus: "Proposal review and adoption planning",
       preferred_start: "adoption-plan.agent.json",
@@ -450,7 +450,7 @@ function verificationMode(graph, options = {}) {
 export function generateContextTaskMode(graph, options = {}) {
   const mode = String(options.modeId || "").trim();
   if (!mode) {
-    throw new Error("context-task-mode requires --mode <modeling|maintained-app-edit|import-adopt|diff-review|verification>");
+    throw new Error("context-task-mode requires --mode <modeling|maintained-app-edit|extract-adopt|diff-review|verification>");
   }
 
   if (mode === "modeling") {
@@ -459,7 +459,7 @@ export function generateContextTaskMode(graph, options = {}) {
   if (mode === "maintained-app-edit") {
     return maintainedAppEditMode(graph, options);
   }
-  if (mode === "import-adopt") {
+  if (mode === "extract-adopt") {
     return importAdoptMode(graph, options);
   }
   if (mode === "diff-review") {

package/src/generator/registry/index.js

@@ -1,8 +1,11 @@
 // @ts-check
 
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
+import {
+  loadPackageManifest,
+  packageInstallCommand,
+  packageInstallHint,
+  resolvePackageManifestPath
+} from "../../package-adapters/index.js";
 import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../../ui/taxonomy.js";
 
 /**
@@ -208,20 +211,12 @@ export function getGeneratorManifest(generatorId) {
   return GENERATOR_BY_ID.get(generatorId) || null;
 }
 
-/**
- * @param {string|null|undefined} rootDir
- * @returns {string}
- */
-function packageResolutionBase(rootDir) {
-  return path.join(rootDir || process.cwd(), "package.json");
-}
-
 /**
  * @param {string|null|undefined} packageName
  * @returns {string|null}
  */
 export function packageGeneratorInstallCommand(packageName) {
-  return packageName ? `npm install -D ${packageName}` : null;
+  return packageInstallCommand(packageName);
 }
 
 /**
@@ -229,8 +224,7 @@ export function packageGeneratorInstallCommand(packageName) {
  * @returns {string|null}
  */
 export function packageGeneratorInstallHint(packageName) {
-  const command = packageGeneratorInstallCommand(packageName);
-  return command ? `Install it from the project root with: ${command}` : null;
+  return packageInstallHint(packageName);
 }
 
 /**
@@ -239,41 +233,7 @@ export function packageGeneratorInstallHint(packageName) {
  * @returns {{ manifestPath: string|null, packageRoot: string|null, error: string|null }}
  */
 export function resolvePackageGeneratorManifestPath(packageName, rootDir = process.cwd()) {
-  const requireFromRoot = createRequire(packageResolutionBase(rootDir));
-  try {
-    const manifestPath = requireFromRoot.resolve(`${packageName}/topogram-generator.json`);
-    return {
-      manifestPath,
-      packageRoot: path.dirname(manifestPath),
-      error: null
-    };
-  } catch (manifestError) {
-    try {
-      const packageJsonPath = requireFromRoot.resolve(`${packageName}/package.json`);
-      const packageRoot = path.dirname(packageJsonPath);
-      const manifestPath = path.join(packageRoot, "topogram-generator.json");
-      if (!fs.existsSync(manifestPath)) {
-        return {
-          manifestPath: null,
-          packageRoot,
-          error: `Generator package '${packageName}' is missing topogram-generator.json`
-        };
-      }
-      return {
-        manifestPath,
-        packageRoot,
-        error: null
-      };
-    } catch {
-      const detail = manifestError instanceof Error ? manifestError.message : String(manifestError);
-      const installHint = packageGeneratorInstallHint(packageName);
-      return {
-        manifestPath: null,
-        packageRoot: null,
-        error: `Generator package '${packageName}' could not be resolved from '${rootDir || process.cwd()}': ${detail}${installHint ? `. ${installHint}` : ""}`
-      };
-    }
-  }
+  return resolvePackageManifestPath(packageName, "topogram-generator.json", rootDir, "Generator package");
 }
 
 /**
@@ -282,32 +242,13 @@ export function resolvePackageGeneratorManifestPath(packageName, rootDir = proce
  * @returns {{ manifest: GeneratorManifest|null, errors: string[], manifestPath: string|null, packageRoot: string|null }}
  */
 export function loadPackageGeneratorManifest(packageName, rootDir = process.cwd()) {
-  const resolved = resolvePackageGeneratorManifestPath(packageName, rootDir);
-  if (!resolved.manifestPath) {
-    return {
-      manifest: null,
-      errors: [resolved.error || `Generator package '${packageName}' could not be resolved`],
-      manifestPath: null,
-      packageRoot: resolved.packageRoot
-    };
-  }
-  try {
-    const manifest = JSON.parse(fs.readFileSync(resolved.manifestPath, "utf8"));
-    const validation = validateGeneratorManifest(manifest);
-    return {
-      manifest: validation.ok ? manifest : null,
-      errors: validation.errors,
-      manifestPath: resolved.manifestPath,
-      packageRoot: resolved.packageRoot
-    };
-  } catch (error) {
-    return {
-      manifest: null,
-      errors: [`Generator package '${packageName}' manifest could not be read: ${error instanceof Error ? error.message : String(error)}`],
-      manifestPath: resolved.manifestPath,
-      packageRoot: resolved.packageRoot
-    };
-  }
+  return loadPackageManifest({
+    packageName,
+    rootDir,
+    manifestFile: "topogram-generator.json",
+    packageLabel: "Generator package",
+    validateManifest: validateGeneratorManifest
+  });
 }
 
 /**

package/src/generator-policy.js

@@ -4,6 +4,12 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { stableStringify } from "./format.js";
+import {
+  optionalStringArray,
+  optionalStringRecord,
+  packageAllowedByPolicy,
+  packageScopeFromName as sharedPackageScopeFromName
+} from "./package-adapters/index.js";
 
 export const GENERATOR_POLICY_FILE = "topogram.generator-policy.json";
 
@@ -66,47 +72,6 @@ function generatorPolicyDiagnostic(input) {
   };
 }
 
-/**
- * @param {unknown} value
- * @param {string} fieldName
- * @param {string} policyPath
- * @returns {string[]}
- */
-function optionalStringArray(value, fieldName, policyPath) {
-  if (value == null) {
-    return [];
-  }
-  if (!Array.isArray(value)) {
-    throw new Error(`${policyPath} ${fieldName} must be an array of strings.`);
-  }
-  return value.map((item) => {
-    if (typeof item !== "string" || item.length === 0) {
-      throw new Error(`${policyPath} ${fieldName} must contain only non-empty strings.`);
-    }
-    return item;
-  });
-}
-
-/**
- * @param {unknown} value
- * @param {string} policyPath
- * @returns {Record<string, string>}
- */
-function optionalStringRecord(value, policyPath) {
-  if (value == null) {
-    return {};
-  }
-  if (typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${policyPath} pinnedVersions must be an object of package-or-generator ids to versions.`);
-  }
-  return Object.fromEntries(Object.entries(value).map(([key, item]) => {
-    if (typeof item !== "string" || item.length === 0) {
-      throw new Error(`${policyPath} pinnedVersions['${key}'] must be a non-empty string.`);
-    }
-    return [key, item];
-  }));
-}
-
 /**
  * @returns {GeneratorPolicy}
  */
@@ -136,7 +101,7 @@ export function validateGeneratorPolicy(value, policyPath) {
       ? defaults.allowedPackageScopes
       : optionalStringArray(raw.allowedPackageScopes, "allowedPackageScopes", policyPath),
     allowedPackages: optionalStringArray(raw.allowedPackages, "allowedPackages", policyPath),
-    pinnedVersions: optionalStringRecord(raw.pinnedVersions, policyPath)
+    pinnedVersions: optionalStringRecord(raw.pinnedVersions, policyPath, "package-or-generator ids")
   };
 }
 
@@ -145,16 +110,7 @@ export function validateGeneratorPolicy(value, policyPath) {
  * @returns {string|null}
  */
 export function packageScopeFromName(packageName) {
-  return packageName.startsWith("@") ? packageName.split("/")[0] || null : null;
-}
-
-/**
- * @param {string} allowed
- * @param {string|null} scope
- * @returns {boolean}
- */
-function packageScopeMatches(allowed, scope) {
-  return Boolean(scope && (allowed === scope || allowed === `${scope}/*`));
+  return sharedPackageScopeFromName(packageName);
 }
 
 /**
@@ -163,11 +119,7 @@ function packageScopeMatches(allowed, scope) {
  * @returns {boolean}
  */
 export function generatorPackageAllowed(policy, packageName) {
-  if (policy.allowedPackages.includes(packageName)) {
-    return true;
-  }
-  const scope = packageScopeFromName(packageName);
-  return policy.allowedPackageScopes.some((allowed) => packageScopeMatches(allowed, scope));
+  return packageAllowedByPolicy(policy, packageName);
 }
 
 /**

package/src/import/core/registry.d.ts

@@ -1,4 +1,7 @@
 export const extractorRegistry: Record<string, any[]>;
 export const enricherRegistry: Record<string, any[]>;
+export const BUILTIN_EXTRACTOR_PACKS: any[];
 export function getExtractorsForTrack(...args: any[]): any[];
 export function getEnrichersForTrack(...args: any[]): any[];
+export function getBundledExtractorPack(...args: any[]): any;
+export function getBundledExtractorById(...args: any[]): any;

package/src/import/core/registry.js

@@ -57,14 +57,80 @@ import { railsControllerEnricher } from "../enrichers/rails-controllers.js";
 import { workflowTargetStateEnricher } from "../enrichers/workflow-target-state.js";
 import { docLinkingEnricher } from "../enrichers/doc-linking.js";
 
-export const extractorRegistry = {
-  db: [prismaExtractor, djangoModelsExtractor, efCoreExtractor, roomExtractor, swiftDataExtractor, dotnetModelsExtractor, flutterEntitiesExtractor, reactNativeEntitiesExtractor, railsSchemaExtractor, liquibaseExtractor, myBatisXmlExtractor, jpaExtractor, drizzleExtractor, sqlExtractor, snapshotExtractor],
-  api: [openApiExtractor, openApiCodeExtractor, graphQlSdlExtractor, graphQlCodeFirstExtractor, trpcExtractor, aspNetCoreExtractor, retrofitExtractor, swiftWebApiExtractor, flutterDioExtractor, reactNativeRepositoryExtractor, fastifyExtractor, expressExtractor, djangoRoutesExtractor, railsRoutesExtractor, micronautExtractor, jaxRsExtractor, springWebExtractor, nextRouteExtractor, genericRouteFallbackExtractor, nextServerActionExtractor, nextAuthExtractor],
-  ui: [nextAppRouterUiExtractor, nextPagesRouterUiExtractor, androidComposeUiExtractor, blazorUiExtractor, razorPagesUiExtractor, swiftUiExtractor, uiKitExtractor, mauiXamlUiExtractor, flutterScreensUiExtractor, reactNativeScreensExtractor, reactRouterUiExtractor, svelteKitUiExtractor, backendOnlyUiExtractor],
-  cli: [genericCliExtractor],
-  workflows: [genericWorkflowExtractor],
-  verification: [genericVerificationExtractor]
-};
+function extractorPack(id, tracks, extractors, candidateKinds, stack = {}, capabilities = {}) {
+  return {
+    manifest: {
+      id,
+      version: "1",
+      tracks,
+      source: "bundled",
+      extractors: extractors.map((extractor) => extractor.id),
+      stack,
+      capabilities,
+      candidateKinds,
+      evidenceTypes: ["runtime_source", "parser_config", "docs", "tests", "fixtures"]
+    },
+    extractors
+  };
+}
+
+export const BUILTIN_EXTRACTOR_PACKS = [
+  extractorPack(
+    "topogram/db-extractors",
+    ["db"],
+    [prismaExtractor, djangoModelsExtractor, efCoreExtractor, roomExtractor, swiftDataExtractor, dotnetModelsExtractor, flutterEntitiesExtractor, reactNativeEntitiesExtractor, railsSchemaExtractor, liquibaseExtractor, myBatisXmlExtractor, jpaExtractor, drizzleExtractor, sqlExtractor, snapshotExtractor],
+    ["entity", "enum", "relation", "index", "maintained_db_migration_seam"],
+    { domain: "database" },
+    { schema: true, migrations: true, maintainedSeams: true }
+  ),
+  extractorPack(
+    "topogram/api-extractors",
+    ["api"],
+    [openApiExtractor, openApiCodeExtractor, graphQlSdlExtractor, graphQlCodeFirstExtractor, trpcExtractor, aspNetCoreExtractor, retrofitExtractor, swiftWebApiExtractor, flutterDioExtractor, reactNativeRepositoryExtractor, fastifyExtractor, expressExtractor, djangoRoutesExtractor, railsRoutesExtractor, micronautExtractor, jaxRsExtractor, springWebExtractor, nextRouteExtractor, genericRouteFallbackExtractor, nextServerActionExtractor, nextAuthExtractor],
+    ["capability", "route", "stack"],
+    { domain: "api" },
+    { routes: true, openapi: true, graphql: true }
+  ),
+  extractorPack(
+    "topogram/ui-extractors",
+    ["ui"],
+    [nextAppRouterUiExtractor, nextPagesRouterUiExtractor, androidComposeUiExtractor, blazorUiExtractor, razorPagesUiExtractor, swiftUiExtractor, uiKitExtractor, mauiXamlUiExtractor, flutterScreensUiExtractor, reactNativeScreensExtractor, reactRouterUiExtractor, svelteKitUiExtractor, backendOnlyUiExtractor],
+    ["screen", "route", "action", "flow", "widget", "shape", "stack"],
+    { domain: "ui" },
+    { screens: true, widgets: true, flows: true }
+  ),
+  extractorPack(
+    "topogram/cli-extractors",
+    ["cli"],
+    [genericCliExtractor],
+    ["command", "capability", "cli_surface"],
+    { domain: "cli" },
+    { commands: true, options: true, effects: true }
+  ),
+  extractorPack(
+    "topogram/workflow-extractors",
+    ["workflows"],
+    [genericWorkflowExtractor],
+    ["workflow", "workflow_state", "workflow_transition"],
+    { domain: "workflow" },
+    { workflows: true }
+  ),
+  extractorPack(
+    "topogram/verification-extractors",
+    ["verification"],
+    [genericVerificationExtractor],
+    ["verification", "scenario", "framework", "script"],
+    { domain: "verification" },
+    { verifications: true }
+  )
+];
+
+export const extractorRegistry = Object.fromEntries(
+  ["db", "api", "ui", "cli", "workflows", "verification"].map((track) => [
+    track,
+    BUILTIN_EXTRACTOR_PACKS.flatMap((pack) => pack.extractors).filter((extractor) => extractor.track === track)
+  ])
+);
 
 export const enricherRegistry = {
   db: [railsModelEnricher],
@@ -82,3 +148,11 @@ export function getExtractorsForTrack(track) {
 export function getEnrichersForTrack(track) {
   return enricherRegistry[track] || [];
 }
+
+export function getBundledExtractorPack(id) {
+  return BUILTIN_EXTRACTOR_PACKS.find((pack) => pack.manifest.id === id) || null;
+}
+
+export function getBundledExtractorById(id) {
+  return BUILTIN_EXTRACTOR_PACKS.flatMap((pack) => pack.extractors).find((extractor) => extractor.id === id) || null;
+}

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

@@ -17,12 +17,12 @@ export function reportMarkdown(track, candidates) {
       `  - manual next: ${(seam.manual_next_steps || []).slice(0, 2).join(" ")}`
     ]);
     return ensureTrailingNewline(
-      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
+      `# DB Extract Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "api") {
     return ensureTrailingNewline(
-      `# API Import Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+      `# API Extract Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
     );
   }
   if (track === "ui") {
@@ -36,7 +36,7 @@ export function reportMarkdown(track, candidates) {
       `- \`${flow.id_hint}\` type \`${flow.flow_type}\` confidence ${flow.confidence || "unknown"} routes ${(flow.route_paths || []).map((/** @type {string} */ route) => `\`${route}\``).join(", ") || "_none_"} missing decisions ${(flow.missing_decisions || []).length}`
     );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
+      `# UI Extract Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram extract plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
   if (track === "cli") {
@@ -44,7 +44,7 @@ export function reportMarkdown(track, candidates) {
       `- \`${command.command_id || command.id_hint}\` usage \`${command.usage || "unknown"}\` effects ${(command.effects || []).map((/** @type {any} */ effect) => `\`${effect}\``).join(", ") || "_none_"}`
     );
     return ensureTrailingNewline(
-      `# CLI Import Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
+      `# CLI Extract Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "verification") {

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

@@ -6,6 +6,7 @@ import { parseImportTracks } from "./options.js";
 import { appReportMarkdown, reportMarkdown } from "./reports.js";
 import { runTrack } from "./tracks.js";
 import { draftUiProjectionFiles } from "./ui-drafts.js";
+import { packageExtractorsForContext } from "../../../extractor/packages.js";
 
 /**
  * @param {string} inputPath
@@ -64,6 +65,7 @@ export function runImportApp(inputPath, options = {}) {
     tracks,
     findings_count: Object.values(findings).reduce((total, entries) => total + entries.length, 0),
     extractor_detections: Object.fromEntries(Object.entries(resultsByTrack).map(([track, result]) => [track, result.extractor_detections])),
+    package_extractors: packageExtractorsForContext(context).provenance,
     candidates
   };
 

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

@@ -2,6 +2,7 @@
 
 import { getEnrichersForTrack, getExtractorsForTrack } from "../registry.js";
 import { normalizeCandidatesForTrack } from "./candidates.js";
+import { packageExtractorsForContext } from "../../../extractor/packages.js";
 
 /**
  * @param {any} context
@@ -10,7 +11,12 @@ import { normalizeCandidatesForTrack } from "./candidates.js";
  */
 function sortExtractors(context, extractors) {
   return extractors
-    .map((extractor) => ({ extractor, detection: extractor.detect(context) || { score: 0, reasons: [] } }))
+    .map((extractor) => {
+      const extractorContext = extractor.source === "package" && typeof extractor.packageContext === "function"
+        ? extractor.packageContext(context)
+        : context;
+      return { extractor, detection: extractor.detect(extractorContext) || { score: 0, reasons: [] } };
+    })
     .filter((entry) => entry.detection.score > 0)
     .sort((a, b) => b.detection.score - a.detection.score || a.extractor.id.localeCompare(b.extractor.id));
 }
@@ -20,7 +26,7 @@ function sortExtractors(context, extractors) {
  * @param {Array<{ extractor: any, detection: any }>} detections
  * @returns {Array<{ extractor: any, detection: any }>}
  */
-function selectDetectionsForTrack(track, detections) {
+function selectBundledDetectionsForTrack(track, detections) {
   if (track === "db") {
     const prisma = detections.find((entry) => entry.extractor.id === "db.prisma");
     if (prisma) return [prisma];
@@ -90,6 +96,20 @@ function selectDetectionsForTrack(track, detections) {
   return detections;
 }
 
+/**
+ * @param {string} track
+ * @param {Array<{ extractor: any, detection: any }>} detections
+ * @returns {Array<{ extractor: any, detection: any }>}
+ */
+function selectDetectionsForTrack(track, detections) {
+  const packageDetections = detections.filter((entry) => entry.extractor.source === "package");
+  const bundledDetections = selectBundledDetectionsForTrack(
+    track,
+    detections.filter((entry) => entry.extractor.source !== "package")
+  );
+  return [...bundledDetections, ...packageDetections];
+}
+
 /**
  * @param {string} track
  * @returns {any}
@@ -113,6 +133,35 @@ function initialCandidatesForTrack(track) {
   return { workflows: [], workflow_states: [], workflow_transitions: [] };
 }
 
+/**
+ * @param {any} extractor
+ * @param {any} result
+ * @returns {void}
+ */
+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.`);
+    }
+  }
+}
+
 /**
  * @param {any} context
  * @param {string} track
@@ -121,9 +170,22 @@ function initialCandidatesForTrack(track) {
 export function runTrack(context, track) {
   const findings = [];
   const rawCandidates = initialCandidatesForTrack(track);
+  const packageState = packageExtractorsForContext(context);
+  const packageErrors = packageState.diagnostics.filter((diagnostic) => diagnostic.severity !== "warning");
+  if (packageErrors.length > 0) {
+    throw new Error(packageErrors.map((diagnostic) => diagnostic.message || String(diagnostic)).join("\n"));
+  }
+  const extractors = [
+    ...getExtractorsForTrack(track),
+    ...packageState.extractors.filter((extractor) => extractor.track === track)
+  ];
 
-  for (const { extractor, detection } of selectDetectionsForTrack(track, sortExtractors(context, getExtractorsForTrack(track)))) {
-    const result = extractor.extract(context) || { findings: [], candidates: {} };
+  for (const { extractor, detection } of selectDetectionsForTrack(track, sortExtractors(context, extractors))) {
+    const extractorContext = extractor.source === "package" && typeof extractor.packageContext === "function"
+      ? extractor.packageContext(context)
+      : context;
+    const result = extractor.extract(extractorContext) || { findings: [], candidates: {} };
+    assertExtractorResultShape(extractor, result);
     findings.push({
       extractor: extractor.id,
       detection,