@allocator-one/harness-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 allocator.one
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @allocator-one/harness-cli
+
+CLI and MCP server for [Harness](https://harness.infra.one), allocator.one's
+issue tracker. A standalone Node client — no backend checkout, no Erlang
+toolchain — that shares credentials with the Elixir escript (`bin/harness`
+in the `allocator-one` repo).
+
+## Install
+
+Zero-install, always current:
+
+```sh
+npx -y @allocator-one/harness-cli list --team ALL
+```
+
+Or globally:
+
+```sh
+npm i -g @allocator-one/harness-cli
+harness ready
+```
+
+Requires Node >= 20.
+
+## Auth
+
+No setup needed: commands target `https://harness.infra.one` and start the
+browser login the first time. One login covers every shell, worktree, and
+agent slot on a machine — credentials are stored at
+`~/.config/harness/credentials.json` (0600), byte-compatible with the
+escript's, so either client can log in or out without breaking the other.
+
+- `harness login` — browser flow (PKCE loopback); `--no-browser` prints the
+  URL and prompts for a pasted token instead.
+- `harness logout` — revokes the stored login server-side and deletes the file.
+- `harness whoami` — shows the resolved host and credential source.
+
+Headless contexts (agents, CI): mint an `aone_…` API token (admin → API
+tokens) and set `HARNESS_API_TOKEN`. Do not set it in interactive sessions —
+the browser login attributes writes to the real user.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `HARNESS_API_URL` | Target host (default `https://harness.infra.one`). https only, plain http allowed against localhost. |
+| `HARNESS_API_TOKEN` | Bearer token (`aone_…`); wins over the stored login. Never inherits the stored login's host. |
+| `HARNESS_TEAM` | Default team key for commands that take `--team`. |
+| `HARNESS_ACTOR` | Write attribution, sent only when explicitly set. |
+| `HARNESS_CACHE_DIR` | Where `show` downloads attached images (default `$XDG_CACHE_HOME/harness/attachments` or `~/.cache/harness/attachments`). Absolute paths only. |
+
+## For agents
+
+`harness mcp` runs a stdio MCP server exposing every operation as a typed
+tool — issue_list, issue_show, issue_create, issue_update, issue_claim,
+issue_close, issue_comment, relation_add/rm, link_list/add/rm,
+project_list/show/create/update, milestone_list/create,
+document_list/show/create/update, label_list/create, team_list,
+workflow_states, user_list, stats, upload. Read-only tools carry
+`readOnlyHint`. Results are compact JSON of the data envelope.
+
+Register it with Claude Code:
+
+```sh
+claude mcp add --scope user harness -- npx -y @allocator-one/harness-cli mcp
+```
+
+Example tool call: `issue_list` with `{"ready": true, "team": "ALL"}`
+returns the ready queue as JSON; `issue_claim` with `{"id": "IO-123"}`
+claims atomically (a conflict means someone else holds it).
+
+Auth resolution is identical to the CLI. Without a credential, tools return
+an error telling the agent to run `harness login` in a terminal — the
+server never opens a browser itself.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build          # bundles to dist/cli.js (tsup)
+node dist/cli.js version
+```
+
+The OpenAPI spec is vendored at `spec/openapi.json` and TypeScript types are
+generated into `src/generated/` (committed, so npx consumers never run
+codegen):
+
+```sh
+npm run spec:refresh   # fetch the spec from a live host (uses your login)
+npm run codegen        # regenerate src/generated/api.ts from the vendored spec
+```
+
+CI regenerates the types and fails on drift.
+
+## Release
+
+Tag a version and push — the Release workflow builds and publishes to npm:
+
+```sh
+git tag v1.0.0 && git push origin v1.0.0
+```
+
+Publishing requires the `NPM_TOKEN` actions secret (an automation token for
+the `allocator-one` npm org). Provenance attestation is disabled: npm only
+accepts it from public source repositories, and this repo is private — turn
+`--provenance` back on in `release.yml` if the repo ever goes public.