@topogram/cli 0.3.63 → 0.3.64

package/src/import/index.d.ts

@@ -0,0 +1,4 @@
+export function createImportContext(...args: any[]): any;
+export function normalizeWorkspacePaths(...args: any[]): any;
+export function parseImportTracks(...args: any[]): any;
+export function runImportAppWorkflow(...args: any[]): any;

package/src/import/provenance.d.ts

@@ -0,0 +1,4 @@
+export const TOPOGRAM_IMPORT_FILE: string;
+export function buildTopogramImportStatus(projectRoot: string): any;
+export function collectImportSourceFileRecords(sourceRoot: string, options?: any): any[];
+export function writeTopogramImportRecord(projectRoot: string, input: any): any;

package/src/new-project.js

@@ -7,7 +7,9 @@ import os from "node:os";
 import path from "node:path";
 
 import { defaultGeneratorPolicy, writeGeneratorPolicy } from "./generator-policy.js";
+import { assertSafeNpmSpec, localNpmrcEnv } from "./npm-safety.js";
 import { writeTemplateTrustRecord } from "./template-trust.js";
+import { githubRepoSlug } from "./topogram-config.js";
 
 const CLI_PACKAGE_NAME = "@topogram/cli";
 const DEFAULT_TEMPLATE_NAME = "hello-web";
@@ -464,12 +466,9 @@ function summarizeTemplateTopology(templateRoot) {
  * @returns {string}
  */
 export function installPackageSpec(templateSpec) {
+  assertSafeNpmSpec(templateSpec);
   const installRoot = fs.mkdtempSync(path.join(os.tmpdir(), "topogram-template-"));
   const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
-  const localNpmConfig = path.join(process.cwd(), ".npmrc");
-  const npmConfigEnv = !process.env.NPM_CONFIG_USERCONFIG && fs.existsSync(localNpmConfig)
-    ? { NPM_CONFIG_USERCONFIG: localNpmConfig }
-    : {};
   const result = childProcess.spawnSync(
     npmBin,
     [
@@ -480,13 +479,14 @@ export function installPackageSpec(templateSpec) {
       "--no-audit",
       "--no-fund",
       "--package-lock=false",
+      "--",
       templateSpec
     ],
     {
       encoding: "utf8",
       env: {
         ...process.env,
-        ...npmConfigEnv,
+        ...localNpmrcEnv(process.cwd()),
         PATH: process.env.PATH || ""
       }
     }
@@ -509,7 +509,7 @@ export function installPackageSpec(templateSpec) {
 function formatPackageInstallError(templateSpec, result) {
   const output = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim();
   const normalized = output.toLowerCase();
-  const npmrcHint = "Ensure npm can access the registry required by this template package.";
+  const npmrcHint = "Ensure npm can access the registry required by this template package. Topogram ignores project .npmrc files unless TOPOGRAM_ALLOW_LOCAL_NPMRC=1 or --allow-local-npmrc is used.";
   const packageAccessHint = "For private package registries, configure a token with package read access.";
   const authHint = "For private template packages, configure npm auth for the package registry before installing.";
   const doctorHint = "Run `topogram doctor` to check Node.js, npm, package, and catalog access.";
@@ -1963,6 +1963,7 @@ function writeProjectPackage(projectRoot, engineRoot, template) {
     scripts: {
       explain: "node ./scripts/explain.mjs",
       doctor: "topogram doctor",
+      "agent:brief": "topogram agent brief --json",
       "source:status": "topogram source status --local",
       "source:status:remote": "topogram source status --remote",
       check: "topogram check",
@@ -2022,29 +2023,33 @@ Topogram app workflow
    topogram/
    topogram.project.json
 
-2. Validate:
+2. Start with project guidance:
+   npm run agent:brief
+
+3. Validate:
    npm run doctor
    npm run source:status
    npm run template:explain
    npm run check
 
-3. Regenerate:
+4. Regenerate:
    npm run generate
 
-4. Verify generated app:
+5. Verify generated app:
    npm run verify
 
-5. Run locally:
+6. Run locally:
    npm run bootstrap
    npm run dev
 
-6. Probe the running app from another terminal:
+7. Probe the running app from another terminal:
    npm run app:probe
 
 Or run self-contained local runtime verification:
    npm run app:runtime
 
 Useful inspection:
+   npm run agent:brief
    npm run check:json
    topogram emit ui-widget-contract ./topogram --json
    topogram emit widget-conformance-report ./topogram --json
@@ -2084,6 +2089,7 @@ function writeProjectReadme(projectRoot, projectConfig) {
   const workflowCommands = [
     "npm install",
     "npm run explain",
+    "npm run agent:brief",
     "npm run doctor",
     "npm run source:status",
     "npm run template:explain",
@@ -2126,11 +2132,93 @@ ${workflowCommands.join("\n")}
 Edit \`topogram/\` and \`topogram.project.json\`, then regenerate with \`npm run generate\`.
 Generated app code is written to \`app/\`.
 Use \`topogram emit <target>\` to inspect contracts, reports, snapshots, and other artifacts without regenerating the app.
+Agents should start with \`AGENTS.md\` and \`npm run agent:brief\`. The direct \`topogram agent brief --json\` command is the canonical machine-readable first-run guidance.
 ${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram new` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
 `;
   fs.writeFileSync(path.join(projectRoot, "README.md"), readme, "utf8");
 }
 
+/**
+ * @param {string} projectRoot
+ * @param {Record<string, any>} projectConfig
+ * @returns {void}
+ */
+function writeAgentsGuide(projectRoot, projectConfig) {
+  const template = projectConfig.template || {};
+  const hasImplementation = Boolean(projectConfig.implementation || template.includesExecutableImplementation);
+  const guide = `# Agent Guide
+
+Start here before editing this Topogram project.
+
+## First Read
+
+1. \`AGENTS.md\`
+2. \`README.md\`
+3. \`topogram.project.json\`
+4. \`topogram.template-policy.json\`
+5. \`topogram.generator-policy.json\`
+${hasImplementation ? "6. `.topogram-template-trust.json`\n7. `implementation/`\n8. Focused `topogram query ...` output\n" : "6. Focused `topogram query ...` output\n"}
+Machine-readable source:
+
+\`\`\`bash
+topogram agent brief --json
+\`\`\`
+
+Local shortcut:
+
+\`\`\`bash
+npm run agent:brief
+\`\`\`
+
+Reference: https://github.com/${githubRepoSlug(null)}/blob/main/docs/agent-first-run.md
+
+## First Commands
+
+\`\`\`bash
+npm run agent:brief
+npm run doctor
+npm run source:status
+npm run template:explain
+npm run generator:policy:check
+${hasImplementation ? "npm run trust:status\n" : ""}npm run check
+npm run query:list
+npm run query:show -- widget-behavior
+\`\`\`
+
+## Edit Rules
+
+- Edit \`topogram/**\` and \`topogram.project.json\` first.
+- Review policy files before editing \`topogram.template-policy.json\` or \`topogram.generator-policy.json\`.
+- Do not make lasting edits under generated-owned \`app/**\`; use \`npm run generate\` to replace generated output.
+- If an output is changed to maintained ownership, agents may edit that app code directly after reading focused query packets.
+
+## UI And Widgets
+
+- \`ui_contract\` owns screens, regions, widget bindings, behavior, visibility, and semantic design tokens.
+- Web/iOS/Android surfaces realize the shared UI contract; they do not own widget placement.
+- Use \`topogram widget check --json\`, \`topogram widget behavior --json\`, and focused \`topogram query ...\` packets after UI edits.
+
+## Template And Trust
+
+- Local edits to template-derived Topogram files are project-owned.
+- Use \`npm run source:status\` and \`npm run template:update:recommend\` before applying template updates.
+${hasImplementation ? "- This project has executable `implementation/` code. `topogram new` did not execute it. Do not refresh trust until the implementation has been reviewed.\n" : "- This template does not declare executable implementation code.\n"}
+## Import And Adoption
+
+- If \`.topogram-import.json\` exists, run \`topogram import check .\`, \`topogram import plan .\`, \`topogram import adopt --list .\`, and \`topogram import history . --verify\`.
+- Imported Topogram files are project-owned after adoption; source hashes record trusted import evidence at the time of import.
+
+## Verification Gates
+
+\`\`\`bash
+npm run check
+npm run generate
+npm run verify
+\`\`\`
+`;
+  fs.writeFileSync(path.join(projectRoot, "AGENTS.md"), guide, "utf8");
+}
+
 /**
  * @param {CreateNewProjectOptions} options
  * @returns {{ projectRoot: string, templateName: string, template: Record<string, any>, topogramPath: string, appPath: string, warnings: string[] }}
@@ -2165,6 +2253,7 @@ export function createNewProject({
   writeProjectPackage(projectRoot, engineRoot, template);
   writeExplainScript(projectRoot);
   writeProjectReadme(projectRoot, projectConfig);
+  writeAgentsGuide(projectRoot, projectConfig);
   writeTemplateFilesManifest(projectRoot, projectConfig);
   writeTemplatePolicy(projectRoot, defaultTemplatePolicyForTemplate(template));
   writeGeneratorPolicy(projectRoot, defaultGeneratorPolicy());

package/src/npm-safety.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const LOCAL_NPMRC_ENV = "TOPOGRAM_ALLOW_LOCAL_NPMRC";
+
+/**
+ * @param {string} spec
+ * @returns {string}
+ */
+export function assertSafeNpmSpec(spec) {
+  if (typeof spec !== "string" || spec.trim().length === 0) {
+    throw new Error("Empty npm package spec.");
+  }
+  if (spec.startsWith("-")) {
+    throw new Error(`Refusing npm package spec starting with '-': '${spec}'.`);
+  }
+  if (/[\s\r\n\0]/.test(spec)) {
+    throw new Error(`Invalid characters in npm package spec: '${spec}'.`);
+  }
+  return spec;
+}
+
+/**
+ * @param {string|undefined} value
+ * @returns {boolean}
+ */
+export function localNpmrcAllowedByEnv(value = process.env[LOCAL_NPMRC_ENV]) {
+  return value === "1" || value === "true" || value === "yes";
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{ exists: boolean, path: string, enabled: boolean, reason: string }}
+ */
+export function localNpmrcStatus(cwd = process.cwd()) {
+  const npmrcPath = path.join(cwd, ".npmrc");
+  const exists = fs.existsSync(npmrcPath);
+  if (process.env.NPM_CONFIG_USERCONFIG) {
+    return {
+      exists,
+      path: npmrcPath,
+      enabled: false,
+      reason: "NPM_CONFIG_USERCONFIG is already set explicitly."
+    };
+  }
+  if (!exists) {
+    return {
+      exists,
+      path: npmrcPath,
+      enabled: false,
+      reason: "No local .npmrc was found."
+    };
+  }
+  if (!localNpmrcAllowedByEnv()) {
+    return {
+      exists,
+      path: npmrcPath,
+      enabled: false,
+      reason: `Local .npmrc is ignored unless ${LOCAL_NPMRC_ENV}=1 or --allow-local-npmrc is used.`
+    };
+  }
+  return {
+    exists,
+    path: npmrcPath,
+    enabled: true,
+    reason: `Local .npmrc is enabled by ${LOCAL_NPMRC_ENV}.`
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, string>}
+ */
+export function localNpmrcEnv(cwd = process.cwd()) {
+  const status = localNpmrcStatus(cwd);
+  return status.enabled ? { NPM_CONFIG_USERCONFIG: status.path } : {};
+}

package/src/parser.d.ts

@@ -0,0 +1 @@
+export function parsePath(root: string): any;

package/src/path-helpers.d.ts

@@ -0,0 +1 @@
+export function relativeTo(from: string, to: string): string;

package/src/path-helpers.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+import path from "node:path";
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function toPosixPath(value) {
+  return String(value || "").replaceAll("\\", "/").replaceAll(path.sep, "/");
+}
+
+/**
+ * @param {string} base
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function relativeTo(base, filePath) {
+  return toPosixPath(path.relative(base, filePath));
+}

package/src/project-config.js

@@ -35,6 +35,7 @@ import { validateProjectGeneratorPolicy } from "./generator-policy.js";
  * @property {Record<string, { path: string, ownership: "generated"|"maintained" }>} outputs
  * @property {{ runtimes: RuntimeTopologyRuntime[] }} topology
  * @property {{ id?: string, module?: string, export?: string, implementation_module?: string, implementation_export?: string }} [implementation]
+ * @property {Record<string, any>} [template]
  */
 
 /**

package/src/reconcile/docs.d.ts

@@ -0,0 +1,8 @@
+export function buildBundleDocDriftSummaries(...args: any[]): any[];
+export function buildBundleDocMetadataPatches(...args: any[]): any[];
+export function applyDocLinkPatchToMarkdown(...args: any[]): string;
+export function applyDocMetadataPatchToMarkdown(...args: any[]): string;
+export function buildDocDriftSummaries(...args: any[]): any[];
+export function buildDocLinkSuggestions(...args: any[]): any[];
+export function buildDocMetadataPatches(...args: any[]): any[];
+export function extractDocMetadata(...args: any[]): any;

package/src/reconcile/journeys.d.ts

@@ -0,0 +1 @@
+export function buildJourneyDrafts(graph: any): any;

package/src/resolver.d.ts

@@ -0,0 +1 @@
+export function resolveWorkspace(ast: any): any;

package/src/runtime-support.js

@@ -0,0 +1,29 @@
+// @ts-check
+
+export const MINIMUM_NODE_MAJOR = 20;
+
+/**
+ * @param {string} version
+ * @returns {{ ok: boolean, major: number, minimum: number, message: string|null }}
+ */
+export function nodeVersionSupport(version = process.versions.node) {
+  const major = Number.parseInt(String(version).split(".")[0] || "0", 10);
+  const ok = Number.isFinite(major) && major >= MINIMUM_NODE_MAJOR;
+  return {
+    ok,
+    major,
+    minimum: MINIMUM_NODE_MAJOR,
+    message: ok ? null : `Topogram requires Node.js ${MINIMUM_NODE_MAJOR}+; current runtime is ${version}.`
+  };
+}
+
+/**
+ * @param {string} [version]
+ * @returns {void}
+ */
+export function assertSupportedNode(version = process.versions.node) {
+  const support = nodeVersionSupport(version);
+  if (!support.ok) {
+    throw new Error(support.message || `Topogram requires Node.js ${MINIMUM_NODE_MAJOR}+.`);
+  }
+}

package/src/sdlc/adopt.d.ts

@@ -0,0 +1 @@
+export function sdlcAdopt(...args: any[]): any;

package/src/sdlc/check.d.ts

@@ -0,0 +1 @@
+export function checkWorkspace(...args: any[]): any;

package/src/sdlc/explain.d.ts

@@ -0,0 +1 @@
+export function explain(...args: any[]): any;

package/src/sdlc/release.d.ts

@@ -0,0 +1 @@
+export function runRelease(...args: any[]): any;

package/src/sdlc/scaffold.d.ts

@@ -0,0 +1 @@
+export function scaffoldNew(...args: any[]): any;

package/src/sdlc/transition.d.ts

@@ -0,0 +1 @@
+export function transitionStatement(...args: any[]): any;

package/src/text-helpers.d.ts

@@ -0,0 +1,6 @@
+export const canonicalCandidateTerm: (value: unknown, options?: { technicalStopwords?: boolean }) => string;
+export const ensureTrailingNewline: (value: string) => string;
+export const extractRankedTerms: (markdown: string, options?: { technicalStopwords?: boolean }) => string[];
+export const idHintify: (value: unknown) => string;
+export const slugify: (value: unknown) => string;
+export const titleCase: (value: unknown) => string;

package/src/text-helpers.js

@@ -0,0 +1,245 @@
+// @ts-check
+
+export const GENERIC_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "into",
+  "your",
+  "their",
+  "have",
+  "will",
+  "when",
+  "where",
+  "what",
+  "which",
+  "then",
+  "than",
+  "been",
+  "being",
+  "does",
+  "each",
+  "just",
+  "also",
+  "through",
+  "about",
+  "because",
+  "after",
+  "before",
+  "under",
+  "over",
+  "still",
+  "they",
+  "them",
+  "there",
+  "these",
+  "those",
+  "more",
+  "most",
+  "some",
+  "only",
+  "very",
+  "same",
+  "much",
+  "many",
+  "other",
+  "used",
+  "using"
+]);
+
+export const TECHNICAL_STOPWORDS = new Set([
+  "readme",
+  "docs",
+  "topogram",
+  "generated",
+  "example",
+  "examples",
+  "app",
+  "apps",
+  "agreement",
+  "api",
+  "artifacts",
+  "bash",
+  "bundle",
+  "bundles",
+  "commands",
+  "compile",
+  "deployment",
+  "deploy",
+  "engine",
+  "environment",
+  "fixtures",
+  "files",
+  "fly",
+  "getting",
+  "implementation",
+  "include",
+  "layout",
+  "local",
+  "migrations",
+  "model",
+  "notes",
+  "npm",
+  "package",
+  "proof",
+  "react",
+  "recommended",
+  "report",
+  "reports",
+  "runnable",
+  "run",
+  "runtime",
+  "scripts",
+  "server",
+  "smoke",
+  "snapshot",
+  "sqlite",
+  "stack",
+  "stages",
+  "started",
+  "state",
+  "sveltekit",
+  "current",
+  "check",
+  "checks",
+  "env",
+  "usage",
+  "web",
+  "workspace"
+]);
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function slugify(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "untitled";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function idHintify(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "") || "untitled";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalCandidateTerm(value) {
+  const normalized = slugify(value);
+  if (normalized.endsWith("ies")) {
+    return `${normalized.slice(0, -3)}y`;
+  }
+  if (normalized === "status" || normalized === "stats") {
+    return normalized;
+  }
+  if (normalized.endsWith("s") && !normalized.endsWith("ss") && !normalized.endsWith("us") && !normalized.endsWith("is")) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function pluralizeCandidateTerm(value) {
+  const normalized = String(value || "");
+  if (!normalized) return "items";
+  const parts = normalized.split("_");
+  const last = parts.pop() || "item";
+  let plural = last;
+  if (last === "stats") {
+    plural = "stats";
+  } else if (last.endsWith("sis")) {
+    plural = `${last.slice(0, -2)}es`;
+  } else if (last.endsWith("y") && !/[aeiou]y$/.test(last)) {
+    plural = `${last.slice(0, -1)}ies`;
+  } else if (/(s|x|z|ch|sh)$/.test(last)) {
+    plural = `${last}es`;
+  } else {
+    plural = `${last}s`;
+  }
+  return [...parts, plural].join("_");
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function titleCase(value) {
+  return String(value || "")
+    .split(/[_\-\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+/**
+ * @param {{ technicalStopwords?: boolean }} [options]
+ * @returns {Set<string>}
+ */
+export function stopwordSet(options = {}) {
+  const includeTechnical = options.technicalStopwords !== false;
+  return new Set([
+    ...GENERIC_STOPWORDS,
+    ...(includeTechnical ? TECHNICAL_STOPWORDS : [])
+  ]);
+}
+
+/**
+ * @param {string} markdown
+ * @param {{ technicalStopwords?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function extractRankedTerms(markdown, options = {}) {
+  const stopwords = stopwordSet(options);
+  const normalized = markdown
+    .replace(/\[[^\]]+\]\([^)]+\)/g, " ")
+    .replace(/\/Users\/[^\s)]+/g, " ")
+    .replace(/https?:\/\/[^\s)]+/g, " ")
+    .replace(/`([^`]+)`/g, " $1 ")
+    .replace(/[_/]/g, " ");
+  const frequency = new Map();
+  const headings = normalized.match(/^#+\s+(.+)$/gm) || [];
+  for (const heading of headings) {
+    for (const word of heading.toLowerCase().match(/\b[a-z][a-z0-9-]{2,}\b/g) || []) {
+      if (stopwords.has(word)) {
+        continue;
+      }
+      frequency.set(word, (frequency.get(word) || 0) + 3);
+    }
+  }
+  for (const word of normalized.toLowerCase().match(/\b[a-z][a-z0-9-]{2,}\b/g) || []) {
+    if (stopwords.has(word)) {
+      continue;
+    }
+    frequency.set(word, (frequency.get(word) || 0) + 1);
+  }
+  return [...frequency.entries()]
+    .sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]))
+    .map(([term]) => term);
+}