@kanera/cli 1.5.0

package/README.md

@@ -0,0 +1,132 @@
+# `kanera` CLI
+
+Manage Kanera work from a terminal, or from any AI agent that can run shell commands.
+
+## Install
+
+Requires Node 22 or newer. The package has no dependencies.
+
+```bash
+npm install --global @kanera/cli
+```
+
+## Authenticate
+
+You need a Kanera API key. Create one in the Kanera web app under **Settings → API keys**
+(personal keys, scoped read-only or read-write), or in **workspace settings** for a key tied to a
+workspace rather than a person. Choose **read-only** if the credential is for an AI agent that
+should not change anything.
+
+```bash
+kanera auth login        # opens the API-keys page, then prompts for the key and stores it
+kanera whoami            # who am I, and what may this credential do?
+```
+
+In CI or an agent sandbox, skip the stored profile and set `KANERA_API_KEY` instead. Self-hosting?
+Point at your deployment with `--url https://api.your-kanera.example` during login (it is saved
+with the profile) or via `KANERA_PUBLIC_API_URL`.
+
+## Use
+
+```bash
+kanera commands          # everything this CLI can do (works before login)
+kanera work              # your assignments across every accessible board
+kanera card MKT-42       # a card, by key, id, or URL
+kanera card done MKT-42  # mark it complete
+kanera comment MKT-42 "Shipped."
+kanera doctor            # diagnose credentials and connectivity
+```
+
+## How it is built
+
+The CLI does not re-implement the public API. It opens an **in-process MCP session** against the
+same tool layer `@kanera/mcp` serves over HTTP and stdio, then exposes those tools as commands.
+Nothing crosses a socket — `InMemoryTransport` links the two ends directly.
+
+That choice is the point: card-reference resolution (`MKT-42`), cursor encoding, response size
+caps, and every tool description already live in that layer, so the CLI's command surface cannot
+drift from what agents see over MCP, and a newly added tool is callable from the shell the day it
+ships.
+
+- `src/aliases.ts` gives the high-traffic tools ergonomic names (`kanera card done MKT-42`). It is
+  a convenience layer, not the surface; a test asserts every alias targets a real tool and only
+  maps arguments that tool accepts.
+- `kanera call <tool>` reaches anything the alias table does not cover.
+- `kanera commands --json` is the machine-readable catalog agents use to discover the rest.
+
+## Credentials
+
+Resolution order: `--api-key`, then `KANERA_API_KEY`, then a stored profile.
+
+Profiles live in `~/.config/kanera/config.json` (mode `600`). Named profiles let one machine hold
+several identities:
+
+```bash
+kanera auth login --profile agent --api-key kanera_u_…
+kanera --profile agent work --json
+```
+
+The non-secret, committable per-repo profile selection goes in `.kanera/config.json`:
+
+```json
+{ "profile": "agent" }
+```
+
+API origins are security-sensitive because they receive the bearer credential, so repository
+configuration cannot set one. Use `--url`, `KANERA_PUBLIC_API_URL`, or the origin saved with a
+profile during `auth login`. Non-loopback origins must use HTTPS.
+
+## Output
+
+| Flag | Output |
+| ---- | ------ |
+| *(none)* | Human-readable tables and summaries |
+| `--json` | `{ ok, tool, data }` envelope |
+| `--quiet` | The bare result, for `jq` |
+
+Failures always go to **stderr**, so redirecting stdout to a file never mixes an error envelope
+into what the caller believes is result data.
+
+Rate-limit and transient API failures include `retryable` and, when supplied by the server,
+`retryAfter` fields in structured output.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | success |
+| 1 | the request failed |
+| 2 | bad usage |
+| 3 | no valid credential |
+| 4 | forbidden — often a read-only credential |
+| 5 | not found |
+| 6 | rate limited |
+
+`4` is deliberately distinct from `1`: an agent holding a read-scoped key needs to tell "I may not
+do this" apart from "this did not work", and stop rather than retry.
+
+## Arguments
+
+Flags map onto tool arguments and are coerced using the tool's own JSON Schema, never by how the
+value looks — a card key can look numeric and an id can look boolean.
+
+Unknown flags, missing required arguments, malformed `--json-args`, and surplus positionals are
+usage errors. The CLI never silently discards an operand.
+
+```bash
+kanera card update MKT-42 --changes.title "Revised"     # dots nest
+kanera work --scope.boardIds[] abc --scope.boardIds[] def   # repeat or [] for arrays
+kanera call kanera_update_card --json-args '{"cardId":"MKT-42","changes":{"title":"Revised"}}'
+```
+
+## Agent setup
+
+```bash
+kanera setup claude     # writes .claude/skills/kanera/SKILL.md
+kanera setup codex      # appends Kanera instructions to AGENTS.md
+kanera skill            # print the portable Agent Skill document for another harness
+kanera mcp              # serve the same tools over stdio MCP, using the stored credential
+```
+
+`kanera mcp` means a user who has already run `kanera auth login` does not configure a second
+credential in a second place to use Kanera from an MCP client.

package/dist/LICENSE

@@ -0,0 +1,94 @@
+# Elastic License 2.0 (ELv2)
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+Hosted mode, hosted billing, hosted entitlements, and any checks controlling
+access to them are license key functionality for purposes of this license.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.