@topogram/cli 0.3.64 → 0.3.66

package/src/archive/jsonl.js

@@ -1,7 +1,7 @@
 // Year-bucketed JSONL archive I/O.
 //
-// File layout: `<project-or-topogram-root>/topogram/_archive/{kind}s-{year}.jsonl`
-// or `<topogram-root>/_archive/{kind}s-{year}.jsonl`
+// File layout: `<project-root>/topo/_archive/{kind}s-{year}.jsonl`
+// or `<workspace-root>/_archive/{kind}s-{year}.jsonl`
 // (e.g. `tasks-2026.jsonl`, `bugs-2026.jsonl`).
 //
 // Each line is a self-contained archived statement. The format is JSONL so

package/src/archive/resolver-bridge.js

@@ -1,7 +1,7 @@
 // Bridge between archived JSONL entries and the live resolver graph.
 //
 // At workspace load time the resolver bridge:
-//   1. Walks `topogram/_archive/*.jsonl`
+//   1. Walks the workspace `_archive/*.jsonl`
 //   2. Builds a flat list of frozen entries (each with `archived: true`)
 //   3. Returns `{ entries, byId }` so the caller can merge them into the
 //      registry / graph

package/src/archive/unarchive.js

@@ -19,6 +19,7 @@ import {
   parseArchiveFile,
   rewriteArchiveFile
 } from "./jsonl.js";
+import { resolveTopoRoot } from "../workspace-paths.js";
 
 const REOPEN_STATUSES = {
   bug: "open",
@@ -83,7 +84,7 @@ export function unarchive(workspaceRoot, id, options = {}) {
 
   const { file, entries, entry } = found;
   const reopenStatus = options.status || REOPEN_STATUSES[entry.kind] || "draft";
-  const targetDir = options.targetDir || path.join(workspaceRoot, "topogram", `${entry.kind}s`);
+  const targetDir = options.targetDir || path.join(resolveTopoRoot(workspaceRoot), `${entry.kind}s`);
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
   const targetFile = path.join(targetDir, `${entry.id}.tg`);
 

package/src/catalog/constants.js

@@ -0,0 +1,10 @@
+// @ts-check
+
+export const CATALOG_FILE_NAME = "topograms.catalog.json";
+export const TOPOGRAM_SOURCE_FILE = ".topogram-source.json";
+export const KNOWN_CATALOG_SURFACES = new Set(["web", "api", "database", "native"]);
+export const GITHUB_TOKEN_HOSTS = new Set([
+  "github.com",
+  "api.github.com",
+  "raw.githubusercontent.com"
+]);

package/src/catalog/copy.js

@@ -0,0 +1,65 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { installPackageSpec } from "../new-project.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH, resolvePackageWorkspace } from "../workspace-paths.js";
+import { catalogEntryPackageSpec } from "./entries.js";
+import { copyPath, ensureEmptyDirectory } from "./files.js";
+import { writeTopogramSourceRecord } from "./provenance.js";
+
+/**
+ * @param {any} entry
+ * @param {string} targetPath
+ * @param {{ version?: string|null, catalogSource?: string|null }} [options]
+ * @returns {{ ok: boolean, id: string, kind: "topogram", packageSpec: string, targetPath: string, provenancePath: string, files: string[] }}
+ */
+export function copyCatalogTopogramEntry(entry, targetPath, options = {}) {
+  if (entry.kind !== "topogram") {
+    throw new Error(`Catalog entry '${entry.id}' is a ${entry.kind}, not a topogram.`);
+  }
+  const packageSpec = catalogEntryPackageSpec(entry, options.version || null);
+  const packageRoot = installPackageSpec(packageSpec);
+  const implementationRoot = path.join(packageRoot, "implementation");
+  if (fs.existsSync(implementationRoot)) {
+    throw new Error(
+      `Catalog topogram entry '${entry.id}' package '${packageSpec}' contains implementation/, which is not allowed for v1 topogram entries.`
+    );
+  }
+  const packageWorkspace = resolvePackageWorkspace(packageRoot);
+
+  const resolvedTarget = path.resolve(targetPath);
+  ensureEmptyDirectory(resolvedTarget);
+  /** @type {string[]} */
+  const files = [];
+  copyPath(packageWorkspace.root, path.join(resolvedTarget, DEFAULT_TOPO_FOLDER_NAME), DEFAULT_TOPO_FOLDER_NAME, files);
+  for (const fileName of ["topogram.project.json", "README.md"]) {
+    const sourcePath = path.join(packageRoot, fileName);
+    if (fs.existsSync(sourcePath) && fs.statSync(sourcePath).isFile()) {
+      if (fileName === "topogram.project.json") {
+        const projectConfig = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+        projectConfig.workspace = DEFAULT_WORKSPACE_PATH;
+        fs.writeFileSync(path.join(resolvedTarget, fileName), `${JSON.stringify(projectConfig, null, 2)}\n`, "utf8");
+        files.push(fileName);
+      } else {
+        copyPath(sourcePath, path.join(resolvedTarget, fileName), fileName, files);
+      }
+    }
+  }
+  const provenance = writeTopogramSourceRecord(resolvedTarget, {
+    catalogSource: options.catalogSource || null,
+    entry,
+    packageSpec,
+    version: options.version || entry.defaultVersion
+  });
+  return {
+    ok: true,
+    id: entry.id,
+    kind: "topogram",
+    packageSpec,
+    targetPath: resolvedTarget,
+    provenancePath: provenance.path,
+    files: files.sort((a, b) => a.localeCompare(b))
+  };
+}

package/src/catalog/diagnostics.js

@@ -0,0 +1,15 @@
+// @ts-check
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {{ code: string, severity: "error"|"warning", message: string, path: string|null, suggestedFix: string|null }}
+ */
+export function catalogDiagnostic(input) {
+  return {
+    code: String(input.code || "catalog_invalid"),
+    severity: input.severity === "warning" ? "warning" : "error",
+    message: String(input.message || "Catalog is invalid."),
+    path: typeof input.path === "string" ? input.path : null,
+    suggestedFix: typeof input.suggestedFix === "string" ? input.suggestedFix : null
+  };
+}

package/src/catalog/entries.js

@@ -0,0 +1,42 @@
+// @ts-check
+
+/**
+ * @param {any} catalog
+ * @param {string} id
+ * @param {"template"|"topogram"|null} [kind]
+ * @returns {any|null}
+ */
+export function findCatalogEntry(catalog, id, kind = null) {
+  return catalog.entries.find((/** @type {any} */ entry) => entry.id === id && (!kind || entry.kind === kind)) || null;
+}
+
+/**
+ * @param {any} entry
+ * @param {string|null|undefined} version
+ * @returns {string}
+ */
+export function catalogEntryPackageSpec(entry, version = null) {
+  return `${entry.package}@${version || entry.defaultVersion}`;
+}
+
+/**
+ * @param {any} entry
+ * @returns {any}
+ */
+export function catalogTemplateListItem(entry) {
+  return {
+    id: entry.id,
+    version: entry.defaultVersion,
+    source: "catalog",
+    name: entry.id,
+    package: entry.package,
+    defaultVersion: entry.defaultVersion,
+    description: entry.description,
+    tags: entry.tags,
+    ...(entry.surfaces ? { surfaces: entry.surfaces } : {}),
+    ...(entry.generators ? { generators: entry.generators } : {}),
+    ...(entry.stack ? { stack: entry.stack } : {}),
+    includesExecutableImplementation: entry.trust.includesExecutableImplementation,
+    trust: entry.trust
+  };
+}

package/src/catalog/files.js

@@ -0,0 +1,67 @@
+// @ts-check
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} currentPath
+ * @param {string} relativePath
+ * @param {string[]} files
+ * @returns {void}
+ */
+export function collectFiles(currentPath, relativePath, files) {
+  const stat = fs.statSync(currentPath);
+  if (stat.isFile()) {
+    files.push(relativePath.replace(/\\/g, "/"));
+    return;
+  }
+  if (!stat.isDirectory()) {
+    return;
+  }
+  for (const entry of fs.readdirSync(currentPath)) {
+    collectFiles(path.join(currentPath, entry), path.join(relativePath, entry), files);
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {{ sha256: string, size: number }}
+ */
+export function fileHash(filePath) {
+  const bytes = fs.readFileSync(filePath);
+  return {
+    sha256: crypto.createHash("sha256").update(bytes).digest("hex"),
+    size: bytes.length
+  };
+}
+
+/**
+ * @param {string} targetPath
+ * @returns {void}
+ */
+export function ensureEmptyDirectory(targetPath) {
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    return;
+  }
+  if (!fs.statSync(targetPath).isDirectory()) {
+    throw new Error(`Cannot copy catalog topogram into non-directory path '${targetPath}'.`);
+  }
+  const entries = fs.readdirSync(targetPath).filter((/** @type {string} */ entry) => entry !== ".DS_Store");
+  if (entries.length > 0) {
+    throw new Error(`Refusing to copy catalog topogram into non-empty directory '${targetPath}'.`);
+  }
+}
+
+/**
+ * @param {string} sourcePath
+ * @param {string} targetPath
+ * @param {string} relativePath
+ * @param {string[]} files
+ * @returns {void}
+ */
+export function copyPath(sourcePath, targetPath, relativePath, files) {
+  fs.cpSync(sourcePath, targetPath, { recursive: true });
+  collectFiles(targetPath, relativePath, files);
+}

package/src/catalog/provenance.js

@@ -0,0 +1,123 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { TOPOGRAM_SOURCE_FILE } from "./constants.js";
+import { collectFiles, fileHash } from "./files.js";
+import { DEFAULT_TOPO_FOLDER_NAME } from "../workspace-paths.js";
+
+/**
+ * @param {string} projectRoot
+ * @param {{ catalogSource: string|null, entry: any, packageSpec: string, version: string }} input
+ * @returns {{ path: string, record: Record<string, any> }}
+ */
+export function writeTopogramSourceRecord(projectRoot, input) {
+  const record = {
+    version: "0.1",
+    kind: "topogram",
+    copiedAt: new Date().toISOString(),
+    catalog: {
+      id: input.entry.id,
+      source: input.catalogSource
+    },
+    package: {
+      name: input.entry.package,
+      version: input.version,
+      spec: input.packageSpec
+    },
+    trust: {
+      includesExecutableImplementation: false
+    },
+    files: collectSourceFileRecords(projectRoot)
+  };
+  const sourcePath = path.join(projectRoot, TOPOGRAM_SOURCE_FILE);
+  fs.writeFileSync(sourcePath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return { path: sourcePath, record };
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ ok: true, exists: boolean, path: string, status: "missing"|"clean"|"changed", source: Record<string, any>|null, content: { changed: string[], added: string[], removed: string[] }, diagnostics: any[], errors: [] }}
+ */
+export function buildTopogramSourceStatus(projectRoot) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const sourcePath = path.join(resolvedRoot, TOPOGRAM_SOURCE_FILE);
+  if (!fs.existsSync(sourcePath)) {
+    return {
+      ok: true,
+      exists: false,
+      path: sourcePath,
+      status: "missing",
+      source: null,
+      content: { changed: [], added: [], removed: [] },
+      diagnostics: [{
+        code: "topogram_source_missing",
+        severity: "warning",
+        message: `${TOPOGRAM_SOURCE_FILE} was not found. This project may not have been copied from a catalog topogram entry.`,
+        path: sourcePath,
+        suggestedFix: "Run `topogram catalog copy <id> <target>` to create a project with source provenance."
+      }],
+      errors: []
+    };
+  }
+  const source = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+  const trustedFiles = Array.isArray(source.files) ? source.files : [];
+  const trustedByPath = new Map(trustedFiles.map((/** @type {any} */ file) => [String(file.path), file]));
+  const currentByPath = new Map(collectSourceFileRecords(resolvedRoot).map((file) => [file.path, file]));
+  /** @type {string[]} */
+  const changed = [];
+  /** @type {string[]} */
+  const added = [];
+  /** @type {string[]} */
+  const removed = [];
+  for (const [filePath, current] of currentByPath) {
+    const trusted = trustedByPath.get(filePath);
+    if (!trusted) {
+      added.push(filePath);
+    } else if (trusted.sha256 !== current.sha256 || trusted.size !== current.size) {
+      changed.push(filePath);
+    }
+  }
+  for (const filePath of trustedByPath.keys()) {
+    if (!currentByPath.has(filePath)) {
+      removed.push(filePath);
+    }
+  }
+  const content = {
+    changed: changed.sort((a, b) => a.localeCompare(b)),
+    added: added.sort((a, b) => a.localeCompare(b)),
+    removed: removed.sort((a, b) => a.localeCompare(b))
+  };
+  return {
+    ok: true,
+    exists: true,
+    path: sourcePath,
+    status: content.changed.length || content.added.length || content.removed.length ? "changed" : "clean",
+    source,
+    content,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Array<{ path: string, sha256: string, size: number }>}
+ */
+function collectSourceFileRecords(projectRoot) {
+  /** @type {string[]} */
+  const files = [];
+  for (const sourceRoot of [DEFAULT_TOPO_FOLDER_NAME, "topogram.project.json", "README.md"]) {
+    const sourcePath = path.join(projectRoot, sourceRoot);
+    if (fs.existsSync(sourcePath)) {
+      collectFiles(sourcePath, sourceRoot, files);
+    }
+  }
+  return files
+    .sort((a, b) => a.localeCompare(b))
+    .map((relativePath) => ({
+      path: relativePath,
+      ...fileHash(path.join(projectRoot, relativePath))
+    }));
+}

package/src/catalog/source.js

@@ -0,0 +1,150 @@
+// @ts-check
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { readGithubCatalogSourceText } from "../github-client.js";
+import { defaultCatalogSource } from "../topogram-config.js";
+import { GITHUB_TOKEN_HOSTS } from "./constants.js";
+import { validateCatalog } from "./validation.js";
+
+const FETCH_URL_SCRIPT = `
+const source = process.argv[1];
+const token = process.env.TOPOGRAM_FETCH_TOKEN || "";
+const tokenHosts = new Set(["github.com", "api.github.com", "raw.githubusercontent.com"]);
+function tokenAllowed(url) {
+  const hostname = new URL(url).hostname.toLowerCase();
+  return tokenHosts.has(hostname) || hostname.endsWith(".github.com");
+}
+async function readUrl(url, redirects = 0) {
+  if (redirects > 5) {
+    throw new Error("Too many redirects.");
+  }
+  const headers = {};
+  if (token && tokenAllowed(url)) {
+    headers.authorization = "Bearer " + token;
+  }
+  const response = await fetch(url, { headers, redirect: "manual" });
+  if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+    const next = new URL(response.headers.get("location"), url).toString();
+    return readUrl(next, redirects + 1);
+  }
+  const text = await response.text();
+  if (!response.ok) {
+    const preview = text.trim().slice(0, 400);
+    throw new Error(String(response.status) + " " + response.statusText + (preview ? "\\n" + preview : ""));
+  }
+  return text;
+}
+try {
+  process.stdout.write(await readUrl(source));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+`;
+
+/**
+ * @param {string|undefined|null} source
+ * @returns {string}
+ */
+export function catalogSourceOrDefault(source = null) {
+  return source || process.env.TOPOGRAM_CATALOG_SOURCE || defaultCatalogSource();
+}
+
+/**
+ * @param {string|undefined|null} source
+ * @returns {boolean}
+ */
+export function isCatalogSourceDisabled(source) {
+  const normalized = String(source || "").trim().toLowerCase();
+  return normalized === "none" || normalized === "off" || normalized === "false";
+}
+
+/**
+ * @param {string|undefined|null} sourceInput
+ * @returns {{ source: string, catalog: any, diagnostics: any[] }}
+ */
+export function loadCatalog(sourceInput = null) {
+  const source = catalogSourceOrDefault(sourceInput);
+  if (isCatalogSourceDisabled(source)) {
+    throw new Error("Catalog source is disabled.");
+  }
+  const text = readCatalogText(source);
+  const parsed = JSON.parse(text);
+  const validation = validateCatalog(parsed, source);
+  if (!validation.ok || !validation.catalog) {
+    throw new Error(validation.errors.join("\n") || `Catalog '${source}' is invalid.`);
+  }
+  return {
+    source,
+    catalog: validation.catalog,
+    diagnostics: validation.diagnostics
+  };
+}
+
+/**
+ * @param {string} source
+ * @returns {{ source: string, ok: boolean, catalog: any|null, diagnostics: any[], errors: string[] }}
+ */
+export function checkCatalogSource(source) {
+  const text = readCatalogText(source);
+  const parsed = JSON.parse(text);
+  return {
+    source,
+    ...validateCatalog(parsed, source)
+  };
+}
+
+/**
+ * @param {string} source
+ * @returns {string}
+ */
+function readCatalogText(source) {
+  if (source.startsWith("github:")) {
+    return readGithubCatalogSourceText(source);
+  }
+  if (source.startsWith("https://") || source.startsWith("http://")) {
+    return readUrlText(source);
+  }
+  const resolvedPath = path.resolve(source);
+  return fs.readFileSync(resolvedPath, "utf8");
+}
+
+/**
+ * @param {string} source
+ * @returns {string}
+ */
+function readUrlText(source) {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+  const tokenEnv = token && githubTokenAllowedForCatalogUrl(source)
+    ? { TOPOGRAM_FETCH_TOKEN: token }
+    : {};
+  const result = childProcess.spawnSync(process.execPath, ["--input-type=module", "-e", FETCH_URL_SCRIPT, source], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      ...tokenEnv,
+      PATH: process.env.PATH || ""
+    }
+  });
+  if (result.status !== 0) {
+    const reason = result.error?.message || result.stderr || result.stdout || "unknown error";
+    throw new Error(`Failed to read catalog URL '${source}'.\n${reason}`.trim());
+  }
+  return result.stdout;
+}
+
+/**
+ * @param {string} source
+ * @returns {boolean}
+ */
+function githubTokenAllowedForCatalogUrl(source) {
+  try {
+    const hostname = new URL(source).hostname.toLowerCase();
+    return GITHUB_TOKEN_HOSTS.has(hostname) || hostname.endsWith(".github.com");
+  } catch {
+    return false;
+  }
+}