@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.
@@ -0,0 +1,115 @@
1
+ import type { Environment } from "./config";
2
+ import { type GeneratedCommand } from "./openapi";
3
+ /** Where a product's catalogue came from; shown by `prudai products` and in every catalogue answer. */
4
+ export interface SpecSource {
5
+ kind: "explicit" | "plugin" | "live" | "cache" | "bundled";
6
+ location: string;
7
+ fetchedAt?: string;
8
+ ref?: string;
9
+ status?: string;
10
+ note?: string;
11
+ }
12
+ export interface ProductCatalog {
13
+ product: string;
14
+ title: string;
15
+ origin: string;
16
+ source?: SpecSource;
17
+ commands: GeneratedCommand[];
18
+ warnings: string[];
19
+ /** Set when no usable spec was found or the spec could not be turned into commands. */
20
+ error?: string;
21
+ /** A known product with no spec at all (not live yet, nothing bundled): commands answer not_available. */
22
+ notAvailable?: boolean;
23
+ /** The product serves its spec to a logged-in person and there is no valid login: not "not available", but `prudai login`. */
24
+ loginNeeded?: boolean;
25
+ /** There is a login, the product asked for a token, and getting one failed (broker down, access refused): that failure, not "no spec". */
26
+ credentialFailure?: {
27
+ code: string;
28
+ exitCode: 1 | 2;
29
+ };
30
+ /** Why the live spec was not used (shown by prudai products, not on every command). */
31
+ liveNote?: string;
32
+ approvalsPath?: string;
33
+ mcpUrl?: string;
34
+ scopeProducts: string[];
35
+ spec?: Record<string, unknown>;
36
+ }
37
+ export interface CatalogContext {
38
+ env: Environment;
39
+ fetch: typeof fetch;
40
+ now: () => number;
41
+ /** --spec / PRUDAI_SPEC / profile.specs[product] / registry template, already resolved per product. */
42
+ explicitSpec?: (product: string) => string | undefined;
43
+ plugins?: Array<{
44
+ product: string;
45
+ spec: unknown;
46
+ apiUrl: string;
47
+ }>;
48
+ /** --refresh: ignore a fresh cache entry and ask the origin again. */
49
+ refresh?: boolean;
50
+ /** --offline or PRUDAI_OFFLINE=1: never fetch a live spec. */
51
+ offline?: boolean;
52
+ /** Origin override per product (flag, env, profile); only used to locate the live spec. */
53
+ originFor?: (product: string) => string | undefined;
54
+ /**
55
+ * A product token for the live spec, when the product does not serve its spec publicly (IRMA and ORDO answer 401 until their owner switches that on).
56
+ * Only asked after an unauthenticated 401/403 and only from a trusted origin; undefined or a not_authenticated error = not logged in, nothing is sent.
57
+ * Any other error (broker down, access refused) is reported as such.
58
+ */
59
+ credentialFor?: (product: string) => Promise<string | undefined>;
60
+ /** Is there a login at all? Without one a cached refusal stands: no request per command. Unset = assume there may be one. */
61
+ hasLogin?: () => boolean;
62
+ }
63
+ declare let manifestCache: {
64
+ products: Record<string, {
65
+ ref?: string;
66
+ status?: string;
67
+ note?: string;
68
+ syncedAt?: string;
69
+ }>;
70
+ } | undefined;
71
+ /** Bundled files live in specs/ next to the package root (source) or in dist/specs (build). */
72
+ export declare function bundledPath(name: string): string | undefined;
73
+ export declare function bundledManifest(): NonNullable<typeof manifestCache>;
74
+ export declare function readBundledJson(name: string): Record<string, unknown> | undefined;
75
+ /** Disk cache of live specs. No HOME (library/tests with an injected environment) = no disk cache. */
76
+ export declare function cacheDir(env: Environment): string | undefined;
77
+ /** One product: explicit spec > plugin > live (cached) > bundled. Never throws for a missing spec. */
78
+ export declare function loadProductCatalog(word: string, ctx: CatalogContext): Promise<ProductCatalog>;
79
+ /** Every known product (registry + plugins), in registry order. */
80
+ export declare function loadCatalog(ctx: CatalogContext, only?: string[]): Promise<ProductCatalog[]>;
81
+ export declare function commandLine(command: GeneratedCommand): string;
82
+ export interface SearchHit {
83
+ command: string;
84
+ product: string;
85
+ method: string;
86
+ path: string;
87
+ operationId: string;
88
+ summary: string;
89
+ approval: string;
90
+ scopes: string[];
91
+ cost: string;
92
+ dryRun: boolean;
93
+ status?: string;
94
+ available?: boolean;
95
+ score: number;
96
+ }
97
+ /** Ranked search over command words, path, summary, operationId, tags and description. */
98
+ export declare function searchOperations(catalogs: ProductCatalog[], query: string, filters?: {
99
+ product?: string;
100
+ approval?: string;
101
+ method?: string;
102
+ }): SearchHit[];
103
+ /**
104
+ * Find one operation by any of: `<product> <command words>`, `<product>:<operationId>`, an
105
+ * operationId that is unique across products, or `METHOD /v1/path` (optionally after a product).
106
+ */
107
+ export declare function findOperation(catalogs: ProductCatalog[], ref: string[]): {
108
+ catalog: ProductCatalog;
109
+ command: GeneratedCommand;
110
+ } | {
111
+ candidates: string[];
112
+ };
113
+ /** `/v1/risks/{id}` matches `/v1/risks/r_123`. */
114
+ export declare function templateMatches(template: string, path: string): boolean;
115
+ export {};
package/dist/cli.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ import type { CliOptions } from "./context";
2
+ import { type ExitCode } from "./core";
3
+ export type { CliOptions, ProductPlugin } from "./context";
4
+ export { HELP } from "./discovery";
5
+ /** The agent guide without a loaded catalogue (library use); `prudai guide` adds the live product list. */
6
+ export declare const GUIDE: string;
7
+ /** Main library entry point. Every invocation owns exactly one stdout document. */
8
+ export declare function runCli(args: string[], options?: CliOptions): Promise<ExitCode>;
@@ -0,0 +1,70 @@
1
+ import { CliError } from './core';
2
+ export declare const DEFAULT_API_URL = "https://api.prudai.com";
3
+ export declare const DEFAULT_ISSUER = "https://login.prudai.com/realms/prudai";
4
+ export declare const DEFAULT_EXCHANGE_URL = "https://mcp.prudai.com/oauth/exchange";
5
+ /** Identity as returned once by the token service at login (token service contract); never secrets. */
6
+ export interface Identity {
7
+ user?: {
8
+ id?: string | null;
9
+ name?: string | null;
10
+ email?: string | null;
11
+ };
12
+ organization?: {
13
+ id?: string | null;
14
+ name?: string | null;
15
+ };
16
+ }
17
+ /** The Keycloak login of a profile: only the offline refresh token is the credential; the access token is a short-lived cache. */
18
+ export interface Login {
19
+ issuer: string;
20
+ refreshToken: string;
21
+ accessToken?: string;
22
+ /** Epoch milliseconds. */
23
+ accessExpiresAt?: number;
24
+ }
25
+ export interface Profile extends Identity {
26
+ apiUrl?: string;
27
+ login?: Login;
28
+ /** Token-broker endpoint (default https://mcp.prudai.com/oauth/exchange). */
29
+ exchangeUrl?: string;
30
+ productApiUrls?: Record<string, string>;
31
+ registryUrl?: string;
32
+ specs?: Record<string, string>;
33
+ /** Read-only leftovers of the removed personal-token login; ignored, reported by `auth status`, dropped at the next login. */
34
+ token?: string;
35
+ tokenApiUrl?: string;
36
+ tokenKind?: string;
37
+ expiresAt?: string;
38
+ products?: string[];
39
+ }
40
+ export interface FileConfig {
41
+ defaultProfile?: string;
42
+ profiles: Record<string, Profile>;
43
+ }
44
+ export interface ResolvedConfig extends Omit<Profile, 'token' | 'login'> {
45
+ profile: string;
46
+ apiUrl: string;
47
+ /** Keycloak realm issuer: PRUDAI_ISSUER, else the stored login, else production. */
48
+ issuer: string;
49
+ exchangeUrl: string;
50
+ /** The credential: PRUDAI_REFRESH_TOKEN (CI runners) wins over the profile's stored login. */
51
+ refreshToken?: string;
52
+ refreshSource: 'env' | 'file' | 'none';
53
+ /** A profile that still holds a removed personal token (reported, never used). */
54
+ legacyLogin: boolean;
55
+ }
56
+ export type Environment = Record<string, string | undefined>;
57
+ export declare const names: (name: string) => boolean;
58
+ export declare function configPath(env: Environment): string;
59
+ /** Missing is an empty config; unreadable or malformed files fail closed. */
60
+ export declare function readConfig(path: string): FileConfig;
61
+ /** Atomic replacement keeps credential contents private, even with a permissive umask. */
62
+ export declare function writeConfig(path: string, cfg: FileConfig): void;
63
+ /** Which profile a command addresses, without requiring that it exists. */
64
+ export declare function selectedProfile(env: Environment, file: FileConfig, profileName?: string): {
65
+ name: string;
66
+ explicit: boolean;
67
+ exists: boolean;
68
+ };
69
+ export declare function unknownProfile(name: string): CliError;
70
+ export declare function resolveConfig(env: Environment, file: FileConfig, profileName?: string): ResolvedConfig;
@@ -0,0 +1,55 @@
1
+ import type { Flags } from "./args";
2
+ import type { CatalogContext } from "./catalog";
3
+ import type { Environment, FileConfig, ResolvedConfig } from "./config";
4
+ import type { Emit } from "./output";
5
+ import type { Session } from "./session";
6
+ export interface ProductPlugin {
7
+ product: string;
8
+ spec: unknown;
9
+ apiUrl: string;
10
+ }
11
+ export interface CliOptions {
12
+ env?: Record<string, string | undefined>;
13
+ fetch?: typeof fetch;
14
+ stdout?: (text: string) => void;
15
+ stderr?: (text: string) => void;
16
+ readConfig?: () => FileConfig;
17
+ saveConfig?: (file: FileConfig) => void;
18
+ plugins?: ProductPlugin[];
19
+ now?: () => number;
20
+ sleep?: (ms: number) => Promise<void>;
21
+ /** Opens the pairing URL at login. Default: the system browser when one is available. */
22
+ openBrowser?: (url: string) => void;
23
+ /**
24
+ * Library use and tests: supply product tokens yourself instead of the Keycloak login (an embedding process that already
25
+ * holds a user's token). Not reachable from the command line or the environment.
26
+ */
27
+ credentials?: {
28
+ productToken(product: string): Promise<string | undefined>;
29
+ };
30
+ /** Reads stdin for `auth set --stdin`. Default: process stdin, refused on a terminal. */
31
+ readStdin?: () => Promise<string>;
32
+ /** Runs an extension `prudai-<name>` for `prudai <name> …`; undefined = not installed. Default: spawn it when it is on PATH. */
33
+ runExternal?: (binary: string, args: string[]) => Promise<number | undefined>;
34
+ /** Home directory for `prudai skill install` (default: HOME). */
35
+ home?: string;
36
+ }
37
+ /** Everything a command handler needs; built once per invocation. */
38
+ export interface RunContext {
39
+ options: CliOptions;
40
+ env: Environment;
41
+ file: FileConfig;
42
+ config: ResolvedConfig;
43
+ flags: Flags;
44
+ json: boolean;
45
+ emit: Emit;
46
+ stderr: (text: string) => void;
47
+ fetch: typeof fetch;
48
+ now: () => number;
49
+ sleep: (ms: number) => Promise<void>;
50
+ catalog: CatalogContext;
51
+ /** Lets `auth token --reveal` print the credential; nothing else may. */
52
+ reveal: () => void;
53
+ /** Keycloak login and the product tokens derived from it. */
54
+ session: Session;
55
+ }
package/dist/core.d.ts ADDED
@@ -0,0 +1,91 @@
1
+ import type { Environment } from "./config";
2
+ export declare const EXIT: {
3
+ readonly OK: 0;
4
+ readonly SERVER: 1;
5
+ readonly USER: 2;
6
+ };
7
+ export type ExitCode = 0 | 1 | 2;
8
+ export declare class CliError extends Error {
9
+ readonly exitCode: 1 | 2;
10
+ readonly code: string;
11
+ constructor(message: string, exitCode?: 1 | 2, code?: string);
12
+ }
13
+ export declare function statusToExit(status: number): ExitCode;
14
+ /** Transport rules for every URL; credential delivery additionally needs a trusted origin (trust.ts). */
15
+ export declare function secureUrl(raw: string): URL;
16
+ export declare function requestJson(fetchImpl: typeof fetch, raw: string, options?: {
17
+ method?: string;
18
+ token?: string;
19
+ body?: unknown;
20
+ headers?: Record<string, string>;
21
+ env?: Environment;
22
+ }): Promise<{
23
+ status: number;
24
+ body: unknown;
25
+ headers: Headers;
26
+ }>;
27
+ /** A local file to send as the one multipart part. `open` yields the bytes and checks that it is still the file that was inspected. */
28
+ export interface UploadPart {
29
+ field: string;
30
+ filename: string;
31
+ contentType: string;
32
+ size: number;
33
+ open: () => AsyncIterable<Uint8Array>;
34
+ }
35
+ /**
36
+ * multipart/form-data with exactly one part, streamed from disk: nothing but the file is in memory at any
37
+ * time. Same transport rules as requestJson (trusted origin for the token, no redirects). The answer is
38
+ * JSON. `sent` is the length and sha256 of the bytes that actually left, counted while they streamed.
39
+ */
40
+ export declare function requestMultipart(fetchImpl: typeof fetch, raw: string, options: {
41
+ method?: string;
42
+ token?: string;
43
+ headers?: Record<string, string>;
44
+ env?: Environment;
45
+ file: UploadPart;
46
+ }): Promise<{
47
+ status: number;
48
+ body: unknown;
49
+ headers: Headers;
50
+ sent: {
51
+ bytes: number;
52
+ sha256: string;
53
+ };
54
+ }>;
55
+ /**
56
+ * GET that may answer with file bytes. A 2xx is the stream of the file (a JSON answer there is refused: the
57
+ * route is meant to return bytes); anything else is read as the usual JSON answer, so errors keep their shape.
58
+ */
59
+ export declare function requestBytes(fetchImpl: typeof fetch, raw: string, options: {
60
+ token?: string;
61
+ headers?: Record<string, string>;
62
+ env?: Environment;
63
+ }): Promise<{
64
+ kind: "bytes";
65
+ status: number;
66
+ headers: Headers;
67
+ stream: ReadableStream<Uint8Array>;
68
+ } | {
69
+ kind: "json";
70
+ status: number;
71
+ body: unknown;
72
+ headers: Headers;
73
+ }>;
74
+ export declare function requireSuccess(status: number): void;
75
+ export interface Envelope {
76
+ data: unknown;
77
+ context: Record<string, unknown>;
78
+ completeness: Record<string, unknown>;
79
+ notIncluded: unknown[];
80
+ provenance: Record<string, unknown>;
81
+ next: unknown[];
82
+ }
83
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
84
+ export declare function parseEnvelope(body: unknown): Envelope;
85
+ export declare function renderEnvelope(body: Envelope): string;
86
+ export declare function approvalResult(body: unknown, env?: Environment): {
87
+ status: "approval_required";
88
+ approvalRequest: unknown;
89
+ next: string;
90
+ warning?: string;
91
+ };
@@ -0,0 +1,103 @@
1
+ import { type ProductCatalog } from "./catalog";
2
+ import type { RunContext } from "./context";
3
+ import { type ExitCode } from "./core";
4
+ import type { GeneratedCommand } from "./openapi";
5
+ export declare const EXIT_CODES: {
6
+ "0": string;
7
+ "1": string;
8
+ "2": string;
9
+ };
10
+ export declare const ERROR_CODES: Record<string, string>;
11
+ /** Product catalogues plus the platform commands; platform spec operations covered by a platform command appear once. */
12
+ export declare function catalogWithPlatform(ctx: RunContext, only?: string[]): Promise<ProductCatalog[]>;
13
+ export declare function guideText(catalogs?: ProductCatalog[]): string;
14
+ export declare const HELP: {
15
+ name: string;
16
+ version: string;
17
+ usage: string;
18
+ commands: string[];
19
+ flags: string[];
20
+ credentials: string;
21
+ exitCodes: {
22
+ "0": string;
23
+ "1": string;
24
+ "2": string;
25
+ };
26
+ errorCodes: Record<string, string>;
27
+ };
28
+ export declare function guideCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
29
+ export declare function productSummary(c: ProductCatalog): {
30
+ liveSpec?: string | undefined;
31
+ warnings?: string[] | undefined;
32
+ error?: string | undefined;
33
+ product: string;
34
+ aliases: string[];
35
+ title: string;
36
+ origin: string | null;
37
+ operations: number;
38
+ writes: number;
39
+ source: import("./catalog").SpecSource | null;
40
+ approvals: string | null;
41
+ mcp: string | null;
42
+ };
43
+ export declare function productsCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
44
+ export declare function opsCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
45
+ /** Compact JSON Schema for reading: types, required, enums, short descriptions; depth-limited. */
46
+ export declare function compactSchema(schema: unknown, depth?: number): unknown;
47
+ /** A minimal valid-looking body: required fields only, from example/default/enum/const or a typed placeholder. */
48
+ export declare function exampleFrom(schema: unknown, name?: string, depth?: number): unknown;
49
+ export declare function describeCommand(command: GeneratedCommand, catalog: ProductCatalog): {
50
+ responses: {
51
+ status: string;
52
+ description: string;
53
+ }[];
54
+ examples: {
55
+ cli: string[];
56
+ curl: string;
57
+ };
58
+ origin: string | null;
59
+ catalog: import("./catalog").SpecSource | null;
60
+ multipart?: {
61
+ contentType: string;
62
+ parts: string;
63
+ note: string;
64
+ } | undefined;
65
+ body?: {
66
+ required: boolean;
67
+ schema: unknown;
68
+ example: unknown;
69
+ } | undefined;
70
+ dryRun: string;
71
+ idempotency: {
72
+ sent: boolean;
73
+ declared: boolean;
74
+ } | undefined;
75
+ positionals: {
76
+ description?: string | undefined;
77
+ name: string;
78
+ in: string;
79
+ required: boolean;
80
+ }[];
81
+ flags: {
82
+ description?: string | undefined;
83
+ name: string;
84
+ in: string;
85
+ required: boolean;
86
+ flag: string;
87
+ }[];
88
+ deprecated?: boolean | undefined;
89
+ status?: string | undefined;
90
+ scopes: string[];
91
+ cost: string;
92
+ approvalSource?: string | undefined;
93
+ approval: string;
94
+ tags?: string[] | undefined;
95
+ description?: string | undefined;
96
+ command: string;
97
+ product: string;
98
+ operationId: string;
99
+ method: string;
100
+ path: string;
101
+ summary: string;
102
+ };
103
+ export declare function describeOperationCommand(words: string[], ctx: RunContext): Promise<ExitCode>;
@@ -0,0 +1,25 @@
1
+ import type { Environment } from './config';
2
+ /**
3
+ * Product tokens come from the token broker.
4
+ * The broker is a confidential Keycloak client that does the standard token exchange (RFC 8693) for this person:
5
+ * login token in, a 5-minute token for exactly one product out. The CLI is a public client and may not do that itself.
6
+ */
7
+ export type TokenProduct = 'prudai' | 'irma' | 'ordo';
8
+ export declare const TOKEN_PRODUCTS: readonly TokenProduct[];
9
+ /** Which token a CLI product group needs: IRMA and ORDO have their own audience, everything else is the platform. */
10
+ export declare function tokenProductFor(product: string): TokenProduct;
11
+ export interface ProductToken {
12
+ token: string;
13
+ expiresAt: number;
14
+ audience?: string;
15
+ }
16
+ export declare function exchangeEndpoint(raw: string, env: Environment): string;
17
+ /** Asks the broker for a token for one product. Never sends anything but the login token and the product name. */
18
+ export declare function exchangeToken(options: {
19
+ fetch: typeof fetch;
20
+ env: Environment;
21
+ now: () => number;
22
+ url: string;
23
+ loginToken: string;
24
+ product: TokenProduct;
25
+ }): Promise<ProductToken>;
@@ -0,0 +1,57 @@
1
+ import { type Flags } from "./args";
2
+ import type { RunContext } from "./context";
3
+ import { CliError, type ExitCode } from "./core";
4
+ import { type GeneratedCommand } from "./openapi";
5
+ import { type LocalFile } from "./transfer";
6
+ /**
7
+ * API origin of a product, first hit wins: --api-url, PRUDAI_<PRODUCT>_API_URL,
8
+ * profile.productApiUrls, a product plugin, (platform) PRUDAI_API_URL/profile apiUrl, the
9
+ * registry default, and last the spec's own servers origin when that is https://*.prudai.com.
10
+ * Every origin still has to pass the token allowlist before a credential is attached.
11
+ */
12
+ export declare function resolveOrigin(product: string, ctx: Pick<RunContext, "flags" | "env" | "file" | "config" | "options">, spec?: unknown, useFlag?: boolean): string | undefined;
13
+ /**
14
+ * The token for one product: a short-lived, single-audience token from the broker, derived from the Keycloak login.
15
+ * There is no other credential: no API key, no personal token, no per-product key.
16
+ */
17
+ export declare function credentialFor(product: string, ctx: Pick<RunContext, "session">): Promise<string | undefined>;
18
+ export declare function missingCredential(_product?: string): CliError;
19
+ export declare function readData(flags: Flags): Promise<unknown>;
20
+ export interface ExecuteExtras {
21
+ /** Body built by a convenience command (merged under --data). */
22
+ body?: Record<string, unknown>;
23
+ /** Extra flags the calling command consumed itself. */
24
+ consumed?: string[];
25
+ /** A last local check of the final request body (flags merged over --data), before anything is sent. */
26
+ checkBody?: (body: unknown) => void;
27
+ /** Product for approval follow-ups, when it differs from operation.product. */
28
+ approvalsPath?: string;
29
+ /** A multipart upload of one local file. `target` says where it goes (shown in the dry run, which sends nothing). */
30
+ upload?: {
31
+ file: LocalFile;
32
+ target?: Record<string, unknown>;
33
+ };
34
+ /** The answer is the bytes of a file: written to `out`, never to stdout. */
35
+ download?: {
36
+ out: string;
37
+ force: boolean;
38
+ };
39
+ /** The answer is a text (a transcript): printed as plain text, or written to `out`. */
40
+ text?: {
41
+ out?: string;
42
+ force: boolean;
43
+ };
44
+ /** A removal that cannot be undone (purge): the dry run and the real run both say so. */
45
+ irreversible?: boolean;
46
+ /** A restore is accepted with HTTP 202 and the document in the answer (it is processed again in the background): that is a success, not an approval request. */
47
+ queued?: boolean;
48
+ /** The step that undoes or follows this one (a delete to the trash is followed by restore): in `next` and in the dry run text. */
49
+ after?: {
50
+ action: string;
51
+ why: string;
52
+ };
53
+ }
54
+ export declare function executeOperation(operation: GeneratedCommand, positionals: string[], origin: string | undefined, ctx: RunContext, extras?: ExecuteExtras): Promise<ExitCode>;
55
+ /** One error shape for HTTP failures: the server's own code and message when structured, else a hint per status. */
56
+ export declare function httpError(status: number, body: unknown, product?: string): CliError;
57
+ export declare function errorCodeOf(body: unknown): string | undefined;
@@ -0,0 +1,15 @@
1
+ export * from "./core";
2
+ export * from "./config";
3
+ export * from "./auth";
4
+ export * from "./openapi";
5
+ export * from "./cli";
6
+ export * from "./trust";
7
+ export * from "./version";
8
+ export * from "./products";
9
+ export * from "./catalog";
10
+ export * from "./scopes";
11
+ export * from "./output";
12
+ export { PLATFORM_OPS, bindOperation, type PlatformOp } from "./platform";
13
+ export { guideText, describeCommand, compactSchema, exampleFrom, EXIT_CODES, ERROR_CODES } from "./discovery";
14
+ export { skillMarkdown } from "./skill";
15
+ export { AUTH_OPERATIONS, EXCEPTIONS, CONSOLE_CAPABILITIES } from "./parity";