benjamin-docs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,352 @@
+# benjamin-docs
+
+Repo-local project memory for humans and AI agents.
+
+`benjamin-docs` turns planning and build conversations into structured Markdown docs that live inside your project. It works before code exists, inside existing codebases, and for individual feature scopes.
+
+## Status
+
+Early MVP. The CLI is prepared for its first public `0.1.0` package release as `benjamin-docs`.
+
+The current goal is to make the open-source repo useful, understandable, and safe to try before adding hosted publishing or SaaS features.
+
+## Why It Exists
+
+Long agent sessions create valuable project context: product decisions, rejected options, feature plans, user-facing notes, handoff context, and code references. That context is easy to lose.
+
+`benjamin-docs` keeps that memory close to the work:
+
+- human-readable Markdown in `benjamin-docs/`
+- machine-readable metadata in `.benjamin-docs/`
+- local validation before docs are shared or exported
+- agent skill guidance so future sessions can update docs without drifting
+
+## Try It From Any Chat
+
+If a conversation already contains a useful project idea, ask your agent:
+
+```text
+Use benjamin-docs to create a project from this chat.
+```
+
+The agent should suggest a local folder like:
+
+```text
+~/Documents/Benjamin Docs/Atelier Edits
+```
+
+After you confirm, it creates:
+
+```text
+README.md
+benjamin-docs/
+.benjamin-docs/
+```
+
+The top-level `README.md` explains the project in plain language. The `benjamin-docs/` folder captures the project brief, roadmap, open questions, and handoff notes. Nothing is uploaded by the CLI.
+
+## For Non-Programmers
+
+You can use `benjamin-docs` even if you are planning an app, product, service, or creative project before any code exists.
+
+Think of it as a project notebook that your AI agent keeps inside your project folder. The agent does the writing; the CLI creates the folders, checks that the notes are valid, and gives the next prompt to use.
+
+You need:
+
+- a place on your computer where the agent can create a project folder, such as `~/Documents/Benjamin Docs/Project Name`
+- an AI coding agent that can run terminal commands and edit files
+- the `benjamin-docs` CLI installed with pnpm, or a local source checkout while developing
+
+If all you have is the current chat, start by asking your agent:
+
+```text
+Use benjamin-docs to create a project from this chat.
+Suggest ~/Documents/Benjamin Docs/<Project Name> as the folder,
+initialize it as a planning-only project, write a simple top-level README.md,
+then capture the current context in plain language.
+```
+
+After that, ask:
+
+```text
+Show me the benjamin-docs project brief, roadmap, open questions,
+and handoff. Explain what each file is for.
+```
+
+Nothing is uploaded or published by the CLI. The docs stay in your project folder unless you choose to share them.
+
+## Create A Project From A Chat
+
+This is the simplest first use case: you do not have a repo, codebase, or project folder yet. You only have a useful conversation.
+
+Ask your agent:
+
+```text
+Use benjamin-docs to create a project from this chat.
+Suggest ~/Documents/Benjamin Docs/<Project Name> unless I choose a different place.
+Create the folder, initialize benjamin-docs there, add a simple README.md,
+and turn this conversation into a project brief, roadmap, open questions,
+and handoff.
+```
+
+The agent should:
+
+- infer a human-readable project name when the chat makes one obvious
+- suggest `~/Documents/Benjamin Docs/<Project Name>` as the default location
+- ask for confirmation before creating files
+- summarize what it will capture in short bullets
+- create the project folder
+- run `benjamin-docs init --mode planning` inside that folder
+- write a top-level `README.md` that explains what the project is and where to start
+- update the Benjamin docs under `benjamin-docs/` from the chat context
+- run `benjamin-docs validate`
+- show you what was created and what is still uncertain
+
+The CLI creates and validates the docs workspace. The agent turns the chat into useful project memory.
+
+## Install The CLI
+
+Install globally with pnpm:
+
+```bash
+pnpm add -g benjamin-docs
+benjamin-docs introduce
+```
+
+Initialize docs in the current project folder:
+
+```bash
+benjamin-docs init
+benjamin-docs status
+benjamin-docs validate
+```
+
+`init` prints the recommended agent prompt. Run `next` later if you want to see that prompt again.
+
+```bash
+benjamin-docs next
+```
+
+In an interactive terminal, `init` asks what you are setting up. In scripts or agent workflows, pass a mode explicitly.
+
+For an existing codebase:
+
+```bash
+benjamin-docs init --mode codebase
+benjamin-docs validate
+```
+
+For a single feature:
+
+```bash
+benjamin-docs init --mode feature --feature billing-reminders
+benjamin-docs validate
+```
+
+If you prefer a project-local dev dependency:
+
+```bash
+cd /path/to/your-project
+pnpm add -D benjamin-docs
+pnpm exec benjamin-docs init
+pnpm exec benjamin-docs validate
+```
+
+## Install The Agent Skill Locally
+
+The skill teaches an agent how to capture planning/build conversations into the docs created by the CLI.
+
+For Codex local skills:
+
+```bash
+mkdir -p ~/.codex/skills/benjamin-docs
+cp skills/benjamin-docs/SKILL.md ~/.codex/skills/benjamin-docs/SKILL.md
+```
+
+Then ask your agent:
+
+```text
+Capture this conversation with benjamin-docs.
+```
+
+For a first planning session, a clearer prompt is:
+
+```text
+Use the benjamin-docs skill.
+If there is no project folder yet, ask me where to create one.
+Suggest ~/Documents/Benjamin Docs/<Project Name> by default.
+Initialize it as a planning-only project, add a simple README.md,
+and capture what we know, what we decided, what is still unclear,
+and what I should do next. Keep it understandable for a non-technical reader.
+```
+
+## Local Development
+
+```bash
+git clone https://github.com/msiksnis/benjamin-docs.git
+cd benjamin-docs
+pnpm install
+pnpm build
+node dist/src/cli.js introduce
+```
+
+To test the source CLI inside another local project without installing the package:
+
+```bash
+cd /path/to/your-project
+node /path/to/benjamin-docs/dist/src/cli.js init
+```
+
+## Checks
+
+```bash
+pnpm check
+node dist/src/cli.js validate
+npm pack --dry-run
+```
+
+Before publishing:
+
+```bash
+pnpm run release:check
+pnpm publish
+```
+
+## Common Commands
+
+```bash
+benjamin-docs introduce
+benjamin-docs help
+benjamin-docs --version
+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
+```
+
+In a source checkout, use `node dist/src/cli.js ...` after `pnpm build`.
+
+## What It Creates
+
+```text
+benjamin-docs/
+.benjamin-docs/
+```
+
+`benjamin-docs/` contains human-readable Markdown. `.benjamin-docs/` contains machine metadata for validation, exports, anchors, and future publishing.
+
+The default workspace is:
+
+```text
+benjamin-docs/
+  project/
+  handoff/
+  engineering/
+  features/
+  releases/
+```
+
+Existing project docs in `docs/` are left alone. They may be useful context, but they are not the Benjamin-managed workspace unless `.benjamin-docs/config.json` explicitly says so.
+
+## Agent Workflow
+
+The CLI owns structure and validation. Codex or Claude skills own synthesis from the current conversation.
+
+Ask your agent:
+
+```text
+Capture this conversation with benjamin-docs.
+```
+
+The agent should update the relevant docs, run validation, and report what changed.
+
+Good capture prompts:
+
+```text
+Use benjamin-docs to create a project from this chat.
+Suggest ~/Documents/Benjamin Docs/<Project Name>, then initialize it and capture the project.
+```
+
+```text
+Capture this planning conversation with benjamin-docs.
+```
+
+```text
+Capture the current project baseline with benjamin-docs.
+Read the existing docs and codebase, then update the Benjamin docs
+under benjamin-docs/. Mark uncertain items.
+```
+
+```text
+Create a benjamin-docs feature scope for billing-reminders
+and capture the plan, decisions, risks, and handoff.
+```
+
+## Capture A Baseline
+
+A baseline capture turns the current state of a project into durable docs. It is the first useful pass after `init`, and it should capture decisions, rejected options, risks, open questions, and next actions instead of saving a raw transcript.
+
+For a new idea or planning-only project:
+
+```bash
+benjamin-docs init --mode planning
+```
+
+```text
+Capture the baseline for this new idea with benjamin-docs.
+Update the project brief, roadmap, open questions, and handoff docs.
+Mark assumptions clearly and challenge any overbuilt V1 scope.
+```
+
+For an existing codebase:
+
+```bash
+benjamin-docs init --mode codebase
+```
+
+```text
+Capture the current codebase baseline with benjamin-docs.
+Read the README, package/config files, existing docs, and major source areas.
+Update the project, engineering, and handoff docs under benjamin-docs/.
+Include important code references, risks, and uncertain findings.
+```
+
+For one feature:
+
+```bash
+benjamin-docs init --mode feature --feature billing-reminders
+```
+
+```text
+Capture the billing-reminders feature with benjamin-docs.
+Update the feature brief, plan, decisions, and handoff.
+Include user goals, constraints, rejected options, test ideas, and next actions.
+```
+
+After any baseline capture:
+
+```bash
+benjamin-docs validate
+```
+
+## Design Boundaries
+
+- The repo-local docs are the source of truth.
+- The CLI should stay deterministic and dependency-light.
+- Ordinary local commands should not make network calls.
+- Existing docs in a repo should not be overwritten.
+- Hosted publishing, auth, comments, and web editing are future layers.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md).

package/dist/src/anchors.d.ts

@@ -0,0 +1 @@
+export declare function addAnchor(root: string, id: string, file: string, docs?: string[]): void;

package/dist/src/anchors.js

@@ -0,0 +1,50 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, sep, win32 } from "node:path";
+import { ANCHORS_FILE, CONFIG_DIR } from "./constants.js";
+import { pathExists, readGeneratedJson, rootPath, writeGeneratedJson } from "./fsx.js";
+const ANCHOR_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const METADATA_LABEL = "Metadata path";
+export function addAnchor(root, id, file, docs = []) {
+    if (!ANCHOR_ID_PATTERN.test(id)) {
+        throw new Error(`Invalid anchor id: ${id}`);
+    }
+    const filePath = validateRelativePath(root, file, "anchor file");
+    const safeDocs = docs.map((doc) => validateRelativePath(root, doc, "anchor docs path"));
+    if (!pathExists(filePath.full)) {
+        throw new Error(`Anchor file does not exist: ${file}`);
+    }
+    assertRegularFileInsideRoot(root, filePath.full, file);
+    const anchorsPath = `${CONFIG_DIR}/${ANCHORS_FILE}`;
+    const anchors = readGeneratedJson(root, anchorsPath, METADATA_LABEL);
+    anchors.anchors[id] = { file, docs: safeDocs.map((doc) => doc.relative) };
+    writeGeneratedJson(root, anchorsPath, anchors, METADATA_LABEL);
+}
+function validateRelativePath(root, path, label) {
+    if (!path || path.includes("\\") || win32.isAbsolute(path) || hasDotSegment(path)) {
+        throw new Error(`Invalid ${label}: ${path}`);
+    }
+    try {
+        return { full: rootPath(root, path), relative: path };
+    }
+    catch {
+        throw new Error(`Invalid ${label}: ${path}`);
+    }
+}
+function hasDotSegment(path) {
+    return path.split("/").some((part) => part === "." || part === ".." || part === "");
+}
+function assertRegularFileInsideRoot(root, fullPath, originalPath) {
+    if (!statSync(fullPath).isFile()) {
+        throw new Error(`Anchor target must be a regular file: ${originalPath}`);
+    }
+    const realRoot = realpathSync(root);
+    const realTarget = realpathSync(fullPath);
+    if (!isInsideRoot(realRoot, realTarget)) {
+        throw new Error(`Anchor target must remain inside project root: ${originalPath}`);
+    }
+}
+function isInsideRoot(root, target) {
+    const relativePath = relative(root, target);
+    return relativePath === "" || (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath));
+}
+//# sourceMappingURL=anchors.js.map

package/dist/src/anchors.js.map

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

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[], cwd?: string): Promise<number>;

package/dist/src/cli.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
+import { addAnchor } from "./anchors.js";
+import { exportAudience } from "./export.js";
+import { initProject, promoteToCodebase } from "./init.js";
+import { getHelpText, getIntroductionText, getPackageVersion } from "./info.js";
+import { formatNextMessage, getNextPrompt } from "./next.js";
+import { createScope } from "./scopes.js";
+import { getStatus } from "./status.js";
+import { validateProject } from "./validate.js";
+export async function main(argv = process.argv.slice(2), cwd = process.cwd()) {
+    const [command] = argv;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        console.log(getHelpText());
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(getPackageVersion());
+        return 0;
+    }
+    if (command === "introduce") {
+        console.log(getIntroductionText());
+        return 0;
+    }
+    if (command === "init") {
+        const options = await resolveInitOptions(argv.slice(1));
+        const result = initProject(cwd, options);
+        console.log(`Initialized benjamin-docs. ${result.written.length} files created.`);
+        console.log("");
+        console.log(formatNextMessage(getNextPrompt(cwd)));
+        return 0;
+    }
+    if (command === "next") {
+        console.log(formatNextMessage(getNextPrompt(cwd)));
+        return 0;
+    }
+    if (command === "status") {
+        console.log(getStatus(cwd));
+        return 0;
+    }
+    if (command === "scope") {
+        if (argv[1] !== "create") {
+            throw new Error("Usage: benjamin-docs scope create feature <slug>");
+        }
+        const kind = argv[2];
+        const id = argv[3];
+        if (!kind || !id) {
+            throw new Error("Usage: benjamin-docs scope create feature <slug>");
+        }
+        const written = createScope(cwd, kind, id);
+        console.log(`Created ${kind} scope ${id}. ${written.length} files created.`);
+        return 0;
+    }
+    if (command === "anchor") {
+        if (argv[1] !== "add") {
+            throw new Error("Usage: benjamin-docs anchor add <id> <file>");
+        }
+        const id = argv[2];
+        const file = argv[3];
+        if (!id || !file) {
+            throw new Error("Usage: benjamin-docs anchor add <id> <file>");
+        }
+        addAnchor(cwd, id, file);
+        console.log(`Added anchor ${id}.`);
+        return 0;
+    }
+    if (command === "validate") {
+        const result = validateProject(cwd);
+        for (const warning of result.warnings)
+            console.warn(`Warning: ${warning}`);
+        if (result.errors.length > 0) {
+            for (const error of result.errors)
+                console.error(`Error: ${error}`);
+            return 1;
+        }
+        console.log("Validation passed.");
+        return 0;
+    }
+    if (command === "export") {
+        const audienceIndex = argv.indexOf("--audience");
+        const audience = audienceIndex === -1 ? undefined : argv[audienceIndex + 1];
+        if (!audience) {
+            throw new Error("Usage: benjamin-docs export --audience <audience>");
+        }
+        const written = exportAudience(cwd, audience);
+        console.log(`Exported ${audience} bundle. ${written.length} files written.`);
+        return 0;
+    }
+    if (command === "promote") {
+        if (argv[1] !== "--to" || argv[2] !== "codebase") {
+            throw new Error("Usage: benjamin-docs promote --to codebase");
+        }
+        const written = promoteToCodebase(cwd);
+        console.log(`Promoted benjamin-docs to codebase mode. ${written.length} files created.`);
+        return 0;
+    }
+    console.error(`Unknown command: ${command}`);
+    console.error("");
+    console.error(getHelpText());
+    return 1;
+}
+async function resolveInitOptions(args) {
+    const parsed = parseInitArgs(args);
+    if (parsed.setup)
+        return parsed;
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+        return promptForInitOptions();
+    }
+    return { setup: "project" };
+}
+function parseInitArgs(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--mode" || arg === "--type" || arg === "--setup") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("Usage: benjamin-docs init --mode <planning|codebase|feature>");
+            options.setup = parseSetup(value);
+            index += 1;
+            continue;
+        }
+        if (arg === "--feature") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("Usage: benjamin-docs init --mode feature --feature <slug>");
+            options.feature = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--docs-root") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("Usage: benjamin-docs init --docs-root <path>");
+            options.docsRoot = value;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown init option: ${arg}`);
+    }
+    return options;
+}
+function parseSetup(value) {
+    if (value === "planning" || value === "project")
+        return "project";
+    if (value === "codebase")
+        return "codebase";
+    if (value === "feature")
+        return "feature";
+    throw new Error("Usage: benjamin-docs init --mode <planning|codebase|feature>");
+}
+async function promptForInitOptions() {
+    const choices = [
+        { label: "Planning a new project", setup: "project" },
+        { label: "Documenting an existing codebase", setup: "codebase" },
+        { label: "Planning/documenting one feature", setup: "feature" },
+    ];
+    const selected = await selectChoice("What are you setting up?", choices.map((choice) => choice.label));
+    const setup = choices[selected]?.setup ?? "project";
+    if (setup !== "feature")
+        return { setup };
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const feature = (await rl.question("Feature slug: ")).trim();
+        return { setup, feature };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function selectChoice(question, choices) {
+    let selected = 0;
+    const input = process.stdin;
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    const render = () => {
+        process.stdout.write("\x1Bc");
+        process.stdout.write(`${question}\n\n`);
+        choices.forEach((choice, index) => {
+            process.stdout.write(`${index === selected ? "> " : "  "}${choice}\n`);
+        });
+        process.stdout.write("\nNavigate to select. Press Enter to continue.\n");
+    };
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            input.setRawMode(false);
+            input.off("keypress", onKeypress);
+            process.stdout.write("\n");
+        };
+        const onKeypress = (str, key) => {
+            if (key.ctrl && key.name === "c") {
+                cleanup();
+                process.exit(130);
+            }
+            if (key.name === "up" || str === "k") {
+                selected = selected === 0 ? choices.length - 1 : selected - 1;
+                render();
+                return;
+            }
+            if (key.name === "down" || str === "j") {
+                selected = selected === choices.length - 1 ? 0 : selected + 1;
+                render();
+                return;
+            }
+            if (/^[1-9]$/.test(str)) {
+                const index = Number(str) - 1;
+                if (index >= 0 && index < choices.length) {
+                    selected = index;
+                    render();
+                }
+                return;
+            }
+            if (key.name === "return" || key.name === "enter") {
+                cleanup();
+                resolve(selected);
+            }
+        };
+        input.on("keypress", onKeypress);
+        render();
+    });
+}
+main()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

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