slimwiki 0.1.0

package/AGENT.md

@@ -0,0 +1,316 @@
+# SlimWiki CLI — Agent Reference
+
+You are operating the `slimwiki` CLI. This file is the contract — every
+flag, output shape, and Tiptap-doc rule you need is here. If a behavior
+isn't documented below, run `slimwiki <subcommand> --help` first; don't
+guess.
+
+## Output contract
+
+- **Default output is JSON** on stdout. One JSON value per command.
+- **Errors** print `{"error":"<message>"}` on stderr and exit non-zero.
+- `--human` switches to a tabular format. Don't use it from an agent —
+  it's for human shell users and is not stable to parse.
+
+Always check the exit code. On non-zero, read stderr for the JSON error
+and decide whether to retry, re-authenticate, or surface to the user.
+
+## Authentication
+
+The CLI must be authenticated before any non-`auth` command. Three ways:
+
+1. `slimwiki auth login` — opens a browser. Interactive only.
+2. `SLIMWIKI_TOKEN=<bearer-token>` env var — for headless/CI/agent-runner
+   environments. Optional `SLIMWIKI_API_BASE=<url>` if not prod.
+3. A previously written `credentials.json` from a prior `auth login`.
+
+To check: `slimwiki auth status` returns `{"authenticated": true|false, ...}`.
+If `false`, ask the user to run `slimwiki auth login` — never try to
+prompt for credentials yourself.
+
+## Account / wiki selection
+
+Most commands accept `--account <slug>` and `--wiki <slug>`. Resolution
+order:
+
+1. Explicit flag.
+2. `SLIMWIKI_ACCOUNT_SLUG` / `SLIMWIKI_WIKI_SLUG` env vars.
+3. The slugs cached during `auth login`.
+4. Live `/users/me` lookup (primary account + default wiki).
+
+If the user belongs to one account, omit the flags. If multiple, list
+them with `slimwiki account list` and pass `--account <slug>` explicitly.
+
+## Commands
+
+### Discovery
+
+```
+slimwiki account list                                    # → [{slug, name}]
+slimwiki wiki list [--account <slug>]                    # → [{slug, name}]
+```
+
+### Reading pages
+
+```
+slimwiki page list [--account <slug>] [--wiki <slug>] \
+                   [--search <query>] \
+                   [--archived] \
+                   [--limit <n>] [--offset <n>]
+# → { "rows": [{title, slug, pageHash, updatedAt}, ...], "total": <int> }
+```
+
+`--search <q>` matches both title and content (ILIKE). Title hits rank
+above content-only hits. Output is metadata only — no `content` blob.
+
+```
+slimwiki page get <slug-or-pageHash-or-id> [--wiki <slug>] [--account <slug>]
+# → { id, title, slug, pageHash, content, archived, wikiId, updatedAt, ... }
+```
+
+`page get` returns the full Tiptap doc in `content`. Use this when you
+need to read existing content (e.g. to summarise or to base a new page
+on existing structure).
+
+### Creating pages
+
+```
+slimwiki page create --title "<title>" \
+                     (--file <path> | --content '<json>' | --stdin) \
+                     [--parent <slug-or-pageHash-or-id>] \
+                     [--wiki <slug>] [--account <slug>]
+# → the created page row including {id, slug, pageHash, ...}
+```
+
+Pass exactly one content source. The body MUST be a valid Tiptap doc
+(see contract below). The CLI validates locally before any network call;
+on a schema error you get a non-zero exit with a `path` to the failing
+node so you can fix and retry without a server round-trip.
+
+`--parent` accepts a UUID, 12-char `pageHash`, or slug. The new page is
+attached to the parent in the navigation tree.
+
+## Tiptap document contract
+
+Every `page create` body must be:
+
+```json
+{ "type": "doc", "content": [ ...block-nodes ] }
+```
+
+Recognised node types — anything else will be rejected:
+
+| Type             | Required attrs                         | Notes                                           |
+|------------------|----------------------------------------|-------------------------------------------------|
+| `paragraph`      | —                                      | Body content                                    |
+| `heading`        | `level: 1 \| 2 \| 3`                   | No h4+                                          |
+| `bulletList`     | —                                      | Wraps `listItem` nodes                          |
+| `orderedList`    | `start?: number`                       | Wraps `listItem` nodes                          |
+| `listItem`       | —                                      | Inside `bulletList`/`orderedList`               |
+| `taskList`       | —                                      | Wraps `taskItem` nodes                          |
+| `taskItem`       | `checked?: boolean`                    | Inside `taskList`                               |
+| `blockquote`     | —                                      | Wraps block nodes                               |
+| `codeBlock`      | `language?: string`                    | Children are `text` only                        |
+| `horizontalRule` | —                                      | Self-closing                                    |
+| `image`          | `src: string`, `alt?`, `title?`        | URL must be reachable from the SlimWiki frontend|
+| `video`          | `src: string`                          | Same as image                                   |
+| `attachment`     | `src?`, `name?`                        |                                                 |
+| `math`           | `latex: string`                        | Inline node — must live inside a paragraph      |
+| `pageMention`    | `pageId: string`                       | Link to another SlimWiki page                   |
+| `table`          | —                                      | Wraps `tableRow`                                |
+| `tableRow`       | —                                      | Wraps `tableCell` / `tableHeader`               |
+| `tableCell`      | —                                      | Children = block nodes (usually `paragraph`)    |
+| `tableHeader`    | —                                      | Same as tableCell, used in the first row        |
+
+Inline / leaf nodes:
+
+- `text` with `text: string` and optional `marks`.
+- `hardBreak` (line break inside a paragraph).
+
+Marks (apply via `text.marks: [{ type: "<mark>", attrs?: ... }]`):
+
+- `bold`, `italic`, `underline`, `strike`, `code`, `highlight`
+- `link` — requires `attrs.href`
+- `textStyle` — optional `attrs.color` (CSS color)
+
+### Minimal valid doc
+
+```json
+{
+  "type": "doc",
+  "content": [
+    { "type": "paragraph",
+      "content": [{ "type": "text", "text": "Hello." }] }
+  ]
+}
+```
+
+### Idiomatic patterns
+
+**Heading + paragraph**
+
+```json
+{ "type": "heading", "attrs": { "level": 1 },
+  "content": [{ "type": "text", "text": "Quarterly roadmap" }] }
+{ "type": "paragraph",
+  "content": [{ "type": "text", "text": "Owner: " },
+              { "type": "text", "text": "@jamie", "marks": [{ "type": "bold" }] }] }
+```
+
+**Bullet list**
+
+```json
+{ "type": "bulletList", "content": [
+  { "type": "listItem", "content": [
+    { "type": "paragraph", "content": [{ "type": "text", "text": "First item" }] }
+  ]}
+]}
+```
+
+**Table** (every cell wraps a `paragraph`)
+
+```json
+{ "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" }] }
+    ]}
+  ]}
+]}
+```
+
+**Code block**
+
+```json
+{ "type": "codeBlock", "attrs": { "language": "ts" },
+  "content": [{ "type": "text", "text": "const x: number = 1;" }] }
+```
+
+**Math** (inline only — wrap in a paragraph)
+
+```json
+{ "type": "paragraph", "content": [
+  { "type": "text", "text": "Einstein: " },
+  { "type": "math", "attrs": { "latex": "E = mc^2" } }
+]}
+```
+
+**Link**
+
+```json
+{ "type": "paragraph", "content": [
+  { "type": "text", "text": "See ", "marks": [] },
+  { "type": "text", "text": "the docs",
+    "marks": [{ "type": "link", "attrs": { "href": "https://example.com" } }] }
+]}
+```
+
+## Recipe library
+
+### "Create a page about X with a table of Y vs Z"
+
+```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": "Common cultivars and their colors." }] },
+    { "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 pages containing 'SpaceX'"
+
+```sh
+slimwiki page list --search SpaceX
+# Parse the .rows array; .total tells you how many matches across the wiki.
+```
+
+### "How many pages mention rockets?"
+
+```sh
+slimwiki page list --search rockets | jq '.total'
+```
+
+### "Read the page about HR benefits and summarise it"
+
+```sh
+# 1. Find the slug
+slimwiki page list --search "HR benefits" --limit 3
+
+# 2. Fetch the full doc (use the slug from step 1)
+slimwiki page get <slug>
+# .content is a full Tiptap doc — walk it to extract text.
+```
+
+### "Create a child page under an existing parent"
+
+```sh
+slimwiki page create --title "Q3 Plan" \
+                     --parent quarterly-roadmap \
+                     --file q3.json
+```
+
+### "List archived pages"
+
+```sh
+slimwiki page list --archived --limit 100
+```
+
+## Failure modes you will hit
+
+- **`Not authenticated`** — credentials missing or expired. Ask the user
+  to `slimwiki auth login` (or set `SLIMWIKI_TOKEN`). Do not loop on it.
+- **`Tiptap doc validation failed at <path>`** — your JSON didn't match
+  the schema. The path tells you which node. Fix locally and retry; no
+  network call was made.
+- **`Account not found for slug "..."`** / **`Wiki not found for slug
+  "..."`** — bad `--account`/`--wiki`. Run `slimwiki account list` /
+  `slimwiki wiki list` to discover the right slug.
+- **`Parent page not found`** — `--parent` value didn't match any slug,
+  pageHash, or UUID in the wiki. Search first.
+- **HTTP 4xx/5xx** — network or server error. The error body is
+  forwarded verbatim. Surface to the user; don't keep retrying.
+
+## Hard rules
+
+- **Don't use `--human`.** Always parse JSON.
+- **Don't ask the user to paste their token into a prompt.** Use
+  `auth login` (browser) or `SLIMWIKI_TOKEN`.
+- **Don't fabricate node types.** If a block doesn't exist in the table
+  above, don't emit it. The schema will reject and abort.
+- **Don't transform the user's content before posting.** If they
+  describe content in markdown, convert it directly to Tiptap JSON
+  yourself — don't shell out to a markdown→tiptap converter.
+- **Don't set `slug` or `pageHash` on create.** The server generates them.
+- **Don't post empty pages.** A doc with at least one paragraph is the
+  minimum the editor will render cleanly.

package/LICENSE.md

@@ -0,0 +1,65 @@
+# SlimWiki CLI License
+
+Copyright (c) 2026 SlimWiki Pte. Ltd. All rights reserved.
+
+This software ("the SlimWiki CLI", or "the Software") is the
+proprietary property of SlimWiki Pte. Ltd. ("SlimWiki"). It is licensed,
+not sold.
+
+## 1. Permitted use
+
+Subject to the restrictions below, SlimWiki grants you a non-exclusive,
+non-transferable, royalty-free licence to:
+
+- Install the Software on devices you own or operate.
+- Run the Software to interact with a SlimWiki workspace you are
+  authorised to access.
+- Distribute unmodified copies of the official npm-published artefact
+  to other users for the same purpose.
+
+## 2. Restrictions
+
+You may NOT, without prior written permission from SlimWiki:
+
+- Modify, adapt, translate, reverse-engineer, decompile, or disassemble
+  the Software, or create derivative works based on it, except to the
+  minimum extent expressly permitted by applicable law.
+- Redistribute modified copies of the Software, or republish it under a
+  different name or organisation.
+- Use the Software to build, train, or operate a product or service that
+  competes with SlimWiki.
+- Remove or alter any copyright, trademark, or attribution notices.
+
+## 3. No transfer of rights
+
+All right, title, and interest in and to the Software (including all
+intellectual property rights) remain with SlimWiki. No rights are
+granted by implication, estoppel, or otherwise except as expressly set
+out in this licence.
+
+## 4. Trademarks
+
+"SlimWiki" and the SlimWiki logo are trademarks of SlimWiki Pte. Ltd.
+This licence does not grant you any rights to use those trademarks.
+
+## 5. Disclaimer of warranty
+
+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 NON-INFRINGEMENT.
+
+## 6. Limitation of liability
+
+IN NO EVENT SHALL SLIMWIKI BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR
+ITS USE.
+
+## 7. Termination
+
+This licence terminates automatically if you breach any of its terms.
+On termination, you must cease all use of the Software and destroy any
+copies in your possession.
+
+## 8. Contact
+
+For licensing inquiries, please contact: support@slimwiki.com