outcrop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amirul Hakim Azmi
+
+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,398 @@
+<p align="center"><img src="assets/logo.svg" alt="" width="96" height="96"></p>
+
+<h1 align="center">outcrop</h1>
+
+<p align="center">
+  Your markdown is the bedrock. <b>outcrop</b> exposes it: point it at a folder of markdown, get a live kanban board, a docs site, and a JSON API for AI agents.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/outcrop"><img alt="npm" src="https://img.shields.io/npm/v/outcrop.svg"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/outcrop.svg"></a>
+  <img alt="node" src="https://img.shields.io/node/v/outcrop.svg">
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen">
+</p>
+
+```bash
+npx outcrop
+```
+
+That's it. No install, no config file, no database, no account. Your markdown files *are* the database.
+
+---
+
+## Table of contents
+
+- [Why](#why)
+- [Quick start](#quick-start)
+- [Workspace format](#workspace-format)
+- [Features](#features)
+- [For AI agents](#for-ai-agents)
+- [CLI reference](#cli-reference)
+- [Documentation](#documentation)
+- [Tech stack](#tech-stack)
+- [Development](#development)
+- [FAQ](#faq)
+- [License](#license)
+
+## Why
+
+Task trackers put your work in someone else's database. Markdown files put it in your repo, but then you're reading a folder of `.md` files by hand: no board, no search, no way for an AI agent to safely pick up work.
+
+outcrop sits in the middle. One command turns a plain `tasks/` folder into:
+
+- a **kanban board** you can drag cards around in. Every drop writes back to the markdown
+- a **docs site** with a foldable file tree, a per-page outline, full-text search, mermaid diagrams, and timelines
+- a **graph view** of how every note links to every other, the way Obsidian draws one
+- a **JSON API** with optimistic concurrency, so multiple AI agents can work the same workspace without clobbering each other
+
+Humans and agents read and write the *same files*. Delete outcrop tomorrow and you still have your markdown, in git, exactly as it was.
+
+## Quick start
+
+Any directory is a workspace. A `tasks/` folder gets you a board; without one you get a docs site:
+
+```bash
+mkdir -p my-workspace/tasks
+cat > my-workspace/tasks/ST-001-first-task.md <<'EOF'
+---
+id: ST-001
+title: Ship the first thing
+epic: E01
+status: ready
+priority: P1
+depends_on: []
+created: 2026-08-02
+---
+
+## Description
+
+The first task in the workspace.
+
+## Subtasks
+
+- [ ] write it
+- [ ] test it
+EOF
+
+npx outcrop my-workspace
+```
+
+Open http://localhost:4311.
+
+| Route | What |
+|---|---|
+| `/` | Kanban board |
+| `/docs` | Docs viewer |
+| `/graph` | Link graph |
+| `/api` | JSON API |
+| `/sse` | Live change stream |
+
+## Workspace format
+
+A workspace is a directory. Nothing is generated, nothing is hidden.
+
+```
+my-workspace/
+├── tasks/                 # optional: one file per task (no tasks/ = docs-only site)
+│   ├── ST-001-slug.md
+│   └── ST-002-slug.md
+├── epics/                 # optional: one file per epic
+│   └── E01-slug.md
+├── decisions/             # optional: any folder of .md becomes a doc group
+│   └── ADR-001.md
+├── README.md              # optional: root docs show in the viewer
+└── TIMELINE.md            # optional: renders as a Gantt chart
+```
+
+Task frontmatter is flat `key: value`. No nesting, no quoting rules, parseable in ten lines of any language:
+
+```yaml
+---
+id: ST-001           # required, unique, ST-###
+title: Short imperative title
+epic: E01
+status: ready        # backlog | ready | in-progress | in-review | done | blocked
+priority: P1         # P1 | P2 | P3
+depends_on: []       # inline list: [ST-001, ST-002]
+created: 2026-08-02
+---
+```
+
+Body sections are optional and ordered: `## Description`, `## Subtasks`, `## Acceptance criteria`, `## Test steps`, `## Notes`. Checkboxes under `## Subtasks` become progress rings on the board.
+
+Full normative spec: **[SPEC.md](docs/SPEC.md)**.
+
+## Features
+
+- **Kanban board** grouped by `status`. Drag and drop rewrites one frontmatter line on disk. Nothing else in the file changes.
+- **Task detail sheet** with subtask checkboxes, dependency chips, and backlinks.
+- **Docs viewer** with a foldable file tree, full-text search, mermaid diagrams, and timeline rendering (`render: timeline` in frontmatter, or a file named `TIMELINE.md`).
+- **Outline pane** on the right of every document, built from its headings, with the current section highlighted as you scroll. Hidden when a document has nothing worth listing.
+- **Foldable folders.** Each folder in the file tree collapses on its own, and one button in the tree header collapses or expands the lot. Everything starts open, and what you fold is remembered per browser.
+- **Graph view**, a force-directed map of the workspace. Nodes are documents, edges are links (markdown links, bare `ST-001` mentions, `epic:` and `depends_on:`), and node size follows how well connected a note is. Scroll to zoom, drag to pan, drag a node to pull it around, click one to open it. Live like every other view.
+- **Globe mode**, on by default. The graph wrapped onto a sphere: links follow great circles across the surface, the far side dims, and it turns slowly until you take hold of it. Drag to spin. `Flat` unwraps it onto a plane, which is worth doing when you need to read the whole graph at once, since a globe hides half its nodes behind itself. Either choice is remembered per browser.
+- **Raw HTML, allowlisted.** The subset a README uses (centred headings, badge images, `<details>` blocks) renders as markup. Everything else stays escaped and shows as text. A workspace gets cloned and written into by agents, and the JSON API on this origin has no auth, so `<script>`, event handlers, `iframe`/`object`/`svg`, and the `class`/`id`/`style` attributes are all off the list. HTML inside a code span is left alone as the sample it is.
+- **Hand entry.** The `+` in the header opens a form for a new user story, epic, or document, on any page. The server assigns ids (`ST-004`, `E02`) and filenames, the epic/status/priority dropdowns are filled from the workspace as it stands, and the result is an ordinary markdown file you could have typed yourself.
+- **Clickable checklists**, in a task's subtasks and in any document. Ticking one rewrites that single `- [ ]` line on disk and nothing else. Checkboxes shown inside fenced code blocks are samples, so they are never counted or touched.
+- **Auto-linking.** A bare `ST-001` or `E01` anywhere in any file becomes a link. Backlinks are derived, never stored.
+- **Live reload** over SSE. Edit a file in your editor, the board updates. Agents can subscribe to the same stream instead of polling.
+- **Git audit trail.** Set `BOARD_GIT_COMMIT=1` and every board mutation becomes a commit (`ST-001: ready -> in-progress via board`).
+- **Keyboard shortcuts.** `⌘K` / `Ctrl+K` jumps to search from anywhere, including mid-typing in another field. `/` does the same when you're not in a text field, `Esc` clears and leaves it, and `Esc` also closes the detail pane.
+- **Settings** in the gear menu, on every page. Workspace settings (title, views, columns, git auto-commit) are saved to `.outcrop.json` and travel with the repo. Appearance (theme, accent colour, typeface, UI scale) is per-browser and stays out of the workspace.
+- **Docs-only workspaces.** No `tasks/` folder? Turn the board view off and it's a markdown site with search, backlinks, and diagrams.
+- **Zero runtime dependencies.** A single bundled file on top of the Node standard library. Nothing is fetched from a CDN at page load: the stylesheet is compiled at build time and inlined into the binary.
+- **Fast on big workspaces.** Parsed files, backlinks, and rendered pages are cached until something on disk changes. Detail panes load on click instead of shipping with the board. Responses are gzipped and revalidate with an `ETag`, so a live-reload for an unrelated file costs one `304` and no re-render.
+
+## For AI agents
+
+This is the part most task tools don't have. Agents are first-class users, not a scraping target.
+
+```bash
+# read
+curl localhost:4311/api/tasks              # all tasks, with id/status/rev/deps/subtask counts
+curl localhost:4311/api/tasks/ST-001       # one item
+curl 'localhost:4311/api/docs-search?q=auth'
+
+# write
+curl -X PATCH localhost:4311/api/items/ST-001 \
+  -H 'content-type: application/json' \
+  -d '{"status":"in-progress","rev":"<rev from the GET>"}'
+```
+
+Every item carries a **`rev`** (the file's mtime when you read it). Send it back with your mutation and outcrop rejects the write with `409` if anyone touched the file in between. Never a silent merge. That one rule is what makes several agents plus a human safe on one workspace:
+
+1. `GET` the task, keep the `rev`.
+2. `PATCH` with that `rev` to claim it (`status: in-progress`).
+3. `409`? Someone else got there first. Re-read, reconcile, or pick a different task.
+
+Agents can also skip HTTP and edit the markdown directly. The format is specified precisely so both paths produce identical files. Convention: **agents stop at `in-review`, a human moves things to `done`** after running the task's test steps.
+
+Drop **[AGENTS.md](docs/AGENTS.md)** into your workspace to hand these rules to your agent, and **[llms.txt](llms.txt)** for the machine-readable index.
+
+## CLI reference
+
+```
+Usage: outcrop [workspace-dir] [-p|--port N] [-v|--version]
+
+  workspace-dir        workspace directory (default: cwd)
+  -p, --port N     port to serve on (default: 4311, or $PORT)
+  -v, --version    print version
+  -h, --help       print this help
+```
+
+| Env var | Effect |
+|---|---|
+| `PORT` | Serving port (overridden by `-p`) |
+| `BOARD_GIT_COMMIT=1` | Force git auto-commit on, whatever `.outcrop.json` says |
+| `OUTCROP_QUIET=1` | Silence the request log |
+
+If the port is already taken, usually by a second workspace you're already running, outcrop takes the next free one and says so instead of failing to start:
+
+```
+notes: http://localhost:4312
+  workspace    /Users/me/notes
+  port     4311 was busy, using 4312
+```
+
+It scans up to 20 ports before giving up.
+
+Every request is logged with what it actually touched, so you can watch a workspace while an agent works it:
+
+```
+21:23:41  PUT   /api/settings         200  .outcrop.json: views: ["docs"] -> ["board","docs"]
+21:23:41  GET   /docs?file=SPEC.md    200  SPEC.md
+21:23:53  PATCH /api/items/ST-001     200  tasks/ST-001.md: ST-001: ready -> in-progress via board
+21:24:02  GET   /sse                  200  2 client(s) live
+```
+
+Opening a task card shows up as a `GET /api/items/:id/pane`, because the board fetches detail panes on click rather than shipping them all up front. Filtering and theme changes stay in the browser and are not logged.
+
+## Settings
+
+Two tiers, because two different things are being remembered.
+
+**Workspace settings** live in `.outcrop.json` at the workspace root. They belong to the workspace, not to you, so commit them and your team gets the same board. Edit the file or use the gear menu; both take effect immediately, no restart. Missing file or a broken key falls back to the default, so an empty workspace still just works.
+
+```json
+{
+  "title": "Payments rewrite",
+  "views": ["board", "docs", "graph"],
+  "columns": ["backlog", "ready", "in-progress", "in-review", "done", "blocked"],
+  "gitCommit": false
+}
+```
+
+- `title`: header and page title. Defaults to the workspace directory name.
+- `views`: which of `board`, `docs` and `graph` are served. Drop `board` for a workspace with no `tasks/` folder and outcrop becomes a plain docs site. A disabled view redirects to the first one still enabled, and with one view the nav tabs disappear. At least one view must stay on: a `PUT` that turns all of them off is rejected, and the settings pane says so rather than quietly putting them back.
+- `columns`: board columns, in order. Values are slugged to match the `status` frontmatter key. A status used by a task always gets a column even if it's listed nowhere here, so renaming columns can never hide a task.
+- `gitCommit`: the persistent form of `BOARD_GIT_COMMIT=1`.
+
+**Browser settings** live in `localStorage`. They're per-person, so they never touch the workspace and never show up in a teammate's diff.
+
+| | |
+|---|---|
+| **Theme** | Light or dark, also on the header button. First visit follows your OS; after that your choice sticks. |
+| **Accent** | Violet (default), blue, emerald, amber, rose. Drives links, refs, focus rings, the Save button, drag targets and search highlights. |
+| **Typeface** | Sans (default), serif, or mono. OS font stacks only: no webfont is downloaded. |
+| **Size** | Compact, default, or large, scaling the whole UI. |
+
+Precedence: CLI flag > env var > `.outcrop.json` > default.
+
+Install globally if you'd rather not type `npx`:
+
+```bash
+npm install -g outcrop
+```
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| **[SPEC.md](docs/SPEC.md)** | Normative workspace format: frontmatter schema, IDs, links, revisions |
+| **[API.md](docs/API.md)** | HTTP API contract: endpoints, request/response shapes, status codes |
+| **[AGENTS.md](docs/AGENTS.md)** | Rules of engagement for AI agents working in a workspace |
+| **[llms.txt](llms.txt)** | Machine-readable index for LLM tooling |
+| **[RELEASING.md](docs/RELEASING.md)** | Maintainer notes: npm setup, versioning, publishing |
+
+## Tech stack
+
+No framework, on either side. The whole thing is TypeScript compiled to one Node script.
+
+**Backend**: Node's standard library only, nothing else at runtime.
+
+| Concern | What does it |
+|---|---|
+| HTTP | `node:http` `createServer`, with the handler written against the web `Request`/`Response` types |
+| Storage | The filesystem. `node:fs` reads and writes markdown; there is no database and no index on disk |
+| Live updates | Server-sent events over a `ReadableStream`, driven by a recursive `node:fs` `watch` |
+| Concurrency | File mtime as an optimistic-concurrency `rev`, returning `409` on a stale write |
+| Markdown | A ~100-line parser in `src/cli.ts`: frontmatter, headings, lists, tables, checkboxes, links |
+| Compression, hashing | `node:zlib` gzip, `node:crypto` SHA-1 for `ETag`s |
+| Git integration | `node:child_process` shelling out to `git` |
+
+**Frontend**: no framework, no build step, no client bundle, no hydration.
+
+| Concern | What does it |
+|---|---|
+| Rendering | Server-rendered HTML from template literals. The browser receives finished markup |
+| Styling | Tailwind CSS, compiled at build time into one stylesheet and inlined into the binary. Accent, typeface and scale are CSS custom properties switched by a `data-` attribute on `<html>`, so a preference change repaints without refetching anything |
+| Interactivity | ~300 lines of plain ES2022 in `<script>` tags: delegated listeners, `fetch`, `EventSource`, native drag-and-drop |
+| Navigation | Clicking a doc swaps the content in place and pushes history. No page reload, so the SSE connection is opened once per tab and never churns |
+| Updates | SSE tells the page something changed; it re-fetches and swaps `innerHTML`, or gets a `304` and does nothing. Every view closes its stream on `pagehide`: a browser allows six connections per origin and is slow to reclaim an abandoned page's, so leaving them to be collected starved later requests of a socket |
+| Detail panes | Fetched as HTML fragments on click and cached in a `Map` |
+| Diagrams | mermaid from a CDN, loaded lazily and only for docs that actually contain one |
+| Graph | Canvas 2D and a cut-down `d3-force` (1/d repulsion, degree-weighted springs, clamped velocity), no dependency and no SVG nodes to lay out. The layout is settled off-screen and framed before the first paint, so it opens still rather than flying apart. The forces are 3D in both modes: the flat graph is the globe with the z axis pinned, which is why there is one simulation and not two |
+| Persistence | `localStorage` for appearance, sidebar width and folded folders; everything shared goes to `.outcrop.json` |
+
+**Build and tooling**: all devDependencies. The published package has zero runtime dependencies.
+
+| | |
+|---|---|
+| Language | TypeScript (strict), typechecked by `tsc`, never emitted by it |
+| Package manager | Bun (`bun.lock`); npm is only used to publish with `--provenance` |
+| Bundler | Bun, producing one `dist/cli.js` targeting Node ≥ 20 |
+| CSS | Tailwind CLI, purging against the template literals in `src/**/*.ts` |
+| Lint / format | [oxlint](https://oxc.rs) and oxfmt |
+| Tests | `bun test` |
+| Hook | `.githooks/pre-commit`, wired by `bun install` |
+
+## Size
+
+One file, no runtime dependencies, nothing fetched at page load.
+
+| | |
+|---|---|
+| npm download | **42 KB** (tarball) |
+| Installed on disk | **147 KB**, of which `dist/cli.js` is 118 KB |
+| Runtime dependencies | **0** |
+| Stylesheet | 39 KB, inlined in the bundle, served as 6 KB gzipped and cached immutably |
+
+What a browser actually pulls, measured on a 300-task / 371-file workspace:
+
+| | gzipped |
+|---|---|
+| Board page | 46 KB |
+| Docs page | 13 KB |
+| Graph page | 9 KB, graph data inlined, so the view makes no follow-up request |
+| Stylesheet | 6 KB (once, then cached) |
+| One detail pane | 2 KB, fetched on click |
+| Switching to another doc | ~11 KB, ~11 ms, no page reload |
+| Live-reload with nothing to show | 0 bytes (`304`) |
+
+The bundle is deliberately not minified: it saves ~3 KB gzipped and costs readable stack traces.
+
+## Development
+
+Requires [Bun](https://bun.sh) to build (the output is plain Node, with no runtime dependencies).
+
+```bash
+git clone https://github.com/amirulhakiim/outcrop
+cd outcrop
+bun install              # dev tooling only; also installs the pre-commit hook
+bun run build            # styles.css -> styles.gen.css, then bundles src/cli.ts -> dist/cli.js
+bun run check            # format + lint + types + tests
+node dist/cli.js path/to/workspace
+```
+
+Bun is the package manager and the runner. There is no `package-lock.json`, only `bun.lock`.
+
+| Script | What it does |
+|---|---|
+| `bun run build` | Compile the stylesheet, then bundle to `dist/cli.js` |
+| `bun run lint` | oxlint (`--deny-warnings`, so a warning fails) |
+| `bun run fmt` | oxfmt, rewriting in place. `fmt:check` only reports |
+| `bun run typecheck` | `tsc --noEmit` over both projects, server and client |
+| `bun test` | Unit tests, plus end-to-end tests that spawn the built CLI and drive it over HTTP |
+| `bun run check` | All four, in the order the hook uses |
+
+`bun run` puts `node_modules/.bin` on `PATH`, so the scripts call `tailwindcss`, `oxlint`, and `tsc` directly, with no `npx` or `bunx` indirection.
+
+`bun install` runs `prepare`, which points `core.hooksPath` at `.githooks/`. The pre-commit hook formats the staged `src/` files, re-stages them, then runs oxlint and `tsc`; a lint warning or type error stops the commit. `git commit --no-verify` skips it.
+
+`bun run build` runs two steps: the Tailwind CLI compiles [`src/styles.css`](src/styles.css) into `src/styles.gen.css` (gitignored), then Bun inlines that as text so the shipped CLI stays a single file. Building `src/cli.ts` on its own will fail until `build:css` has run once.
+
+```
+src/
+├── cli.ts            server: routing, caching, markdown, HTML rendering
+├── settings.ts       .outcrop.json schema and normalisation
+├── styles.css        Tailwind source, compiled at build time
+├── client/           browser code: real TypeScript, typechecked and linted
+│   ├── prefs.ts      appearance preferences (localStorage)
+│   ├── chrome.ts     resizer, theme, sheet, settings, search shortcut
+│   ├── board.ts      board entry point
+│   ├── docs.ts       docs entry point
+│   └── tsconfig.json DOM types, no node types
+├── settings.test.ts  unit tests
+└── server.test.ts    end-to-end tests against the built CLI
+```
+
+The browser code is bundled separately (`bun run build:client` → `src/generated/*.js`, gitignored) and inlined into `dist/cli.js` as text, so the CLI is still a single shipped file with no runtime dependencies.
+
+Each client bundle is built as an IIFE. Without that, every bundle's top-level names land on `window`, and the pre-paint head script shares eight of them with the page scripts.
+
+### Performance notes
+
+Class names are scanned out of the template literals in `src/**/*.ts`, so a class assembled by string concatenation gets purged. Write them out in full. The accent swatches list `"swatch swatch-violet"` and friends verbatim for exactly this reason.
+
+Browser code belongs in `src/client/`, not in a template literal. Code inside a template string is data as far as `tsc` and oxlint are concerned: a call to an undefined function and an assignment to a `const` both used to pass lint, typecheck and build without a word.
+
+Anything the board repeats per task (the card, its chips, the priority and progress marks) is a component class in `styles.css` rather than inline utilities. Inline utility strings on a few hundred cards were about a third of the page.
+
+## FAQ
+
+**Does it modify my files?**
+Only the exact line you change. Moving a card rewrites one `status:` line; ticking a checkbox rewrites one `- [ ]`. Everything else in the file is byte-identical.
+
+**Is it multiplayer / hosted?**
+No. It binds locally and has no auth. Sharing state is git's job.
+
+**What if two agents write at once?**
+The second one gets a `409` and retries. See [For AI agents](#for-ai-agents).
+
+**Can I use my own file naming or extra frontmatter keys?**
+IDs and filenames follow the spec (`ST-###-slug.md`). Extra frontmatter keys are preserved on write but ignored by the board.
+
+## License
+
+[MIT](LICENSE)

package/assets/logo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="120 12 800 800">
+  <title>outcrop</title>
+  <desc>A rock outcrop: faceted strata breaking the surface.</desc>
+  <g id="outcrop-mark">
+    <path d="M140 640 L215 590 L275 500 L330 530 L385 400 L455 330 L515 170 L580 280 L650 245 L710 365 L780 430 L850 585 L900 640 Z" fill="#24282d"/>
+    <path d="M385 400 L455 330 L515 170 L525 410 L455 520 Z" fill="#e2e6ea"/>
+    <path d="M525 410 L515 170 L580 280 L650 245 L625 430 Z" fill="#59616a"/>
+    <path d="M625 430 L650 245 L710 365 L690 510 Z" fill="#30363d"/>
+    <path d="M455 520 L525 410 L625 430 L570 575 Z" fill="#414850"/>
+    <path d="M275 500 L330 530 L385 400 L410 525 L350 585 Z" fill="#7c858e"/>
+    <path d="M650 245 L710 365 L780 430 L720 465 L690 510 Z" fill="#747d86"/>
+    <path d="M140 640 L215 590 L275 600 L330 575 L350 585 L410 560 L455 590 L570 575 L630 610 L690 510 L720 465 L780 430 L850 585 L900 640 Z" fill="#343a41"/>
+    <path d="M215 590 L275 500 L275 600 Z" fill="#9aa1a8"/>
+    <path d="M350 585 L410 525 L455 590 Z" fill="#b9bec3"/>
+    <path d="M570 575 L625 430 L630 610 Z" fill="#8b939b"/>
+    <path d="M690 510 L720 465 L780 430 L760 550 Z" fill="#aeb4b9"/>
+    <path d="M140 640 L900 640 L850 655 L175 655 Z" fill="#15191d"/>
+  </g>
+</svg>