chapterhouse 0.3.13 → 0.3.15

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

package/dist/wiki/topic-structure.test.js

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getCategoryDir, slugify, topicPagePath, validateTopicPath, topicPathError, } from "./topic-structure.js";
+test("getCategoryDir maps category names to directories", () => {
+    assert.equal(getCategoryDir("project"), "projects");
+    assert.equal(getCategoryDir("projects"), "projects");
+    assert.equal(getCategoryDir("person"), "people");
+    assert.equal(getCategoryDir("org"), "orgs");
+    assert.equal(getCategoryDir("tool"), "tools");
+    assert.equal(getCategoryDir("topic"), "topics");
+    assert.equal(getCategoryDir("area"), "areas");
+    assert.equal(getCategoryDir("decision"), "decisions");
+    assert.equal(getCategoryDir("preference"), "preferences");
+});
+test("slugify normalizes free text into a safe path segment", () => {
+    assert.equal(slugify("Chapter House!"), "chapter-house");
+    assert.equal(slugify("  --Foo_Bar--  "), "foo-bar");
+    assert.equal(slugify("v0.3.14"), "v0-3-14");
+    assert.equal(slugify("!!!"), "untitled");
+});
+test("topicPagePath builds canonical paths", () => {
+    assert.equal(topicPagePath("project", "Chapterhouse"), "pages/projects/chapterhouse/index.md");
+    assert.equal(topicPagePath("project", "Chapterhouse", "decisions"), "pages/projects/chapterhouse/decisions.md");
+    assert.equal(topicPagePath("person", "Brian K"), "pages/people/brian-k/index.md");
+    assert.equal(topicPagePath("tool", "Kubernetes"), "pages/tools/kubernetes/index.md");
+});
+test("validateTopicPath accepts canonical and exempt paths", () => {
+    assert.deepEqual(validateTopicPath("pages/projects/chapterhouse/index.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/projects/chapterhouse/decisions.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/people/brian/index.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/preferences.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/facts.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/conversations/2026-05-12.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/team/onboarding.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/okrs/2026-Q2.md"), { ok: true });
+});
+test("validateTopicPath rejects a bare entity-category file and suggests the topic index", () => {
+    const r = validateTopicPath("pages/projects/chapterhouse.md");
+    assert.equal(r.ok, false);
+    assert.equal(r.ok === false && r.suggestion, "pages/projects/chapterhouse/index.md");
+});
+test("validateTopicPath rejects entity paths that nest too deep", () => {
+    const r = validateTopicPath("pages/projects/chapterhouse/sub/deep.md");
+    assert.equal(r.ok, false);
+    assert.equal(r.ok === false && r.suggestion, "pages/projects/chapterhouse/deep.md");
+});
+test("validateTopicPath rejects a flat category used as a directory", () => {
+    const r = validateTopicPath("pages/preferences/foo.md");
+    assert.equal(r.ok, false);
+    assert.equal(r.ok === false && r.suggestion, "pages/preferences.md");
+});
+test("validateTopicPath treats `decisions` as an entity facet, not a flat page", () => {
+    // A standalone pages/decisions.md is no longer valid…
+    assert.equal(validateTopicPath("pages/decisions.md").ok, false);
+    // …decisions live as a facet under the entity they concern.
+    assert.deepEqual(validateTopicPath("pages/projects/chapterhouse/decisions.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/tools/kubernetes/decisions.md"), { ok: true });
+});
+test("validateTopicPath rejects unknown top-level categories", () => {
+    const r = validateTopicPath("pages/randomstuff/foo.md");
+    assert.equal(r.ok, false);
+    assert.match(r.ok === false ? r.reason : "", /not a recognized wiki category/);
+});
+test("validateTopicPath rejects non-slug topic or page names", () => {
+    const r = validateTopicPath("pages/projects/Chapter House/index.md");
+    assert.equal(r.ok, false);
+    assert.equal(r.ok === false && r.suggestion, "pages/projects/chapter-house/index.md");
+});
+test("topicPathError returns a message for invalid paths and undefined for valid ones", () => {
+    assert.equal(topicPathError("pages/projects/chapterhouse/index.md"), undefined);
+    assert.equal(topicPathError("pages/preferences.md"), undefined);
+    assert.match(String(topicPathError("pages/projects/chapterhouse.md")), /Use: pages\/projects\/chapterhouse\/index\.md/);
+});
+//# sourceMappingURL=topic-structure.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Chapterhouse — a team-level AI assistant for engineering teams, built on the GitHub Copilot SDK. Web UI only.",
   "bin": {
     "chapterhouse": "dist/cli.js"
@@ -51,7 +51,6 @@
   },
   "type": "module",
   "dependencies": {
-    "@bradygaster/squad-sdk": "0.9.4",
     "@github/copilot-sdk": "^0.3.0",
     "azure-devops-node-api": "^15.1.2",
     "better-sqlite3": "^12.6.2",
@@ -65,7 +64,6 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@bradygaster/squad-cli": "^0.9.4",
     "@commitlint/cli": "^21.0.0",
     "@commitlint/config-conventional": "^21.0.0",
     "@types/better-sqlite3": "^7.6.13",