@topogram/cli 0.3.39 → 0.3.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.39",
+  "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
   });
@@ -6170,13 +6182,13 @@ function buildTemplateCheckPayload(templateSpec) {
         configDir: projectConfigInfo.configDir
       }
     : null;
-  if (implementationInfo && implementationRequiresTrust(implementationInfo)) {
+  if (implementationInfo && implementationRequiresTrust(implementationInfo, projectConfigInfo.config)) {
     const trustStatus = getTemplateTrustStatus(implementationInfo, projectConfigInfo.config);
     const trustDiagnostics = trustStatus.issues.map((issue) => templateCheckDiagnostic({
       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, {
@@ -7796,7 +7808,7 @@ try {
         configPath: projectConfigInfo.configPath,
         configDir: projectConfigInfo.configDir
       };
-      if (implementationRequiresTrust(implementationInfo)) {
+      if (implementationRequiresTrust(implementationInfo, projectConfigInfo.config)) {
         const trustRecord = writeTemplateTrustRecord(projectConfigInfo.configDir, projectConfigInfo.config);
         console.log(`Wrote ${TEMPLATE_TRUST_FILE} for ${trustRecord.implementation.module}.`);
         if (trustRecord.template.id) {
@@ -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
@@ -331,6 +340,34 @@ function readTemplateManifest(templateRoot) {
   return validateTemplateManifest(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
 }
 
+/**
+ * @param {string} root
+ * @param {string} currentDir
+ * @param {string} label
+ * @param {string} templateId
+ * @returns {void}
+ */
+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(unsupportedTemplateSymlinkMessage(templateId, relativeRoot));
+  }
+  if (!rootStat.isDirectory()) {
+    return;
+  }
+  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+    const entryPath = path.join(currentDir, entry.name);
+    const relativePath = path.relative(root, entryPath).replace(/\\/g, "/");
+    if (entry.isSymbolicLink()) {
+      throw new Error(unsupportedTemplateSymlinkMessage(templateId, relativePath));
+    }
+    if (entry.isDirectory()) {
+      assertTemplateTreeHasNoSymlinks(root, entryPath, label, templateId);
+    }
+  }
+}
+
 /**
  * @param {string} templateRoot
  * @returns {TemplateManifest}
@@ -339,19 +376,30 @@ function validateTemplateRoot(templateRoot) {
   const manifest = readTemplateManifest(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(unsupportedTemplateSymlinkMessage(manifest.id, "topogram"));
+  }
+  if (fs.existsSync(projectConfigPath) && fs.lstatSync(projectConfigPath).isSymbolicLink()) {
+    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/.`);
   }
   if (!fs.existsSync(projectConfigPath) || !fs.statSync(projectConfigPath).isFile()) {
     throw new Error(`Template '${manifest.id}' is missing topogram.project.json.`);
   }
+  assertTemplateTreeHasNoSymlinks(templateRoot, topogramRoot, "topogram", manifest.id);
   if (manifest.includesExecutableImplementation) {
     const implementationRoot = path.join(templateRoot, "implementation");
+    if (fs.existsSync(implementationRoot) && fs.lstatSync(implementationRoot).isSymbolicLink()) {
+      throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "implementation"));
+    }
     if (!fs.existsSync(implementationRoot) || !fs.statSync(implementationRoot).isDirectory()) {
       throw new Error(
         `Template '${manifest.id}' declares executable implementation code but is missing implementation/.`
       );
     }
+    assertTemplateTreeHasNoSymlinks(templateRoot, implementationRoot, "implementation", manifest.id);
   } else {
     const implementationRoot = path.join(templateRoot, "implementation");
     if (fs.existsSync(implementationRoot) && fs.statSync(implementationRoot).isDirectory()) {
@@ -1129,6 +1177,9 @@ function collectFiles(root, currentDir, files) {
       continue;
     }
     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, "/")}'. 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);
       continue;

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}
@@ -185,12 +225,16 @@ function collectImplementationFiles(implementationRoot, currentDir, files) {
       continue;
     }
     const entryPath = path.join(currentDir, entry.name);
+    const relativePath = normalizeRelativePath(path.relative(implementationRoot, entryPath));
+    if (entry.isSymbolicLink()) {
+      throw new Error(unsupportedImplementationSymlinkMessage(relativePath));
+    }
     if (entry.isDirectory()) {
       collectImplementationFiles(implementationRoot, entryPath, files);
       continue;
     }
     if (entry.isFile()) {
-      files.push(normalizeRelativePath(path.relative(implementationRoot, entryPath)));
+      files.push(relativePath);
     }
   }
 }
@@ -250,17 +294,38 @@ export function implementationTrustFingerprint(config) {
   };
 }
 
+/**
+ * @param {{ config: Record<string, any>, configDir: string }} implementationInfo
+ * @param {Record<string, any>|null} [projectConfig]
+ * @returns {boolean}
+ */
+export function implementationRequiresTrust(implementationInfo, projectConfig = null) {
+  const fingerprint = implementationTrustFingerprint(implementationInfo.config);
+  const modulePath = path.resolve(implementationInfo.configDir, fingerprint.module);
+  const implementationRoot = path.resolve(implementationInfo.configDir, "implementation");
+  return isSameOrInside(implementationRoot, modulePath) || projectHasTemplateAttachment(projectConfig);
+}
+
 /**
  * @param {{ config: Record<string, any>, configDir: string }} implementationInfo
  * @returns {boolean}
  */
-export function implementationRequiresTrust(implementationInfo) {
+function implementationModuleIsUnderRoot(implementationInfo) {
   const fingerprint = implementationTrustFingerprint(implementationInfo.config);
   const modulePath = path.resolve(implementationInfo.configDir, fingerprint.module);
   const implementationRoot = path.resolve(implementationInfo.configDir, "implementation");
   return isSameOrInside(implementationRoot, modulePath);
 }
 
+/**
+ * @param {Record<string, any>|null} projectConfig
+ * @returns {boolean}
+ */
+function projectHasTemplateAttachment(projectConfig) {
+  const template = projectConfig?.template || null;
+  return Boolean(template?.id || template?.sourceSpec || template?.requested);
+}
+
 /**
  * @param {string} configDir
  * @returns {TemplateTrustRecord|null}
@@ -312,6 +377,14 @@ export function writeTemplateTrustRecord(configDir, projectConfig) {
   if (!implementationConfig) {
     throw new Error("Cannot trust template implementation because topogram.project.json has no implementation config.");
   }
+  const implementationInfo = {
+    config: implementationConfig,
+    configDir
+  };
+  if (!implementationModuleIsUnderRoot(implementationInfo)) {
+    const implementation = implementationTrustFingerprint(implementationConfig);
+    throw new Error(implementationOutsideRootMessage(implementation.module));
+  }
   const implementation = implementationTrustFingerprint(implementationConfig);
   const record = buildTrustRecord(configDir, projectConfig, implementation);
   fs.writeFileSync(path.join(configDir, TEMPLATE_TRUST_FILE), `${JSON.stringify(record, null, 2)}\n`, "utf8");
@@ -329,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
   );
 }
 
@@ -393,7 +467,8 @@ function implementationReviewFile(configDir, relativePath, file) {
  * @returns {{ ok: boolean, requiresTrust: boolean, trustPath: string, trustRecord: TemplateTrustRecord|null, template: { id: string|null, version: string|null, source: string|null, sourceSpec: string|null, requested: string|null, sourceRoot: string|null, catalog?: Record<string, any>|null, includesExecutableImplementation: boolean|null }, implementation: { id: string|null, module: string|null, export: string|null }, content: { trustedDigest: string|null, currentDigest: string|null, added: string[], removed: string[], changed: string[] }, issues: string[] }}
  */
 export function getTemplateTrustStatus(implementationInfo, projectConfig = null) {
-  if (!implementationRequiresTrust(implementationInfo)) {
+  const templateAttached = projectHasTemplateAttachment(projectConfig);
+  if (!implementationRequiresTrust(implementationInfo, projectConfig)) {
     return {
       ok: true,
       requiresTrust: false,
@@ -406,6 +481,7 @@ export function getTemplateTrustStatus(implementationInfo, projectConfig = null)
     };
   }
   const fingerprint = implementationTrustFingerprint(implementationInfo.config);
+  const moduleInsideImplementation = implementationModuleIsUnderRoot(implementationInfo);
   const trustRecord = readTemplateTrustRecord(implementationInfo.configDir);
   const configLabel = implementationInfo.configPath || "topogram.project.json";
   const trustPath = path.join(implementationInfo.configDir, TEMPLATE_TRUST_FILE);
@@ -415,6 +491,10 @@ export function getTemplateTrustStatus(implementationInfo, projectConfig = null)
   /** @type {{ trustedDigest: string|null, currentDigest: string|null, added: string[], removed: string[], changed: string[] }} */
   const contentStatus = { trustedDigest: null, currentDigest: null, added: [], removed: [], changed: [] };
 
+  if (templateAttached && !moduleInsideImplementation) {
+    issues.push(implementationOutsideRootMessage(fingerprint.module));
+  }
+
   if (!trustRecord) {
     issues.push(
       `Refusing to load executable implementation '${fingerprint.module}' from ${normalizeRoot(configLabel)} without ${TEMPLATE_TRUST_FILE}`
@@ -441,22 +521,29 @@ export function getTemplateTrustStatus(implementationInfo, projectConfig = null)
       issues.push(`${TEMPLATE_TRUST_FILE} trusts template version '${trustRecord.template?.version}', but topogram.project.json declares '${projectTemplate.version}'`);
     }
 
-    if (!trustRecord.content) {
+    if (!moduleInsideImplementation) {
+      // The module itself is outside the only supported trust root. Do not
+      // pretend the implementation/ content digest covers the executable code.
+    } else if (!trustRecord.content) {
       issues.push(`${TEMPLATE_TRUST_FILE} is missing implementation content hashes`);
     } 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));
       }
     }
   }
@@ -494,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 }>} */