slimwiki 0.1.0

package/README.md

@@ -0,0 +1,434 @@
+# slimwiki
+
+Agent-friendly CLI for [SlimWiki](https://slimwiki.com). Lets a human or an
+AI agent sign in to a SlimWiki account, browse pages, and create new
+ones from Tiptap JSON.
+
+The two audiences this README addresses:
+
+- **End users + their AI agents** — install the CLI, authenticate it
+  once, then either run commands by hand or let an agent drive it. Jump
+  to [Install & use](#install--use).
+- **Contributors** — clone the monorepo, run a local stack, edit CLI
+  source. Jump to [Development](#development).
+
+---
+
+## Install & use
+
+### 1. Install the CLI
+
+Once published:
+
+```sh
+npm i -g slimwiki       # or pnpm add -g, bun i -g
+slimwiki --version
+```
+
+Until then, install from source — see [Local install for users](#local-install-for-users).
+
+### 2. Authenticate
+
+```sh
+slimwiki auth login
+```
+
+Opens your browser, you click *Allow*, the CLI saves a 14-day session
+token to:
+
+- macOS: `~/Library/Application Support/slimwiki/credentials.json`
+- Linux: `~/.config/slimwiki/credentials.json`
+- Windows: `%APPDATA%\slimwiki\credentials.json`
+
+Sanity check:
+
+```sh
+slimwiki auth status
+slimwiki account list
+```
+
+For headless agents (CI, remote machines) skip the browser flow:
+
+```sh
+export SLIMWIKI_TOKEN=<bearer-token>
+export SLIMWIKI_API_BASE=https://slimwiki.com   # optional, defaults to prod
+slimwiki auth status
+```
+
+`slimwiki auth logout` revokes the session and wipes the local file.
+
+### 3. Wire up an AI agent
+
+The CLI ships two artefacts so agents can learn its contract without
+you re-explaining each session:
+
+- **`AGENT.md`** — agent-agnostic contract: command surface, JSON
+  output shape, Tiptap-doc schema, failure modes, recipes.
+- **`SKILL.md`** — Claude Code skill stub with frontmatter.
+- **`slimwiki agent-help`** — prints `AGENT.md` to stdout for sandboxed
+  agents that can't read files.
+
+Pick the row that matches your tool:
+
+| Agent | One-time setup |
+|---|---|
+| **Claude Code** | `mkdir -p ~/.claude/skills/slimwiki && ln -sf $(npm root -g)/slimwiki/{SKILL,AGENT}.md ~/.claude/skills/slimwiki/`. Then invoke `/slimwiki` in any session. |
+| **Cursor / Aider / Continue** | Add to project rules (e.g. `.cursorrules`): *"When the user asks to read or write SlimWiki content, use the `slimwiki` CLI. Run `slimwiki agent-help` first to load the contract."* |
+| **Claude API / custom agent** | Pipe `slimwiki agent-help` into the system prompt, or expose a tool that runs CLI subcommands. |
+
+Verify it works: open an agent session and ask *"create a SlimWiki page
+titled 'Hello' with one paragraph"*. The agent should run
+`slimwiki page create --title "Hello" --stdin <<...`.
+
+---
+
+## Output
+
+By default every command prints **one JSON value** on stdout — agents
+parse this directly. Errors print `{"error":"..."}` on stderr and exit
+non-zero.
+
+Pass `--human` for a tabular / formatted view when running the CLI
+interactively.
+
+```sh
+slimwiki account list                  # JSON
+slimwiki account list --human          # table
+```
+
+The CLI deliberately strips internal UUIDs from output — agents
+reference accounts and wikis by `slug`, and pages by `slug` or
+`pageHash`. UUIDs stay inside the CLI for resolving API paths.
+
+## Commands
+
+```
+slimwiki auth login    [--api-base <url>]
+slimwiki auth logout
+slimwiki auth status
+
+slimwiki account list                                     # → [{slug, name}]
+slimwiki wiki list     [--account <slug>]                 # → [{slug, name}]
+
+slimwiki page list     [--account <slug>] [--wiki <slug>]
+                       [--search <query>] [--archived]
+                       [--limit N] [--offset M]
+                       # → { rows: [{title, slug, pageHash, updatedAt}], total }
+
+slimwiki page get      <slug-or-pageHash-or-id>
+                       [--account <slug>] [--wiki <slug>]
+                       # → full page row including Tiptap doc body
+
+slimwiki page create   --title <title>
+                       (--file <path> | --content <jsonString> | --stdin)
+                       [--parent <slug-or-pageHash-or-id>]
+                       [--account <slug>] [--wiki <slug>]
+
+slimwiki agent-help    # prints AGENT.md to stdout
+```
+
+Global flags (work on every command):
+
+- `--human` — opt into formatted output (default: JSON).
+- `--api-base <url>` — override the API base for this invocation. Useful
+  for local dev without disturbing cached credentials.
+
+Defaults for `--account` / `--wiki`, in order:
+
+1. The flag value.
+2. `SLIMWIKI_ACCOUNT_SLUG` / `SLIMWIKI_WIKI_SLUG` env vars.
+3. The slugs cached during `auth login`.
+4. The user's primary account + that account's default wiki (live
+   `/users/me` lookup).
+
+If the user belongs to exactly one account, no flags are required.
+
+## Tiptap document contract
+
+`page create` accepts a single object of shape
+`{ "type": "doc", "content": [...] }`. The CLI validates locally before
+sending — invalid payloads exit non-zero with the path of the failing
+node so an agent can fix and retry without a server round-trip.
+
+Recognised node types — anything else is rejected:
+
+| Type             | Required attrs                  | Notes                                      |
+|------------------|---------------------------------|--------------------------------------------|
+| `paragraph`      | —                               |                                            |
+| `heading`        | `level: 1 \| 2 \| 3`            | No h4+                                     |
+| `bulletList`     | —                               | Wraps `listItem` nodes                     |
+| `orderedList`    | `start?: number`                | Wraps `listItem` nodes                     |
+| `listItem`       | —                               |                                            |
+| `taskList`       | —                               | Wraps `taskItem` nodes                     |
+| `taskItem`       | `checked?: boolean`             |                                            |
+| `blockquote`     | —                               |                                            |
+| `codeBlock`      | `language?: string`             | Children are `text` only                   |
+| `horizontalRule` | —                               | Self-closing                               |
+| `image`          | `src: string`, `alt?`, `title?` | URL must be reachable from the frontend    |
+| `video`          | `src: string`                   |                                            |
+| `attachment`     | `src?`, `name?`                 |                                            |
+| `math`           | `latex: string`                 | **Inline** — must live inside a paragraph  |
+| `pageMention`    | `pageId: string`                |                                            |
+| `table`          | —                               | Wraps `tableRow`                           |
+| `tableRow`       | —                               | Wraps `tableCell` / `tableHeader`          |
+| `tableCell`      | —                               | Children = block nodes (usually paragraph) |
+| `tableHeader`    | —                               | Same as tableCell, used in the first row   |
+
+Inline / leaf:
+
+- `text` — `text: string`, optional `marks`.
+- `hardBreak` — line break inside a paragraph.
+
+Marks (apply via `text.marks: [{ type, attrs? }]`):
+
+- `bold`, `italic`, `underline`, `strike`, `code`, `highlight`
+- `link` (`attrs.href`)
+- `textStyle` (optional `attrs.color`)
+
+See `cli/AGENT.md` for the full canonical contract — it's the source of
+truth that agents read.
+
+## Recipes
+
+### Create a page from Tiptap JSON
+
+```sh
+slimwiki page create --title "Apple varieties" --stdin <<'JSON'
+{
+  "type": "doc",
+  "content": [
+    { "type": "heading", "attrs": { "level": 1 },
+      "content": [{ "type": "text", "text": "Apple varieties" }] },
+    { "type": "paragraph",
+      "content": [{ "type": "text", "text": "A few common cultivars." }] },
+    { "type": "table", "content": [
+      { "type": "tableRow", "content": [
+        { "type": "tableHeader", "content": [{ "type": "paragraph",
+          "content": [{ "type": "text", "text": "Name" }] }] },
+        { "type": "tableHeader", "content": [{ "type": "paragraph",
+          "content": [{ "type": "text", "text": "Color" }] }] }
+      ]},
+      { "type": "tableRow", "content": [
+        { "type": "tableCell", "content": [{ "type": "paragraph",
+          "content": [{ "type": "text", "text": "Granny Smith" }] }] },
+        { "type": "tableCell", "content": [{ "type": "paragraph",
+          "content": [{ "type": "text", "text": "Green" }] }] }
+      ]}
+    ]}
+  ]
+}
+JSON
+```
+
+### Find / count pages
+
+```sh
+slimwiki page list --search SpaceX
+slimwiki page list --search rockets | jq '.total'
+slimwiki page list --search "HR benefits" --limit 3
+```
+
+### Read a page
+
+```sh
+slimwiki page get quarterly-roadmap-x      # by slug
+slimwiki page get 1jydyfwevwro             # by pageHash (rename-stable)
+```
+
+### Create a child page
+
+```sh
+slimwiki page create --title "Q3 Plan" --parent quarterly-roadmap --file q3.json
+```
+
+### List archived pages
+
+```sh
+slimwiki page list --archived --limit 100
+```
+
+## Exit codes
+
+- `0` — success.
+- `1` — any error (auth, validation, network, API). Stderr carries
+  `{"error":"..."}` so agents can branch on it.
+
+---
+
+## Development
+
+The CLI is a workspace package inside the SlimWiki monorepo at
+`/cli/`, alongside `/api/` and `/frontend/`.
+
+### Repo layout
+
+```
+cli/
+├── package.json           # bin: slimwiki, deps: commander, env-paths, open, zod
+├── tsconfig.json          # strict TS, NodeNext, ESM
+├── tsup.config.ts         # bundles src/index.ts → dist/index.js (single file)
+├── AGENT.md               # contract for AI agents
+├── SKILL.md               # Claude Code skill stub
+├── README.md              # this file
+└── src/
+    ├── index.ts           # commander root, registers subcommands
+    ├── commands/
+    │   ├── auth.ts        # login (browser device flow), logout, status
+    │   ├── account.ts     # account list
+    │   ├── wiki.ts        # wiki list
+    │   ├── page.ts        # page list, get, create
+    │   └── agent-help.ts  # prints AGENT.md
+    ├── lib/
+    │   ├── api-client.ts  # fetch wrapper: bearer auth, JSON parsing, error mapping
+    │   ├── config.ts      # ~/.config/slimwiki/credentials.json + SLIMWIKI_TOKEN
+    │   ├── output.ts      # JSON-default vs --human, stderr error path
+    │   ├── selectors.ts   # resolve --account/--wiki/--parent flags into IDs
+    │   └── tiptap-schema.ts  # Zod schema for the page-create body
+    └── types.ts           # public response shapes (no UUIDs)
+```
+
+The CLI talks to the SlimWiki API over HTTPS only. It does **not**
+import anything from `api/` — bringing Drizzle, Better Auth server,
+etc. into a CLI binary would balloon its size and tie its release
+cadence to the API's.
+
+### Local install for users
+
+End users who want to try the CLI without waiting for an npm release:
+
+```sh
+git clone git@github.com:slimwiki/slimwiki.git
+cd slimwiki
+pnpm install
+pnpm --filter slimwiki build
+
+# Put `slimwiki` on PATH. Either:
+cd cli && npm link              # uses your existing Node bin dir
+# or:
+pnpm setup && pnpm link --global   # one-time pnpm bin setup
+
+slimwiki --version
+```
+
+Note that `pnpm link --global` requires `pnpm setup` to have been run
+once on the machine (it adds `PNPM_HOME` to your shell rc).
+
+### Local dev loop
+
+With the API and frontend running locally:
+
+```sh
+# Terminal 1 — API
+cd api && pnpm dev          # listens on :3001
+
+# Terminal 2 — Frontend
+cd frontend && pnpm dev     # listens on :3000
+
+# Terminal 3 — CLI
+cd cli
+pnpm dev                    # tsup --watch, rebuilds dist/ on save
+
+# In another terminal, run commands against the local stack:
+node dist/index.js auth login --api-base http://localhost:3001
+node dist/index.js account list --api-base http://localhost:3001
+```
+
+`--api-base` is a global flag, so any command can be redirected at
+localhost without re-running `auth login`. The flag is more convenient
+during development than baking the value into credentials.
+
+`pnpm dev` runs tsup in watch mode — every save rebuilds
+`dist/index.js`. If you've run `npm link` once, your global `slimwiki`
+points at the same `dist/`, so subsequent invocations pick up changes
+automatically.
+
+### Typecheck / build / clean
+
+```sh
+pnpm --filter slimwiki typecheck    # tsc --noEmit
+pnpm --filter slimwiki build        # tsup → dist/index.js
+```
+
+The bundle is a single ESM file with a `#!/usr/bin/env node` shebang.
+There's no separate type-declaration output — the CLI isn't intended to
+be imported as a library.
+
+### How auth works under the hood
+
+`slimwiki auth login` runs a **device-code OAuth flow** modelled on
+`gh auth login` and `vercel login`:
+
+1. CLI POSTs `/api/v1/auth/cli/init`. API generates a 32-byte
+   `deviceCode` and an 8-character `userCode` (e.g. `WXYZ-1234`),
+   inserts them into `cli_auth_codes` with a 10-minute TTL.
+2. CLI prints the `userCode` to stderr and `open()`s the browser at
+   `${client.url}/cli-auth?code=<userCode>`.
+3. Frontend's `/cli-auth` page (`frontend/src/app/[locale]/cli-auth/`)
+   gates on session, displays the code, and POSTs `/api/v1/auth/cli/approve`
+   when the user clicks Allow.
+4. API mints a fresh `ba_session` row tied to the user, attaches its
+   `id` to the device-code row.
+5. CLI polls `/api/v1/auth/cli/poll` every ~2s. While unapproved →
+   `{ status: "pending" }`. Once approved → `{ status: "approved",
+   token, expiresAt, user, account, wiki }`. CLI persists everything
+   to `credentials.json`.
+
+The session token is a regular Better Auth `ba_session.token` — the
+CLI sends it as `Authorization: Bearer <token>`, and the API's
+existing `bearer()` plugin handles every subsequent request without
+CLI-specific code paths.
+
+Server endpoints live in `api/src/routes/v1/auth.ts` and
+`api/src/services/CliAuthService.ts`; the table schema is in
+`api/src/db/schema/cliAuthCodes.ts` (migration 0011).
+
+### Adding a new command
+
+1. Create `src/commands/<name>.ts`. Export a single
+   `register<Name>Commands(program: Command)` function that attaches
+   subcommands to the passed-in commander program.
+2. Reuse `requireAuth({ apiBaseOverride: apiBaseOverride(cmd) })` for
+   anything that needs the bearer token.
+3. Use `writeResult(cmd, value, humanFormatter?)` for the success path
+   and `exitWithError(err)` for the failure path. Don't `console.log`
+   directly — those helpers handle JSON-vs-human output and exit codes.
+4. Strip API responses to a narrow public shape before emitting them.
+   Defining a new type in `src/types.ts` keeps that contract obvious.
+5. Register the new file in `src/index.ts`.
+6. Document the command in this README + `AGENT.md`. The two should
+   stay in sync — `AGENT.md` is what agents read first.
+
+### Adding a Tiptap node type
+
+The Zod schema in `src/lib/tiptap-schema.ts` is the contract documented
+in `AGENT.md`. To add a new node:
+
+1. Add a discriminated-union branch to the `Node` schema. Use
+   `.passthrough()` so unknown attrs survive the round-trip.
+2. Update the table in `AGENT.md` (and this README) — node name and
+   required attrs.
+3. Verify the same node name and attrs are registered on the frontend
+   in `frontend/src/extensions/index.ts` and in the API's hocuspocus
+   shadow extensions in
+   `api/src/lib/collaboration/extensions/extensions.ts`. All three
+   must agree, or pages saved through the CLI won't render in the
+   editor.
+
+A real-world example of why this matters: the `math` node is named
+`math` (not `mathematics`) with attr `latex` (not `formula`). Getting
+that wrong meant the frontend rejected docs the CLI happily accepted.
+
+### Releasing
+
+(Pre-launch — workflow TBD when the package goes public on npm.)
+
+Rough plan:
+
+1. Bump `cli/package.json` version.
+2. `pnpm --filter slimwiki build`.
+3. `cd cli && npm publish --access public`.
+4. Tag the repo: `git tag cli-vX.Y.Z && git push --tags`.
+
+`AGENT.md` and `SKILL.md` are listed in `package.json#files` so they
+ship with the npm package; `slimwiki agent-help` reads `AGENT.md` from
+the package's installed location at runtime.

package/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: slimwiki
+description: Operate the SlimWiki CLI to create, search, and read wiki pages. Use whenever the user asks to add, find, summarise, or update content in their SlimWiki workspace.
+---
+
+# slimwiki
+
+You have access to the `slimwiki` CLI. It is the only sanctioned way to
+read or write SlimWiki content — do not call the SlimWiki API directly.
+
+**Always read [AGENT.md](./AGENT.md) before issuing your first command in
+a session.** It contains the full command surface, the JSON output
+contract, the Tiptap document schema, and the failure modes you will
+hit. Do not guess node types or flag names.
+
+If `AGENT.md` is not on disk (sandboxed environments), run
+`slimwiki agent-help` to print the same content to stdout.