@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/system/site/lib/shared.ts

@@ -2,12 +2,13 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 
 import { governanceVisible } from "./governance";
+import { splitFrontmatter } from "../record/frontmatter";
 
-// The record's one identity source: instance.md's `name:` — the same file
-// every other shell reads, so renaming the instance renames every surface
-// at the next build, and no shell carries a baked-in copy (found live
-// 2026-08-18: a stamped constant survived a restore-from-templates as the
-// literal placeholder name, with every gate green).
+// The record's one identity source: instance.md — the same file every other
+// surface reads, so renaming the instance renames every surface at the next
+// build, and no shell carries a baked-in copy (found live 2026-08-18: a
+// stamped constant survived a restore-from-templates as the literal
+// placeholder name, with every gate green).
 function findInstance(start: string): string {
   let dir = start;
   for (let i = 0; i < 5; i += 1) {
@@ -22,24 +23,42 @@ function findInstance(start: string): string {
   );
 }
 
+/** The project root: the directory holding instance.md. */
+export const projectRoot: string = path.dirname(findInstance(process.cwd()));
+
 /**
- * instance.md's frontmatter block — the configuration every surface reads
- * (identity here, the audience model in lib/audience.ts). Only this block:
- * body prose that looks like a key must never become configuration (review
- * finding, 2026-08-18).
+ * instance.md's frontmatter, read with the record's own parser (decision 26:
+ * one YAML reader, never a line scanner — the scanner this replaced could not
+ * read a nested block and failed silently on it). Only the frontmatter: the
+ * body is the MCP server's instructions in full (record spec §3), and prose
+ * that looks like a key must never become configuration (review finding,
+ * 2026-08-18).
  */
-export function instanceFrontmatter(): string {
-  const text = readFileSync(findInstance(process.cwd()), "utf8");
-  // The checker's boundary exactly: BOM stripped, CRLF normalized, lax close.
-  const normalized = text.replace(/^\uFEFF/, "").replaceAll("\r\n", "\n");
-  return /^---\n([\s\S]*?)\n---/.exec(normalized)?.[1] ?? "";
+function readInstance(): Readonly<Record<string, unknown>> {
+  const split = splitFrontmatter(
+    readFileSync(path.join(projectRoot, "instance.md"), "utf8"),
+    "instance.md",
+  );
+  if (!split.ok) {
+    throw new Error(
+      `${split.refusal.slug}: instance.md — ${split.refusal.why}\n  fix: ${split.refusal.fix}`,
+    );
+  }
+  return split.frontmatter ?? {};
+}
+
+export const instanceData: Readonly<Record<string, unknown>> = readInstance();
+
+function scalar(key: string): string | null {
+  const value = instanceData[key];
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
 }
 
 function readInstanceName(): string {
-  const raw = /^name:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[1]?.trim() ?? "";
-  const unquoted = /^(['"])(.*)\1$/.exec(raw);
-  const name = unquoted?.[2] ?? raw;
-  if (name === "") {
+  const name = scalar("name");
+  if (name === null) {
     throw new Error("instance.md carries no name: — it is the project's identity; run pnpm check.");
   }
   return name;
@@ -48,89 +67,33 @@ function readInstanceName(): string {
 export const appName: string = readInstanceName();
 
 /**
- * The record's DISPLAY TITLE: instance.md's first body heading. The slug in
- * `name:` is the machine identity (llms.txt, future citations); the H1 is
- * the human name every page leads with. A fresh scaffold reads "Knowledge
- * System of Record" until the intake interview writes the real one.
+ * The record's DISPLAY TITLE: instance.md's `title:` (record spec §3, format
+ * 2 — what used to be the body's H1). The slug in `name:` is the machine
+ * identity (llms.txt, citations); the title is the human name every page leads
+ * with. Falls back to the name so a page always has one.
  */
-function readInstanceTitle(): string {
-  const text = readFileSync(findInstance(process.cwd()), "utf8");
-  const body = text.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
-  return /^#[ \t]+(.+)$/m.exec(body)?.[1]?.trim() ?? appName;
-}
-
-export const appTitle: string = readInstanceTitle();
+export const appTitle: string = scalar("title") ?? appName;
 
 /**
- * Whether the pages show the governance each document declares
- * (`site.governance` in instance.md, default on). Read once at build/server
- * start, like the identity above — restart `pnpm dev` after changing it.
- */
-export const showGovernance: boolean = governanceVisible(instanceFrontmatter());
-
-/**
- * The record's own statement of what it is authoritative for: the first
- * paragraph of instance.md's body, below the display title.
- *
- * The home page used to carry a line of ksor's marketing copy instead — the
- * framework's voice above somebody else's knowledge, which the project's own
- * critical rule 1 forbids. This is the record speaking for itself, and it is
- * the same prose `ksor serve` hands the MCP server as its instructions, so the
- * two surfaces open with one sentence.
+ * The record's own one-sentence statement of what it is authoritative for:
+ * instance.md's `description:`. It seeds the home page, `llms.txt` and
+ * `server.json`, and it is the record speaking for itself — the framework's
+ * marketing copy used to sit where it goes (research/site-design.md F7).
  *
- * Null when the body says nothing yet; the page then renders nothing rather
- * than inventing a purpose.
+ * Null when the owner has not written one; the page then renders nothing
+ * rather than inventing a purpose.
  */
-function readInstancePurpose(): string | null {
-  const text = readFileSync(findInstance(process.cwd()), "utf8");
-  const body = text.replace(/^?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
-  const afterTitle = body.replace(/^#[ \t]+.*$/m, "");
-  const paragraph = afterTitle
-    .split(/\n\s*\n/)
-    .map((block) => block.trim())
-    .find((block) => block !== "");
-  if (paragraph === undefined) return null;
-  // One paragraph, as one line: the body wraps at 80 columns for the file's
-  // sake, and those newlines are not sentence breaks.
-  return paragraph.replaceAll(/\s*\n\s*/g, " ").trim();
-}
+export const appDescription: string | null = scalar("description");
 
-export const appPurpose: string | null = readInstancePurpose();
+/** The description, under the name the home page's cover takes it by. */
+export const appPurpose: string | null = appDescription;
 
 /**
- * How this record describes ITSELF, in one line — what an agent reads in a
- * registry listing to decide whether this record can answer its question.
- *
- * It comes from the record's own prose (instance.md's first real paragraph,
- * which the intake interview writes) because the alternative is what shipped
- * before: one hard-coded sentence, byte-identical in every ksor record ever
- * scaffolded, telling a discovering agent nothing that distinguishes this record
- * from any other. "Discoverability determines whether agents find you at all" is
- * a product principle, and a description that cannot discriminate is not
- * discoverability (found live 2026-08-21).
- *
- * An UNDESCRIBED record says so rather than borrowing a confident sentence it
- * has not earned — the same answer the MCP door already gives an agent that
- * connects, so the two surfaces do not disagree about whether this record knows
- * what it is. The marker is the template's own unfilled placeholder, matched on
- * the WHOLE body: a scaffold's first paragraphs are authoring guidance, and
- * reading one of those as the record's scope is worse than admitting there is
- * none.
+ * Whether the pages show the governance each document declares
+ * (`site.governance` in instance.md, default on). Read once at build/server
+ * start, like the identity above — restart `pnpm dev` after changing it.
  */
-const TEMPLATE_MARKER = "_fill this in; it is";
-
-function readInstanceScope(): string | null {
-  const text = readFileSync(findInstance(process.cwd()), "utf8");
-  const body = text.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
-  if (body.includes(TEMPLATE_MARKER)) return null;
-  const afterHeading = body.replace(/^[\s\S]*?^#[ \t]+.+$/m, "");
-  for (const para of afterHeading.split(/\n[ \t]*\n/)) {
-    const one = para.trim().replace(/\s+/g, " ");
-    if (one === "" || one.startsWith("#") || one.startsWith("-") || one.startsWith(">")) continue;
-    return sentence(one);
-  }
-  return null;
-}
+export const showGovernance: boolean = governanceVisible(instanceData);
 
 /**
  * The MCP registry schema caps `ServerDetail.description` at **100 characters**
@@ -146,9 +109,10 @@ function readInstanceScope(): string | null {
  */
 const DESCRIPTION_MAX = 100;
 
-function sentence(one: string): string {
-  const first = /^(.+?[.!?])(\s|$)/.exec(one)?.[1] ?? one;
-  return first;
+/** One paragraph as one line: a wrapped description is not several sentences. */
+function sentence(text: string): string {
+  const one = text.replace(/\s+/g, " ").trim();
+  return /^(.+?[.!?])(\s|$)/.exec(one)?.[1] ?? one;
 }
 
 /** Fit `text` inside `max`, breaking on a word rather than mid-word. */
@@ -156,11 +120,11 @@ function fit(text: string, max: number): string {
   if (text.length <= max) return text;
   const cut = text.slice(0, max - 1);
   const at = cut.lastIndexOf(" ");
-  return `${(at > max / 2 ? cut.slice(0, at) : cut).replace(/[,;:.\s]+$/, "")}\u2026`;
+  return `${(at > max / 2 ? cut.slice(0, at) : cut).replace(/[,;:.\s]+$/, "")}…`;
 }
 
-/** null until the owner has written one — never a guess. */
-export const appScope: string | null = readInstanceScope();
+/** The first sentence of the description, or null until the owner has written one — never a guess. */
+export const appScope: string | null = appDescription === null ? null : sentence(appDescription);
 
 /**
  * The one-line description every discovery surface publishes. Built here so the
@@ -181,9 +145,7 @@ export function recordDescription(): string {
  * agent would try it and conclude the record is down rather than unpublished.
  */
 export function mcpEndpoint(): string | null {
-  const declared = /^mcp_url:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[1] ?? "";
-  const value = declared.trim().replace(/^["']|["']$/g, "");
-  return value === "" ? null : value;
+  return scalar("mcp_url");
 }
 
 /**
@@ -217,7 +179,8 @@ export function mcpNamespace(): string {
  * instance.md and falls back to a first-release default.
  */
 export function recordVersion(): string {
-  const declared = /^version:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[1] ?? "";
-  const value = declared.trim().replace(/^["']|["']$/g, "");
-  return /^\d+\.\d+\.\d+/.test(value) ? value : "0.1.0";
+  const value = instanceData["version"];
+  const text =
+    typeof value === "number" ? String(value) : typeof value === "string" ? value.trim() : "";
+  return /^\d+\.\d+\.\d+/.test(text) ? text : "0.1.0";
 }

package/templates/scaffold/system/site/lib/sim-rule.ts

@@ -0,0 +1,49 @@
+/**
+ * What makes a file in the record a SIM — an interactive page the record
+ * CARRIES, served rather than bundled.
+ *
+ * A sim is an ASSET of its document, exactly like the figures beside it: many
+ * per document, named freely, linked from the prose the way a figure is, and
+ * staged only when a published document references it. It is deliberately NOT
+ * a study attachment (decision 24) — an attachment is named after its parent
+ * (`<doc>.quiz.yaml`), and seven sims cannot all be `index.sim.html`. So this
+ * rule is the SUFFIX and nothing else: there is no parent name to derive, and
+ * governance is inherited by POSITION — through the concept whose link is the
+ * only way a sim ever reaches the stage.
+ *
+ * The suffix is what separates a page the record MEANS to serve from an
+ * `.html` that fell into `knowledge/`. Both are bytes with the same extension,
+ * so without a marker the record would either serve every stray export or
+ * serve none of the sims — which is why the checker admits this shape by name
+ * and refuses the rest.
+ *
+ * A LEAF: no imports, so the record's checker and the site's embed rule can
+ * each take it without taking anything else with them. Duplicated by
+ * construction — the site cannot import the kernel (decision 18) — and the
+ * copy is asserted rather than trusted.
+ */
+
+/** The suffix that marks an asset as a page to be SERVED rather than bundled. */
+export const SIM_SUFFIX = ".sim.html";
+
+/**
+ * True when this file name is a sim.
+ *
+ * Matched on the whole base name: a file called exactly `.sim.html` is a
+ * dotfile with no stem, so it names no page and is not one — the same
+ * boundary `attachmentKindOf` draws, and it keeps a stray dotfile falling
+ * through to the honest "unexpected file type" refusal.
+ */
+export function isSim(baseName: string): boolean {
+  return baseName.length > SIM_SUFFIX.length && baseName.endsWith(SIM_SUFFIX);
+}
+
+/**
+ * Where a sim is served, derived from where it sits in the record.
+ *
+ * The record path is the identity (product principle 3), so two documents may
+ * each own a `goal-loop.sim.html` without colliding.
+ */
+export function publicSimPath(recordRelative: string): string {
+  return recordRelative.slice(0, -SIM_SUFFIX.length).replaceAll("\\", "/") + ".html";
+}