@productlobster/plob 0.1.2 → 0.1.4

package/README.md

@@ -35,13 +35,14 @@ plob --help
 | `plob run-replay <runId> [--from-stage <name>]` | Replay a run, optionally from a given stage. |
 | `plob prototype-list [--cursor <cursor>]` | List prototypes in the workspace. |
 | `plob prototype-pack --prototype-id <id> [--out <dir>]` | Fetch a prototype ZIP reference (extracts when `--out` is set). |
-| `plob document-list [--type <type>] [--run <runId>] [--latest] [--since <iso>] [--limit <n>] [--cursor <cursor>]` | List workspace documents. |
+| `plob document-list [--type <type>] [--run <runId>] [--latest] [--since <iso>] [--limit <n>] [--cursor <cursor>]` | List workspace documents. `--latest` applies only with `--type`. |
 | `plob document-get --document-id <id>` | Read a document. |
 | `plob document-put --document-id <id> --version-token <token> --content <markdown> [--idempotency-key <key>]` | Update a document. |
 | `plob context-pack [--sections <list>] [--limit <n>] [--cursor <cursor>]` | Read accumulated workspace context. |
 | `plob observe --kind <kind> --content <text> [--idempotency-key <key>]` | Record a single observation. |
 | `plob ingest --bundle <path-or-dash> [--content-type <type>] [--source-name <name>] [--idempotency-key <key>]` | Ingest a bundle of notes. |
 | `plob --workspace <workspaceId> upload --file <path>` | Upload a document file to a workspace. |
+| `plob --version` | Print the installed CLI version. |
 
 `plob workspaces` lists the workspace your stored credential can access. The initial credential is workspace-bound, so it returns that single workspace.
 
@@ -76,12 +77,31 @@ Use an explicit idempotency key for a scripted retry:
 plob observe --kind signal --content "Three users asked for CSV export" --idempotency-key "$JOB_ID"
 ```
 
-Fetch and extract a prototype pack:
+Fetch and extract a prototype pack into a new directory:
 
 ```bash
 plob prototype-pack --prototype-id proto_123 --out ./proto
 ```
 
+The output directory must not already exist, and its parent must exist. Choose a
+new name for each extraction; existing files, empty directories, and symlink
+output roots are rejected without being changed. The CLI does not merge or
+overwrite an earlier extraction. Parent path aliases are resolved to their
+canonical location, which is returned as `extraction.outDir`. Create missing
+parent directories yourself before running the command.
+
+Extraction creates a fresh tree, uses exclusive file creation, and removes that
+new tree if extraction fails. Unsafe archive paths and colliding filenames are
+rejected, including case or Unicode aliases recognized by the host filesystem.
+Directory-entry paths are validated, but empty directories are not extracted;
+parent directories are created as needed for files. Inconsistent ZIP directory
+counts, payload ranges, and decoded sizes are rejected. On POSIX the new
+directories and files use permissions 0700 and 0600; Windows inherits the
+caller's filesystem permissions. Use a trusted, stable parent directory on a
+local filesystem: this does not defend against another process replacing parent
+directories during extraction, and exclusive creation may not be reliable on
+every network filesystem.
+
 `plob upload` attaches one file to the selected workspace. Use the workspace `id` from `plob workspaces`, not the display name. The connection must include the `write:upload` scope. Supported extensions: `.pdf`, `.docx`, `.txt`, `.md`, `.markdown`, `.png`, `.jpg`, `.jpeg`, and `.webp`; files must be non-empty and at most 10 MB.
 
 ```bash
@@ -102,6 +122,8 @@ https://app.productlobster.ai/settings/connections
 
 Create an API key in the hosted app, then paste the one-time `ak_` key into the CLI prompt. The key is stored only in the OS keychain through `@napi-rs/keyring`; it is never written to a plaintext config file and is never printed by the CLI.
 
+Where there is no OS keychain (headless Linux, CI runners, containers, cloud agent sandboxes), skip `login` and set `PRODUCTLOBSTER_API_KEY` instead; see [Credentials](#credentials).
+
 Automation-safe login reads the key from stdin and does not open a browser:
 
 ```bash
@@ -132,13 +154,15 @@ In `--json` mode, stdout contains exactly one JSON document for both success and
 
 ## Debugging
 
-Use `--debug` to print request IDs to stderr when the server returns one:
+Use `--debug` to print request IDs to stderr when the server returns one, the credential source (`keychain` or `PRODUCTLOBSTER_API_KEY`, never the key), and the HTTP status and response body or local error behind a failure:
 
 ```bash
 plob --debug --json workspaces
 ```
 
-The CLI ships no client-side telemetry. Server-side request IDs are the support join key.
+Anything shaped like an API key is redacted to `ak_[redacted]` in those diagnostics. The CLI ships no client-side telemetry. Server-side request IDs are the support join key.
+
+`plob --version` prints the bare version; with `--json` (or piped stdout) it writes `{"data":{"version":"<version>"},"schemaVersion":1}`.
 
 ## Exit Codes
 
@@ -156,21 +180,33 @@ The CLI ships no client-side telemetry. Server-side request IDs are the support
 | 16 | Rate limited |
 | 17 | CLI version revoked; upgrade before retrying |
 | 18 | Backend temporarily unavailable; retry shortly |
+| 19 | Included outcomes used; the account is read-only for agents |
 | 70 | Network or transport failure |
 
 When the server reports a version is no longer supported, the CLI exits 17 and prints the npm upgrade command from the structured error details. In `--json` mode, the same detail is emitted in the single JSON error document.
 
+An HTTP-level refusal (rate limit, Terms re-acceptance, a rejected key) carries the server's own error document, so the CLI reports that code and message. A response that is not a ProductLobster error document reports its HTTP status in `details.httpStatus`, plus its `requestId` when the body is JSON that carries one: 401 maps to `unauthorized`, 429 to `rate_limited` (exit `16`), and any 5xx (including Cloudflare's own origin-error pages) to `service_unavailable` (exit `18`). A network-edge challenge or block page reports `details.reason: "edge_challenge"`. `plob upload` and the `prototype-pack --out` download apply the same mapping. If the response body cannot be read (the connection closed mid-body), the status alone decides the code. With `--debug`, the CLI also writes the HTTP status and the start of the response body, or the local error, to stderr, with anything shaped like an API key redacted. A `requestId` is kept only when it is id-shaped (letters, digits, `.`, `_`, `:`, `-`; at most 128 characters) and not shaped like an API key.
+
 ## Credentials
 
-The API key is loaded from the OS keychain through `@napi-rs/keyring`. `plob login` writes the pasted or stdin-provided `ak_` key to the keychain entry, and `plob logout` deletes it. A missing credential returns exit code `10` with a structured unauthorized error.
+Every command except `login` and `logout` takes the API key from, in order:
+
+1. the OS keychain entry `plob login` saved, through `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, or the Linux Secret Service). A stored value that is not a valid `ak_` key is refused (exit `10`; run `plob login` again);
+2. the `PRODUCTLOBSTER_API_KEY` environment variable, only when the keychain holds no key or there is no keychain backend (CI, containers, headless Linux). A value that is not an `ak_` key is refused (exit `10`) rather than ignored.
+
+The keychain wins so that a variable exported for another tool or workspace never silently replaces the key you logged in with. `--debug` names which source a command used.
+
+`plob login` writes the pasted or stdin-provided `ak_` key to the keychain entry, and `plob logout` deletes it; neither reads or changes the environment variable, and `logout` notes on stderr when the variable is still set, since plob falls back to it once no keychain key is stored. A missing credential returns exit code `10` with a structured unauthorized error. When the keychain itself is unavailable (no Secret Service on a headless Linux host, for example), the error carries `details.reason: "keychain_unavailable"` and names the environment variable. The environment variable is visible to the process and anything it starts; prefer the keychain on a workstation.
 
 Default keychain entry:
 
 | Field | Value |
 | --- | --- |
-| Service | `productlobster.pl-cli` |
+| Service | `productlobster.plob-cli` |
 | Account | `default` |
 
+Versions 0.1.3 and earlier stored the key under the service `productlobster.pl-cli`. The CLI still reads that entry when the new one is empty, so an upgrade keeps working without a new login; reading never writes the keychain. `plob login` saves to the new entry and removes the old one, and `plob logout` removes both. Because a 0.1.4 `login` removes the legacy entry, going back to 0.1.3 afterwards needs a fresh `plob login`.
+
 ## Endpoint
 
 The default endpoint is:
@@ -182,10 +218,12 @@ https://app.productlobster.ai/api/mcp
 For local development, set:
 
 ```bash
-PL_MCP_URL=http://localhost:3000/api/mcp
+PLOB_MCP_URL=http://localhost:3000/api/mcp
 ```
 
-`plob upload` uses the same origin as `PL_MCP_URL`.
+The override must be an `https` URL on `productlobster.ai` (or a subdomain) or a `localhost` URL; any other host is refused (exit `2`) before the API key is sent. `plob upload` and `plob prototype-pack --out` use the same origin.
+
+Versions 0.1.3 and earlier read `PL_MCP_URL`. It still works when `PLOB_MCP_URL` is unset, and plob writes one deprecation note to stderr when it uses it.
 
 ## Dependency Posture