@topogram/cli 0.3.40 → 0.3.42

package/package.json

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

package/src/cli.js

@@ -32,6 +32,7 @@ import {
   getTemplateTrustStatus,
   implementationRequiresTrust,
   TEMPLATE_TRUST_FILE,
+  templateTrustRecoveryGuidance,
   validateProjectImplementationTrust,
   writeTemplateTrustRecord
 } from "./template-trust.js";
@@ -43,6 +44,17 @@ import {
   loadPackageGeneratorManifest,
   packageGeneratorInstallCommand
 } from "./generator/registry.js";
+import {
+  defaultGeneratorPolicy,
+  GENERATOR_POLICY_FILE,
+  generatorPackageAllowed,
+  generatorPolicyDiagnosticsForBindings,
+  loadGeneratorPolicy,
+  packageBackedGeneratorBindings,
+  packageScopeFromName,
+  parseGeneratorPolicyPin,
+  writeGeneratorPolicy
+} from "./generator-policy.js";
 import {
   buildAuthHintsQueryPayload,
   buildAuthReviewPacketPayload,
@@ -206,6 +218,10 @@ function printUsage(options = {}) {
   console.log("   or: topogram generator list [--json]");
   console.log("   or: topogram generator show <id-or-package> [--json]");
   console.log("   or: topogram generator check <path-or-package> [--json]");
+  console.log("   or: topogram generator policy init [path] [--json]");
+  console.log("   or: topogram generator policy check [path] [--json]");
+  console.log("   or: topogram generator policy explain [path] [--json]");
+  console.log("   or: topogram generator policy pin [package@version] [path] [--json]");
   console.log("   or: topogram new <path> [--template hello-web|todo|./local-template|@scope/template]");
   console.log("   or: topogram new --list-templates [--json] [--catalog <path-or-source>]");
   console.log("");
@@ -227,6 +243,7 @@ function printUsage(options = {}) {
   console.log("  topogram generator list");
   console.log("  topogram generator show @topogram/generator-react-web");
   console.log("  topogram generator check ./generator-package");
+  console.log("  topogram generator policy check");
   console.log("  topogram generate");
   console.log("  topogram import ./existing-app --out ./imported-topogram");
   console.log("  topogram import diff ./imported-topogram");
@@ -568,6 +585,10 @@ function printGeneratorHelp() {
   console.log("Usage: topogram generator list [--json]");
   console.log("   or: topogram generator show <id-or-package> [--json]");
   console.log("   or: topogram generator check <path-or-package> [--json]");
+  console.log("   or: topogram generator policy init [path] [--json]");
+  console.log("   or: topogram generator policy check [path] [--json]");
+  console.log("   or: topogram generator policy explain [path] [--json]");
+  console.log("   or: topogram generator policy pin [package@version] [path] [--json]");
   console.log("");
   console.log("Inspects generator manifests and checks generator pack conformance.");
   console.log("");
@@ -576,6 +597,7 @@ function printGeneratorHelp() {
   console.log("  - show accepts an installed package name or a bundled fallback generator id.");
   console.log("  - check validates a local generator package path or an already installed package.");
   console.log("  - Topogram does not install generator packages during show or check.");
+  console.log(`  - package-backed project generators are governed by ${GENERATOR_POLICY_FILE}; bundled topogram/* generators are allowed.`);
   console.log("");
   console.log("Examples:");
   console.log("  topogram generator list");
@@ -584,6 +606,9 @@ function printGeneratorHelp() {
   console.log("  topogram generator show @scope/topogram-generator-web --json");
   console.log("  topogram generator check ./generator-package");
   console.log("  topogram generator check @scope/topogram-generator-web --json");
+  console.log("  topogram generator policy init");
+  console.log("  topogram generator policy check --json");
+  console.log("  topogram generator policy pin @topogram/generator-react-web@1");
 }
 
 function printTemplateHelp() {
@@ -788,7 +813,7 @@ function printImportHelp() {
 function printCheckHelp() {
   console.log("Usage: topogram check [path] [--json]");
   console.log("");
-  console.log("Validates Topogram files, project configuration, topology, generator compatibility, output ownership, and template policy.");
+  console.log("Validates Topogram files, project configuration, topology, generator compatibility, generator policy, output ownership, and template policy.");
   console.log("");
   console.log("Defaults: path is ./topogram.");
   console.log("");
@@ -1523,6 +1548,341 @@ function printGeneratorShow(payload) {
   console.log(stableStringify(payload.exampleTopologyBinding));
 }
 
+/**
+ * @param {string} name
+ * @param {boolean} ok
+ * @param {string} actual
+ * @param {string} expected
+ * @param {string} message
+ * @param {string|null} fix
+ * @returns {{ name: string, ok: boolean, actual: string, expected: string, message: string, fix: string|null }}
+ */
+function generatorPolicyRule(name, ok, actual, expected, message, fix = null) {
+  return { name, ok, actual, expected, message, fix };
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function generatorPolicyRuleLabel(name) {
+  return ({
+    "policy-file": "Policy file",
+    "allowed-package": "Allowed package",
+    "pinned-version": "Pinned version"
+  })[name] || name;
+}
+
+/**
+ * @param {import("./generator-policy.js").GeneratorPolicyInfo} policyInfo
+ * @returns {import("./generator-policy.js").GeneratorPolicy}
+ */
+function effectiveGeneratorPolicy(policyInfo) {
+  return policyInfo.policy || {
+    version: "0.1",
+    allowedPackageScopes: ["@topogram"],
+    allowedPackages: [],
+    pinnedVersions: {}
+  };
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {{ ok: boolean, path: string, exists: boolean, policy: any, defaulted: boolean, bindings: ReturnType<typeof packageBackedGeneratorBindings>, diagnostics: any[], errors: string[] }}
+ */
+function buildGeneratorPolicyCheckPayload(projectPath) {
+  const projectConfigInfo = loadProjectConfig(projectPath);
+  if (!projectConfigInfo) {
+    const diagnostic = {
+      code: "generator_policy_project_missing",
+      severity: "error",
+      message: "Cannot check generator policy without topogram.project.json.",
+      path: path.resolve(projectPath),
+      suggestedFix: "Run this command in a Topogram project.",
+      step: "generator-policy"
+    };
+    return {
+      ok: false,
+      path: path.join(path.resolve(projectPath), GENERATOR_POLICY_FILE),
+      exists: false,
+      policy: null,
+      defaulted: false,
+      bindings: [],
+      diagnostics: [diagnostic],
+      errors: [diagnostic.message]
+    };
+  }
+  const policyInfo = loadGeneratorPolicy(projectConfigInfo.configDir);
+  const bindings = packageBackedGeneratorBindings(projectConfigInfo.config);
+  const diagnostics = [];
+  if (!policyInfo.exists) {
+    diagnostics.push({
+      code: "generator_policy_missing",
+      severity: "warning",
+      message: `No ${GENERATOR_POLICY_FILE} found. Default generator policy allows @topogram/* package-backed generators and blocks other package scopes.`,
+      path: policyInfo.path,
+      suggestedFix: "Run `topogram generator policy init` to write an explicit project generator policy after review.",
+      step: "generator-policy"
+    });
+  }
+  diagnostics.push(...generatorPolicyDiagnosticsForBindings(policyInfo, bindings, "generator-policy"));
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message);
+  return {
+    ok: errors.length === 0,
+    path: policyInfo.path,
+    exists: policyInfo.exists,
+    policy: policyInfo.policy || effectiveGeneratorPolicy(policyInfo),
+    defaulted: !policyInfo.exists,
+    bindings,
+    diagnostics,
+    errors
+  };
+}
+
+/**
+ * @param {string} projectPath
+ * @returns {ReturnType<typeof buildGeneratorPolicyCheckPayload> & { rules: Array<{ name: string, ok: boolean, actual: string, expected: string, message: string, fix: string|null }> }}
+ */
+function buildGeneratorPolicyExplainPayload(projectPath) {
+  const check = buildGeneratorPolicyCheckPayload(projectPath);
+  const policy = check.policy || effectiveGeneratorPolicy({ path: check.path, exists: false, policy: null, diagnostics: [] });
+  const rules = [];
+  rules.push(generatorPolicyRule(
+    "policy-file",
+    check.exists,
+    check.exists ? "present" : "missing",
+    "present",
+    check.exists
+      ? "Project has a generator policy file."
+      : "Project is using the default generator policy.",
+    check.exists ? null : "Run `topogram generator policy init` after review."
+  ));
+  for (const binding of check.bindings) {
+    const scope = packageScopeFromName(binding.packageName);
+    rules.push(generatorPolicyRule(
+      "allowed-package",
+      generatorPackageAllowed(policy, binding.packageName),
+      `${binding.packageName}${scope ? ` (${scope})` : ""}`,
+      [
+        `scopes=${policy.allowedPackageScopes.join(", ") || "(none)"}`,
+        `packages=${policy.allowedPackages.join(", ") || "(none)"}`
+      ].join("; "),
+      `Component '${binding.componentId}' package-backed generator must be from an allowed package or scope.`,
+      `Run \`topogram generator policy pin ${binding.packageName}@${binding.version}\` after reviewing the generator package.`
+    ));
+    const pinnedVersion = policy.pinnedVersions[binding.packageName] || policy.pinnedVersions[binding.generatorId] || null;
+    rules.push(generatorPolicyRule(
+      "pinned-version",
+      !pinnedVersion || pinnedVersion === binding.version,
+      binding.version,
+      pinnedVersion || "(unpinned)",
+      `Component '${binding.componentId}' generator version must match its policy pin when one exists.`,
+      `Run \`topogram generator policy pin ${binding.packageName}@${binding.version}\` after review.`
+    ));
+  }
+  return {
+    ...check,
+    rules
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildGeneratorPolicyCheckPayload>} payload
+ * @returns {void}
+ */
+function printGeneratorPolicyCheckPayload(payload) {
+  console.log(payload.ok ? "Generator policy check passed" : "Generator policy check failed");
+  console.log(`Policy: ${payload.path}`);
+  console.log(`Exists: ${payload.exists ? "yes" : "no"}`);
+  console.log(`Defaulted: ${payload.defaulted ? "yes" : "no"}`);
+  console.log(`Package-backed generators: ${payload.bindings.length}`);
+  for (const binding of payload.bindings) {
+    console.log(`- ${binding.componentId}: ${binding.generatorId}@${binding.version} via ${binding.packageName}`);
+  }
+  for (const diagnostic of payload.diagnostics) {
+    console.log(`[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`);
+    if (diagnostic.path) {
+      console.log(`  path: ${diagnostic.path}`);
+    }
+    if (diagnostic.suggestedFix) {
+      console.log(`  fix: ${diagnostic.suggestedFix}`);
+    }
+  }
+}
+
+/**
+ * @param {ReturnType<typeof buildGeneratorPolicyExplainPayload>} payload
+ * @returns {void}
+ */
+function printGeneratorPolicyExplainPayload(payload) {
+  console.log(payload.ok ? "Generator policy: allowed" : "Generator policy: denied");
+  console.log(payload.ok
+    ? "Decision: package-backed generators are allowed by this project's generator policy."
+    : "Decision: one or more package-backed generators are blocked by this project's generator policy.");
+  console.log(`Policy file: ${payload.path}`);
+  console.log(`Policy file exists: ${payload.exists ? "yes" : "no"}`);
+  console.log(`Default policy active: ${payload.defaulted ? "yes" : "no"}`);
+  if (payload.bindings.length > 0) {
+    console.log("");
+    console.log("Package-backed generators:");
+    for (const binding of payload.bindings) {
+      console.log(`- ${binding.componentId}: ${binding.generatorId}@${binding.version} via ${binding.packageName}`);
+    }
+  }
+  if (payload.rules.length > 0) {
+    console.log("");
+    console.log("Policy checks:");
+  }
+  for (const rule of payload.rules) {
+    console.log(`${rule.ok ? "PASS" : "FAIL"} ${generatorPolicyRuleLabel(rule.name)}: ${rule.message}`);
+    console.log(`  actual: ${rule.actual}`);
+    console.log(`  expected: ${rule.expected}`);
+    if (!rule.ok && rule.fix) {
+      console.log(`  fix: ${rule.fix}`);
+    }
+  }
+  for (const diagnostic of payload.diagnostics) {
+    const label = diagnostic.severity === "warning" ? "Warning" : "Error";
+    console.log(`${label}: ${diagnostic.code}: ${diagnostic.message}`);
+    if (diagnostic.suggestedFix) {
+      console.log(`  fix: ${diagnostic.suggestedFix}`);
+    }
+  }
+}
+
+/**
+ * @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[] }}
+ */
+function buildGeneratorPolicyPinPayload(projectPath, spec) {
+  const projectConfigInfo = loadProjectConfig(projectPath);
+  if (!projectConfigInfo) {
+    const diagnostic = {
+      code: "generator_policy_project_missing",
+      severity: "error",
+      message: "Cannot pin generator policy without topogram.project.json.",
+      path: path.resolve(projectPath),
+      suggestedFix: "Run this command in a Topogram project.",
+      step: "generator-policy"
+    };
+    return {
+      ok: false,
+      path: path.join(path.resolve(projectPath), GENERATOR_POLICY_FILE),
+      policy: null,
+      pinned: [],
+      diagnostics: [diagnostic],
+      errors: [diagnostic.message]
+    };
+  }
+  const policyInfo = loadGeneratorPolicy(projectConfigInfo.configDir);
+  if (policyInfo.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    const errors = policyInfo.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message);
+    return {
+      ok: false,
+      path: policyInfo.path,
+      policy: policyInfo.policy,
+      pinned: [],
+      diagnostics: policyInfo.diagnostics,
+      errors
+    };
+  }
+  let pins = [];
+  try {
+    pins = spec
+      ? [parseGeneratorPolicyPin(spec)]
+      : packageBackedGeneratorBindings(projectConfigInfo.config).map((binding) => ({
+          packageName: binding.packageName,
+          version: binding.version
+        }));
+  } catch (error) {
+    const diagnostic = {
+      code: "generator_policy_pin_invalid",
+      severity: "error",
+      message: error instanceof Error ? error.message : String(error),
+      path: policyInfo.path,
+      suggestedFix: "Pass a pin such as @topogram/generator-react-web@1.",
+      step: "generator-policy"
+    };
+    return {
+      ok: false,
+      path: policyInfo.path,
+      policy: policyInfo.policy,
+      pinned: [],
+      diagnostics: [diagnostic],
+      errors: [diagnostic.message]
+    };
+  }
+  if (pins.length === 0) {
+    const diagnostic = {
+      code: "generator_policy_pin_no_generators",
+      severity: "error",
+      message: "No package-backed topology generator bindings are available to pin.",
+      path: projectConfigInfo.configPath,
+      suggestedFix: "Pass an explicit pin such as @topogram/generator-react-web@1, or use bundled generators.",
+      step: "generator-policy"
+    };
+    return {
+      ok: false,
+      path: policyInfo.path,
+      policy: policyInfo.policy,
+      pinned: [],
+      diagnostics: [diagnostic],
+      errors: [diagnostic.message]
+    };
+  }
+  const policy = policyInfo.policy || defaultGeneratorPolicy();
+  const allowedPackages = [...policy.allowedPackages];
+  const allowedPackageScopes = [...policy.allowedPackageScopes];
+  const pinnedVersions = { ...policy.pinnedVersions };
+  for (const pin of pins) {
+    if (!allowedPackages.includes(pin.packageName)) {
+      allowedPackages.push(pin.packageName);
+    }
+    const scope = packageScopeFromName(pin.packageName);
+    if (scope && !allowedPackageScopes.includes(scope)) {
+      allowedPackageScopes.push(scope);
+    }
+    pinnedVersions[pin.packageName] = pin.version;
+  }
+  const nextPolicy = {
+    ...policy,
+    allowedPackageScopes,
+    allowedPackages,
+    pinnedVersions
+  };
+  writeGeneratorPolicy(projectConfigInfo.configDir, nextPolicy);
+  return {
+    ok: true,
+    path: path.join(projectConfigInfo.configDir, GENERATOR_POLICY_FILE),
+    policy: nextPolicy,
+    pinned: pins,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+/**
+ * @param {{ ok: boolean, path: string, pinned: Array<{ packageName: string, version: string }>, diagnostics: any[] }} payload
+ * @returns {void}
+ */
+function printGeneratorPolicyPinPayload(payload) {
+  console.log(payload.ok ? "Generator policy pin updated" : "Generator 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}`);
+    if (diagnostic.path) {
+      console.log(`  path: ${diagnostic.path}`);
+    }
+    if (diagnostic.suggestedFix) {
+      console.log(`  fix: ${diagnostic.suggestedFix}`);
+    }
+  }
+}
+
 function combineProjectValidationResults(...results) {
   const errors = [];
   for (const result of results) {
@@ -3339,6 +3699,7 @@ function printNewProjectResult(result, cwd) {
   }
   console.log(`Executable implementation: ${template.includesExecutableImplementation ? "yes" : "no"}`);
   console.log("Policy: topogram.template-policy.json");
+  console.log(`Generator policy: ${GENERATOR_POLICY_FILE}`);
   console.log("Template files: .topogram-template-files.json");
   if (template.includesExecutableImplementation) {
     console.log("Trust: .topogram-template-trust.json");
@@ -3354,6 +3715,7 @@ function printNewProjectResult(result, cwd) {
   console.log("  npm run source:status");
   console.log("  npm run template:explain");
   console.log("  npm run check");
+  console.log("  npm run generator:policy:check");
   if (template.includesExecutableImplementation) {
     console.log("  npm run template:policy:explain");
     console.log("  npm run trust:status");
@@ -5951,6 +6313,15 @@ function diagnosticForTemplateCreateFailure(message, templateSpec, step) {
       step
     });
   }
+  if (message.includes("unsupported symlink")) {
+    return templateCheckDiagnostic({
+      code: "template_symlink_unsupported",
+      message,
+      path: path.isAbsolute(templateSpec) ? templateSpec : null,
+      suggestedFix: "Replace template symlinks with real files or directories, then rerun `topogram new` or `topogram template check`.",
+      step
+    });
+  }
   return templateCheckDiagnostic({
     code: "template_create_failed",
     message,
@@ -5968,13 +6339,15 @@ function diagnosticForTemplateCreateFailure(message, templateSpec, step) {
  */
 function diagnosticForStarterCheckFailure(error, step, configPath) {
   const locFile = typeof error?.loc?.file === "string" ? error.loc.file : null;
-  const isTrust = error.message.includes(TEMPLATE_TRUST_FILE);
+  const isTrust = error.message.includes(TEMPLATE_TRUST_FILE) ||
+    error.message.includes("unsupported symlink") ||
+    error.message.includes("must be under implementation/");
   return templateCheckDiagnostic({
     code: isTrust ? "template_trust_invalid" : "starter_check_failed",
     message: error.message,
     path: locFile || configPath,
     suggestedFix: isTrust
-      ? "Review implementation/ and run topogram trust template in the generated starter."
+      ? templateTrustRecoveryGuidance(error.message)
       : "Fix the generated Topogram source or topogram.project.json so topogram check passes.",
     step
   });
@@ -6176,7 +6549,7 @@ function buildTemplateCheckPayload(templateSpec) {
       code: "template_trust_invalid",
       message: issue,
       path: trustStatus.trustPath,
-      suggestedFix: "Review implementation/ and run topogram trust template in the generated starter.",
+      suggestedFix: templateTrustRecoveryGuidance(issue),
       step: "executable-implementation-trust"
     }));
     steps.push(templateCheckStep("executable-implementation-trust", trustStatus.ok, {
@@ -6844,6 +7217,14 @@ if (args[0] === "version" || args[0] === "--version") {
   commandArgs = { generatorShow: true, inputPath: args[2] };
 } else if (args[0] === "generator" && args[1] === "check") {
   commandArgs = { generatorCheck: true, inputPath: args[2] };
+} else if (args[0] === "generator" && args[1] === "policy" && args[2] === "init") {
+  commandArgs = { generatorPolicyInit: true, inputPath: commandPath(3) };
+} else if (args[0] === "generator" && args[1] === "policy" && args[2] === "check") {
+  commandArgs = { generatorPolicyCheck: true, inputPath: commandPath(3) };
+} else if (args[0] === "generator" && args[1] === "policy" && args[2] === "explain") {
+  commandArgs = { generatorPolicyExplain: true, inputPath: commandPath(3) };
+} else if (args[0] === "generator" && args[1] === "policy" && args[2] === "pin") {
+  commandArgs = { generatorPolicyPin: true, generatorPolicyPinSpec: args[3] && !args[3].startsWith("-") ? args[3] : null, inputPath: commandPath(4) };
 } else if (args[0] === "generator") {
   printGeneratorHelp();
   process.exit(args[1] ? 1 : 0);
@@ -7040,6 +7421,10 @@ const shouldComponentBehavior = Boolean(commandArgs?.componentBehavior);
 const shouldGeneratorList = Boolean(commandArgs?.generatorList);
 const shouldGeneratorShow = Boolean(commandArgs?.generatorShow);
 const shouldGeneratorCheck = Boolean(commandArgs?.generatorCheck);
+const shouldGeneratorPolicyInit = Boolean(commandArgs?.generatorPolicyInit);
+const shouldGeneratorPolicyCheck = Boolean(commandArgs?.generatorPolicyCheck);
+const shouldGeneratorPolicyExplain = Boolean(commandArgs?.generatorPolicyExplain);
+const shouldGeneratorPolicyPin = Boolean(commandArgs?.generatorPolicyPin);
 const shouldTrustTemplate = Boolean(commandArgs?.trustTemplate);
 const shouldTrustStatus = Boolean(commandArgs?.trustStatus);
 const shouldTrustDiff = Boolean(commandArgs?.trustDiff);
@@ -7173,7 +7558,7 @@ const outIndex = args.indexOf("--out");
 const outPath = outIndex >= 0 ? args[outIndex + 1] : null;
 const effectiveOutDir = outDir || outPath || commandArgs?.defaultOutDir || null;
 
-if ((shouldCheck || shouldComponentCheck || shouldComponentBehavior || shouldGeneratorCheck || shouldValidate || shouldTrustTemplate || shouldTrustStatus || shouldTrustDiff || shouldSourceStatus || shouldTemplateExplain || shouldTemplateStatus || shouldTemplateDetach || shouldTemplatePolicyInit || shouldTemplatePolicyCheck || shouldTemplatePolicyExplain || shouldTemplatePolicyPin || shouldTemplateCheck || shouldTemplateUpdate || generateTarget === "app-bundle") && !inputPath) {
+if ((shouldCheck || shouldComponentCheck || shouldComponentBehavior || shouldGeneratorCheck || shouldGeneratorPolicyInit || shouldGeneratorPolicyCheck || shouldGeneratorPolicyExplain || shouldGeneratorPolicyPin || shouldValidate || shouldTrustTemplate || shouldTrustStatus || shouldTrustDiff || shouldSourceStatus || shouldTemplateExplain || shouldTemplateStatus || shouldTemplateDetach || shouldTemplatePolicyInit || shouldTemplatePolicyCheck || shouldTemplatePolicyExplain || shouldTemplatePolicyPin || shouldTemplateCheck || shouldTemplateUpdate || generateTarget === "app-bundle") && !inputPath) {
   console.error("Missing required <path>.");
   printUsage();
   process.exit(1);
@@ -7227,7 +7612,7 @@ if (shouldQueryShow && !commandArgs?.queryShowName) {
   process.exit(1);
 }
 
-if ((shouldCheck || shouldComponentCheck || shouldComponentBehavior || shouldValidate || shouldTrustTemplate || shouldTrustStatus || shouldTrustDiff || shouldTemplateExplain || shouldTemplateStatus || shouldTemplatePolicyInit || shouldTemplatePolicyCheck || shouldTemplatePolicyExplain || shouldTemplatePolicyPin || shouldTemplateUpdate || generateTarget === "app-bundle") && inputPath) {
+if ((shouldCheck || shouldComponentCheck || shouldComponentBehavior || shouldValidate || shouldGeneratorPolicyInit || shouldGeneratorPolicyCheck || shouldGeneratorPolicyExplain || shouldGeneratorPolicyPin || shouldTrustTemplate || shouldTrustStatus || shouldTrustDiff || shouldTemplateExplain || shouldTemplateStatus || shouldTemplatePolicyInit || shouldTemplatePolicyCheck || shouldTemplatePolicyExplain || shouldTemplatePolicyPin || shouldTemplateUpdate || generateTarget === "app-bundle") && inputPath) {
   inputPath = normalizeTopogramPath(inputPath);
 }
 
@@ -7354,6 +7739,59 @@ try {
     process.exit(payload.ok ? 0 : 1);
   }
 
+  if (shouldGeneratorPolicyInit) {
+    const projectConfigInfo = loadProjectConfig(inputPath);
+    if (!projectConfigInfo) {
+      throw new Error("Cannot initialize generator policy without topogram.project.json.");
+    }
+    const policy = writeGeneratorPolicy(projectConfigInfo.configDir, defaultGeneratorPolicy());
+    const payload = {
+      ok: true,
+      path: path.join(projectConfigInfo.configDir, GENERATOR_POLICY_FILE),
+      policy,
+      diagnostics: [],
+      errors: []
+    };
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      console.log(`Wrote generator policy: ${payload.path}`);
+      console.log(`Allowed package scopes: ${policy.allowedPackageScopes.join(", ") || "(none)"}`);
+      console.log(`Allowed packages: ${policy.allowedPackages.join(", ") || "(none)"}`);
+    }
+    process.exit(0);
+  }
+
+  if (shouldGeneratorPolicyCheck) {
+    const payload = buildGeneratorPolicyCheckPayload(inputPath);
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printGeneratorPolicyCheckPayload(payload);
+    }
+    process.exit(payload.ok ? 0 : 1);
+  }
+
+  if (shouldGeneratorPolicyExplain) {
+    const payload = buildGeneratorPolicyExplainPayload(inputPath);
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printGeneratorPolicyExplainPayload(payload);
+    }
+    process.exit(payload.ok ? 0 : 1);
+  }
+
+  if (shouldGeneratorPolicyPin) {
+    const payload = buildGeneratorPolicyPinPayload(inputPath, commandArgs?.generatorPolicyPinSpec);
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printGeneratorPolicyPinPayload(payload);
+    }
+    process.exit(payload.ok ? 0 : 1);
+  }
+
   if (shouldCatalogList) {
     const payload = buildCatalogListPayload(catalogSource || inputPath || null);
     if (emitJson) {
@@ -7853,7 +8291,10 @@ try {
         console.log(`Removed: ${filePath}`);
       }
       if (!status.ok) {
-        console.log("Run `topogram trust diff` to review implementation changes, then `topogram trust template` to trust the current files.");
+        const guidance = templateTrustRecoveryGuidance(status.issues);
+        if (guidance) {
+          console.log(guidance);
+        }
       }
     }
     process.exit(status.ok ? 0 : 1);
@@ -7882,6 +8323,12 @@ try {
       for (const issue of diff.status.issues) {
         console.log(`Issue: ${issue}`);
       }
+      if (!diff.ok) {
+        const guidance = templateTrustRecoveryGuidance(diff.status.issues);
+        if (guidance) {
+          console.log(guidance);
+        }
+      }
     } else {
       console.log(diff.ok ? "Template trust diff: no implementation changes." : "Template trust diff: review required");
       for (const file of diff.files) {
@@ -7906,7 +8353,10 @@ try {
       }
       if (!diff.ok) {
         console.log("");
-        console.log("After review, run `topogram trust template` to trust the current files.");
+        const guidance = templateTrustRecoveryGuidance(diff.status.issues);
+        if (guidance) {
+          console.log(guidance);
+        }
       }
     }
     process.exit(diff.ok ? 0 : 1);

package/src/generator-policy.d.ts

@@ -0,0 +1,12 @@
+export const GENERATOR_POLICY_FILE: string;
+export function defaultGeneratorPolicy(): any;
+export function validateGeneratorPolicy(value: unknown, policyPath: string): any;
+export function packageScopeFromName(packageName: string): string | null;
+export function generatorPackageAllowed(policy: any, packageName: string): boolean;
+export function packageBackedGeneratorBindings(projectConfig: any): any[];
+export function loadGeneratorPolicy(projectRoot: string): any;
+export function writeGeneratorPolicy(projectRoot: string, policy: any): any;
+export function generatorPolicyDiagnosticsForBindings(policyInfo: any, bindings: any[], step?: string): any[];
+export function generatorPolicyDiagnosticsForProject(projectConfig: any, projectRoot: string, step?: string): any[];
+export function validateProjectGeneratorPolicy(projectConfig: any, options?: { configDir?: string | null; rootDir?: string | null }): { ok: boolean; errors: Array<{ message: string; loc: null }> };
+export function parseGeneratorPolicyPin(spec: string): { packageName: string; version: string };

package/src/generator-policy.js

@@ -0,0 +1,344 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "./format.js";
+
+export const GENERATOR_POLICY_FILE = "topogram.generator-policy.json";
+
+/**
+ * @typedef {Object} GeneratorPolicy
+ * @property {string} version
+ * @property {string[]} allowedPackageScopes
+ * @property {string[]} allowedPackages
+ * @property {Record<string, string>} pinnedVersions
+ */
+
+/**
+ * @typedef {Object} GeneratorPolicyInfo
+ * @property {string} path
+ * @property {GeneratorPolicy|null} policy
+ * @property {boolean} exists
+ * @property {GeneratorPolicyDiagnostic[]} diagnostics
+ */
+
+/**
+ * @typedef {Object} GeneratorPolicyDiagnostic
+ * @property {string} code
+ * @property {"error"|"warning"} severity
+ * @property {string} message
+ * @property {string|null} path
+ * @property {string|null} suggestedFix
+ * @property {string|null} step
+ * @property {string|null} [componentId]
+ * @property {string|null} [generatorId]
+ * @property {string|null} [packageName]
+ * @property {string|null} [version]
+ */
+
+/**
+ * @typedef {Object} PackageGeneratorBinding
+ * @property {string} componentId
+ * @property {string} componentType
+ * @property {string} projection
+ * @property {string} generatorId
+ * @property {string} version
+ * @property {string} packageName
+ */
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {GeneratorPolicyDiagnostic}
+ */
+function generatorPolicyDiagnostic(input) {
+  return {
+    code: String(input.code || "generator_policy_failed"),
+    severity: input.severity === "warning" ? "warning" : "error",
+    message: String(input.message || "Generator policy check failed."),
+    path: typeof input.path === "string" ? input.path : null,
+    suggestedFix: typeof input.suggestedFix === "string" ? input.suggestedFix : null,
+    step: typeof input.step === "string" ? input.step : null,
+    componentId: typeof input.componentId === "string" ? input.componentId : null,
+    generatorId: typeof input.generatorId === "string" ? input.generatorId : null,
+    packageName: typeof input.packageName === "string" ? input.packageName : null,
+    version: typeof input.version === "string" ? input.version : null
+  };
+}
+
+/**
+ * @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}
+ */
+export function defaultGeneratorPolicy() {
+  return {
+    version: "0.1",
+    allowedPackageScopes: ["@topogram"],
+    allowedPackages: [],
+    pinnedVersions: {}
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} policyPath
+ * @returns {GeneratorPolicy}
+ */
+export function validateGeneratorPolicy(value, policyPath) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${GENERATOR_POLICY_FILE} must contain a JSON object.`);
+  }
+  const raw = /** @type {Record<string, unknown>} */ (value);
+  const defaults = defaultGeneratorPolicy();
+  return {
+    version: typeof raw.version === "string" && raw.version ? raw.version : defaults.version,
+    allowedPackageScopes: raw.allowedPackageScopes == null
+      ? defaults.allowedPackageScopes
+      : optionalStringArray(raw.allowedPackageScopes, "allowedPackageScopes", policyPath),
+    allowedPackages: optionalStringArray(raw.allowedPackages, "allowedPackages", policyPath),
+    pinnedVersions: optionalStringRecord(raw.pinnedVersions, policyPath)
+  };
+}
+
+/**
+ * @param {string} packageName
+ * @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}/*`));
+}
+
+/**
+ * @param {GeneratorPolicy} policy
+ * @param {string} packageName
+ * @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));
+}
+
+/**
+ * @param {Record<string, any>} projectConfig
+ * @returns {PackageGeneratorBinding[]}
+ */
+export function packageBackedGeneratorBindings(projectConfig) {
+  const components = Array.isArray(projectConfig?.topology?.components)
+    ? projectConfig.topology.components
+    : [];
+  return components
+    .filter((component) => typeof component?.generator?.package === "string" && component.generator.package.length > 0)
+    .map((component) => ({
+      componentId: String(component.id || "unknown"),
+      componentType: String(component.type || "unknown"),
+      projection: String(component.projection || "unknown"),
+      generatorId: String(component.generator.id || "unknown"),
+      version: String(component.generator.version || "unknown"),
+      packageName: String(component.generator.package)
+    }));
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {GeneratorPolicyInfo}
+ */
+export function loadGeneratorPolicy(projectRoot) {
+  const policyPath = path.join(projectRoot, GENERATOR_POLICY_FILE);
+  if (!fs.existsSync(policyPath)) {
+    return {
+      path: policyPath,
+      policy: null,
+      exists: false,
+      diagnostics: []
+    };
+  }
+  try {
+    return {
+      path: policyPath,
+      policy: validateGeneratorPolicy(JSON.parse(fs.readFileSync(policyPath, "utf8")), policyPath),
+      exists: true,
+      diagnostics: []
+    };
+  } catch (error) {
+    return {
+      path: policyPath,
+      policy: null,
+      exists: true,
+      diagnostics: [generatorPolicyDiagnostic({
+        code: "generator_policy_invalid",
+        message: error instanceof Error ? error.message : String(error),
+        path: policyPath,
+        suggestedFix: `Fix ${GENERATOR_POLICY_FILE} or regenerate it with \`topogram generator policy init\`.`,
+        step: "generator-policy"
+      })]
+    };
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {GeneratorPolicy} policy
+ * @returns {GeneratorPolicy}
+ */
+export function writeGeneratorPolicy(projectRoot, policy) {
+  fs.writeFileSync(path.join(projectRoot, GENERATOR_POLICY_FILE), `${stableStringify(policy)}\n`, "utf8");
+  return policy;
+}
+
+/**
+ * @param {GeneratorPolicyInfo} policyInfo
+ * @returns {GeneratorPolicy}
+ */
+function effectivePolicy(policyInfo) {
+  return policyInfo.policy || defaultGeneratorPolicy();
+}
+
+/**
+ * @param {GeneratorPolicyInfo} policyInfo
+ * @param {PackageGeneratorBinding[]} bindings
+ * @param {string} step
+ * @returns {GeneratorPolicyDiagnostic[]}
+ */
+export function generatorPolicyDiagnosticsForBindings(policyInfo, bindings, step = "generator-policy") {
+  if (policyInfo.diagnostics.length > 0) {
+    return policyInfo.diagnostics;
+  }
+  const policy = effectivePolicy(policyInfo);
+  /** @type {GeneratorPolicyDiagnostic[]} */
+  const diagnostics = [];
+  for (const binding of bindings) {
+    if (!generatorPackageAllowed(policy, binding.packageName)) {
+      const scope = packageScopeFromName(binding.packageName);
+      const allowedScopes = policy.allowedPackageScopes.join(", ") || "(none)";
+      const allowedPackages = policy.allowedPackages.join(", ") || "(none)";
+      diagnostics.push(generatorPolicyDiagnostic({
+        code: "generator_package_denied",
+        message: `Component '${binding.componentId}' generator package '${binding.packageName}' is not allowed by ${GENERATOR_POLICY_FILE}.`,
+        path: policyInfo.path,
+        suggestedFix: `Review '${binding.packageName}', then run \`topogram generator policy pin ${binding.packageName}@${binding.version}\` or add '${scope || binding.packageName}' to ${GENERATOR_POLICY_FILE}.`,
+        step,
+        componentId: binding.componentId,
+        generatorId: binding.generatorId,
+        packageName: binding.packageName,
+        version: binding.version
+      }));
+      diagnostics[diagnostics.length - 1].message += ` Allowed scopes: ${allowedScopes}; allowed packages: ${allowedPackages}.`;
+    }
+    const pinnedVersion = policy.pinnedVersions[binding.packageName] || policy.pinnedVersions[binding.generatorId] || null;
+    if (pinnedVersion && pinnedVersion !== binding.version) {
+      diagnostics.push(generatorPolicyDiagnostic({
+        code: "generator_version_mismatch",
+        message: `Component '${binding.componentId}' generator '${binding.generatorId}' uses version '${binding.version}', but ${GENERATOR_POLICY_FILE} pins '${binding.packageName}' to '${pinnedVersion}'.`,
+        path: policyInfo.path,
+        suggestedFix: `Use generator version '${pinnedVersion}', or run \`topogram generator policy pin ${binding.packageName}@${binding.version}\` after review.`,
+        step,
+        componentId: binding.componentId,
+        generatorId: binding.generatorId,
+        packageName: binding.packageName,
+        version: binding.version
+      }));
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * @param {Record<string, any>} projectConfig
+ * @param {string} projectRoot
+ * @param {string} [step]
+ * @returns {GeneratorPolicyDiagnostic[]}
+ */
+export function generatorPolicyDiagnosticsForProject(projectConfig, projectRoot, step = "generator-policy") {
+  const bindings = packageBackedGeneratorBindings(projectConfig);
+  const policyInfo = loadGeneratorPolicy(projectRoot);
+  return generatorPolicyDiagnosticsForBindings(policyInfo, bindings, step);
+}
+
+/**
+ * @param {Record<string, any>} projectConfig
+ * @param {{ configDir?: string|null, rootDir?: string|null }} [options]
+ * @returns {{ ok: boolean, errors: Array<{ message: string, loc: null }> }}
+ */
+export function validateProjectGeneratorPolicy(projectConfig, options = {}) {
+  const projectRoot = options.configDir || options.rootDir || process.cwd();
+  const diagnostics = generatorPolicyDiagnosticsForProject(projectConfig, projectRoot, "project-config");
+  const errors = diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map((diagnostic) => ({
+      message: diagnostic.suggestedFix
+        ? `${diagnostic.message} Suggested fix: ${diagnostic.suggestedFix}`
+        : diagnostic.message,
+      loc: null
+    }));
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * @param {string} spec
+ * @returns {{ packageName: string, version: string }}
+ */
+export function parseGeneratorPolicyPin(spec) {
+  const separator = spec.lastIndexOf("@");
+  if (separator <= 0 || separator === spec.length - 1) {
+    throw new Error("Generator policy pin requires a package name and generator version, for example @topogram/generator-react-web@1.");
+  }
+  return {
+    packageName: spec.slice(0, separator),
+    version: spec.slice(separator + 1)
+  };
+}

package/src/new-project.js

@@ -6,6 +6,7 @@ import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 
+import { defaultGeneratorPolicy, writeGeneratorPolicy } from "./generator-policy.js";
 import { writeTemplateTrustRecord } from "./template-trust.js";
 
 const CLI_PACKAGE_NAME = "@topogram/cli";
@@ -32,6 +33,15 @@ const SURFACE_ORDER = new Map([
   ["native", 40]
 ]);
 
+/**
+ * @param {string} templateId
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function unsupportedTemplateSymlinkMessage(templateId, relativePath) {
+  return `Template '${templateId}' contains unsupported symlink '${relativePath}'. Template packs must copy real files because Topogram records hashes for copied topogram/ and implementation/ content; symlinks can point outside the trusted template root. Replace the symlink with a real file or directory before running topogram new or topogram template check.`;
+}
+
 /**
  * @typedef {Object} CreateNewProjectOptions
  * @property {string} targetPath
@@ -342,7 +352,7 @@ function assertTemplateTreeHasNoSymlinks(root, currentDir, label, templateId) {
   const rootStat = fs.lstatSync(currentDir);
   const relativeRoot = path.relative(root, currentDir).replace(/\\/g, "/") || label;
   if (rootStat.isSymbolicLink()) {
-    throw new Error(`Template '${templateId}' contains unsupported symlink '${relativeRoot}'.`);
+    throw new Error(unsupportedTemplateSymlinkMessage(templateId, relativeRoot));
   }
   if (!rootStat.isDirectory()) {
     return;
@@ -351,7 +361,7 @@ function assertTemplateTreeHasNoSymlinks(root, currentDir, label, templateId) {
     const entryPath = path.join(currentDir, entry.name);
     const relativePath = path.relative(root, entryPath).replace(/\\/g, "/");
     if (entry.isSymbolicLink()) {
-      throw new Error(`Template '${templateId}' contains unsupported symlink '${relativePath}'.`);
+      throw new Error(unsupportedTemplateSymlinkMessage(templateId, relativePath));
     }
     if (entry.isDirectory()) {
       assertTemplateTreeHasNoSymlinks(root, entryPath, label, templateId);
@@ -368,10 +378,10 @@ function validateTemplateRoot(templateRoot) {
   const topogramRoot = path.join(templateRoot, "topogram");
   const projectConfigPath = path.join(templateRoot, "topogram.project.json");
   if (fs.existsSync(topogramRoot) && fs.lstatSync(topogramRoot).isSymbolicLink()) {
-    throw new Error(`Template '${manifest.id}' contains unsupported symlink 'topogram'.`);
+    throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "topogram"));
   }
   if (fs.existsSync(projectConfigPath) && fs.lstatSync(projectConfigPath).isSymbolicLink()) {
-    throw new Error(`Template '${manifest.id}' contains unsupported symlink 'topogram.project.json'.`);
+    throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "topogram.project.json"));
   }
   if (!fs.existsSync(topogramRoot) || !fs.statSync(topogramRoot).isDirectory()) {
     throw new Error(`Template '${manifest.id}' is missing topogram/.`);
@@ -383,7 +393,7 @@ function validateTemplateRoot(templateRoot) {
   if (manifest.includesExecutableImplementation) {
     const implementationRoot = path.join(templateRoot, "implementation");
     if (fs.existsSync(implementationRoot) && fs.lstatSync(implementationRoot).isSymbolicLink()) {
-      throw new Error(`Template '${manifest.id}' contains unsupported symlink 'implementation'.`);
+      throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "implementation"));
     }
     if (!fs.existsSync(implementationRoot) || !fs.statSync(implementationRoot).isDirectory()) {
       throw new Error(
@@ -1169,7 +1179,7 @@ function collectFiles(root, currentDir, files) {
     }
     const entryPath = path.join(currentDir, entry.name);
     if (entry.isSymbolicLink()) {
-      throw new Error(`Template-owned files cannot include symlink '${path.relative(root, entryPath).replace(/\\/g, "/")}'.`);
+      throw new Error(`Template-owned files cannot include symlink '${path.relative(root, entryPath).replace(/\\/g, "/")}'. Template-owned files must be real files so Topogram can hash the exact content being trusted. Replace the symlink with a real file, then run topogram trust status, topogram trust diff, and topogram trust template after review.`);
     }
     if (entry.isDirectory()) {
       collectFiles(root, entryPath, files);
@@ -1965,6 +1975,8 @@ function writeProjectPackage(projectRoot, engineRoot, template) {
       "template:detach:dry-run": "topogram template detach --dry-run",
       "template:policy:check": "topogram template policy check",
       "template:policy:explain": "topogram template policy explain",
+      "generator:policy:check": "topogram generator policy check",
+      "generator:policy:explain": "topogram generator policy explain",
       "template:update:status": "topogram template update --status",
       "template:update:recommend": "topogram template update --recommend",
       "template:update:plan": "topogram template update --plan",
@@ -2040,6 +2052,8 @@ Useful inspection:
    npm run template:detach:dry-run
    npm run template:policy:check
    npm run template:policy:explain
+   npm run generator:policy:check
+   npm run generator:policy:explain
    npm run template:update:status
    npm run template:update:recommend
    npm run template:update:plan
@@ -2070,6 +2084,7 @@ function writeProjectReadme(projectRoot, projectConfig) {
     "npm run template:explain",
     "npm run check",
     "npm run template:policy:check",
+    "npm run generator:policy:check",
     ...(template.includesExecutableImplementation ? [
       "npm run template:policy:explain",
       "npm run trust:status"
@@ -2145,6 +2160,7 @@ export function createNewProject({
   writeProjectReadme(projectRoot, projectConfig);
   writeTemplateFilesManifest(projectRoot, projectConfig);
   writeTemplatePolicy(projectRoot, defaultTemplatePolicyForTemplate(template));
+  writeGeneratorPolicy(projectRoot, defaultGeneratorPolicy());
 
   const warnings = [];
   if (template.manifest.includesExecutableImplementation) {

package/src/project-config.js

@@ -8,6 +8,7 @@ import {
   resolveGeneratorManifestForBinding,
   validateGeneratorManifest
 } from "./generator/registry.js";
+import { validateProjectGeneratorPolicy } from "./generator-policy.js";
 
 /**
  * @typedef {Object} GeneratorBinding
@@ -434,6 +435,10 @@ export function validateProjectConfig(config, graph = null, options = {}) {
     for (const component of config.topology.components) {
       validateComponentShape(errors, component, seenIds);
     }
+    const generatorPolicy = validateProjectGeneratorPolicy(config, options);
+    for (const error of generatorPolicy.errors) {
+      pushError(errors, error.message, error.loc);
+    }
     if (graph) {
       const projections = projectionById(graph);
       for (const component of config.topology.components) {

package/src/template-trust.js

@@ -19,6 +19,7 @@ export const TEMPLATE_TRUST_POLICY = "topogram-template-executable-implementatio
 
 const IGNORED_IMPLEMENTATION_ENTRIES = new Set([".DS_Store", "node_modules", ".tmp"]);
 const MAX_TEXT_DIFF_BYTES = 256 * 1024;
+const TRUST_REVIEW_COMMANDS = "`topogram trust status`, `topogram trust diff`, and `topogram trust template`";
 
 /**
  * @param {string} parent
@@ -46,6 +47,45 @@ function normalizeRelativePath(value) {
   return value.replace(/\\/g, "/");
 }
 
+/**
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function unsupportedImplementationSymlinkMessage(relativePath) {
+  return `Template implementation contains unsupported symlink '${relativePath}'. Implementation trust hashes real files under implementation/; symlinks can point outside the trusted root. Replace symlinks with real files under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+}
+
+/**
+ * @param {string} modulePath
+ * @returns {string}
+ */
+function implementationOutsideRootMessage(modulePath) {
+  return `Template implementation module '${modulePath}' must be under implementation/ for template-attached projects. Keep executable template code inside implementation/ so the trust record covers what topogram generate may load. Move the module back under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+}
+
+/**
+ * @param {string|string[]} issueOrIssues
+ * @returns {string}
+ */
+export function templateTrustRecoveryGuidance(issueOrIssues) {
+  const issues = Array.isArray(issueOrIssues) ? issueOrIssues : [issueOrIssues];
+  const text = issues.join("\n");
+  if (issues.length > 0 && issues.every((issue) =>
+    issue.includes("topogram trust status") &&
+    issue.includes("topogram trust diff") &&
+    issue.includes("topogram trust template")
+  )) {
+    return "";
+  }
+  if (text.includes("unsupported symlink")) {
+    return `Replace symlinks with real files under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+  }
+  if (text.includes("must be under implementation/")) {
+    return `Keep executable template code under implementation/ so it can be hashed and trusted; move the module back under implementation/, then run ${TRUST_REVIEW_COMMANDS} after review.`;
+  }
+  return `Run \`topogram trust status\` and \`topogram trust diff\` to review implementation changes; after review, run \`topogram trust template\` to trust the current files.`;
+}
+
 /**
  * @param {string} value
  * @returns {string}
@@ -187,7 +227,7 @@ function collectImplementationFiles(implementationRoot, currentDir, files) {
     const entryPath = path.join(currentDir, entry.name);
     const relativePath = normalizeRelativePath(path.relative(implementationRoot, entryPath));
     if (entry.isSymbolicLink()) {
-      throw new Error(`Template implementation contains unsupported symlink '${relativePath}'.`);
+      throw new Error(unsupportedImplementationSymlinkMessage(relativePath));
     }
     if (entry.isDirectory()) {
       collectImplementationFiles(implementationRoot, entryPath, files);
@@ -343,7 +383,7 @@ export function writeTemplateTrustRecord(configDir, projectConfig) {
   };
   if (!implementationModuleIsUnderRoot(implementationInfo)) {
     const implementation = implementationTrustFingerprint(implementationConfig);
-    throw new Error(`Template implementation module '${implementation.module}' must be under implementation/.`);
+    throw new Error(implementationOutsideRootMessage(implementation.module));
   }
   const implementation = implementationTrustFingerprint(implementationConfig);
   const record = buildTrustRecord(configDir, projectConfig, implementation);
@@ -362,8 +402,9 @@ export function assertTrustedImplementation(implementationInfo, projectConfig =
     return;
   }
   const firstIssue = status.issues[0] || "implementation trust is invalid";
+  const guidance = templateTrustRecoveryGuidance(firstIssue);
   throw new Error(
-    `${firstIssue}. Review implementation/ and run 'topogram trust template' to trust the current files.`
+    guidance ? `${firstIssue}. ${guidance}` : firstIssue
   );
 }
 
@@ -451,9 +492,7 @@ export function getTemplateTrustStatus(implementationInfo, projectConfig = null)
   const contentStatus = { trustedDigest: null, currentDigest: null, added: [], removed: [], changed: [] };
 
   if (templateAttached && !moduleInsideImplementation) {
-    issues.push(
-      `Template implementation module '${fingerprint.module}' must be under implementation/ for template-attached projects`
-    );
+    issues.push(implementationOutsideRootMessage(fingerprint.module));
   }
 
   if (!trustRecord) {
@@ -490,17 +529,21 @@ export function getTemplateTrustStatus(implementationInfo, projectConfig = null)
     } else if (trustRecord.content.algorithm !== "sha256") {
       issues.push(`${TEMPLATE_TRUST_FILE} uses unsupported content hash algorithm '${trustRecord.content.algorithm}'`);
     } else {
-      const currentContent = hashImplementationContent(implementationInfo.configDir);
-      contentStatus.trustedDigest = trustRecord.content.digest;
-      contentStatus.currentDigest = currentContent.digest;
-      const trustedByPath = new Map((trustRecord.content.files || []).map((file) => [file.path, file]));
-      const currentByPath = new Map(currentContent.files.map((file) => [file.path, file]));
-      const diff = diffContentFiles(trustedByPath, currentByPath);
-      contentStatus.added = diff.added;
-      contentStatus.removed = diff.removed;
-      contentStatus.changed = diff.changed;
-      if (trustRecord.content.digest !== currentContent.digest) {
-        issues.push(`${TEMPLATE_TRUST_FILE} implementation content changed since it was last trusted`);
+      try {
+        const currentContent = hashImplementationContent(implementationInfo.configDir);
+        contentStatus.trustedDigest = trustRecord.content.digest;
+        contentStatus.currentDigest = currentContent.digest;
+        const trustedByPath = new Map((trustRecord.content.files || []).map((file) => [file.path, file]));
+        const currentByPath = new Map(currentContent.files.map((file) => [file.path, file]));
+        const diff = diffContentFiles(trustedByPath, currentByPath);
+        contentStatus.added = diff.added;
+        contentStatus.removed = diff.removed;
+        contentStatus.changed = diff.changed;
+        if (trustRecord.content.digest !== currentContent.digest) {
+          issues.push(`${TEMPLATE_TRUST_FILE} implementation content changed since it was last trusted`);
+        }
+      } catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
       }
     }
   }
@@ -538,7 +581,12 @@ export function getTemplateTrustDiff(implementationInfo, projectConfig = null) {
   if (!status.requiresTrust || !status.trustRecord?.content) {
     return { ok: status.ok, requiresTrust: status.requiresTrust, status, files: [] };
   }
-  const currentContent = hashImplementationContent(implementationInfo.configDir);
+  let currentContent;
+  try {
+    currentContent = hashImplementationContent(implementationInfo.configDir);
+  } catch (_error) {
+    return { ok: false, requiresTrust: status.requiresTrust, status, files: [] };
+  }
   const trustedByPath = new Map((status.trustRecord.content.files || []).map((file) => [file.path, file]));
   const currentByPath = new Map(currentContent.files.map((file) => [file.path, file]));
   /** @type {Array<{ path: string, kind: "added"|"removed"|"changed", trusted: { path: string, sha256: string|null, size: number|null }|null, current: { path: string, sha256: string|null, size: number|null, binary: boolean, diffOmitted: boolean }|null, binary: boolean, diffOmitted: boolean, unifiedDiff: string|null }>} */