@datagusto/cli 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -154
- package/package.json +1 -1
- package/vendor/manifest.json +1 -1
package/README.md
CHANGED
|
@@ -1,187 +1,90 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Datagusto CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`dg` connects a coding agent to your company's Datagusto server with one command. Once connected, the agent's tool calls are checked against the guardrails your company has set for it.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
|
-
```
|
|
8
|
-
dg setup <claude-code|kiro|codex> [--server-url <url>] [--workspace <dir>]
|
|
9
|
-
dg status
|
|
10
|
-
dg remove <claude-code|kiro|codex> [--workspace <dir>]
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Connect Claude Code
|
|
14
|
-
|
|
15
|
-
```sh
|
|
7
|
+
```bash
|
|
16
8
|
npm install -g @datagusto/cli
|
|
17
|
-
dg setup claude-code --server-url https://datagusto.your-company.example # prompts for the key (hidden)
|
|
18
9
|
```
|
|
19
10
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
`dg setup claude-code`:
|
|
23
|
-
|
|
24
|
-
1. checks that Claude Code is installed (`claude` on `PATH`, or a `~/.claude` folder)
|
|
25
|
-
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
|
|
26
|
-
3. copies the bundled plugin to `~/.datagusto/claude-code/` and writes `claude-code.json` (server URL + key, mode `0600`) inside it
|
|
27
|
-
4. adds the plugin's hooks to `~/.claude/settings.json`, pointing at that folder. Nothing else in the file is changed
|
|
28
|
-
5. records the install in `~/.datagusto/installs.json` (paths and agent id, never the key)
|
|
29
|
-
|
|
30
|
-
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`).
|
|
31
|
-
|
|
32
|
-
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.
|
|
33
|
-
|
|
34
|
-
`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.
|
|
35
|
-
|
|
36
|
-
`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.
|
|
37
|
-
|
|
38
|
-
### How the plugin is wired in, and why
|
|
39
|
-
|
|
40
|
-
| Option | Loads every session | Works on every Claude Code version | Used |
|
|
41
|
-
|---|---|---|---|
|
|
42
|
-
| Hook entries merged into `~/.claude/settings.json` | Yes | Yes (any version with hooks) | **Yes** |
|
|
43
|
-
| `~/.claude/skills/<dir>/` with `.claude-plugin/plugin.json` | Yes | No: 2.1.157 or later only | No |
|
|
44
|
-
| `claude --plugin-dir` / `CLAUDE_CODE_PLUGIN_DIRS` | No: one session, or needs a shell-profile edit | Yes | No (still fine for plugin development) |
|
|
45
|
-
| Marketplace + `/plugin install` | Yes | Yes | No: marketplaces are out of scope (ADR-0003) |
|
|
46
|
-
|
|
47
|
-
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.
|
|
48
|
-
|
|
49
|
-
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.
|
|
50
|
-
|
|
51
|
-
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.
|
|
11
|
+
Needs Node.js 22 or later, on macOS, Linux or Windows. The same program is also installed as `datagusto`.
|
|
52
12
|
|
|
53
|
-
|
|
13
|
+
## Quick Start
|
|
54
14
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
- **Symlinks survive.** A symlinked `settings.json` (dotfile managers) is written through to its target, and the file keeps its mode.
|
|
59
|
-
- **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.
|
|
15
|
+
```bash
|
|
16
|
+
# Connect Claude Code (asks for your agent API key)
|
|
17
|
+
dg setup claude-code --server-url https://datagusto.your-company.example
|
|
60
18
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
- Loading the plugin with `--plugin-dir` as well (plugin development) runs every hook twice. Run `dg remove claude-code` first.
|
|
64
|
-
- `.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.
|
|
65
|
-
- 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.
|
|
66
|
-
- If setup created `~/.claude/settings.json`, `dg remove` leaves it behind as `{}`.
|
|
67
|
-
- 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.
|
|
68
|
-
|
|
69
|
-
## Connect Kiro
|
|
70
|
-
|
|
71
|
-
Kiro hooks are per workspace, so the plugin is installed into one workspace at a time. `--workspace` defaults to the current directory.
|
|
19
|
+
# Check that it's connected
|
|
20
|
+
dg status
|
|
72
21
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
dg setup kiro --server-url https://datagusto.your-company.example # prompts for the key (hidden)
|
|
22
|
+
# Disconnect
|
|
23
|
+
dg remove claude-code
|
|
76
24
|
```
|
|
77
25
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
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
|
|
81
|
-
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`)
|
|
82
|
-
3. reads the agent API key (see below) and checks it with whoami, exactly as for Claude Code. `--server-url` is the same flag
|
|
83
|
-
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`
|
|
84
|
-
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
|
|
85
|
-
6. records the install in `~/.datagusto/installs.json`, one entry per workspace
|
|
86
|
-
|
|
87
|
-
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`.
|
|
88
|
-
|
|
89
|
-
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.
|
|
90
|
-
|
|
91
|
-
`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.
|
|
26
|
+
You need two things from your Datagusto dashboard or admin:
|
|
92
27
|
|
|
93
|
-
|
|
28
|
+
- The **address of your company's Datagusto server**. There is no shared server, so there is no default.
|
|
29
|
+
- An **agent API key** from the agent's page in the dashboard. Keys start with `agt_`.
|
|
94
30
|
|
|
95
|
-
|
|
96
|
-
- **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.
|
|
97
|
-
- **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`.
|
|
98
|
-
- **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.
|
|
99
|
-
- **`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.
|
|
100
|
-
- **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.
|
|
101
|
-
- The plugin's `package.json` is installed as `dist/package.json`, so node loads the plugin as ESM even in a CommonJS project.
|
|
102
|
-
- 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.
|
|
31
|
+
Start a new agent session after setup.
|
|
103
32
|
|
|
104
|
-
##
|
|
33
|
+
## Commands
|
|
105
34
|
|
|
106
|
-
|
|
35
|
+
| Command | Description |
|
|
36
|
+
|---------|-------------|
|
|
37
|
+
| `dg setup claude-code` | Connect Claude Code, for your user account |
|
|
38
|
+
| `dg setup kiro` | Connect the Kiro CLI, in one workspace |
|
|
39
|
+
| `dg status` | Show connected agents and check that each one still works |
|
|
40
|
+
| `dg remove claude-code` | Remove what setup installed for Claude Code |
|
|
41
|
+
| `dg remove kiro` | Remove what setup installed in a workspace |
|
|
107
42
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
43
|
+
| Option | Description |
|
|
44
|
+
|--------|-------------|
|
|
45
|
+
| `--server-url <url>` | Your company's Datagusto server. Needed the first time; a re-run keeps the saved address |
|
|
46
|
+
| `--workspace <dir>` | Kiro only: the workspace to connect or remove. Defaults to the current folder |
|
|
111
47
|
|
|
112
|
-
|
|
48
|
+
`dg status` exits with `1` if any check fails, so it can be used in scripts.
|
|
113
49
|
|
|
114
|
-
##
|
|
50
|
+
## Supported agents
|
|
115
51
|
|
|
116
|
-
|
|
52
|
+
| Agent | Name | Installed |
|
|
53
|
+
|-------|------|-----------|
|
|
54
|
+
| Claude Code | `claude-code` | Once per user |
|
|
55
|
+
| Kiro CLI | `kiro` | Once per workspace. The Kiro IDE is not supported yet |
|
|
56
|
+
| Codex | `codex` | Not supported yet |
|
|
117
57
|
|
|
118
|
-
|
|
58
|
+
## API key
|
|
119
59
|
|
|
120
|
-
|
|
60
|
+
The key is never passed as a flag, so it stays out of your shell history. `dg setup` reads it from the first of these it finds:
|
|
121
61
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
| `src/adapters/claude-code.ts` | Claude Code adapter: detect, plan, apply, clear, doctor |
|
|
126
|
-
| `src/adapters/claude-settings.ts` | Reads and edits the `hooks` in `~/.claude/settings.json` without touching anything else |
|
|
127
|
-
| `src/adapters/kiro.ts` | Kiro adapter: the same five steps, per workspace |
|
|
128
|
-
| `src/adapters/kiro-agent.ts` | Reads and edits the hooks in a Kiro agent config without touching the rest of it |
|
|
129
|
-
| `src/adapters/index.ts` | Adapter registry and the default adapter context |
|
|
130
|
-
| `src/adapters/types.ts` | Per-agent contract: `detect`, `plan`, `apply`, `clear`, `doctor` |
|
|
131
|
-
| `src/api/client.ts` | Bearer agent-key client, `GET /api/v1/public/safety/whoami` |
|
|
132
|
-
| `src/api/errors.ts` | Failed API calls → one plain-English sentence with the next step |
|
|
133
|
-
| `src/key-input.ts` | Key from env / stdin / hidden prompt, plus a format check |
|
|
134
|
-
| `src/state/installs.ts` | `~/.datagusto/installs.json` ledger: paths and agent id only, dir `0700`, file `0600` |
|
|
135
|
-
| `src/fs/atomic.ts` | Crash-safe writes: temp file → chmod → rename |
|
|
136
|
-
| `src/vendor.ts` | Reads `vendor/manifest.json` and checks file hashes |
|
|
137
|
-
| `scripts/` | `vendor-plugins.mjs` and `write-vendor-manifest.mjs`, plus `dev-whoami-stub.mjs` (dev only, not in the npm package) |
|
|
62
|
+
1. The `DATAGUSTO_API_KEY` environment variable
|
|
63
|
+
2. Standard input, when piped: `pbpaste | dg setup claude-code`
|
|
64
|
+
3. A hidden prompt
|
|
138
65
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
## Development
|
|
142
|
-
|
|
143
|
-
```sh
|
|
144
|
-
npm install
|
|
145
|
-
npm test # vendors ../claude_code and ../kiro, builds, then runs node --test tests/
|
|
146
|
-
./bin/run.js --help
|
|
66
|
+
```bash
|
|
67
|
+
DATAGUSTO_API_KEY=agt_live_… dg setup claude-code --server-url https://datagusto.your-company.example
|
|
147
68
|
```
|
|
148
69
|
|
|
149
|
-
|
|
70
|
+
Setup checks the key with your server before changing anything. A wrong key or address stops setup with nothing changed.
|
|
150
71
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
```sh
|
|
154
|
-
T=$(mktemp -d) && mkdir $T/.claude
|
|
155
|
-
DATAGUSTO_API_KEY=agt_live_… HOME=$T ./bin/run.js setup claude-code --server-url http://localhost:8000
|
|
156
|
-
HOME=$T ./bin/run.js status # should show ✔ Hooks: 7 events in ~/.claude/settings.json
|
|
157
|
-
```
|
|
72
|
+
## What setup changes
|
|
158
73
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
T=$(mktemp -d) && mkdir -p $T/home $T/ws # terminal 2: throwaway HOME and workspace
|
|
165
|
-
export DATAGUSTO_API_KEY=agt_live_anything
|
|
166
|
-
HOME=$T/home ./bin/run.js setup kiro --workspace $T/ws --server-url http://127.0.0.1:8787
|
|
167
|
-
find $T/ws -type f # dist/, kiro.json, .kiro/hooks/datagusto-*.json, .kiro/agents/kiro_default.json
|
|
168
|
-
HOME=$T/home ./bin/run.js status # ✔ Plugin files, ✔ Hooks (--v3), ✔ Hooks (default engine), agent "stub-agent"
|
|
169
|
-
HOME=$T/home ./bin/run.js remove kiro --workspace $T/ws
|
|
170
|
-
find $T/ws # only the empty folder is left
|
|
171
|
-
```
|
|
74
|
+
| Agent | Files |
|
|
75
|
+
|-------|-------|
|
|
76
|
+
| Claude Code | The plugin and its config in `~/.datagusto/claude-code/`, and the Datagusto hooks added to `~/.claude/settings.json`. Your other settings and hooks are left as they are |
|
|
77
|
+
| Kiro | The plugin in the workspace's `dist/` folder, its config in `kiro.json`, and hook files in `.kiro/` |
|
|
172
78
|
|
|
173
|
-
|
|
79
|
+
- The config file holds the API key and is readable only by you. For Kiro, keep `kiro.json` out of git: `dg status` warns if git isn't ignoring it.
|
|
80
|
+
- Running setup again is safe. It updates the plugin, key or server address in place.
|
|
81
|
+
- `dg remove` deletes only what setup added, and works offline. The API key keeps working until you revoke it in the dashboard.
|
|
174
82
|
|
|
175
|
-
|
|
83
|
+
## Good to know
|
|
176
84
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
3. With a guardrail that blocks a tool, the tool call is denied in Claude Code.
|
|
180
|
-
4. Change `serverUrl` in `~/.datagusto/claude-code/claude-code.json` to an unreachable address. Tool calls are denied (fail-closed).
|
|
181
|
-
5. `dg remove claude-code`, then check that `~/.claude/settings.json` has no Datagusto hooks left, and revoke the key.
|
|
85
|
+
- **Fails closed.** If the agent can't reach your Datagusto server, its tool calls are blocked until the connection is back, not let through unchecked.
|
|
86
|
+
- **Kiro covers the default agent.** On the Kiro CLI's default engine, sessions started with another agent (`--agent <name>`) are not checked. `dg setup` and `dg status` both say so.
|
|
182
87
|
|
|
183
|
-
##
|
|
88
|
+
## License
|
|
184
89
|
|
|
185
|
-
|
|
186
|
-
- **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.
|
|
187
|
-
- **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.
|
|
90
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@datagusto/cli",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Connect a coding agent (Claude Code, Kiro) to your company's Datagusto server with one command",
|
|
5
5
|
"homepage": "https://github.com/datagusto/safety-platform-plugins/tree/main/cli#readme",
|
|
6
6
|
"repository": {
|