outcrop 0.1.0

package/docs/AGENTS.md

@@ -0,0 +1,39 @@
+# Agent instructions for outcrop workspaces
+
+[README](../README.md) · [SPEC](SPEC.md) · [API](API.md) · **AGENTS**
+
+You are working in (or against) an outcrop workspace: a directory of plain markdown files that doubles as a task tracker and a docs site. The files are the source of truth. This page tells you how to work in one safely.
+
+## Two ways to work
+
+1. **HTTP API** (preferred when the board is running): read JSON, mutate with revision checks. See [API.md](API.md).
+2. **Direct file edits**: read and write the markdown files yourself. Follow the format rules below exactly; the running board live-reloads on every change, and humans see your edits instantly.
+
+## File format rules (non-negotiable)
+
+- Frontmatter is flat `key: value` only: no nesting, no multiline values. Lists are inline (`depends_on: [ST-001, ST-002]`). Dates are `YYYY-MM-DD`.
+- Valid `status`: `backlog | ready | in-progress | in-review | done | blocked`. Valid `priority`: `P1 | P2 | P3`.
+- Task body sections in fixed order: `## Description`, `## Subtasks`, `## Acceptance criteria`, `## Test steps`, `## Notes`.
+- Subtasks are `- [ ]` / `- [x]` checkboxes under `## Subtasks`. Do not reorder them: the API addresses checkboxes by index.
+- IDs: tasks `ST-###`, epics `E##`. Filenames: `ST-###-slug.md`, `E##-slug.md`. Bare ID mentions anywhere in the workspace auto-link; `depends_on` and `epic` create graph edges.
+- Cross-doc references are real relative markdown links (`[PRD](PRD.md)`), not code spans: links drive navigation and backlinks.
+
+Full normative format: [SPEC.md](SPEC.md).
+
+## Lifecycle gate
+
+Implement and self-verify up to `in-review`. **Only a human moves a task to `done`**, after running its test steps. Never set `done` yourself unless the workspace's own docs explicitly say otherwise.
+
+## Working with other agents (and humans)
+
+- Every item carries a `rev` (file mtime at read). PATCH with the rev you read; a 409 means someone changed the file first: re-read, reconcile, retry or move on.
+- To claim a task, set `status: in-progress` in one rev-checked PATCH. If you get 409, the task may already be claimed: pick another.
+- Subscribe to `GET /sse` to hear about workspace changes instead of polling.
+- If `BOARD_GIT_COMMIT=1` is set (or `gitCommit: true` in `.outcrop.json`), every board mutation becomes a git commit: keep your own direct-edit commits small and scoped so the history stays readable.
+- The workspace may define its own columns: `GET /api/settings` for the valid `status` values before you invent one.
+
+## Don'ts
+
+- Don't rewrite frontmatter formatting you don't need to touch (keep diffs minimal; mutations are format-preserving).
+- Don't invent new statuses, priorities, or frontmatter keys.
+- Don't edit files under `board/`, `.git/`, or `node_modules/`.

package/docs/API.md

@@ -0,0 +1,176 @@
+# outcrop HTTP API
+
+[README](../README.md) · [SPEC](SPEC.md) · **API** · [AGENTS](AGENTS.md)
+
+Local server, default `http://localhost:4311`. No auth: it binds for local use. All JSON.
+
+**Endpoints at a glance**
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/tasks` | All tasks |
+| `POST` | `/api/tasks` | Create a task |
+| `POST` | `/api/epics` | Create an epic |
+| `POST` | `/api/docs` | Create a document |
+| `GET` | `/api/epics` | All epics |
+| `GET` | `/api/tasks/:id` | One item (task or epic) |
+| `GET` | `/api/docs-search?q=` | Full-text doc search |
+| `GET` | `/api/graph` | Document link graph |
+| `GET` | `/api/items/:id/pane` | Rendered detail pane (HTML fragment) |
+| `PATCH` | `/api/items/:id` | Mutate status, priority, or a checkbox |
+| `PATCH` | `/api/docs?file=` | Toggle a checkbox in a document |
+| `GET` | `/api/settings` | Workspace settings |
+| `PUT` | `/api/settings` | Replace workspace settings |
+| `GET` | `/sse` | Change stream |
+
+## Read
+
+### `GET /api/tasks`
+
+All tasks. Each:
+
+```json
+{
+  "id": "ST-001",
+  "title": "Engine crate and index",
+  "epic": "E01",
+  "status": "in-progress",
+  "priority": "P1",
+  "depends_on": ["ST-000"],
+  "created": "2026-07-07",
+  "body": "## Description\n...",
+  "file": "ST-001-engine-crate-and-index.md",
+  "rev": "1784910833019.7715",
+  "subtasksDone": 2,
+  "subtasksTotal": 5
+}
+```
+
+### `GET /api/epics`
+
+All epics: `id`, `title`, `milestone`, `status`, `created`, `body`, `file`, `rev`.
+
+### `GET /api/tasks/:id`
+
+One item by id (task or epic). 404 if unknown.
+
+### `GET /api/docs-search?q=term`
+
+Full-text search over all docs: `[{ "file": "PRD.md", "count": 16, "snippets": ["..."] }]`, sorted by count.
+
+## Write
+
+### `PATCH /api/items/:id`
+
+Body: any of
+
+```json
+{
+  "status": "in-review",
+  "priority": "P2",
+  "checkbox": { "index": 0, "checked": true },
+  "rev": "1784910833019.7715"
+}
+```
+
+- `rev` (recommended, from a prior GET): request is rejected if the file changed since. Omitting `rev` skips the check: last write wins. Multi-agent setups must send it.
+- Mutations are format-preserving: only the targeted frontmatter line or checkbox is rewritten.
+- With `BOARD_GIT_COMMIT=1`, each successful PATCH becomes a git commit (`ST-001: ready -> in-progress via board`).
+
+Responses:
+
+| Status | Meaning | Body |
+|---|---|---|
+| 200 | applied | `{ "ok": true, "rev": "<new rev>" }` |
+| 200 (no-op) | nothing changed | `{ "ok": true, "rev": "...", "unchanged": true }` |
+| 400 | invalid status/priority/checkbox/JSON | `{ "error": "..." }` |
+| 404 | unknown id | `{ "error": "..." }` |
+| 409 | stale rev: file changed since read | `{ "error": "stale: ..." }` |
+
+On 409: re-GET the item, reconcile, retry with the new rev.
+
+### `PATCH /api/docs?file=REL.md`
+
+Toggle a checkbox in a plain document, which has no id to address it by:
+
+```bash
+curl -X PATCH 'localhost:4311/api/docs?file=NOTES.md' -H 'content-type: application/json' \
+  -d '{"checkbox":{"index":2,"checked":true},"rev":"<rev>"}'
+```
+
+Checkboxes only — a document is not a task, so there is no status or priority to set. `index` counts `- [ ]` / `- [x]` lines from the top of the file, skipping fenced code blocks, exactly as it does for a task. `rev` is optional and behaves as it does elsewhere: supply it and a concurrent change is a `409`. `404` for an unknown or out-of-workspace file, `400` for an index that does not exist.
+
+### `POST /api/tasks`, `POST /api/epics`, `POST /api/docs`
+
+Create a file. The server assigns the id and the filename, so a create cannot collide with what is already on disk:
+
+```bash
+curl -X POST localhost:4311/api/tasks -H 'content-type: application/json' \
+  -d '{"title":"Wire up password reset","epic":"E01","status":"ready","priority":"P1",
+       "body":"Reset by email.","subtasks":"send the mail\nverify the token"}'
+# -> 201 {"ok":true,"id":"ST-004","file":"tasks/ST-004-wire-up-password-reset.md"}
+```
+
+- `title` (required): folded to a single line, 200 characters max. The filename slug is derived from it.
+- `body`: markdown for the `## Description` section.
+- Tasks also take `epic` (must exist), `status` (must be a current column), `priority` (`P1` to `P3`), and `subtasks` (one per line; `-` and `- [ ]` prefixes are tolerated and normalized).
+- Docs take `path` instead of getting a generated name: workspace-relative, `.md`, at most four segments, each a plain name. Missing folders are created.
+
+`400` for a bad title, status, priority, epic, or path. `409` if the target file already exists. A create never overwrites, and the write uses `wx` so a file appearing mid-request is a conflict rather than a clobber. Ids come from the highest existing number plus one, per series (`ST-###`, `E##`).
+
+Paths are refused rather than sanitized: `..`, absolute paths, dotfiles, anything outside the workspace, and the excluded directories (`.git`, `.claude`, `board`, `node_modules`) are all `400`.
+
+### `GET /api/settings`, `PUT /api/settings`
+
+Workspace settings, persisted as `.outcrop.json` at the workspace root. `PUT` replaces the whole object (no merge) and returns the normalized result:
+
+```json
+{ "title": "Payments rewrite", "views": ["board", "docs", "graph"], "columns": ["backlog", "ready", "done"], "gitCommit": false }
+```
+
+Fields are optional and normalized rather than rejected: `columns` entries are lowercased and slugged, non-slug and duplicate entries are dropped, and an empty list falls back to the default six. `views` is filtered to `board`/`docs`/`graph` and returned in that order; an omitted or all-unrecognized list falls back to all three. A blank `title` falls back to the workspace directory name. `gitCommit` must be boolean `true` to enable; `BOARD_GIT_COMMIT=1` forces it on regardless. A successful `PUT` fires an SSE `change`.
+
+The one rejection: a `views` list that is present but names no known view is a `400`, not a silent reset. Serving nothing is never what the caller meant, and quietly turning everything back on would hide the mistake.
+
+Disabling a view takes effect immediately: its route `302`s to the first view still enabled (`views` order is `board`, `docs`, `graph`). The API and `/sse` are unaffected either way.
+
+No `rev` check here: settings are a small last-write-wins file, not a task.
+
+## Events
+
+### `GET /sse`
+
+`text/event-stream`. One message type: `data: change`, debounced 120ms, fired on any markdown change in the workspace (from the board, an agent, or an editor). Re-fetch what you care about on receipt. Keep-alive comment pings every 25s.
+
+Open one per tab and keep it. Browsers cap concurrent connections per origin (six on HTTP/1.1) and are slow to release a closed page's socket, so a client that reconnects on every navigation can starve itself of connections. The docs viewer navigates in place for exactly this reason. The server also caps the client set and drops the oldest connection past the limit; a dropped EventSource reconnects on its own.
+
+## HTML
+
+`GET /` board, `GET /docs?file=REL.md` docs viewer, `GET /graph` link graph. Same data, human-shaped. Any of them `302`s to the first enabled view when disabled in `views`.
+
+Both carry an `ETag` over their own rendered output and honour `If-None-Match` with a `304`. The board's live-reload uses this: a write anywhere in the workspace broadcasts a `change`, but most writes leave a given page byte-identical, so the client revalidates and does no work. Send the header yourself (with `cache: "no-store"` from `fetch`) if you want to see the `304` rather than have the browser replay it as a `200`.
+
+`GET /styles.css` is the precompiled stylesheet, served `immutable` when requested with the `?v=` hash the pages link. HTML, CSS, and JSON responses are gzipped when the request allows it; `/sse` never is.
+
+### `GET /api/graph`
+
+The document link graph, one node per markdown file in the workspace:
+
+```json
+{
+  "nodes": [{ "id": "docs/SPEC.md", "label": "Workspace format", "group": "docs", "deg": 7 }],
+  "links": [{ "source": "README.md", "target": "docs/SPEC.md" }]
+}
+```
+
+- `id`: workspace-relative path, the same value `/docs?file=` takes.
+- `label`: frontmatter `title` if there is one, otherwise the filename without `.md`.
+- `group`: the folder it came from (`planner` for workspace-root files).
+- `deg`: how many edges touch it, counting both directions.
+- `links`: deduplicated and directed source to target. An edge is any markdown link to another `.md`, a bare `ST-###` / `E##` mention, an `epic:` and a `depends_on:` entry, which are the same relations the backlink index is built from. Self-links are dropped, and every endpoint is guaranteed to be a node in `nodes`.
+
+Cached until the workspace changes. This is what the `/graph` view fetches; the layout is computed in the browser, so nothing about node positions is server state.
+
+### `GET /api/items/:id/pane`
+
+The task or epic detail pane as an HTML fragment, the same markup the board's slide-over shows. Panes are not inlined in the board page (with a few hundred tasks they were ~80% of it), so the UI fetches this on click. `404` for an unknown id. No `ETag`: it's small and the client caches it until the next workspace change.

package/docs/SPEC.md

@@ -0,0 +1,101 @@
+# outcrop workspace format (v0)
+
+[README](../README.md) · **SPEC** · [API](API.md) · [AGENTS](AGENTS.md)
+
+Normative spec for the on-disk format outcrop reads and writes. Any tool or agent that follows this spec interoperates with outcrop without going through it.
+
+> Read this if you're writing files directly (an agent, a script, a generator). If you only want to run the board, [README.md](../README.md) is enough.
+
+## Workspace layout
+
+A workspace is a directory containing:
+
+| Path | Required | Contents |
+|---|---|---|
+| `tasks/` | no | One markdown file per task: `ST-###-slug.md`. Without it the board is simply empty; set `views` to `["docs"]` in `.outcrop.json` to hide it |
+| `epics/` | no | One markdown file per epic: `E##-slug.md` |
+| `*.md` (root) | no | Docs (README, PRD, architecture, ...), shown in the docs viewer under the `planner` folder. Raw HTML is rendered for an allowlisted subset of tags and attributes; anything else is escaped and displayed as text |
+| any other dir of `.md` | no | Doc groups (e.g. `decisions/`), each a foldable folder in the docs viewer |
+| `.outcrop.json` | no | Workspace settings: `title`, `views`, `columns`, `gitCommit`. Absent = defaults. See [API](API.md#get-apisettings-put-apisettings) |
+
+Excluded from doc indexing: `.git/`, `.claude/`, `board/`, `node_modules/`, dot-directories.
+
+## Frontmatter
+
+YAML-ish, deliberately restricted so any language can parse it with a few lines:
+
+- Delimited by `---` lines at the top of the file.
+- Flat `key: value` pairs only. No nesting, no multiline values, no quoting semantics: the value is the raw string after the first `:`.
+- Lists are inline: `depends_on: [ST-001, ST-002]` (comma-separated, brackets).
+- Dates are `YYYY-MM-DD`.
+
+### Task keys
+
+```yaml
+id: ST-001           # required, unique, grammar: ST-\d{3}
+title: Short imperative title
+epic: E01            # owning epic id
+status: ready        # default set: backlog | ready | in-progress | in-review | done | blocked
+                     # a workspace can redefine this set via "columns" in .outcrop.json
+priority: P1         # P1 | P2 | P3
+depends_on: []       # list of task ids
+created: 2026-07-07
+```
+
+Missing keys default to: `status: backlog`, `priority: P3`, empty strings/lists.
+
+### Epic keys
+
+```yaml
+id: E01              # required, unique, grammar: E\d{2}
+title: Epic title
+milestone: M0
+status: active       # free-form for epics
+created: 2026-07-07
+```
+
+## Task body
+
+Sections in fixed order, all optional but ordered:
+
+```markdown
+## Description
+## Subtasks
+## Acceptance criteria
+## Test steps
+## Notes
+```
+
+Subtasks are checkbox list items under `## Subtasks`:
+
+```markdown
+- [ ] not done
+- [x] done
+```
+
+Checkbox index (0-based, top to bottom, skipping fenced code blocks) is the address used by the mutation API. Reordering checkboxes changes addresses: avoid it.
+
+## References and links
+
+- Bare `ST-###` or `E##` anywhere in a body is an auto-linked mention.
+- `depends_on` and `epic` frontmatter create typed graph edges.
+- Relative markdown links between docs (`[PRD](PRD.md)`) drive docs navigation and backlinks. Code spans do not.
+- Backlinks are derived, never stored.
+
+## Timeline rendering
+
+A doc renders a Gantt-style timeline above its body when its frontmatter has `render: timeline`, or the file is named `TIMELINE.md`. The first markdown table with `start` and `end` columns (dates as `YYYY-MM-DD`) is used; optional columns: `id`/`milestone`, `title`, `status` (`done | active | pending`), `epic`.
+
+## Revisions and concurrency
+
+An item's `rev` is its file's mtime in milliseconds, as a string. Writers must:
+
+1. Read the file (capturing rev).
+2. Mutate format-preservingly (change only the line/value being changed).
+3. Reject their own write if the file's rev changed since read.
+
+outcrop's HTTP API enforces this with 409 responses. Direct-editing agents should follow the same read-check-write discipline when a board is live.
+
+## Lifecycle
+
+`backlog -> ready -> in-progress -> in-review -> done`, plus `blocked` from anywhere. Convention: automated agents stop at `in-review`; a human moves items to `done` after running the task's test steps.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "outcrop",
+  "version": "0.1.0",
+  "description": "Serve a folder of markdown tasks and docs as a live kanban board, docs site, and agent API. AI-native, zero-config, files are the database.",
+  "type": "module",
+  "bin": {
+    "outcrop": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets/logo.svg",
+    "docs/API.md",
+    "docs/SPEC.md",
+    "docs/AGENTS.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build:css": "tailwindcss -c tailwind.config.js -i src/styles.css -o src/styles.gen.css --minify",
+    "build": "bun run build:css && bun run build:client && bun build src/cli.ts --target=node --outfile=dist/cli.js --banner='#!/usr/bin/env node'",
+    "lint": "oxlint --deny-warnings src/",
+    "lint:fix": "oxlint --fix --deny-warnings src/",
+    "fmt": "oxfmt src/",
+    "fmt:check": "oxfmt --check src/",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p src/client/tsconfig.json",
+    "test": "bun test",
+    "check": "bun run fmt:check && bun run lint && bun run typecheck && bun run test",
+    "prepare": "git config core.hooksPath .githooks || true",
+    "prepublishOnly": "bun run check && bun run build",
+    "build:client": "bun build src/client/head.ts src/client/board.ts src/client/docs.ts src/client/graph.ts --target=browser --format=iife --outdir=src/generated"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "kanban",
+    "markdown",
+    "tasks",
+    "local-first",
+    "board",
+    "planning",
+    "ai",
+    "agents",
+    "mcp",
+    "workspace"
+  ],
+  "license": "MIT",
+  "author": "amirulhakiim",
+  "homepage": "https://github.com/amirulhakiim/outcrop#readme",
+  "bugs": {
+    "url": "https://github.com/amirulhakiim/outcrop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amirulhakiim/outcrop.git"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.2",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.77.0",
+    "tailwindcss": "^3.4.19",
+    "typescript": "^7.0.2"
+  }
+}