@north-light/sdk 0.0.0 → 0.3.415

package/dist/env-command.d.ts

@@ -0,0 +1,15 @@
+export declare const ENV_USAGE = "Usage: crouter-sdk env --app <client id> [--out <path>]";
+/** The variables `env` owns, in the order it writes them. `CROUTER_KEY_FILE` is never one. */
+declare const NAMES: readonly ["CROUTER_ISSUER", "CROUTER_CLIENT_ID", "APP_ORIGIN"];
+type Name = typeof NAMES[number];
+export interface EnvOptions {
+    /** How long `crtr cloud apps get` may run before env gives up. */
+    crtrTimeoutMs?: number;
+}
+/** Rewrites each assignment to a name in `values`, appends the names it had none for, and keeps every other line. */
+export declare function updateEnvText(text: string, values: Record<Name, string>): string;
+/** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
+export declare function keyFileOf(text: string): string | undefined;
+/** The `crouter-sdk env` command. Returns the process exit code. */
+export declare function runEnv(argv: string[], options?: EnvOptions): Promise<number>;
+export {};

package/dist/env-command.js

@@ -0,0 +1,138 @@
+import { mkdir, open, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { CRTR_TIMEOUT_MS, notJoinedLines, parseJson, runCrtr, say } from './crtr.js';
+export const ENV_USAGE = 'Usage: crouter-sdk env --app <client id> [--out <path>]';
+const DEFAULT_KEY_FILE = 'local/app-key.json';
+/** The variables `env` owns, in the order it writes them. `CROUTER_KEY_FILE` is never one. */
+const NAMES = ['CROUTER_ISSUER', 'CROUTER_CLIENT_ID', 'APP_ORIGIN'];
+function parseArgs(args) {
+    if (args[0] !== 'env')
+        throw new Error(ENV_USAGE);
+    let path = 'local/app.env';
+    let app;
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        const value = args[++i];
+        if (seen.has(flag) || (flag !== '--out' && flag !== '--app') || !value || value.startsWith('--'))
+            throw new Error(ENV_USAGE);
+        seen.add(flag);
+        if (flag === '--out')
+            path = value;
+        else
+            app = value;
+    }
+    if (!app)
+        throw new Error(ENV_USAGE);
+    return { path, app };
+}
+/** One `NAME=value` assignment line, with an optional `export ` prefix. */
+const ASSIGNMENT = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=)(.*)$/;
+/** A value is written bare when a dotenv reader and a shell both read it back unchanged. */
+const formatValue = (value) => (/^[A-Za-z0-9_\-.:/@%+,~]*$/.test(value) ? value : JSON.stringify(value));
+/** The value of a dotenv assignment's right-hand side: quotes removed, a trailing comment dropped. */
+function readValue(raw) {
+    const text = raw.trim();
+    const quote = text[0];
+    if ((quote === '"' || quote === "'") && text.indexOf(quote, 1) > 0) {
+        const inner = text.slice(1, text.indexOf(quote, 1));
+        if (quote === "'")
+            return inner;
+        try {
+            return JSON.parse(`"${inner}"`);
+        }
+        catch {
+            return inner;
+        }
+    }
+    return text.replace(/\s+#.*$/, '');
+}
+/** Rewrites each assignment to a name in `values`, appends the names it had none for, and keeps every other line. */
+export function updateEnvText(text, values) {
+    const lines = text === '' ? [] : text.replace(/\n$/, '').split('\n');
+    const written = new Set();
+    const out = lines.map((line) => {
+        const match = ASSIGNMENT.exec(line);
+        const name = match?.[2];
+        if (!match || !name || !NAMES.includes(name))
+            return line;
+        written.add(name);
+        return `${match[1]}${name}${match[3]}${formatValue(values[name])}`;
+    });
+    for (const name of NAMES)
+        if (!written.has(name))
+            out.push(`${name}=${formatValue(values[name])}`);
+    return `${out.join('\n')}\n`;
+}
+/** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
+export function keyFileOf(text) {
+    let found;
+    for (const line of text.split('\n')) {
+        const match = ASSIGNMENT.exec(line);
+        if (match?.[2] === 'CROUTER_KEY_FILE')
+            found = readValue(match[4] ?? '');
+    }
+    return found || undefined;
+}
+function envOf(answer) {
+    const env = answer?.env;
+    if (!env || typeof env !== 'object')
+        return undefined;
+    const values = {};
+    for (const name of NAMES) {
+        const value = env[name];
+        if (typeof value !== 'string' || !value)
+            return undefined;
+        values[name] = value;
+    }
+    return values;
+}
+const byHand = (path) => `Set ${NAMES.join(', ')} in ${path} by hand: \`crtr cloud apps get --app-id <client id>\` shows them under env.`;
+/** The `crouter-sdk env` command. Returns the process exit code. */
+export async function runEnv(argv, options = {}) {
+    const { path, app } = parseArgs(argv);
+    const outcome = await runCrtr(['cloud', 'apps', 'get', '--app-id', app, '--json'], options.crtrTimeoutMs ?? CRTR_TIMEOUT_MS);
+    if (outcome.kind === 'missing') {
+        say(["Couldn't find crtr, so nothing was written.", byHand(path)]);
+        return 2;
+    }
+    if (outcome.kind === 'not_joined') {
+        say(notJoinedLines('nothing was written', outcome.joinStep));
+        return 2;
+    }
+    if (outcome.kind === 'failed') {
+        say([`Couldn't read ${app}: ${outcome.message}`, 'Nothing was written.']);
+        return 2;
+    }
+    const values = envOf(parseJson(outcome.stdout));
+    if (!values) {
+        const last = outcome.stdout.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+        say([`crtr answered without the app's env: ${last ?? '(no output)'}`, 'Nothing was written.']);
+        return 2;
+    }
+    const existing = await readFile(path, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    const next = updateEnvText(existing ?? '', values);
+    if (existing === undefined) {
+        await mkdir(dirname(path), { recursive: true });
+        const file = await open(path, 'wx', 0o600);
+        try {
+            await file.writeFile(next);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    else if (next !== existing) {
+        await writeFile(path, next);
+    }
+    say([
+        `Set in ${path}:`,
+        ...NAMES.map((name) => `  ${name}=${values[name]}`),
+        `Key file: ${keyFileOf(next) ?? DEFAULT_KEY_FILE} (set CROUTER_KEY_FILE to change it).`,
+    ]);
+    return 0;
+}

package/dist/error-codes.d.ts

@@ -0,0 +1,7 @@
+export { errorCodes } from '@north-light/api';
+export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from '@north-light/api';
+export { mapError } from './errors.js';
+/** Codes the SDK raises itself rather than reading from a daemon or directory response. */
+export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "not_connected", "refusal_handler_reentry", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "deadline_exceeded", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "runtime_version_unsupported", "invalid_response", "stream_error", "stream_ended"];
+/** A code the SDK raises itself. An `APIError`'s `code` is one of these or an `ErrorCode` from the contract. */
+export type SdkErrorCode = typeof sdkErrorCodes[number];

package/dist/error-codes.js

@@ -0,0 +1,43 @@
+// The API contract owns the daemon's table; the SDK adds the codes it raises itself.
+export { errorCodes } from '@north-light/api';
+export { mapError } from './errors.js';
+/** Codes the SDK raises itself rather than reading from a daemon or directory response. */
+export const sdkErrorCodes = [
+    /** A `CrouterError` configuration or protocol failure with no more specific code. */
+    'crouter_error',
+    /** An ID token was missing, failed verification, or its nonce did not match. */
+    'id_token_invalid',
+    /** `exchangeIdentity` was called without the nonce `authorizeUrl` returned. */
+    'oauth_nonce_missing',
+    /** The callback's `state` was missing or differed from the saved one. */
+    'oauth_state_mismatch',
+    /** `exchangeCode` got a sign-in-only answer, or `exchangeIdentity` got one carrying a connection. */
+    'oauth_exchange_mismatch',
+    /** `oauth.client(userId)` or `refresh` found no stored connection for the person: they must sign in again. */
+    'not_connected',
+    /** `onRefusal` called `oauth.client` (or `refresh`) for the user whose dead connection it is handling. */
+    'refusal_handler_reentry',
+    /** `runs.parse`: the run stopped without settling. */
+    'run_idle',
+    /** `runs.parse`: the run waits on a question and no `onQuestion` was given. */
+    'waiting_on_user',
+    /** The caller's `AbortSignal` fired (`APIUserAbortError`). */
+    'request_aborted',
+    /** The request exceeded its timeout (`APIConnectionTimeoutError`). */
+    'request_timeout',
+    /** The call's overall deadline passed, or a retry wait would have passed it (`DeadlineExceededError`). */
+    'deadline_exceeded',
+    /** The daemon could not be reached, or the connection failed (`APIConnectionError`). */
+    'connection_error',
+    'transport_error',
+    'daemon_unavailable',
+    'daemon_request_interrupted',
+    'daemon_health_unavailable',
+    /** The runtime is older than this SDK, or sent no `Crouter-Runtime-Version` (`RuntimeVersionError`). */
+    'runtime_version_unsupported',
+    /** A response the SDK could not read as the API's JSON or error envelope. */
+    'invalid_response',
+    /** An event stream failed, or ended before the reply or node it carried did. */
+    'stream_error',
+    'stream_ended',
+];

package/dist/errors.d.ts

@@ -0,0 +1,72 @@
+import { APIError } from '@north-light/api';
+import type { SdkErrorCode } from './error-codes.js';
+export { APIError };
+/** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
+export declare class CrouterError extends APIError {
+    readonly code: SdkErrorCode;
+    constructor(message: string, code?: SdkErrorCode);
+}
+/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
+ *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+ *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
+export declare class RuntimeVersionError extends APIError {
+    /** The oldest runtime this SDK accepts: its own release version. */
+    get sdkVersion(): string;
+    /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
+    get runtimeVersion(): string | null;
+}
+/** `RuntimeVersionError.details`. */
+export interface RuntimeVersionDetails {
+    sdk_version: string;
+    runtime_version: string | null;
+}
+/** The daemon rejected the request: HTTP 400. */
+export declare class BadRequestError extends APIError {
+}
+/** The token was missing or wrong: HTTP 401. */
+export declare class AuthenticationError extends APIError {
+}
+/** The caller is not allowed to do this: HTTP 403. */
+export declare class PermissionDeniedError extends APIError {
+}
+/** No such node, profile, cron, or other resource: HTTP 404. */
+export declare class NotFoundError extends APIError {
+}
+/** The resource is in a state that forbids the request: HTTP 409. */
+export declare class ConflictError extends APIError {
+}
+/** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
+export declare class UnprocessableEntityError extends APIError {
+}
+/** Too many requests: HTTP 429. */
+export declare class RateLimitError extends APIError {
+}
+/** The daemon failed while handling the request: HTTP 500 and above. */
+export declare class InternalServerError extends APIError {
+}
+/** The daemon could not be reached, or the connection failed mid-request. */
+export declare class APIConnectionError extends APIError {
+}
+/** The request exceeded its timeout before the daemon answered. */
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+}
+/** The call's overall deadline (`budgetMs` / `deadlineAt`) passed, or the next retry wait would have passed it.
+ *  `status` 504, `code` `deadline_exceeded`. `deadlineAt` is the instant (epoch ms); `reason` is `elapsed` (time ran out)
+ *  or `retry_after` (the server asked for a wait longer than the time left, so the call stopped without sleeping;
+ *  `retryAfterS` is that request). `cause` is the last failure, when there was one. */
+export declare class DeadlineExceededError extends APIConnectionTimeoutError {
+    get deadlineAt(): number;
+    get reason(): 'elapsed' | 'retry_after';
+    get retryAfterRequestS(): number | undefined;
+}
+/** `DeadlineExceededError.details`. */
+export interface DeadlineDetails {
+    deadline_at: number;
+    reason: 'elapsed' | 'retry_after';
+    retry_after_s?: number;
+}
+/** The caller's `AbortSignal` fired. */
+export declare class APIUserAbortError extends APIError {
+}
+/** Maps a transport failure or a plain `APIError` onto the specific class for its status and code. */
+export declare function mapError(error: unknown): APIError;

package/dist/errors.js

@@ -0,0 +1,101 @@
+import { APIError } from '@north-light/api';
+export { APIError };
+/** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
+export class CrouterError extends APIError {
+    constructor(message, code = 'crouter_error') {
+        super(0, code, message);
+        this.name = 'CrouterError';
+    }
+}
+/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
+ *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+ *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
+export class RuntimeVersionError extends APIError {
+    /** The oldest runtime this SDK accepts: its own release version. */
+    get sdkVersion() { return this.details.sdk_version; }
+    /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
+    get runtimeVersion() { return this.details.runtime_version; }
+}
+/** The daemon rejected the request: HTTP 400. */
+export class BadRequestError extends APIError {
+}
+/** The token was missing or wrong: HTTP 401. */
+export class AuthenticationError extends APIError {
+}
+/** The caller is not allowed to do this: HTTP 403. */
+export class PermissionDeniedError extends APIError {
+}
+/** No such node, profile, cron, or other resource: HTTP 404. */
+export class NotFoundError extends APIError {
+}
+/** The resource is in a state that forbids the request: HTTP 409. */
+export class ConflictError extends APIError {
+}
+/** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
+export class UnprocessableEntityError extends APIError {
+}
+/** Too many requests: HTTP 429. */
+export class RateLimitError extends APIError {
+}
+/** The daemon failed while handling the request: HTTP 500 and above. */
+export class InternalServerError extends APIError {
+}
+/** The daemon could not be reached, or the connection failed mid-request. */
+export class APIConnectionError extends APIError {
+}
+/** The request exceeded its timeout before the daemon answered. */
+export class APIConnectionTimeoutError extends APIConnectionError {
+}
+/** The call's overall deadline (`budgetMs` / `deadlineAt`) passed, or the next retry wait would have passed it.
+ *  `status` 504, `code` `deadline_exceeded`. `deadlineAt` is the instant (epoch ms); `reason` is `elapsed` (time ran out)
+ *  or `retry_after` (the server asked for a wait longer than the time left, so the call stopped without sleeping;
+ *  `retryAfterS` is that request). `cause` is the last failure, when there was one. */
+export class DeadlineExceededError extends APIConnectionTimeoutError {
+    get deadlineAt() { return this.details.deadline_at; }
+    get reason() { return this.details.reason; }
+    get retryAfterRequestS() { return this.details.retry_after_s; }
+}
+/** The caller's `AbortSignal` fired. */
+export class APIUserAbortError extends APIError {
+}
+/** Maps a transport failure or a plain `APIError` onto the specific class for its status and code. */
+export function mapError(error) {
+    if (!(error instanceof APIError) || error.constructor !== APIError) {
+        return error instanceof APIError ? error : new APIConnectionError(0, 'connection_error', error instanceof Error ? error.message : String(error));
+    }
+    const Constructor = error.code === 'runtime_version_unsupported'
+        ? RuntimeVersionError
+        : error.code === 'deadline_exceeded'
+            ? DeadlineExceededError
+            : error.code === 'request_aborted'
+                ? APIUserAbortError
+                : error.status === 504 || error.code === 'request_timeout'
+                    ? APIConnectionTimeoutError
+                    : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
+                        ? APIConnectionError
+                        : error.status === 400
+                            ? BadRequestError
+                            : error.status === 401
+                                ? AuthenticationError
+                                : error.status === 403
+                                    ? PermissionDeniedError
+                                    : error.status === 404
+                                        ? NotFoundError
+                                        : error.status === 409
+                                            ? ConflictError
+                                            : error.status === 413 || error.status === 422
+                                                ? UnprocessableEntityError
+                                                : error.status === 402 || error.status === 429
+                                                    ? RateLimitError
+                                                    : error.status >= 500
+                                                        ? InternalServerError
+                                                        : APIError;
+    const mapped = new Constructor(error.status, error.code, error.message, error.details, error.headers, {
+        type: error.type, param: error.param, origin: error.origin, retryable: error.retryable,
+        retry_after_s: error.retryAfterS, reset_at: error.resetAt, request_id: error.requestId, run_id: error.runId,
+        question_id: error.questionId, scope: error.scope, user_action: error.userAction,
+    });
+    if (error.cause !== undefined)
+        Object.defineProperty(mapped, 'cause', { value: error.cause, configurable: true, writable: true });
+    return mapped;
+}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+export { Crouter as default, Crouter } from './client.js';
+export type { CrouterOptions } from './client.js';
+export { NodeStream } from './resources/node-stream.js';
+export { RunStream } from './resources/run-stream.js';
+export { CustomObjects } from './resources/custom-objects.js';
+export type { CustomDeliveryStream, ReceiveOptions } from './resources/custom-objects.js';
+export type { RunEvent, RunEventListener, RunEventOf, RunEventType, RunStreamEnd, UnknownRunEvent } from './resources/run-stream.js';
+export { RunReply } from './resources/run-reply.js';
+export type { RunReplyCollectOptions, RunReplyEnding, RunReplyEvent, RunReplyResult, SentRunMessage } from './resources/run-reply.js';
+export type { AppProfile, RunActivity, RunDeleteResult, RunObject, RunParsedOutcome, RunParseOptions, RunParseParams, RunStartParams, RunStartResult, RunStatus, RunTrace } from './resources/runs.js';
+export type { FileDownloadOptions } from './resources/files.js';
+export type { Upload, UploadCreateParams } from './resources/uploads.js';
+export type { AttachmentLink } from './resources/attachments.js';
+export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.js';
+export type { MemoryDocument, MemoryGetParams, MemoryListItem, MemoryListPage, MemoryListParams } from './resources/memory.js';
+export type { Question, QuestionAnswered, QuestionFields, QuestionResponses, QuestionSlot, QuestionStatus } from './resources/questions.js';
+export type { ProviderToolEntry } from './resources/providers.js';
+export { OAuth2Client, ConnectedCrouter, DEFAULT_DIRECTORY_TIMEOUT_MS, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refusalOf } from './oauth/index.js';
+export type { RefreshFailure, Refusal, RefusalKind } from './oauth/index.js';
+export { RunWatcher } from './resources/run-watcher.js';
+export type { PendingRun, RunActivityEvent, RunEnded, RunEnding, RunWatchOptions } from './resources/run-watcher.js';
+export { GrantWatcher } from './resources/grant-watcher.js';
+export type { GrantChanged, GrantWatchOptions } from './resources/grant-watcher.js';
+export { generateKeyPair } from './oauth/keygen.js';
+export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
+export type { AuthorizeNonce, Connection, ConnectionStore, Identity, OAuth2Options } from './oauth/index.js';
+export type { IdTokenClaims } from '@north-light/identity';
+export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { RUN_NOTICE_SCOPE, RunNoticeError, verifyRunNotice } from './resources/run-notice.js';
+export type { RunNotice, VerifyRunNoticeOptions } from './resources/run-notice.js';
+export type { NodeStreamEvent, NodeStreamEventListener, NodeStreamEventType } from './resources/node-stream.js';
+export { describeToolDefault, followActivity } from './resources/activity.js';
+export type { ActivityStep, DescribeTool } from './resources/activity.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, DeadlineExceededError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export type { DeadlineDetails, RuntimeVersionDetails } from './errors.js';
+export { SDK_VERSION } from './version.js';
+export { sdkErrorCodes } from './error-codes.js';
+export type { SdkErrorCode } from './error-codes.js';
+export type { AuthStatus, AuthStatusParams, CancelParams, EnsureProfileParams, JsonSchema, MessageParams, NodeCreateParams, NodeEventsOptions, NodeOutcomeOptions, OutputSchema, ParsedOutcome, RequestOptions, SchemaOutput, } from './types.js';
+export type * from '@north-light/api';

package/dist/index.js

@@ -0,0 +1,17 @@
+export { Crouter as default, Crouter } from './client.js';
+export { NodeStream } from './resources/node-stream.js';
+export { RunStream } from './resources/run-stream.js';
+export { CustomObjects } from './resources/custom-objects.js';
+export { RunReply } from './resources/run-reply.js';
+export { OAuth2Client, ConnectedCrouter, DEFAULT_DIRECTORY_TIMEOUT_MS, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refusalOf } from './oauth/index.js';
+export { RunWatcher } from './resources/run-watcher.js';
+export { GrantWatcher } from './resources/grant-watcher.js';
+export { generateKeyPair } from './oauth/keygen.js';
+export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
+export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { RUN_NOTICE_SCOPE, RunNoticeError, verifyRunNotice } from './resources/run-notice.js';
+export { describeToolDefault, followActivity } from './resources/activity.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, DeadlineExceededError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export { SDK_VERSION } from './version.js';
+export { sdkErrorCodes } from './error-codes.js';

package/dist/keygen-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/keygen-cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The `crouter-sdk` bin: `keygen` and `env`. The file keeps its first command's name because the
+// published bin path (`dist/keygen-cli.js`) is part of the package.
+import { runEnv } from './env-command.js';
+import { runKeygen } from './keygen-command.js';
+const args = process.argv.slice(2);
+const run = args[0] === 'env' ? runEnv(args) : runKeygen(args);
+run.then((code) => { process.exitCode = code; }, (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/keygen-command.d.ts

@@ -0,0 +1,6 @@
+export interface KeygenOptions {
+    /** How long `crtr cloud apps keys add` may run before keygen gives up. */
+    crtrTimeoutMs?: number;
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export declare function runKeygen(argv: string[], options?: KeygenOptions): Promise<number>;

package/dist/keygen-command.js

@@ -0,0 +1,131 @@
+import { mkdir, open, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { CRTR_TIMEOUT_MS, notJoinedLines, parseJson, runCrtr, say } from './crtr.js';
+import { generateKeyPair } from './oauth/keygen.js';
+const USAGE = 'Usage: crouter-sdk keygen [--out <path>] [--app <client id>] [--yes]';
+function parseArgs(args) {
+    if (args[0] !== 'keygen')
+        throw new Error(USAGE);
+    const parsed = { path: 'local/app-key.json', yes: false };
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        if (seen.has(flag))
+            throw new Error(USAGE);
+        seen.add(flag);
+        if (flag === '--yes') {
+            parsed.yes = true;
+            continue;
+        }
+        const value = args[++i];
+        if ((flag !== '--out' && flag !== '--app') || !value || value.startsWith('--'))
+            throw new Error(USAGE);
+        if (flag === '--out')
+            parsed.path = value;
+        else
+            parsed.app = value;
+    }
+    return parsed;
+}
+const manualSteps = (path) => [
+    'Next, in this order:',
+    "  1. Add the public JWK printed on stdout as a key: click Add key on your app's Sign-in tab in the console, or paste it under Register an app for a new app. Adding a key never replaces your current one.",
+    `  2. Then point your app's privateKey at ${path} and deploy.`,
+    '  3. Once a real sign-in works, retire the old key on the Sign-in tab.',
+];
+const addedSteps = (path, app) => [
+    'Next, in this order:',
+    `  1. Point your app's privateKey at ${path} and deploy.`,
+    '  2. Check that a real sign-in works.',
+    `  3. Retire the old key: on the app's Sign-in tab, or \`crtr cloud apps keys retire --app-id ${app} --kid <old kid>\` (\`crtr cloud apps keys list --app-id ${app}\` shows the kids).`,
+];
+/** Asks on stderr; resolves true only for Enter or y/yes. End of input declines. */
+function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        let answered = false;
+        rl.on('close', () => { if (!answered) {
+            process.stderr.write('\n');
+            resolve(false);
+        } });
+        rl.question(`${question} `, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(/^(y|yes)?$/i.test(answer.trim()));
+        });
+    });
+}
+/** Runs `crtr cloud apps keys add` once. */
+async function addKey(app, publicJwk, timeoutMs) {
+    const outcome = await runCrtr(['cloud', 'apps', 'keys', 'add', '--app-id', app, '--jwk', publicJwk, '--json'], timeoutMs);
+    if (outcome.kind !== 'ok')
+        return outcome;
+    const answer = parseJson(outcome.stdout);
+    if (typeof answer?.kid !== 'string') {
+        const last = outcome.stdout.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+        return { kind: 'failed', message: `crtr answered without the added key: ${last ?? '(no output)'}` };
+    }
+    return { kind: 'added', kid: answer.kid, created: answer.created !== false };
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export async function runKeygen(argv, options = {}) {
+    const { path, app, yes } = parseArgs(argv);
+    await mkdir(dirname(path), { recursive: true });
+    // Reserve the destination before generating or printing the public key; never truncate an existing key.
+    const file = await open(path, 'wx', 0o600).catch((error) => {
+        if (error.code === 'EEXIST')
+            throw new Error(`${path} already exists. Delete it or pass --out to write somewhere else.`);
+        throw error;
+    });
+    let publicJwk;
+    let kid;
+    try {
+        const pair = await generateKeyPair();
+        await file.writeFile(`${JSON.stringify(pair.privateJwk)}\n`);
+        ({ publicJwk, kid } = pair);
+    }
+    catch (error) {
+        await file.close();
+        await unlink(path);
+        throw error;
+    }
+    await file.close();
+    const publicLine = JSON.stringify(publicJwk);
+    console.error(`Saved the private key to ${path} (key id ${kid}). Keep it out of git.`);
+    console.log(publicLine);
+    if (!app) {
+        say([...manualSteps(path), 'Tip: pass --app <client id> to add the key with crtr.']);
+        return 0;
+    }
+    if (!yes) {
+        if (!process.stdin.isTTY || !process.stderr.isTTY) {
+            say(['Not adding the key: no terminal to confirm. Pass --yes to add it with crtr.', ...manualSteps(path)]);
+            return 0;
+        }
+        if (!(await confirm(`Add this key to ${app} as an additional key? Your current key keeps working. [Y/n]`))) {
+            say(manualSteps(path));
+            return 0;
+        }
+    }
+    const outcome = await addKey(app, publicLine, options.crtrTimeoutMs ?? CRTR_TIMEOUT_MS);
+    if (outcome.kind === 'missing') {
+        say(["Couldn't find crtr, so the key was not added.", ...manualSteps(path)]);
+        return 0;
+    }
+    if (outcome.kind === 'not_joined') {
+        say([...notJoinedLines('the key was not added', outcome.joinStep), ...manualSteps(path)]);
+        return 2;
+    }
+    if (outcome.kind === 'failed') {
+        say([`Couldn't add the key: ${outcome.message}`, ...manualSteps(path)]);
+        return 2;
+    }
+    say([
+        outcome.created
+            ? `Added key ${outcome.kid} to ${app} as an additional key. Your current key still works.`
+            : `Key ${outcome.kid} is already on ${app}.`,
+        ...addedSteps(path, app),
+    ]);
+    return 0;
+}