@prudai/cli 0.0.0-stage → 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Prudai B.V.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,189 @@
1
- # Temporary Holding Version
1
+ # @prudai/cli
2
2
 
3
- 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.
3
+ `prudai` is de complete interface tot Prudai, voor mensen én agents: elke productoperatie (LEO en het platform, IRMA, ORDO), het account- en developerplatform (leden, rollen, seats, sleutels, factuurgegevens, abonnementen, credits, gebruik, logs, facturen, apps), goedkeuringen (HITL) en MCP. Er is niets in de Prudai Console of de API dat je niet via de CLI kunt. Wat het platform nog niet serveert, beantwoordt de CLI met "not available yet" en de geplande route; hij doet nooit alsof. Vandaag is de `/v1` van IRMA live; LEO met het platform en ORDO volgen, en hun commando's verschijnen zodra hun `/v1` live staat (tot dan `not_available`, exit 2).
4
+
5
+ Draait op **Node >=20**, ook zonder installatie: `npx @prudai/cli@next products`. Bun is alleen voor ontwikkelaars (installeren, bouwen, testen; **Bun >=1.3.6**), niet om de CLI te draaien. Eén runtimeafhankelijkheid, [`yaml`](https://github.com/eemeli/yaml) (ISC, zonder eigen afhankelijkheden, exacte versie vastgepind): Node heeft geen YAML-parser en OpenAPI-specificaties mogen YAML zijn (`--spec spec.yaml`); Bun had er een ingebouwd.
6
+
7
+ ## Snel
8
+
9
+ ```sh
10
+ prudai guide # alles wat een agent moet weten, met de productlijst
11
+ prudai products # producten, catalogusbron, aantal operaties
12
+ prudai ops search "api key" # operaties en platformcommando's, met scope, HITL, kosten, status
13
+ prudai describe irma risks create # parameters, body + voorbeeld, responses, curl
14
+ prudai irma risks list --limit 5 --json
15
+ prudai login # Keycloak-device-login: mensen en agents (op een machine zonder browser: --no-browser)
16
+ prudai whoami # wie, organisatie, effectieve scopes of gebruikersrechten
17
+ prudai skill install # skill voor Claude Code (--target codex|all)
18
+ ```
19
+
20
+ Er is één identiteit: je Prudai-account in Keycloak (`login.prudai.com`). De CLI zelf logt nooit in met een sleutel, een persoonlijk token of een sleutel per product; ook automatisering van de CLI gaat via `prudai login`. `prudai keys` beheert servicesleutels voor eigen applicaties van de klant, met jouw Keycloak-login; de geheime waarde van een nieuwe of geroteerde sleutel wordt eenmalig getoond.
21
+
22
+ ## Commando's
23
+
24
+ | Groep | Commando's |
25
+ | --- | --- |
26
+ | Ontdekken | `guide`, `products`, `ops search <tekst> [--product p\|platform]`, `ops list`, `describe <product> <commando>` / `<product>:<operationId>` / `<METHOD> <pad>` / `<platformcommando>`, `<product> help`, `help --json` |
27
+ | Product | `prudai <product> <object> <werkwoord> [args] [--param v] [--data json\|@file]` voor `leo`, `irma`, `ordo` |
28
+ | Rauw | `api <METHOD> <pad> [--product p]`: dezelfde regels; een querystring vult alleen de queryparameters van de operatie |
29
+ | Auth | `login`, `logout`, `whoami`, `auth login\|status [--online]\|logout\|token [--reveal --product p]\|export --reveal\|set --stdin`, `profile …` |
30
+ | Sleutels | `keys scopes`, `keys check --scopes …`, `keys list\|get\|create\|update\|rotate\|revoke` |
31
+ | Account | `account [show]`, `account orgs list\|create\|update`, `account members list\|invite\|update\|remove`, `account seats change`, `account subscription show\|change`, `account billing show\|update`, `account products list\|update`, `settings agent-keys` (alleen een mens) |
32
+ | Geld en gebruik | `credits [balance]\|ledger\|topup`, `usage [insights]`, `logs`, `invoices list\|download` |
33
+ | Kennisbanken | `kb list\|create\|get\|update\|delete\|restore\|docs\|doc [delete\|restore]\|upload\|answer`, `kb query [<kb_id>] --question …` en `kb search --question …` met `--kb <id>[,<id>…]\|all\|none` (zonder `<kb_id>` over meerdere kennisbanken, standaard `all`). Status `planned`: tot de live platformspec de routes noemt antwoordt elk commando `not_available` en wordt er niets verstuurd. `kb upload <kb_id> <bestand>` (of `--file`) verstuurt één multipart-onderdeel `file`, gestreamd van schijf (dry run lokaal; echt uploaden is `--no-dry-run --yes`) |
34
+ | Apps en tokens | `apps list\|create\|rotate-secret\|delete`, `tokens list\|revoke` |
35
+ | Projecten en memo's | `projects list [--q t] [--include-archived]`, `projects get\|docs [--trash]\|doc <project> …`, `projects doc text\|original\|delete\|restore\|purge <project> <document_id>`, `projects upload <project> <bestand>` (alias `dossiers`); `memos list [--trash]\|get\|transcript\|download\|upload\|delete\|restore\|purge [--project p]` |
36
+ | HITL | `approvals list\|get\|status\|wait <id> [--execute]\|execute\|cancel --product irma`; `--wait [--timeout s]` op elke write |
37
+ | MCP | `mcp [--check]`, `mcp connections list\|remove` |
38
+ | Agent | `skill install [--target claude\|codex\|all] [--dir p] [--print] [--force]` |
39
+ | Extensies | `prudai <naam> …` start `prudai-<naam>` van PATH, als die er is. Op Windows moet dat een `.exe` zijn: Node (>=20.12) start `.cmd`/`.bat` niet zonder shell, en een shell voegt de CLI bewust niet toe. Open punt, niet op Windows gemeten |
40
+
41
+ Seats, abonnementen en opwaarderingen kosten geld: ze wachten op goedkeuring van een mens (het antwoord bevat de goedkeuringslink) en een mens betaalt, nooit de CLI. De organisatie verwijderen kan alleen in de console. Per platformcommando staat de status (`contract`, `planned`, `proposed`) in `prudai ops list --product platform` en `prudai describe <commando>`.
42
+
43
+ ## Projecten (dossiers) en memo's
44
+
45
+ Opnames (`.m4a`, `.webm`, `.mp3`, `.wav` …) en transcripten (`.vtt`, `.srt`) staan als documenten in een LEO-project; het project "Transcribe" is de standaard voor `memos`. Een agent kan ze via de CLI uploaden, lezen, downloaden en verwijderen. `<project>` is een UUID of de exacte projectnaam (hoofdletters maken niet uit). Een naam die nul of meer dan één project oplevert, stopt met exit 2 en de kandidaat-id's; er wordt dan niets geschreven. `memos` gebruikt `Transcribe`, tenzij `--project` of `PRUDAI_MEMOS_PROJECT` iets anders zegt.
46
+
47
+ ```sh
48
+ prudai memos list # alleen audio en transcripten: id, bestandsnaam, kind, status, uploaded_by, subtitles, taal
49
+ prudai memos transcript <id> # de tekst op stdout (--json: de hele envelop; --out p schrijft een bestand)
50
+ prudai memos download <id> --out ./opname.m4a # het origineel; mode 0600; nooit over een bestaand bestand zonder --force
51
+ prudai memos upload ./opname.m4a # dry run: grootte, sha256, doelproject; er gaat niets de deur uit
52
+ prudai memos upload ./opname.m4a --no-dry-run --yes # echt uploaden: één multipart-onderdeel `file`, met Idempotency-Key
53
+ prudai memos delete <id> # dry run; --no-dry-run --yes zet het in de prullenbak (terug te zetten)
54
+ prudai memos list --trash # de prullenbak
55
+ prudai memos restore <id> --no-dry-run --yes # terugzetten (wordt opnieuw verwerkt)
56
+ prudai memos purge <id> --no-dry-run --yes # uit de prullenbak voorgoed weg: onomkeerbaar
57
+ prudai projects docs "Transcribe" --status completed
58
+ prudai dossiers upload <project-id> ./gesprek.vtt --no-dry-run --yes
59
+ ```
60
+
61
+ - **Lezen** werkt zodra het platform de routes serveert (tot dan `not_available`, exit 2). **Uploaden, verwijderen, terugzetten en purgen** wachten op goedkeuring van een mens (`confirm` en `review`): zolang de approvals-dienst van het platform ze niet uitvoert, antwoordt het platform 403 `approval_required` en gebeurt er niets.
62
+ - **Upload**: het bestand moet bestaan, regulier en niet leeg zijn en mag geen symlink zijn. Het wordt van schijf gestreamd; de dry run toont naam, grootte en sha256 en stuurt niets. De verwerking aan de serverkant loopt asynchroon: lees `status` (`memos get <id>`) tot `completed`. Na een onzekere aflevering herhaal je met dezelfde `--idempotency-key`. Het token gaat alleen naar een vertrouwde origin en redirects worden niet gevolgd.
63
+ - **Download en tekst**: `--out` is verplicht voor bytes (die gaan nooit naar stdout of een terminal). Het bestand krijgt mode 0600, een bestaand bestand blijft staan zonder `--force`, een mislukte of onderbroken download (ook Ctrl-C) laat geen half bestand achter. Op stdout staat `{path, bytes, sha256, content_type}`; vergelijk de sha256 met `sha256sum`. Een transfer mag 10 minuten duren (`PRUDAI_TRANSFER_TIMEOUT_SECONDS`, 5 tot 7200).
64
+ - **Verwijderen gaat naar de prullenbak** (soft delete, zoals overal in `/v1`): het document verdwijnt uit lijsten, zoeken en de LEO-chat maar blijft terug te zetten met `restore` (het wordt dan opnieuw verwerkt: status `pending` tot `completed`; de server antwoordt 202 met het document, dat is een succes en geen goedkeuringsverzoek). `--trash` toont de prullenbak. Alleen `purge` is definitief en onomkeerbaar, en alleen voor een document dat al in de prullenbak staat (de server weigert een actief document met 409 `document_not_in_trash`). De dry run (standaard) van `purge` zegt dat het onomkeerbaar is; bevestigt de server niet dat het een preview was, dan geeft de CLI een fout (exit 1, `dry_run_unconfirmed`) in plaats van een kalme dry run.
65
+ - `kb upload <kb_id> <bestand>` (of `--file`) gebruikt dezelfde uploadlaag.
66
+
67
+ ## Catalogus
68
+
69
+ Per product, eerste bron die er is: `--spec`/`PRUDAI_SPEC`/`profile.specs`/register > productplugin > live `<origin>/v1/openapi.json` (zonder credential opgehaald, alleen van een vertrouwde origin; 24 uur in `~/.cache/prudai`, missers 1 uur) > de meegeleverde kopie (`dist/specs/`, alleen de `/v1`-slice). `--refresh` vraagt opnieuw, `--offline` of `PRUDAI_OFFLINE=1` haalt nooit op. Nieuwe operaties in een live spec verschijnen dus zonder CLI-release, en een platformcommando werkt zodra zijn route in de platformspec staat. Meegeleverd worden alleen API's die live in productie staan (nu IRMA). Een product zonder live spec en zonder meegeleverde kopie (nu LEO met het platform, en ORDO) antwoordt `not_available` (exit 2) tot het zijn spec serveert; `prudai products` zegt waarom. De scopecatalogus komt van `GET /v1/scopes` zodra het platform die serveert; tot dan antwoordt `keys scopes` met `not_available` en toetst `keys check` alleen de vorm van een scope.
70
+
71
+ ## Agent-regels in het kort
72
+
73
+ - `--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
+ - 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
+ - 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.
77
+ - 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
+
79
+ ## Login en profielen
80
+
81
+ ```sh
82
+ prudai login # = auth login: Keycloak-device-login
83
+ prudai auth status --json # wie ben ik (lokaal, zonder netwerk); --online bewijst dat de sessie nog leeft
84
+ prudai profile create klant-b
85
+ prudai profile use klant-b
86
+ prudai profile set productApiUrls.ordo https://ordo.prudai.com
87
+ prudai profile set specs.ordo ./specs/ordo.openapi.json # opgeslagen als absoluut pad
88
+ prudai auth login --profile klant-b --no-browser # URL en code printen; goedkeuren kan op elk ander apparaat
89
+ prudai auth logout # beëindigt de sessie bij Keycloak, wist daarna lokaal
90
+ prudai profile delete klant-b
91
+ ```
92
+
93
+ **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
+
95
+ **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 te lang stil lag (30 dagen) geeft `not_authenticated` (exit 2) met de loginstap.
96
+
97
+ 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. Een login hoort bij één organisatie; voor een andere organisatie gebruik je een ander profiel (`prudai auth login --profile <naam>`). Een profiel met het oude persoonlijke token (`prudai_pat_…`) wordt genegeerd: `auth status` zegt `legacy_login` en `prudai login` vervangt het.
98
+
99
+ 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>` en `registryUrl`.
100
+
101
+ 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
+
103
+ Voorbeeld zonder credentials (login vult die zelf in):
104
+
105
+ ```json
106
+ {
107
+ "defaultProfile": "default",
108
+ "profiles": {
109
+ "default": {
110
+ "apiUrl": "https://api.prudai.com",
111
+ "productApiUrls": { "irma": "https://api.irma.prudai.com" },
112
+ "specs": { "irma": "./specs/irma.openapi.json" }
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ 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
+
120
+ **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.
121
+
122
+ ## OpenAPI-commando's
123
+
124
+ ```sh
125
+ prudai irma help
126
+ prudai irma context
127
+ prudai irma search datalek
128
+ prudai irma risks list --limit 25 --json
129
+ prudai irma risks get <id>
130
+ prudai irma risks history <id>
131
+ prudai irma risk-profile compare --from 2026-01-01
132
+ prudai irma simulations create --data '{"iterations":1000}' --no-dry-run --yes # IRMA declareert geen dry-run
133
+ ```
134
+
135
+ LEO, het platform en ORDO krijgen dezelfde vorm (`prudai <product> <object> <werkwoord>`) zodra hun `/v1` live is.
136
+
137
+ 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:
138
+
139
+ - CRUD op een collectie: `<resource> list|get|create|update|delete`; geneste resources krijgen koppeltekens (`registers-rows`). PUT naast PATCH heet `replace`.
140
+ - Een POST op een niet-collectiepad is een **taakactie** met de naam van het laatste padsegment (`flow-proposals approve`, `control-years close`, `certification-cycles withdraw`, `risks restore`). Een collectie is een pad met een `/{id}`-kind, een GET op hetzelfde pad of één padsegment.
141
+ - Overige GETs en taakacties: op een pad zonder parameters het eerste en laatste padwoord (`audit summary`, `simulations preview`); met parameters alle woorden vóór het laatste samen (`risks history`, `processes-flow auto-layout`, `controls-tests-proposal accept`), zodat er geen betekenis wegvalt. Eén segment zonder collectiekenmerk is één woord (`context`, `search`, `taxonomy`).
142
+ - Botsen korte namen, dan krijgen de botsende commando's alle padwoorden. `x-prudai-cli: "<woorden>"` (of `{ command: "<woorden>" }`) op een operatie legt een naam vast.
143
+ - Positionele argumenten vullen eerst de padparameters en daarna de verplichte queryparameters, in de volgorde van `help` (`risks history <id>`, `search <q>`). Overige queryfilters gebruiken `--<parameter>`, veilige headerparameters kleine letters.
144
+ - `servers` met een basispad wordt ondersteund: de platformspec (`servers: https://api.prudai.com/v1`, paden zonder `/v1`) levert `/v1/models` enzovoort. Levert een spec 0 commando's, dan zegt de CLI waarom. De paden `/v1/auth/*` horen bij `prudai auth` en worden niet gegenereerd.
145
+
146
+ Naamconflicten en writes zonder `x-prudai-approval` worden geweigerd. JSON en YAML zijn ondersteund; lokale `$ref`s worden opgelost, externe/cyclische referenties geweigerd.
147
+
148
+ Specbron, eerste beschikbare waarde: `--spec`, `PRUDAI_SPEC`, `profile.specs[product]`, registertemplate, plugin, live spec, gebundelde kopie (zie Catalogus). Een expliciete spec of plugin is strikt (een write zonder `x-prudai-approval` wordt geweigerd); een live of gebundelde spec krijgt dan de standaard (confirm, delete: review) met een waarschuwing, zodat één ontbrekende annotatie niet het hele product blokkeert. Een registertemplate komt uit `--registry`, `PRUDAI_REGISTRY_URL` of `profile.registryUrl` en bevat de spec-URL met `{product}`. De definitieve registerroute wordt nog afgestemd; lokale specs werken al.
149
+
150
+ Product-origin: `--api-url`, `PRUDAI_<PRODUCT>_API_URL`, `profile.productApiUrls[product]`, plugin, en als laatste de origin uit `servers` van de spec, maar die alleen als hij zelf `https://*.prudai.com` is (nooit localhost of een opt-in). Elke bron moet door de origin-allowlist hierboven.
151
+
152
+ 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
+
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.
155
+
156
+ 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
+
158
+ ## Dun productpakket
159
+
160
+ Een later `@prudai/irma` gebruikt de kern zonder eigen auth of HTTP-client:
161
+
162
+ ```js
163
+ #!/usr/bin/env node
164
+ import { readFileSync } from "node:fs";
165
+ import { runCli } from "@prudai/cli";
166
+
167
+ const spec = JSON.parse(readFileSync(new URL("./irma.openapi.json", import.meta.url), "utf8"));
168
+ const args = process.argv.slice(2);
169
+ const shared = new Set(["auth", "profile", "guide", "help"]);
170
+ const forwarded = shared.has(args[0] ?? "") ? args : ["irma", ...args];
171
+ process.exitCode = await runCli(forwarded, {
172
+ plugins: [{ product: "irma", spec, apiUrl: "https://api.irma.prudai.com" }],
173
+ });
174
+ ```
175
+
176
+ De library exporteert ook `generateCommands`, `buildOperationRequest`, `loadSpec`, config-, auth- en envelopfuncties. `runCli` heeft injecteerbare IO, fetch, klok en opslag. Het productpakket levert zijn spec; backendcode hoort niet in het pakket.
177
+
178
+ ## Ontwikkeling
179
+
180
+ De library exporteert `runCli`, `generateCommands`, `buildOperationRequest`, `loadSpec`, de catalogus, de scope-regels en config/auth/envelop-functies; `runCli` heeft injecteerbare IO, fetch, klok en opslag.
181
+
182
+ ```sh
183
+ bun install --frozen-lockfile
184
+ bun run check:source && bun run typecheck && bun test && bun run test:break && bun run check:pack
185
+ ```
186
+
187
+ 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
+
189
+ MIT-licentie. Vragen en meldingen: https://support.prudai.com.
package/dist/api.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type { RunContext } from "./context";
2
+ import { type ExitCode } from "./core";
3
+ export declare function apiCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
@@ -0,0 +1,13 @@
1
+ import type { RunContext } from "./context";
2
+ import { type ExitCode } from "./core";
3
+ export declare const APPROVAL_POLL_MS = 5000;
4
+ /** Poll until decided; on approval optionally let the server execute the stored call. */
5
+ export declare function waitForApproval(ctx: RunContext, opts: {
6
+ product: string;
7
+ origin: string;
8
+ approvalsPath: string;
9
+ id: string;
10
+ execute: boolean;
11
+ timeoutSeconds?: number;
12
+ }): Promise<ExitCode>;
13
+ export declare function approvalsCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
package/dist/args.d.ts ADDED
@@ -0,0 +1,14 @@
1
+ export type Flags = Record<string, string | boolean>;
2
+ /** Flags that never take a value. Product specs declare no parameters with these names (checked in tests). */
3
+ export declare const BOOLEAN_FLAGS: Set<string>;
4
+ /** Flags every product command accepts besides its own parameters. */
5
+ export declare const GLOBAL_FLAGS: Set<string>;
6
+ export declare function parseArgs(args: string[]): {
7
+ words: string[];
8
+ flags: Flags;
9
+ };
10
+ export declare function str(flags: Flags, key: string): string | undefined;
11
+ export declare function validateFlags(flags: Flags, allowed: Iterable<string>): void;
12
+ export declare function safeApiOrigin(raw: string): string;
13
+ /** Positive integer flag with bounds, e.g. --limit or --timeout. */
14
+ export declare function intFlag(flags: Flags, key: string, fallback: number, min: number, max: number): number;
package/dist/auth.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ import type { Environment, FileConfig, ResolvedConfig } from './config';
2
+ import { readClaims } from './keycloak';
3
+ import { type Session } from './session';
4
+ export interface AuthOptions {
5
+ config: ResolvedConfig;
6
+ file: FileConfig;
7
+ save: (cfg: FileConfig) => void;
8
+ load?: () => FileConfig;
9
+ fetch: typeof fetch;
10
+ stderr: (s: string) => void;
11
+ now?: () => number;
12
+ sleep?: (ms: number) => Promise<void>;
13
+ /** Environment for the origin allowlist (PRUDAI_ALLOW_ORIGIN, PRUDAI_ISSUER). */
14
+ env?: Environment;
15
+ /** Opens the validated pairing URL in a browser; omitted means print only. */
16
+ openBrowser?: (url: string) => void;
17
+ /** Reads a refresh token for `auth set --stdin`. */
18
+ readStdin?: () => Promise<string>;
19
+ session: Session;
20
+ }
21
+ export declare function authLogin(options: AuthOptions): Promise<unknown>;
22
+ /**
23
+ * `auth status`: who this login is, from the access token (no network). `--online` proves the session still lives
24
+ * by refreshing it; without a cached token the status refreshes anyway, because there is nothing local to read.
25
+ */
26
+ export declare function authStatus(options: AuthOptions, online?: boolean): Promise<unknown>;
27
+ export declare function authLogout(options: AuthOptions): Promise<unknown>;
28
+ /** `auth token` without --reveal: what the login is, never a secret. */
29
+ export declare function authToken(options: AuthOptions): Record<string, unknown>;
30
+ /** Bare product token for `$(…)`. Only `--reveal` gets here. */
31
+ export declare function revealProductToken(options: AuthOptions, product: string): Promise<string>;
32
+ /** Store a refresh token read from stdin (a runner that logged in once elsewhere). Never from a flag or argument. */
33
+ export declare function authSet(options: AuthOptions): Promise<unknown>;
34
+ /** The refresh token for a secret store (CI). Same care as `auth token --reveal`: only inside a pipe or `$(…)`. */
35
+ export declare function authExport(options: AuthOptions): string;
36
+ export { readClaims };
package/dist/bin.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};