@topogram/cli 0.3.40 → 0.3.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.40",
+  "version": "0.3.41",
   "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";
@@ -5951,6 +5952,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 +5978,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 +6188,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, {
@@ -7853,7 +7865,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 +7897,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 +7927,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/new-project.js

@@ -32,6 +32,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 +351,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 +360,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 +377,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 +392,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 +1178,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);

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 }>} */