@topogram/cli 0.3.34

package/src/archive/archive.js

@@ -0,0 +1,141 @@
+// Archive: move a terminal-status statement out of the active workspace
+// and into a year-bucketed JSONL file.
+//
+// Strategy:
+//   1. Validate the statement is in a status eligible for archiving.
+//   2. Build the archive entry (frozen snapshot + transitions).
+//   3. Append to `_archive/{kind}s-{year}.jsonl`.
+//   4. Surgically remove the statement block from its source `.tg` file.
+//
+// `archiveBatch` is the bulk counterpart used by `release`.
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import path from "node:path";
+
+import { parsePath } from "../parser.js";
+import { resolveWorkspace } from "../resolver/index.js";
+import { isArchivableStatus } from "../sdlc/transitions/index.js";
+import { readHistory } from "../sdlc/history.js";
+import { appendEntry } from "./jsonl.js";
+import { buildArchiveEntry, isArchivableKind } from "./schema.js";
+
+function findAstStatement(ast, id) {
+  for (const file of ast.files) {
+    for (const statement of file.statements) {
+      if (statement.id === id) {
+        return { file, statement };
+      }
+    }
+  }
+  return null;
+}
+
+function removeStatementBlock(source, statement) {
+  // The statement runs from `loc.start.offset` to `loc.end.offset`. Trim
+  // any leading whitespace on the same line and any trailing newline.
+  let start = statement.loc.start.offset;
+  let end = statement.loc.end.offset;
+  while (start > 0 && (source[start - 1] === " " || source[start - 1] === "\t")) {
+    start -= 1;
+  }
+  while (end < source.length && (source[end] === " " || source[end] === "\t")) {
+    end += 1;
+  }
+  if (source[end] === "\n") end += 1;
+  while (start > 0 && source[start - 1] === "\n" && source[start - 2] === "\n") {
+    start -= 1;
+  }
+  return source.slice(0, start) + source.slice(end);
+}
+
+export function archiveStatement(workspaceRoot, id, options = {}) {
+  const ast = parsePath(workspaceRoot);
+  const resolved = resolveWorkspace(ast);
+  if (!resolved.ok) {
+    return { ok: false, error: "workspace failed validation; cannot archive", validation: resolved.validation };
+  }
+
+  const located = findAstStatement(ast, id);
+  if (!located) return { ok: false, error: `Statement '${id}' not found` };
+
+  const { statement: astStatement } = located;
+  const resolvedStatement = resolved.graph.statements.find((s) => s.id === id);
+  if (!resolvedStatement) return { ok: false, error: `Statement '${id}' not in resolved graph` };
+
+  if (!isArchivableKind(resolvedStatement.kind)) {
+    return { ok: false, error: `Kind '${resolvedStatement.kind}' is not archivable` };
+  }
+  if (!isArchivableStatus(resolvedStatement.kind, resolvedStatement.status) && !options.force) {
+    return {
+      ok: false,
+      error: `Status '${resolvedStatement.status}' is not archive-eligible for ${resolvedStatement.kind}`
+    };
+  }
+
+  const history = readHistory(workspaceRoot);
+  const transitions = (history[id] || []).slice();
+  const entry = buildArchiveEntry(resolvedStatement, transitions, {
+    by: options.by,
+    release: options.release,
+    reason: options.reason
+  });
+
+  if (options.dryRun) {
+    return {
+      ok: true,
+      id,
+      kind: resolvedStatement.kind,
+      status: resolvedStatement.status,
+      file: astStatement.loc.file,
+      dryRun: true,
+      entry
+    };
+  }
+
+  const archiveFile = appendEntry(workspaceRoot, resolvedStatement.kind, entry);
+
+  const sourcePath = astStatement.loc.file;
+  const original = readFileSync(sourcePath, "utf8");
+  const rewritten = removeStatementBlock(original, astStatement);
+  if (rewritten.trim().length === 0) {
+    unlinkSync(sourcePath);
+  } else {
+    writeFileSync(sourcePath, rewritten, "utf8");
+  }
+
+  return {
+    ok: true,
+    id,
+    kind: resolvedStatement.kind,
+    status: resolvedStatement.status,
+    file: sourcePath,
+    archiveFile,
+    dryRun: false
+  };
+}
+
+export function archiveBatch(workspaceRoot, ids, options = {}) {
+  const results = [];
+  for (const id of ids) {
+    results.push(archiveStatement(workspaceRoot, id, options));
+  }
+  return {
+    ok: results.every((r) => r.ok),
+    results
+  };
+}
+
+export function archiveEligibleStatements(resolved, options = {}) {
+  const beforeIso = options.before || null;
+  const wantStatuses = options.statuses ? new Set(options.statuses) : null;
+  const eligible = [];
+  for (const s of resolved.graph.statements) {
+    if (s.archived) continue;
+    if (!isArchivableKind(s.kind)) continue;
+    if (!isArchivableStatus(s.kind, s.status)) continue;
+    if (wantStatuses && !wantStatuses.has(s.status)) continue;
+    if (beforeIso && s.updated && s.updated > beforeIso) continue;
+    eligible.push(s.id);
+  }
+  return eligible;
+}

package/src/archive/compact.js

@@ -0,0 +1,26 @@
+// Compact a JSONL archive file into pretty-printed JSON for inspection.
+//
+// Reverse operation `expand` is intentionally absent — JSONL is the
+// canonical on-disk format because it supports append-only growth without
+// re-serialization.
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { parseArchiveFile } from "./jsonl.js";
+
+export function compact(jsonlPath, outputPath) {
+  if (!existsSync(jsonlPath)) {
+    return { ok: false, error: `File not found: ${jsonlPath}` };
+  }
+  const entries = parseArchiveFile(jsonlPath);
+  const errors = entries.filter((e) => e.__error).map((e) => e.__error);
+  const valid = entries.filter((e) => !e.__error);
+  const out = outputPath || jsonlPath.replace(/\.jsonl$/, ".json");
+  writeFileSync(out, JSON.stringify(valid, null, 2) + "\n", "utf8");
+  return {
+    ok: true,
+    inputFile: jsonlPath,
+    outputFile: out,
+    count: valid.length,
+    errors
+  };
+}

package/src/archive/jsonl.js

@@ -0,0 +1,70 @@
+// 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`
+// (e.g. `tasks-2026.jsonl`, `bugs-2026.jsonl`).
+//
+// Each line is a self-contained archived statement. The format is JSONL so
+// archives can grow append-only without requiring a full rewrite.
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { topogramRootForSdlc } from "../sdlc/paths.js";
+
+const ARCHIVE_DIR = "_archive";
+
+export function archiveDir(workspaceRoot) {
+  return path.join(topogramRootForSdlc(workspaceRoot), ARCHIVE_DIR);
+}
+
+export function archiveFileFor(workspaceRoot, kind, year) {
+  return path.join(archiveDir(workspaceRoot), `${kind}s-${year}.jsonl`);
+}
+
+function ensureArchiveDir(workspaceRoot) {
+  const dir = archiveDir(workspaceRoot);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function listArchiveFiles(workspaceRoot) {
+  const dir = archiveDir(workspaceRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".jsonl"))
+    .map((name) => path.join(dir, name));
+}
+
+export function parseArchiveFile(filePath) {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf8");
+  const entries = [];
+  let lineNo = 0;
+  for (const line of content.split(/\r?\n/)) {
+    lineNo += 1;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch (err) {
+      entries.push({
+        __error: `${path.basename(filePath)}:${lineNo}: ${err.message}`
+      });
+    }
+  }
+  return entries;
+}
+
+export function appendEntry(workspaceRoot, kind, entry) {
+  ensureArchiveDir(workspaceRoot);
+  const year = (entry.archived?.at || new Date().toISOString()).slice(0, 4);
+  const file = archiveFileFor(workspaceRoot, kind, year);
+  appendFileSync(file, JSON.stringify(entry) + "\n", "utf8");
+  return file;
+}
+
+export function rewriteArchiveFile(filePath, entries) {
+  const lines = entries.map((entry) => JSON.stringify(entry)).join("\n");
+  writeFileSync(filePath, lines + (lines.length > 0 ? "\n" : ""), "utf8");
+}

package/src/archive/resolver-bridge.js

@@ -0,0 +1,82 @@
+// Bridge between archived JSONL entries and the live resolver graph.
+//
+// At workspace load time the resolver bridge:
+//   1. Walks `topogram/_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
+//
+// Frozen entries participate in cross-references and the traceability
+// matrix but are filtered out of slices and boards by default.
+
+import path from "node:path";
+import { listArchiveFiles, parseArchiveFile } from "./jsonl.js";
+
+function kindFromFilename(filePath) {
+  // tasks-2026.jsonl → task
+  const base = path.basename(filePath, ".jsonl");
+  const dashIndex = base.lastIndexOf("-");
+  if (dashIndex < 0) return null;
+  const plural = base.slice(0, dashIndex);
+  if (plural.endsWith("s")) return plural.slice(0, -1);
+  return plural;
+}
+
+export function loadArchive(workspaceRoot) {
+  const entries = [];
+  const errors = [];
+  for (const file of listArchiveFiles(workspaceRoot)) {
+    const expectedKind = kindFromFilename(file);
+    for (const raw of parseArchiveFile(file)) {
+      if (raw.__error) {
+        errors.push(raw.__error);
+        continue;
+      }
+      if (expectedKind && raw.kind && raw.kind !== expectedKind) {
+        errors.push(`${file}: entry id='${raw.id}' has kind '${raw.kind}', expected '${expectedKind}'`);
+        continue;
+      }
+      entries.push(normalizeArchivedEntry(raw));
+    }
+  }
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  return { entries, byId, errors };
+}
+
+function normalizeArchivedEntry(raw) {
+  const fields = raw.fields && typeof raw.fields === "object" && !Array.isArray(raw.fields) ? raw.fields : {};
+  return {
+    ...fields,
+    ...raw,
+    fields,
+    archived: true,
+    archivedMeta: raw.archived || {},
+    updated: raw.updated || fields.updated || raw.archived?.at || null
+  };
+}
+
+export function mergeArchivedIntoGraph(graph, archive) {
+  // Only insert entries whose id isn't already present in the live graph
+  // (active workspace wins; an unarchived entry shadows the frozen one).
+  const liveIds = new Set(graph.statements.map((s) => s.id));
+  const merged = [...graph.statements];
+  for (const entry of archive.entries) {
+    if (!liveIds.has(entry.id)) {
+      merged.push(entry);
+    }
+  }
+  return {
+    ...graph,
+    statements: merged,
+    byKind: groupByKind(merged)
+  };
+}
+
+function groupByKind(statements) {
+  const map = new Map();
+  for (const s of statements) {
+    if (!map.has(s.kind)) map.set(s.kind, []);
+    map.get(s.kind).push(s);
+  }
+  return Object.fromEntries(map);
+}

package/src/archive/schema.js

@@ -0,0 +1,87 @@
+// Archive entry schema.
+//
+// An archived statement is a frozen snapshot of the resolved statement at
+// the time of archiving, plus:
+//   - `transitions`: full history (copied from the sidecar)
+//   - `archived`: { at, by, release, reason }
+//   - `archived: true` flag (for resolver-bridge's quick filter)
+//
+// Documents archive includes the body verbatim.
+
+const ALLOWED_KINDS = new Set(["pitch", "task", "bug", "document"]);
+
+export function isArchivableKind(kind) {
+  return ALLOWED_KINDS.has(kind);
+}
+
+export function buildArchiveEntry(statement, transitions, archivedMeta = {}) {
+  if (!isArchivableKind(statement.kind)) {
+    throw new Error(`Kind '${statement.kind}' is not archivable`);
+  }
+  return {
+    id: statement.id,
+    kind: statement.kind,
+    name: statement.name,
+    description: statement.description,
+    status: statement.status,
+    fields: statement.archivedFields || serializeFields(statement),
+    transitions: transitions || [],
+    archived: {
+      at: archivedMeta.at || new Date().toISOString(),
+      by: archivedMeta.by || null,
+      release: archivedMeta.release || null,
+      reason: archivedMeta.reason || null
+    }
+  };
+}
+
+// Serialize a normalized resolved statement into a portable field map. We
+// drop `loc`, `ast`, and resolver-derived back-link arrays (they'd be stale
+// once frozen).
+function serializeFields(statement) {
+  const skip = new Set([
+    "kind",
+    "id",
+    "name",
+    "description",
+    "status",
+    "loc",
+    "from",
+    "transformGraph",
+    "members",
+    "policy",
+    "plan",
+    "monitoring",
+    "vocabulary",
+    "componentContract",
+    "record",
+    "flow",
+    "affectedByPitches",
+    "affectedByRequirements",
+    "affectedByTasks",
+    "affectedByBugs",
+    "introducedByRequirements",
+    "respectedByRequirements",
+    "violatedByBugs",
+    "surfacedByBugs",
+    "introducedByTasks",
+    "verifiedBy",
+    "blockingMe",
+    "blockedByMe",
+    "tasks",
+    "verifications",
+    "documents",
+    "rules",
+    "acceptanceCriteria",
+    "supersededBy",
+    "decisionsFromPitch",
+    "requirements",
+    "projectedFields"
+  ]);
+  const out = {};
+  for (const [key, value] of Object.entries(statement)) {
+    if (skip.has(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}

package/src/archive/unarchive.js

@@ -0,0 +1,108 @@
+// Unarchive: pull a frozen entry back into the active workspace.
+//
+// Strategy:
+//   1. Find the entry across all archive files (kind+id).
+//   2. Render it as a `.tg` statement and append to a target file.
+//   3. Strip the entry from the archive file (rewrite without it).
+//
+// Status is reset to a sensible "re-opened" value per kind:
+//   - bug: open
+//   - task: claimed (caller must set claimed_by)
+//   - pitch: draft
+//   - document: draft
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import {
+  archiveDir,
+  listArchiveFiles,
+  parseArchiveFile,
+  rewriteArchiveFile
+} from "./jsonl.js";
+
+const REOPEN_STATUSES = {
+  bug: "open",
+  task: "claimed",
+  pitch: "draft",
+  document: "draft"
+};
+
+function findEntry(workspaceRoot, id) {
+  for (const file of listArchiveFiles(workspaceRoot)) {
+    const entries = parseArchiveFile(file);
+    const match = entries.find((e) => e.id === id);
+    if (match) return { file, entries, entry: match };
+  }
+  return null;
+}
+
+function renderStatement(entry, newStatus) {
+  // Render a minimal `.tg` representation. Unknown field types fall back to
+  // a string. Lists are space-separated symbols inside `[ ... ]`.
+  const lines = [];
+  lines.push(`${entry.kind} ${entry.id} {`);
+  if (entry.name) lines.push(`  name "${entry.name.replace(/"/g, "\\\"")}"`);
+  if (entry.description) lines.push(`  description "${entry.description.replace(/"/g, "\\\"")}"`);
+  for (const [key, value] of Object.entries(entry.fields || {})) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      const items = value
+        .map((v) => (typeof v === "string" ? v : v?.id))
+        .filter(Boolean);
+      if (items.length > 0) {
+        lines.push(`  ${snakeCase(key)} [${items.join(", ")}]`);
+      }
+      continue;
+    }
+    if (typeof value === "object" && value.id) {
+      lines.push(`  ${snakeCase(key)} ${value.id}`);
+      continue;
+    }
+    if (typeof value === "string") {
+      lines.push(`  ${snakeCase(key)} "${value.replace(/"/g, "\\\"")}"`);
+      continue;
+    }
+    if (typeof value === "boolean" || typeof value === "number") {
+      lines.push(`  ${snakeCase(key)} ${value}`);
+    }
+  }
+  lines.push(`  status ${newStatus}`);
+  lines.push("}");
+  return lines.join("\n") + "\n";
+}
+
+function snakeCase(camel) {
+  return camel.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
+}
+
+export function unarchive(workspaceRoot, id, options = {}) {
+  const found = findEntry(workspaceRoot, id);
+  if (!found) {
+    return { ok: false, error: `No archived entry with id '${id}'` };
+  }
+
+  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`);
+  if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
+  const targetFile = path.join(targetDir, `${entry.id}.tg`);
+
+  if (existsSync(targetFile)) {
+    return { ok: false, error: `Target file '${targetFile}' already exists; refuse to overwrite` };
+  }
+
+  const rendered = renderStatement(entry, reopenStatus);
+  writeFileSync(targetFile, rendered, "utf8");
+
+  const remaining = entries.filter((e) => e.id !== id);
+  rewriteArchiveFile(file, remaining);
+
+  return {
+    ok: true,
+    id,
+    kind: entry.kind,
+    targetFile,
+    archiveFile: file,
+    reopenStatus
+  };
+}