i-plane 1.1.1 → 1.2.0

package/docs/api-coverage.md

@@ -69,6 +69,13 @@ Field references: [module creation](https://developers.plane.so/api-reference/mo
 
 ## Compatibility details
 
+The supported runtime is Node 22.21+ on the 22.x line, or Node 24+. The optional
+proxy dependency, `undici` 8.x, requires Node 22.19 or newer. The fallback based
+on `NODE_USE_ENV_PROXY` requires Node 22.21 or Node 24; the package's `engines`
+range covers both transport paths. Node 20 is not a supported configuration.
+See [Undici support](https://github.com/nodejs/undici#long-term-support) and
+[Node proxy support](https://nodejs.org/api/cli.html#node_use_env_proxy1).
+
 Enabling intake on project creation requires a follow-up project PATCH to create
 the queue. A creation flag alone can leave `intake_view=true` without an intake
 record, causing the first submission to fail with HTTP 500. The CLI initializes
@@ -93,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
@@ -112,3 +128,40 @@ Reference: [projects](https://developers.plane.so/api-reference/project/add-proj
 [cycles](https://developers.plane.so/api-reference/cycle/transfer-cycle-work-items),
 [modules](https://developers.plane.so/api-reference/module/add-module),
 [intake](https://developers.plane.so/api-reference/intake-issue/overview).
+
+## Development checks
+
+From a repository checkout:
+
+```bash
+bun test
+bun run check
+bun run lint
+node scripts/release.mjs
+```
+
+The release gate builds and checks the distributable, smoke-tests the command,
+and validates package contents, size and registry availability. Its default run
+does not publish; `--publish` is the publishing path.
+
+For live acceptance, build first and use the normal Plane credentials:
+
+```bash
+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,
+assignment, dates, comments, states and archive. The second checks cycles,
+unfinished-work transfer, module membership and the intake lifecycle. Both use
+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,13 +1,10 @@
 {
   "name": "i-plane",
-  "version": "1.1.1",
-  "description": "CLI \u0434\u043b\u044f Plane \u0441 \u043f\u043b\u043e\u0442\u043d\u044b\u043c \u0432\u044b\u0432\u043e\u0434\u043e\u043c \u043f\u043e\u0434 \u0430\u0433\u0435\u043d\u0442\u0430",
+  "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>",
-  "contributors": [
-    "Claude (Anthropic) <noreply@anthropic.com>"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/iiiokojiadbi/i-plane.git"
@@ -18,15 +15,16 @@
   "files": [
     "dist",
     "docs/api-coverage.md",
+    "docs/pages.md",
     "AGENTS.md",
     "CLAUDE.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": "^22.21.0 || >=24.0.0"
   },
   "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 .",
@@ -38,14 +36,41 @@
     "@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",
+    "plane-cli",
+    "plane-so",
+    "project-management",
+    "issue-tracker",
+    "task-management",
+    "cli",
+    "coding-agent",
+    "agent-tools",
+    "automation",
+    "markdown",
+    "knowledge-base",
+    "collaborative-editing"
+  ],
+  "homepage": "https://github.com/iiiokojiadbi/i-plane#readme",
+  "bugs": {
+    "url": "https://github.com/iiiokojiadbi/i-plane/issues"
   }
 }