@schneiderjoseph/devia 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.6.0 — 2026-09-09
+
+The standard is unchanged: `VERSION` stays at 0.1.0.
+
+### `devia read` — the memory as one page
+
+A memory nobody reads is documentation with extra steps. `devia read` renders `.devia/` into a
+single HTML file: a sidebar in reading order — the contract first, then the numbered files — and
+links between memory files that jump inside the page instead of asking the filesystem for them.
+
+The page is **self-contained**: content embedded, no fetch, no CDN, no stylesheet to resolve. It
+opens by double-click, offline. The reader that prompted this one needed a running local server,
+because a page that fetches its own content hits CORS on `file://`.
+
+- `devia read` writes `.devia/reader.html`; `--out` puts it elsewhere
+- It is a **snapshot**, never the source: regenerate it after changing the memory. Adopters
+  should gitignore it, as this repository now does
+- `src/lib/markdown.mjs` renders the subset the memory templates actually use — headings,
+  tables, fenced code, lists, quotes, rules, and a few inline marks. Same reasoning as the YAML
+  parser: devia writes the files it reads, and `ARC-004` rules out a library. Content is escaped
+  before anything else, so memory text cannot inject markup, and a line outside the subset is
+  shown as written rather than dropped
+
+Recorded as G9.
+
+### Fixed
+
+- `devia --help` still described `sync` as refreshing a vendored standard, which 0.5.0 made
+  opt-in
+
 ## 0.5.0 — 2026-09-09
 
 The standard is unchanged: `VERSION` stays at 0.1.0.

package/README.md

@@ -79,6 +79,26 @@ Update .devia/ in the SAME change
 An agent that codes without reading the memory, or that ships code without updating it, has
 failed the task — not styled it differently.
 
+## What the gates actually caught
+
+`PRINCIPLES.md` says evidence beats opinion, so here is the evidence. Every defect below was
+found by devia's own gates, in one week, on devia itself and on one real project — a Next.js
+application whose manifest lives in `apps/web/`. None of it is independent adoption; read it as
+a tool being run in anger, not as a case study.
+
+| Defect | Caught by |
+|---|---|
+| Nine relative links resolved in this repository and not in the copy shipped to adopters — every project got nine broken links | The test that walks a materialised `.devia/` instead of listing it |
+| `devia debt close` blanked a table row instead of removing it. A blank line ends a markdown table, so every debt line below the closed one was orphaned | Discharging a real debt line with the command itself |
+| Two tests parsed `--json` from stdout merged with stderr. On a machine with `FORCE_COLOR` set, a Node warning made the JSON unparseable | `prepublishOnly`, which refused to publish |
+| The skill told every agent to bootstrap with `npx devia init`. The package is scoped, so in a repository that has not installed devia that resolves to `404 devia@*` | Installing the skill system-wide, where a cold start is the normal case |
+| Five gates reported `SKIP  no package.json` to a repository that has one, with a lockfile, a lint script and thirteen dependencies. The letter of the rule held — nothing was rounded up to `PASS` — but the reason printed was false | Running `devia check` on a real project instead of a fixture |
+| `MEM-DEBT-P0` matched `P0` anywhere in a debt row. A P1 line reading "becomes P0 once payments ship" reported a P0 blocker on a project that had none | Writing a real project's debt registry |
+
+The last two are the ones worth dwelling on. A check that cannot answer must say so — but a
+`SKIP` with a false reason, or a `FAIL` invented out of prose, is worse than no check at all,
+because the reader believes the tool looked. Both are now regression tests.
+
 ## What is in the box
 
 | Layer | Where | Content |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schneiderjoseph/devia",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "One standard, one memory: engineering and design rules plus living project memory for AI coding agents",
   "type": "module",
   "license": "MIT",

package/src/cli.mjs

@@ -10,6 +10,7 @@ const COMMANDS = {
   check: () => import("./commands/check.mjs"),
   doctor: () => import("./commands/doctor.mjs"),
   rules: () => import("./commands/rules.mjs"),
+  read: () => import("./commands/read.mjs"),
   sync: () => import("./commands/sync.mjs"),
   skills: () => import("./commands/skills.mjs"),
   gap: () => import("./commands/registry.mjs"),
@@ -24,7 +25,8 @@ ${color.bold("devia")} — one standard, one memory
   ${color.bold("devia check")}       readiness gates — P0 failures exit non-zero
   ${color.bold("devia doctor")}      adoption, drift and staleness diagnosis
   ${color.bold("devia rules")}       list or show rules from the registry
-  ${color.bold("devia sync")}        refresh the vendored standard after upgrading devia
+  ${color.bold("devia read")}        render the memory as one self-contained page
+  ${color.bold("devia sync")}        pin the standard under .devia/standard/, or refresh it
   ${color.bold("devia skills")}      install the agent adapters (install --agent all)
   ${color.bold("devia gap")}         add or close a line in 11_GAPS.md
   ${color.bold("devia debt")}        add or close a line in 12_DEBT.md

package/src/commands/read.mjs

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { exists, read, writeFile, walk } from "../lib/fs.mjs";
+import { renderMarkdown, escapeHtml } from "../lib/markdown.mjs";
+import { cliVersion } from "../lib/version.mjs";
+import { color, heading, status, line } from "../lib/ui.mjs";
+
+/**
+ * The memory, as one page a human can read.
+ *
+ * Self-contained on purpose: the content is embedded, so the file opens by double-click with no
+ * server, no network and no CDN. A reader that needs a running server is a reader nobody opens.
+ */
+
+/** Reading order: the contract first, then the numbered files, then whatever else is there. */
+function order(files) {
+  const rank = (f) => {
+    if (f === "AGENTS.md") return -2;
+    if (f === "README.md") return -1;
+    const n = f.match(/^(\d+)_/);
+    return n ? Number(n[1]) : 999;
+  };
+  return files.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+}
+
+function title(file) {
+  if (file === "AGENTS.md") return "AGENTS";
+  const body = file.replace(/\.md$/, "");
+  const m = body.match(/^(\d+)_(.*)$/);
+  return m ? `${m[1]} · ${m[2].replace(/_/g, " ")}` : body.replace(/_/g, " ");
+}
+
+const STYLE = `
+:root{--ink:#121826;--ink-line:#222F45;--paper:#fff;--canvas:#EFEEEA;--line:#E7E7EA;
+--muted:#6B7280;--muted-d:rgba(229,231,235,.62);--text-d:#E5E7EB;--accent:#FF5A5F;
+--mono:"JetBrains Mono",ui-monospace,SFMono-Regular,Menlo,monospace}
+*{box-sizing:border-box}
+body{margin:0;background:var(--canvas);color:var(--ink);
+font:15px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;display:flex;min-height:100vh}
+nav{width:290px;flex:0 0 290px;background:var(--ink);color:var(--text-d);position:sticky;top:0;
+height:100vh;overflow:auto;padding:22px 16px}
+nav h1{font-size:13px;letter-spacing:.28em;text-transform:uppercase;font-family:var(--mono);
+color:var(--muted-d);margin:0 0 4px}
+nav .sub{font-size:12px;color:var(--muted-d);margin-bottom:18px;line-height:1.4}
+nav a{display:block;padding:7px 10px;border-radius:8px;color:var(--text-d);text-decoration:none;
+font-size:13px;margin-bottom:2px}
+nav a:hover{background:rgba(255,255,255,.06)}
+nav a.active{background:rgba(255,90,95,.16);outline:1px solid rgba(255,90,95,.25)}
+main{flex:1;min-width:0;padding:44px 56px;background:var(--paper)}
+article{max-width:820px;display:none}
+article.active{display:block}
+h1,h2,h3,h4{line-height:1.25;margin:1.8em 0 .6em}
+h1{font-size:30px;margin-top:0}h2{font-size:22px}h3{font-size:17px}h4{font-size:15px}
+h2{border-top:1px solid var(--line);padding-top:1.2em}
+p{margin:.7em 0}
+a{color:var(--accent)}
+code{font-family:var(--mono);font-size:.88em;background:var(--canvas);padding:2px 5px;border-radius:4px}
+pre{background:var(--ink);color:var(--text-d);padding:16px 18px;border-radius:10px;overflow:auto}
+pre code{background:none;color:inherit;padding:0;font-size:12.5px;line-height:1.55}
+table{border-collapse:collapse;width:100%;margin:1.1em 0;font-size:14px;display:block;overflow-x:auto}
+th,td{border:1px solid var(--line);padding:8px 11px;text-align:left;vertical-align:top}
+th{background:var(--canvas);font-weight:600}
+blockquote{margin:1.1em 0;padding:2px 0 2px 16px;border-left:3px solid var(--accent);color:var(--muted)}
+hr{border:0;border-top:1px solid var(--line);margin:2em 0}
+ul,ol{padding-left:1.3em}li{margin:.3em 0}
+footer{margin-top:48px;padding-top:16px;border-top:1px solid var(--line);
+font-family:var(--mono);font-size:11px;color:var(--muted)}
+@media(max-width:820px){body{display:block}nav{width:auto;height:auto;position:static}main{padding:28px 20px}}
+`;
+
+const SCRIPT = `
+var links = [].slice.call(document.querySelectorAll('nav a'));
+var docs = [].slice.call(document.querySelectorAll('article'));
+function show(id) {
+  docs.forEach(function (d) { d.classList.toggle('active', d.id === id); });
+  links.forEach(function (a) { a.classList.toggle('active', a.getAttribute('href') === '#' + id); });
+  if (location.hash !== '#' + id) history.replaceState(null, '', '#' + id);
+  window.scrollTo(0, 0);
+}
+links.forEach(function (a) {
+  a.addEventListener('click', function (e) { e.preventDefault(); show(a.getAttribute('href').slice(1)); });
+});
+// A link between memory files jumps inside the page instead of asking the filesystem for it.
+[].slice.call(document.querySelectorAll('article a')).forEach(function (a) {
+  var href = a.getAttribute('href') || '';
+  if (!/^[^/:#]+\\.md(#.*)?$/.test(href)) return;
+  var id = 'doc-' + href.split('#')[0].replace(/\\.md$/, '');
+  if (!document.getElementById(id)) return;
+  a.addEventListener('click', function (e) { e.preventDefault(); show(id); });
+});
+show((location.hash || '').slice(1) || docs[0].id);
+`;
+
+export default async function readCommand(ctx) {
+  const { root, deviaDir, flags } = ctx;
+
+  if (flags.help) {
+    line(`
+${color.bold("devia read")} — the memory as one self-contained page
+
+  --root <dir>   repository to read
+  --out <file>   where to write (default: .devia/reader.html)
+
+The page embeds the memory: it opens by double-click, with no server and no network.
+Regenerate it after changing the memory — it is a snapshot, never the source.
+`.trim());
+    return 0;
+  }
+
+  if (!exists(deviaDir)) {
+    status("FAIL", "no .devia/", "run `devia init` first");
+    return 1;
+  }
+
+  const files = order(walk(deviaDir, { filter: (f) => f.endsWith(".md") && !f.includes(path.sep) }));
+  if (!files.length) {
+    status("FAIL", "no memory files to read", ".devia/ holds no markdown");
+    return 1;
+  }
+
+  const project = path.basename(root);
+  const nav = [];
+  const articles = [];
+  for (const file of files) {
+    const id = `doc-${file.replace(/\.md$/, "")}`;
+    nav.push(`<a href="#${id}">${escapeHtml(title(file))}</a>`);
+    articles.push(
+      `<article id="${id}">\n${renderMarkdown(read(path.join(deviaDir, file)) || "")}\n` +
+        `<footer>${escapeHtml(file)} · .devia/</footer></article>`
+    );
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(project)} — memory</title>
+<style>${STYLE}</style></head>
+<body>
+<nav><h1>${escapeHtml(project)}</h1>
+<div class="sub">Project memory · read before the code, updated with it</div>
+${nav.join("\n")}
+</nav>
+<main>
+${articles.join("\n")}
+</main>
+<script>${SCRIPT}</script>
+</body></html>
+`;
+
+  const out = flags.out ? path.resolve(String(flags.out)) : path.join(deviaDir, "reader.html");
+  writeFile(out, html);
+
+  heading(`devia read — ${project}`);
+  status("PASS", `${files.length} memory files rendered`, `${Math.round(html.length / 1024)} kB`);
+  status("PASS", "written", out);
+  line("");
+  line(color.dim("  Open it directly — no server needed. Regenerate after changing the memory."));
+  line(color.dim(`  Generated ${today} by devia ${cliVersion()}.`));
+  line("");
+  return 0;
+}

package/src/lib/markdown.mjs

@@ -0,0 +1,179 @@
+/**
+ * A Markdown subset, rendered to HTML.
+ *
+ * The same reasoning as `yaml.mjs`: devia writes the files it reads. The memory templates use
+ * headings, tables, fenced code, lists, blockquotes, rules and a few inline marks — so that is
+ * what this renders. Anything outside the subset survives as escaped text rather than being
+ * silently swallowed, because a reader that drops a line is worse than one that shows it plainly.
+ *
+ * A dependency would be the easy answer here, and `ARC-004` says it is not available.
+ */
+
+const ESCAPES = [
+  ["&", "&"],
+  ["<", "&lt;"],
+  [">", "&gt;"],
+  ['"', "&quot;"],
+];
+
+export function escapeHtml(text) {
+  let out = String(text);
+  for (const [from, to] of ESCAPES) out = out.split(from).join(to);
+  return out;
+}
+
+/**
+ * Inline marks, applied to already-escaped text. Code spans are lifted out first so their
+ * contents are never re-parsed. The placeholder is NUL-delimited on purpose: prose contains
+ * " 12 ", and a placeholder prose can produce turns a number into a code span.
+ */
+const MARK = "\u0000";
+
+function inline(text) {
+  const spans = [];
+  let out = text.replace(/`([^`]+)`/g, (_, code) => {
+    spans.push(code);
+    return `${MARK}${spans.length - 1}${MARK}`;
+  });
+
+  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, href) => {
+    const safe = /^(https?:|mailto:|#|[\w./-])/.test(href) ? href : "#";
+    return `<a href="${safe}">${label}</a>`;
+  });
+  out = out.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  out = out.replace(/(^|[\s(])\*([^*\n]+)\*(?=[\s).,;:!?]|$)/g, "$1<em>$2</em>");
+
+  // Regex littérale avec des échappements \u0000 : aucun octet de contrôle dans la source.
+  return out.replace(/\u0000(\d+)\u0000/g, (_, i) => `<code>${spans[Number(i)]}</code>`);
+}
+
+function isTableSeparator(line) {
+  return /^\|[\s:|-]+\|$/.test(line.trim()) && line.includes("-");
+}
+
+function cells(line) {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((c) => inline(c.trim()));
+}
+
+/** Render a Markdown subset to an HTML fragment. */
+export function renderMarkdown(source) {
+  const lines = escapeHtml(source).split(/\r?\n/);
+  const html = [];
+  let i = 0;
+
+  const flushList = (tag, items) => {
+    html.push(`<${tag}>`);
+    for (const item of items) html.push(`<li>${inline(item)}</li>`);
+    html.push(`</${tag}>`);
+  };
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (!line.trim()) {
+      i++;
+      continue;
+    }
+
+    // Fenced code: kept verbatim, never re-parsed.
+    const fence = line.match(/^```(\w*)\s*$/);
+    if (fence) {
+      const body = [];
+      i++;
+      while (i < lines.length && !/^```\s*$/.test(lines[i])) body.push(lines[i++]);
+      i++;
+      const lang = fence[1] ? ` data-lang="${fence[1]}"` : "";
+      html.push(`<pre${lang}><code>${body.join("\n")}</code></pre>`);
+      continue;
+    }
+
+    const heading = line.match(/^(#{1,4})\s+(.*)$/);
+    if (heading) {
+      const level = heading[1].length;
+      html.push(`<h${level}>${inline(heading[2].trim())}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    if (/^(-{3,}|\*{3,})\s*$/.test(line.trim())) {
+      html.push("<hr>");
+      i++;
+      continue;
+    }
+
+    // Table: a header row followed by a separator row.
+    if (line.trim().startsWith("|") && i + 1 < lines.length && isTableSeparator(lines[i + 1])) {
+      const head = cells(line);
+      i += 2;
+      const body = [];
+      while (i < lines.length && lines[i].trim().startsWith("|")) body.push(cells(lines[i++]));
+      html.push("<table><thead><tr>");
+      for (const c of head) html.push(`<th>${c}</th>`);
+      html.push("</tr></thead><tbody>");
+      for (const row of body) {
+        html.push("<tr>");
+        for (const c of row) html.push(`<td>${c}</td>`);
+        html.push("</tr>");
+      }
+      html.push("</tbody></table>");
+      continue;
+    }
+
+    // Les lignes sont déjà échappées : le chevron d'une citation y est "&gt;", pas ">".
+    if (/^&gt;\s?/.test(line)) {
+      const quote = [];
+      while (i < lines.length && /^&gt;\s?/.test(lines[i])) {
+        quote.push(lines[i++].replace(/^&gt;\s?/, ""));
+      }
+      html.push(`<blockquote>${inline(quote.join(" "))}</blockquote>`);
+      continue;
+    }
+
+    if (/^\s*[-*]\s+/.test(line)) {
+      const items = [];
+      while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+        let item = lines[i++].replace(/^\s*[-*]\s+/, "");
+        // A wrapped bullet continues on the next indented, non-marker line.
+        while (i < lines.length && /^\s{2,}\S/.test(lines[i]) && !/^\s*[-*]\s+/.test(lines[i])) {
+          item += " " + lines[i++].trim();
+        }
+        items.push(item);
+      }
+      flushList("ul", items);
+      continue;
+    }
+
+    if (/^\s*\d+\.\s+/.test(line)) {
+      const items = [];
+      while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i])) {
+        let item = lines[i++].replace(/^\s*\d+\.\s+/, "");
+        while (i < lines.length && /^\s{2,}\S/.test(lines[i]) && !/^\s*\d+\.\s+/.test(lines[i])) {
+          item += " " + lines[i++].trim();
+        }
+        items.push(item);
+      }
+      flushList("ol", items);
+      continue;
+    }
+
+    // Paragraph: consecutive plain lines, joined.
+    const para = [];
+    while (
+      i < lines.length &&
+      lines[i].trim() &&
+      !/^(#{1,4}\s|```|&gt;|\s*[-*]\s|\s*\d+\.\s|\|)/.test(lines[i])
+    ) {
+      para.push(lines[i++].trim());
+    }
+    if (para.length) html.push(`<p>${inline(para.join(" "))}</p>`);
+    // A line the subset does not recognise is shown as written, never dropped.
+    else html.push(`<p>${inline(lines[i++].trim())}</p>`);
+  }
+
+  return html.join("\n");
+}