opctl 0.1.5 → 0.1.7

package/README.md

@@ -1,5 +1,7 @@
 # opctl
 
+[![npm version](https://img.shields.io/npm/v/opctl.svg)](https://www.npmjs.com/package/opctl)
+
 `opctl` is a small local Node.js + TypeScript CLI bridge for OpenProject API v3. It uses the current user's personal API token and is read-only by default.
 
 ## Install
@@ -7,7 +9,7 @@
 Published package:
 
 - npmjs.com: `opctl`
-- current package: `opctl@0.1.4`
+- current package: `opctl@0.1.7`
 - binary: `opctl`
 
 Install globally:
@@ -81,15 +83,21 @@ opctl wp get 123 --raw-json
 opctl wp get 123 124 --table
 opctl wp get --ids 123,124 --fields id,subject,status,assignee --table
 opctl wp get --ids 123,124 --jsonl
+opctl wp get --ids 123,124 --raw-json
 ```
 
-Field selection supports `id,subject,status,type,assignee,project,href,updatedAt,description,shortDescription,attachmentsCount,lockVersion`; aliases: `title=subject`, `url=href`.
+`--raw-json` emits a single raw OpenProject object for one ID and JSONL for multiple IDs.
+
+Field selection supports `id,subject,status,type,assignee,responsible,project,href,browserUrl,updatedAt,description,shortDescription,attachmentsCount,lockVersion,priority`; aliases: `title=subject`, `url=href`.
 
 Search work packages:
 
 ```sh
 opctl wp search --project my-project --subject "pump"
 opctl wp search --project my-project --assignee-me --status open
+opctl wp search --responsible-me --open
+opctl wp search --responsible 18 --not-status "In Client Review"
+opctl wp search --filter responsible=me --filter status=o --sort updated_at:desc
 opctl wp search --open --subject "pump" --compact
 opctl wp search --subject "pump" --fields id,subject,status --json
 
@@ -97,6 +105,15 @@ opctl wp search --subject "pump" --fields id,subject,status --json
 
 If `--project` is omitted, `opctl wp search` uses `OPENPROJECT_DEFAULT_PROJECT` when set. Without either, it searches the instance-wide work package endpoint.
 
+Lookup work package types, statuses, and priorities:
+
+```sh
+opctl types --project my-project
+opctl types --json
+opctl statuses
+opctl priorities
+```
+
 List work packages assigned to the authenticated user:
 
 ```sh
@@ -105,6 +122,13 @@ opctl wp mine --open --table
 opctl wp mine --project my-project --page-size 50 --fields id,subject,status,updatedAt
 ```
 
+List open work packages accountable/responsible to the authenticated user:
+
+```sh
+opctl wp accountable
+opctl wp accountable --table --fields id,subject,status,responsible,updatedAt
+```
+
 Triage a known list:
 
 ```sh
@@ -112,30 +136,70 @@ opctl wp check 123 124
 opctl wp check --ids 123,124 --fields id,title,status,assignee,shortDescription,attachmentsCount --table
 ```
 
-Pull the OpenAPI spec from your configured instance:
+Inspect and download work package attachments:
+
+```sh
+opctl wp attachments 123
+opctl wp attachments 123 --json
+opctl wp download-attachments 123 --dir /tmp/op-attachments
+opctl wp download-attachments 123 --dir /tmp/op-attachments --overwrite --json
+```
+
+Show redacted diagnostics:
+
+```sh
+opctl doctor
+opctl doctor --json
+```
+
+Pull the OpenAPI spec (defaults to the public community instance):
 
 ```sh
 opctl spec pull
+opctl spec pull --output openapi/my-spec.json
+opctl spec pull --url https://openproject.example.com
 ```
 
-Write-capable command:
+Write-capable commands:
 
 ```sh
+# Comment on a work package
 OPENPROJECT_ALLOW_WRITE=1 opctl wp comment 123 --dry-run "Investigating"
 OPENPROJECT_ALLOW_WRITE=1 opctl wp comment 123 "Investigating"
+
+# Create a work package (dry-run validates through /api/v3/work_packages/form)
+OPENPROJECT_ALLOW_WRITE=1 opctl wp create --project alspc --type Feature --subject "Improve Ask NAVLIN Explore messaging experience" --description-file ticket.md --dry-run
+OPENPROJECT_ALLOW_WRITE=1 opctl wp create --project alspc --type Feature --subject "S" --json < ticket.md
+
+# Use a user-story template
+opctl wp create --template user-story > ticket.md
+OPENPROJECT_ALLOW_WRITE=1 opctl wp create --project alspc --type Feature --subject "New feature" --template user-story --dry-run
 ```
 
-`wp comment` fetches the work package first and posts only when a documented HAL comment action link is present. It fails safely instead of guessing a mutation URL.
+`wp comment` and `wp create` both require `OPENPROJECT_ALLOW_WRITE=1`. `wp create --dry-run` validates through `/api/v3/work_packages/form` before any create call. Write-capable commands support `--dry-run` and avoid mutation in dry-run mode.
+
+`wp create` resolves `--type`, `--status`, and `--priority` by name (case-insensitive exact match), numeric id, or full `/api/v3/...` href. Use `opctl types`, `opctl statuses`, or `opctl priorities` to list valid values. Description can come from `--description <text>`, `--description-file <path>` (use `-` for stdin), piped stdin, or `--template user-story`.
 
 ## OpenAPI
 
-The repository commits `openapi/openproject.json` and generated types in `src/generated/openproject.ts`. The committed spec is an auditable public OpenProject baseline; users should refresh it against their own instance when local API shape matters.
+The repository commits `openapi/openproject.json` and generated types in `src/generated/openproject.ts`. The committed spec is an auditable public OpenProject baseline.
+
+`npm run openapi:pull` and `opctl spec pull` default to the official public spec at `https://community.openproject.org`. They do **not** read `OPENPROJECT_URL` or `OPENPROJECT_TOKEN`, so running tests or pulling the spec never sends credentials to a private instance.
 
 ```sh
-OPENPROJECT_URL=https://openproject.example.com OPENPROJECT_TOKEN=... npm run openapi:update
+# Refresh from the public community spec (safe, no credentials needed)
+npm run openapi:update
+
+# Pull from a specific private instance (explicit opt-in)
+OPENPROJECT_SPEC_URL=https://openproject.example.com \
+OPENPROJECT_SPEC_TOKEN=... \
+  npm run openapi:pull
+
+# Or via the CLI
+opctl spec pull --url https://openproject.example.com
 ```
 
-`npm run openapi:pull` downloads only `/api/v3/spec.json`, uses a timeout, and prints only host, output path, title, and version. It never prints the token or authorization header.
+Private-instance pulls use dedicated `OPENPROJECT_SPEC_URL` / `OPENPROJECT_SPEC_TOKEN` / `OPENPROJECT_SPEC_AUTH_MODE` variables. Normal `OPENPROJECT_URL` and `OPENPROJECT_TOKEN` are never used for spec pulling.
 
 ## Build and verification
 
@@ -150,6 +214,7 @@ node dist/cli.js wp --help
 ## Safety model
 
 - No token or `Authorization` header is printed by normal errors, JSON output, spec pulling, or tests.
+- Spec pulling defaults to the public community spec and ignores `OPENPROJECT_URL` / `OPENPROJECT_TOKEN`; private-instance pulls require explicit `--url` or `OPENPROJECT_SPEC_URL`.
 - Local `.env` files are loaded for read configuration by default; `--no-env` disables that, and `.env` cannot enable writes.
 - OpenProject writes are blocked unless the real process environment contains `OPENPROJECT_ALLOW_WRITE=1` exactly.
 - Every write-capable command supports `--dry-run` and avoids mutation in dry-run mode.