doctrina-cli 0.1.0

package/src/lib/colors.js

@@ -0,0 +1,31 @@
+// ANSI colour helpers. Falls back to plain text when:
+//   - stdout is not a TTY, OR
+//   - the NO_COLOR environment variable is set (any value), OR
+//   - the FORCE_COLOR variable is "0".
+//
+// Reference for NO_COLOR: https://no-color.org/
+
+import process from "node:process";
+
+const enabled = (() => {
+  if (process.env.NO_COLOR !== undefined) return false;
+  if (process.env.FORCE_COLOR === "0") return false;
+  if (process.env.FORCE_COLOR !== undefined) return true;
+  return Boolean(process.stdout.isTTY);
+})();
+
+function wrap(open, close) {
+  return (s) => (enabled ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+}
+
+export const c = {
+  enabled,
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  cyan: wrap(36, 39),
+  gray: wrap(90, 39),
+};

package/src/lib/dates.js

@@ -0,0 +1,21 @@
+// Date helpers. Single source so the CLI emits consistent YYYY-MM-DD strings.
+
+export function today(now = new Date()) {
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+export function slugify(s) {
+  return String(s)
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function padNumber(n, width = 4) {
+  return String(n).padStart(width, "0");
+}

package/src/lib/fs-ops.js

@@ -0,0 +1,75 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, renameSync, unlinkSync, rmdirSync } from "node:fs";
+import path from "node:path";
+
+export function read(p) {
+  return readFileSync(p, "utf8");
+}
+
+export function write(p, content, { force = false } = {}) {
+  if (existsSync(p) && !force) {
+    throw new Error(`refusing to overwrite existing file: ${p} (pass --force to allow)`);
+  }
+  mkdirSync(path.dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+export function exists(p) {
+  return existsSync(p);
+}
+
+export function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function mkdirp(p) {
+  mkdirSync(p, { recursive: true });
+}
+
+export function move(from, to) {
+  mkdirSync(path.dirname(to), { recursive: true });
+  renameSync(from, to);
+}
+
+export function remove(p) {
+  if (!existsSync(p)) return;
+  if (isDir(p)) {
+    for (const entry of readdirSync(p)) remove(path.join(p, entry));
+    rmdirSync(p);
+  } else {
+    unlinkSync(p);
+  }
+}
+
+// Recursive file walk. Returns absolute paths of every regular file.
+export function walk(root) {
+  const out = [];
+  if (!exists(root)) return out;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      if (isDir(full)) stack.push(full);
+      else if (isFile(full)) out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+export function lineCount(p) {
+  const text = read(p);
+  if (text.length === 0) return 0;
+  return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}

package/src/lib/index-json.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { read, write, exists } from "./fs-ops.js";
+
+const SCHEMA_VERSION = "0.1.0";
+
+export function indexPath(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "index.json");
+}
+
+export function load(projectRoot) {
+  const p = indexPath(projectRoot);
+  if (!exists(p)) {
+    throw new Error(`.doctrina/index.json not found at ${p}`);
+  }
+  const raw = read(p);
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`.doctrina/index.json is not valid JSON: ${err.message}`);
+  }
+}
+
+export function save(projectRoot, index) {
+  const p = indexPath(projectRoot);
+  const text = JSON.stringify(index, null, 2) + "\n";
+  write(p, text, { force: true });
+}
+
+export function blank(projectName, date) {
+  return {
+    $schema_version: SCHEMA_VERSION,
+    project: projectName,
+    framework_version: "0.0.0",
+    last_updated: date,
+    artifacts: {
+      product: {
+        path: ".doctrina/product.md",
+        status: "active",
+        version: "0.1.0",
+        last_updated: date,
+      },
+      specs: [],
+      decisions: [],
+      changes: [],
+      changes_archive: [],
+      skills: [],
+    },
+  };
+}
+
+export function addSkill(index, entry) {
+  if (!index.artifacts.skills) index.artifacts.skills = [];
+  if (!index.artifacts.skills.some((s) => s.id === entry.id)) {
+    index.artifacts.skills.push(entry);
+  }
+  return index;
+}
+
+export function removeSkill(index, id) {
+  if (!index.artifacts.skills) return index;
+  index.artifacts.skills = index.artifacts.skills.filter((s) => s.id !== id);
+  return index;
+}
+
+export function touch(index, date) {
+  index.last_updated = date;
+  return index;
+}
+
+export function addSpec(index, entry) {
+  if (!index.artifacts.specs.some((s) => s.id === entry.id)) {
+    index.artifacts.specs.push(entry);
+  }
+  return index;
+}
+
+export function removeSpec(index, id) {
+  index.artifacts.specs = index.artifacts.specs.filter((s) => s.id !== id);
+  return index;
+}
+
+export function addDecision(index, entry) {
+  if (!index.artifacts.decisions.some((d) => d.id === entry.id)) {
+    index.artifacts.decisions.push(entry);
+  }
+  return index;
+}
+
+export function updateDecision(index, id, mutator) {
+  const list = index.artifacts.decisions;
+  const i = list.findIndex((d) => d.id === id);
+  if (i >= 0) list[i] = { ...list[i], ...mutator(list[i]) };
+  return index;
+}
+
+export function addChange(index, entry) {
+  if (!index.artifacts.changes.some((c) => c.id === entry.id)) {
+    index.artifacts.changes.push(entry);
+  }
+  return index;
+}
+
+export function moveChangeToArchive(index, id, archiveEntry) {
+  index.artifacts.changes = index.artifacts.changes.filter((c) => c.id !== id);
+  if (!index.artifacts.changes_archive.some((c) => c.id === id)) {
+    index.artifacts.changes_archive.push(archiveEntry);
+  }
+  return index;
+}

package/src/lib/prompt.js

@@ -0,0 +1,19 @@
+import readline from "node:readline";
+
+export async function ask(question, { defaultValue = "" } = {}) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = defaultValue ? `${question} [${defaultValue}] ` : `${question} `;
+  try {
+    const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+    return answer.trim() || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function confirm(question, { defaultYes = false } = {}) {
+  const suffix = defaultYes ? "Y/n" : "y/N";
+  const ans = await ask(`${question} (${suffix})`);
+  if (!ans) return defaultYes;
+  return /^y(es)?$/i.test(ans);
+}

package/src/lib/suggest.js

@@ -0,0 +1,44 @@
+// Tiny Levenshtein distance + "did you mean" suggester. Zero deps.
+
+export function distance(a, b) {
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+  const m = a.length;
+  const n = b.length;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost,
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+// Return the closest match from `candidates` to `input`, or null
+// when no candidate is close enough.
+export function suggest(input, candidates) {
+  if (!input || !candidates || candidates.length === 0) return null;
+  const inputLower = String(input).toLowerCase();
+  let best = null;
+  let bestD = Infinity;
+  for (const cand of candidates) {
+    const d = distance(inputLower, String(cand).toLowerCase());
+    if (d < bestD) {
+      bestD = d;
+      best = cand;
+    }
+  }
+  // Threshold: at most ceil(len/3), and never more than 3 absolute.
+  const threshold = Math.min(3, Math.ceil(inputLower.length / 3));
+  return bestD <= threshold ? best : null;
+}

package/src/lib/templates.js

@@ -0,0 +1,78 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { read, walk, write } from "./fs-ops.js";
+
+// Resolve the path to the .doctrina/templates/ directory shipped with this
+// package. The package layout is:
+//   packages/doctrina-cli/src/lib/templates.js     (this file)
+//   .doctrina/templates/                            (when running from a source checkout)
+//
+// When installed via npm, the package will ship a copy of templates alongside
+// src/. The resolver below tries the local source first, then a packaged copy.
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export function locateTemplatesDir() {
+  const candidates = [
+    // running from source checkout: ../../../../.doctrina/templates
+    path.resolve(here, "..", "..", "..", "..", ".doctrina", "templates"),
+    // installed package layout: ../../templates
+    path.resolve(here, "..", "..", "templates"),
+  ];
+  for (const candidate of candidates) {
+    try {
+      // statSync via fs-ops without importing it twice
+      const test = path.join(candidate, "README.md");
+      // dynamic check using read (throws if missing)
+      read(test);
+      return candidate;
+    } catch {
+      // try next
+    }
+  }
+  throw new Error(
+    `cannot locate .doctrina/templates/. Tried: ${candidates.join(", ")}`,
+  );
+}
+
+// Single-pass {{TOKEN}} substitution. Tokens are uppercase, digits, or
+// underscore inside double curly braces.
+export function substitute(text, tokens) {
+  return text.replace(/\{\{([A-Z0-9_]+)\}\}/g, (match, name) => {
+    if (Object.prototype.hasOwnProperty.call(tokens, name)) {
+      return String(tokens[name]);
+    }
+    return match;
+  });
+}
+
+// Scan a template body for required tokens (every {{TOKEN}} occurrence).
+export function discoverTokens(text) {
+  const set = new Set();
+  for (const m of text.matchAll(/\{\{([A-Z0-9_]+)\}\}/g)) set.add(m[1]);
+  return [...set].sort();
+}
+
+// Walk a template subdirectory and return an array of
+// { templatePath, relativePath, body } entries, suitable for substitution.
+export function loadTemplateTree(templatesDir, subdir) {
+  const root = path.join(templatesDir, subdir);
+  const files = walk(root);
+  return files.map((templatePath) => {
+    const relativePath = path.relative(root, templatePath);
+    const body = templatePath.endsWith(".gitkeep") ? "" : read(templatePath);
+    return { templatePath, relativePath, body };
+  });
+}
+
+// Materialise a template entry into a destination directory. If the relative
+// path ends in ".template", the suffix is stripped on write.
+export function materialiseEntry(entry, destDir, tokens, opts = {}) {
+  const cleaned = entry.relativePath.replace(/\.template$/, "");
+  const destPath = path.join(destDir, cleaned);
+  const body = entry.templatePath.endsWith(".gitkeep")
+    ? ""
+    : substitute(entry.body, tokens);
+  write(destPath, body, opts);
+  return destPath;
+}