@datagusto/cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 datagusto
+
+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

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# @datagusto/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `dg` command (also installed as `datagusto`) connects a coding agent to Datagusto with one command. See [ADR-0003](../ADR-0003-agent-setup-cli.md) for the design.
+
+> **Status: Phase 2.** `claude-code` and `kiro` work end to end (Kiro on the Kiro CLI; the Kiro IDE is not verified). `codex` is accepted by the argument parser but reports "not supported yet".
+
+```sh
+dg setup <claude-code|kiro|codex> [--server-url <url>] [--workspace <dir>]
+dg status
+dg remove <claude-code|kiro|codex> [--workspace <dir>]
+```
+
+## Connect Claude Code
+
+```sh
+npm install -g @datagusto/cli
+dg setup claude-code --server-url https://datagusto.your-company.example      # prompts for the key (hidden)
+```
+
+`--server-url` is the address of your company's Datagusto server. There is no shared Datagusto server and so no default: the first setup needs the flag. A re-run without it keeps the URL that is already installed.
+
+`dg setup claude-code`:
+
+1. checks that Claude Code is installed (`claude` on `PATH`, or a `~/.claude` folder)
+2. reads the agent API key (see below) and checks it with `GET /api/v1/public/safety/whoami`. A bad key or URL stops here and nothing is written
+3. copies the bundled plugin to `~/.datagusto/claude-code/` and writes `claude-code.json` (server URL + key, mode `0600`) inside it
+4. adds the plugin's hooks to `~/.claude/settings.json`, pointing at that folder. Nothing else in the file is changed
+5. records the install in `~/.datagusto/installs.json` (paths and agent id, never the key)
+
+Running it again is safe. It replaces the plugin files with the bundled version and updates the key and URL, keeping any other options you added to `claude-code.json` (such as `"verbose": true`).
+
+New Claude Code sessions run the hooks automatically. Sessions that are already open usually pick up the `settings.json` change on their own; restart them to be sure.
+
+`dg status` checks every install: Claude Code version, plugin files against the hashes recorded at install time, the hooks in `settings.json`, config file permissions, and a live whoami call with the stored key. It exits `1` if any check fails.
+
+`dg remove claude-code` takes dg's entries out of `settings.json`, deletes the plugin folder and drops the ledger entry. It works offline. The key keeps working until you revoke it in the dashboard, and `dg remove` says so.
+
+### How the plugin is wired in, and why
+
+| Option | Loads every session | Works on every Claude Code version | Used |
+|---|---|---|---|
+| Hook entries merged into `~/.claude/settings.json` | Yes | Yes (any version with hooks) | **Yes** |
+| `~/.claude/skills/<dir>/` with `.claude-plugin/plugin.json` | Yes | No: 2.1.157 or later only | No |
+| `claude --plugin-dir` / `CLAUDE_CODE_PLUGIN_DIRS` | No: one session, or needs a shell-profile edit | Yes | No (still fine for plugin development) |
+| Marketplace + `/plugin install` | Yes | Yes | No: marketplaces are out of scope (ADR-0003) |
+
+One method for every version keeps setup, status and remove simple. The skills folder was tried first and dropped: it only works on newer Claude Code, so it needed `settings.json` as a second method anyway, plus logic to switch between them. It is also a confusing home for something that isn't a skill.
+
+The hook commands are the ones in the plugin's `hooks/hooks.json`, with `${CLAUDE_PLUGIN_ROOT}` replaced by the absolute folder: `node "/Users/you/.datagusto/claude-code/dist/index.js"`. The plugin's `loadConfig()` reads `claude-code.json` from its own folder, so the plugin runtime needed no change. The folder lives outside `~/.claude` so that no Claude Code version also loads it as a plugin, which would run every hook twice.
+
+Confirmed on Claude Code 2.1.202 in a throwaway HOME: a session started there made the plugin's session-start and prompt calls to the server.
+
+How dg treats `settings.json` (ADR-0003 TR-5: only add or remove our own entries):
+
+- **Only known events are written.** Before 2.1.122, one bad hooks entry could invalidate the whole settings file, so each event is written only if the installed version has it: `PreToolUse`/`PostToolUse` 1.0.38, `UserPromptSubmit` 1.0.54, `SessionStart` 1.0.62, `SessionEnd` 1.0.85, `PermissionRequest` 2.0.45, `PostToolUseFailure` 2.1.119 (its first changelog mention). Setup refuses Claude Code older than 1.0.62. If `claude --version` can't be run, setup assumes a current version and writes all seven.
+- **A file that isn't valid JSON is never rewritten.** Setup stops and asks the user to fix it.
+- **Only dg's entries change.** Entries are recognised by their command pointing into `~/.datagusto/claude-code/`. The user's other hooks and settings are written back as read, though the file is re-indented with 2 spaces.
+- **Symlinks survive.** A symlinked `settings.json` (dotfile managers) is written through to its target, and the file keeps its mode.
+- **Upgrades are picked up on a re-run.** After a Claude Code upgrade, `dg status` says which newer events are missing, and `dg setup claude-code` adds them.
+
+Things to know:
+
+- Loading the plugin with `--plugin-dir` as well (plugin development) runs every hook twice. Run `dg remove claude-code` first.
+- `.datagusto-install.json` inside the folder marks it as dg's. `dg setup` refuses to overwrite a `~/.datagusto/claude-code` folder without it, and `dg remove` won't delete one.
+- An earlier build of dg installed to `~/.claude/skills/datagusto-safety/`. Setup removes that copy if it carries dg's marker, and keeps its options.
+- If setup created `~/.claude/settings.json`, `dg remove` leaves it behind as `{}`.
+- The version floors come from Claude Code's `CHANGELOG.md`. Versions older than 2.1.202 are tested with a fake `claude --version`, not a real old install.
+
+## Connect Kiro
+
+Kiro hooks are per workspace, so the plugin is installed into one workspace at a time. `--workspace` defaults to the current directory.
+
+```sh
+cd ~/code/my-repo
+dg setup kiro --server-url https://datagusto.your-company.example      # prompts for the key (hidden)
+```
+
+`dg setup kiro`:
+
+1. checks that the workspace is a folder and that the Kiro CLI is installed (`kiro-cli` on `PATH`). If it isn't, setup stops and prints the install command (`curl -fsSL https://cli.kiro.dev/install | bash`, `brew install --cask kiro-cli` on macOS, or the Windows installer from kiro.dev). The Kiro IDE on its own is not enough
+2. stops, before asking for the key, if the workspace already has a file at one of the paths below that dg didn't put there (most often the project's own `dist/index.js`)
+3. reads the agent API key (see below) and checks it with whoami, exactly as for Claude Code. `--server-url` is the same flag
+4. copies the bundled plugin to `<workspace>/dist/`, writes `<workspace>/kiro.json` (server URL + key, mode `0600`), and copies the five hook files to `<workspace>/.kiro/hooks/datagusto-*.json`
+5. writes `<workspace>/.kiro/agents/kiro_default.json`, a default agent carrying the same five hooks, or merges those hooks into the file if the workspace already has one
+6. records the install in `~/.datagusto/installs.json`, one entry per workspace
+
+Then start `kiro-cli` in that folder. Running setup again is safe: it replaces the plugin and hook files with the bundled version and updates the key and URL, keeping any other options in `kiro.json`.
+
+Kiro CLI 2.x has engines that read hooks from different places, which is why there are two sets. `kiro-cli --v3` reads the standalone files in `.kiro/hooks/`. The default engine (plain `kiro-cli`, or `--v2`) ignores those and runs the `hooks` in the config of the agent a session uses; a workspace agent named `kiro_default` takes the built-in default agent's place, so its hooks run in a plain session. `--v3` does not run the hooks in that file, so the two sets never fire together. A third engine, V1, runs when the Kiro setting `chat.agentEngine` is `v1` or, per `kiro-cli chat --help`, with `--agent-engine v1` (the flag was not tried); it honours neither set, so dg does not cover it.
+
+`dg status` lists every workspace separately and checks the plugin files and hook files against the hashes recorded at install time, that the default agent still runs the plugin on all five events, `kiro.json`'s permissions and whether git ignores it, and a live whoami call. It fails when it knows a plain `kiro-cli` session goes unchecked, which includes Kiro's `chat.agentEngine` setting being `v1`, and warns when that depends on an agent dg doesn't manage: Kiro's `chat.defaultAgent` setting pointing plain sessions at another agent, on either engine. It only reads Kiro's settings, and it cannot see a `--agent-engine v1` flag passed on the command line. `dg remove kiro [--workspace <dir>]` deletes the files dg installed and the folders it created, if they're empty. Other workspaces stay connected.
+
+Things to know:
+
+- **Kiro CLI only.** The hooks are verified on `kiro-cli` 2.27, on the default engine and `--v3`: they run and they block. The two engines send different tool names and inputs, and the plugin registers the tool catalog of the engine a session runs, so a guardrail written for one engine's names does not match the other (see the [plugin README](../kiro/README.md#tool-catalog)). The Kiro IDE reads the same hook files, but whether it runs them the same way is unconfirmed. Setup and `dg status` both say so.
+- **On the default engine, only the default agent is covered.** Hooks there belong to an agent, so a session started with `--agent <name>`, or switched with `/agent`, runs none of ours. Setup and `dg status` both say so.
+- **The default agent can be the user's.** If `.kiro/agents/kiro_default.json` already exists, dg adds one entry per event to its `hooks` and changes nothing else, the way it treats Claude Code's `settings.json`. Its entries are recognized by their command, `node dist/index.js`. A file that isn't valid JSON is never rewritten: setup stops. `dg remove` deletes the file only if dg created it and it hasn't changed since; otherwise it takes its own entries out and keeps the rest. The agent dg creates has all tools, `includeMcpJson`, and the built-in agent's resources, but no `prompt`.
+- **The layout is the plugin's own.** Its hook files run `node dist/index.js` relative to the workspace, and it reads `kiro.json` from the folder above `dist/`, so the hook files are installed unchanged. That is why a workspace that builds to `dist/index.js` can't be set up.
+- **`kiro.json` holds the API key.** Keep it out of git. dg doesn't edit `.gitignore`; `dg status` warns if git isn't ignoring the file.
+- **Ownership is per file.** `.kiro/.datagusto-install.json` lists each installed file with its hash. `dg remove` deletes only files that still match, so if the project's build has since written its own `dist/index.js`, that file is left and reported. Your own hooks in `.kiro/hooks/` and other files in `dist/` are never touched.
+- The plugin's `package.json` is installed as `dist/package.json`, so node loads the plugin as ESM even in a CommonJS project.
+- A build step that empties `dist/` deletes the plugin. Kiro treats a hook that can't start as a warning and lets the tool call through, so check `dg status` after changing the build; it fails when plugin files are missing.
+
+## The API key is never a flag
+
+A flag value ends up in shell history and in `ps` output, so `dg` reads the key from one of these sources, in this order:
+
+1. the `DATAGUSTO_API_KEY` environment variable
+2. stdin, when it is piped: `pbpaste | dg setup claude-code`
+3. a hidden prompt, when stdin is a terminal
+
+`--api-key` is rejected. The "Connect your agent" page in the platform has to show one of the forms above.
+
+## Bundled plugins
+
+`npm run vendor` (`scripts/vendor-plugins.mjs`) does a clean build of `../claude_code` and copies its runtime files into `vendor/claude_code/`: `dist/*.js`, `.claude-plugin/`, `hooks/`, `package.json` (needed for `"type": "module"`) and `README.md`. It does the same for `../kiro` into `vendor/kiro/`: `dist/*.js`, `.kiro/hooks/` and `package.json`. Then `scripts/write-vendor-manifest.mjs` records a sha256 for every file in `vendor/manifest.json`.
+
+Setup refuses to install if the bundled files don't match the manifest, and `dg status` compares the installed files against the hashes copied into the install's marker. `vendor/` is git-ignored. `npm test` and `prepublishOnly` regenerate it, so the npm package always ships a fresh build.
+
+## Layout
+
+| Path | What it does |
+|---|---|
+| `src/commands/` | One file per command (oclif) |
+| `src/adapters/claude-code.ts` | Claude Code adapter: detect, plan, apply, clear, doctor |
+| `src/adapters/claude-settings.ts` | Reads and edits the `hooks` in `~/.claude/settings.json` without touching anything else |
+| `src/adapters/kiro.ts` | Kiro adapter: the same five steps, per workspace |
+| `src/adapters/kiro-agent.ts` | Reads and edits the hooks in a Kiro agent config without touching the rest of it |
+| `src/adapters/index.ts` | Adapter registry and the default adapter context |
+| `src/adapters/types.ts` | Per-agent contract: `detect`, `plan`, `apply`, `clear`, `doctor` |
+| `src/api/client.ts` | Bearer agent-key client, `GET /api/v1/public/safety/whoami` |
+| `src/api/errors.ts` | Failed API calls → one plain-English sentence with the next step |
+| `src/key-input.ts` | Key from env / stdin / hidden prompt, plus a format check |
+| `src/state/installs.ts` | `~/.datagusto/installs.json` ledger: paths and agent id only, dir `0700`, file `0600` |
+| `src/fs/atomic.ts` | Crash-safe writes: temp file → chmod → rename |
+| `src/vendor.ts` | Reads `vendor/manifest.json` and checks file hashes |
+| `scripts/` | `vendor-plugins.mjs` and `write-vendor-manifest.mjs`, plus `dev-whoami-stub.mjs` (dev only, not in the npm package) |
+
+`DATAGUSTO_HOME` overrides `~/.datagusto`. It's used by the tests and is handy when trying things locally.
+
+## Development
+
+```sh
+npm install
+npm test          # vendors ../claude_code and ../kiro, builds, then runs node --test tests/
+./bin/run.js --help
+```
+
+Needs Node 22 or later, on macOS, Linux or Windows. GitHub Actions runs the tests on all three (`.github/workflows/cli-test.yml`). The tests use a throwaway `HOME` and a local stand-in for the Datagusto API, so they never touch your real `~/.claude`. The Kiro tests use a throwaway workspace as well.
+
+To try it by hand without touching your real home:
+
+```sh
+T=$(mktemp -d) && mkdir $T/.claude
+DATAGUSTO_API_KEY=agt_live_… HOME=$T ./bin/run.js setup claude-code --server-url http://localhost:8000
+HOME=$T ./bin/run.js status     # should show ✔ Hooks: 7 events in ~/.claude/settings.json
+```
+
+To try Kiro by hand with no Datagusto server to point at, `scripts/dev-whoami-stub.mjs` answers whoami for any `agt_…` key. It answers every other path with `200 {}`, so it is only good for setup, status and remove:
+
+```sh
+node scripts/dev-whoami-stub.mjs 8787          # terminal 1; Ctrl-C to stop
+
+T=$(mktemp -d) && mkdir -p $T/home $T/ws         # terminal 2: throwaway HOME and workspace
+export DATAGUSTO_API_KEY=agt_live_anything
+HOME=$T/home ./bin/run.js setup kiro --workspace $T/ws --server-url http://127.0.0.1:8787
+find $T/ws -type f                              # dist/, kiro.json, .kiro/hooks/datagusto-*.json, .kiro/agents/kiro_default.json
+HOME=$T/home ./bin/run.js status                # ✔ Plugin files, ✔ Hooks (--v3), ✔ Hooks (default engine), agent "stub-agent"
+HOME=$T/home ./bin/run.js remove kiro --workspace $T/ws
+find $T/ws                                      # only the empty folder is left
+```
+
+### Live check (manual, before release)
+
+Datagusto runs no shared staging server, so this needs a Datagusto server you run yourself (one that has the whoami endpoint) and an agent key from its dashboard.
+
+1. `dg setup claude-code --server-url <your server>` with that agent key. `dg status` shows the agent name.
+2. Start `claude` in a scratch project and ask it to run `ls`. The call shows up in the dashboard's guardrail logs for that agent.
+3. With a guardrail that blocks a tool, the tool call is denied in Claude Code.
+4. Change `serverUrl` in `~/.datagusto/claude-code/claude-code.json` to an unreachable address. Tool calls are denied (fail-closed).
+5. `dg remove claude-code`, then check that `~/.claude/settings.json` has no Datagusto hooks left, and revoke the key.
+
+## Decisions
+
+- **oclif, not Commander.js.** The plan allowed falling back to Commander if oclif's scaffolding slowed down day 1. It didn't: `@oclif/core` v5 needs one `bin/run.js` and an `oclif` block in `package.json`, and it gives us generated help, arg validation and the `datagusto` alias for free.
+- **Hooks in `settings.json`, not a skills-folder plugin.** See [How the plugin is wired in](#how-the-plugin-is-wired-in-and-why). One method works on every Claude Code version; the cost is editing a file the user owns, which dg limits to its own entries.
+- **Replace the whole folder on re-run.** The new folder is built in a staging directory next to the target and renamed into place. The old one is restored if the rename fails, so the plugin files never mix two versions.

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from "@oclif/core";
+
+await execute({ dir: import.meta.url });

package/dist/adapters/claude-code.d.ts

@@ -0,0 +1,48 @@
+import { type ApiResult, type WhoamiResponse } from "../api/client.js";
+import { type Platform } from "../platform.js";
+import type { InstallRecord } from "../state/installs.js";
+import { type HooksConfig } from "./claude-settings.js";
+import { type AdapterContext, type AgentAdapter, type ClearResult, type DetectResult, type DoctorReport, type InstallPlan, type PluginConnection } from "./types.js";
+/** Oldest Claude Code dg will set up: has SessionStart + UserPromptSubmit. */
+export declare const MIN_HOOKS_VERSION = "1.0.62";
+/**
+ * First Claude Code release with each hook event, from its CHANGELOG.md.
+ * PostToolUseFailure's first changelog mention is 2.1.119, so that is used as
+ * a safe lower bound. Events not listed are never written to settings.json.
+ */
+export declare const HOOK_EVENT_SINCE: Record<string, string>;
+export interface ClaudeCodeAdapterDeps {
+    whoami?: (serverUrl: string, apiKey: string) => Promise<ApiResult<WhoamiResponse>>;
+    /** `claude --version` output, or undefined if it can't be run. */
+    claudeVersion?: (env: NodeJS.ProcessEnv) => Promise<string | undefined>;
+}
+export declare class ClaudeCodeAdapter implements AgentAdapter {
+    readonly name: "claude-code";
+    readonly displayName = "Claude Code";
+    private readonly whoami;
+    private readonly claudeVersion;
+    constructor(deps?: ClaudeCodeAdapterDeps);
+    pluginDir(ctx: AdapterContext): string;
+    installedServerUrl(ctx: AdapterContext): Promise<string | undefined>;
+    /** ~/.claude/skills/datagusto-safety, removed on setup if dg created it. */
+    legacySkillsDir(ctx: AdapterContext): string;
+    settingsPath(ctx: AdapterContext): string;
+    detect(ctx: AdapterContext): Promise<DetectResult>;
+    plan(ctx: AdapterContext, _conn: PluginConnection): Promise<InstallPlan>;
+    apply(ctx: AdapterContext, _plan: InstallPlan, conn: PluginConnection): Promise<InstallRecord>;
+    clear(ctx: AdapterContext, record: InstallRecord): Promise<ClearResult>;
+    doctor(ctx: AdapterContext, record: InstallRecord): Promise<DoctorReport>;
+    /** Parsed `claude --version` (undefined if it can't be run); throws if too old. */
+    private supportedVersion;
+    /** Drop hooks pointing into `dirs` from settings.json; true if any went. */
+    private removeSettingsHooks;
+    private checkClaudeVersion;
+    private checkSettingsHooks;
+}
+/**
+ * The plugin's hooks.json rewritten for settings.json: ${CLAUDE_PLUGIN_ROOT}
+ * becomes the absolute plugin folder (only plugins get that variable), and
+ * events `version` doesn't know are left out.
+ */
+export declare function settingsHooks(pluginHooks: HooksConfig, pluginDir: string, version: string | undefined, platform?: Platform): HooksConfig;
+export declare function compareVersions(a: string, b: string): number;