@topogram/cli 0.3.64 → 0.3.65

package/src/new-project/constants.js

@@ -0,0 +1,128 @@
+// @ts-check
+
+export const CLI_PACKAGE_NAME = "@topogram/cli";
+export const DEFAULT_TEMPLATE_NAME = "hello-web";
+export const TEMPLATE_MANIFEST = "topogram-template.json";
+export const TEMPLATE_FILES_MANIFEST = ".topogram-template-files.json";
+export const TEMPLATE_POLICY_FILE = "topogram.template-policy.json";
+export const MAX_TEXT_DIFF_BYTES = 256 * 1024;
+
+export const GENERATOR_LABELS = new Map([
+  ["topogram/express", "Express"],
+  ["topogram/hono", "Hono"],
+  ["topogram/postgres", "Postgres"],
+  ["topogram/react", "React"],
+  ["topogram/sqlite", "SQLite"],
+  ["topogram/sveltekit", "SvelteKit"],
+  ["topogram/vanilla-web", "Vanilla HTML/CSS/JS"]
+]);
+
+export const SURFACE_ORDER = new Map([
+  ["web_surface", 10],
+  ["api_service", 20],
+  ["database", 30],
+  ["ios_surface", 40],
+  ["android_surface", 50]
+]);
+
+/**
+ * @param {string} templateId
+ * @param {string} relativePath
+ * @returns {string}
+ */
+export 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
+ * @property {string} [templateName]
+ * @property {string} engineRoot
+ * @property {string} templatesRoot
+ * @property {CatalogTemplateProvenance|null} [templateProvenance]
+ */
+
+/**
+ * @typedef {Object} TemplateUpdatePlanOptions
+ * @property {string} projectRoot
+ * @property {Record<string, any>} projectConfig
+ * @property {string|null} [templateName]
+ * @property {string} templatesRoot
+ */
+
+/**
+ * @typedef {TemplateUpdatePlanOptions & { filePath: string, action: "accept-current"|"accept-candidate"|"delete-current" }} TemplateUpdateFileActionOptions
+ */
+
+/**
+ * @typedef {Object} TemplateOwnedFileRecord
+ * @property {string} path
+ * @property {string} sha256
+ * @property {number} size
+ */
+
+/**
+ * @typedef {Object} TemplateManifest
+ * @property {string} id
+ * @property {string} version
+ * @property {string} kind
+ * @property {string} topogramVersion
+ * @property {boolean} [includesExecutableImplementation]
+ * @property {string} [description]
+ * @property {Record<string, string>} [starterScripts]
+ */
+
+/**
+ * @typedef {Object} TemplateTopologySummary
+ * @property {string[]} surfaces
+ * @property {string[]} generators
+ * @property {string} stack
+ */
+
+/**
+ * @typedef {Object} TemplatePolicy
+ * @property {string} version
+ * @property {Array<"local"|"package">} allowedSources
+ * @property {string[]} allowedTemplateIds
+ * @property {string[]} [allowedPackageScopes]
+ * @property {"allow"|"warn"|"deny"} executableImplementation
+ * @property {Record<string, string>} [pinnedVersions]
+ */
+
+/**
+ * @typedef {Object} TemplatePolicyInfo
+ * @property {string} path
+ * @property {TemplatePolicy|null} policy
+ * @property {boolean} exists
+ * @property {TemplateUpdateDiagnostic[]} diagnostics
+ */
+
+/**
+ * @typedef {Object} TemplateUpdateDiagnostic
+ * @property {string} code
+ * @property {"error"|"warning"} severity
+ * @property {string} message
+ * @property {string|null} path
+ * @property {string|null} suggestedFix
+ * @property {string|null} step
+ */
+
+/**
+ * @typedef {Object} ResolvedTemplate
+ * @property {string} requested
+ * @property {string} root
+ * @property {TemplateManifest} manifest
+ * @property {"local"|"package"} source
+ * @property {string|null} packageSpec
+ */
+
+/**
+ * @typedef {Object} CatalogTemplateProvenance
+ * @property {string} id
+ * @property {string} source
+ * @property {string} package
+ * @property {string} version
+ * @property {string} packageSpec
+ * @property {boolean} [includesExecutableImplementation]
+ */

package/src/new-project/create.js

@@ -0,0 +1,83 @@
+// @ts-check
+
+import path from "node:path";
+
+import { defaultGeneratorPolicy, writeGeneratorPolicy } from "../generator-policy.js";
+import { writeTemplateTrustRecord } from "../template-trust.js";
+import { DEFAULT_TEMPLATE_NAME } from "./constants.js";
+import { writeProjectTemplateMetadata } from "./metadata.js";
+import { assertProjectOutsideEngine, copyTopogramWorkspace, ensureCreatableProjectRoot, writeAgentsGuide, writeExplainScript, writeProjectPackage, writeProjectReadme } from "./project-files.js";
+import { resolveTemplate } from "./template-resolution.js";
+import { defaultTemplatePolicyForTemplate, writeTemplatePolicy } from "./template-policy.js";
+import { writeTemplateFilesManifest } from "./template-snapshots.js";
+
+/** @typedef {import("./types.js").CreateNewProjectOptions} CreateNewProjectOptions */
+/** @typedef {import("./types.js").TemplateUpdatePlanOptions} TemplateUpdatePlanOptions */
+/** @typedef {import("./types.js").TemplateUpdateFileActionOptions} TemplateUpdateFileActionOptions */
+/** @typedef {import("./types.js").TemplateOwnedFileRecord} TemplateOwnedFileRecord */
+/** @typedef {import("./types.js").TemplateManifest} TemplateManifest */
+/** @typedef {import("./types.js").TemplateTopologySummary} TemplateTopologySummary */
+/** @typedef {import("./types.js").TemplatePolicy} TemplatePolicy */
+/** @typedef {import("./types.js").TemplatePolicyInfo} TemplatePolicyInfo */
+/** @typedef {import("./types.js").TemplateUpdateDiagnostic} TemplateUpdateDiagnostic */
+/** @typedef {import("./types.js").ResolvedTemplate} ResolvedTemplate */
+/** @typedef {import("./types.js").CatalogTemplateProvenance} CatalogTemplateProvenance */
+
+/**
+ * @param {CreateNewProjectOptions} options
+ * @returns {{ projectRoot: string, templateName: string, template: Record<string, any>, topogramPath: string, appPath: string, warnings: string[] }}
+ */
+export function createNewProject({
+  targetPath,
+  templateName = DEFAULT_TEMPLATE_NAME,
+  engineRoot,
+  templatesRoot,
+  templateProvenance = null
+}) {
+  if (!targetPath) {
+    throw new Error("topogram new requires <path>.");
+  }
+  const projectRoot = path.resolve(targetPath);
+  assertProjectOutsideEngine(projectRoot, engineRoot);
+  const template = resolveTemplate(templateName, templatesRoot);
+  if (
+    templateProvenance &&
+    typeof templateProvenance.includesExecutableImplementation === "boolean" &&
+    templateProvenance.includesExecutableImplementation !== Boolean(template.manifest.includesExecutableImplementation)
+  ) {
+    throw new Error(
+      `Catalog entry '${templateProvenance.id}' declares includesExecutableImplementation: ${templateProvenance.includesExecutableImplementation}, ` +
+        `but template package '${template.packageSpec || template.requested}' declares includesExecutableImplementation: ${Boolean(template.manifest.includesExecutableImplementation)}.`
+    );
+  }
+
+  ensureCreatableProjectRoot(projectRoot);
+  copyTopogramWorkspace(template.root, projectRoot);
+  const projectConfig = writeProjectTemplateMetadata(projectRoot, template, templateProvenance);
+  writeProjectPackage(projectRoot, engineRoot, template);
+  writeExplainScript(projectRoot);
+  writeProjectReadme(projectRoot, projectConfig);
+  writeAgentsGuide(projectRoot, projectConfig);
+  writeTemplateFilesManifest(projectRoot, projectConfig);
+  writeTemplatePolicy(projectRoot, defaultTemplatePolicyForTemplate(template));
+  writeGeneratorPolicy(projectRoot, defaultGeneratorPolicy());
+
+  const warnings = [];
+  if (template.manifest.includesExecutableImplementation) {
+    writeTemplateTrustRecord(projectRoot, projectConfig);
+    warnings.push(
+      `Template '${template.manifest.id}' copied implementation/ code into this project. ` +
+        "topogram new did not execute it, but topogram generate may load it later. " +
+        "Recorded local trust in .topogram-template-trust.json."
+    );
+  }
+
+  return {
+    projectRoot,
+    templateName: template.manifest.id,
+    template: projectConfig.template,
+    topogramPath: path.join(projectRoot, "topogram"),
+    appPath: path.join(projectRoot, "app"),
+    warnings
+  };
+}

package/src/new-project/json.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * @param {any} value
+ * @returns {any}
+ */
+function sortJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  if (value && typeof value === "object") {
+    /** @type {Record<string, any>} */
+    const sorted = {};
+    for (const key of Object.keys(value).sort((left, right) => left.localeCompare(right))) {
+      sorted[key] = sortJsonValue(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/**
+ * @param {any} value
+ * @returns {string}
+ */
+export function stableJsonStringify(value) {
+  return JSON.stringify(sortJsonValue(value), null, 2);
+}

package/src/new-project/metadata.js

@@ -0,0 +1,96 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableJsonStringify } from "./json.js";
+
+/** @typedef {import("./types.js").CreateNewProjectOptions} CreateNewProjectOptions */
+/** @typedef {import("./types.js").TemplateUpdatePlanOptions} TemplateUpdatePlanOptions */
+/** @typedef {import("./types.js").TemplateUpdateFileActionOptions} TemplateUpdateFileActionOptions */
+/** @typedef {import("./types.js").TemplateOwnedFileRecord} TemplateOwnedFileRecord */
+/** @typedef {import("./types.js").TemplateManifest} TemplateManifest */
+/** @typedef {import("./types.js").TemplateTopologySummary} TemplateTopologySummary */
+/** @typedef {import("./types.js").TemplatePolicy} TemplatePolicy */
+/** @typedef {import("./types.js").TemplatePolicyInfo} TemplatePolicyInfo */
+/** @typedef {import("./types.js").TemplateUpdateDiagnostic} TemplateUpdateDiagnostic */
+/** @typedef {import("./types.js").ResolvedTemplate} ResolvedTemplate */
+/** @typedef {import("./types.js").CatalogTemplateProvenance} CatalogTemplateProvenance */
+
+/**
+ * @param {string} projectRoot
+ * @param {ResolvedTemplate} template
+ * @param {CatalogTemplateProvenance|null} [templateProvenance]
+ * @returns {Record<string, any>}
+ */
+export function writeProjectTemplateMetadata(projectRoot, template, templateProvenance = null) {
+  const projectConfigPath = path.join(projectRoot, "topogram.project.json");
+  const projectConfig = JSON.parse(fs.readFileSync(projectConfigPath, "utf8"));
+  projectConfig.template = projectTemplateMetadata(template, templateProvenance);
+  fs.writeFileSync(projectConfigPath, `${stableJsonStringify(projectConfig)}\n`, "utf8");
+  return projectConfig;
+}
+
+/**
+ * @param {ResolvedTemplate} template
+ * @param {CatalogTemplateProvenance|null} [templateProvenance]
+ * @returns {{ id: string, version: string, source: string, requested: string, sourceSpec: string, sourceRoot: string|null, includesExecutableImplementation: boolean, catalog?: CatalogTemplateProvenance }}
+ */
+export function projectTemplateMetadata(template, templateProvenance = null) {
+  /** @type {{ id: string, version: string, source: string, requested: string, sourceSpec: string, sourceRoot: string|null, includesExecutableImplementation: boolean, catalog?: CatalogTemplateProvenance }} */
+  const metadata = {
+    id: template.manifest.id,
+    version: template.manifest.version,
+    source: template.source,
+    requested: templateProvenance?.id || template.requested,
+    sourceSpec: template.packageSpec || template.requested,
+    sourceRoot: template.source === "local" ? template.root : null,
+    includesExecutableImplementation: Boolean(template.manifest.includesExecutableImplementation)
+  };
+  if (templateProvenance) {
+    metadata.catalog = templateProvenance;
+  }
+  return metadata;
+}
+
+/**
+ * @param {Record<string, any>} projectConfig
+ * @returns {{ id: string|null, version: string|null, source: string|null, sourceSpec: string|null, requested: string|null }}
+ */
+export function currentTemplateMetadata(projectConfig) {
+  const currentTemplate = projectConfig.template || {};
+  return {
+    id: typeof currentTemplate.id === "string" ? currentTemplate.id : null,
+    version: typeof currentTemplate.version === "string" ? currentTemplate.version : null,
+    source: typeof currentTemplate.source === "string" ? currentTemplate.source : null,
+    sourceSpec: typeof currentTemplate.sourceSpec === "string" ? currentTemplate.sourceSpec : null,
+    requested: typeof currentTemplate.requested === "string" ? currentTemplate.requested : null
+  };
+}
+
+/**
+ * @param {ResolvedTemplate} template
+ * @param {Record<string, any>|null} currentProjectConfig
+ * @returns {ReturnType<typeof projectTemplateMetadata>}
+ */
+export function candidateProjectTemplateMetadata(template, currentProjectConfig) {
+  const metadata = projectTemplateMetadata(template);
+  const currentTemplate = currentProjectConfig?.template || null;
+  if (!currentTemplate || currentTemplate.id !== metadata.id) {
+    return metadata;
+  }
+  if (typeof currentTemplate.requested === "string" && currentTemplate.requested) {
+    metadata.requested = currentTemplate.requested;
+  }
+  if (currentTemplate.catalog && typeof currentTemplate.catalog === "object") {
+    metadata.catalog = {
+      ...currentTemplate.catalog,
+      package: typeof currentTemplate.catalog.package === "string"
+        ? currentTemplate.catalog.package
+        : metadata.id,
+      version: metadata.version,
+      packageSpec: metadata.sourceSpec
+    };
+  }
+  return metadata;
+}

package/src/new-project/package-spec.js

@@ -0,0 +1,161 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { CLI_PACKAGE_NAME } from "./constants.js";
+
+/**
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function packageNameFromPath(projectRoot) {
+  const baseName = path.basename(path.resolve(projectRoot)).toLowerCase();
+  const normalized = baseName
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[._-]+/, "")
+    .replace(/[._-]+$/, "");
+  return normalized || "topogram-app";
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} engineRoot
+ * @returns {string}
+ */
+function fileDependencyForEngine(projectRoot, engineRoot) {
+  const relative = path.relative(projectRoot, engineRoot).replace(/\\/g, "/");
+  if (!relative || relative.startsWith("..")) {
+    return `file:${engineRoot}`;
+  }
+  return `file:./${relative}`;
+}
+
+/**
+ * @param {string} engineRoot
+ * @returns {{ name: string, version: string }}
+ */
+function readCliPackageMetadata(engineRoot) {
+  const packagePath = path.join(engineRoot, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  return {
+    name: typeof pkg.name === "string" ? pkg.name : CLI_PACKAGE_NAME,
+    version: typeof pkg.version === "string" ? pkg.version : "0.0.0"
+  };
+}
+
+/**
+ * @param {string} engineRoot
+ * @returns {boolean}
+ */
+function isSourceCheckoutEngine(engineRoot) {
+  return fs.existsSync(path.join(engineRoot, "tests", "active"));
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} engineRoot
+ * @returns {{ name: string, spec: string }}
+ */
+export function cliDependencyForProject(projectRoot, engineRoot) {
+  const metadata = readCliPackageMetadata(engineRoot);
+  const overrideSpec = process.env.TOPOGRAM_CLI_PACKAGE_SPEC || "";
+  if (overrideSpec) {
+    return { name: metadata.name, spec: overrideSpec };
+  }
+  if (isSourceCheckoutEngine(engineRoot)) {
+    return { name: metadata.name, spec: fileDependencyForEngine(projectRoot, engineRoot) };
+  }
+  return { name: metadata.name, spec: metadata.version };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ name: string, spec: string }} cliDependency
+ * @returns {void}
+ */
+export function writeProjectNpmConfig(projectRoot, cliDependency) {
+  void projectRoot;
+  void cliDependency;
+}
+
+/**
+ * @param {string} templateRoot
+ * @returns {Record<string, string>}
+ */
+export function generatorDependenciesForTemplate(templateRoot) {
+  const packagePath = path.join(templateRoot, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return {};
+  }
+  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  const explicit = pkg.topogramGeneratorDependencies &&
+    typeof pkg.topogramGeneratorDependencies === "object" &&
+    !Array.isArray(pkg.topogramGeneratorDependencies)
+    ? pkg.topogramGeneratorDependencies
+    : {};
+  const dependencies = {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+    ...explicit
+  };
+  return Object.fromEntries(Object.entries(dependencies).filter(([name, spec]) =>
+    typeof name === "string" &&
+    (name.includes("topogram-generator") || name.startsWith("@topogram/generator-")) &&
+    typeof spec === "string" &&
+    spec.length > 0
+  ));
+}
+
+/**
+ * @param {string} parent
+ * @param {string} child
+ * @returns {boolean}
+ */
+export function isSameOrInside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isLocalTemplateSpec(value) {
+  return value === "." ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    path.isAbsolute(value);
+}
+
+/**
+ * @param {string} spec
+ * @returns {string}
+ */
+export function packageNameFromSpec(spec) {
+  if (spec.startsWith("@")) {
+    const segments = spec.split("/");
+    if (segments.length < 2) {
+      throw new Error(`Invalid scoped template package spec '${spec}'.`);
+    }
+    const scope = segments[0];
+    const nameAndVersion = segments[1];
+    const versionIndex = nameAndVersion.indexOf("@");
+    const name = versionIndex >= 0 ? nameAndVersion.slice(0, versionIndex) : nameAndVersion;
+    return `${scope}/${name}`;
+  }
+  const versionIndex = spec.indexOf("@");
+  return versionIndex >= 0 ? spec.slice(0, versionIndex) : spec;
+}
+
+/**
+ * @param {string|null|undefined} spec
+ * @returns {string|null}
+ */
+export function packageScopeFromSpec(spec) {
+  if (!spec) {
+    return null;
+  }
+  const packageName = packageNameFromSpec(spec);
+  return packageName.startsWith("@") ? packageName.split("/")[0] : null;
+}