@prudai/cli 0.1.0 → 0.1.2
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 +33 -8
- package/dist/approvals.d.ts +2 -0
- package/dist/bin.js +2173 -1793
- package/dist/config.d.ts +2 -0
- package/dist/context.d.ts +5 -0
- package/dist/core.d.ts +3 -1
- package/dist/discovery.d.ts +3 -1
- package/dist/execute.d.ts +2 -0
- package/dist/index.js +565 -183
- package/dist/openapi.d.ts +7 -0
- package/dist/organization.d.ts +17 -0
- package/dist/version.d.ts +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,7 +13,11 @@ prudai ops search "api key" # operaties en platformcommando's, met scop
|
|
|
13
13
|
prudai describe irma risks create # parameters, body + voorbeeld, responses, curl
|
|
14
14
|
prudai irma risks list --limit 5 --json
|
|
15
15
|
prudai login # Keycloak-device-login: mensen en agents (op een machine zonder browser: --no-browser)
|
|
16
|
-
prudai whoami #
|
|
16
|
+
prudai whoami # loginorganisatie en ingestelde productomgevingen
|
|
17
|
+
prudai whoami --product irma --org <id> # gekozen IRMA-omgeving en bron van de keuze
|
|
18
|
+
prudai irma help # objecten met omschrijving en aantal operaties; --all voor alles
|
|
19
|
+
prudai irma risks create --help # hulp voor precies dit commando
|
|
20
|
+
prudai --version # versie; -v werkt ook
|
|
17
21
|
prudai skill install # skill voor Claude Code (--target codex|all)
|
|
18
22
|
```
|
|
19
23
|
|
|
@@ -23,7 +27,7 @@ Er is één identiteit: je Prudai-account in Keycloak (`login.prudai.com`). De C
|
|
|
23
27
|
|
|
24
28
|
| Groep | Commando's |
|
|
25
29
|
| --- | --- |
|
|
26
|
-
| Ontdekken | `guide`, `products`, `ops search <tekst> [--product p\|platform]`, `ops list`, `describe <product> <commando>` / `<product>:<operationId>` / `<METHOD> <pad>` / `<platformcommando>`, `<product> help`, `help --json` |
|
|
30
|
+
| Ontdekken | `guide`, `products`, `ops search <tekst> [--product p\|platform]`, `ops list`, `describe <product> <commando>` / `<product>:<operationId>` / `<METHOD> <pad>` / `<platformcommando>`, `<product> help [--all]`, `<commando> --help`, `help --json`, `--version` / `-v` |
|
|
27
31
|
| Product | `prudai <product> <object> <werkwoord> [args] [--param v] [--data json\|@file]` voor `leo`, `irma`, `ordo` |
|
|
28
32
|
| Rauw | `api <METHOD> <pad> [--product p]`: dezelfde regels; een querystring vult alleen de queryparameters van de operatie |
|
|
29
33
|
| Auth | `login`, `logout`, `whoami`, `auth login\|status [--online]\|logout\|token [--reveal --product p]\|export --reveal\|set --stdin`, `profile …` |
|
|
@@ -73,7 +77,7 @@ Per product, eerste bron die er is: `--spec`/`PRUDAI_SPEC`/`profile.specs`/regis
|
|
|
73
77
|
- `--json` geeft precies één JSON-document: elk resultaat is de `/v1`-envelop (`data, context, completeness, notIncluded, provenance, next`), ook voor auth, profielen en catalogusantwoorden. Dry run: `{dryRun: true, …}`; wachtend: `{status: "approval_required", …, follow}`; fout: `{error, message, exitCode, …details}`; `help` is de commandolijst.
|
|
74
78
|
- Exitcodes: **0** klaar, **1** netwerk/server (eerst de toestand checken voor je een write herhaalt), **2** jij moet iets doen (validatie, auth, geweigerd, `not_available`, wachtende goedkeuring). Foutcodes: `prudai help --json` (`errorCodes`).
|
|
75
79
|
- Writes: dry run waar de spec hem declareert, anders gaat er niets de deur uit; echt schrijven vraagt `--no-dry-run --yes`. Elke write krijgt een `Idempotency-Key` (op stderr); `--idempotency-key` hergebruikt hem.
|
|
76
|
-
- HITL: 202 → link + `prudai approvals wait <id> --product <p> --execute`. De CLI keurt nooit zelf goed en betaalt nooit.
|
|
80
|
+
- HITL: `confirm` voert na `--no-dry-run --yes` direct uit als het product in shadow draait; in enforce kan een goedkeuringsverzoek volgen. `review` wacht op een tweede persoon of wordt geweigerd als review niet beschikbaar is. `forbidden_for_agents` voert nooit uit. 202 → link + `prudai approvals wait <id> --product <p> --execute`. De CLI keurt nooit zelf goed en betaalt nooit.
|
|
77
81
|
- Geen secrets in output: elke Prudai-credential uit de omgeving of het configbestand wordt uit stdout en stderr gefilterd; alleen `auth token --reveal` print hem, bedoeld voor `$(…)`.
|
|
78
82
|
|
|
79
83
|
## Login en profielen
|
|
@@ -85,6 +89,8 @@ prudai profile create klant-b
|
|
|
85
89
|
prudai profile use klant-b
|
|
86
90
|
prudai profile set productApiUrls.ordo https://ordo.prudai.com
|
|
87
91
|
prudai profile set specs.ordo ./specs/ordo.openapi.json # opgeslagen als absoluut pad
|
|
92
|
+
prudai profile set orgs.irma <omgeving-id> # standaardomgeving binnen dit profiel
|
|
93
|
+
prudai irma context --org <omgeving-id> # afwijkende keuze voor één commando
|
|
88
94
|
prudai auth login --profile klant-b --no-browser # URL en code printen; goedkeuren kan op elk ander apparaat
|
|
89
95
|
prudai auth logout # beëindigt de sessie bij Keycloak, wist daarna lokaal
|
|
90
96
|
prudai profile delete klant-b
|
|
@@ -92,11 +98,13 @@ prudai profile delete klant-b
|
|
|
92
98
|
|
|
93
99
|
**Hoe het werkt (Keycloak-token en token-exchange).** `prudai login` is de device-flow (RFC 8628) van Keycloak, client `prudai-cli`: een mens keurt de code goed op `login.prudai.com`, met het eigen account en de MFA die daar geldt. De CLI bewaart het refreshtoken en het laatste login-toegangstoken (300 s) in `~/.config/prudai/config.json` (0600); producttokens staan nooit op schijf. Voor elke aanroep vraagt de CLI de token-broker (`https://mcp.prudai.com/oauth/exchange`) om een token voor precies één product (`irma`, `ordo` of het platform voor al het andere). De broker doet de standaard OAuth-token-exchange (RFC 8693) bij Keycloak; het gewisselde token leeft 5 minuten, heeft één audience en blijft alleen in het geheugen van dat proces. De CLI is een publieke client en mag zelf niet wisselen. Een product ziet nooit je login-token en nooit een sleutel: alleen een kortlevend token voor zichzelf, met jouw rechten. Een sessie intrekken (in Keycloak of met `prudai auth logout`) werkt direct voor nieuwe tokens; wat al gewisseld is verloopt binnen 5 minuten.
|
|
94
100
|
|
|
95
|
-
**
|
|
101
|
+
**Sessieduur en toegangstoken zijn afzonderlijk.** Het login-antwoord toont `accessToken.validUntil` voor het kortlevende toegangstoken en `session` voor de login. De CLI ververst het toegangstoken automatisch; de login eindigt door uitloggen, intrekken of het offline-sessiebeleid van Keycloak. De tokenrespons geeft geen vaste einddatum voor die sessie; daarom is `session.validUntil` null. Het bestaande `loginValidUntil` blijft voor compatibiliteit staan als alias van de toegangstokenvervaldatum en is geen sessievervaldatum. `auth status --online` controleert de sessie bij Keycloak.
|
|
96
102
|
|
|
97
|
-
|
|
103
|
+
**Automatisering gebruikt dezelfde login.** Op een runner: `prudai login --no-browser` (een mens keurt de code goed; het configbestand blijft staan), of verplaats de sessie: `prudai auth export --reveal | <secret store>` op de machine waar je inlogde, en op de runner `printf %s "$TOKEN" | prudai auth set --stdin` of de omgevingsvariabele `PRUDAI_REFRESH_TOKEN` (wint van het bestand en schrijft niets weg). Een gestolen refreshtoken is een login: bewaar het zoals een wachtwoord en beëindig de sessie met `prudai auth logout` of in Keycloak. Een sessie die ingetrokken is of volgens het Keycloak-beleid te lang stil lag geeft `not_authenticated` (exit 2) met de loginstap.
|
|
98
104
|
|
|
99
|
-
|
|
105
|
+
Login print de koppel-URL en code op stderr en opent de koppelpagina in de browser als er een is (een interactieve terminal en `open`, `xdg-open` met een display of Windows). `--no-browser` print alleen. De koppelpagina moet op de origin van de issuer staan, anders weigert de CLI. De login bevat een organisatie als standaard. Een product dat organisatiekeuze declareert kan binnen dezelfde login een andere omgeving kiezen met `--org`; de server controleert je toegang. Een ander profiel is geschikt voor een afzonderlijke login of een eigen set instellingen. Een profiel met het oude persoonlijke token (`prudai_pat_…`) wordt genegeerd: `auth status` zegt `legacy_login` en `prudai login` vervangt het.
|
|
106
|
+
|
|
107
|
+
Profielbeheer (`list`, `create`, `use`, `delete`, `set`, `unset`) lost het actieve profiel niet op. `list`, `create`, `use` en `delete` werken dus ook als `defaultProfile` naar een verwijderd profiel wijst of `PRUDAI_PROFILE` een nieuw profiel noemt; `set`/`unset` op zo'n ontbrekend profiel geven `unknown_profile` met de vervolgstap. Staging kiest u met `PRUDAI_API_URL` (er is geen `profile set apiUrl`). `unknown_profile` noemt de vervolgstap (`prudai profile create <naam>` of `prudai profile list`). `profile delete` weigert een profiel met een opgeslagen login: eerst `auth logout`. `profile set` kent `productApiUrls.<product>`, `specs.<product>`, `orgs.<product>` en `registryUrl`.
|
|
100
108
|
|
|
101
109
|
Configuratievoorrang: `--profile` boven `PRUDAI_PROFILE` boven `defaultProfile`. `PRUDAI_REFRESH_TOKEN`, `PRUDAI_ISSUER`, `PRUDAI_EXCHANGE_URL` en `PRUDAI_API_URL` gaan boven profielwaarden. Secrets komen nooit uit flags. `PRUDAI_CONFIG_FILE` kiest een alternatief bestand; `XDG_CONFIG_HOME` wordt ondersteund. Een bestand met credentials en groeps-/wereldrechten wordt geweigerd.
|
|
102
110
|
|
|
@@ -115,6 +123,14 @@ Voorbeeld zonder credentials (login vult die zelf in):
|
|
|
115
123
|
}
|
|
116
124
|
```
|
|
117
125
|
|
|
126
|
+
**Organisatie/omgeving kiezen.** Dit werkt alleen voor een product waarvan de spec `x-prudai-organization` declareert. Voor IRMA werkt dit zodra die release live is; tot dan geeft een expliciete keuze `organization_not_supported`. Voor een expliciete keuze is de voorrang `--org <id>` → `PRUDAI_<PRODUCT>_ORG` (bijvoorbeeld `PRUDAI_IRMA_ORG`) → `profile.orgs[product]`. Zonder die instellingen gebruikt het product de loginorganisatie zonder organisatieheader; de CLI controleert dan geen mismatch tegen de loginorganisatie en toont de door de server gemelde organisatie met bron `login`. `prudai whoami` toont de loginorganisatie en de ingestelde productkeuzes; `prudai whoami --product irma [--org <id>]` toont de effectieve keuze voor dat product. Elk productantwoord noemt de gekozen organisatie in de context. De keuze geeft geen extra rechten.
|
|
127
|
+
|
|
128
|
+
De OpenAPI-spec moet op documentniveau `"x-prudai-organization": { "header": "X-Irma-Active-Org", "description": "…" }` declareren. Alleen bij een expliciete keuze via flag, omgeving of profiel stuurt de CLI de gekozen id met die header. De header begint met `x-`, bevat alleen letters, cijfers en koppeltekens en mag geen CLI-header overnemen (`authorization`, `idempotency-key`, `if-match`, `x-prudai-agent`, `x-prudai-approval*`). Een ongeldige declaratie wordt geweigerd. Zonder declaratie geeft een expliciete keuze via `--org`, omgeving of profiel een fout vóór de productaanroep; zonder expliciete keuze bepaalt het product de loginorganisatie zonder extra header. De meegeleverde spec behoudt de declaratie als de bron die heeft.
|
|
129
|
+
|
|
130
|
+
De platformcommando's (bijvoorbeeld `account members list --org <id>`) behouden hun bestaande model: `--org` kiest de organisatie-id in het routepad, geen productheader. Dezelfde voorrang geldt: flag → `PRUDAI_PLATFORM_ORG` → `profile.orgs.platform` → login. Zo betekent `--org` steeds de doelorganisatie, terwijl de product-API bepaalt hoe die wordt meegestuurd.
|
|
131
|
+
|
|
132
|
+
Bij een expliciete organisatiekeuze via flag, omgeving of profiel vergelijkt de CLI `context.organization.id` uit een productantwoord (en `data.organization.id` bij `/v1/context`) met de gekozen organisatie voordat hij data toont. Een afwijking geeft `organization_mismatch`, exit 2, met beide id's en zonder de antwoorddata. Bij een echte write naar een gekozen productomgeving controleert hij eerst de gedeclareerde droogloop; een afwijking stopt de echte write. Zonder gedeclareerde droogloop blijft `--no-dry-run --yes` werken, met controle op het antwoord. Een mismatch na een echte write waarschuwt dat de actie mogelijk in de andere organisatie is uitgevoerd: controleer de toestand vóór herhalen. Multipart-uploadpreviews blijven lokaal; de organisatiecontrole gebeurt op het uploadantwoord.
|
|
133
|
+
|
|
118
134
|
De issuer en de broker krijgen een token en vallen dus onder dezelfde origin-regel als de producten (`PRUDAI_ISSUER` en `PRUDAI_EXCHANGE_URL` zijn alleen via de omgeving in te stellen; staging gebruikt eigen waarden). HTTP is uitsluitend voor localhost toegestaan; requests volgen geen redirects.
|
|
119
135
|
|
|
120
136
|
**Tokens gaan alleen naar vertrouwde origins:** `https://*.prudai.com` (standaardpoort) en `localhost`/`127.0.0.1`/`[::1]`. Een andere origin werkt alleen met `PRUDAI_ALLOW_ORIGIN=<exacte origin>` (kommagescheiden) in de omgeving; een flag, profielwaarde of spec kan geen origin toevoegen. De controle zit in de transportlaag, dus elk pad met een token (productcommando's, status, logout, intrekken na een mislukte opslag) valt eronder. Een `approveUrl` buiten deze lijst wordt niet getoond; de CLI waarschuwt en verwijst naar de productapp.
|
|
@@ -122,7 +138,8 @@ De issuer en de broker krijgen een token en vallen dus onder dezelfde origin-reg
|
|
|
122
138
|
## OpenAPI-commando's
|
|
123
139
|
|
|
124
140
|
```sh
|
|
125
|
-
prudai irma help
|
|
141
|
+
prudai irma help # korte samenvatting per object
|
|
142
|
+
prudai irma help --all # volledige gegroepeerde lijst
|
|
126
143
|
prudai irma context
|
|
127
144
|
prudai irma search datalek
|
|
128
145
|
prudai irma risks list --limit 25 --json
|
|
@@ -132,6 +149,12 @@ prudai irma risk-profile compare --from 2026-01-01
|
|
|
132
149
|
prudai irma simulations create --data '{"iterations":1000}' --no-dry-run --yes # IRMA declareert geen dry-run
|
|
133
150
|
```
|
|
134
151
|
|
|
152
|
+
Zoeken met `prudai ops search "setup"` ondersteunt NL/EN-synoniemen voor setup/onboarding/inrichten, tenant/omgeving/organisatie en bibliotheek/normenkader/framework. Exacte treffers op naam of samenvatting staan bovenaan; alleen relevante treffers tellen mee in een afgekapt resultaat. Zonder `--json` tonen lijsten een tabel met kernvelden en daaronder totaal, afkapping en vervolgstappen. `describe` toont het body-schema per veld: naam, type, verplicht, enum en beschrijving; met `--json` blijft het ruwe schema beschikbaar in één JSON-document.
|
|
153
|
+
|
|
154
|
+
Alleen bij lijstcommando's wordt een object zonder scalaire `data.id` en met precies één array-veld van objecten ook als lijst getoond, ongeacht de veldnaam (`data.risks`, `data.items`, `data.runs`, `data.links`). De overige velden staan onder de tabel. Lege lijsten tellen mee; bij meerdere arrays of gemengde arraywaarden blijft de objectweergave behouden.
|
|
155
|
+
|
|
156
|
+
Begin voor IRMA met `prudai irma context` (voeg `--org <id>` alleen toe zodra de live spec `x-prudai-organization` declareert) en volg de geordende stappen in `next`: eerst de menselijke stap om een normenkader in de app te laden als dat ontbreekt, daarna de concepten en voorstellen voor de agent. De server levert dit startpad zodra zijn spec/context het ondersteunt.
|
|
157
|
+
|
|
135
158
|
LEO, het platform en ORDO krijgen dezelfde vorm (`prudai <product> <object> <werkwoord>`) zodra hun `/v1` live is.
|
|
136
159
|
|
|
137
160
|
De commandonamen volgen het pad, nooit de operationId, en hebben dezelfde vorm als `@prudai/irma`, zodat `@prudai/irma` er later zonder breuk een dunne laag op kan zijn:
|
|
@@ -151,7 +174,7 @@ Product-origin: `--api-url`, `PRUDAI_<PRODUCT>_API_URL`, `profile.productApiUrls
|
|
|
151
174
|
|
|
152
175
|
Een productwrite voert standaard nooit uit. Declareert de spec voor die operatie een dry-run (queryparameter `dryRun`, of `x-prudai-dry-run: true` op operatie of document), dan stuurt de CLI `?dryRun=true` en heet de uitvoer `dryRun: true`, met `serverConfirmed` (header `x-prudai-dry-run`), het verzoek en de vervolgstap "Repeat with --no-dry-run --yes" (zoals IRMA `cli/v1.ts`). Zonder declaratie stuurt de CLI niets en meldt `dry_run_unsupported`: een product dat `dryRun` negeert, zou de actie anders echt uitvoeren. Ook `--yes` alleen verandert niets. Alleen **`--no-dry-run --yes` samen** vraagt een echte write. Iedere write krijgt een `Idempotency-Key` (op stderr getoond); `describe` zegt of het product replay-bescherming belooft (`idempotency.declared`). Een expliciete `--idempotency-key <vaste-waarde>` gaat altijd mee, voor hergebruik na onzekere aflevering. Writes worden nooit automatisch herhaald. Gebruik `--if-match` voor optimistic concurrency wanneer het product een ETag vereist.
|
|
153
176
|
|
|
154
|
-
`x-prudai-approval` bepaalt HITL. `forbidden_for_agents` wordt lokaal geblokkeerd; HTTP 202 toont het verzoek, de link en `prudai approvals wait <id> --product <p> --execute`, met exitcode 2; `--wait` op de write wacht meteen. De mens gebruikt de productapp; de CLI maakt geen approvalgrant. Het product voert de exact goedgekeurde call uit. DELETE volgt het soft-deletecontract van het product; restore is apart.
|
|
177
|
+
`x-prudai-approval` bepaalt HITL. `confirm` kan na `--no-dry-run --yes` direct uitvoeren in shadow; in enforce kan goedkeuring nodig zijn. `review` vraagt een tweede persoon of wordt geweigerd (bijvoorbeeld als review niet beschikbaar is), en is dus geen belofte dat er altijd een wachtrij bestaat. `forbidden_for_agents` wordt lokaal geblokkeerd; HTTP 202 toont het verzoek, de link en `prudai approvals wait <id> --product <p> --execute`, met exitcode 2; `--wait` op de write wacht meteen. De mens gebruikt de productapp; de CLI maakt geen approvalgrant. Het product voert de exact goedgekeurde call uit. DELETE volgt het soft-deletecontract van het product; restore is apart.
|
|
155
178
|
|
|
156
179
|
Antwoorden behouden alle zes velden: `data`, `context`, `completeness`, `notIncluded`, `provenance`, `next`. Menselijke uitvoer toont ook volledigheid en vervolgstappen. `--json` geeft precies één JSON-document op stdout, ook bij help en fouten; diagnostiek gaat naar stderr. Exitcodes: **0** afgerond, **1** netwerk/server, **2** validatie/auth of wachtende goedkeuring.
|
|
157
180
|
|
|
@@ -184,6 +207,8 @@ bun install --frozen-lockfile
|
|
|
184
207
|
bun run check:source && bun run typecheck && bun test && bun run test:break && bun run check:pack
|
|
185
208
|
```
|
|
186
209
|
|
|
210
|
+
Commandonamen liggen vast in `tests/fixtures/command-names.txt` (meegeleverde IRMA-spec en de ORDO- en platformfixtures). `tests/command-names.test.ts` faalt bij elke hernoeming: een gewijzigde regel is een gewijzigd commando voor elke gebruiker. Alleen bij een bedoelde hernoeming opnieuw maken met `bun scripts/gen-command-names.ts` en de diff in de PR toelichten. Een naambotsing in een live spec laat alleen de botsende commando's weg, met een waarschuwing; `--spec` en plugins blijven strikt.
|
|
211
|
+
|
|
187
212
|
De gebouwde CLI (`dist/bin.js`, shebang `#!/usr/bin/env node`) gebruikt in `src/` alleen Node-API's (`node:fs`, `node:child_process`, …): `check:source` en `typecheck` (tegen `@types/node` 20, zonder Bun-types) weigeren `Bun.*`, `bun:`-imports en `import.meta.dir`. `tests/node-runtime.test.ts` en `check:pack` draaien de gebouwde bundel onder echte Node (`node` van PATH, of `PRUDAI_TEST_NODE=/pad/naar/node`; minimaal Node 20, Bun's `node`-shim wordt geweigerd), en `check:pack` pakt bovendien de tarball uit zoals npx hem installeert.
|
|
188
213
|
|
|
189
214
|
MIT-licentie. Vragen en meldingen: https://support.prudai.com.
|
package/dist/approvals.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { RunContext } from "./context";
|
|
2
2
|
import { type ExitCode } from "./core";
|
|
3
|
+
import type { OrganizationDeclaration } from "./organization";
|
|
3
4
|
export declare const APPROVAL_POLL_MS = 5000;
|
|
4
5
|
/** Poll until decided; on approval optionally let the server execute the stored call. */
|
|
5
6
|
export declare function waitForApproval(ctx: RunContext, opts: {
|
|
@@ -9,5 +10,6 @@ export declare function waitForApproval(ctx: RunContext, opts: {
|
|
|
9
10
|
id: string;
|
|
10
11
|
execute: boolean;
|
|
11
12
|
timeoutSeconds?: number;
|
|
13
|
+
organization?: OrganizationDeclaration;
|
|
12
14
|
}): Promise<ExitCode>;
|
|
13
15
|
export declare function approvalsCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
|