chapterhouse 0.3.14 → 0.3.16

package/dist/wiki/log-manager.js

@@ -1,20 +1,63 @@
 // ---------------------------------------------------------------------------
-// Wiki log.md manager — append-only chronological operation log
+// Wiki action-log manager — append-only chronological operation log
 // ---------------------------------------------------------------------------
-import { appendFileSync } from "fs";
+import { appendFileSync, existsSync, readFileSync, renameSync } from "fs";
 import { join } from "path";
-import { WIKI_DIR } from "../paths.js";
-import { ensureWikiStructure } from "./fs.js";
-const LOG_PATH = join(WIKI_DIR, "log.md");
+import { WIKI_PAGES_DIR } from "../paths.js";
+import { ensureWikiStructure, writeFileAtomic } from "./fs.js";
+export const ACTION_LOG_PATH = "pages/_meta/log.md";
+const LOG_PATH = join(WIKI_PAGES_DIR, "_meta", "log.md");
+const MAX_LOG_ENTRIES = 500;
+const LOG_ENTRY_RE = /^## \[/gm;
+const INITIAL_LOG = `# Wiki Action Log
+
+_Append-only record of wiki operations._
+
+`;
 /**
- * Append a timestamped entry to log.md.
- * Format: `## [YYYY-MM-DD HH:MM] type | description`
+ * Append a timestamped entry to pages/_meta/log.md.
+ * Format: `## [YYYY-MM-DD HH:MM] action | subject | agent`
  */
-export function appendLog(type, description) {
+export function appendLog(type, subject, agent = resolveAgentName()) {
     ensureWikiStructure();
+    rotateLogIfNeeded();
     const now = new Date();
     const ts = now.toISOString().slice(0, 16).replace("T", " ");
-    const entry = `## [${ts}] ${type} | ${description}\n\n`;
+    const entry = `## [${ts}] ${type} | ${subject} | ${agent}\n\n`;
     appendFileSync(LOG_PATH, entry, "utf-8");
 }
+function rotateLogIfNeeded() {
+    const currentLog = readFileSync(LOG_PATH, "utf-8");
+    const entryCount = (currentLog.match(LOG_ENTRY_RE) ?? []).length;
+    if (entryCount < MAX_LOG_ENTRIES) {
+        return;
+    }
+    const archivePath = join(WIKI_PAGES_DIR, "_meta", `log-${new Date().getFullYear()}.md`);
+    if (!existsSync(archivePath)) {
+        renameSync(LOG_PATH, archivePath);
+    }
+    else {
+        const archivedEntries = extractEntries(currentLog);
+        if (archivedEntries.length > 0) {
+            const separator = readFileSync(archivePath, "utf-8").endsWith("\n\n") ? "" : "\n\n";
+            appendFileSync(archivePath, `${separator}${archivedEntries.join("\n\n")}\n\n`, "utf-8");
+        }
+    }
+    writeFileAtomic(LOG_PATH, INITIAL_LOG);
+}
+function extractEntries(content) {
+    return content
+        .split(/\n{2,}/)
+        .map((chunk) => chunk.trim())
+        .filter((chunk) => chunk.startsWith("## ["));
+}
+function resolveAgentName() {
+    const candidates = [
+        process.env.CHAPTERHOUSE_SESSION_AGENT_NAME,
+        process.env.CHAPTERHOUSE_AGENT_NAME,
+        process.env.COPILOT_AGENT_NAME,
+        process.env.AGENT_NAME,
+    ];
+    return candidates.find((candidate) => candidate && candidate.trim().length > 0)?.trim() ?? "unknown";
+}
 //# sourceMappingURL=log-manager.js.map

package/dist/wiki/log-manager.test.js

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `wiki-log-${process.pid}`);
+const wikiDir = join(sandboxRoot, ".chapterhouse", "wiki");
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+process.env.CHAPTERHOUSE_AGENT_NAME = "wiki-test-agent";
+async function loadModules() {
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const logManager = await import(new URL(`./log-manager.js?case=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?case=${nonce}`, import.meta.url).href);
+    return { logManager, wikiFs };
+}
+function resetSandbox() {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+}
+test.beforeEach(() => {
+    resetSandbox();
+});
+test.after(() => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("appendLog writes action entries to pages/_meta/log.md with the resolved agent name", async () => {
+    const { logManager, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    logManager.appendLog("update", "wiki_update: Chapterhouse (pages/shared/chapterhouse.md)");
+    assert.equal(existsSync(join(wikiDir, "pages", "_meta", "log.md")), true);
+    assert.match(wikiFs.readLogFile(), /^## \[\d{4}-\d{2}-\d{2} \d{2}:\d{2}\] update \| wiki_update: Chapterhouse \(pages\/shared\/chapterhouse\.md\) \| wiki-test-agent/m);
+});
+test("appendLog rotates the active log after 500 entries and keeps appending to a fresh log", async () => {
+    const { logManager, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writeLogFile("# Wiki Action Log\n\n" +
+        Array.from({ length: 500 }, (_, index) => `## [2026-01-01 00:00] update | historical entry ${index + 1} | wiki-test-agent\n\n`).join(""));
+    logManager.appendLog("update", "fresh entry after rotation");
+    const archiveYear = String(new Date().getFullYear());
+    const activeLog = wikiFs.readLogFile();
+    const archivedLog = wikiFs.readPage(`pages/_meta/log-${archiveYear}.md`);
+    assert.ok(archivedLog);
+    assert.match(archivedLog, /historical entry 1/);
+    assert.doesNotMatch(activeLog, /historical entry 1/);
+    assert.match(activeLog, /fresh entry after rotation/);
+});
+//# sourceMappingURL=log-manager.test.js.map

package/dist/wiki/migrate-topics.js

@@ -0,0 +1,132 @@
+// ---------------------------------------------------------------------------
+// One-time migration: enforce the topic-directory structure for entity
+// categories (pages/<category>/<topic-slug>/index.md + facet pages).
+//
+// Fixes wikis created before the structure was enforced, e.g.:
+//   pages/projects/chapterhouse.md               -> pages/projects/chapterhouse/index.md
+//   pages/projects/chapterhouse-feature-ideas.md -> pages/projects/chapterhouse/feature-ideas.md
+//   pages/projects/chapterhouse/decisions.md     -> (already correct, left alone)
+// ---------------------------------------------------------------------------
+import { existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import { getState, setState } from "../store/db.js";
+import { WIKI_PAGES_DIR } from "../paths.js";
+import { ensureWikiStructure, readPage, writePage, deletePage, listPages } from "./fs.js";
+import { rebuildIndexFromPages } from "./index-manager.js";
+import { appendLog } from "./log-manager.js";
+import { entityCategories, slugify } from "./topic-structure.js";
+import { childLogger } from "../util/logger.js";
+const log = childLogger("wiki:migrate-topics");
+const TOPIC_STRUCTURE_KEY = "wiki_topic_structure_v1";
+export function shouldEnforceTopics() {
+    return getState(TOPIC_STRUCTURE_KEY) !== "true";
+}
+function dirNamesUnder(absDir) {
+    if (!existsSync(absDir))
+        return [];
+    return readdirSync(absDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+function fileBaseNamesUnder(absDir) {
+    if (!existsSync(absDir))
+        return [];
+    return readdirSync(absDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(".md"))
+        .map((e) => e.name.replace(/\.md$/i, ""));
+}
+function stripFrontmatter(content) {
+    return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
+}
+/** Move src -> dest. If dest exists, merge src's body into it. Returns true if anything happened. */
+function moveOrMerge(srcRel, destRel, today) {
+    if (srcRel === destRel)
+        return false;
+    const srcContent = readPage(srcRel);
+    if (srcContent == null)
+        return false;
+    const destContent = readPage(destRel);
+    if (destContent != null) {
+        const merged = `${destContent.trimEnd()}\n\n<!-- merged from ${srcRel} on ${today} -->\n\n${stripFrontmatter(srcContent).trim()}\n`;
+        writePage(destRel, merged);
+    }
+    else {
+        writePage(destRel, srcContent);
+    }
+    deletePage(srcRel);
+    appendLog("migrate", `topic-structure: ${srcRel} -> ${destRel}${destContent != null ? " (merged)" : ""}`);
+    log.info({ from: srcRel, to: destRel, merged: destContent != null }, "moved wiki page into topic structure");
+    return true;
+}
+/**
+ * Bring the wiki page tree into compliance with the topic structure.
+ * Idempotent; safe to call repeatedly. Returns the number of pages moved/merged.
+ */
+export function enforceTopicStructure() {
+    ensureWikiStructure();
+    const today = new Date().toISOString().slice(0, 10);
+    let moves = 0;
+    for (const cat of entityCategories()) {
+        const catAbs = join(WIKI_PAGES_DIR, cat);
+        if (!existsSync(catAbs) || !statSync(catAbs).isDirectory()) {
+            // Also handle a bare `pages/<cat>.md` flat file for an entity category.
+            const bareFlat = `pages/${cat}.md`;
+            if (readPage(bareFlat) != null) {
+                if (moveOrMerge(bareFlat, `pages/${cat}/general/index.md`, today)) {
+                    moves++;
+                    log.warn({ page: bareFlat }, "moved entity-category flat file to a 'general' topic; consider splitting it");
+                }
+            }
+            continue;
+        }
+        // Topics already represented by a directory under pages/<cat>/.
+        const existingDirs = new Set(dirNamesUnder(catAbs));
+        // All bare files directly under pages/<cat>/ (the things that need relocating).
+        const bareFiles = fileBaseNamesUnder(catAbs);
+        // The full set of candidate topic stems: existing dirs + every bare file stem.
+        const topicSet = new Set([...existingDirs, ...bareFiles]);
+        for (const base of bareFiles) {
+            const srcRel = `pages/${cat}/${base}.md`;
+            // Is `base` a facet of some other topic T (i.e. base === "T-<facet>")? Pick the longest such T.
+            let facetOf;
+            let facetName = "";
+            for (const t of topicSet) {
+                if (t === base)
+                    continue;
+                if (base.startsWith(`${t}-`) && t.length > (facetOf?.length ?? 0)) {
+                    facetOf = t;
+                    facetName = base.slice(t.length + 1);
+                }
+            }
+            if (facetOf) {
+                const dest = `pages/${cat}/${slugify(facetOf)}/${slugify(facetName) || "notes"}.md`;
+                if (moveOrMerge(srcRel, dest, today))
+                    moves++;
+            }
+            else {
+                const dest = `pages/${cat}/${slugify(base)}/index.md`;
+                if (moveOrMerge(srcRel, dest, today))
+                    moves++;
+            }
+        }
+    }
+    if (moves > 0) {
+        rebuildIndexFromPages();
+        appendLog("migrate", `topic-structure: ${moves} page(s) relocated; index rebuilt`);
+    }
+    else {
+        // Still rebuild once so the index picks up the hierarchical layout.
+        rebuildIndexFromPages();
+    }
+    // Sanity log of anything still off (non-blocking).
+    for (const p of listPages()) {
+        const segs = p.replace(/^pages\//, "").split("/").filter(Boolean);
+        if (entityCategories().includes(segs[0]) && segs.length !== 3) {
+            log.warn({ page: p }, "wiki page still not in canonical topic shape after migration");
+        }
+    }
+    setState(TOPIC_STRUCTURE_KEY, "true");
+    log.info({ moves }, "topic-structure migration complete");
+    return moves;
+}
+//# sourceMappingURL=migrate-topics.js.map

package/dist/wiki/migrate-topics.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `wiki-migrate-topics-${process.pid}`);
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+async function loadModules() {
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const migrate = await import(new URL(`./migrate-topics.js?case=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?case=${nonce}`, import.meta.url).href);
+    return { migrate, wikiFs };
+}
+test.beforeEach(() => {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test.after(() => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("enforceTopicStructure relocates bare entity pages and folds facet pages", async () => {
+    const { migrate, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/projects/chapterhouse.md", "---\ntitle: Chapterhouse\n---\n\n# Chapterhouse\n\n- Source at ~/projects/chapterhouse\n");
+    wikiFs.writePage("pages/projects/chapterhouse-feature-ideas.md", "---\ntitle: Chapterhouse Feature Ideas\n---\n\n# Feature Ideas\n\n- Add wiki topics\n");
+    wikiFs.writePage("pages/projects/chapterhouse/decisions.md", "---\ntitle: Decisions\n---\n\n# Decisions\n\n- Use SSE\n");
+    wikiFs.writePage("pages/conversations/2026-05-09.md", "# 2026-05-09\n\nDaily summary.\n");
+    const moves = migrate.enforceTopicStructure();
+    assert.equal(moves, 2);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse.md"), false);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse-feature-ideas.md"), false);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse/index.md"), true);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse/feature-ideas.md"), true);
+    assert.equal(wikiFs.pageExists("pages/projects/chapterhouse/decisions.md"), true);
+    // Conversations are exempt and untouched.
+    assert.equal(wikiFs.pageExists("pages/conversations/2026-05-09.md"), true);
+    assert.match(wikiFs.readPage("pages/projects/chapterhouse/index.md") ?? "", /Source at ~\/projects\/chapterhouse/);
+    assert.match(wikiFs.readPage("pages/projects/chapterhouse/feature-ideas.md") ?? "", /Add wiki topics/);
+    // Index reflects the new shape.
+    assert.match(wikiFs.readIndexFile(), /^- \[Chapterhouse\]\(pages\/projects\/chapterhouse\/index\.md\) — /m);
+    assert.match(wikiFs.readIndexFile(), /^ {2}- \[.+\]\(pages\/projects\/chapterhouse\/feature-ideas\.md\) — /m);
+    // Idempotent.
+    assert.equal(migrate.enforceTopicStructure(), 0);
+});
+test("enforceTopicStructure merges into an existing topic index instead of clobbering it", async () => {
+    const { migrate, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/people/brian/index.md", "---\ntitle: Brian\n---\n\n# Brian\n\n- Likes Go\n");
+    wikiFs.writePage("pages/people/brian.md", "---\ntitle: Brian\n---\n\n# Brian\n\n- Based in the US\n");
+    const moves = migrate.enforceTopicStructure();
+    assert.equal(moves, 1);
+    assert.equal(wikiFs.pageExists("pages/people/brian.md"), false);
+    const merged = wikiFs.readPage("pages/people/brian/index.md") ?? "";
+    assert.match(merged, /Likes Go/);
+    assert.match(merged, /Based in the US/);
+});
+//# sourceMappingURL=migrate-topics.test.js.map

package/dist/wiki/taxonomy.js

@@ -0,0 +1,73 @@
+import { readPage } from "./fs.js";
+const ENGINEERING_TAGS = [
+    "engineering",
+    "architecture",
+    "release",
+    "runbook",
+    "incident",
+    "orchestration",
+];
+const PEOPLE_TAGS = [
+    "people",
+    "person",
+    "org",
+    "team",
+    "tool",
+];
+const PROCESS_TAGS = [
+    "process",
+    "project",
+    "topic",
+    "area",
+    "decision",
+    "preference",
+    "fact",
+    "routine",
+    "research",
+];
+const META_TAGS = [
+    "meta",
+    "index",
+    "source",
+    "taxonomy",
+    "autostub",
+];
+export const DEFAULT_TAGS = [
+    ...ENGINEERING_TAGS,
+    ...PEOPLE_TAGS,
+    ...PROCESS_TAGS,
+    ...META_TAGS,
+];
+export const TAXONOMY_PATH = "pages/_meta/taxonomy.md";
+export function parseTaxonomyTags(content) {
+    const tags = new Set();
+    let seenHeading = false;
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (/^##\s+.+/.test(line)) {
+            seenHeading = true;
+            continue;
+        }
+        const bulletMatch = line.match(/^-\s+([a-z0-9][a-z0-9-]*)$/i);
+        if (bulletMatch && seenHeading) {
+            tags.add(bulletMatch[1].toLowerCase());
+            continue;
+        }
+        throw new Error(`Invalid wiki taxonomy at ${TAXONOMY_PATH}: expected '## Group' headings with '- tag' bullets.`);
+    }
+    return [...tags];
+}
+export function loadTaxonomy() {
+    const tags = new Set(DEFAULT_TAGS);
+    const override = readPage(TAXONOMY_PATH);
+    if (!override) {
+        return [...tags].sort();
+    }
+    for (const tag of parseTaxonomyTags(override)) {
+        tags.add(tag);
+    }
+    return [...tags].sort();
+}
+//# sourceMappingURL=taxonomy.js.map

package/dist/wiki/taxonomy.test.js

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `wiki-taxonomy-${process.pid}`);
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+async function loadModules() {
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const taxonomy = await import(new URL(`./taxonomy.js?case=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?case=${nonce}`, import.meta.url).href);
+    return { taxonomy, wikiFs };
+}
+function resetSandbox() {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+}
+test.beforeEach(() => {
+    resetSandbox();
+});
+test.after(() => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("loadTaxonomy returns the default tags when no wiki taxonomy file exists", async () => {
+    const { taxonomy } = await loadModules();
+    const merged = taxonomy.loadTaxonomy();
+    assert.deepEqual(merged, [...taxonomy.DEFAULT_TAGS].sort());
+});
+test("loadTaxonomy merges pages/_meta/taxonomy.md entries with the defaults", async () => {
+    const { taxonomy, wikiFs } = await loadModules();
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Engineering
+- orchestration
+- release
+
+## Custom Group
+- teammate
+`);
+    const merged = taxonomy.loadTaxonomy();
+    assert.equal(merged.includes("orchestration"), true);
+    assert.equal(merged.includes("release"), true);
+    assert.equal(merged.includes("teammate"), true);
+    assert.equal(merged.includes("engineering"), true);
+});
+test("loadTaxonomy deduplicates repeated tags across defaults and overrides", async () => {
+    const { taxonomy, wikiFs } = await loadModules();
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Engineering
+- engineering
+- release
+- release
+`);
+    const merged = taxonomy.loadTaxonomy();
+    assert.equal(merged.filter((tag) => tag === "engineering").length, 1);
+    assert.equal(merged.filter((tag) => tag === "release").length, 1);
+});
+test("loadTaxonomy accepts arbitrary heading labels as grouping metadata", async () => {
+    const { taxonomy, wikiFs } = await loadModules();
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Totally New Bucket
+- field-note
+`);
+    const merged = taxonomy.loadTaxonomy();
+    assert.equal(merged.includes("field-note"), true);
+});
+test("loadTaxonomy rejects malformed taxonomy markdown clearly", async () => {
+    const { taxonomy, wikiFs } = await loadModules();
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Engineering
+not-a-bullet
+`);
+    assert.throws(() => taxonomy.loadTaxonomy(), /Invalid wiki taxonomy/i);
+});
+//# sourceMappingURL=taxonomy.test.js.map

package/dist/wiki/topic-structure.js

@@ -0,0 +1,167 @@
+// ---------------------------------------------------------------------------
+// Wiki topic structure: the canonical layout rules for pages/.
+//
+// Entity categories (projects, people, orgs, tools, topics, areas by default)
+// require a topic-level directory: pages/<category>/<topic-slug>/<page>.md,
+// where index.md is the topic's overview page and other files are facets.
+//
+// Flat categories (preferences, facts, routines, decisions) stay as single
+// files: pages/<category>.md.
+//
+// Some prefixes (conversations/, team/, okrs/, kpis/, shared/) follow their
+// own conventions and are exempt from these rules.
+// ---------------------------------------------------------------------------
+import { config } from "../config.js";
+import { normalizeWikiPath } from "./path-utils.js";
+/**
+ * Flat categories: each is a single file at pages/<category>.md.
+ * Note: `decisions` is intentionally NOT flat — a decision is always recorded as a
+ * `decisions.md` facet under the entity it concerns (e.g. pages/projects/chapterhouse/decisions.md).
+ */
+export const FLAT_CATEGORIES = ["preferences", "facts", "routines"];
+/** Path prefixes (relative to the wiki root) that follow their own conventions. */
+export const EXEMPT_PREFIXES = [
+    "pages/conversations/",
+    "pages/team/",
+    "pages/okrs/",
+    "pages/kpis/",
+    "pages/shared/",
+];
+/** Map a `remember`-style category name to its directory under pages/. */
+const CATEGORY_DIR_MAP = {
+    person: "people",
+    people: "people",
+    project: "projects",
+    projects: "projects",
+    org: "orgs",
+    orgs: "orgs",
+    organization: "orgs",
+    tool: "tools",
+    tools: "tools",
+    topic: "topics",
+    topics: "topics",
+    area: "areas",
+    areas: "areas",
+    preference: "preferences",
+    preferences: "preferences",
+    fact: "facts",
+    facts: "facts",
+    routine: "routines",
+    routines: "routines",
+    decision: "decisions",
+    decisions: "decisions",
+};
+export function getCategoryDir(category) {
+    return CATEGORY_DIR_MAP[category.toLowerCase()] || category.toLowerCase();
+}
+/** The active list of entity-category directories (configurable via WIKI_ENTITY_CATEGORIES). */
+export function entityCategories() {
+    return config.wikiEntityCategories;
+}
+function isEntityCategory(dir) {
+    return entityCategories().includes(dir);
+}
+function isFlatCategory(dir) {
+    return FLAT_CATEGORIES.includes(dir);
+}
+function isExemptPath(relativePath) {
+    return EXEMPT_PREFIXES.some((p) => relativePath.startsWith(p));
+}
+/** Slugify a free-text name into a wiki-safe path segment. */
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        || "untitled";
+}
+/**
+ * Canonical path for an entity topic page.
+ * topicPagePath("project", "Chapterhouse")              -> "pages/projects/chapterhouse/index.md"
+ * topicPagePath("project", "Chapterhouse", "decisions") -> "pages/projects/chapterhouse/decisions.md"
+ */
+export function topicPagePath(category, entity, facet = "index") {
+    const dir = getCategoryDir(category);
+    const topic = slugify(entity);
+    const page = slugify(facet) || "index";
+    return `pages/${dir}/${topic}/${page}.md`;
+}
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Validate that a tool-writable wiki page path conforms to the canonical layout.
+ * Assumes the path has already passed the basic safety checks in assertPagePath
+ * (under pages/, ends in .md, no traversal).
+ */
+export function validateTopicPath(relativePath) {
+    const path = normalizeWikiPath(relativePath);
+    if (!path.startsWith("pages/")) {
+        // assertPagePath handles this; nothing topic-structural to add.
+        return { ok: true };
+    }
+    if (isExemptPath(path)) {
+        return { ok: true };
+    }
+    const rest = path.slice("pages/".length); // e.g. "projects/chapterhouse/index.md"
+    const segments = rest.split("/").filter(Boolean);
+    // For a single-segment path the "category" is the bare filename (pages/preferences.md).
+    const topDir = segments.length === 1 ? segments[0].replace(/\.md$/i, "") : (segments[0] ?? "");
+    if (isFlatCategory(topDir)) {
+        if (segments.length === 1 && rest === `${topDir}.md`) {
+            return { ok: true };
+        }
+        return {
+            ok: false,
+            reason: `'${topDir}' is a flat category and must be a single file.`,
+            suggestion: `pages/${topDir}.md`,
+        };
+    }
+    if (isEntityCategory(topDir)) {
+        if (segments.length === 2) {
+            // pages/projects/foo.md  ->  pages/projects/foo/index.md
+            const base = slugify(segments[1].replace(/\.md$/i, ""));
+            return {
+                ok: false,
+                reason: `Entity category '${topDir}' requires a topic directory: pages/${topDir}/<topic>/<page>.md. ` +
+                    `'index.md' is the topic's overview page.`,
+                suggestion: `pages/${topDir}/${base}/index.md`,
+            };
+        }
+        if (segments.length !== 3) {
+            const flat = segments.slice(1, -1).map((s) => slugify(s.replace(/\.md$/i, ""))).filter(Boolean);
+            const topic = flat[0] || "topic";
+            const page = slugify(segments[segments.length - 1].replace(/\.md$/i, "")) || "index";
+            return {
+                ok: false,
+                reason: `Entity category '${topDir}' allows exactly one topic level: pages/${topDir}/<topic>/<page>.md. ` +
+                    `Got ${segments.length} path segments.`,
+                suggestion: `pages/${topDir}/${topic}/${page}.md`,
+            };
+        }
+        const [, topic, file] = segments;
+        const pageSlug = file.replace(/\.md$/i, "");
+        if (!SLUG_RE.test(topic) || !SLUG_RE.test(pageSlug)) {
+            return {
+                ok: false,
+                reason: `Topic and page names must be lowercase slugs ([a-z0-9-]).`,
+                suggestion: `pages/${topDir}/${slugify(topic)}/${slugify(pageSlug) || "index"}.md`,
+            };
+        }
+        return { ok: true };
+    }
+    // Unknown top-level directory.
+    const valid = [...entityCategories(), ...FLAT_CATEGORIES].sort().join(", ");
+    return {
+        ok: false,
+        reason: `'${topDir}' is not a recognized wiki category. ` +
+            `Use one of: ${valid} (entity categories take a topic directory: pages/<category>/<topic>/<page>.md). ` +
+            `Conversations and team pages are written by the system.`,
+    };
+}
+/** Convenience: returns the error message string for an invalid path, or undefined if valid. */
+export function topicPathError(relativePath) {
+    const result = validateTopicPath(relativePath);
+    if (result.ok)
+        return undefined;
+    return result.suggestion ? `${result.reason} Use: ${result.suggestion}` : result.reason;
+}
+//# sourceMappingURL=topic-structure.js.map