@guiho/xdocs 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,347 @@
+# XDocs
+
+**Structured documentation system for codebases. Helps AI make sense of projects.**
+
+xdocs is a CLI and TypeScript library that places structured documentation files throughout your project so that AI agents (and humans) can navigate, understand, and work within a codebase without reading every file. Each xdocs file describes the directory it lives in -- its purpose, its files, and how it fits into the project hierarchy.
+
+```text
+codebase -> xdocs files -> AI understands the project
+```
+
+xdocs runs on **Bun** and **Node >= 20**. It ships as a compiled binary, a thin JS loader for `npx`/`bunx`, and a fully-typed TypeScript library.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -D @guiho/xdocs
+# or
+bun add -d @guiho/xdocs
+```
+
+### Initializing
+
+Set up xdocs in your project:
+
+```bash
+xdocs init
+```
+
+This creates:
+- `XDOCS.md` -- the root documentation file for the project
+- `xdocs.config.toml` -- configuration with sensible defaults
+- Updates `AGENTS.md` with instructions for AI agents
+- Installs agent skill files for your AI tool
+
+### Typical Workflow
+
+```bash
+# Scan the project for existing xdocs files
+xdocs scan
+
+# Generate documentation for a specific module
+xdocs generate ./src/auth
+
+# View the project hierarchy
+xdocs tree
+
+# Get a ready-made prompt for AI to write documentation
+xdocs prompt --name=write
+```
+
+---
+
+## Documentation
+
+### The Problem
+
+When AI works on a codebase, most of the structural knowledge lives in the head of the person who built it. The AI has no understanding of _why_ files exist, _what purpose_ a directory serves, or _how_ modules relate to each other. To figure this out, it must read every file and piece things together -- slow, expensive, and error-prone.
+
+### The Solution
+
+xdocs solves this by placing documentation files throughout the project. Each xdocs file describes the directory it lives in, acting as a self-contained map of that module. Instead of opening every file to understand a directory, the AI reads its xdocs file.
+
+### File Format
+
+xdocs files are Markdown with YAML frontmatter. A file is recognized as an xdocs file if it ends with one of the configured extensions (default: `.docs.md`, `.xdocs.md`).
+
+```markdown
+---
+subject: authentication
+description: Handles user login, registration, password reset, and session management.
+parent: domain-core
+children:
+  - login
+  - registration
+  - password-reset
+files:
+  authenticate.ts: Validates credentials and returns a session token.
+  register.ts: Creates a new user account with email verification.
+  session.ts: Manages session creation, validation, and expiration.
+tags: []
+flags: []
+---
+
+## Overview
+
+The authentication module handles all identity verification flows...
+```
+
+#### Metadata Fields
+
+| Field         | Type                  | Required | Description                                                   |
+| ------------- | --------------------- | -------- | ------------------------------------------------------------- |
+| `subject`     | `string`              | Yes      | The name of this module/subject.                              |
+| `description` | `string`              | Yes      | A short description the AI reads first to understand the module. |
+| `parent`      | `string \| null`      | Yes      | The parent subject in the hierarchy. `null` for the root.     |
+| `children`    | `string[]`            | Yes      | Child subjects (submodules) contained within this module.     |
+| `files`       | `map<string, string>` | Yes      | Files in this directory. Key = filename, value = description. |
+| `tags`        | `string[]`            | Yes      | Tags for categorization and search.                           |
+| `flags`       | `string[]`            | Yes      | Flags for marking attributes or states.                       |
+| `status`      | `string`              | No       | Module status (e.g., `active`, `deprecated`, `experimental`). |
+
+### The Tree
+
+xdocs files form a hierarchy through their `subject`, `parent`, and `children` fields. The tree represents containment -- not dependencies -- and is computed by scanning all xdocs files.
+
+```
+project (root)
+  domain-core
+    authentication
+      login
+      registration
+      password-reset
+    user
+      profile
+      preferences
+  domain-supply
+    supply
+    product
+      catalog
+      inventory
+```
+
+The CLI validates tree integrity: no orphan subjects, no missing parents, no cycles.
+
+### CLI Commands
+
+#### `xdocs init`
+
+Initializes xdocs in a project. Creates the root `XDOCS.md`, the `xdocs.config.toml` configuration, updates `AGENTS.md`, and installs agent skills.
+
+#### `xdocs scan`
+
+Scans the project for xdocs files. Reports which directories have coverage and which are missing documentation.
+
+```bash
+xdocs scan
+xdocs scan --format json
+```
+
+#### `xdocs generate [path]`
+
+Generates documentation for a directory or the entire project.
+
+```bash
+# Generate docs for a specific module
+xdocs generate ./src/auth
+
+# Generate docs for the entire project
+xdocs generate
+```
+
+#### `xdocs prompt --name=<name>`
+
+Outputs a ready-made prompt for AI agents. Each prompt is a self-contained instruction for a specific xdocs task. Prompts are selected by the `--name` flag, not by subcommand.
+
+```bash
+xdocs prompt --name=write      # How to write xdocs documentation
+xdocs prompt --name=update     # How to update existing xdocs files
+xdocs prompt --name=agents     # How to update AGENTS.md
+xdocs prompt --name=generate   # How to generate comprehensive docs
+```
+
+#### `xdocs merge [path]`
+
+Merges xdocs files from a directory into a single consolidated document.
+
+```bash
+xdocs merge ./src/domain
+```
+
+#### `xdocs tree`
+
+Displays the project hierarchy tree assembled from xdocs metadata.
+
+```bash
+xdocs tree
+xdocs tree --format markdown --output tree.md
+```
+
+#### `xdocs list [path]`
+
+Lists files in a scope with descriptions pulled from xdocs metadata.
+
+```bash
+xdocs list ./src/auth
+```
+
+#### Global Flags
+
+All commands accept:
+
+| Flag              | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `-h`, `--help`    | Show help for a command                      |
+| `-v`, `--version` | Show the xdocs version                       |
+| `--cwd <path>`    | Run as if started in the given directory      |
+| `--config <path>` | Path to `xdocs.config.toml`                  |
+| `--format <fmt>`  | Output format: `text`, `json`, or `markdown` |
+| `--verbose`       | Show detailed output                         |
+
+### Configuration (`xdocs.config.toml`)
+
+xdocs looks for configuration at `./xdocs.config.toml`, `./config/xdocs.config.toml`, or the path given by `--config`.
+
+```toml
+schema = 1
+
+[extensions]
+# File extensions recognized as xdocs files.
+# Default: [".docs.md", ".xdocs.md"]
+supported = [".docs.md", ".xdocs.md"]
+
+[ai]
+# How the AI handles documentation updates.
+# "prompt" = AI announces updates needed, waits for user to confirm.
+# "auto"   = AI updates documentation automatically on any change.
+# Default: "prompt"
+mode = "prompt"
+
+[scan]
+# Directories to exclude from scanning.
+# Default: ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
+exclude = ["node_modules", ".git", "dist", "build", "library", "bin", "bundle"]
+
+[project]
+# Project name. Used in the root XDOCS.md and tree output.
+name = "my-project"
+```
+
+### Agent Skills and Plugins
+
+xdocs ships agent skill files that teach AI tools how to work with xdocs -- when to create, update, or regenerate documentation, how to use the CLI, and how to respect the configured AI behavior mode.
+
+Supported tools:
+
+| Tool             | Plugin Format                                     |
+| ---------------- | ------------------------------------------------- |
+| **OpenCode**     | `SKILL.md` in the skills directory                |
+| **Claude Code**  | `CLAUDE.md` in the project root or `.claude/`     |
+| **OpenAI Codex** | Instructions file in the tool's expected location |
+| **Google Jules** | Instructions file in the tool's expected location |
+
+`xdocs init` generates the correct file for your chosen tool. Multiple tools can be supported simultaneously.
+
+---
+
+## API Reference
+
+xdocs exposes a fully-typed TypeScript API for programmatic use.
+
+### Configuration
+
+```ts
+import { loadConfig, loadConfigOrDefaults, defaultConfig } from '@guiho/xdocs'
+
+// Load config from xdocs.config.toml (throws if not found)
+const config = await loadConfig({ cwd: process.cwd(), format: 'text', verbose: false })
+
+// Load config or fall back to defaults
+const configOrDefaults = await loadConfigOrDefaults({ cwd: process.cwd(), format: 'text', verbose: false })
+```
+
+### Discovery and Scanning
+
+```ts
+import { scanProject, scanDirectory, isXDocsFile } from '@guiho/xdocs'
+
+// Scan the entire project
+const result = await scanProject(config)
+console.log(result.totalFiles)           // Total files found
+console.log(result.xdocsFiles)           // Array of XDocsFile objects
+console.log(result.uncoveredPaths)       // Directories without xdocs coverage
+
+// Check if a file is an xdocs file
+isXDocsFile('auth.xdocs.md', ['.docs.md', '.xdocs.md'])  // true
+```
+
+### Metadata Parsing
+
+```ts
+import { parseXDocsFile, extractFrontmatter, validateMetadata } from '@guiho/xdocs'
+
+// Parse an xdocs file from disk
+const file = await parseXDocsFile('/path/to/auth.xdocs.md', process.cwd())
+console.log(file.metadata?.subject)       // "authentication"
+console.log(file.metadata?.description)   // "Handles user login..."
+console.log(file.valid)                   // true if metadata is complete
+```
+
+### Tree Operations
+
+```ts
+import { buildTree, renderTree, renderTreeMarkdown, validateTree } from '@guiho/xdocs'
+
+// Build the hierarchy tree from scanned files
+const tree = buildTree(result.xdocsFiles)
+
+// Render as indented text
+console.log(renderTree(tree))
+
+// Render as Markdown
+console.log(renderTreeMarkdown(tree))
+
+// Validate tree integrity
+const validation = validateTree(result.xdocsFiles)
+console.log(validation.valid)    // true if no orphans or cycles
+console.log(validation.errors)   // Array of error messages
+```
+
+### Prompts
+
+```ts
+import { getPrompt, getPromptNames } from '@guiho/xdocs'
+
+// List all available prompt names
+console.log(getPromptNames())  // ["write", "update", "agents", "generate"]
+
+// Get a specific prompt
+const prompt = getPrompt('write')
+console.log(prompt?.description)
+console.log(prompt?.body)
+```
+
+---
+
+## Development
+
+Development requires Bun. Run from the `xdocs/` directory:
+
+```bash
+cd xdocs
+bun install
+bun run typecheck
+bun test
+bun run build
+bun run binary
+```
+
+---
+
+## License
+
+MIT -- see [LICENSE.md](xdocs/LICENSE.md).

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/xdocs",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "exports": "./source/guiho-xdocs.ts",
   "publish": {
     "include": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/xdocs",
   "description": "Structured documentation system for codebases. Helps AI make sense of projects.",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "module",
   "main": "./library/guiho-xdocs.js",
   "types": "./library/guiho-xdocs.d.ts",
@@ -17,6 +17,7 @@
   "files": [
     "README.md",
     "library/",
+    "prompts/",
     "docs/",
     "jsr.json",
     "CHANGELOG.md",

package/prompts/agents.md

@@ -0,0 +1,21 @@
+---
+name: agents
+description: Update AGENTS.md with xdocs instructions for AI agents.
+---
+
+# xdocs: Update AGENTS.md
+
+You are an AI assistant tasked with updating the AGENTS.md file to include xdocs instructions.
+
+## Instructions
+
+1. Read the existing AGENTS.md file.
+2. Check if there is already an xdocs section (between `<!-- BEGIN XDOCS -->` and `<!-- END XDOCS -->` markers).
+3. If the section exists, update it with the current xdocs configuration.
+4. If the section does not exist, add it at the end of the file.
+5. The xdocs section should instruct AI agents to:
+   - Read XDOCS.md and xdocs files when entering the project
+   - Respect the configured AI behavior mode (prompt or auto)
+   - Use the xdocs CLI for documentation operations
+   - Maintain xdocs files when modifying code
+   - Follow the metadata schema for frontmatter

package/prompts/generate.md

@@ -0,0 +1,26 @@
+---
+name: generate
+description: Generate comprehensive documentation for a domain or entire project.
+---
+
+# xdocs: Generate Comprehensive Documentation
+
+You are an AI assistant tasked with generating comprehensive documentation for a domain or the entire project.
+
+## Instructions
+
+1. Scan all xdocs files in the target scope (directory or project).
+2. Read every source file in the scope.
+3. Build a complete understanding of:
+   - The module hierarchy
+   - The purpose of each module
+   - How modules relate to each other
+   - What each file does
+4. Generate a single comprehensive Markdown document that includes:
+   - Project or domain overview
+   - Complete hierarchy tree
+   - Detailed description of each module
+   - File listings with descriptions
+   - Cross-references between related modules
+5. The output should be a self-contained document that fully describes the scope.
+6. Use clear headings, consistent formatting, and concise language.

package/prompts/update.md

@@ -0,0 +1,31 @@
+---
+name: update
+description: Update existing xdocs files after code changes.
+---
+
+# xdocs: Update Documentation
+
+You are an AI assistant tasked with updating existing xdocs documentation after code changes.
+
+## Instructions
+
+1. Identify which files have changed in the recent modifications.
+2. Find the xdocs files that document the directories containing those changes.
+3. For each affected xdocs file:
+   a. Re-read the files listed in the metadata to check if descriptions are still accurate.
+   b. Check if new files were added that need to be listed.
+   c. Check if files were removed that should be unlisted.
+   d. Update the description if the module's purpose has changed.
+   e. Update children if subdirectories were added or removed.
+   f. Update the body content if significant changes occurred.
+4. Preserve the existing structure and style of the xdocs file.
+5. Do not remove information that is still accurate.
+
+## Checklist
+
+- [ ] All new files are listed in the files metadata
+- [ ] Removed files are no longer listed
+- [ ] File descriptions are accurate
+- [ ] Module description reflects current state
+- [ ] Children list matches actual subdirectories
+- [ ] Parent reference is still correct

package/prompts/write.md

@@ -0,0 +1,45 @@
+---
+name: write
+description: Scan a directory and write a new xdocs documentation file for it.
+---
+
+# xdocs: Write Documentation
+
+You are an AI assistant tasked with writing xdocs documentation for a directory/module.
+
+## Instructions
+
+1. Scan the target directory and all its subdirectories.
+2. Read every source file to understand what it does.
+3. Identify the purpose of this module/directory.
+4. Create an xdocs file with YAML frontmatter containing:
+   - subject: A short identifier for this module
+   - description: A concise description of what this module does
+   - parent: The parent module's subject (or null if this is a root module)
+   - children: List of child module subjects
+   - files: Map of filename to short description for each file
+   - tags: Relevant tags (empty array if none)
+   - flags: Relevant flags (empty array if none)
+5. Write a Markdown body below the frontmatter with:
+   - An overview section explaining the module in more detail
+   - Usage examples if relevant
+   - Any important notes or caveats
+6. Name the file as `<module-name>.xdocs.md` in the target directory.
+
+## Frontmatter Template
+
+```yaml
+---
+subject: module-name
+description: What this module does in one sentence.
+parent: parent-module
+children:
+  - child-a
+  - child-b
+files:
+  - file-a.ts: What file-a does.
+  - file-b.ts: What file-b does.
+tags: []
+flags: []
+---
+```