@klok-integration/cli 0.2.0

package/LICENSE.md

@@ -0,0 +1,74 @@
+# Klok CLI End User Licence Agreement
+
+Version 1.0
+
+This agreement is between you ("you") and Klok ("Klok") and governs your use of the Klok CLI,
+distributed on the public npm registry as `@klok-integration/cli` (the "Software"). By installing or
+using the Software you accept these terms. If you do not accept them, do not install or use the
+Software.
+
+## 1. Licence grant
+
+Klok grants you a non-exclusive, non-transferable, revocable, worldwide licence to install and run the
+Software on any number of machines you control, for the purpose of using the Klok integration platform
+and services. The licence is granted free of charge and for as long as these terms are observed.
+
+## 2. Ownership
+
+The Software is licensed, not sold. Klok retains all right, title and interest in the Software,
+including all intellectual property rights. The Software is proprietary and is not open source. No
+rights are granted other than those expressly stated in this agreement.
+
+## 3. Restrictions
+
+You may not:
+
+a. redistribute, sublicense, sell, rent, lease or host the Software for third parties;
+b. modify the Software, or create derivative works from it;
+c. decompile, disassemble, deobfuscate or otherwise attempt to reconstruct the source code of the
+   Software, except to the extent that this restriction is prohibited by applicable law;
+d. remove or obscure any proprietary notice contained in the Software; or
+e. use the Software to build a product or service that competes with the Klok platform.
+
+Nothing in section 3(c) limits the rights you have under Article 6 of Directive 2009/24/EC on the legal
+protection of computer programs, or under any other mandatory provision of applicable law.
+
+## 4. Instruction assets
+
+The Software installs instruction and skill files intended to be read and used by AI coding agents in
+your own repositories. You may use, adapt and keep those files in your repositories for your own
+development work. Section 3 otherwise continues to apply to them.
+
+## 5. Third party components
+
+The Software includes open source components that are licensed under their own terms. Those terms are
+reproduced in `THIRD-PARTY-NOTICES.md` in this package, and they prevail over this agreement in respect
+of the components they cover.
+
+## 6. Services and data
+
+The Software is a client for Klok services. Use of those services is governed by the separate agreement
+between Klok and the organisation whose account you authenticate with. The Software stores credentials
+locally on the machine it runs on.
+
+## 7. No warranty
+
+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 NON-INFRINGEMENT.
+
+## 8. Limitation of liability
+
+TO THE EXTENT PERMITTED BY LAW, KLOK SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL OR
+CONSEQUENTIAL DAMAGES, OR FOR LOSS OF PROFITS, REVENUE OR DATA, ARISING OUT OF OR IN CONNECTION WITH THE
+SOFTWARE. Nothing in this agreement excludes liability that cannot be excluded by law.
+
+## 9. Term and termination
+
+This licence terminates automatically if you breach it. On termination you must stop using the Software
+and remove it from your machines.
+
+## 10. Governing law
+
+This agreement is governed by the laws of Sweden, and disputes shall be settled by the courts of Sweden.
+
+Contact: https://klok.dev

package/README.md

@@ -0,0 +1,106 @@
+# klok
+
+The command line client for the [Klok integration platform](https://klok.dev). It runs tasks on your
+tenant's Klok agent, publishes documentation, keeps your workspace in sync, and exposes the platform to
+your IDE and coding agents over MCP and A2A.
+
+```sh
+npm install -g @klok-integration/cli
+klok --help
+```
+
+Node 22.14 or newer. The package has no dependencies and runs no install scripts.
+
+## First run
+
+```sh
+klok config set agentUrl https://agent.klok.dev
+klok login                     # device flow; add --browser for the browser flow
+klok whoami
+klok                           # opens the terminal UI
+```
+
+Configuration lives in `~/.config/klok/config.json`. Every value can be overridden by an environment
+variable: `KLOK_AGENT_URL`, `KLOK_TENANT`, `KLOK_DOMAIN`, `KLOK_DEV_URL`, `KLOK_KEYCLOAK_ISSUER`,
+`KLOK_KEYCLOAK_CLIENT_ID`, `KLOK_GIT_URL`, `KLOK_GIT_LOCAL_WORKSPACE`. Run `klok config list` to see
+what is set and where it comes from.
+
+Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `klok` | Terminal UI. `j`/`k` or arrows move, `enter` opens a task, `a` asks a question, `b` shows beads, `r` refreshes, `q` quits. |
+| `klok login`, `klok logout`, `klok whoami` | Session against your tenant's identity provider. |
+| `klok config list\|get\|set\|delete` | Configuration. |
+| `klok agent ask "<question>"` | Ask a question about the integration landscape and get a cited answer. |
+| `klok agent impact <nodeId\|datamodel> --change minor\|major\|remove` | Impact analysis. |
+| `klok agent plan <solutionKey> --change-request <file\|->` | Integration plan following the Klok process. |
+| `klok agent tasks`, `klok agent open <taskId>`, `klok agent cancel <taskId>` | Work with tasks. |
+| `klok agent answer <taskId> --question <qid> --text "..."` | Answer a clarification and continue. |
+| `klok agent serve [--port 3091]` | Loopback MCP and A2A proxy for IDEs and other agents. |
+| `klok agents init` | Write the Klok agent instructions and skills into a repository. |
+| `klok bead list\|show\|report` | Progress beads in the current repository. |
+| `klok docs publish` | Build this repository's znai documentation and upload it to the docs portal. |
+| `klok sync clone\|pull\|status` | Clone and refresh every repository you can see, in one workspace folder. |
+
+Global flags: `--json`, `--no-tui`, `--stream`, `--tenant <slug>`, `--domain <slug>`,
+`--agent-url <url>`.
+
+## Scripting
+
+`klok` prints a terminal UI when stdout is a terminal, and a single JSON document otherwise, so it works
+unchanged in a shell pipeline or a CI job.
+
+```sh
+klok agent ask "which routes consume CustomerV1?" --json | jq -r '.result.answer'
+klok agent plan KLK002 --change-request ./change.md --stream    # NDJSON events, then the result
+```
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | ok |
+| 1 | error |
+| 2 | the task needs input; the document carries `details.questionId` and `details.question` |
+| 3 | denied by policy; `details.decisions` lists capability, decision and reason |
+| 4 | not authenticated; run `klok login` |
+
+## Use it from your IDE and coding agents
+
+```sh
+klok agent serve            # 127.0.0.1:3091
+```
+
+- `http://127.0.0.1:3091/mcp` — MCP over streamable HTTP, with tools for context search, impact
+  analysis, planning, issues, beads and task control. Long tasks send progress notifications.
+- `http://127.0.0.1:3091/a2a` — Agent2Agent JSON-RPC proxied to your tenant's cloud agent with your
+  identity.
+- `http://127.0.0.1:3091/.well-known/agent-card.json` — the agent card.
+
+```sh
+claude mcp add klok --transport http http://127.0.0.1:3091/mcp
+codex mcp add klok --url http://127.0.0.1:3091/mcp
+```
+
+Cursor (`.cursor/mcp.json`):
+
+```json
+{ "mcpServers": { "klok": { "url": "http://127.0.0.1:3091/mcp" } } }
+```
+
+## Agent instructions
+
+`klok agents init` writes `KLOK-AGENTS.md` with the rules, one managed row in every harness file
+(`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.clinerules`,
+`.github/copilot-instructions.md`), the klok named rule files (`.cursor/rules`, `.agents/rules`) and the
+Klok skills. `KLOK-AGENTS.md`, the klok rule files and the `klok-*` skills belong to Klok and are
+replaced wholesale; every other file keeps its content and only has its single row created or replaced,
+so an update can never duplicate text. Klok skills the CLI no longer ships are removed.
+`klok agents status` shows whether a repository is up to date with the CLI version you have installed.
+
+## Licence and support
+
+Proprietary. See `LICENSE.md` in this package; third party notices are in `THIRD-PARTY-NOTICES.md`.
+
+Documentation: https://docs.klok.dev — support: https://klok.dev/support