@schneiderjoseph/devia 0.1.0

package/src/commands/sync.mjs

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { exists, read, readJSON, writeJSON, walk } from "../lib/fs.mjs";
+import { cliVersion, standardVersion } from "../lib/version.mjs";
+import { vendorStandard, vendorContents } from "../lib/vendor.mjs";
+import { color, heading, status, line } from "../lib/ui.mjs";
+
+export default async function sync(ctx) {
+  const { root, deviaDir, flags } = ctx;
+
+  if (flags.help) {
+    line(`
+${color.bold("devia sync")} — refresh the vendored standard in .devia/standard/
+
+  --root <dir>   repository to sync
+  --dry-run      report what would change, write nothing
+
+The project memory is never touched: sync replaces the pinned copy of the standard only.
+`.trim());
+    return 0;
+  }
+
+  if (!exists(deviaDir)) {
+    status("FAIL", "no .devia/", "run `devia init` first");
+    return 1;
+  }
+
+  const dest = path.join(deviaDir, "standard");
+  const installed = standardVersion();
+  const cli = cliVersion();
+  const config = readJSON(path.join(deviaDir, "devia.json")) || {};
+  const pinned = config.standardVersion;
+
+  heading("devia sync");
+  line(`  ${color.dim("pinned")}     ${pinned || "none"}`);
+  line(`  ${color.dim("installed")}  ${installed || "unknown"}`);
+
+  const before = new Map();
+  for (const rel of walk(dest)) before.set(rel, read(path.join(dest, rel)));
+
+  if (flags["dry-run"]) {
+    let changed = 0;
+    let added = 0;
+    const now = vendorContents();
+    for (const [rel, content] of now) {
+      if (!before.has(rel)) added++;
+      else if (before.get(rel) !== content) changed++;
+    }
+    const removed = [...before.keys()].filter((k) => !now.has(k) && k !== "PINNED.md").length;
+    status("INFO", `would write ${added} new, ${changed} changed, remove ${removed}`);
+    line("");
+    return 0;
+  }
+
+  const files = vendorStandard(dest, {
+    by: "devia sync",
+    cli,
+    standard: installed,
+    date: new Date().toISOString().slice(0, 10),
+  });
+
+  if (config.standardVersion !== installed || config.deviaVersion !== cli) {
+    config.standardVersion = installed;
+    config.deviaVersion = cli;
+    writeJSON(path.join(deviaDir, "devia.json"), config);
+    status("PASS", `pin updated to ${installed}`, `written by devia ${cli}`);
+  }
+
+  const after = new Map();
+  for (const rel of walk(dest)) after.set(rel, read(path.join(dest, rel)));
+  const changed = [...after.keys()].filter((k) => before.has(k) && before.get(k) !== after.get(k));
+  const added = [...after.keys()].filter((k) => !before.has(k));
+  const removed = [...before.keys()].filter((k) => !after.has(k));
+
+  status("PASS", `${files} files vendored`, `v${installed}`);
+  if (added.length) status("INFO", `${added.length} new`, added.slice(0, 5).join(", "));
+  if (changed.length) status("INFO", `${changed.length} changed`, changed.slice(0, 5).join(", "));
+  if (removed.length) status("WARN", `${removed.length} removed`, removed.slice(0, 5).join(", "));
+
+  line("");
+  line(color.dim("  Read CHANGELOG.md for what moved, then run `devia check`."));
+  line("");
+  return 0;
+}

package/src/commands/validate.mjs

@@ -0,0 +1,194 @@
+import path from "node:path";
+import { exists, read, readJSON, packageRoot } from "../lib/fs.mjs";
+import { parseYaml } from "../lib/yaml.mjs";
+import { standardVersion } from "../lib/version.mjs";
+import { color, heading, status, line, summary } from "../lib/ui.mjs";
+
+export const REQUIRED_MEMORY = [
+  "AGENTS.md",
+  "00_OVERVIEW.md",
+  "01_ARCHITECTURE.md",
+  "02_SURFACES.md",
+  "03_DATA_MODEL.md",
+  "04_PERMISSIONS.md",
+  "05_FLOWS.md",
+  "06_INTEGRATIONS.md",
+  "07_DESIGN.md",
+  "10_NEVER_ALWAYS.md",
+  "11_GAPS.md",
+  "12_DEBT.md",
+  "13_RECIPES.md",
+  "14_INDEX.md",
+  "impact-map.yaml",
+  "devia.json",
+];
+
+const PLACEHOLDER = /TODO\(devia\)/g;
+
+/** Perishable facts do not belong in files that describe what the project is (MEM-007). */
+const PERISHABLE = [
+  /\b\d+\s+tests?\s+(passing|green|failing)\b/i,
+  /\bcurrently\s+(working|building|on)\b/i,
+  /\bnext\s+(we|up|sprint|milestone)\b/i,
+  /\bas of (today|this week|yesterday)\b/i,
+  /\bin progress\b/i,
+  /\b(this|next) (sprint|week)\b/i,
+];
+const PERISHABLE_FILES = ["00_OVERVIEW.md", "01_ARCHITECTURE.md", "14_INDEX.md"];
+
+/** Registry ids look like `| G12 |` (gaps) or `| D7 |` (debt). */
+export function registryIds(text, prefix) {
+  const re = new RegExp(`^\\|\\s*(${prefix}(\\d+))\\s*\\|`, "gm");
+  const out = [];
+  let m;
+  while ((m = re.exec(text))) out.push({ id: m[1], n: Number(m[2]) });
+  return out;
+}
+
+export function checkRegistry(text, prefix, name, add) {
+  const entries = registryIds(text, prefix);
+  const seen = new Map();
+  for (const { id, n } of entries) {
+    if (seen.has(id)) add("FAIL", `${name}: duplicate id ${id}`, "ids are never reused (MEM-004)");
+    else seen.set(id, n);
+  }
+  const nums = [...seen.values()];
+  if (nums.length && new Set(nums).size !== nums.length) {
+    add("FAIL", `${name}: repeated numbering`, "MEM-004");
+  }
+  return seen.size;
+}
+
+export default async function validate(ctx) {
+  const { root, deviaDir, flags } = ctx;
+  const results = [];
+  const add = (kind, label, detail = "") => results.push({ kind, label, detail });
+
+  if (flags.help) {
+    line(`
+${color.bold("devia validate")} — memory integrity
+
+  --root <dir>   repository to validate
+  --strict       treat unfilled placeholders as failures
+  --json         machine-readable output
+`.trim());
+    return 0;
+  }
+
+  if (!exists(deviaDir)) {
+    if (ctx.json) {
+      console.log(JSON.stringify({ ok: false, error: "no .devia directory", root }, null, 2));
+    } else {
+      heading("devia validate");
+      status("FAIL", "no .devia/ in this repository", "run `devia init` (AGT-002)");
+      line("");
+    }
+    return 1;
+  }
+
+  // 1. Structure
+  for (const file of REQUIRED_MEMORY) {
+    if (exists(path.join(deviaDir, file))) add("PASS", `memory file ${file}`);
+    else add("FAIL", `missing ${file}`, "run `devia init` to restore the template");
+  }
+
+  // 2. Configuration
+  const config = readJSON(path.join(deviaDir, "devia.json"));
+  if (!config) {
+    add("FAIL", "devia.json missing or invalid JSON");
+  } else {
+    for (const key of ["project", "maturity", "standardVersion"]) {
+      if (!config[key]) add("FAIL", `devia.json: missing ${key}`);
+    }
+    if (config.project && !config.project.name) add("FAIL", "devia.json: project.name is empty");
+    const installed = standardVersion();
+    if (installed && config.standardVersion && installed !== config.standardVersion) {
+      add(
+        "WARN",
+        `standard pinned at ${config.standardVersion}, installed is ${installed}`,
+        "run `devia sync`"
+      );
+    }
+  }
+
+  // 3. Impact map
+  const mapRaw = read(path.join(deviaDir, "impact-map.yaml"));
+  if (mapRaw) {
+    const map = parseYaml(mapRaw);
+    const impacts = map.impacts || {};
+    const keys = Object.keys(impacts);
+    if (!keys.length) add("FAIL", "impact-map.yaml has no impacts", "MEM-009 cannot be checked");
+    let missing = 0;
+    for (const [key, targets] of Object.entries(impacts)) {
+      for (const t of [].concat(targets || [])) {
+        const rel = String(t);
+        if (rel.startsWith(".") || rel.includes("/")) continue; // points outside .devia
+        if (!exists(path.join(deviaDir, rel))) {
+          add("FAIL", `impact-map: ${key} -> ${rel} does not exist`);
+          missing++;
+        }
+      }
+    }
+    if (!missing && keys.length) add("PASS", `impact map: ${keys.length} change types`);
+  }
+
+  // 4. Registries
+  const gaps = read(path.join(deviaDir, "11_GAPS.md")) || "";
+  const debt = read(path.join(deviaDir, "12_DEBT.md")) || "";
+  const nGaps = checkRegistry(gaps, "G", "11_GAPS.md", add);
+  const nDebt = checkRegistry(debt, "D", "12_DEBT.md", add);
+  add("PASS", `registries: ${nGaps} gap ids, ${nDebt} debt ids`);
+
+  // 5. Placeholders
+  const strict = Boolean(flags.strict);
+  const current = String(config?.maturity?.current || "bronze").toLowerCase();
+  let placeholders = 0;
+  for (const file of REQUIRED_MEMORY) {
+    const text = read(path.join(deviaDir, file));
+    if (!text) continue;
+    const n = (text.match(PLACEHOLDER) || []).length;
+    if (!n) continue;
+    placeholders += n;
+    const blocking = strict || (file === "00_OVERVIEW.md" && current !== "bronze");
+    add(blocking ? "FAIL" : "WARN", `${file}: ${n} unfilled placeholder${n > 1 ? "s" : ""}`);
+  }
+  if (!placeholders) add("PASS", "no unfilled placeholders");
+
+  // 6. Perishable facts (MEM-007)
+  for (const file of PERISHABLE_FILES) {
+    const text = read(path.join(deviaDir, file));
+    if (!text) continue;
+    for (const re of PERISHABLE) {
+      const m = text.match(re);
+      if (m) add("WARN", `${file}: perishable fact "${m[0].trim()}"`, "MEM-007");
+    }
+  }
+
+  // 7. Committed
+  if (exists(path.join(root, ".gitignore"))) {
+    const ignore = read(path.join(root, ".gitignore")) || "";
+    if (/^\s*\.devia\/?\s*$/m.test(ignore)) {
+      add("FAIL", ".devia/ is gitignored", "the memory is part of the repository");
+    }
+  }
+
+  const counts = results.reduce((a, r) => ((a[r.kind] = (a[r.kind] || 0) + 1), a), {});
+  const failed = counts.FAIL || 0;
+
+  if (ctx.json) {
+    console.log(JSON.stringify({ ok: failed === 0, counts, results }, null, 2));
+    return failed ? 1 : 0;
+  }
+
+  heading("devia validate");
+  const quiet = !flags.verbose;
+  for (const r of results) {
+    if (quiet && r.kind === "PASS") continue;
+    status(r.kind, r.label, r.detail);
+  }
+  if (quiet && !failed && !counts.WARN) status("PASS", `${results.length} checks passed`);
+  line("");
+  line(`  ${failed ? color.red("FAILED") : color.green("OK")}  ${summary(counts)}`);
+  line("");
+  return failed ? 1 : 0;
+}

package/src/lib/fs.mjs

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Root of the installed devia package. */
+export const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  ".."
+);
+
+export function exists(p) {
+  return fs.existsSync(p);
+}
+
+export function read(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function readJSON(p) {
+  const raw = read(p);
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function writeFile(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content.replace(/\r\n/g, "\n"), "utf8");
+}
+
+export function writeJSON(p, value) {
+  writeFile(p, JSON.stringify(value, null, 2) + "\n");
+}
+
+/** Recursively list files under dir, relative to dir. */
+export function walk(dir, { filter = () => true, skip = () => false } = {}) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  const stack = [""];
+  while (stack.length) {
+    const rel = stack.pop();
+    const abs = path.join(dir, rel);
+    for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
+      const childRel = rel ? path.join(rel, ent.name) : ent.name;
+      if (skip(childRel, ent)) continue;
+      if (ent.isDirectory()) stack.push(childRel);
+      else if (ent.isFile() && filter(childRel)) out.push(childRel);
+    }
+  }
+  return out.sort();
+}
+
+/** Copy a directory tree. Returns the number of files written. */
+export function copyDir(from, to, { filter = () => true, overwrite = true } = {}) {
+  let n = 0;
+  for (const rel of walk(from, { filter })) {
+    const target = path.join(to, rel);
+    if (!overwrite && fs.existsSync(target)) continue;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(path.join(from, rel), target);
+    n++;
+  }
+  return n;
+}
+
+/** Find the repository root by walking up for a marker, else return cwd. */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (
+      fs.existsSync(path.join(dir, ".devia")) ||
+      fs.existsSync(path.join(dir, ".git")) ||
+      fs.existsSync(path.join(dir, "package.json"))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(start);
+    dir = parent;
+  }
+}

package/src/lib/git.mjs

@@ -0,0 +1,31 @@
+import { execFileSync } from "node:child_process";
+
+/** Run git in `root`. Returns trimmed stdout, or null when git is absent or the command fails. */
+export function git(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function isRepo(root) {
+  return git(root, ["rev-parse", "--is-inside-work-tree"]) === "true";
+}
+
+/**
+ * What the repository actually carries under `root`: tracked files plus untracked ones that are
+ * not ignored. Ignored paths are local artefacts, not the repository's content — scanning them
+ * turns a build cache into a P0 failure. Returns null when git cannot answer, so the caller
+ * falls back to walking the tree rather than scanning nothing.
+ */
+export function trackedFiles(root) {
+  const out = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]);
+  if (out === null) return null;
+  return out.split("\0").filter(Boolean);
+}

package/src/lib/rules.mjs

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { parseFrontmatter } from "./yaml.mjs";
+import { read, walk, packageRoot } from "./fs.mjs";
+
+export const SEVERITIES = ["MUST", "MUST NOT", "SHOULD", "MAY"];
+export const STATUSES = [
+  "draft",
+  "proposed",
+  "active",
+  "deprecated",
+  "superseded",
+  "removed",
+];
+export const PRIORITIES = ["P0", "P1", "P2", "P3"];
+export const ID_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)+$/;
+
+const NOT_A_RULE = new Set(["README.md", "LIFECYCLE.md"]);
+
+/**
+ * Load every rule under a `rules/` directory.
+ * Returns `{ rules, errors }`; a malformed file becomes an error, never a silent skip.
+ */
+export function loadRules(rulesDir = path.join(packageRoot, "rules")) {
+  const files = walk(rulesDir, {
+    filter: (rel) => rel.endsWith(".md") && !NOT_A_RULE.has(path.basename(rel)),
+  });
+  const rules = [];
+  const errors = [];
+  const seen = new Map();
+
+  for (const rel of files) {
+    const abs = path.join(rulesDir, rel);
+    const text = read(abs);
+    const { data, error } = parseFrontmatter(text ?? "");
+    const where = rel.split(path.sep).join("/");
+
+    if (error || !data) {
+      errors.push(`${where}: ${error || "missing frontmatter"}`);
+      continue;
+    }
+    const rule = { ...data, file: where };
+    const id = rule.id;
+
+    if (!id || !ID_PATTERN.test(String(id))) errors.push(`${where}: invalid id ${id}`);
+    else if (seen.has(id)) errors.push(`${where}: duplicate id ${id} (also ${seen.get(id)})`);
+    else seen.set(id, where);
+
+    if (path.basename(where, ".md") !== id) errors.push(`${where}: filename must match id`);
+    if (!SEVERITIES.includes(rule.severity)) errors.push(`${where}: bad severity ${rule.severity}`);
+    if (!STATUSES.includes(rule.status)) errors.push(`${where}: bad status ${rule.status}`);
+    if (!PRIORITIES.includes(rule.priority)) errors.push(`${where}: bad priority ${rule.priority}`);
+    if (!rule.domain) errors.push(`${where}: missing domain`);
+    if (!Array.isArray(rule.source) || rule.source.length === 0)
+      errors.push(`${where}: at least one source is required`);
+    if (!rule.requirement || String(rule.requirement).length < 10)
+      errors.push(`${where}: requirement too short`);
+    if (
+      typeof rule.validation?.automated !== "boolean" ||
+      typeof rule.validation?.manual !== "boolean"
+    )
+      errors.push(`${where}: validation.automated and validation.manual are required`);
+
+    const dir = where.split("/")[0];
+    if (rule.domain && dir !== rule.domain)
+      errors.push(`${where}: lives in ${dir}/ but declares domain ${rule.domain}`);
+
+    rules.push(rule);
+  }
+
+  rules.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  return { rules, errors };
+}
+
+export function ruleStats(rules) {
+  const by = (key) =>
+    rules.reduce((acc, r) => ((acc[r[key]] = (acc[r[key]] || 0) + 1), acc), {});
+  return {
+    total: rules.length,
+    severity: by("severity"),
+    priority: by("priority"),
+    domain: by("domain"),
+    automatable: rules.filter((r) => r.validation?.automated).length,
+    active: rules.filter((r) => r.status === "active").length,
+  };
+}

package/src/lib/ui.mjs

@@ -0,0 +1,52 @@
+import process from "node:process";
+
+const useColor =
+  process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+
+const ESC = String.fromCharCode(27);
+const wrap = (code) => (s) =>
+  useColor ? `${ESC}[${code}m${s}${ESC}[0m` : String(s);
+
+export const color = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  gray: wrap("90"),
+};
+
+export function heading(text) {
+  console.log("\n" + color.bold(text));
+}
+
+export function line(text = "") {
+  console.log(text);
+}
+
+export const STATUS = {
+  PASS: color.green("PASS"),
+  WARN: color.yellow("WARN"),
+  FAIL: color.red("FAIL"),
+  SKIP: color.gray("SKIP"),
+  INFO: color.blue("INFO"),
+};
+
+export function status(kind, label, detail = "") {
+  const tag = STATUS[kind] ?? kind;
+  console.log(`  ${tag}  ${label}${detail ? color.dim(" — " + detail) : ""}`);
+}
+
+export function summary(counts) {
+  const parts = [];
+  for (const [k, v] of Object.entries(counts)) {
+    if (v) parts.push(`${v} ${k.toLowerCase()}`);
+  }
+  return parts.length ? parts.join(" · ") : "nothing to report";
+}
+
+export function fail(message) {
+  console.error(color.red("error: ") + message);
+  process.exitCode = 1;
+}

package/src/lib/vendor.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { packageRoot, exists, read, writeFile, copyDir, walk } from "./fs.mjs";
+
+/**
+ * What `.devia/standard/` receives.
+ *
+ * A file is vendored together with whatever it links to: a relative link that resolves in this
+ * repository and not in the adopter's copy is a broken link shipped to every project
+ * (`tests/cli.test.mjs` walks the materialised tree and fails on one).
+ *
+ * `templates/project/` and `templates/agents/` are deliberately absent: their links are written
+ * for a materialised `.devia/`, so they only resolve once `init` has expanded them.
+ */
+export const VENDOR_FILES = [
+  "AGENTS.md",
+  "PRINCIPLES.md",
+  "MEMORY.md",
+  "LEVELS.md",
+  "MATURITY.md",
+  "GOVERNANCE.md",
+  "MIGRATION.md",
+  "REFERENCES.md",
+  "CHANGELOG.md",
+  "VERSION",
+];
+
+export const VENDOR_DIRS = [
+  "rules",
+  "checklists",
+  "standard",
+  "compliance",
+  "schema",
+  path.join("templates", "docs"),
+  path.join("templates", "github"),
+];
+
+/** Everything the vendor would write, as `relative path -> content`. */
+export function vendorContents() {
+  const out = new Map();
+  for (const f of VENDOR_FILES) {
+    const src = path.join(packageRoot, f);
+    if (exists(src)) out.set(f, read(src));
+  }
+  for (const d of VENDOR_DIRS) {
+    const from = path.join(packageRoot, d);
+    for (const rel of walk(from)) out.set(path.join(d, rel), read(path.join(from, rel)));
+  }
+  return out;
+}
+
+/**
+ * Rewrite the pinned copy from scratch. Returns the number of files written, `PINNED.md`
+ * included.
+ */
+export function vendorStandard(dest, { by, cli, standard, date }) {
+  fs.rmSync(dest, { recursive: true, force: true });
+  let files = 0;
+  for (const f of VENDOR_FILES) {
+    const src = path.join(packageRoot, f);
+    if (exists(src)) {
+      writeFile(path.join(dest, f), read(src));
+      files++;
+    }
+  }
+  for (const d of VENDOR_DIRS) files += copyDir(path.join(packageRoot, d), path.join(dest, d));
+  writeFile(
+    path.join(dest, "PINNED.md"),
+    `# Pinned standard\n\nVendored by \`${by}\` on ${date}.\n\n` +
+      `- devia version: ${cli}\n- standard version: ${standard}\n\n` +
+      "Do not edit these files. Change the standard upstream, then run `npx devia sync`.\n"
+  );
+  return files + 1;
+}

package/src/lib/version.mjs

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { packageRoot, read, readJSON } from "./fs.mjs";
+import { parseYaml } from "./yaml.mjs";
+
+/**
+ * Two versions, deliberately separate: the CLI ships bug fixes without moving the standard, and
+ * the standard gains rules without a CLI change. An adopter pins the second and reports the
+ * first, so neither may stand in for the other.
+ */
+
+/** Version of the installed devia CLI. */
+export function cliVersion() {
+  return readJSON(path.join(packageRoot, "package.json"))?.version || "0.0.0";
+}
+
+/** Version of the standard corpus. */
+export function standardVersion() {
+  return parseYaml(read(path.join(packageRoot, "VERSION")) || "").standard_version || "0.0.0";
+}