benjamin-docs 0.1.0

package/dist/src/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_DOCS_ROOT = "benjamin-docs";
+export declare const CONFIG_DIR = ".benjamin-docs";
+export declare const MANIFEST_FILE = "manifest.json";
+export declare const SCOPES_FILE = "scopes.json";
+export declare const ANCHORS_FILE = "anchors.json";
+export declare const CONFIG_FILE = "config.json";
+export declare const KNOWN_SCOPES: readonly ["project", "feature", "release", "handoff"];
+export declare const KNOWN_FOCUS_TYPES: readonly ["project", "codebase", "feature"];
+export declare const KNOWN_AUDIENCES: readonly ["developer", "designer", "agent", "business", "public", "user", "advisor"];
+export declare const KNOWN_STATUSES: readonly ["draft", "review", "approved", "stale", "archived"];
+export declare const KNOWN_VISIBILITIES: readonly ["private", "unlisted", "public"];
+export declare const KNOWN_SOURCES: readonly ["session-capture", "manual", "codebase-scan", "release-sync"];

package/dist/src/constants.js

@@ -0,0 +1,13 @@
+export const DEFAULT_DOCS_ROOT = "benjamin-docs";
+export const CONFIG_DIR = ".benjamin-docs";
+export const MANIFEST_FILE = "manifest.json";
+export const SCOPES_FILE = "scopes.json";
+export const ANCHORS_FILE = "anchors.json";
+export const CONFIG_FILE = "config.json";
+export const KNOWN_SCOPES = ["project", "feature", "release", "handoff"];
+export const KNOWN_FOCUS_TYPES = ["project", "codebase", "feature"];
+export const KNOWN_AUDIENCES = ["developer", "designer", "agent", "business", "public", "user", "advisor"];
+export const KNOWN_STATUSES = ["draft", "review", "approved", "stale", "archived"];
+export const KNOWN_VISIBILITIES = ["private", "unlisted", "public"];
+export const KNOWN_SOURCES = ["session-capture", "manual", "codebase-scan", "release-sync"];
+//# sourceMappingURL=constants.js.map

package/dist/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AACjD,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAC3C,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAC7C,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AACzC,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAU,CAAC;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AACpH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AAC5F,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,iBAAiB,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,CAAU,CAAC"}

package/dist/src/export.d.ts

@@ -0,0 +1 @@
+export declare function exportAudience(root: string, audience: string): string[];

package/dist/src/export.js

@@ -0,0 +1,70 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { KNOWN_AUDIENCES } from "./constants.js";
+import { assertGeneratedPathSafe, ensureGeneratedDir, lstatIfExists, rootPath, writeGeneratedText } from "./fsx.js";
+import { parseMarkdown } from "./frontmatter.js";
+import { readConfig } from "./project-config.js";
+import { validateProject } from "./validate.js";
+export function exportAudience(root, audience) {
+    const selectedAudience = parseAudience(audience);
+    const validation = validateProject(root);
+    if (validation.errors.length > 0) {
+        throw new Error(["Cannot export while validation has errors:", ...validation.errors.map((error) => `- ${error}`)].join("\n"));
+    }
+    const config = readConfig(root);
+    const docsRoot = rootPath(root, config.docsRoot);
+    const docs = findMarkdownFiles(docsRoot);
+    const bundleRelativeRoot = `exports/${selectedAudience}`;
+    prepareCleanBundleDirectory(root, selectedAudience);
+    const written = [];
+    for (const docPath of docs) {
+        const content = readFileSync(docPath, "utf8");
+        const parsed = parseMarkdown(content);
+        if (!parsed.frontmatter.audience.includes(selectedAudience))
+            continue;
+        const relativePath = relative(docsRoot, docPath).split(sep).join("/");
+        const targetRelativePath = `${bundleRelativeRoot}/${relativePath}`;
+        const targetPath = rootPath(root, ...targetRelativePath.split("/"));
+        writeGeneratedText(root, targetRelativePath, content);
+        written.push(targetPath);
+    }
+    return written;
+}
+function parseAudience(audience) {
+    if (!KNOWN_AUDIENCES.includes(audience)) {
+        throw new Error(`Unknown audience: ${audience}. Expected one of: ${KNOWN_AUDIENCES.join(", ")}`);
+    }
+    return audience;
+}
+function prepareCleanBundleDirectory(root, audience) {
+    const parts = ["exports", audience];
+    const relativePath = parts.join("/");
+    const bundleRoot = rootPath(root, ...parts);
+    assertGeneratedPathSafe(root, parts, "Generated output path", "directory");
+    const stat = lstatIfExists(bundleRoot);
+    if (stat) {
+        rmSync(bundleRoot, { recursive: true, force: true });
+    }
+    ensureGeneratedDir(root, relativePath);
+    return bundleRoot;
+}
+function findMarkdownFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const files = [];
+    for (const entry of readdirSync(dir)) {
+        const fullPath = rootPath(dir, entry);
+        const stat = lstatSync(fullPath);
+        if (stat.isSymbolicLink()) {
+            if (fullPath.endsWith(".md"))
+                files.push(fullPath);
+            continue;
+        }
+        if (stat.isDirectory())
+            files.push(...findMarkdownFiles(fullPath));
+        if (stat.isFile() && fullPath.endsWith(".md"))
+            files.push(fullPath);
+    }
+    return files.sort();
+}
+//# sourceMappingURL=export.js.map

package/dist/src/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/export.ts"],"names":[],"mappings":"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"}

package/dist/src/frontmatter.d.ts

@@ -0,0 +1,3 @@
+import type { DocFrontmatter, ParsedMarkdown } from "./types.js";
+export declare function parseMarkdown(markdown: string): ParsedMarkdown;
+export declare function serializeMarkdown(frontmatter: DocFrontmatter, body: string): string;

package/dist/src/frontmatter.js

@@ -0,0 +1,119 @@
+import { KNOWN_AUDIENCES, KNOWN_SCOPES, KNOWN_SOURCES, KNOWN_STATUSES, KNOWN_VISIBILITIES } from "./constants.js";
+const ORDER = [
+    "title",
+    "scope",
+    "scope_id",
+    "audience",
+    "status",
+    "visibility",
+    "updated",
+    "source",
+];
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+export function parseMarkdown(markdown) {
+    const normalized = normalizeMarkdown(markdown);
+    if (!normalized.startsWith("---\n")) {
+        throw new Error("Markdown file is missing frontmatter");
+    }
+    const end = normalized.indexOf("\n---\n", 4);
+    if (end === -1) {
+        throw new Error("Markdown frontmatter is not closed");
+    }
+    const raw = normalized.slice(4, end);
+    const body = normalized.slice(end + 5);
+    const frontmatter = {};
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            throw new Error(`Invalid frontmatter line: ${line}`);
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        frontmatter[key] = parseValue(value);
+    }
+    return { frontmatter: validateFrontmatter(frontmatter), body };
+}
+export function serializeMarkdown(frontmatter, body) {
+    const lines = ORDER.map((key) => `${key}: ${serializeValue(frontmatter[key])}`);
+    return `---\n${lines.join("\n")}\n---\n\n${body.replace(/^\n+/, "")}`;
+}
+function parseValue(value) {
+    if (value.startsWith("[") && value.endsWith("]")) {
+        const inner = value.slice(1, -1).trim();
+        if (!inner)
+            return [];
+        return inner.split(",").map((item) => item.trim());
+    }
+    return value;
+}
+function serializeValue(value) {
+    if (Array.isArray(value))
+        return `[${value.join(", ")}]`;
+    return value;
+}
+function normalizeMarkdown(markdown) {
+    return markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+}
+function validateFrontmatter(frontmatter) {
+    const scope = knownValue("scope", requiredString(frontmatter, "scope"), KNOWN_SCOPES);
+    const status = knownValue("status", requiredString(frontmatter, "status"), KNOWN_STATUSES);
+    const visibility = knownValue("visibility", requiredString(frontmatter, "visibility"), KNOWN_VISIBILITIES);
+    const source = knownValue("source", requiredString(frontmatter, "source"), KNOWN_SOURCES);
+    const audience = requiredAudience(frontmatter);
+    return {
+        title: requiredString(frontmatter, "title"),
+        scope,
+        scope_id: requiredString(frontmatter, "scope_id"),
+        audience,
+        status,
+        visibility,
+        updated: requiredDate(frontmatter),
+        source,
+    };
+}
+function requiredString(frontmatter, key) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        throw new Error(`Missing required frontmatter field: ${key}`);
+    }
+    if (typeof value !== "string") {
+        throw new Error(`Frontmatter field ${key} must be a string`);
+    }
+    return value;
+}
+function requiredAudience(frontmatter) {
+    const value = frontmatter.audience;
+    if (value === undefined) {
+        throw new Error("Missing required frontmatter field: audience");
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("Frontmatter field audience must be an array");
+    }
+    const audiences = [];
+    for (const audience of value) {
+        if (typeof audience !== "string") {
+            throw new Error("Frontmatter field audience must contain only strings");
+        }
+        audiences.push(knownValue("audience", audience, KNOWN_AUDIENCES));
+    }
+    if (audiences.length === 0) {
+        throw new Error("Frontmatter field audience must include at least one value");
+    }
+    return audiences;
+}
+function requiredDate(frontmatter) {
+    const value = requiredString(frontmatter, "updated");
+    const date = new Date(`${value}T00:00:00.000Z`);
+    if (!DATE_PATTERN.test(value) || Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
+        throw new Error("Frontmatter field updated must be YYYY-MM-DD");
+    }
+    return value;
+}
+function knownValue(field, value, knownValues) {
+    if (!knownValues.includes(value)) {
+        throw new Error(`Unknown frontmatter ${field}: ${value}`);
+    }
+    return value;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/src/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/src/fsx.d.ts

@@ -0,0 +1,14 @@
+import { lstatSync } from "node:fs";
+type GeneratedTarget = "any" | "directory" | "file";
+export declare function pathExists(path: string): boolean;
+export declare function readJson<T>(path: string): T;
+export declare function readGeneratedJson<T>(root: string, relativePath: string, label?: string): T;
+export declare function ensureGeneratedDir(root: string, relativePath: string, label?: string): void;
+export declare function writeGeneratedJson(root: string, relativePath: string, value: unknown, label?: string): void;
+export declare function writeGeneratedText(root: string, relativePath: string, value: string, label?: string): void;
+export declare function writeGeneratedJsonIfMissing(root: string, relativePath: string, value: unknown, label?: string): boolean;
+export declare function writeGeneratedTextIfMissing(root: string, relativePath: string, value: string, label?: string): boolean;
+export declare function assertGeneratedPathSafe(root: string, parts: string[], label?: string, target?: GeneratedTarget): void;
+export declare function lstatIfExists(path: string): ReturnType<typeof lstatSync> | undefined;
+export declare function rootPath(root: string, ...parts: string[]): string;
+export {};

package/dist/src/fsx.js

@@ -0,0 +1,129 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep, win32 } from "node:path";
+const DEFAULT_GENERATED_LABEL = "Generated output path";
+export function pathExists(path) {
+    return existsSync(path);
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+export function readGeneratedJson(root, relativePath, label = DEFAULT_GENERATED_LABEL) {
+    const parts = generatedPathParts(relativePath, label);
+    assertGeneratedPathSafe(root, parts, label, "file");
+    return readJson(rootPath(root, ...parts));
+}
+export function ensureGeneratedDir(root, relativePath, label = DEFAULT_GENERATED_LABEL) {
+    const parts = generatedPathParts(relativePath, label);
+    const fullPath = rootPath(root, ...parts);
+    assertGeneratedPathSafe(root, parts, label, "directory");
+    mkdirSync(fullPath, { recursive: true });
+    assertGeneratedPathSafe(root, parts, label, "directory");
+}
+export function writeGeneratedJson(root, relativePath, value, label = DEFAULT_GENERATED_LABEL) {
+    writeGeneratedText(root, relativePath, `${JSON.stringify(value, null, 2)}\n`, label);
+}
+export function writeGeneratedText(root, relativePath, value, label = DEFAULT_GENERATED_LABEL) {
+    const parts = generatedPathParts(relativePath, label);
+    const fullPath = prepareGeneratedFile(root, parts, label);
+    writeFileSync(fullPath, value, "utf8");
+}
+export function writeGeneratedJsonIfMissing(root, relativePath, value, label = DEFAULT_GENERATED_LABEL) {
+    return writeGeneratedTextIfMissing(root, relativePath, `${JSON.stringify(value, null, 2)}\n`, label);
+}
+export function writeGeneratedTextIfMissing(root, relativePath, value, label = DEFAULT_GENERATED_LABEL) {
+    const parts = generatedPathParts(relativePath, label);
+    assertGeneratedPathSafe(root, parts, label, "file");
+    const fullPath = rootPath(root, ...parts);
+    if (lstatIfExists(fullPath))
+        return false;
+    prepareGeneratedParent(root, parts, label);
+    assertGeneratedPathSafe(root, parts, label, "file");
+    writeFileSync(fullPath, value, "utf8");
+    return true;
+}
+export function assertGeneratedPathSafe(root, parts, label = DEFAULT_GENERATED_LABEL, target = "any") {
+    const realRoot = realpathSync(root);
+    for (const [index] of parts.entries()) {
+        const currentParts = parts.slice(0, index + 1);
+        const current = rootPath(root, ...currentParts);
+        const displayPath = currentParts.join("/");
+        const stat = lstatIfExists(current);
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink()) {
+            throw new Error(`${label} must not be a symlink: ${displayPath}`);
+        }
+        const realCurrent = realpathSync(current);
+        if (!isInsideRoot(realRoot, realCurrent)) {
+            throw new Error(`${label} must remain inside project root: ${displayPath}`);
+        }
+        if (index < parts.length - 1 && !stat.isDirectory()) {
+            throw new Error(`${label} parent must be a directory: ${displayPath}`);
+        }
+        if (index === parts.length - 1) {
+            if (target === "directory" && !stat.isDirectory()) {
+                throw new Error(`${label} must be a directory: ${displayPath}`);
+            }
+            if (target === "file" && !stat.isFile()) {
+                throw new Error(`${label} must be a file: ${displayPath}`);
+            }
+        }
+    }
+}
+export function lstatIfExists(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return undefined;
+        throw error;
+    }
+}
+export function rootPath(root, ...parts) {
+    const resolvedRoot = resolve(root);
+    for (const part of parts) {
+        if (isAbsolute(part)) {
+            throw new Error(`Refusing absolute path segment outside root: ${part}`);
+        }
+    }
+    const resolvedPath = resolve(resolvedRoot, ...parts);
+    const relativePath = relative(resolvedRoot, resolvedPath);
+    if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+        throw new Error(`Resolved path is outside root: ${resolvedPath}`);
+    }
+    return resolvedPath;
+}
+function prepareGeneratedFile(root, parts, label) {
+    assertGeneratedPathSafe(root, parts, label, "file");
+    prepareGeneratedParent(root, parts, label);
+    assertGeneratedPathSafe(root, parts, label, "file");
+    return rootPath(root, ...parts);
+}
+function prepareGeneratedParent(root, parts, label) {
+    const parentParts = parts.slice(0, -1);
+    if (parentParts.length === 0)
+        return;
+    const parentPath = rootPath(root, ...parentParts);
+    assertGeneratedPathSafe(root, parentParts, label, "directory");
+    mkdirSync(parentPath, { recursive: true });
+    assertGeneratedPathSafe(root, parentParts, label, "directory");
+}
+function generatedPathParts(relativePath, label) {
+    if (!relativePath || isAbsolute(relativePath) || win32.isAbsolute(relativePath) || relativePath.includes("\\")) {
+        throw new Error(`${label} must be a relative project path: ${relativePath}`);
+    }
+    const parts = relativePath.split("/");
+    if (parts.some((part) => part === "" || part === "." || part === ".." || isAbsolute(part) || win32.isAbsolute(part))) {
+        throw new Error(`${label} must be a relative project path: ${relativePath}`);
+    }
+    return parts;
+}
+function isNotFoundError(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isInsideRoot(root, target) {
+    const relativePath = relative(root, target);
+    return relativePath === "" || (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath));
+}
+//# sourceMappingURL=fsx.js.map

package/dist/src/fsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsx.js","sourceRoot":"","sources":["../../src/fsx.ts"],"names":[],"mappings":"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"}

package/dist/src/info.d.ts

@@ -0,0 +1,3 @@
+export declare function getPackageVersion(): string;
+export declare function getHelpText(): string;
+export declare function getIntroductionText(): string;

package/dist/src/info.js

@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export function getPackageVersion() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const packagePath = join(currentDir, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+    return pkg.version;
+}
+export function getHelpText() {
+    return [
+        "benjamin-docs",
+        "",
+        "Repo-local project memory for humans and AI agents.",
+        "",
+        "What it does:",
+        "  Creates a small docs workspace in your project.",
+        "  Gives your AI agent a clear place to capture decisions, plans, open questions, and handoffs.",
+        "  Keeps those docs local unless you choose to share them.",
+        "",
+        "If you are here with an AI agent:",
+        "  1. Run: benjamin-docs introduce",
+        "  2. If you only have a chat, ask the agent to create a project folder from this chat.",
+        "     A good default is ~/Documents/Benjamin Docs/<Project Name>.",
+        "  3. Otherwise run: benjamin-docs init",
+        "  4. Ask: Capture the current project baseline with benjamin-docs in plain language.",
+        "",
+        "Common commands:",
+        "  benjamin-docs --version",
+        "  benjamin-docs introduce",
+        "  benjamin-docs init",
+        "  benjamin-docs init --mode codebase",
+        "  benjamin-docs init --mode feature --feature booking-capacity",
+        "  benjamin-docs next",
+        "  benjamin-docs status",
+        "  benjamin-docs validate",
+        "  benjamin-docs scope create feature booking-capacity",
+        "  benjamin-docs anchor add booking-capacity-rules src/features/booking/capacity.ts",
+        "  benjamin-docs export --audience developer",
+        "  benjamin-docs promote --to codebase",
+        "",
+        "Start here:",
+        "  benjamin-docs introduce",
+        "  benjamin-docs init",
+        "  benjamin-docs next",
+    ].join("\n");
+}
+export function getIntroductionText() {
+    return [
+        "benjamin-docs turns planning and build conversations into durable project memory.",
+        "",
+        "In plain language: it gives your project a local notebook that both humans and AI agents can read later.",
+        "",
+        "Your agent can use that notebook to capture what the project is, what was decided, what was rejected, what is still unclear, and what should happen next.",
+        "",
+        "The docs live inside your project, close to the work, so they can be versioned, reviewed, and reused by future sessions.",
+        "",
+        "Your docs are not uploaded or published by the CLI. The repo-local docs are the source of truth.",
+        "",
+        "If you only have a chat, ask your AI agent to create a new project from the chat with benjamin-docs. A good default location is ~/Documents/Benjamin Docs/<Project Name>.",
+        "",
+        "If you already have a project folder, ask your AI agent to run `benjamin-docs init`, then capture the current project baseline in plain language.",
+    ].join("\n");
+}
+//# sourceMappingURL=info.js.map

package/dist/src/info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../../src/info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,iBAAiB;IAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACjE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAwB,CAAC;IACjF,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,eAAe;QACf,EAAE;QACF,qDAAqD;QACrD,EAAE;QACF,eAAe;QACf,mDAAmD;QACnD,gGAAgG;QAChG,2DAA2D;QAC3D,EAAE;QACF,mCAAmC;QACnC,mCAAmC;QACnC,wFAAwF;QACxF,kEAAkE;QAClE,wCAAwC;QACxC,sFAAsF;QACtF,EAAE;QACF,kBAAkB;QAClB,2BAA2B;QAC3B,2BAA2B;QAC3B,sBAAsB;QACtB,sCAAsC;QACtC,gEAAgE;QAChE,sBAAsB;QACtB,wBAAwB;QACxB,0BAA0B;QAC1B,uDAAuD;QACvD,oFAAoF;QACpF,6CAA6C;QAC7C,uCAAuC;QACvC,EAAE;QACF,aAAa;QACb,2BAA2B;QAC3B,sBAAsB;QACtB,sBAAsB;KACvB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,mFAAmF;QACnF,EAAE;QACF,0GAA0G;QAC1G,EAAE;QACF,2JAA2J;QAC3J,EAAE;QACF,0HAA0H;QAC1H,EAAE;QACF,kGAAkG;QAClG,EAAE;QACF,2KAA2K;QAC3K,EAAE;QACF,mJAAmJ;KACpJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/src/init.d.ts

@@ -0,0 +1,12 @@
+import type { BenjaminDocsConfig, FocusType } from "./types.js";
+export interface InitProjectOptions {
+    setup?: FocusType;
+    feature?: string;
+    docsRoot?: string;
+}
+export interface InitProjectResult {
+    written: string[];
+    config: BenjaminDocsConfig;
+}
+export declare function initProject(root: string, options?: InitProjectOptions): InitProjectResult;
+export declare function promoteToCodebase(root: string): string[];

package/dist/src/init.js

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { ANCHORS_FILE, CONFIG_DIR, CONFIG_FILE, DEFAULT_DOCS_ROOT, MANIFEST_FILE, SCOPES_FILE } from "./constants.js";
+import { ensureGeneratedDir, readGeneratedJson, writeGeneratedJson, writeGeneratedJsonIfMissing, writeGeneratedTextIfMissing, } from "./fsx.js";
+import { codebaseDocs, featureDocs, workspaceDocs } from "./templates.js";
+import { assertSafeDocsRoot, defaultConfig, normalizeConfig } from "./project-config.js";
+const METADATA_LABEL = "Metadata path";
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function initProject(root, options = {}) {
+    const written = [];
+    const docsRoot = options.docsRoot ?? DEFAULT_DOCS_ROOT;
+    assertSafeDocsRoot(docsRoot);
+    const setup = options.setup ?? "project";
+    const feature = options.feature;
+    if (setup === "feature" && (!feature || !SLUG_PATTERN.test(feature))) {
+        throw new Error("Usage: benjamin-docs init --mode feature --feature <slug>");
+    }
+    const mode = setup === "codebase" || (setup === "feature" && looksLikeCodebase(root)) ? "codebase" : "planning";
+    const config = defaultConfig({ mode, docsRoot, focus: setup, feature });
+    ensureGeneratedDir(root, docsRoot);
+    ensureGeneratedDir(root, CONFIG_DIR, METADATA_LABEL);
+    const docs = workspaceDocs(docsRoot);
+    const featureFiles = setup === "feature" && feature ? featureDocs(feature, docsRoot) : [];
+    for (const doc of [...docs, ...featureFiles]) {
+        if (writeGeneratedTextIfMissing(root, doc.path, doc.content)) {
+            written.push(doc.path);
+        }
+    }
+    writeConfig(root, config, written);
+    writeManifest(root, [...docs, ...featureFiles].map((item) => item.path), written);
+    writeScopes(root, docsRoot, feature, written);
+    writeJsonIfMissing(root, [CONFIG_DIR, ANCHORS_FILE], { version: 1, anchors: {} }, written);
+    return { written, config };
+}
+export function promoteToCodebase(root) {
+    const written = [];
+    const config = normalizeConfig(readGeneratedJson(root, `${CONFIG_DIR}/${CONFIG_FILE}`, METADATA_LABEL));
+    assertSafeDocsRoot(config.docsRoot);
+    for (const codebaseDoc of codebaseDocs(config.docsRoot)) {
+        if (writeGeneratedTextIfMissing(root, codebaseDoc.path, codebaseDoc.content)) {
+            written.push(codebaseDoc.path);
+        }
+    }
+    config.mode = "codebase";
+    config.focus = "codebase";
+    writeGeneratedJson(root, `${CONFIG_DIR}/${CONFIG_FILE}`, config, METADATA_LABEL);
+    updateManifest(root, config.docsRoot);
+    updateScopes(root, config.docsRoot);
+    return written;
+}
+function writeConfig(root, config, written) {
+    const path = `${CONFIG_DIR}/${CONFIG_FILE}`;
+    if (writeGeneratedJsonIfMissing(root, path, config, METADATA_LABEL)) {
+        written.push(path);
+        return;
+    }
+    const existing = normalizeConfig(readGeneratedJson(root, path, METADATA_LABEL));
+    const next = {
+        ...existing,
+        docsRoot: existing.docsRoot || config.docsRoot,
+        mode: config.mode,
+        focus: config.focus,
+        feature: config.feature,
+    };
+    writeGeneratedJson(root, path, next, METADATA_LABEL);
+}
+function writeManifest(root, docs, written) {
+    const path = `${CONFIG_DIR}/${MANIFEST_FILE}`;
+    const initial = { version: 1, docs };
+    if (writeGeneratedJsonIfMissing(root, path, initial, METADATA_LABEL)) {
+        written.push(path);
+        return;
+    }
+    const manifest = readGeneratedJson(root, path, METADATA_LABEL);
+    for (const doc of docs) {
+        if (!manifest.docs.includes(doc))
+            manifest.docs.push(doc);
+    }
+    writeGeneratedJson(root, path, manifest, METADATA_LABEL);
+}
+function writeScopes(root, docsRoot, feature, written) {
+    const path = `${CONFIG_DIR}/${SCOPES_FILE}`;
+    const records = baseScopes(docsRoot, feature);
+    const initial = { version: 1, scopes: records };
+    if (writeGeneratedJsonIfMissing(root, path, initial, METADATA_LABEL)) {
+        written.push(path);
+        return;
+    }
+    const scopes = readGeneratedJson(root, path, METADATA_LABEL);
+    for (const record of records) {
+        if (!scopes.scopes.some((scope) => scope.id === record.id))
+            scopes.scopes.push(record);
+    }
+    writeGeneratedJson(root, path, scopes, METADATA_LABEL);
+}
+function baseScopes(docsRoot, feature) {
+    return [
+        { id: "project", kind: "project", title: "Project", path: `${docsRoot}/project`, status: "draft" },
+        { id: "human-brief", kind: "handoff", title: "Human Brief", path: `${docsRoot}/handoff/human-brief.md`, status: "draft" },
+        { id: "agent-brief", kind: "handoff", title: "Agent Brief", path: `${docsRoot}/handoff/agent-brief.md`, status: "draft" },
+        { id: "release", kind: "release", title: "Release", path: `${docsRoot}/releases/changelog.md`, status: "draft" },
+        ...(feature
+            ? [{ id: feature, kind: "feature", title: titleFromSlug(feature), path: `${docsRoot}/features/${feature}`, status: "draft" }]
+            : []),
+    ];
+}
+function writeJsonIfMissing(root, parts, value, written) {
+    const path = parts.join("/");
+    if (writeGeneratedJsonIfMissing(root, path, value, METADATA_LABEL)) {
+        written.push(path);
+    }
+}
+function updateManifest(root, docsRoot) {
+    const manifest = readGeneratedJson(root, `${CONFIG_DIR}/${MANIFEST_FILE}`, METADATA_LABEL);
+    for (const codebaseDoc of codebaseDocs(docsRoot)) {
+        if (!manifest.docs.includes(codebaseDoc.path))
+            manifest.docs.push(codebaseDoc.path);
+    }
+    writeGeneratedJson(root, `${CONFIG_DIR}/${MANIFEST_FILE}`, manifest, METADATA_LABEL);
+}
+function updateScopes(root, docsRoot) {
+    const scopes = readGeneratedJson(root, `${CONFIG_DIR}/${SCOPES_FILE}`, METADATA_LABEL);
+    if (scopes.scopes.some((scope) => scope.id === "release")) {
+        return;
+    }
+    const releaseScope = {
+        id: "release",
+        kind: "release",
+        title: "Release",
+        path: `${docsRoot}/releases/changelog.md`,
+        status: "draft",
+    };
+    scopes.scopes.push(releaseScope);
+    writeGeneratedJson(root, `${CONFIG_DIR}/${SCOPES_FILE}`, scopes, METADATA_LABEL);
+}
+function looksLikeCodebase(root) {
+    return ["package.json", "src", "app", "pages", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml"].some((path) => existsSync(`${root}/${path}`));
+}
+function titleFromSlug(slug) {
+    return slug
+        .split("-")
+        .filter(Boolean)
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join(" ");
+}
+//# sourceMappingURL=init.js.map