();
+ const out: SxMark[] = [];
+ for (const m of marks) if (!seen.has(m)) { seen.add(m); out.push(m); }
+ return out;
+};
+
+// ─── shortcode lifting ──────────────────────────────────────────────────
+
+// When a contains [[sx:foo]] tokens mixed with text, split it into
+// (paragraph)(shortcode)(paragraph) blocks so the document is queryable
+// per-shortcode rather than per-paragraph-with-substring.
+const splitShortcodesFromParagraph = (inlines: SxInline[]): SxBlock[] => {
+ const out: SxBlock[] = [];
+ let buf: SxInline[] = [];
+ const flush = (): void => {
+ if (buf.length > 0 && buf.some((i) => !(i.t === "text" && i.v.trim() === ""))) {
+ out.push({ t: "p", c: buf });
+ }
+ buf = [];
+ };
+ for (const i of inlines) {
+ if (i.t !== "text" || !SHORTCODE_RE.test(i.v)) {
+ buf.push(i);
+ continue;
+ }
+ SHORTCODE_RE.lastIndex = 0;
+ const blocks = textWithShortcodesToBlocks(i.v, i.m ?? []);
+ for (const b of blocks) {
+ if (b.t === "shortcode") {
+ flush();
+ out.push(b);
+ } else if (b.t === "p") {
+ for (const inner of b.c) buf.push(inner);
+ }
+ }
+ }
+ flush();
+ return out;
+};
+
+const textWithShortcodesToBlocks = (text: string, marks: SxMark[]): SxBlock[] => {
+ const out: SxBlock[] = [];
+ let last = 0;
+ SHORTCODE_RE.lastIndex = 0;
+ for (const m of text.matchAll(SHORTCODE_RE)) {
+ const idx = m.index ?? 0;
+ if (idx > last) {
+ const before = text.slice(last, idx);
+ if (before.trim() !== "") {
+ out.push({ t: "p", c: [{ t: "text", v: before, ...(marks.length ? { m: marks } : {}) }] });
+ }
+ }
+ const name = m[1]!;
+ const args: Record = {};
+ for (const a of (m[2] ?? "").matchAll(SHORTCODE_ARG_RE)) {
+ args[a[1]!] = a[2] ?? a[3] ?? "";
+ }
+ out.push({ t: "shortcode", name, args });
+ last = idx + m[0].length;
+ }
+ const tail = text.slice(last);
+ if (tail.trim() !== "") {
+ out.push({ t: "p", c: [{ t: "text", v: tail, ...(marks.length ? { m: marks } : {}) }] });
+ }
+ return out;
+};
+
+// ─── small helpers ───────────────────────────────────────────────────────
+
+const parseLangFromClass = (cls: string): string => {
+ const m = cls.match(/(?:^|\s)language-([\w-]+)/);
+ return m?.[1] ?? "";
+};
+
+const numAttr = (el: HTMLElement, name: string): number | undefined => {
+ const v = el.getAttribute(name);
+ if (!v) return undefined;
+ const n = parseInt(v, 10);
+ return Number.isFinite(n) ? n : undefined;
+};
+
+const decodeEntities = (s: string): string =>
+ s
+ .replace(/&/g, "&")
+ .replace(/</g, "<")
+ .replace(/>/g, ">")
+ .replace(/"/g, '"')
+ .replace(/'/g, "'")
+ .replace(/ /g, " ");
diff --git a/src/b32_anchor_extract.test.ts b/src/b32_anchor_extract.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bce5d02275d3e5807e1ddb990b0109f80079809c
--- /dev/null
+++ b/src/b32_anchor_extract.test.ts
@@ -0,0 +1,57 @@
+import { test, expect } from "bun:test";
+import { extractAnchors } from "./b32_anchor_extract.ts";
+
+test("extracts h2 with explicit id", () => {
+ const html = `Getting started
`;
+ expect(extractAnchors(html)).toEqual([
+ { level: 2, text: "Getting started", id: "getting-started" },
+ ]);
+});
+
+test("extracts h3 with explicit id", () => {
+ const html = `Why
`;
+ expect(extractAnchors(html)).toEqual([
+ { level: 3, text: "Why", id: "why" },
+ ]);
+});
+
+test("ignores h1 and h4+", () => {
+ const html = `T
A
B
`;
+ const anchors = extractAnchors(html);
+ expect(anchors.map((a) => a.id)).toEqual(["a"]);
+});
+
+test("slugifies when id attribute is missing", () => {
+ const html = `What this number does *not* measure
`;
+ const anchors = extractAnchors(html);
+ expect(anchors[0]?.id).toBe("what-this-number-does-not-measure");
+});
+
+test("strips inline tags from text and id source", () => {
+ const html = `red: phase
`;
+ const anchors = extractAnchors(html);
+ expect(anchors[0]?.text).toBe("red: phase");
+ expect(anchors[0]?.id).toBe("red-phase");
+});
+
+test("returns multiple anchors in document order", () => {
+ const html = `One
x
Two
Three
`;
+ const anchors = extractAnchors(html);
+ expect(anchors.map((a) => `${a.level}:${a.id}`)).toEqual([
+ "2:one",
+ "3:two",
+ "2:three",
+ ]);
+});
+
+test("skips empty headings", () => {
+ const html = `Real
`;
+ expect(extractAnchors(html).length).toBe(1);
+});
+
+test("handles HTML entities in text", () => {
+ const html = `Tom & Jerry
`;
+ const anchors = extractAnchors(html);
+ expect(anchors[0]?.text).toBe("Tom & Jerry");
+ expect(anchors[0]?.id).toBe("tom-jerry");
+});
diff --git a/src/b32_anchor_extract.ts b/src/b32_anchor_extract.ts
new file mode 100644
index 0000000000000000000000000000000000000000..182e4b3e8ceab5b87fd315a848fe49a2080e6589
--- /dev/null
+++ b/src/b32_anchor_extract.ts
@@ -0,0 +1,44 @@
+// c32 — pure: parse rendered HTML and extract anchor entries for
+// h2/h3 headings. Used by the docs layout to build the right-rail
+// "on this page" navigator. No I/O; given a string in, returns a
+// list of anchors out.
+//
+// Input shape: HTML produced by `marked` (which adds `id` attrs to
+// headings via the GFM-slugger by default in our config). When an
+// id is missing, we slug-ify the heading text ourselves so the
+// anchor link still works.
+
+export interface Anchor {
+ level: 2 | 3;
+ text: string;
+ id: string;
+}
+
+const slugify = (raw: string): string =>
+ raw
+ .toLowerCase()
+ .replace(/<[^>]*>/g, "")
+ .replace(/&[a-z]+;/g, " ")
+ .replace(/[^a-z0-9\s-]/g, "")
+ .trim()
+ .replace(/\s+/g, "-");
+
+const stripTags = (s: string): string => s.replace(/<[^>]*>/g, "").replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, '"').replace(/'|'/g, "'").trim();
+
+export const extractAnchors = (html: string): Anchor[] => {
+ const out: Anchor[] = [];
+ const re = /]*))?>([\s\S]*?)<\/h\1>/g;
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(html)) !== null) {
+ const level = parseInt(m[1] ?? "2", 10) as 2 | 3;
+ const attrs = m[2] ?? "";
+ const inner = m[3] ?? "";
+ const idMatch = /\bid="([^"]+)"/.exec(attrs);
+ const text = stripTags(inner);
+ if (!text) continue;
+ const id = idMatch?.[1] ?? slugify(text);
+ if (!id) continue;
+ out.push({ level, text, id });
+ }
+ return out;
+};
diff --git a/src/b32_edit_resolve.test.ts b/src/b32_edit_resolve.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..159c5ac7c33293d78ecd97c736042598d8a133c0
--- /dev/null
+++ b/src/b32_edit_resolve.test.ts
@@ -0,0 +1,58 @@
+import { test, expect } from "bun:test";
+import { resolveEdit } from "./b32_edit_resolve.ts";
+
+test("resolves an existing sama page", () => {
+ const r = resolveEdit("sama", "sorted");
+ expect(r).not.toBeNull();
+ expect(r?.pageUrl).toBe("/sama/sorted");
+ expect(r?.filePath).toBe("content/sama/sorted.md");
+ expect(r?.title).toMatch(/Sorted/);
+});
+
+test("resolves an existing guide", () => {
+ const r = resolveEdit("guides", "claude-code");
+ expect(r).not.toBeNull();
+ expect(r?.filePath).toBe("content/guides/claude-code.md");
+});
+
+test("resolves an existing blog post", () => {
+ const r = resolveEdit("blog", "from-rules-to-checks");
+ expect(r).not.toBeNull();
+ expect(r?.filePath).toBe("content/blog/from-rules-to-checks.md");
+});
+
+test("returns null for unknown section", () => {
+ expect(resolveEdit("admin", "x")).toBeNull();
+ expect(resolveEdit("etc", "passwd")).toBeNull();
+});
+
+test("returns null for unknown slug in a known section", () => {
+ expect(resolveEdit("sama", "nonexistent-discipline")).toBeNull();
+});
+
+test("rejects path traversal in slug", () => {
+ expect(resolveEdit("sama", "../sorted")).toBeNull();
+ expect(resolveEdit("sama", "..")).toBeNull();
+ expect(resolveEdit("sama", "/etc/passwd")).toBeNull();
+});
+
+test("rejects unsafe slug shapes", () => {
+ expect(resolveEdit("sama", "Sorted")).toBeNull(); // uppercase
+ expect(resolveEdit("sama", "")).toBeNull();
+ expect(resolveEdit("sama", "with space")).toBeNull();
+ expect(resolveEdit("sama", "-leading-dash")).toBeNull();
+});
+
+test("resolves nav-only sama pages (e.g. /sama/skill) via SITE_NAV fallback", () => {
+ const r = resolveEdit("sama", "skill");
+ expect(r).not.toBeNull();
+ expect(r?.pageUrl).toBe("/sama/skill");
+ expect(r?.filePath).toBe("content/sama/skill.md");
+ expect(r?.title).toMatch(/SKILL/i);
+});
+
+test("non-editable nav links (editPath:null) stay unresolvable", () => {
+ // /sama/verify is in SITE_NAV but has editPath: null because it's
+ // a verifier form, not a content/<...>.md doc.
+ expect(resolveEdit("sama", "verify")).toBeNull();
+});
diff --git a/src/b32_edit_resolve.ts b/src/b32_edit_resolve.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e980666f2f22735d25161f7dffefaa93c9f2b16a
--- /dev/null
+++ b/src/b32_edit_resolve.ts
@@ -0,0 +1,68 @@
+// c32 — pure logic: given a (section, slug) tuple from a /edit/<...>
+// URL, resolve it to the editable resource (page URL, file path on
+// disk, page title) — or return null if the combination doesn't map
+// to an existing doc page. Pure: no I/O. The handler does the actual
+// fs read for the current body.
+//
+// Editable sections are the ones that already have a registry: sama,
+// guides, blog. Slug must match an entry in the corresponding registry
+// — this prevents arbitrary file writes via /edit/../../etc/passwd
+// style inputs.
+
+import { ALL_SAMA } from "./a31_sama.ts";
+import { ALL_GUIDES } from "./a31_guides.ts";
+import { ALL_POSTS } from "./a31_blog.ts";
+import { SITE_NAV } from "./a31_docs_nav.ts";
+
+export type EditableSection = "sama" | "guides" | "blog";
+
+export interface ResolvedEdit {
+ section: EditableSection;
+ slug: string;
+ pageUrl: string;
+ filePath: string;
+ title: string;
+}
+
+const SECTIONS = new Set(["sama", "guides", "blog"]);
+
+const isValidSection = (s: string): s is EditableSection => SECTIONS.has(s as EditableSection);
+
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+
+const lookupTitle = (section: EditableSection, slug: string): string | null => {
+ if (section === "sama") {
+ const e = ALL_SAMA.find((d) => d.slug === slug);
+ if (e) return `${e.letter} — ${e.title}`;
+ } else if (section === "guides") {
+ const e = ALL_GUIDES.find((g) => g.slug === slug);
+ if (e) return e.title;
+ } else {
+ const e = ALL_POSTS.find((p) => p.slug === slug);
+ if (e) return e.title;
+ }
+ // Fallback to SITE_NAV: nav-only editable pages (e.g. /sama/skill)
+ // have a content/<...>.md backing file but no entry in the discipline
+ // / guide / blog registries. They're listed in SITE_NAV with a
+ // non-null editPath, which is the single source of truth for
+ // "this docs page is editable".
+ const navSection = SITE_NAV.find((s) => s.id === section);
+ const link = navSection?.links.find(
+ (l) => l.href === `/${section}/${slug}` && l.editPath !== null,
+ );
+ return link?.label ?? null;
+};
+
+export const resolveEdit = (section: string, slug: string): ResolvedEdit | null => {
+ if (!isValidSection(section)) return null;
+ if (!SAFE_SLUG.test(slug)) return null;
+ const title = lookupTitle(section, slug);
+ if (title === null) return null;
+ return {
+ section,
+ slug,
+ pageUrl: `/${section}/${slug}`,
+ filePath: `content/${section}/${slug}.md`,
+ title,
+ };
+};
diff --git a/src/b32_sama_v2_verify.test.ts b/src/b32_sama_v2_verify.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a612308d4a05572d0c0478a136d9c4bba56982dc
--- /dev/null
+++ b/src/b32_sama_v2_verify.test.ts
@@ -0,0 +1,247 @@
+import { describe, test, expect } from "bun:test";
+import { verifySamaV2 } from "./b32_sama_v2_verify.ts";
+import type { ProfileSpec, SamaV2Input } from "./a31_sama_v2.ts";
+
+// Minimal fixture profile mirroring the shape this repo's
+// sama.profile.toml declares, but with synthetic prefixes so tests
+// don't change when the live profile evolves.
+const FIXTURE_PROFILE: ProfileSpec = {
+ samaVersion: "2.0",
+ profile: "test-fixture",
+ layers: {
+ 0: { sublayers: [{ name: "default", prefix: "p0_", index: 0 }] },
+ 1: {
+ sublayers: [
+ { name: "logic", prefix: "p1a_", index: 0 },
+ { name: "render", prefix: "p1b_", index: 1 },
+ ],
+ },
+ 2: {
+ sublayers: [
+ { name: "data", prefix: "p2a_", index: 0 },
+ { name: "io", prefix: "p2b_", index: 1 },
+ ],
+ },
+ 3: {
+ sublayers: [
+ { name: "handlers", prefix: "p3a_", index: 0 },
+ { name: "server", prefix: "p3b_", index: 1 },
+ ],
+ },
+ },
+};
+
+const mk = (entries: Array<[string, string]>): SamaV2Input => ({
+ profile: FIXTURE_PROFILE,
+ files: new Map(entries),
+});
+
+describe("c32_sama_v2_verify — overall", () => {
+ test("empty repo: every check passes with examined=0 for content-bearing checks", () => {
+ const report = verifySamaV2(mk([]));
+ expect(report.overallPassed).toBe(true);
+ expect(report.checks).toHaveLength(7);
+ for (const c of report.checks) expect(c.passed).toBe(true);
+ });
+
+ test("a minimal Layer-0-only repo conforms", () => {
+ const report = verifySamaV2(mk([
+ ["src/p0_types.ts", "export const x = 1;\n"],
+ ]));
+ expect(report.overallPassed).toBe(true);
+ });
+});
+
+describe("c32_sama_v2_verify — Sorted (#1)", () => {
+ test("a file without a profile-recognised prefix is flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/unknown_x.ts", "export const x = 1;\n"],
+ ]));
+ const sorted = report.checks.find((c) => c.id === 1)!;
+ expect(sorted.passed).toBe(false);
+ expect(sorted.violations.some((v) => v.file === "src/unknown_x.ts")).toBe(true);
+ });
+
+ test("a profile whose prefixes lex-sort against layer order is flagged", () => {
+ // Swap: Layer 0 prefix sorts AFTER Layer 1 prefix.
+ const bad: ProfileSpec = {
+ samaVersion: "2.0", profile: "bad",
+ layers: {
+ 0: { sublayers: [{ name: "default", prefix: "z0_", index: 0 }] },
+ 1: { sublayers: [{ name: "default", prefix: "a1_", index: 0 }] },
+ 2: { sublayers: [{ name: "default", prefix: "b2_", index: 0 }] },
+ 3: { sublayers: [{ name: "default", prefix: "c3_", index: 0 }] },
+ },
+ };
+ const report = verifySamaV2({ profile: bad, files: new Map() });
+ const sorted = report.checks.find((c) => c.id === 1)!;
+ expect(sorted.passed).toBe(false);
+ expect(sorted.violations.length).toBeGreaterThan(0);
+ });
+});
+
+describe("c32_sama_v2_verify — Architecture (#2)", () => {
+ test("an unprefixed src/*.ts file is flagged with a clear reason", () => {
+ const report = verifySamaV2(mk([
+ ["src/random.ts", "export const x = 1;\n"],
+ ]));
+ const arch = report.checks.find((c) => c.id === 2)!;
+ expect(arch.passed).toBe(false);
+ const vio = arch.violations.find((v) => v.file === "src/random.ts")!;
+ expect(vio.detail).toContain("unprefixed");
+ });
+
+ test("a properly-prefixed file is not flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "export const x = 1;\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 2)!.passed).toBe(true);
+ });
+});
+
+describe("c32_sama_v2_verify — Modeled tests (#3)", () => {
+ test("a Layer 1 file without a sibling test is flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "export const x = 1;\n"],
+ ]));
+ const modeled = report.checks.find((c) => c.id === 3)!;
+ expect(modeled.passed).toBe(false);
+ const vio = modeled.violations[0]!;
+ expect(vio.file).toBe("src/p1a_logic.ts");
+ expect(vio.detail).toContain("p1a_logic.test.ts");
+ });
+
+ test("a Layer 1 file with its sibling passes", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "export const x = 1;\n"],
+ ["src/p1a_logic.test.ts", "import {expect, test} from \"bun:test\"; test(\"x\", () => { expect(1).toBe(1); });\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 3)!.passed).toBe(true);
+ });
+
+ test("Layer 0 files don't require sibling tests", () => {
+ const report = verifySamaV2(mk([
+ ["src/p0_types.ts", "export const x = 1;\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 3)!.passed).toBe(true);
+ });
+});
+
+describe("c32_sama_v2_verify — Modeled boundary (#4)", () => {
+ test("JSON.parse in Layer 1 is flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_naughty.ts", "export const f = (s: string) => JSON.parse(s);\n"],
+ ]));
+ const boundary = report.checks.find((c) => c.id === 4)!;
+ expect(boundary.passed).toBe(false);
+ expect(boundary.violations[0]!.detail).toContain("JSON.parse");
+ });
+
+ test("JSON.parse in Layer 2 is OK (Layer 2 IS the boundary)", () => {
+ const report = verifySamaV2(mk([
+ ["src/p2b_adapter.ts", "export const f = (s: string) => JSON.parse(s);\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 4)!.passed).toBe(true);
+ });
+
+ test("string literals containing JSON.parse don't false-positive", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "const explainer = \"to fix, call JSON.parse(input) in Layer 2\";\nexport const x = explainer.length;\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 4)!.passed).toBe(true);
+ });
+});
+
+describe("c32_sama_v2_verify — Atomic (#5)", () => {
+ test("a file over the 700-line cap is flagged", () => {
+ const fat = Array.from({ length: 720 }, (_, i) => `// line ${i}`).join("\n");
+ const report = verifySamaV2(mk([
+ ["src/p1a_fat.ts", fat],
+ ]));
+ const atomic = report.checks.find((c) => c.id === 5)!;
+ expect(atomic.passed).toBe(false);
+ expect(atomic.violations[0]!.detail).toContain("over the 700-line cap");
+ });
+
+ test("a barrel re-export file is flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_barrel.ts", "export * from \"./p1a_a.ts\";\nexport * from \"./p1a_b.ts\";\n"],
+ ]));
+ const atomic = report.checks.find((c) => c.id === 5)!;
+ expect(atomic.passed).toBe(false);
+ expect(atomic.violations[0]!.detail).toContain("barrel");
+ });
+});
+
+describe("c32_sama_v2_verify — Law §1.2 (#6)", () => {
+ test("upward import (Layer 1 → Layer 2) is flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "import { x } from \"./p2a_data.ts\";\nexport const y = x;\n"],
+ ["src/p1a_logic.test.ts", "import { test, expect } from \"bun:test\"; test(\"y\", () => { expect(1).toBe(1); });\n"],
+ ["src/p2a_data.ts", "export const x = 1;\n"],
+ ["src/p2a_data.test.ts","import { test, expect } from \"bun:test\"; test(\"x\", () => { expect(1).toBe(1); });\n"],
+ ]));
+ const law = report.checks.find((c) => c.id === 6)!;
+ expect(law.passed).toBe(false);
+ expect(law.violations.some((v) => v.detail.includes("upward"))).toBe(true);
+ });
+
+ test("downward import (Layer 2 → Layer 0) passes", () => {
+ const report = verifySamaV2(mk([
+ ["src/p2a_data.ts", "import type { X } from \"./p0_types.ts\";\nexport const f = (): X => ({} as X);\n"],
+ ["src/p2a_data.test.ts", "import { test, expect } from \"bun:test\"; test(\"f\", () => { expect(1).toBe(1); });\n"],
+ ["src/p0_types.ts", "export interface X { id: number }\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 6)!.passed).toBe(true);
+ });
+
+ test("same-layer reversed sublayer is flagged", () => {
+ // p1a_logic is sublayer index 0 (logic), p1b_render is sublayer
+ // index 1 (render). Logic importing render is reverse order.
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "import { r } from \"./p1b_render.ts\";\nexport const y = r;\n"],
+ ["src/p1a_logic.test.ts", "import { test, expect } from \"bun:test\"; test(\"y\", () => { expect(1).toBe(1); });\n"],
+ ["src/p1b_render.ts", "export const r = 1;\n"],
+ ["src/p1b_render.test.ts","import { test, expect } from \"bun:test\"; test(\"r\", () => { expect(1).toBe(1); });\n"],
+ ]));
+ const law = report.checks.find((c) => c.id === 6)!;
+ expect(law.passed).toBe(false);
+ expect(law.violations.some((v) => v.detail.includes("sublayer"))).toBe(true);
+ });
+
+ test("an import cycle is flagged", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_a.ts", "import { y } from \"./p1a_b.ts\";\nexport const x = y;\n"],
+ ["src/p1a_a.test.ts", "import { test, expect } from \"bun:test\"; test(\"x\", () => { expect(1).toBe(1); });\n"],
+ ["src/p1a_b.ts", "import { x } from \"./p1a_a.ts\";\nexport const y = x;\n"],
+ ["src/p1a_b.test.ts", "import { test, expect } from \"bun:test\"; test(\"y\", () => { expect(1).toBe(1); });\n"],
+ ]));
+ const law = report.checks.find((c) => c.id === 6)!;
+ expect(law.passed).toBe(false);
+ expect(law.violations.some((v) => v.detail.includes("cycle"))).toBe(true);
+ });
+});
+
+describe("c32_sama_v2_verify — Consistency §3 (#7)", () => {
+ test("Layer 1 file reaching Layer 2 contradicts its declared prefix", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "import { f } from \"./p2a_data.ts\";\nexport const y = f;\n"],
+ ["src/p1a_logic.test.ts", "import { test, expect } from \"bun:test\"; test(\"y\", () => { expect(1).toBe(1); });\n"],
+ ["src/p2a_data.ts", "export const f = 1;\n"],
+ ["src/p2a_data.test.ts", "import { test, expect } from \"bun:test\"; test(\"f\", () => { expect(1).toBe(1); });\n"],
+ ]));
+ const consistency = report.checks.find((c) => c.id === 7)!;
+ expect(consistency.passed).toBe(false);
+ expect(consistency.violations[0]!.detail).toContain("declared Layer 1");
+ expect(consistency.violations[0]!.detail).toContain("Layer 2");
+ });
+
+ test("downward-only imports are consistent", () => {
+ const report = verifySamaV2(mk([
+ ["src/p1a_logic.ts", "import type { X } from \"./p0_types.ts\";\nexport const y = (a: X) => a;\n"],
+ ["src/p1a_logic.test.ts", "import { test, expect } from \"bun:test\"; test(\"y\", () => { expect(1).toBe(1); });\n"],
+ ["src/p0_types.ts", "export interface X { id: number }\n"],
+ ]));
+ expect(report.checks.find((c) => c.id === 7)!.passed).toBe(true);
+ });
+});
diff --git a/src/b32_sama_v2_verify.ts b/src/b32_sama_v2_verify.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a6d584412e46a1dcf251604daeb4a0a76812cc7e
--- /dev/null
+++ b/src/b32_sama_v2_verify.ts
@@ -0,0 +1,436 @@
+// c32 — logic: the SAMA v2 verifier. Implements the seven §4
+// conformance checks (Sorted, Architecture, Modeled-tests,
+// Modeled-boundary, Atomic, the Law §1.2, Consistency §3) as pure
+// functions over an in-memory (profile, files) input. Never reads
+// the filesystem — the loader (c14_sama_profile + c21 handler)
+// populates the input map. No mocks, no stubs: every check is a
+// real grep/string-op on the supplied content.
+
+import {
+ declaredLayer,
+ type SamaV2Check,
+ type SamaV2Input,
+ type SamaV2Report,
+ type SamaV2Violation,
+} from "./a31_sama_v2.ts";
+
+// — shared utilities -------------------------------------------------
+
+// A SAMA file is one we expect to obey the layer rules: any *.ts
+// under src/ that isn't a *.test.ts. Tests live next to source as
+// siblings; they're examined for the Modeled check but don't carry
+// their own layer.
+const isSamaFile = (path: string): boolean =>
+ path.startsWith("src/") && path.endsWith(".ts") && !path.endsWith(".test.ts");
+
+const isTestFile = (path: string): boolean =>
+ path.startsWith("src/") && path.endsWith(".test.ts");
+
+// Strip JS/TS string literals and comments to whitespace so a regex
+// that walks the source doesn't trip on test fixtures that contain
+// the very patterns we're scanning for. Same shape as the helper in
+// c32_sama_verify; duplicated here to keep c32_sama_v2_verify a
+// stand-alone module the loader can pull in without dragging the v1
+// verifier with it.
+const stripStringsAndComments = (src: string): string => {
+ let out = "";
+ let i = 0;
+ while (i < src.length) {
+ const c = src[i];
+ const n = src[i + 1];
+ if (c === "/" && n === "/") {
+ out += " ";
+ i += 2;
+ while (i < src.length && src[i] !== "\n") { out += " "; i++; }
+ } else if (c === "/" && n === "*") {
+ out += " ";
+ i += 2;
+ while (i < src.length - 1 && !(src[i] === "*" && src[i + 1] === "/")) {
+ out += src[i] === "\n" ? "\n" : " ";
+ i++;
+ }
+ out += " ";
+ i += 2;
+ } else if (c === '"' || c === "'" || c === "`") {
+ const quote = c;
+ out += " ";
+ i++;
+ while (i < src.length && src[i] !== quote) {
+ if (src[i] === "\\" && i + 1 < src.length) { out += " "; i += 2; continue; }
+ out += src[i] === "\n" ? "\n" : " ";
+ i++;
+ }
+ out += " ";
+ i++;
+ } else {
+ out += c;
+ i++;
+ }
+ }
+ return out;
+};
+
+// Collect every relative ".ts" import edge in a file. Scans raw
+// source: a stripped copy would erase the quoted import paths along
+// with all other string literals, so the regex must run over the
+// original. To avoid picking up import-like strings inside test
+// fixtures, we cross-check each match position against the stripped
+// mask — if the keyword `from` lands on whitespace in the mask, it
+// was inside a string literal and we skip it.
+const collectRelativeImports = (content: string): string[] => {
+ const mask = stripStringsAndComments(content);
+ const re = /\bfrom\s+["'](\.\/[A-Za-z0-9_./-]+\.ts)["']/g;
+ const out: string[] = [];
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(content)) !== null) {
+ // If the `from` keyword position is whitespace in the mask, the
+ // entire match was inside a string literal (e.g. a test fixture).
+ if (mask[m.index] === " " || mask[m.index] === "\n") continue;
+ if (m[1]) out.push(m[1]);
+ }
+ return out;
+};
+
+// Resolve a relative import like "./c14_git.ts" from the importing
+// file's directory to the repo-relative path used as the input map's
+// key (e.g. "src/c14_git.ts").
+const resolveImport = (fromPath: string, importPath: string): string => {
+ const dir = fromPath.split("/").slice(0, -1).join("/");
+ const rel = importPath.replace(/^\.\//, "");
+ return dir + "/" + rel;
+};
+
+// — Check 1: Sorted -------------------------------------------------
+//
+// "Every file carries a profile-recognised prefix; lexicographic
+// prefix order equals layer order."
+const checkSorted = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ // Collect (prefix, layer) pairs from the profile.
+ const pairs: Array<{ prefix: string; layer: number }> = [];
+ for (const [k, spec] of Object.entries(input.profile.layers)) {
+ const layer = parseInt(k, 10);
+ for (const sub of spec.sublayers) pairs.push({ prefix: sub.prefix, layer });
+ }
+ // For any two prefixes with layer(A) < layer(B), A must lex-sort < B.
+ for (let i = 0; i < pairs.length; i++) {
+ for (let j = 0; j < pairs.length; j++) {
+ if (i === j) continue;
+ const a = pairs[i]!;
+ const b = pairs[j]!;
+ if (a.layer < b.layer && a.prefix > b.prefix) {
+ violations.push({
+ file: a.prefix,
+ detail: `prefix \`${a.prefix}\` (layer ${a.layer}) sorts after \`${b.prefix}\` (layer ${b.layer}) — lex order must equal layer order`,
+ });
+ }
+ }
+ }
+ // Also count source files whose prefix isn't recognised by any
+ // sublayer. They'd be flagged by Architecture too, but the Sorted
+ // rule needs each file to have a recognised prefix.
+ for (const path of input.files.keys()) {
+ if (!isSamaFile(path)) continue;
+ examined++;
+ if (declaredLayer(path, input.profile) === null) {
+ violations.push({ file: path, detail: "no profile-recognised prefix" });
+ }
+ }
+ return {
+ id: 1, name: "Sorted", property: "Sorted",
+ passed: violations.length === 0, examined, violations,
+ };
+};
+
+// — Check 2: Architecture -------------------------------------------
+//
+// "Every file maps to exactly one canonical layer; no file is
+// unprefixed or maps to two layers."
+const checkArchitecture = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ for (const path of input.files.keys()) {
+ if (!isSamaFile(path) && !isTestFile(path)) continue;
+ examined++;
+ const base = path.split("/").pop() ?? path;
+ // Find every profile prefix that matches this filename. Exactly
+ // one is required; zero = unprefixed (caught by Sorted too) but
+ // we surface it here as the canonical "unmapped" failure.
+ const matches: Array<{ layer: number; prefix: string }> = [];
+ for (const [k, spec] of Object.entries(input.profile.layers)) {
+ const layer = parseInt(k, 10);
+ for (const sub of spec.sublayers) {
+ if (base.startsWith(sub.prefix)) matches.push({ layer, prefix: sub.prefix });
+ }
+ }
+ if (matches.length === 0) {
+ violations.push({ file: path, detail: "unprefixed — does not match any profile prefix" });
+ } else if (matches.length > 1) {
+ // Two prefixes claim the same file: profile ambiguity.
+ const distinctLayers = new Set(matches.map((m) => m.layer));
+ if (distinctLayers.size > 1) {
+ violations.push({
+ file: path,
+ detail: `ambiguous — matches multiple layers: ${matches.map((m) => `${m.prefix}→L${m.layer}`).join(", ")}`,
+ });
+ }
+ }
+ }
+ return {
+ id: 2, name: "Architecture", property: "Architecture",
+ passed: violations.length === 0, examined, violations,
+ };
+};
+
+// — Check 3: Modeled (tests) ----------------------------------------
+//
+// "Every Layer 1 and Layer 2 behavior file has a sibling test file."
+const checkModeledTests = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ for (const path of input.files.keys()) {
+ if (!isSamaFile(path)) continue;
+ const decl = declaredLayer(path, input.profile);
+ if (!decl) continue;
+ if (decl.layer !== 1 && decl.layer !== 2) continue;
+ examined++;
+ const siblingPath = path.replace(/\.ts$/, ".test.ts");
+ if (!input.files.has(siblingPath)) {
+ violations.push({
+ file: path,
+ detail: `no sibling test at \`${siblingPath}\` — Layer ${decl.layer} requires one`,
+ });
+ }
+ }
+ return {
+ id: 3, name: "Modeled (tests)", property: "Modeled (tests)",
+ passed: violations.length === 0, examined, violations,
+ };
+};
+
+// — Check 4: Modeled (boundary) -------------------------------------
+//
+// "External input is parsed only in Layer 2."
+//
+// §4.4 is profile-dependent (spec §6). Our profile defines boundary
+// parsing as `JSON.parse(` of arbitrary input (not constant strings)
+// or `new URL(` of arbitrary input — i.e. patterns that turn bytes
+// into typed structures. Platform-provided parsers called *through*
+// Layer 3 entry handlers (`req.json()`, `req.formData()`, route
+// params) are treated as delegation to the platform's own Layer 2,
+// not parsing performed in our Layer 3. The verifier reports any
+// raw JSON.parse / new URL calls landing outside Layer 2.
+const BOUNDARY_PATTERNS = [
+ { name: "JSON.parse", re: /\bJSON\.parse\s*\(/ },
+ { name: "new URL", re: /\bnew\s+URL\s*\(/ },
+];
+const checkModeledBoundary = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ for (const [path, content] of input.files.entries()) {
+ if (!isSamaFile(path)) continue;
+ const decl = declaredLayer(path, input.profile);
+ if (!decl) continue;
+ examined++;
+ if (decl.layer === 2) continue; // Layer 2 is the legitimate site.
+ const stripped = stripStringsAndComments(content);
+ for (const pat of BOUNDARY_PATTERNS) {
+ if (pat.re.test(stripped)) {
+ violations.push({
+ file: path,
+ detail: `boundary pattern \`${pat.name}\` found in Layer ${decl.layer} — parsing belongs in Layer 2`,
+ });
+ }
+ }
+ }
+ return {
+ id: 4, name: "Modeled (boundary)", property: "Modeled (boundary)",
+ passed: violations.length === 0, examined, violations,
+ note: "profile-dependent (spec §4.4): boundary = raw `JSON.parse` / `new URL` outside Layer 2. Platform parsers reached via `req.json()` etc. are treated as delegation to the platform's own Layer 2.",
+ };
+};
+
+// — Check 5: Atomic -------------------------------------------------
+//
+// "No file exceeds the line cap (default ~700; profile may lower,
+// never raise). No barrel re-export files."
+const ATOMIC_LINE_CAP = 700;
+const checkAtomic = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ for (const [path, content] of input.files.entries()) {
+ if (!isSamaFile(path) && !isTestFile(path)) continue;
+ examined++;
+ const lines = content.split("\n").length;
+ if (lines > ATOMIC_LINE_CAP) {
+ violations.push({
+ file: path,
+ detail: `${lines} lines (over the ${ATOMIC_LINE_CAP}-line cap — split per UI/data domain)`,
+ });
+ }
+ // Barrel detection: a file whose entire body is re-exports.
+ // Heuristic: every non-blank, non-comment line is `export ... from`.
+ const stripped = stripStringsAndComments(content);
+ const codeLines = stripped.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+ if (codeLines.length >= 2 && codeLines.every((l) => /^export\s+(\*|\{)/.test(l) && /\bfrom\b/.test(l))) {
+ violations.push({ file: path, detail: "barrel re-export file (all lines are `export … from`)" });
+ }
+ }
+ return {
+ id: 5, name: "Atomic", property: "Atomic",
+ passed: violations.length === 0, examined, violations,
+ };
+};
+
+// — Check 6: The Law (§1.2) -----------------------------------------
+//
+// "Imports always point to a strictly lower layer number — never
+// upward, never sideways across a higher number, never cyclic."
+//
+// Build the import graph from relative-.ts imports, then for each
+// edge A → B require: layer(B) < layer(A), OR same layer + B's
+// sublayer index <= A's sublayer index. Also run a DFS cycle detector.
+const checkLaw = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ // Build adjacency.
+ const adj = new Map();
+ for (const [path, content] of input.files.entries()) {
+ if (!isSamaFile(path) && !isTestFile(path)) continue;
+ examined++;
+ const out: string[] = [];
+ for (const imp of collectRelativeImports(content)) {
+ const resolved = resolveImport(path, imp);
+ // Only follow edges into known SAMA files (in-tree, in src/).
+ if (input.files.has(resolved)) out.push(resolved);
+ }
+ adj.set(path, out);
+ }
+ // Edge-by-edge layer/sublayer check.
+ for (const [from, outs] of adj.entries()) {
+ const aDecl = declaredLayer(from, input.profile);
+ if (!aDecl) continue; // Unmapped — caught by Architecture.
+ for (const to of outs) {
+ const bDecl = declaredLayer(to, input.profile);
+ if (!bDecl) continue;
+ if (bDecl.layer < aDecl.layer) continue; // strictly lower — OK
+ if (bDecl.layer > aDecl.layer) {
+ violations.push({
+ file: from,
+ detail: `imports \`${to}\` — Layer ${aDecl.layer} → Layer ${bDecl.layer} (upward, breaks §1.2)`,
+ });
+ continue;
+ }
+ // Same layer: sublayer ordering. The import target must be in
+ // an earlier-or-equal sublayer slot (spec §2.2: later may import
+ // earlier).
+ if (bDecl.sublayer.index > aDecl.sublayer.index) {
+ violations.push({
+ file: from,
+ detail: `imports \`${to}\` — same layer ${aDecl.layer} but sublayer order is reversed (${aDecl.sublayer.name} sublayer-index ${aDecl.sublayer.index} → ${bDecl.sublayer.name} sublayer-index ${bDecl.sublayer.index})`,
+ });
+ }
+ }
+ }
+ // DFS cycle detection on the same graph.
+ const WHITE = 0, GRAY = 1, BLACK = 2;
+ const color = new Map();
+ for (const k of adj.keys()) color.set(k, WHITE);
+ const cycles: string[][] = [];
+ const stack: string[] = [];
+ const dfs = (node: string): boolean => {
+ color.set(node, GRAY);
+ stack.push(node);
+ for (const next of adj.get(node) ?? []) {
+ const c = color.get(next) ?? WHITE;
+ if (c === GRAY) {
+ const idx = stack.indexOf(next);
+ if (idx !== -1) cycles.push([...stack.slice(idx), next]);
+ return true;
+ }
+ if (c === WHITE && dfs(next)) {
+ // bubble up
+ }
+ }
+ stack.pop();
+ color.set(node, BLACK);
+ return false;
+ };
+ for (const k of adj.keys()) if (color.get(k) === WHITE) dfs(k);
+ for (const cyc of cycles) {
+ violations.push({
+ file: cyc[0] ?? "(unknown)",
+ detail: `import cycle: ${cyc.join(" → ")}`,
+ });
+ }
+ return {
+ id: 6, name: "Law (§1.2)", property: "Law",
+ passed: violations.length === 0, examined, violations,
+ };
+};
+
+// — Check 7: Consistency (§3) ---------------------------------------
+//
+// "Verifier FAILS if a file imports from a layer that its declared
+// layer is not permitted to import." This is the same set of edges
+// the Law check examines, framed from the file's own perspective:
+// does the prefix lie about what the file actually does?
+//
+// We emit a separate verdict so the report can show both framings.
+// In a profile where no §1.2 violation exists, §3 also passes by
+// construction — both are derived from the same edge set.
+const checkConsistency = (input: SamaV2Input): SamaV2Check => {
+ const violations: SamaV2Violation[] = [];
+ let examined = 0;
+ for (const [path, content] of input.files.entries()) {
+ if (!isSamaFile(path)) continue;
+ const aDecl = declaredLayer(path, input.profile);
+ if (!aDecl) continue;
+ examined++;
+ let ceiling = -1;
+ let ceilingFile: string | null = null;
+ for (const imp of collectRelativeImports(content)) {
+ const resolved = resolveImport(path, imp);
+ const bDecl = declaredLayer(resolved, input.profile);
+ if (!bDecl) continue;
+ if (bDecl.layer > ceiling) { ceiling = bDecl.layer; ceilingFile = resolved; }
+ }
+ // Consistency fails if any import goes to a strictly higher
+ // layer than the file's declared layer. Same-layer with bad
+ // sublayer order is the Law's concern, not Consistency's.
+ if (ceiling > aDecl.layer) {
+ violations.push({
+ file: path,
+ detail: `declared Layer ${aDecl.layer} (prefix \`${aDecl.sublayer.prefix}\`) but imports reach Layer ${ceiling} via \`${ceilingFile}\` — the prefix claims something the imports contradict`,
+ });
+ }
+ }
+ return {
+ id: 7, name: "Consistency (§3)", property: "Consistency",
+ passed: violations.length === 0, examined, violations,
+ };
+};
+
+// — Orchestrator ----------------------------------------------------
+
+export const verifySamaV2 = (input: SamaV2Input): SamaV2Report => {
+ const checks: SamaV2Check[] = [
+ checkSorted(input),
+ checkArchitecture(input),
+ checkModeledTests(input),
+ checkModeledBoundary(input),
+ checkAtomic(input),
+ checkLaw(input),
+ checkConsistency(input),
+ ];
+ // Architecture's examined count is the canonical total — it counts
+ // every file the profile assigns to a layer (or fails to).
+ const examined = checks.find((c) => c.id === 2)?.examined ?? 0;
+ return {
+ profile: input.profile.profile,
+ examined,
+ checks,
+ overallPassed: checks.every((c) => c.passed),
+ };
+};
diff --git a/src/b32_sama_verify.test.ts b/src/b32_sama_verify.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8d1d0c99462fadb53fd924ed6258ed936bdb0c77
--- /dev/null
+++ b/src/b32_sama_verify.test.ts
@@ -0,0 +1,137 @@
+import { test, expect } from "bun:test";
+import { verifySama } from "./b32_sama_verify.ts";
+
+const baseInput = {
+ repoOwner: "test",
+ repoName: "repo",
+ defaultBranch: "main",
+ srcPaths: [] as string[],
+ contents: new Map(),
+};
+
+test("empty input: all checks pass, sorted has a 'no SAMA files' note", () => {
+ const r = verifySama(baseInput);
+ expect(r.overallPassed).toBe(true);
+ const sorted = r.checks.find((c) => c.letter === "S")!;
+ expect(sorted.passed).toBe(true);
+ expect(sorted.examined).toBe(0);
+ expect(sorted.note).toMatch(/no cXX_\*\.ts files found/);
+});
+
+test("Sorted: c14 importing c51 is flagged", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c14_io.ts", "c51_render.ts"],
+ contents: new Map([
+ ["c14_io.ts", `import { x } from "./c51_render.ts";`],
+ ["c51_render.ts", "export const x = 1;"],
+ ]),
+ });
+ const sorted = r.checks.find((c) => c.letter === "S")!;
+ expect(sorted.passed).toBe(false);
+ expect(sorted.violations[0]?.file).toBe("c14_io.ts");
+ expect(sorted.violations[0]?.detail).toMatch(/UI/);
+});
+
+test("Sorted: c21 importing c51 is NOT flagged (handlers may compose UI)", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c21_handler.ts", "c51_render.ts"],
+ contents: new Map([
+ ["c21_handler.ts", `import { x } from "./c51_render.ts";`],
+ ["c51_render.ts", "export const x = 1;"],
+ ]),
+ });
+ const sorted = r.checks.find((c) => c.letter === "S")!;
+ expect(sorted.passed).toBe(true);
+});
+
+test("Sorted: c31 importing c32 (sibling layer, non-UI) is NOT flagged", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c31_model.ts", "c32_logic.ts"],
+ contents: new Map([
+ ["c31_model.ts", `import { x } from "./c32_logic.ts";`],
+ ["c32_logic.ts", "export const x = 1;"],
+ ]),
+ });
+ const sorted = r.checks.find((c) => c.letter === "S")!;
+ expect(sorted.passed).toBe(true);
+});
+
+test("Architecture: unknown prefix is flagged", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c99_thing.ts"],
+ contents: new Map([["c99_thing.ts", "export const x = 1;"]]),
+ });
+ const arch = r.checks.find((c) => c.property === "Architecture")!;
+ expect(arch.passed).toBe(false);
+ expect(arch.violations[0]?.detail).toMatch(/unknown layer prefix/);
+});
+
+test("Modeled: c32 file without sibling test is flagged; c31 without sibling is informational", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c32_logic.ts", "c31_model.ts"],
+ contents: new Map([
+ ["c32_logic.ts", "export const x = 1;"],
+ ["c31_model.ts", "export const y = 2;"],
+ ]),
+ });
+ const modeled = r.checks.find((c) => c.property === "Modeled")!;
+ expect(modeled.passed).toBe(false);
+ expect(modeled.violations.length).toBe(1);
+ expect(modeled.violations[0]?.file).toBe("c32_logic.ts");
+ expect(modeled.note).toMatch(/c31_\* file/);
+});
+
+test("Modeled: c32 file with sibling test passes", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c32_logic.ts", "c32_logic.test.ts"],
+ contents: new Map([
+ ["c32_logic.ts", "export const x = 1;"],
+ ["c32_logic.test.ts", "test('x', () => { expect(true).toBe(true); });"],
+ ]),
+ });
+ const modeled = r.checks.find((c) => c.property === "Modeled")!;
+ expect(modeled.passed).toBe(true);
+});
+
+test("Atomic: file over 700 lines is flagged", () => {
+ const big = "// line\n".repeat(800);
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c21_huge.ts"],
+ contents: new Map([["c21_huge.ts", big]]),
+ });
+ const atomic = r.checks.find((c) => c.property === "Atomic")!;
+ expect(atomic.passed).toBe(false);
+ expect(atomic.violations[0]?.detail).toMatch(/line/);
+});
+
+test("Atomic: placeholder test (zero expect calls) is flagged", () => {
+ const placeholderFixture = `test("does nothing", () => { /* TODO */ })`;
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c32_x.test.ts"],
+ contents: new Map([["c32_x.test.ts", placeholderFixture]]),
+ });
+ const atomic = r.checks.find((c) => c.property === "Atomic")!;
+ expect(atomic.passed).toBe(false);
+ expect(atomic.violations[0]?.detail).toMatch(/placeholder test/);
+});
+
+test("overallPassed reflects every check passing", () => {
+ const r = verifySama({
+ ...baseInput,
+ srcPaths: ["c31_model.ts", "c32_logic.ts", "c32_logic.test.ts"],
+ contents: new Map([
+ ["c31_model.ts", "export const x = 1;"],
+ ["c32_logic.ts", `import { x } from "./c31_model.ts";\nexport const y = x + 1;`],
+ ["c32_logic.test.ts", `import { y } from "./c32_logic.ts";\ntest("y", () => { expect(y).toBe(2); });`],
+ ]),
+ });
+ expect(r.overallPassed).toBe(true);
+});
diff --git a/src/b32_sama_verify.ts b/src/b32_sama_verify.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0564493da312bde26ba6a477c4409a9306ca2de9
--- /dev/null
+++ b/src/b32_sama_verify.ts
@@ -0,0 +1,347 @@
+// c32 — logic: pure SAMA verification given a repo's file tree and the
+// contents of every cXX_*.ts file. Drives /sama/verify.
+//
+// Verifier is intentionally strict: a check passes iff there is zero
+// evidence of violation. The four properties (S/A/M/A) each become one
+// callable, and the top-level `verifySama(...)` runs them all and
+// returns a SamaReport.
+
+export interface SamaViolation {
+ file: string;
+ detail: string;
+}
+
+export interface SamaCheckResult {
+ letter: "S" | "A" | "M" | "A";
+ property: "Sorted" | "Architecture" | "Modeled" | "Atomic";
+ passed: boolean;
+ examined: number;
+ violations: SamaViolation[];
+ note?: string;
+}
+
+export interface SamaReport {
+ repoSlug: string;
+ defaultBranch: string;
+ totalSrcFiles: number;
+ samaFiles: number;
+ testFiles: number;
+ checks: SamaCheckResult[];
+ overallPassed: boolean;
+ generatedAt: number;
+}
+
+export interface SamaVerifyInput {
+ repoOwner: string;
+ repoName: string;
+ defaultBranch: string;
+ // src-relative paths, e.g. "c21_app.ts", "c31_blog.ts", "c32_session.test.ts"
+ srcPaths: string[];
+ // file path -> content. Contents only required for cXX_*.ts files
+ // and *.test.ts files.
+ contents: Map;
+}
+
+const SAMA_PREFIX = /^c(\d{2})_/;
+
+// Strip JS string literals and comments from source, preserving
+// position/length by replacing each character with whitespace. This
+// is the cheapest reliable fix for the test-fixture false-positive:
+// import strings and `test(...)` patterns inside literals/comments
+// would otherwise trigger Sorted/Atomic violations.
+export const stripStringsAndComments = (src: string): string => {
+ let out = "";
+ let i = 0;
+ while (i < src.length) {
+ const c = src[i];
+ const n = src[i + 1];
+ if (c === "/" && n === "/") {
+ out += " ";
+ i += 2;
+ while (i < src.length && src[i] !== "\n") {
+ out += " ";
+ i++;
+ }
+ } else if (c === "/" && n === "*") {
+ out += " ";
+ i += 2;
+ while (i < src.length - 1 && !(src[i] === "*" && src[i + 1] === "/")) {
+ out += src[i] === "\n" ? "\n" : " ";
+ i++;
+ }
+ out += " ";
+ i += 2;
+ } else if (c === '"' || c === "'" || c === "`") {
+ const quote = c;
+ out += " ";
+ i++;
+ while (i < src.length && src[i] !== quote) {
+ if (src[i] === "\\" && i + 1 < src.length) {
+ out += " ";
+ i += 2;
+ continue;
+ }
+ out += src[i] === "\n" ? "\n" : " ";
+ i++;
+ }
+ out += " ";
+ i++;
+ } else {
+ out += c ?? "";
+ i++;
+ }
+ }
+ return out;
+};
+
+const isSamaFile = (p: string): boolean => SAMA_PREFIX.test(p) && p.endsWith(".ts");
+const isTestFile = (p: string): boolean => p.endsWith(".test.ts");
+
+const layerOf = (filename: string): number | null => {
+ const m = SAMA_PREFIX.exec(filename);
+ if (!m) return null;
+ return parseInt(m[1] ?? "0", 10);
+};
+
+// Pull import targets out of a TypeScript source. Recognizes both
+// static `import ... from "./x.ts"` and dynamic `import("./x.ts")`.
+// We only care about relative imports (the cross-layer ones). We
+// scan against a stripped source (string literals + comments
+// blanked out) so test fixtures that quote import statements as
+// data don't cause false positives.
+const collectRelativeImports = (source: string): string[] => {
+ const out: string[] = [];
+ // Match against the original source so the captured import path
+ // text is preserved; but only accept matches whose start position
+ // is NOT inside a string-literal/comment region (we test that by
+ // checking the stripped source's character at the path-open quote).
+ const stripped = stripStringsAndComments(source);
+ const staticRe = /\bfrom\s+(["'])\s*(\.\/[^"']+)\1/g;
+ const dynRe = /\bimport\s*\(\s*(["'])\s*(\.\/[^"']+)\1/g;
+ let m: RegExpExecArray | null;
+ const pushIfReal = (mm: RegExpExecArray, pathIdx: number) => {
+ // Check the start of the match (the `f` of `from` or `i` of
+ // `import`). If that keyword is inside a string literal/comment
+ // in the original source, the stripped version replaces it with
+ // whitespace and we skip the match. The PATH itself is always
+ // inside quotes (that's how imports are written), so we never
+ // gate on the path's position — only the keyword's.
+ if (stripped[mm.index] === " " || stripped[mm.index] === "\n") return;
+ out.push(mm[pathIdx]!);
+ };
+ while ((m = staticRe.exec(source)) !== null) pushIfReal(m, 2);
+ while ((m = dynRe.exec(source)) !== null) pushIfReal(m, 2);
+ return out;
+};
+
+const importTargetFilename = (importPath: string): string => {
+ // "./c14_github.ts" -> "c14_github.ts"
+ return importPath.replace(/^\.\//, "");
+};
+
+// S — Sorted. The rule, as practiced: foundation, data and logic layers
+// (c1*, c3*) don't import UI (c5*+). c21 (handlers/composers) is the
+// orchestration layer and is allowed to import anything; c51 (UI) is
+// allowed to import models (c3*) for the data it renders. A strict
+// "lower never imports higher" reading would forbid c21 → c31, which
+// is the natural pattern (handler composes model). The actual
+// constraint is one-directional: UI sits at the edge, never below.
+const checkSorted = (input: SamaVerifyInput): SamaCheckResult => {
+ const violations: SamaViolation[] = [];
+ let examined = 0;
+ for (const path of input.srcPaths) {
+ if (!isSamaFile(path)) continue;
+ examined++;
+ const m = SAMA_PREFIX.exec(path);
+ const prefix = m?.[1] ?? "";
+ // Skip c2* (handlers, allowed to depend on anything) and c5*+ (UI,
+ // its outbound deps are governed by other rules, not this one).
+ if (!/^[13]/.test(prefix)) continue;
+ const content = input.contents.get(path);
+ if (!content) continue;
+ for (const rawImport of collectRelativeImports(content)) {
+ const target = importTargetFilename(rawImport);
+ const targetMatch = SAMA_PREFIX.exec(target);
+ const targetPrefix = targetMatch?.[1] ?? "";
+ if (!targetPrefix) continue;
+ if (/^[59]/.test(targetPrefix)) {
+ violations.push({
+ file: path,
+ detail: `imports \`${target}\` (UI layer c${targetPrefix}_) from a non-UI/non-handler file (c${prefix}_) — UI sits at the edge, foundation/data/logic must not depend on it`,
+ });
+ }
+ }
+ }
+ return {
+ letter: "S",
+ property: "Sorted",
+ passed: violations.length === 0,
+ examined,
+ violations,
+ note: examined === 0
+ ? "no cXX_*.ts files found in the project — the convention isn't applied here"
+ : undefined,
+ };
+};
+
+// A — Architecture. Each prefix is a known layer; flag unknown prefixes.
+const KNOWN_LAYERS = new Set(["11", "13", "14", "21", "31", "32", "51"]);
+const checkArchitecture = (input: SamaVerifyInput): SamaCheckResult => {
+ const violations: SamaViolation[] = [];
+ let examined = 0;
+ for (const path of input.srcPaths) {
+ if (!isSamaFile(path)) continue;
+ examined++;
+ const m = SAMA_PREFIX.exec(path);
+ const prefix = m?.[1] ?? "";
+ if (!KNOWN_LAYERS.has(prefix)) {
+ violations.push({
+ file: path,
+ detail: `unknown layer prefix \`c${prefix}_\` (known: c11, c13, c14, c21, c31, c32, c51)`,
+ });
+ }
+ }
+ return {
+ letter: "A",
+ property: "Architecture",
+ passed: violations.length === 0,
+ examined,
+ violations,
+ };
+};
+
+// M — Modeled. Tests live next to source. Every cXX_.ts (non-data)
+// should have a sibling cXX_.test.ts. Pure data files (registries
+// like c31_blog.ts that are just an exported array) often legitimately
+// have no behaviour to test, so we soften this check by requiring a
+// sibling for c32_*.ts (logic) at minimum, and reporting a list of c31
+// files without siblings as informational rather than hard violations.
+const checkModeled = (input: SamaVerifyInput): SamaCheckResult => {
+ const violations: SamaViolation[] = [];
+ const informational: SamaViolation[] = [];
+ let examined = 0;
+ const present = new Set(input.srcPaths);
+ for (const path of input.srcPaths) {
+ if (!isSamaFile(path) || isTestFile(path)) continue;
+ examined++;
+ const sibling = path.replace(/\.ts$/, ".test.ts");
+ if (present.has(sibling)) continue;
+ const layer = layerOf(path);
+ if (layer === 32) {
+ violations.push({ file: path, detail: `no sibling test file at \`${sibling}\`` });
+ } else if (layer === 31) {
+ informational.push({ file: path, detail: `no sibling test (often fine for pure data registries; flag if logic accumulates)` });
+ }
+ }
+ const passed = violations.length === 0;
+ const note = informational.length > 0
+ ? `${informational.length} c31_* file${informational.length === 1 ? "" : "s"} without a sibling test — usually fine for pure-data registries, flag if logic accumulates: ${informational.map((v) => v.file).join(", ")}`
+ : undefined;
+ return {
+ letter: "M",
+ property: "Modeled",
+ passed,
+ examined,
+ violations,
+ note,
+ };
+};
+
+// A — Atomic. ~700-line split rule. Flag any cXX_*.ts over 700 lines.
+// Also flag placeholder tests (zero expect() calls in test body) as
+// part of the same pass — they're a structural violation of the
+// testing surface that Atomic owns.
+const findPlaceholderTestsLite = (file: string, content: string): SamaViolation[] => {
+ const out: SamaViolation[] = [];
+ // Same string/comment-aware trick as collectRelativeImports: only
+ // count test()/it() calls whose `test`/`it` keyword is real code,
+ // not a literal in a fixture.
+ const stripped = stripStringsAndComments(content);
+ const re = /\b(test|it)\s*\(\s*(["'`])((?:\\.|(?!\2).)*)\2\s*,\s*(?:async\s+)?(?:\([^)]*\)|[^=()]*?)\s*=>\s*\{/g;
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(content)) !== null) {
+ // Skip matches whose `test`/`it` keyword is inside a string literal
+ // or comment (the stripped version replaces those with whitespace).
+ if (stripped[m.index] === " " || stripped[m.index] === "\n") continue;
+ const name = m[3] ?? "";
+ const startBrace = re.lastIndex - 1;
+ let depth = 1;
+ let i = startBrace + 1;
+ let inString: string | null = null;
+ while (i < content.length && depth > 0) {
+ const c = content[i];
+ if (inString !== null) {
+ if (c === "\\") { i += 2; continue; }
+ if (c === inString) inString = null;
+ } else {
+ if (c === '"' || c === "'" || c === "`") inString = c;
+ else if (c === "/" && content[i + 1] === "/") {
+ while (i < content.length && content[i] !== "\n") i++;
+ continue;
+ } else if (c === "/" && content[i + 1] === "*") {
+ i += 2;
+ while (i < content.length - 1 && !(content[i] === "*" && content[i + 1] === "/")) i++;
+ i += 2;
+ continue;
+ } else if (c === "{") depth++;
+ else if (c === "}") depth--;
+ }
+ i++;
+ }
+ const body = content.slice(startBrace + 1, i - 1);
+ const expectCount = (body.match(/\bexpect\s*\(/g) ?? []).length;
+ if (expectCount === 0) {
+ out.push({ file, detail: `placeholder test \`${name}\` — zero \`expect()\` calls` });
+ }
+ }
+ return out;
+};
+
+const checkAtomic = (input: SamaVerifyInput): SamaCheckResult => {
+ const violations: SamaViolation[] = [];
+ let examined = 0;
+ for (const path of input.srcPaths) {
+ if (!isSamaFile(path)) continue;
+ examined++;
+ const content = input.contents.get(path);
+ if (!content) continue;
+ const lineCount = content.split("\n").length;
+ if (lineCount > 700) {
+ violations.push({
+ file: path,
+ detail: `${lineCount} lines (over the 700-line split threshold — split per UI/data domain)`,
+ });
+ }
+ if (isTestFile(path)) {
+ violations.push(...findPlaceholderTestsLite(path, content));
+ }
+ }
+ return {
+ letter: "A",
+ property: "Atomic",
+ passed: violations.length === 0,
+ examined,
+ violations,
+ };
+};
+
+export const verifySama = (input: SamaVerifyInput): SamaReport => {
+ const samaPaths = input.srcPaths.filter(isSamaFile);
+ const testPaths = samaPaths.filter(isTestFile);
+ const checks = [
+ checkSorted(input),
+ checkArchitecture(input),
+ checkModeled(input),
+ checkAtomic(input),
+ ];
+ return {
+ repoSlug: `${input.repoOwner}/${input.repoName}`,
+ defaultBranch: input.defaultBranch,
+ totalSrcFiles: input.srcPaths.length,
+ samaFiles: samaPaths.length,
+ testFiles: testPaths.length,
+ checks,
+ overallPassed: checks.every((c) => c.passed),
+ generatedAt: Date.now(),
+ };
+};
diff --git a/src/b32_session.test.ts b/src/b32_session.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d9d1cc9077d72802e22c9ec5262d111dddb5ac0a
--- /dev/null
+++ b/src/b32_session.test.ts
@@ -0,0 +1,179 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import {
+ parseCookies,
+ timingSafeEqual,
+ hmacSha256Hex,
+ sessionCookieHeader,
+ randomHex,
+ signSession,
+ verifySession,
+ SESSION_TTL_SEC,
+} from "./b32_session.ts";
+
+describe("c32_session — parseCookies", () => {
+ test("empty / null header returns an empty object", () => {
+ expect(parseCookies(null)).toEqual({});
+ expect(parseCookies("")).toEqual({});
+ });
+
+ test("parses a single name=value pair", () => {
+ expect(parseCookies("tdd_session=abc")).toEqual({ tdd_session: "abc" });
+ });
+
+ test("parses multiple pairs separated by `;`", () => {
+ const out = parseCookies("a=1; b=2; c=3");
+ expect(out).toEqual({ a: "1", b: "2", c: "3" });
+ });
+
+ test("strips surrounding whitespace from name and value", () => {
+ expect(parseCookies(" k = v ")).toEqual({ k: "v" });
+ });
+
+ test("url-decodes values", () => {
+ expect(parseCookies("path=%2Ffoo%2Fbar")).toEqual({ path: "/foo/bar" });
+ });
+
+ test("ignores entries that have no `=` separator", () => {
+ expect(parseCookies("malformed; ok=yes")).toEqual({ ok: "yes" });
+ });
+});
+
+describe("c32_session — timingSafeEqual", () => {
+ test("returns true for identical strings", () => {
+ expect(timingSafeEqual("hello", "hello")).toBe(true);
+ });
+
+ test("returns false for different strings of the same length", () => {
+ expect(timingSafeEqual("hello", "world")).toBe(false);
+ });
+
+ test("returns false when lengths differ — early exit", () => {
+ expect(timingSafeEqual("a", "ab")).toBe(false);
+ });
+
+ test("returns true for two empty strings", () => {
+ expect(timingSafeEqual("", "")).toBe(true);
+ });
+});
+
+describe("c32_session — hmacSha256Hex", () => {
+ test("is deterministic for a fixed (secret, body) pair", async () => {
+ const a = await hmacSha256Hex("s3cret", "payload");
+ const b = await hmacSha256Hex("s3cret", "payload");
+ expect(a).toBe(b);
+ });
+
+ test("returns a 64-char lowercase hex string (SHA-256 hex length)", async () => {
+ const sig = await hmacSha256Hex("k", "v");
+ expect(sig).toMatch(/^[0-9a-f]{64}$/);
+ });
+
+ test("a different secret produces a different signature for the same body", async () => {
+ const a = await hmacSha256Hex("secret-a", "payload");
+ const b = await hmacSha256Hex("secret-b", "payload");
+ expect(a).not.toBe(b);
+ });
+
+ test("a different body produces a different signature for the same secret", async () => {
+ const a = await hmacSha256Hex("k", "body-a");
+ const b = await hmacSha256Hex("k", "body-b");
+ expect(a).not.toBe(b);
+ });
+});
+
+describe("c32_session — sessionCookieHeader", () => {
+ test("formats the canonical attributes", () => {
+ const h = sessionCookieHeader("token-x", 3600);
+ expect(h).toContain("tdd_session=token-x");
+ expect(h).toContain("Path=/");
+ expect(h).toContain("HttpOnly");
+ expect(h).toContain("Secure");
+ expect(h).toContain("SameSite=Lax");
+ expect(h).toContain("Max-Age=3600");
+ });
+
+ test("zero max-age (logout) still emits Max-Age=0", () => {
+ expect(sessionCookieHeader("", 0)).toContain("Max-Age=0");
+ });
+});
+
+describe("c32_session — randomHex", () => {
+ test("returns a hex string of 2 × bytes characters", () => {
+ expect(randomHex(8)).toMatch(/^[0-9a-f]{16}$/);
+ expect(randomHex(16)).toMatch(/^[0-9a-f]{32}$/);
+ });
+
+ test("successive calls produce distinct values", () => {
+ expect(randomHex(16)).not.toBe(randomHex(16));
+ });
+});
+
+describe("c32_session — signSession / verifySession round-trip", () => {
+ // The signer reads SESSION_SECRET (or WEBHOOK_SECRET) from the env.
+ // Set a fixed value before the tests run so both sides hash with the
+ // same key. beforeAll/afterAll, not bare describe-body, because the
+ // body runs at registration time while tests run async — restoration
+ // there would happen *before* any test executes.
+ let original: string | undefined;
+ beforeAll(() => {
+ original = process.env.SESSION_SECRET;
+ process.env.SESSION_SECRET = "test-secret-do-not-use-in-prod";
+ });
+ afterAll(() => {
+ if (original === undefined) {
+ delete process.env.SESSION_SECRET;
+ } else {
+ process.env.SESSION_SECRET = original;
+ }
+ });
+
+ test("signSession produces a 3-part cookie of `name.exp.sig`", async () => {
+ const cookie = await signSession("alice");
+ const parts = cookie.split(".");
+ expect(parts.length).toBe(3);
+ expect(parts[0]).toBe("alice");
+ expect(Number(parts[1])).toBeGreaterThan(Math.floor(Date.now() / 1000));
+ });
+
+ test("verifySession round-trips a freshly signed cookie back to the username", async () => {
+ const cookie = await signSession("bob");
+ const username = await verifySession(cookie);
+ expect(username).toBe("bob");
+ });
+
+ test("verifySession rejects a cookie with a forged signature", async () => {
+ const cookie = await signSession("eve");
+ // Flip the LAST sig char to something *guaranteed* different —
+ // a fixed `replace(/.$/, "0")` collides when the original char is
+ // already "0" (~1 in 16 runs). Detect the original and flip to
+ // a hex digit it can never be.
+ const lastChar = cookie.slice(-1);
+ const tampered = cookie.slice(0, -1) + (lastChar === "f" ? "0" : "f");
+ expect(tampered).not.toBe(cookie);
+ const result = await verifySession(tampered);
+ expect(result).toBeNull();
+ });
+
+ test("verifySession rejects a cookie that's not three parts", async () => {
+ expect(await verifySession("just-one-part")).toBeNull();
+ expect(await verifySession("two.parts")).toBeNull();
+ });
+
+ test("verifySession rejects a cookie whose expiry is in the past", async () => {
+ // Hand-roll a cookie with an `exp` that's already passed; sign with
+ // the same secret so the HMAC matches but the time-window check
+ // fails.
+ const username = "carol";
+ const exp = Math.floor(Date.now() / 1000) - 60;
+ const sig = await hmacSha256Hex(process.env.SESSION_SECRET!, `${username}.${exp}`);
+ const cookie = `${username}.${exp}.${sig}`;
+ expect(await verifySession(cookie)).toBeNull();
+ });
+
+});
+
+describe("c32_session — exports", () => {
+ test("SESSION_TTL_SEC is a positive integer (30 days)", () => {
+ expect(SESSION_TTL_SEC).toBe(30 * 24 * 60 * 60);
+ });
+});
diff --git a/src/b32_session.ts b/src/b32_session.ts
new file mode 100644
index 0000000000000000000000000000000000000000..47006e72a46a994a89b28ccf2ecb680c2b134c0a
--- /dev/null
+++ b/src/b32_session.ts
@@ -0,0 +1,81 @@
+// c32 — logic: session signing/verification + cookie helpers. Pure
+// HMAC over the session payload, no I/O. Handlers (c21) pull a viewer
+// off the request via getViewer(), and the OAuth callback issues a
+// session cookie via sessionCookieHeader + signSession.
+
+// 30 days. Long enough for everyday use, short enough that a leaked
+// cookie doesn't grant indefinite access.
+export const SESSION_TTL_SEC = 30 * 24 * 60 * 60;
+const SESSION_COOKIE = "tdd_session";
+
+const sessionSecret = (): string =>
+ process.env.SESSION_SECRET ?? process.env.WEBHOOK_SECRET ?? "";
+
+export const randomHex = (bytes: number): string =>
+ Array.from(crypto.getRandomValues(new Uint8Array(bytes)))
+ .map((b) => b.toString(16).padStart(2, "0"))
+ .join("");
+
+export const parseCookies = (header: string | null): Record => {
+ const out: Record = {};
+ if (!header) return out;
+ for (const part of header.split(";")) {
+ const idx = part.indexOf("=");
+ if (idx === -1) continue;
+ const name = part.slice(0, idx).trim();
+ const value = part.slice(idx + 1).trim();
+ if (name) out[name] = decodeURIComponent(value);
+ }
+ return out;
+};
+
+export const timingSafeEqual = (a: string, b: string): boolean => {
+ if (a.length !== b.length) return false;
+ let r = 0;
+ for (let i = 0; i < a.length; i++) r |= a.charCodeAt(i) ^ b.charCodeAt(i);
+ return r === 0;
+};
+
+export const hmacSha256Hex = async (secret: string, body: string): Promise => {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-256" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body));
+ return Array.from(new Uint8Array(sig))
+ .map((b) => b.toString(16).padStart(2, "0"))
+ .join("");
+};
+
+export const signSession = async (username: string): Promise => {
+ const exp = Math.floor(Date.now() / 1000) + SESSION_TTL_SEC;
+ const payload = `${username}.${exp}`;
+ const sig = await hmacSha256Hex(sessionSecret(), payload);
+ return `${payload}.${sig}`;
+};
+
+export const verifySession = async (cookie: string): Promise => {
+ const parts = cookie.split(".");
+ if (parts.length !== 3) return null;
+ const [username, expStr, providedSig] = parts;
+ if (!username || !expStr || !providedSig) return null;
+ const exp = Number(expStr);
+ if (!Number.isFinite(exp) || exp < Math.floor(Date.now() / 1000)) return null;
+ const expectedSig = await hmacSha256Hex(sessionSecret(), `${username}.${expStr}`);
+ if (!timingSafeEqual(providedSig, expectedSig)) return null;
+ return username;
+};
+
+export const getViewer = async (req: Request): Promise => {
+ if (!sessionSecret()) return null;
+ const cookies = parseCookies(req.headers.get("cookie"));
+ const raw = cookies[SESSION_COOKIE];
+ if (!raw) return null;
+ return verifySession(raw);
+};
+
+export const sessionCookieHeader = (value: string, maxAge: number): string =>
+ `${SESSION_COOKIE}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`;
diff --git a/src/b51_render_admin.test.ts b/src/b51_render_admin.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..4191a228b00816f5621ab9f28bb99e1ab61e5948
--- /dev/null
+++ b/src/b51_render_admin.test.ts
@@ -0,0 +1,34 @@
+// Sibling test for c51_render_admin.ts (Layer 1, render). The admin
+// pages (list, edit, login wall, non-admin wall) are exercised by
+// e2e/admin-block-editor.spec.ts. This sibling pins the export shape.
+
+import { describe, test, expect } from "bun:test";
+import {
+ renderAdminList,
+ renderAdminEdit,
+ renderAdminLoginWall,
+ renderAdminNonAdminWall,
+} from "./b51_render_admin.ts";
+
+describe("c51_render_admin — export shape", () => {
+ test("renderAdminList is async", () => {
+ expect(typeof renderAdminList).toBe("function");
+ });
+ test("renderAdminEdit is async", () => {
+ expect(typeof renderAdminEdit).toBe("function");
+ });
+ test("renderAdminLoginWall is async", () => {
+ expect(typeof renderAdminLoginWall).toBe("function");
+ });
+ test("renderAdminNonAdminWall is async", () => {
+ expect(typeof renderAdminNonAdminWall).toBe("function");
+ });
+});
+
+describe("c51_render_admin — login wall renders for anonymous viewer", () => {
+ test("returns an HTML document mentioning sign-in", async () => {
+ const html = await renderAdminLoginWall();
+ expect(html).toContain("");
+ expect(html.toLowerCase()).toMatch(/sign in|login|github/);
+ });
+});
diff --git a/src/b51_render_admin.ts b/src/b51_render_admin.ts
new file mode 100644
index 0000000000000000000000000000000000000000..03b68360e9c4c36d6ea6ea64d07f3a9003b38c44
--- /dev/null
+++ b/src/b51_render_admin.ts
@@ -0,0 +1,163 @@
+// c51 — UI: shells for the admin sxdoc editor.
+//
+// Three views: list (GET /admin), edit form (GET /admin/edit/...), and
+// auth walls for non-admin viewers. Body builders return HTML strings;
+// the c21 handler wraps them in htmlResponse.
+//
+// Fase 2a: raw-HTML textarea editor. Fase 2b adds the block editor on
+// top — the textarea stays as the underlying form field, and the
+// block-editor JS will hydrate it into a typed UI. So the form shape
+// here is forward-compatible with the block editor that lands next.
+
+import { escape, renderPage } from "./b51_render_layout.ts";
+import type { SxDocumentSummary } from "./a31_sxdoc.ts";
+import type { SxDocument } from "./a31_sxdoc.ts";
+import { sxToHtml } from "./b51_render_sxdoc.ts";
+
+export const renderAdminList = async (documents: SxDocumentSummary[]): Promise => {
+ const pages = documents.filter((d) => d.type === "page");
+ const posts = documents.filter((d) => d.type === "post");
+ const body = `# admin
+
+[+ new document](/admin/new)
+
+## pages (${pages.length})
+
+${pages.length === 0 ? "_no pages yet — migrate or create one._" : adminTable(pages)}
+
+## posts (${posts.length})
+
+${posts.length === 0 ? "_no posts yet — migrate or create one._" : adminTable(posts)}
+
+[← back to home](/)
+`;
+ return renderPage({
+ title: "admin — tdd.md",
+ bodyMarkdown: body,
+ noindex: true,
+ });
+};
+
+const adminTable = (rows: SxDocumentSummary[]): string => {
+ const lines = rows.map((r) =>
+ `| [${escape(r.title)}](/admin/edit/${r.type}/${r.slug}) | \`${escape(r.slug)}\` | ${r.status} | ${r.primaryTag ?? "—"} |`,
+ );
+ return `| title | slug | status | tag |
+|---|---|---|---|
+${lines.join("\n")}`;
+};
+
+export interface AdminEditViewModel {
+ mode: "new" | "edit";
+ title: string;
+ slug: string;
+ type: "page" | "post";
+ // SxDocument is the canonical input — server projects it to HTML for
+ // the textarea and embeds the JSON for the client editor's hydration.
+ doc: SxDocument;
+ status: "published" | "draft";
+ primaryTag: string | null;
+ error?: string;
+}
+
+// Embed JSON safely inside " in user content can't break out of the
+// script tag. JSON.parse handles "<" identically to "<".
+const safeJsonForScript = (value: unknown): string =>
+ JSON.stringify(value).replace(/ => {
+ const action = vm.mode === "new" ? "/admin/new" : `/admin/edit/${vm.type}/${vm.slug}`;
+ const heading = vm.mode === "new" ? "new document" : "edit document";
+ const submitLabel = vm.mode === "new" ? "Create" : "Save";
+ const html = sxToHtml(vm.doc);
+ const docJson = safeJsonForScript(vm.doc);
+
+ const errorBlock = vm.error
+ ? `${escape(vm.error)}
`
+ : "";
+
+ // Delete button uses a separate form to avoid posting the entire edit
+ // payload to the delete endpoint. confirm() catches accidental clicks.
+ const deleteForm = vm.mode === "edit"
+ ? ``
+ : "";
+
+ const form = `
+${deleteForm}
+
+`;
+
+ const title = vm.mode === "new"
+ ? "new — admin — tdd.md"
+ : `${vm.title} — admin — tdd.md`;
+ return renderPage({
+ title,
+ bodyHtml: `${heading}
${form}`,
+ noindex: true,
+ });
+};
+
+export const renderAdminLoginWall = async (): Promise =>
+ renderPage({
+ title: "admin — sign in — tdd.md",
+ bodyMarkdown: `# admin
+
+> Sign in with GitHub to access the admin UI.
+
+[ sign in with github → ](/auth/github/start)
+
+[← back to home](/)`,
+ noindex: true,
+ });
+
+export const renderAdminNonAdminWall = async (viewer: string): Promise =>
+ renderPage({
+ title: "admin — not authorized — tdd.md",
+ bodyMarkdown: `# not authorized
+
+> You are signed in as \`${escape(viewer)}\`, but the admin UI is reserved for the site admin.
+
+[← back to home](/) · [your agent](/agents/${escape(viewer)})`,
+ noindex: true,
+ });
diff --git a/src/b51_render_commit.test.ts b/src/b51_render_commit.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..af855e4636f1e6690f26fc380ff6a5e180425a82
--- /dev/null
+++ b/src/b51_render_commit.test.ts
@@ -0,0 +1,11 @@
+// Sibling test for c51_render_commit.ts (Layer 1, render). End-to-end
+// shape covered by /GIT/.../commit/ e2e; this pins the export.
+
+import { describe, test, expect } from "bun:test";
+import { renderCommitView } from "./b51_render_commit.ts";
+
+describe("c51_render_commit — export shape", () => {
+ test("renderCommitView is an async-style function", () => {
+ expect(typeof renderCommitView).toBe("function");
+ });
+});
diff --git a/src/b51_render_commit.ts b/src/b51_render_commit.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c655260950109dd6d5f1c1c73a26633564f9936e
--- /dev/null
+++ b/src/b51_render_commit.ts
@@ -0,0 +1,128 @@
+// c51 — UI: SAMA-native commit detail page. Replaces what visitors
+// would see at git.tdd.md///commit/ with the same
+// information rendered through tdd.md's chrome. Consumes the parsed
+// diff (c31_diff_parse) and commit metadata (any source — c14_git or
+// c14_forgejo can both produce it).
+
+import { renderPage, escape } from "./b51_render_layout.ts";
+import type { DiffFile, DiffHunk, ParsedDiff } from "./a31_diff_parse.ts";
+
+// Source-agnostic commit shape this renderer consumes. Both c14_git's
+// GitCommit and c14_forgejo's ForgejoCommitDetail fit this surface.
+export interface CommitForView {
+ sha: string;
+ parents: string[];
+ authorName: string;
+ authorEmail: string;
+ authorDate: string;
+ committerName: string;
+ committerEmail: string;
+ committerDate: string;
+ message: string;
+}
+
+const shortSha = (sha: string): string => sha.slice(0, 7);
+
+// "2026-05-10 12:31:07 +01:00" — ISO-ish, easy to scan.
+const ts = (iso: string): string => {
+ // Trust Forgejo's ISO format; only chop the timezone/seconds for compactness.
+ return iso.replace("T", " ").replace(/\+\d{2}:\d{2}$/, (m) => " " + m);
+};
+
+// First line of the commit message is the subject; rest is body.
+const splitMessage = (msg: string): { subject: string; body: string } => {
+ const newline = msg.indexOf("\n");
+ if (newline === -1) return { subject: msg, body: "" };
+ return {
+ subject: msg.slice(0, newline),
+ body: msg.slice(newline + 1).trim(),
+ };
+};
+
+const statusBadge = (status: DiffFile["status"]): string => {
+ const label =
+ status === "added" ? "added" :
+ status === "removed" ? "removed" :
+ status === "renamed" ? "renamed" : "modified";
+ return `${label}`;
+};
+
+const renderHunk = (hunk: DiffHunk): string => {
+ const headingHtml = hunk.heading
+ ? `${escape(hunk.heading)}`
+ : "";
+ const headerRow = ``;
+ const lineRows = hunk.lines.map((line) => {
+ const marker = line.kind === "added" ? "+" : line.kind === "removed" ? "-" : " ";
+ const oldNum = line.oldNum === null ? "" : String(line.oldNum);
+ const newNum = line.newNum === null ? "" : String(line.newNum);
+ return `| ${oldNum} | ${newNum} | ${escape(marker + line.text)} |
`;
+ }).join("");
+ return headerRow + lineRows;
+};
+
+const renderFile = (file: DiffFile): string => {
+ const renamed = file.status === "renamed" && file.oldPath !== file.path
+ ? `${escape(file.oldPath)} → `
+ : "";
+ return `
+
+ ${file.hunks.map(renderHunk).join("")}
+`;
+};
+
+export const renderCommitView = async (params: {
+ owner: string;
+ repo: string;
+ detail: CommitForView;
+ diff: ParsedDiff;
+}): Promise => {
+ const { owner, repo, detail, diff } = params;
+ const { subject, body } = splitMessage(detail.message);
+ const parentLinks = detail.parents.length === 0
+ ? `no parent (root commit)`
+ : detail.parents.map((p) =>
+ `${escape(shortSha(p))}`,
+ ).join(" · ");
+
+ const totalAdded = diff.files.reduce((s, f) => s + f.added, 0);
+ const totalRemoved = diff.files.reduce((s, f) => s + f.removed, 0);
+ const filesSummary = diff.files.length === 0
+ ? `No file changes (empty / merge commit).
`
+ : `${diff.files.length} file${diff.files.length === 1 ? "" : "s"} changed · +${totalAdded} −${totalRemoved}
`;
+
+ const inner = `
+
+ ${filesSummary}
+ ${diff.files.map(renderFile).join("")}
+
+`;
+
+ return renderPage({
+ title: `${shortSha(detail.sha)} · ${subject} — tdd.md`,
+ bodyHtml: inner,
+ description: `Commit ${shortSha(detail.sha)} on ${owner}/${repo}: ${subject}`,
+ noindex: true,
+ bodyClass: "commit-body-page",
+ hideNav: true,
+ });
+};
diff --git a/src/b51_render_docs_layout.test.ts b/src/b51_render_docs_layout.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e59f504f42021e51fbc25b53bb59a93ac6ae3a59
--- /dev/null
+++ b/src/b51_render_docs_layout.test.ts
@@ -0,0 +1,28 @@
+// Sibling test for c51_render_docs_layout.ts (Layer 1, render). The
+// docs chrome wraps markdown content with sidebar + on-this-page +
+// edit-link blocks. End-to-end coverage is in editor-flow.spec.ts
+// (which asserts .docs-content presence on /sama).
+
+import { describe, test, expect } from "bun:test";
+import { renderDocsPage } from "./b51_render_docs_layout.ts";
+
+describe("c51_render_docs_layout — renderDocsPage", () => {
+ test("is an async function", () => {
+ expect(typeof renderDocsPage).toBe("function");
+ });
+
+ test("renders a complete HTML document for a minimal options object", async () => {
+ const html = await renderDocsPage({
+ title: "Test page",
+ description: "Test description",
+ bodyMarkdown: "# Hello\n\nThis is a docs page.\n",
+ ogPath: "https://tdd.md/test",
+ active: "home",
+ pathForDocs: "/test",
+ });
+ expect(html).toContain("");
+ expect(html).toContain("Test page");
+ expect(html).toContain("docs-content");
+ expect(html).toContain("This is a docs page");
+ });
+});
diff --git a/src/b51_render_docs_layout.ts b/src/b51_render_docs_layout.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d8243d1c065b3d961896509e85f6f9b50b1f98ef
--- /dev/null
+++ b/src/b51_render_docs_layout.ts
@@ -0,0 +1,123 @@
+// c51 (docs-layout) — UI: GitBook-style chrome around the existing
+// renderPage. Wraps content with a right "on this page" anchor rail
+// (h2/h3 from the rendered body), an edit-on-GitHub link at the top
+// of content, and a prev/next navigator at the bottom. Per SAMA:
+// imports c31 (data), c32 (logic), and c51_render_layout (chrome).
+// No I/O of its own.
+
+import { marked } from "marked";
+import {
+ resolveDocsLocation,
+ type ResolvedDocsLocation,
+} from "./a31_docs_nav.ts";
+import { extractAnchors, type Anchor } from "./b32_anchor_extract.ts";
+import {
+ renderPage,
+ escape,
+ type PageOptions,
+} from "./b51_render_layout.ts";
+
+export interface DocsPageOptions extends Omit<PageOptions, "bodyHtml"> {
+ // The route path the user is on, e.g. "/sama/sorted". Used to
+ // compute prev/next.
+ pathForDocs: string;
+ // Optional override of which file the "edit on GitHub" link
+ // targets, when the body isn't a content/<section>/<slug>.md.
+ // Defaults to the editPath from the resolved nav location.
+ editPathOverride?: string | null;
+}
+
+const renderAnchorRail = (anchors: Anchor[]): string => {
+ if (anchors.length === 0) return "";
+ const items = anchors
+ .map((a) => {
+ const cls = a.level === 3 ? "docs-rail-link docs-rail-link-h3" : "docs-rail-link";
+ return `<li><a class="${cls}" href="#${escape(a.id)}">${escape(a.text)}</a></li>`;
+ })
+ .join("");
+ return `<aside class="docs-rail" aria-label="on this page">
+ <p class="docs-rail-title">on this page</p>
+ <ul class="docs-rail-list">${items}</ul>
+</aside>`;
+};
+
+// Derive (section, slug) from a content/<section>/<slug>.md editPath.
+// Returns null when the path doesn't follow the convention (in which
+// case there's no editor route to link to).
+const sectionSlugFromEditPath = (editPath: string): { section: string; slug: string } | null => {
+ const m = /^content\/([a-z]+)\/([a-z0-9][a-z0-9-]*)\.md$/.exec(editPath);
+ return m ? { section: m[1]!, slug: m[2]! } : null;
+};
+
+const renderEditLink = (editPath: string | null): string => {
+ if (!editPath) return "";
+ // Source view is served from tdd.md itself (c21_handlers_source);
+ // we no longer depend on the git.tdd.md (Forgejo) subdomain for
+ // the docs site's "view source" link.
+ const ss = sectionSlugFromEditPath(editPath);
+ const sourceHref = ss ? `/content/${ss.section}/${ss.slug}.md` : `/${editPath}`;
+ const editHref = ss ? `/edit/${ss.section}/${ss.slug}` : null;
+ const editAnchor = editHref
+ ? `<a href="${escape(editHref)}">propose an edit →</a> · `
+ : "";
+ return `<p class="docs-edit">${editAnchor}<a href="${escape(sourceHref)}">view source →</a></p>`;
+};
+
+const renderPrevNext = (loc: ResolvedDocsLocation | null): string => {
+ if (!loc) return "";
+ const prev = loc.prev
+ ? `<a class="docs-pn-prev" href="${loc.prev.href}"><span class="docs-pn-arrow">←</span><span class="docs-pn-label">${escape(loc.prev.label)}</span></a>`
+ : `<span class="docs-pn-spacer"></span>`;
+ const next = loc.next
+ ? `<a class="docs-pn-next" href="${loc.next.href}"><span class="docs-pn-label">${escape(loc.next.label)}</span><span class="docs-pn-arrow">→</span></a>`
+ : `<span class="docs-pn-spacer"></span>`;
+ return `<nav class="docs-prev-next" aria-label="previous and next page">${prev}${next}</nav>`;
+};
+
+// Wrap a heading element with an anchor link for hover-click access.
+// Also injects an `id` if marked didn't (rare with our config but
+// possible). Operates on the rendered HTML before composing the page.
+const enrichHeadings = (html: string): string =>
+ html.replace(
+ /<h([23])(\s+[^>]*)?>([\s\S]*?)<\/h\1>/g,
+ (_full, level, attrs, inner) => {
+ const idMatch = /\bid="([^"]+)"/.exec(attrs ?? "");
+ const id = idMatch?.[1] ?? inner.replace(/<[^>]*>/g, "").toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-");
+ const finalAttrs = idMatch ? attrs : `${attrs ?? ""} id="${id}"`;
+ return `<h${level}${finalAttrs}><a class="docs-h-anchor" href="#${id}" aria-label="link to this section">#</a>${inner}</h${level}>`;
+ },
+ );
+
+export const renderDocsPage = async (opts: DocsPageOptions): Promise<string> => {
+ const rawHtml = opts.bodyMarkdown
+ ? await marked.parse(opts.bodyMarkdown, { gfm: true, breaks: false })
+ : "";
+ const enriched = enrichHeadings(rawHtml);
+ const anchors = extractAnchors(enriched);
+ const loc = resolveDocsLocation(opts.pathForDocs);
+ const editPath = opts.editPathOverride !== undefined ? opts.editPathOverride : loc?.current.editPath ?? null;
+
+ const rail = renderAnchorRail(anchors);
+ const editLink = renderEditLink(editPath);
+ const prevNext = renderPrevNext(loc);
+
+ const composed = `<div class="docs-layout">
+<article class="docs-content">
+${editLink}
+${enriched}
+${prevNext}
+</article>
+${rail}
+</div>`;
+
+ return renderPage({
+ title: opts.title,
+ bodyHtml: composed,
+ description: opts.description,
+ ogPath: opts.ogPath,
+ active: opts.active,
+ noindex: opts.noindex,
+ jsonLd: opts.jsonLd,
+ bodyClass: "docs-body",
+ });
+};
diff --git a/src/b51_render_edit.test.ts b/src/b51_render_edit.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6e7d6689ecc7464ec0d095bb422908605e052346
--- /dev/null
+++ b/src/b51_render_edit.test.ts
@@ -0,0 +1,47 @@
+// Sibling test for c51_render_edit.ts (Layer 1, render). End-to-end
+// coverage in e2e/editor-flow.spec.ts (login wall, propose-edit
+// flow) and e2e/git-native-proof.spec.ts (applied-live page). This
+// sibling pins the export shape.
+
+import { describe, test, expect } from "bun:test";
+import {
+ renderEditFormPage,
+ renderEditLoginWall,
+ renderEditNonAdminWall,
+ renderEditAppliedLive,
+ renderEditCommitFailed,
+} from "./b51_render_edit.ts";
+
+describe("c51_render_edit — export shape", () => {
+ test("renderEditFormPage is async", () => {
+ expect(typeof renderEditFormPage).toBe("function");
+ });
+ test("renderEditLoginWall is async", () => {
+ expect(typeof renderEditLoginWall).toBe("function");
+ });
+ test("renderEditNonAdminWall is async", () => {
+ expect(typeof renderEditNonAdminWall).toBe("function");
+ });
+ test("renderEditAppliedLive is async", () => {
+ expect(typeof renderEditAppliedLive).toBe("function");
+ });
+ test("renderEditCommitFailed is async", () => {
+ expect(typeof renderEditCommitFailed).toBe("function");
+ });
+});
+
+describe("c51_render_edit — login wall renders a complete document", () => {
+ test("anonymous viewer sees a sign-in prompt", async () => {
+ // ResolvedEdit shape — minimal but realistic.
+ const html = await renderEditLoginWall({
+ section: "sama",
+ slug: "skill",
+ title: "SAMA skill",
+ pageUrl: "/sama/skill",
+ mdPath: "content/sama/skill.md",
+ body: "# stub",
+ });
+ expect(html).toContain("<!doctype html>");
+ expect(html.toLowerCase()).toMatch(/sign in|login|github/);
+ });
+});
diff --git a/src/b51_render_edit.ts b/src/b51_render_edit.ts
new file mode 100644
index 0000000000000000000000000000000000000000..de56bd4b23fc1c4442dbd2c9fbbfa846839bfbb1
--- /dev/null
+++ b/src/b51_render_edit.ts
@@ -0,0 +1,165 @@
+// c51 (edit) — UI: edit-form, login-required prompt, applied-live
+// success page, commit-failure page, non-admin "read-only" wall.
+// Composes the docs layout's chrome via renderPage with bodyHtml so
+// the form can use real <form> elements (markdown would escape them).
+
+import {
+ renderPage,
+ escape,
+} from "./b51_render_layout.ts";
+import type { ResolvedEdit } from "./b32_edit_resolve.ts";
+import type { GitCommitOk, GitCommitFailure } from "./a31_git_parse.ts";
+
+const layoutWrap = (innerHtml: string): string =>
+ `<main class="md edit-page"><div class="edit-container">${innerHtml}</div></main>`;
+
+// Override the standard <main class="md">: the edit experience needs
+// full-width form controls, not the doc-layout's three columns.
+const editBodyClass = "edit-body";
+
+const shortSha = (sha: string): string => sha.slice(0, 7);
+
+// SAMA-native commit URL on tdd.md itself. The /GIT/ prefix routes to
+// c21_handlers_commit_view which reads the data from Forgejo's API and
+// renders it through tdd.md's chrome — visitor never leaves the main
+// domain.
+const tddCommitUrl = (sha: string): string =>
+ `/GIT/syntaxai/tdd.md/commit/${sha}`;
+
+// -------- /edit/:section/:slug — form for the admin --------
+
+export const renderEditFormPage = async (
+ resolved: ResolvedEdit,
+ currentBody: string,
+ viewer: string,
+): Promise<string> => {
+ const inner = `<h1>edit · ${escape(resolved.title)}</h1>
+<p class="edit-meta">
+ Editing <code>${escape(resolved.filePath)}</code> as <strong>${escape(viewer)}</strong>.
+ Saving will commit directly to <code>syntaxai/tdd.md@main</code> on git.tdd.md
+ and refresh the live page.
+ <a href="${escape(resolved.pageUrl)}">view the live page</a> ·
+ <a href="/auth/logout">log out</a>
+</p>
+<form method="post" action="/edit/${escape(resolved.section)}/${escape(resolved.slug)}" class="edit-form">
+ <textarea name="body" class="edit-textarea" rows="32" spellcheck="false">${escape(currentBody)}</textarea>
+ <div class="edit-actions">
+ <button type="submit">save (commit + live)</button>
+ <a class="edit-cancel" href="${escape(resolved.pageUrl)}">cancel</a>
+ </div>
+</form>
+<p class="edit-note">
+ This editor commits to git via Forgejo's contents API — the container has
+ no <code>.git</code> directory, no SSH keys, only an HTTP token. Every save
+ becomes a real commit you can review at git.tdd.md.
+</p>`;
+ return renderPage({
+ title: `edit · ${resolved.title} — tdd.md`,
+ bodyHtml: layoutWrap(inner),
+ description: `Edit ${resolved.title} on tdd.md. Admin-only; saves commit directly to git.tdd.md.`,
+ ogPath: `https://tdd.md/edit/${resolved.section}/${resolved.slug}`,
+ noindex: true,
+ bodyClass: editBodyClass,
+ });
+};
+
+// -------- login wall before the form --------
+
+export const renderEditLoginWall = async (
+ resolved: ResolvedEdit,
+): Promise<string> => {
+ const returnTo = `/edit/${resolved.section}/${resolved.slug}`;
+ const inner = `<h1>edit · ${escape(resolved.title)}</h1>
+<p>To edit a page you need to sign in via GitHub. Editing is admin-only — only the site owner's GitHub account can save changes. We use GitHub for identity only; saves commit to git.tdd.md, never to GitHub.</p>
+<p><a class="edit-login-button" href="/auth/github/start?to=${encodeURIComponent(returnTo)}">sign in with GitHub →</a></p>
+<p class="edit-meta">If you have an edit suggestion and you're not the admin, open an issue at <a href="https://git.tdd.md/syntaxai/tdd.md/issues" rel="noopener" target="_blank">git.tdd.md/syntaxai/tdd.md/issues</a>.</p>
+<p><a href="${escape(resolved.pageUrl)}">← back to the page</a></p>`;
+ return renderPage({
+ title: `sign in to edit · ${resolved.title} — tdd.md`,
+ bodyHtml: layoutWrap(inner),
+ description: `Sign in via GitHub to edit ${resolved.title} on tdd.md.`,
+ noindex: true,
+ bodyClass: editBodyClass,
+ });
+};
+
+// -------- non-admin signed-in wall --------
+
+export const renderEditNonAdminWall = async (
+ resolved: ResolvedEdit,
+ viewer: string,
+): Promise<string> => {
+ const inner = `<h1>edit · ${escape(resolved.title)}</h1>
+<p>Signed in as <strong>${escape(viewer)}</strong>, but editing is admin-only. Only the site owner can save changes from here.</p>
+<p>If you'd like to suggest an edit, open an issue at <a href="https://git.tdd.md/syntaxai/tdd.md/issues" rel="noopener" target="_blank">git.tdd.md/syntaxai/tdd.md/issues</a> describing the change.</p>
+<p><a href="${escape(resolved.pageUrl)}">← back to the page</a> · <a href="/auth/logout">log out</a></p>`;
+ return renderPage({
+ title: `edit · ${resolved.title} — tdd.md`,
+ bodyHtml: layoutWrap(inner),
+ noindex: true,
+ bodyClass: editBodyClass,
+ });
+};
+
+// -------- admin direct-edit applied live --------
+
+export const renderEditAppliedLive = async (
+ resolved: ResolvedEdit,
+ commit: GitCommitOk,
+): Promise<string> => {
+ const sha = commit.commitSha;
+ const inner = `<h1>applied live · ${escape(resolved.title)}</h1>
+<p>Your edit to <a href="${escape(resolved.pageUrl)}"><code>${escape(resolved.pageUrl)}</code></a> is now live <strong>and committed</strong>.</p>
+<p class="edit-meta">
+ Commit <a href="${escape(tddCommitUrl(sha))}"><code>${escape(shortSha(sha))}</code></a>
+ landed in the local bare repo (<code>/app/repo</code> in the container,
+ <code>~/repos/tdd.md.git</code> on p620) via <code>git</code> plumbing.
+ No HTTP, no Forgejo, no SSH involved — just a real git commit on disk.
+</p>
+<p class="edit-note">
+ The container's <code>content/</code> dir is copied from the working
+ tree at image build, and the next deploy fetches new commits from the
+ local bare repo before rebuilding — so this commit will outlive any
+ container restart.
+</p>
+<p><a href="${escape(resolved.pageUrl)}">→ view the live page</a> · <a href="/edit/${escape(resolved.section)}/${escape(resolved.slug)}">edit again</a></p>`;
+ return renderPage({
+ title: `applied · ${resolved.title} — tdd.md`,
+ bodyHtml: layoutWrap(inner),
+ noindex: true,
+ bodyClass: editBodyClass,
+ });
+};
+
+// -------- admin commit failed (Forgejo conflict / network / other) --------
+
+export const renderEditCommitFailed = async (
+ resolved: ResolvedEdit,
+ failure: GitCommitFailure,
+): Promise<string> => {
+ const explanation =
+ failure.kind === "conflict"
+ ? "The branch tip moved while you were editing — someone else committed in between. Refresh the editor to load the latest version, then re-apply your change."
+ : failure.kind === "permission"
+ ? "The container can't write to the bare repo. Check that /home/scri/repos/tdd.md.git on p620 is mounted read-write into /app/repo."
+ : failure.kind === "not_found"
+ ? "The 'main' branch doesn't exist in the bare repo. Verify that ~/repos/tdd.md.git on p620 has a refs/heads/main."
+ : "git rejected the commit for an unexpected reason. See the message below.";
+ const inner = `<h1>commit failed · ${escape(resolved.title)}</h1>
+<p>Your edit to <a href="${escape(resolved.pageUrl)}"><code>${escape(resolved.pageUrl)}</code></a> was <strong>not applied</strong>. The live page is unchanged.</p>
+<p class="edit-meta">
+ git returned <strong>${escape(failure.kind)}</strong>.
+</p>
+<p>${escape(explanation)}</p>
+<details class="edit-note">
+ <summary>git stderr</summary>
+ <pre><code>${escape(failure.message.slice(0, 2000))}</code></pre>
+</details>
+<p><a href="/edit/${escape(resolved.section)}/${escape(resolved.slug)}">← back to the editor (refreshes the form)</a></p>`;
+ return renderPage({
+ title: `commit failed · ${resolved.title} — tdd.md`,
+ bodyHtml: layoutWrap(inner),
+ noindex: true,
+ bodyClass: editBodyClass,
+ });
+};
diff --git a/src/b51_render_layout.test.ts b/src/b51_render_layout.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..270bd02590743beeffe6491e4150d338c434fe84
--- /dev/null
+++ b/src/b51_render_layout.test.ts
@@ -0,0 +1,59 @@
+// Sibling test for c51_render_layout.ts (Layer 1, render). The page
+// chrome plus the `escape` HTML-escaper. End-to-end coverage at every
+// route that renders HTML; this sibling pins the pure helpers.
+
+import { describe, test, expect } from "bun:test";
+import { escape, renderPage, renderNotFound, htmlResponse } from "./b51_render_layout.ts";
+
+describe("c51_render_layout — escape (HTML entity escaping)", () => {
+ test("escapes ampersand, lt, gt, double-quote", () => {
+ expect(escape("&")).toBe("&");
+ expect(escape("<")).toBe("<");
+ expect(escape(">")).toBe(">");
+ expect(escape('"')).toBe(""");
+ });
+
+ test("escapes ampersand FIRST so we don't double-escape", () => {
+ // Naive ordering ("<&" → "<&" then & → "<&") would
+ // produce "<&" if the order were wrong.
+ expect(escape("<&>")).toBe("<&>");
+ });
+
+ test("passes plain text through unchanged", () => {
+ expect(escape("hello world")).toBe("hello world");
+ });
+});
+
+describe("c51_render_layout — renderPage", () => {
+ test("renders a complete HTML document with the supplied title", async () => {
+ const html = await renderPage({
+ title: "Hello",
+ description: "Test page",
+ bodyMarkdown: "# Hi\n\nbody",
+ ogPath: "https://tdd.md/test",
+ });
+ expect(html).toContain("<!doctype html>");
+ expect(html).toContain("<title>Hello");
+ expect(html).toContain("body");
+ });
+});
+
+describe("c51_render_layout — renderNotFound + htmlResponse", () => {
+ test("renderNotFound produces a 404-friendly body string", async () => {
+ const html = await renderNotFound("/nonexistent");
+ expect(html).toContain("<!doctype html>");
+ expect(html).toMatch(/not.found|404/i);
+ });
+
+ test("htmlResponse wraps a string in a 200 Response with text/html", async () => {
+ const r = htmlResponse("<p>hi</p>");
+ expect(r.status).toBe(200);
+ expect(r.headers.get("content-type")).toMatch(/text\/html/);
+ expect(await r.text()).toBe("<p>hi</p>");
+ });
+
+ test("htmlResponse honours the optional status arg", () => {
+ const r = htmlResponse("<p>nope</p>", 404);
+ expect(r.status).toBe(404);
+ });
+});
diff --git a/src/b51_render_layout.ts b/src/b51_render_layout.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d611d6168c1a20083fcf9803a288df2220f8075e
--- /dev/null
+++ b/src/b51_render_layout.ts
@@ -0,0 +1,125 @@
+// c51 (layout) — UI: page chrome + small response/format helpers shared
+// across every domain. Bigger per-domain body builders live next to this
+// file as `c51_render_<domain>.ts` (projects, reports). Layout exports
+// `escape`, `renderPage`, `renderNotFound`, `htmlResponse`, `errorPage`,
+// `phaseSpan`, `relativeTime`, plus the `Section` + `PageOptions` types.
+// Per the SAMA convention, lower layers don't import from this one.
+
+import { marked } from "marked";
+import type { Phase } from "./a31_commits.ts";
+
+const STYLE_CSS = "./public/style.css";
+const css = await Bun.file(STYLE_CSS).text();
+
+export type Section = "home" | "games" | "guides" | "blog" | "agents" | "leaderboard" | "sama";
+
+export interface PageOptions {
+ title: string;
+ // Provide either bodyMarkdown (parsed by marked) or bodyHtml
+ // (passed through as-is). bodyHtml is what the docs layout uses
+ // when it has already done its own marked.parse and wrapped the
+ // result in sidebar/content/anchor-rail chrome.
+ bodyMarkdown?: string;
+ bodyHtml?: string;
+ description?: string;
+ ogPath?: string;
+ active?: Section;
+ noindex?: boolean;
+ jsonLd?: Record<string, unknown>;
+ bodyClass?: string;
+ // Skip the top nav bar (tdd.md · games · guides · sama · blog · agents
+ // · leaderboard). Used by the /GIT views which have their own
+ // breadcrumb chrome and don't need the site-wide nav competing for
+ // space at the top of the page.
+ hideNav?: boolean;
+}
+
+const SITE_DESCRIPTION = "SAMA — the architectural standard for AI-agent codebases. Sorted, Architecture, Modeled, Atomic. Four pillars, one CI verifier.";
+
+export const escape = (s: string): string =>
+ s.replace(/&/g, "&").replace(/"/g, """).replace(/</g, "<").replace(/>/g, ">");
+
+const navLink = (href: string, label: string, active: boolean): string => {
+ const cls = active ? ' class="nav-active"' : "";
+ return `<a href="${href}"${cls}>${label}</a>`;
+};
+
+const nav = (active?: Section): string => `<nav class="md-nav">${navLink("/", "tdd.md", active === "home")} <span class="md-nav-sep">·</span> ${navLink("/games", "games", active === "games")} <span class="md-nav-sep">·</span> ${navLink("/guides", "guides", active === "guides")} <span class="md-nav-sep">·</span> ${navLink("/sama", "sama", active === "sama")} <span class="md-nav-sep">·</span> ${navLink("/blog", "blog", active === "blog")} <span class="md-nav-sep">·</span> ${navLink("/agents", "agents", active === "agents")} <span class="md-nav-sep">·</span> ${navLink("/leaderboard", "leaderboard", active === "leaderboard")}</nav>`;
+
+export const renderPage = async (opts: PageOptions): Promise<string> => {
+ const body = opts.bodyHtml ?? await marked.parse(opts.bodyMarkdown ?? "", { gfm: true, breaks: false });
+ const description = opts.description ?? SITE_DESCRIPTION;
+ const bodyClassAttr = opts.bodyClass ? ` class="${escape(opts.bodyClass)}"` : "";
+ const ogPath = opts.ogPath ?? "https://tdd.md";
+ const robots = opts.noindex ? `<meta name="robots" content="noindex,nofollow">\n` : "";
+ const jsonLd = opts.jsonLd
+ ? `<script type="application/ld+json">${JSON.stringify(opts.jsonLd)}</script>\n`
+ : "";
+ return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="dark light">
+<meta name="description" content="${escape(description)}">
+${robots}<link rel="canonical" href="${escape(ogPath)}">
+<meta property="og:title" content="${escape(opts.title)}">
+<meta property="og:description" content="${escape(description)}">
+<meta property="og:type" content="website">
+<meta property="og:url" content="${escape(ogPath)}">
+<meta property="og:image" content="https://tdd.md/og.png?v=2">
+<meta property="og:image:type" content="image/png">
+<meta property="og:image:width" content="1200">
+<meta property="og:image:height" content="630">
+<meta property="og:site_name" content="tdd.md">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${escape(opts.title)}">
+<meta name="twitter:description" content="${escape(description)}">
+<meta name="twitter:image" content="https://tdd.md/og.png?v=2">
+<title>${escape(opts.title)}
+${jsonLd}
+
+
+${opts.hideNav ? "" : nav(opts.active)}
+
+${body}
+
+
`);
+ expect(doc.blocks[0]).toEqual({ t: "img", src: "/x.png", alt: "x icon" });
+});
+
+test("parses img with width and height attributes", () => {
+ const doc = htmlToSx(`
`);
+ expect(doc.blocks[0]).toEqual({ t: "img", src: "/a.jpg", w: 200, h: 100 });
+});
+
+test("skips img with empty src", () => {
+ const doc = htmlToSx(`