i-plane 1.0.0

package/AGENTS.md

@@ -0,0 +1,94 @@
+# Working on this repository
+
+Read this before changing anything here. It is not documentation of what the tool
+does — that is `README.md` — it is what breaks when the rules below are ignored.
+
+## What this is
+
+A CLI for [Plane](https://plane.so) whose caller is a coding agent, not a person
+at a terminal. Plane's REST answer for seven work items is ~6,500 tokens of JSON;
+this prints ~145 tokens of lines. Every rule below follows from that one fact.
+
+## Authorship
+
+Written by Claude (Anthropic) with the repository owner. The owner decides what
+gets built and what ships; the model writes the code, runs the checks, and
+reports what it finds — including when the finding is its own bug.
+
+## Invariants
+
+Breaking one of these is a bug even when tests pass.
+
+**Nothing prompts, ever.** A CLI that waits for input hangs an agent forever. A
+missing argument is a `UsageError` naming what was expected; `src/commands/guide.ts`
+turns it into a hint with that command's real examples.
+
+**Exit codes are a contract.** `2` the call was wrong, `1` Plane refused or was
+unreachable. Callers branch on the code instead of parsing text, so a
+misclassified error is worse than a vague message.
+
+**`--json` is never optional.** Commands build a model and hand it to a formatter;
+`printValue` in `src/output.ts` decides between them. Print directly and you have
+silently dropped `--json` for that command.
+
+**`src/registry.ts` is the single source for commands.** It feeds the guide, every
+`<command> --help`, and the hint on a failed call — and it is what rejects unknown
+flags. Add a flag to a command without adding it there and the CLI will refuse it.
+
+**Never trust a server-side filter.** The list endpoint honours `fields` and
+`expand` (11 KB → 737 bytes on the wire) but accepts `state_group`, `priority` and
+`order_by` with a 200 and ignores them. Narrowing happens in `src/commands/issues.ts`.
+
+**Never let the token reach text.** `redact` in `src/client.ts` guards every error
+path; `maskToken` guards `config`. Node puts an offending header value into its
+own error message, and a server can echo a key back in an error body.
+
+**Pin versions exactly.** A range once meant the tree tested here and the tree a
+user installs were different — undici, `^7.16.0` against 8.10.2 installed.
+
+## Ground already lost once
+
+Twenty-one findings came out of one review. These are the ones worth remembering:
+
+| What happened | Why |
+|---|---|
+| ` ```c++ ` hung the process forever | a fence pattern that refused a line without consuming it |
+| `--yes=false` deleted a work item | a switch tested for presence, not value |
+| a misspelled `--priority` returned an unfiltered list, exit 0 | no flag validation |
+| the API token appeared in an error message | masking guarded one command, not the error paths |
+| a description lost `<div>` inside inline code | entity decoding followed by tag stripping |
+
+The Markdown conversion was hand-written and lost five ways at once. It now uses
+`markdown-it` and `turndown`. `markdown-it` rather than `marked` for one reason:
+with `html:false` it escapes raw HTML instead of passing `<img src=x onerror=…>`
+into other people's browsers.
+
+## Checks
+
+```bash
+bun test                              # every case is a bug that shipped once
+./node_modules/.bin/tsc --noEmit      # src and types; tests are checked by bun
+./node_modules/.bin/biome check .
+node scripts/release.mjs              # the full gate, without publishing
+```
+
+Tests are deliberately not in `tsc`'s `include`: pulling `bun-types` in collides
+with `@types/node` inside the library's own declarations, and a type error in
+someone else's file says nothing about this code.
+
+## Testing against a live instance
+
+Credentials are at `~/.config/plane/credentials` and the CLI reads them itself, so
+`node dist/cli.js list CLOUD` works with no arguments. Delete anything you create:
+
+```bash
+node dist/cli.js delete CLOUD-42 --yes
+```
+
+## Releasing
+
+Publishing is irreversible — a version cannot be reused, and a tarball that
+shipped too much stays in every mirror. `node scripts/release.mjs` does
+everything except publish; `--publish` is the only path to `npm publish`. The gate
+empties `dist`, runs the checks, smoke-tests the built command, enforces package
+contents and size, and refuses when the registry cannot be reached.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -0,0 +1,127 @@
+# i-plane
+
+A command-line client for [Plane](https://plane.so) that prints lines instead of
+JSON dumps.
+
+Ask Plane's API for seven work items and it answers with twenty-nine fields
+each — about 6,500 tokens. The same seven through `i-plane` are 145. If you are
+piping work items into a coding agent, that difference is the entire point.
+
+```
+$ i-plane list CLOUD --state started
+CLOUD-4  Create and assign work items [high] (In Progress)
+CLOUD-5  Visualize your work (In Progress)
+```
+
+## Install
+
+```bash
+npm install -g i-plane
+```
+
+Node 20 or newer.
+
+## Set it up
+
+You need three things: the address of your Plane, an API key, and a workspace.
+The key comes from **Workspace settings → API tokens**.
+
+Supply them however suits you — flags win over environment, environment wins over
+the file:
+
+```bash
+# once, in a file
+mkdir -p ~/.config/plane && chmod 700 ~/.config/plane
+cat > ~/.config/plane/credentials <<'EOF'
+PLANE_URL=https://plane.example.com
+PLANE_API_KEY=plane_api_…
+PLANE_WORKSPACE=my-workspace
+EOF
+chmod 600 ~/.config/plane/credentials
+
+# or per call
+i-plane list CLOUD --url https://plane.example.com --token … --workspace my-workspace
+```
+
+Not sure what is in effect:
+
+```
+$ i-plane config
+url        https://plane.example.com  (file)
+workspace  my-workspace  (env)
+token      plane_…856f  (file)
+file       /home/you/.config/plane/credentials
+```
+
+## Use it
+
+Run `i-plane` with no arguments and it shows the command map, the usual order of
+work, and how it behaves. `i-plane <command> --help` gives one command's flags
+and real examples.
+
+```
+summary               projects and how much is in each
+list [project]        work items, one line each    --state --priority --limit
+show <ID>             one work item, description included
+search <text>         across the whole workspace
+create <title>        --project --priority --state --description
+update <ID>           --state --priority --name --description
+done <ID>             move to the first completed state
+comment <ID> <text>   add a comment
+delete <ID> --yes     delete; refuses without --yes
+projects  states  labels  members  whoami  config  guide
+```
+
+Short forms for what fingers type: `ls`, `new`, `set`, `rm`, `find`.
+
+Work items go by the name people say — `CLOUD-8`. Projects take an identifier
+(`CLOUD`), a full name, or a unique prefix of one.
+
+Every command accepts `--json` and then prints the whole model, for when you need
+ids and timestamps rather than a readable line.
+
+## Descriptions are Markdown
+
+Write them as Markdown; read them back as Markdown. Plane stores HTML, and the
+translation happens here.
+
+````bash
+i-plane create --project CLOUD "Fix the resolver" --description '## Steps
+
+```bash
+dig +short example.com @127.0.0.1
+```
+
+| Node | Role | Status |
+| ---- | ---- | ------ |
+| pi5  | DNS  | broken |
+
+1. check the cache
+2. check the routes'
+````
+
+Code fences keep their language, tables stay tables, ordered lists stay numbered.
+Raw HTML in a description is escaped rather than passed through, so nothing you
+write can execute in someone else's browser.
+
+## Good to know
+
+**A list is complete unless it says so.** `list` returns every work item in the
+project. `--limit` exists, but when it cuts the list the last line tells you how
+many rows it hid.
+
+**Exit codes mean something.** `2` — the command was wrong. `1` — Plane refused or
+could not be reached. Useful in scripts.
+
+**Proxies work without configuration.** If `HTTPS_PROXY` applies to your Plane
+address, it is used; `NO_PROXY` is honoured the way curl honours it, including
+CIDR ranges. On a network without a proxy none of this runs.
+
+## Contributing
+
+`AGENTS.md` has the working rules: the invariants, the checks to run, and the
+bugs that already shipped once.
+
+## License
+
+MIT