superdev-cli 0.1.0

package/src/model/ids.mjs

@@ -0,0 +1,185 @@
+// Stable, human-readable, typed identifiers.
+//
+// Ids appear in deep links, generated Markdown, commit messages and agent
+// conversation, so they are readable rather than opaque. Uniqueness comes from
+// the primary key: a colliding insert fails and the caller retries with the
+// next number, which is safe because every write is already a transaction.
+
+export const PREFIX = {
+  project: "PRJ",
+  project_scope_item: "SCOPE",
+  glossary_term: "TERM",
+  runtime_piece: "RT",
+  source_material: "SRC",
+  discovery_item: "DIS",
+  question: "Q",
+  goal: "GOAL",
+  goal_success_criterion: "GSC",
+  milestone: "MS",
+  module: "MOD",
+  feature: "FEAT",
+  feature_flow: "FLOW",
+  feature_acceptance_criterion: "AC",
+  feature_edge_case: "EC",
+  workflow: "WF",
+  workflow_actor: "WFA",
+  workflow_step: "STEP",
+  workflow_branch: "BR",
+  state_machine: "SM",
+  state: "ST",
+  state_transition: "STT",
+  surface: "SRF",
+  surface_state: "SRS",
+  ui_action: "ACT",
+  api_operation: "API",
+  data_entity: "ENT",
+  data_field: "FLD",
+  data_relationship: "REL",
+  schema_migration: "MIG",
+  integration: "INT",
+  job: "JOB",
+  webhook: "WH",
+  role: "ROLE",
+  permission: "PERM",
+  non_functional_requirement: "NFR",
+  decision: "DEC",
+  decision_link: "DL",
+  change: "CHG",
+  assumption: "ASM",
+  test_plan: "TP",
+  test_plan_case: "TPC",
+  api_service: "SVC",
+  decision_transition: "DT",
+  document: "DOC",
+  capability_area: "CAP",
+  module_completeness: "MCS",
+  task: "TASK",
+  task_category: "TC",
+  task_assignment: "ASG",
+  developer: "DEV",
+  agent: "AGT",
+  branch: "GBR",
+  work_session: "SES",
+  activity_event: "EVT",
+  verification_evidence: "EV",
+  status_history: "SH",
+  memory_entry: "MEM",
+  memory_link: "ML",
+  sync_peer: "PEER",
+  sync_conflict: "CONF",
+  layout_position: "POS",
+};
+
+const TABLE = {
+  project: "projects",
+  // Added by migration 002. runtime_piece_edges is deliberately absent: it has a
+  // composite primary key and no id column, like the other join tables here.
+  project_scope_item: "project_scope_items",
+  glossary_term: "glossary_terms",
+  runtime_piece: "runtime_pieces",
+  source_material: "source_material",
+  discovery_item: "discovery_items",
+  question: "questions",
+  goal: "goals",
+  goal_success_criterion: "goal_success_criteria",
+  milestone: "milestones",
+  module: "modules",
+  feature: "features",
+  feature_flow: "feature_flows",
+  feature_acceptance_criterion: "feature_acceptance_criteria",
+  feature_edge_case: "feature_edge_cases",
+  workflow: "workflows",
+  workflow_actor: "workflow_actors",
+  workflow_step: "workflow_steps",
+  workflow_branch: "workflow_branches",
+  state_machine: "state_machines",
+  state: "states",
+  state_transition: "state_transitions",
+  surface: "surfaces",
+  surface_state: "surface_states",
+  ui_action: "ui_actions",
+  api_operation: "api_operations",
+  data_entity: "data_entities",
+  data_field: "data_fields",
+  data_relationship: "data_relationships",
+  schema_migration: "schema_migrations",
+  integration: "integrations",
+  job: "jobs",
+  webhook: "webhooks",
+  role: "roles",
+  permission: "permissions",
+  non_functional_requirement: "non_functional_requirements",
+  decision: "decisions",
+  decision_link: "decision_links",
+  change: "changes",
+  assumption: "assumptions",
+  test_plan: "test_plans",
+  test_plan_case: "test_plan_cases",
+  api_service: "api_services",
+  decision_transition: "decision_transitions",
+  document: "documents",
+  capability_area: "capability_areas",
+  module_completeness: "module_completeness",
+  task: "tasks",
+  task_category: "task_categories",
+  task_assignment: "task_assignments",
+  developer: "developers",
+  agent: "agents",
+  branch: "branches",
+  work_session: "work_sessions",
+  activity_event: "activity_events",
+  verification_evidence: "verification_evidence",
+  status_history: "status_history",
+  memory_entry: "memory_entries",
+  memory_link: "memory_links",
+  sync_peer: "sync_peers",
+  sync_conflict: "sync_conflicts",
+  layout_position: "layout_positions",
+};
+
+export const tableFor = (kind) => TABLE[kind];
+
+const PAD = 4;
+
+/** `FEAT-0007`. Sequential per kind, derived from what is already stored. */
+export async function nextId(db, kind) {
+  const prefix = PREFIX[kind];
+  const table = TABLE[kind];
+  if (!prefix || !table) throw new Error(`unknown record kind: ${kind}`);
+  const row = await db.get(
+    `SELECT id FROM ${table} WHERE id LIKE ? ORDER BY length(id) DESC, id DESC LIMIT 1`,
+    `${prefix}-%`,
+  );
+  const last = row ? Number(String(row.id).slice(prefix.length + 1)) : 0;
+  const next = (Number.isFinite(last) ? last : 0) + 1;
+  return `${prefix}-${String(next).padStart(PAD, "0")}`;
+}
+
+export function kindOf(id) {
+  const prefix = String(id).split("-")[0];
+  return Object.keys(PREFIX).find((k) => PREFIX[k] === prefix) ?? null;
+}
+
+export const isId = (value) => typeof value === "string" && /^[A-Z]{1,5}-\d{4,}$/.test(value);
+
+/** URL and filesystem safe slug. Used for module and feature document paths. */
+export function slugify(text, fallback = "item") {
+  const slug = String(text ?? "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return slug || fallback;
+}
+
+export async function uniqueSlug(db, table, projectId, text, fallback) {
+  const base = slugify(text, fallback);
+  let candidate = base;
+  for (let n = 2; n < 500; n++) {
+    const clash = await db.get(`SELECT 1 FROM ${table} WHERE project_id = ? AND slug = ?`, projectId, candidate);
+    if (!clash) return candidate;
+    candidate = `${base}-${n}`;
+  }
+  throw new Error(`could not find a free slug for "${text}"`);
+}

package/src/model/screening.mjs

@@ -0,0 +1,150 @@
+// Content screening applied at the storage boundary, so nothing reaches the
+// database that the project would be embarrassed to generate: no em dash, no
+// emoji, no secret-shaped strings, no absolute home paths, no model reasoning.
+//
+// Enforcement is real and refuses with the exact field, rather than advising.
+
+export const E = {
+  EM_DASH: "E_STYLE_EM_DASH",
+  EMOJI: "E_STYLE_EMOJI",
+  SECRET: "E_SECRET_SHAPED",
+  HOME_PATH: "E_ABSOLUTE_HOME_PATH",
+  REASONING: "E_MODEL_REASONING_FIELD",
+};
+
+export class ScreeningError extends Error {
+  constructor(code, field, message) {
+    super(message);
+    this.name = "ScreeningError";
+    this.code = code;
+    this.field = field;
+  }
+}
+
+/** The character Superdev never generates. Exported so the style scanner, the
+ *  storage boundary and the toolkit all test for the same codepoint. */
+export const EM_DASH = "\u2014";
+const EM_DASH_RE = new RegExp(EM_DASH);
+// What counts as emoji, in one place, so the scanner and the storage boundary
+// cannot disagree. The earlier range list banned the whole Arrows and Dingbats
+// blocks, which made the store refuse an arrow or a check mark while the style
+// validator passed them, and the Docs templates use both. A character in text
+// presentation is text; emoji presentation is the thing being excluded.
+const EMOJI_SOURCE = "\\p{Emoji_Presentation}|\\uFE0F";
+const EMOJI = new RegExp(EMOJI_SOURCE, "u");
+/** The same rule, global, for stripping. A non-global pattern removes one. */
+const EMOJI_ALL = new RegExp(EMOJI_SOURCE, "gu");
+/** Exported so the style validator judges by exactly the rule the store enforces. */
+export const EMOJI_PATTERN = EMOJI_SOURCE;
+
+const HOME_PATH = /(?:^|[\s"'`(=:])(\/(?:Users|home)\/[A-Za-z0-9._-]+|[A-Z]:\\Users\\[A-Za-z0-9._-]+)/;
+
+const SECRET_PATTERNS = [
+  // The separator repeats, and it is either kind. Requiring sixteen unbroken
+  // alphanumerics after a single hyphen matched an OpenAI key of the older
+  // shape and missed every current one: sk-proj-... breaks at the second
+  // hyphen, and every Stripe key (sk_live_..., pk_test_...) uses underscores,
+  // so all three passed screening and would have been stored verbatim.
+  /\b(?:sk|pk|rk)[-_](?:[A-Za-z0-9]+[-_])*[A-Za-z0-9]{16,}\b/,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/,
+  /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+  /\b(?:password|passwd|secret|api[_-]?key|auth[_-]?token|access[_-]?token)\s*[:=]\s*["']?[^\s"']{8,}/i,
+];
+
+/** Fields that would carry private model reasoning. Never stored. */
+const REASONING_FIELDS = new Set([
+  "reasoning", "chain_of_thought", "chainOfThought", "thinking", "thought",
+  "internal_monologue", "scratchpad", "deliberation",
+]);
+
+/**
+ * Personal data shapes. Deliberately NOT part of the storage boundary: a project
+ * record may legitimately name a person, and refusing that would make the tool
+ * unusable. They exist for the outbound path only, where a report or a provider
+ * packet leaves the machine and a name that was fine on disk is a leak in transit.
+ */
+const PII_PATTERNS = [
+  /[A-Za-z0-9._%+-]+@(?!example\.(?:com|org|net))[A-Za-z0-9.-]+\.[A-Za-z]{2,}/,
+  /(?:^|\s)\+?\d{1,3}[-. (]{1,2}\d{3}[-. )]{1,2}\d{3}[-. ]?\d{4}\b/,
+];
+
+export const hasEmDash = (text) => EM_DASH_RE.test(String(text ?? ""));
+export const hasEmoji = (text) => EMOJI.test(String(text ?? ""));
+export const looksSecret = (text) => SECRET_PATTERNS.some((p) => p.test(String(text ?? "")));
+export const looksPersonal = (text) => PII_PATTERNS.some((p) => p.test(String(text ?? "")));
+export const hasHomePath = (text) => HOME_PATH.test(String(text ?? ""));
+
+/** Would this field name become covert storage for model reasoning? */
+export const isReasoningField = (key) => REASONING_FIELDS.has(key);
+
+/**
+ * Rewrite punctuation rather than deleting the sentence. An em dash becomes a
+ * comma or a hyphen depending on how it was used.
+ */
+export function rewriteStyle(text) {
+  if (typeof text !== "string") return text;
+  return text
+    .replace(/\s*\u2014\s*/g, " - ")
+    .replace(/\u2013/g, "-")
+    .replace(EMOJI_ALL, "")
+    .replace(/[ \t]{2,}/g, " ");
+}
+
+/** Replace an absolute home path with a portable placeholder. */
+export const redactHomePaths = (text) =>
+  String(text ?? "")
+    .replace(/\/(?:Users|home)\/[A-Za-z0-9._-]+/g, "~")
+    .replace(/[A-Z]:\\Users\\[A-Za-z0-9._-]+/g, "~");
+
+export function redactSecrets(text) {
+  let out = String(text ?? "");
+  for (const p of SECRET_PATTERNS) out = out.replace(new RegExp(p.source, p.flags.replace("g", "") + "g"), "[redacted]");
+  return out;
+}
+
+/** Throw on anything that must never be stored. Used on every write. */
+export function assertStorable(field, value) {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== "string") return value;
+  if (hasEmDash(value)) {
+    throw new ScreeningError(E.EM_DASH, field,
+      `${field} contains an em dash. Superdev never generates U+2014; use a comma, colon, semicolon, parentheses or a hyphen.`);
+  }
+  if (hasEmoji(value)) {
+    throw new ScreeningError(E.EMOJI, field, `${field} contains emoji, which Superdev never generates.`);
+  }
+  if (looksSecret(value)) {
+    throw new ScreeningError(E.SECRET, field, `${field} looks like it contains a credential. Store a reference, never the value.`);
+  }
+  if (hasHomePath(value)) {
+    throw new ScreeningError(E.HOME_PATH, field,
+      `${field} contains an absolute home path. It names one machine and points nowhere on anyone else's; store a path relative to the project.`);
+  }
+  return value;
+}
+
+/** Screen a whole record before it is written. Returns the record unchanged. */
+export function assertRecordStorable(record, { allow = [] } = {}) {
+  for (const [key, value] of Object.entries(record ?? {})) {
+    if (REASONING_FIELDS.has(key)) {
+      throw new ScreeningError(E.REASONING, key, `${key} would store private model reasoning. Store the observable outcome instead.`);
+    }
+    // `allow` used to cover every column ending in _json, on the theory that
+    // structured data is not prose. None of these rules reacts to braces: an em
+    // dash inside a JSON array is the same character, and it was reaching
+    // generated Markdown through exactly this hole. A caller may still exempt a
+    // named field, but nothing is exempt by virtue of its shape.
+    if (allow.includes(key)) continue;
+    assertStorable(key, value);
+  }
+  return record;
+}
+
+/**
+ * Screen text arriving from a provider or an external file. External content is
+ * evidence, never instruction, so it is sanitized rather than refused.
+ */
+export const sanitizeExternal = (text) => redactSecrets(rewriteStyle(redactHomePaths(text)));

package/src/model/toolkit.mjs

@@ -0,0 +1,258 @@
+/**
+ * Shared safety layer for the command line surfaces.
+ *
+ * Extracted verbatim from the record engine that used to own it, because the
+ * guarantees below are the reason the surrounding commands are safe to run and
+ * rewriting them for tidiness would be a security change disguised as a cleanup:
+ *
+ *  - root confinement: every path an operation touches is validated against the
+ *    project root (absolute inputs rejected, drive letters rejected, ".."
+ *    rejected, symlink escapes rejected) BEFORE any read or write
+ *  - atomic writes: content lands via temp file, fsync, rename, directory fsync,
+ *    so a crash leaves either the old file or the new one, never a torn one
+ *  - deterministic serialization: stable key order and a trailing newline, so
+ *    reruns produce byte-identical files
+ *  - one shared refusal type, so a CLI can tell an expected refusal from a bug
+ *
+ * The screening and writing style rules are NOT implemented here. They live in
+ * screening.mjs, which is the storage boundary, and this file only adapts them
+ * to the shapes the command line callers use (whole structures rather than one
+ * field). Two implementations of "what counts as a secret" is how a rule quietly
+ * stops matching in one of the places it is enforced.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  EM_DASH,
+  isReasoningField,
+  looksPersonal,
+  looksSecret,
+  redactHomePaths,
+  rewriteStyle,
+} from "./screening.mjs";
+
+export class SuperdevError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** Callers written against the previous name keep working unchanged. */
+export { SuperdevError as TalksError };
+
+/** Realpath-safe main-module check (Node realpaths the entry module URL). */
+export function isMain(importMetaUrl) {
+  try {
+    return Boolean(process.argv[1]) && importMetaUrl === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+/** Resolve a project root: must exist, be a directory; returns its realpath. */
+export function resolveRoot(root) {
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+    throw new SuperdevError("E_ROOT", `root is not a directory: ${root}`);
+  return fs.realpathSync(root);
+}
+
+/**
+ * Resolve a project-relative path safely. Rejects absolute paths, drive-letter
+ * paths, ".." segments, resolution outside the root, and symlink escapes of any
+ * existing ancestor. Returns the absolute confined path.
+ */
+export function safeResolve(rootReal, rel) {
+  const v = String(rel);
+  if (path.isAbsolute(v) || /^[A-Za-z]:[\\/]/.test(v))
+    throw new SuperdevError("E_PATH_ABSOLUTE", `absolute path rejected: field-controlled path`);
+  if (v.split(/[\\/]/).some((seg) => seg === ".."))
+    throw new SuperdevError("E_PATH_TRAVERSAL", `path traversal rejected`);
+  const resolved = path.resolve(rootReal, v);
+  if (resolved !== rootReal && !resolved.startsWith(rootReal + path.sep))
+    throw new SuperdevError("E_PATH_OUTSIDE", `path resolves outside root`);
+  // Walk existing ancestors: none may realpath outside the root.
+  let probe = resolved;
+  while (!fs.existsSync(probe)) probe = path.dirname(probe);
+  const real = fs.realpathSync(probe);
+  if (real !== rootReal && !real.startsWith(rootReal + path.sep))
+    throw new SuperdevError("E_PATH_SYMLINK", `symlink escape rejected`);
+  return resolved;
+}
+
+/** Interrupted-migration guard shared by every mutating command. The journal is
+ *  written next to the store it belongs to and removed when the migration
+ *  finishes, so its presence means a migration stopped part way through. */
+export function migrationJournalPath(rootReal) {
+  return path.join(rootReal, ".superdev", ".migration-journal.json");
+}
+
+export function assertNotInterrupted(rootReal) {
+  if (fs.existsSync(migrationJournalPath(rootReal)))
+    throw new SuperdevError(
+      "E_MIGRATION_INTERRUPTED",
+      "an interrupted migration journal exists; complete or restore it before mutating the record"
+    );
+}
+
+/** Deterministic serialization: known keys in declared order first, remaining
+ *  keys alphabetically, 2-space indent, trailing newline. */
+export function stableStringify(value, preferredOrder = []) {
+  const order = (obj) => {
+    if (Array.isArray(obj)) return obj.map(order);
+    if (obj && typeof obj === "object") {
+      // Null prototype + hasOwn: fields named after Object.prototype members
+      // (toString, constructor, __proto__ and the rest) survive serialization intact.
+      const out = Object.create(null);
+      for (const k of preferredOrder) if (Object.hasOwn(obj, k)) out[k] = order(obj[k]);
+      for (const k of Object.keys(obj).sort()) if (!Object.hasOwn(out, k)) out[k] = order(obj[k]);
+      return out;
+    }
+    return obj;
+  };
+  return JSON.stringify(order(value), null, 2) + "\n";
+}
+
+/** Best-effort directory-entry durability (no-op where dirs cannot be fsynced,
+ *  e.g. Windows). Scopes the durability claim: process-crash safety is
+ *  guaranteed by construction; power-loss safety is best-effort via dir fsync. */
+function fsyncDir(dir) {
+  try {
+    const fd = fs.openSync(dir, "r");
+    try {
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    /* platform without directory fsync */
+  }
+}
+
+/** Atomic write: temp file in the target directory, fsync, rename, dir fsync.
+ *  Rename retries on EPERM (Windows: a concurrent reader briefly holding the
+ *  target open makes rename flake; short bounded retry is the known remedy). */
+export function atomicWrite(file, content) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+  const fd = fs.openSync(tmp, "w");
+  try {
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.renameSync(tmp, file);
+      break;
+    } catch (e) {
+      if (e.code === "EPERM" && attempt < 4) {
+        const until = Date.now() + 15;
+        while (Date.now() < until); // bounded busy-wait; sync CLI context
+        continue;
+      }
+      fs.rmSync(tmp, { force: true });
+      throw e;
+    }
+  }
+  fsyncDir(dir);
+}
+
+/** ISO-8601 UTC timestamp, second precision, filename-safe when compacted. */
+export function nowStamp() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** Shared CLI reporting contract (every public CLI):
+ *  - `--out <file>` writes exactly the machine-readable report, deterministic
+ *    JSON with a trailing newline, via the atomic path; no other destination is
+ *    ever invented.
+ *  - absence of --out writes no report file; read-only ops honor --out too.
+ *  - expected failures never print stack traces. */
+export function writeReport(outPath, report) {
+  if (!outPath) return;
+  atomicWrite(outPath, JSON.stringify(report, null, 2) + "\n");
+}
+
+export function usageError(message, usage) {
+  console.error(message);
+  console.error(usage);
+  process.exit(2);
+}
+
+/* ------------------------------------------------------------------ *
+ * Screening and writing style: adapters over screening.mjs
+ * ------------------------------------------------------------------ */
+
+export { EM_DASH };
+
+/** Rewrite prohibited punctuation rather than deleting the sentence around it.
+ *  Used for migration and for provider output, never as a silent fixer on the
+ *  write path: a write that would have been wrong should fail loudly while
+ *  someone can still choose the right punctuation. */
+export const rewriteWritingStyle = rewriteStyle;
+
+const isSensitiveString = (str) => looksSecret(str) || looksPersonal(str);
+
+/** Is any string in this value secret- or personal-shaped? Never returns the value. */
+export function containsSensitive(value) {
+  let hit = false;
+  const walk = (v) => {
+    if (hit) return;
+    if (typeof v === "string") hit = isSensitiveString(v);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (v && typeof v === "object") Object.values(v).forEach(walk);
+  };
+  walk(value);
+  return hit;
+}
+
+/** Redact every sensitive or machine-identifying string in a value, recursively.
+ *  Returns a NEW value; the offending text is replaced, never echoed. Arrays,
+ *  nested objects and object KEYS are all covered. */
+export function redactSensitive(value, { onFinding } = {}) {
+  const redactString = (str) => {
+    if (isSensitiveString(str)) {
+      onFinding?.("sensitive");
+      return "[redacted: sensitive shape]";
+    }
+    const portable = redactHomePaths(str);
+    if (portable !== str) onFinding?.("machine-path");
+    return portable;
+  };
+  const walk = (v) => {
+    if (typeof v === "string") return redactString(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === "object") {
+      const out = {};
+      for (const [k, val] of Object.entries(v)) out[redactString(k)] = walk(val);
+      return out;
+    }
+    return v;
+  };
+  return walk(value);
+}
+
+/** The single shared field-safety gate: reject any secret or personal string AND
+ *  any reasoning-shaped field name, anywhere in the value. Coded refusal that
+ *  NEVER echoes the offending value, so the refusal itself cannot leak it. */
+export function assertSafeField(value, where = "field") {
+  const walk = (v) => {
+    if (typeof v === "string") {
+      if (isSensitiveString(v)) throw new SuperdevError("E_SENSITIVE", `secret or personal content rejected in ${where}`);
+    } else if (Array.isArray(v)) {
+      v.forEach(walk);
+    } else if (v && typeof v === "object") {
+      for (const [k, val] of Object.entries(v)) {
+        if (isReasoningField(k))
+          throw new SuperdevError("E_REASONING_FIELD", `reasoning-shaped field "${k}" rejected in ${where}`);
+        walk(val);
+      }
+    }
+  };
+  walk(value);
+}