i-plane 1.1.2 → 1.2.0

package/docs/api-coverage.md

@@ -100,11 +100,20 @@ API endpoints; the diagnostic points to `issueId` from an earlier JSON response.
 - This is an inventory of the implemented surface, not a claim to cover every
   endpoint in every edition of Plane.
 
+## Project pages
+
+`pages` and `page show` use the internal session API. `page outline`, `page read`,
+`page stamp`, `page create`, `page set`, `page insert` and block removal use the
+live document protocol. Whole-page deletion uses the session API. See the
+[page workflow](pages.md) for credentials, fingerprints, formatting losses and
+asynchronous persistence. This internal API can change independently of Plane's
+public API; compatibility is covered by converter fixtures and live acceptance.
+
 ## Adding a command
 
 1. Add the command and all options to `src/registry.ts`. The parser gets value
    flags from the registry, including those of multiword commands.
-2. Add an online handler to `src/dispatch.ts`. Both missing handlers and handlers
+2. Add an online handler to `src/dispatch.ts` or a session handler to `src/page-dispatch.ts`. Both missing handlers and handlers
    absent from the registry fail the command-set test.
 3. Add a fixture invocation and valid option values to the registry suite. Test
    the requested method, path and body, and assert observable output. Merely
@@ -141,6 +150,7 @@ For live acceptance, build first and use the normal Plane credentials:
 bun run build
 node scripts/acceptance.mjs --live
 node scripts/planning-acceptance.mjs --live
+node scripts/pages-acceptance.mjs --live --project APP
 ```
 
 The first script creates an epic and nine children, then checks labels,
@@ -150,3 +160,8 @@ CLI commands and delete their temporary projects in a `finally` block.
 They space calls to respect the API request budget and take several minutes;
 a forced termination can interrupt cleanup. For a focused change, prefer a
 small targeted live check to repeating both scenarios.
+
+The page acceptance script creates and removes one page in the selected existing
+project. It exercises all nine commands and observes saved HTML within a bounded
+window; that window is a test limit, not a persistence guarantee. Run
+`node scripts/page-mutations.mjs` for isolated mutation checks.

package/docs/pages.md

@@ -0,0 +1,98 @@
+# Project pages
+
+Read project knowledge as Markdown, then change a section without rewriting the
+rest of the document. Pages use Plane's internal session API and live editor;
+they are available on instances exposing project pages and the live service.
+
+## Connect
+
+Add these to your private credentials file alongside `PLANE_URL` and
+`PLANE_WORKSPACE`:
+
+```ini
+PLANE_LOGIN=you@example.com
+PLANE_PASSWORD=your-password
+```
+
+An API token is optional for page commands and still required for work items.
+`i-plane config` reports whether credentials are configured and where they came
+from, without printing the login password or cookies. Sessions persist under
+`$XDG_CACHE_HOME/i-plane/sessions` or `~/.cache/i-plane/sessions`; the directory
+has mode 700 and files have mode 600. A restricted environment can select a
+private writable directory with `PLANE_SESSION_CACHE` or `--session-cache`.
+An expired session receives one refresh. HTTP and WebSocket connections honor
+`HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY`.
+
+## Read, inspect, edit
+
+```bash
+i-plane pages APP
+i-plane page show APP "Release notes"
+i-plane page outline APP "Release notes"
+```
+
+Pages accept a UUID, exact name or unique name prefix. Outline reads the live
+document and shows top-level index, eight-character anchor prefix, node kind and
+40-character preview. Neither reading command writes anchors. When an existing
+page has missing anchors, assign them explicitly:
+
+```bash
+i-plane page stamp APP "Release notes"
+i-plane page outline APP "Release notes"
+i-plane page read APP "Release notes" --block a1b2c3d4 --json
+```
+
+Use an actual anchor from outline. Copy the returned `fingerprint` into the next
+command; it hashes block content, while the anchor remains stable across edits:
+
+```bash
+i-plane page set APP "Release notes" --block a1b2c3d4 \
+  --if-match "$FINGERPRINT" --text "Updated paragraph"
+i-plane page insert APP "Release notes" --after a1b2c3d4 --text "Another paragraph"
+i-plane page insert APP "Release notes" --at-end --file appendix.md
+i-plane page rm APP "Release notes" --block a1b2c3d4 --if-match "$FINGERPRINT" --yes
+```
+
+Read a fresh fingerprint before each edit. A stale fingerprint refuses the
+change. `--force` explicitly bypasses that check. Without `--if-match`, a block
+edit uses the latest live content. A replacement's first block inherits the
+anchor; any additional blocks get new anchors. Repeating a command can produce
+additional changes: commands are never automatically replayed.
+
+## Create, replace, remove
+
+```bash
+i-plane page create APP --name "Release notes" --file release.md
+i-plane page set APP "Release notes" --file revised-release.md
+i-plane page rm APP "Release notes" --yes
+```
+
+`--file` and `--text` are mutually exclusive. Creation without either produces an
+empty page. Creation with content uses two steps; an error after creation names
+the new page UUID so you can recover without creating a duplicate. Empty content
+clears a whole page, but empty block replacement or insertion is refused. Use
+`page rm --block` for a block deletion. Page deletion always requires `--yes`. Plane requires archiving first; the CLI
+archives and then deletes the page. If deletion fails, the error reports the
+archived page UUID so you can inspect and recover it.
+Nested pages and `--parent` are unsupported by the project-page API.
+
+## Delivery and formatting
+
+Successful editing means **the live server acknowledged delivery**. It does not
+confirm a database commit. `page show` reads saved HTML and can immediately show
+the previous content: persistence usually takes about ten seconds, with no
+guaranteed upper bound. Use `page outline` and `page read` to check the immediate
+live result. An interrupted write without an acknowledgement reports uncertain
+delivery; inspect the live document before deciding whether to retry.
+
+Markdown supports headings, paragraphs, lists, code, links, images and tables.
+Rich editor features such as mentions, callouts, colors, underline, multiple
+paragraphs inside a table cell and layout
+attributes may not survive Markdown conversion. Unsupported nodes remain visible
+as XML text and the reader reports representation losses. Code-block languages
+are restored locally because the server converter discards them.
+
+Replacement checks the affected document and converted input. Reported losses
+require `--allow-loss`; `--force` does not approve them. A block edit leaves other
+blocks intact. None of these commands prompts for input, and every command
+supports `--json`. Run `i-plane page set --help` for flags and examples.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i-plane",
-  "version": "1.1.2",
-  "description": "Compact Plane CLI for coding agents: project management, issue tracking, cycles, modules and intake.",
+  "version": "1.2.0",
+  "description": "Compact Plane CLI for coding agents: tasks, projects, live pages, cycles, modules and intake.",
   "type": "module",
   "license": "MIT",
   "author": "iiiokojiadbi <iiiokojiadbi@yandex.ru>",
@@ -15,6 +15,7 @@
   "files": [
     "dist",
     "docs/api-coverage.md",
+    "docs/pages.md",
     "AGENTS.md",
     "CLAUDE.md"
   ],
@@ -23,7 +24,7 @@
   },
   "packageManager": "bun@1.4.0",
   "scripts": {
-    "build": "bun build src/cli.ts --target=node --outfile=dist/cli.js --minify --external undici",
+    "build": "bun build src/cli.ts --target=node --outdir=dist --splitting --entry-naming=[name].js --chunk-naming=chunks/[name]-[hash].js --minify --external undici --external yjs --external @hocuspocus/provider --external ws --external https-proxy-agent",
     "check": "tsc --noEmit",
     "lint": "biome check .",
     "format": "biome format --write .",
@@ -35,15 +36,23 @@
     "@types/markdown-it": "14.2.0",
     "@types/node": "24.13.4",
     "@types/turndown": "5.0.6",
+    "@types/ws": "8.18.1",
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
     "undici": "8.10.2"
   },
   "dependencies": {
+    "@hocuspocus/provider": "4.7.0",
+    "@mixmark-io/domino": "2.2.0",
+    "https-proxy-agent": "9.1.0",
     "markdown-it": "15.0.1",
+    "markdown-it-task-lists": "2.1.1",
     "turndown": "7.2.4",
-    "turndown-plugin-gfm": "1.0.2"
+    "turndown-plugin-gfm": "1.0.2",
+    "ws": "8.21.3",
+    "y-protocols": "1.0.7",
+    "yjs": "13.6.32"
   },
   "keywords": [
     "plane",
@@ -56,7 +65,9 @@
     "coding-agent",
     "agent-tools",
     "automation",
-    "markdown"
+    "markdown",
+    "knowledge-base",
+    "collaborative-editing"
   ],
   "homepage": "https://github.com/iiiokojiadbi/i-plane#readme",
   "bugs": {