@kora-platform/cli 0.8.0-rc3 → 0.8.0-rc7

package/dist/api-client.d.ts

@@ -1,11 +1,22 @@
 import type { AbortRuntimeRunResult, AgentUsageReport, ApiKeyRecord, AuditEventListResult, AuditEventRecord, AuditOutcome, AuthoringOrganizationManagementContext, CapabilityEditorRecord, ChatHealth, ChatSessionRecord, ChatSessionSummary, CreateReleaseResult, CompleteRuntimeTaskResult, DeletedOrganizationDetail, DeletedOrganizationSummary, EnvironmentDeploymentRecord, EnvironmentDetailRecord, EnvironmentRecord, BuiltInExtensionRecord, ExtensionInstallDetailRecord, ExtensionInstallRecord, ExtensionInstallUpdatePlan, ExtensionPackageExportEnvelope, ExtensionPackageFileInput, ExtensionPackageRecord, ExtensionPackageRevisionRecord, ExtensionPackageValidationResult, ExtensionPermissions, InviteRecord, MembershipRecord, OperationsEditorRecord, WorkflowNodeTestResult, OrganizationRecord, OrganizationWithRoleRecord, OrgSecretRecord, OrgSettingsRecord, ProcessDefinitionDetail, ProcessDefinitionRecord, ProcessDefinitionSummary, ReleaseSourceSnapshotRecord, ReleaseValidationResult, ReleaseSummaryRecord, RuntimeControlActivityFocusType, RuntimeControlActivityReadResult, RuntimeControlOverviewRecord, RuntimeControlRunDetailRecord, RuntimeControlRunRecord, RuntimeControlRunStateRecord, RuntimeControlRunStepRecord, RuntimeControlStartProcessResult, RuntimeControlTaskRecord, RuntimeVariableRecord, WorkflowDependencySummary, WorkflowInspectionContext } from "./api-types.js";
 import type { CliSessionState } from "./transport.js";
 import { createPlatformTransport } from "./transport.js";
+export type ReleaseSnapshotSelectorInput = {
+    environment: string;
+    releaseId?: never;
+} | {
+    environment?: never;
+    releaseId: string;
+};
 export interface PlatformApiClientInput {
     now?: () => number;
     sessionStore: Parameters<typeof createPlatformTransport>[0]["sessionStore"];
 }
 export declare function createPlatformApiClient(input: PlatformApiClientInput): {
+    claimDeviceLogin: (claim: {
+        baseUrl: string;
+        deviceCode: string;
+    }) => Promise<import("./transport.js").CliDeviceLoginClaim>;
     getAuthSettings: (baseUrl: string) => Promise<import("./transport.js").CliAuthSettings>;
     login: (credentials: {
         baseUrl: string;
@@ -19,6 +30,7 @@ export declare function createPlatformApiClient(input: PlatformApiClientInput):
         name: string;
         password: string;
     }) => Promise<CliSessionState>;
+    startDeviceLogin: (baseUrl: string) => Promise<import("./transport.js").CliDeviceLoginStart>;
     getMe(session: CliSessionState): Promise<{
         user: {
             email: string;
@@ -84,6 +96,13 @@ export declare function createPlatformApiClient(input: PlatformApiClientInput):
     }): Promise<{
         variables: RuntimeVariableRecord[];
     }>;
+    upsertRuntimeVariable(session: CliSessionState, orgId: string, inputData: {
+        environment: string;
+        name: string;
+        value: string;
+    }): Promise<{
+        variable: RuntimeVariableRecord;
+    }>;
     listOrgSecrets(session: CliSessionState, orgId: string, inputData?: {
         environment?: string;
     }): Promise<{
@@ -216,19 +235,23 @@ export declare function createPlatformApiClient(input: PlatformApiClientInput):
     deleteExtensionInstall(session: CliSessionState, orgId: string, installRef: string, inputData: {
         environment: string;
     }): Promise<void>;
-    listWorkflows(session: CliSessionState, orgId: string, releaseId?: string): Promise<{
+    listWorkflows(session: CliSessionState, orgId: string, inputData: {
+        environment?: never;
+        live: true;
+        releaseId?: never;
+    } | ReleaseSnapshotSelectorInput): Promise<{
         processes: ProcessDefinitionSummary[];
     }>;
-    getWorkflow(session: CliSessionState, orgId: string, name: string, releaseId?: string): Promise<{
+    getWorkflow(session: CliSessionState, orgId: string, name: string, selector: ReleaseSnapshotSelectorInput): Promise<{
         process: ProcessDefinitionDetail;
     }>;
-    getWorkflowVersion(session: CliSessionState, orgId: string, name: string, version: number, releaseId?: string): Promise<{
+    getWorkflowVersion(session: CliSessionState, orgId: string, name: string, version: number, selector: ReleaseSnapshotSelectorInput): Promise<{
         process: ProcessDefinitionRecord;
     }>;
-    getWorkflowDependencies(session: CliSessionState, orgId: string, name: string, version: number, releaseId?: string): Promise<{
+    getWorkflowDependencies(session: CliSessionState, orgId: string, name: string, version: number, selector: ReleaseSnapshotSelectorInput): Promise<{
         dependencies: WorkflowDependencySummary;
     }>;
-    getWorkflowContext(session: CliSessionState, orgId: string, releaseId?: string): Promise<{
+    getWorkflowContext(session: CliSessionState, orgId: string, selector: ReleaseSnapshotSelectorInput): Promise<{
         context: WorkflowInspectionContext;
     }>;
     startWorkflow(session: CliSessionState, orgId: string, name: string, inputData?: {
@@ -242,13 +265,13 @@ export declare function createPlatformApiClient(input: PlatformApiClientInput):
     }): Promise<{
         started: RuntimeControlStartProcessResult;
     }>;
-    getOrganizationManagementContext(session: CliSessionState, orgId: string): Promise<{
+    getOrganizationManagementContext(session: CliSessionState, orgId: string, selector: ReleaseSnapshotSelectorInput): Promise<{
         context: AuthoringOrganizationManagementContext;
     }>;
-    getCapabilityEditor(session: CliSessionState, orgId: string, name: string): Promise<{
+    getCapabilityEditor(session: CliSessionState, orgId: string, name: string, selector: ReleaseSnapshotSelectorInput): Promise<{
         editor: CapabilityEditorRecord;
     }>;
-    getOperationsEditor(session: CliSessionState, orgId: string): Promise<{
+    getOperationsEditor(session: CliSessionState, orgId: string, selector: ReleaseSnapshotSelectorInput): Promise<{
         editor: OperationsEditorRecord;
     }>;
     getOverview(session: CliSessionState, orgId: string): Promise<{
@@ -341,9 +364,7 @@ export declare function createPlatformApiClient(input: PlatformApiClientInput):
     listEnvironments(session: CliSessionState, orgId: string): Promise<{
         environments: EnvironmentDetailRecord[];
     }>;
-    getEnvironment(session: CliSessionState, orgId: string, environment: string): Promise<{
-        environment: EnvironmentDetailRecord;
-    }>;
+    getEnvironment(session: CliSessionState, orgId: string, environment: string): Promise<EnvironmentDetailRecord>;
     createEnvironment(session: CliSessionState, orgId: string, inputData: {
         copyFromEnvironmentId?: string;
         key: string;
@@ -386,12 +407,10 @@ export declare function createPlatformApiClient(input: PlatformApiClientInput):
             content: string;
             path: string;
         }>;
-        label?: string;
     }): Promise<{
         created: CreateReleaseResult;
     }>;
     createReleaseArchive(session: CliSessionState, orgId: string, archive: Uint8Array, inputData?: {
-        label?: string;
         subdir?: string;
     }): Promise<{
         created: CreateReleaseResult;

package/dist/api-client.js

@@ -5,10 +5,12 @@ export function createPlatformApiClient(input) {
     const artifactApi = createArtifactApiClient(transport);
     return {
         ...artifactApi,
+        claimDeviceLogin: transport.claimDeviceLogin,
         getAuthSettings: transport.getAuthSettings,
         login: transport.login,
         refreshSession: transport.refreshSession,
         signup: transport.signup,
+        startDeviceLogin: transport.startDeviceLogin,
         async getMe(session) {
             return transport.requestJson({
                 path: "/api/v1/auth/me",
@@ -96,6 +98,15 @@ export function createPlatformApiClient(input) {
                 session
             });
         },
+        async upsertRuntimeVariable(session, orgId, inputData) {
+            const { environment, name, value } = inputData;
+            return transport.requestJson({
+                body: { value },
+                method: "PUT",
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/runtime-variables/${encodeURIComponent(name)}`, { environment }),
+                session
+            });
+        },
         async listOrgSecrets(session, orgId, inputData = {}) {
             return transport.requestJson({
                 path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/secrets`, inputData),
@@ -255,37 +266,36 @@ export function createPlatformApiClient(input) {
                 session
             });
         },
-        async listWorkflows(session, orgId, releaseId) {
+        async listWorkflows(session, orgId, inputData) {
             return transport.requestJson({
                 path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes`, {
-                    releaseId
+                    environment: inputData.environment,
+                    releaseId: inputData.releaseId
                 }),
                 session
             });
         },
-        async getWorkflow(session, orgId, name, releaseId) {
+        async getWorkflow(session, orgId, name, selector) {
             return transport.requestJson({
-                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes/${encodeURIComponent(name)}`, { releaseId }),
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes/${encodeURIComponent(name)}`, selector),
                 session
             });
         },
-        async getWorkflowVersion(session, orgId, name, version, releaseId) {
+        async getWorkflowVersion(session, orgId, name, version, selector) {
             return transport.requestJson({
-                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes/${encodeURIComponent(name)}/versions/${String(version)}`, { releaseId }),
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes/${encodeURIComponent(name)}/versions/${String(version)}`, selector),
                 session
             });
         },
-        async getWorkflowDependencies(session, orgId, name, version, releaseId) {
+        async getWorkflowDependencies(session, orgId, name, version, selector) {
             return transport.requestJson({
-                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes/${encodeURIComponent(name)}/versions/${String(version)}/dependencies`, { releaseId }),
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/processes/${encodeURIComponent(name)}/versions/${String(version)}/dependencies`, selector),
                 session
             });
         },
-        async getWorkflowContext(session, orgId, releaseId) {
+        async getWorkflowContext(session, orgId, selector) {
             return transport.requestJson({
-                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/workflows/context`, {
-                    releaseId
-                }),
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/workflows/context`, selector),
                 session
             });
         },
@@ -297,21 +307,21 @@ export function createPlatformApiClient(input) {
                 session
             });
         },
-        async getOrganizationManagementContext(session, orgId) {
+        async getOrganizationManagementContext(session, orgId, selector) {
             return transport.requestJson({
-                path: `/api/v1/orgs/${encodeURIComponent(orgId)}/organization/management`,
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/organization/management`, selector),
                 session
             });
         },
-        async getCapabilityEditor(session, orgId, name) {
+        async getCapabilityEditor(session, orgId, name, selector) {
             return transport.requestJson({
-                path: `/api/v1/orgs/${encodeURIComponent(orgId)}/capabilities/editor/${encodeURIComponent(name)}`,
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/capabilities/editor/${encodeURIComponent(name)}`, selector),
                 session
             });
         },
-        async getOperationsEditor(session, orgId) {
+        async getOperationsEditor(session, orgId, selector) {
             return transport.requestJson({
-                path: `/api/v1/orgs/${encodeURIComponent(orgId)}/operations/editor`,
+                path: withQuery(`/api/v1/orgs/${encodeURIComponent(orgId)}/operations/editor`, selector),
                 session
             });
         },

package/dist/api-types.d.ts

@@ -290,6 +290,13 @@ export interface AgentUsageReport extends CliRecord {
 }
 export interface RuntimeControlDeploymentRecord extends CliRecord {
 }
+export interface WorkflowFailureSummary extends CliRecord {
+    causeChain: string[];
+    rootCause: string;
+    rootCauseCode?: string;
+    summary: string;
+    summaryCode?: string;
+}
 export interface EnvironmentRecord extends CliRecord {
     currentDeploymentId?: string | null;
     id: string;
@@ -319,9 +326,22 @@ export interface EnvironmentDetailRecord extends CliRecord {
 }
 export interface RuntimeControlOverviewRecord extends CliRecord {
 }
-export interface RuntimeControlRunDetailRecord extends CliRecord {
-}
 export interface RuntimeControlRunRecord extends CliRecord {
+    closeTime?: string | null;
+    deploymentId?: string | null;
+    environmentKey?: string | null;
+    failure?: WorkflowFailureSummary;
+    releaseId?: string | null;
+    startTime?: string;
+    status: string;
+    workflowId: string;
+}
+export interface RuntimeControlRunDetailRecord extends RuntimeControlRunRecord {
+    failureLookupError?: string;
+    historyLength?: number;
+    historySizeBytes?: number;
+    state?: CliRecord | null;
+    stateQueryError?: string;
 }
 export interface RuntimeControlRunStateRecord extends CliRecord {
 }

package/dist/artifact-commands.js

@@ -1,15 +1,17 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { TextDecoder } from "node:util";
 import { genericProblem, usageProblem } from "./cli-errors.js";
 import { readOptionalNumberFlag, readOptionalStringFlag, readRequiredStringFlag } from "./command-flags.js";
 import { renderKeyValue, renderSuccess, renderTable } from "./format.js";
+import { readLocalFileBytes } from "./files.js";
 import { confirmDestructive } from "./interaction.js";
 export async function executeArtifactUpload(parsed, context, api, resolveOrgScope) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
     const pathValue = readRequiredArg(parsed, "path");
-    const filePath = resolve(pathValue);
-    const fileBytes = await readFile(filePath);
+    const { absolutePath: filePath, bytes: fileBytes } = await readLocalFileBytes(pathValue, parsed.definition.id, {
+        regularFileMessage: "Artifact upload path must be a regular file, not a directory or symbolic link."
+    });
     const data = await api.uploadArtifact(session, org.id, {
         body: new Uint8Array(fileBytes),
         ...(readOptionalStringFlag(parsed, "sha256") ? { expectedSha256: readOptionalStringFlag(parsed, "sha256") } : {}),

package/dist/auth-commands.js

@@ -1,9 +1,9 @@
-import { authProblem, toProblem } from "./cli-errors.js";
+import { authProblem, toProblem, usageProblem } from "./cli-errors.js";
 import { readOptionalStringFlag } from "./command-flags.js";
 import { writeCliConfig, readCliConfig, findRepoConfigPath } from "./config.js";
 import { renderKeyValue, renderSuccess } from "./format.js";
 import { chooseOrganization, ensureInteractive } from "./interaction.js";
-import { promptPassword, promptText } from "./prompts.js";
+import { isInteractive, promptPassword, promptText } from "./prompts.js";
 export async function executeAuthLogin(parsed, context, api) {
     const prompts = parsed.json
         ? {
@@ -11,6 +11,9 @@ export async function executeAuthLogin(parsed, context, api) {
             stdout: context.stderr
         }
         : context;
+    if (parsed.flags.device === true || !isInteractive(prompts)) {
+        return executeDeviceLogin(parsed, context, api, prompts);
+    }
     ensureInteractive(prompts, "auth login");
     const resolvedBaseUrl = await resolveAuthBaseUrl(parsed, context, prompts);
     const { baseUrl } = resolvedBaseUrl;
@@ -25,8 +28,8 @@ export async function executeAuthLogin(parsed, context, api) {
             },
             human: [
                 "SSO is required for this deployment.",
-                `Open this URL in a browser: ${oidcLoginUrl}`,
-                "The CLI does not complete browser SSO login in this release. API keys remain the supported non-browser CLI auth path."
+                "Run `kora auth login --device` to approve this login in the browser instead.",
+                `SSO sign-in URL: ${oidcLoginUrl}`
             ].join("\n"),
             kind: "access_auth_login_sso_required",
             meta: {
@@ -90,8 +93,8 @@ export async function executeAuthSignup(parsed, context, api) {
             },
             human: [
                 "Local account signup is disabled for this deployment.",
-                `Open this URL in a browser: ${oidcLoginUrl}`,
-                "Account creation is managed by SSO for this deployment."
+                `Account creation is managed by SSO. Sign in once in a browser: ${oidcLoginUrl}`,
+                "Then run `kora auth login --device` to approve a CLI login in the browser."
             ].join("\n"),
             kind: "access_auth_signup_sso_required",
             meta: {
@@ -136,13 +139,86 @@ export async function executeAuthSignup(parsed, context, api) {
         }
     };
 }
-async function resolveAuthBaseUrl(parsed, context, prompts) {
+async function executeDeviceLogin(parsed, context, api, prompts) {
+    const resolvedBaseUrl = await resolveAuthBaseUrl(parsed, context, prompts, {
+        allowPrompt: isInteractive(prompts)
+    });
+    const { baseUrl } = resolvedBaseUrl;
+    const started = await api.startDeviceLogin(baseUrl);
+    const verificationUrl = buildDeviceVerificationUrl(baseUrl, started.verificationPath, started.userCode);
+    prompts.stdout.write(`Open this URL in a browser to approve the login:\n\n  ${verificationUrl}\n\n`);
+    prompts.stdout.write(`Confirmation code: ${started.userCode}\n`);
+    prompts.stdout.write("Waiting for browser approval...\n");
+    const expiresAtMs = Date.parse(started.expiresAt);
+    const pollIntervalMs = Math.max(0, started.pollIntervalSeconds * 1000);
+    let session = null;
+    while (Date.now() < expiresAtMs) {
+        const claim = await api.claimDeviceLogin({ baseUrl, deviceCode: started.deviceCode });
+        if (claim.status === "approved") {
+            session = claim.session;
+            break;
+        }
+        if (claim.status === "denied") {
+            throw authProblem("Device login was denied in the browser.", "auth login");
+        }
+        if (claim.status === "expired") {
+            break;
+        }
+        await sleep(pollIntervalMs);
+    }
+    if (!session) {
+        throw authProblem("Device login expired before it was approved. Run `kora auth login` again.", "auth login");
+    }
+    const nextSession = await writeSessionWithSelectedOrg({
+        allowInteractiveOrgChoice: isInteractive(prompts),
+        api,
+        context,
+        parsed,
+        prompts,
+        session
+    });
+    if (resolvedBaseUrl.shouldPersistGlobalBaseUrl) {
+        await writeCliConfig(context.configPath, {
+            ...resolvedBaseUrl.persistedGlobalConfig,
+            baseUrl
+        });
+    }
+    return {
+        data: {
+            activeOrg: nextSession.activeOrg,
+            method: "device",
+            user: nextSession.user
+        },
+        human: renderSuccess(nextSession.activeOrg
+            ? `Logged in as ${nextSession.user.email}. Active org: ${nextSession.activeOrg.slug}.`
+            : `Logged in as ${nextSession.user.email}. No active organization selected; use \`kora org select <org>\` or \`kora org create\`.`),
+        kind: "access_auth_login",
+        meta: {
+            command: "auth login",
+            orgId: nextSession.activeOrg?.id ?? null
+        }
+    };
+}
+function buildDeviceVerificationUrl(baseUrl, verificationPath, userCode) {
+    const normalizedBaseUrl = baseUrl.replace(/\/+$/u, "");
+    const normalizedPath = verificationPath.startsWith("/") ? verificationPath : `/${verificationPath}`;
+    return `${normalizedBaseUrl}${normalizedPath}?code=${encodeURIComponent(userCode)}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function resolveAuthBaseUrl(parsed, context, prompts, options = { allowPrompt: true }) {
     const persistedGlobalConfig = await readCliConfig(context.configPath);
     const repoConfigPath = await findRepoConfigPath(context.cwd);
     const repoConfig = repoConfigPath ? await readCliConfig(repoConfigPath) : {};
     const flagBaseUrl = readOptionalStringFlag(parsed, "base-url");
     const envBaseUrl = context.env.KORA_BASE_URL;
     const configuredBaseUrl = flagBaseUrl ?? envBaseUrl ?? repoConfig.baseUrl ?? persistedGlobalConfig.baseUrl;
+    if (!configuredBaseUrl && !options.allowPrompt) {
+        throw usageProblem("Pass --base-url <url> or set KORA_BASE_URL to log in from a non-interactive shell.", "auth login");
+    }
     const baseUrl = configuredBaseUrl ?? await promptText("Platform base URL: ", prompts);
     return {
         baseUrl,
@@ -154,7 +230,7 @@ async function writeSessionWithSelectedOrg(input) {
     const organizations = (await input.api.listOrganizations(input.session)).organizations;
     const activeOrg = organizations.length === 1
         ? organizations[0] ?? null
-        : organizations.length > 1
+        : organizations.length > 1 && (input.allowInteractiveOrgChoice ?? true)
             ? await chooseOrganization(organizations, input.prompts, input.parsed)
             : null;
     const latestSession = await readLatestSessionForWrite(input.context.sessionStore, input.session);

package/dist/cli-errors.d.ts

@@ -1,13 +1,18 @@
 import { ApiError } from "./transport.js";
+type CliProblemDetails = Record<string, unknown>;
 export declare class CliProblem extends Error {
+    readonly code: string;
     readonly detail: string;
+    readonly details?: CliProblemDetails;
     readonly exitCode: number;
     readonly instance: string;
     readonly status: number;
     readonly title: string;
     readonly type: string;
     constructor(input: {
+        code: string;
         detail: string;
+        details?: CliProblemDetails;
         exitCode: number;
         instance: string;
         status: number;
@@ -15,9 +20,10 @@ export declare class CliProblem extends Error {
         type: string;
     });
 }
-export declare function usageProblem(detail: string, instance: string): CliProblem;
+export declare function usageProblem(detail: string, instance: string, details?: CliProblemDetails): CliProblem;
 export declare function authProblem(detail: string, instance: string): CliProblem;
 export declare function notFoundProblem(detail: string, instance: string): CliProblem;
 export declare function genericProblem(detail: string, instance: string): CliProblem;
 export declare function toProblem(error: unknown, instance: string): CliProblem | ApiError;
 export declare function exitCodeFromError(error: CliProblem | ApiError): number;
+export {};

package/dist/cli-errors.js

@@ -1,6 +1,8 @@
 import { ApiError } from "./transport.js";
 export class CliProblem extends Error {
+    code;
     detail;
+    details;
     exitCode;
     instance;
     status;
@@ -9,7 +11,11 @@ export class CliProblem extends Error {
     constructor(input) {
         super(input.detail);
         this.name = "CliProblem";
+        this.code = input.code;
         this.detail = input.detail;
+        if (input.details) {
+            this.details = input.details;
+        }
         this.exitCode = input.exitCode;
         this.instance = input.instance;
         this.status = input.status;
@@ -17,9 +23,11 @@ export class CliProblem extends Error {
         this.type = input.type;
     }
 }
-export function usageProblem(detail, instance) {
+export function usageProblem(detail, instance, details) {
     return new CliProblem({
+        code: "cli/usage",
         detail,
+        ...(details ? { details } : {}),
         exitCode: 2,
         instance,
         status: 400,
@@ -29,6 +37,7 @@ export function usageProblem(detail, instance) {
 }
 export function authProblem(detail, instance) {
     return new CliProblem({
+        code: "cli/auth",
         detail,
         exitCode: 3,
         instance,
@@ -39,6 +48,7 @@ export function authProblem(detail, instance) {
 }
 export function notFoundProblem(detail, instance) {
     return new CliProblem({
+        code: "cli/not_found",
         detail,
         exitCode: 4,
         instance,
@@ -49,6 +59,7 @@ export function notFoundProblem(detail, instance) {
 }
 export function genericProblem(detail, instance) {
     return new CliProblem({
+        code: "cli/error",
         detail,
         exitCode: 1,
         instance,

package/dist/command-flags.d.ts

@@ -1,4 +1,5 @@
 import type { ParsedCommand } from "./runner.js";
 export declare function readOptionalStringFlag(parsed: ParsedCommand, name: string): string | undefined;
 export declare function readRequiredStringFlag(parsed: ParsedCommand, name: string): string;
+export declare function readRequiredStringFlagPreservingEmpty(parsed: ParsedCommand, name: string): string;
 export declare function readOptionalNumberFlag(parsed: ParsedCommand, name: string): number | undefined;

package/dist/command-flags.js

@@ -10,6 +10,13 @@ export function readRequiredStringFlag(parsed, name) {
     }
     return value;
 }
+export function readRequiredStringFlagPreservingEmpty(parsed, name) {
+    const value = parsed.flags[name];
+    if (typeof value !== "string") {
+        throw usageProblem(`Missing required flag --${name}.`, parsed.definition.id);
+    }
+    return value;
+}
 export function readOptionalNumberFlag(parsed, name) {
     const value = parsed.flags[name];
     return typeof value === "number" ? value : undefined;