slimwiki 0.1.0 → 0.1.1

package/README.md

@@ -4,30 +4,14 @@ 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:
+## Install
 
 ```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
+## Authenticate
 
 ```sh
 slimwiki auth login
@@ -57,7 +41,7 @@ slimwiki auth status
 
 `slimwiki auth logout` revokes the session and wipes the local file.
 
-### 3. Wire up an AI agent
+## Wire up an AI agent
 
 The CLI ships two artefacts so agents can learn its contract without
 you re-explaining each session:
@@ -252,183 +236,3 @@ slimwiki page list --archived --limit 100
 - `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slimwiki",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agent-friendly CLI for SlimWiki — auth, search, and create wiki pages from JSON.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "SlimWiki Pte. Ltd.",