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

package/dist/command-registry.js

@@ -31,6 +31,12 @@ export const CLI_ALIASES = Object.freeze({
     process: ["workflow"],
     project: ["org"],
 });
+const releaseReadFlag = (description, required = false) => flag("release", description, { acceptsValue: true, ...(required ? { required: true } : {}), valueType: "string" });
+const releaseEnvironmentReadFlag = (description) => flag("environment", description, { acceptsValue: true, valueType: "string" });
+const releaseSnapshotReadFlags = (releaseDescription, environmentDescription) => [
+    releaseReadFlag(releaseDescription),
+    releaseEnvironmentReadFlag(environmentDescription)
+];
 const RAW_CLI_COMMANDS = [
     command(["help"], "Show human or machine-readable help for a command path.", {
         labels: ["read", "chat-read", "help"],
@@ -64,13 +70,14 @@ const RAW_CLI_COMMANDS = [
     command(["auth", "whoami"], "Show the current authenticated user and selected organization.", {
         labels: ["local", "auth"]
     }),
-    command(["auth", "login"], "Start an interactive login flow and select the active organization.", {
+    command(["auth", "login"], "Log in and select the active organization. Uses browser device approval with --device or when the terminal is not interactive.", {
         labels: ["credential", "auth"],
         flags: [
             flag("base-url", "Platform base URL for this login.", {
                 acceptsValue: true,
                 valueType: "string"
-            })
+            }),
+            flag("device", "Use the browser device-approval flow instead of interactive email/password login.")
         ]
     }),
     command(["auth", "signup"], "Create a local account and start a CLI session.", {
@@ -182,52 +189,37 @@ const RAW_CLI_COMMANDS = [
         labels: ["read", "activity", "chat-read"],
         requiresActiveOrg: true
     }),
-    command(["workflow", "list"], "List workflows.", {
-        labels: ["read", "workflow"],
-        aliases: [["process", "list"]],
-        flags: [flag("release", "Read workflows from a release.", {
-                acceptsValue: true,
-                valueType: "string"
-            })],
+    command(["workflow", "list"], "List live deployed workflows, filter live deployments with --environment, or list workflows from a release with --release.", {
+        labels: ["read", "workflow"], aliases: [["process", "list"]],
+        examples: ["kora workflow list", "kora workflow list --environment <environment>", "kora workflow list --release <release>"],
+        flags: releaseSnapshotReadFlags("Read workflows from an immutable release instead of live deployments.", "Filter live deployed workflows to one environment's live deployment."),
         requiresActiveOrg: true
     }),
     command(["workflow", "get"], "Show workflow detail.", {
         labels: ["read", "workflow"],
         aliases: [["process", "get"]],
         args: [arg("name", "Workflow name.")],
-        flags: [flag("release", "Read workflow detail from a release.", {
-                acceptsValue: true,
-                valueType: "string"
-            })],
+        flags: releaseSnapshotReadFlags("Read workflow detail from a release.", "Read workflow detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["workflow", "version", "get"], "Show one workflow version.", {
         labels: ["read", "workflow"],
         aliases: [["process", "version", "get"]],
         args: [arg("name", "Workflow name."), arg("version", "Workflow version.")],
-        flags: [flag("release", "Read workflow version from a release.", {
-                acceptsValue: true,
-                valueType: "string"
-            })],
+        flags: releaseSnapshotReadFlags("Read workflow version from a release.", "Read workflow version from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["workflow", "dependencies"], "Show workflow dependency detail.", {
         labels: ["read", "workflow"],
         aliases: [["process", "dependencies"]],
         args: [arg("name", "Workflow name."), arg("version", "Workflow version.")],
-        flags: [flag("release", "Read workflow dependencies from a release.", {
-                acceptsValue: true,
-                valueType: "string"
-            })],
+        flags: releaseSnapshotReadFlags("Read workflow dependencies from a release.", "Read workflow dependencies from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["workflow", "context"], "Show workflow inspection context.", {
         labels: ["read", "workflow"],
         aliases: [["process", "context"]],
-        flags: [flag("release", "Read workflow context from a release.", {
-                acceptsValue: true,
-                valueType: "string"
-            })],
+        flags: releaseSnapshotReadFlags("Read workflow context from a release.", "Read workflow context from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["workflow", "start"], "Start a workflow.", {
@@ -294,10 +286,7 @@ const RAW_CLI_COMMANDS = [
     command(["release", "create"], "Create an immutable release artifact from source files; this mutates Platform state and is not a test command.", {
         labels: ["write", "chat-write", "release"],
         args: [arg("workspace", "Path to the source folder or zip archive.")],
-        flags: [flag("label", "Human label for the release.", {
-                acceptsValue: true,
-                valueType: "string"
-            })],
+        flags: [],
         requiresActiveOrg: true
     }),
     command(["release", "validate"], "Validate release readiness without deploying.", {
@@ -701,55 +690,72 @@ const RAW_CLI_COMMANDS = [
         requiresActiveOrg: true
     }),
     command(["org-model", "people", "list"], "List modeled people.", {
+        flags: releaseSnapshotReadFlags("Read modeled people from a release.", "Read modeled people from an environment's live deployment release."),
         labels: ["read", "org-model"], requiresActiveOrg: true
     }),
     command(["org-model", "people", "get"], "Show one modeled person.", {
         labels: ["read", "org-model"],
         args: [arg("name", "Person name.")],
+        flags: releaseSnapshotReadFlags("Read modeled person detail from a release.", "Read modeled person detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["org-model", "agents", "list"], "List modeled agents.", {
-        labels: ["read", "org-model"], requiresActiveOrg: true
+        flags: releaseSnapshotReadFlags("Read modeled agents from a release.", "Read modeled agents from an environment's live deployment release."),
+        labels: ["read", "org-model"],
+        requiresActiveOrg: true
     }),
     command(["org-model", "agents", "get"], "Show one modeled agent.", {
         labels: ["read", "org-model"],
         args: [arg("name", "Agent name.")],
+        flags: releaseSnapshotReadFlags("Read modeled agent detail from a release.", "Read modeled agent detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["org-model", "roles", "list"], "List modeled roles.", {
-        labels: ["read", "org-model"], requiresActiveOrg: true
+        flags: releaseSnapshotReadFlags("Read modeled roles from a release.", "Read modeled roles from an environment's live deployment release."),
+        labels: ["read", "org-model"],
+        requiresActiveOrg: true
     }),
     command(["org-model", "roles", "get"], "Show one modeled role.", {
         labels: ["read", "org-model"],
         args: [arg("name", "Role name.")],
+        flags: releaseSnapshotReadFlags("Read modeled role detail from a release.", "Read modeled role detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["org-model", "assignments", "list"], "List modeled assignments.", {
-        labels: ["read", "org-model"], requiresActiveOrg: true
+        flags: releaseSnapshotReadFlags("Read modeled assignments from a release.", "Read modeled assignments from an environment's live deployment release."),
+        labels: ["read", "org-model"],
+        requiresActiveOrg: true
     }),
     command(["org-model", "assignments", "get"], "Show one modeled assignment group by role.", {
         labels: ["read", "org-model"],
         args: [arg("role-name", "Role name.")],
+        flags: releaseSnapshotReadFlags("Read modeled assignment detail from a release.", "Read modeled assignment detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["org-model", "capabilities", "list"], "List capabilities.", {
-        labels: ["read", "org-model"], requiresActiveOrg: true
+        flags: releaseSnapshotReadFlags("Read capabilities from a release.", "Read capabilities from an environment's live deployment release."),
+        labels: ["read", "org-model"],
+        requiresActiveOrg: true
     }),
     command(["org-model", "capabilities", "get"], "Show one capability.", {
         labels: ["read", "org-model"],
         args: [arg("name", "Capability name.")],
+        flags: releaseSnapshotReadFlags("Read capability detail from a release.", "Read capability detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["org-model", "operations", "list"], "List operations.", {
-        labels: ["read", "org-model"], requiresActiveOrg: true
+        flags: releaseSnapshotReadFlags("Read operations from a release.", "Read operations from an environment's live deployment release."),
+        labels: ["read", "org-model"],
+        requiresActiveOrg: true
     }),
     command(["org-model", "operations", "get"], "Show one operation.", {
         labels: ["read", "org-model"],
         args: [arg("name", "Operation name.")],
+        flags: releaseSnapshotReadFlags("Read operation detail from a release.", "Read operation detail from an environment's live deployment release."),
         requiresActiveOrg: true
     }),
     command(["access", "members", "list"], "List organization members.", {
-        labels: ["read", "access"],
+        labels: ["read", "chat-read", "access"],
         flags: [
             flag("limit", "Maximum number of members to return.", {
                 acceptsValue: true,
@@ -764,7 +770,7 @@ const RAW_CLI_COMMANDS = [
         requiresActiveOrg: true
     }),
     command(["access", "members", "get"], "Show one organization member.", {
-        labels: ["read", "access"],
+        labels: ["read", "chat-read", "access"],
         args: [arg("user-id", "User id.")],
         requiresActiveOrg: true
     }),
@@ -787,7 +793,7 @@ const RAW_CLI_COMMANDS = [
         requiresActiveOrg: true
     }),
     command(["access", "invites", "list"], "List organization invites.", {
-        labels: ["read", "access"],
+        labels: ["read", "chat-read", "access"],
         flags: [
             flag("limit", "Maximum number of invites to return.", {
                 acceptsValue: true,
@@ -802,12 +808,12 @@ const RAW_CLI_COMMANDS = [
         requiresActiveOrg: true
     }),
     command(["access", "invites", "get"], "Show one organization invite.", {
-        labels: ["read", "access"],
+        labels: ["read", "chat-read", "access"],
         args: [arg("invite-id", "Invite id.")],
         requiresActiveOrg: true
     }),
     command(["access", "invites", "create"], "Create an organization invite.", {
-        labels: ["write", "access"],
+        labels: ["write", "chat-write", "access"],
         flags: [
             flag("email", "Invitee email address.", {
                 acceptsValue: true,
@@ -1101,6 +1107,23 @@ const RAW_CLI_COMMANDS = [
             })],
         requiresActiveOrg: true
     }),
+    command(["env", "set"], "Create or update one runtime variable without reading other values.", {
+        labels: ["write", "chat-write", "env"],
+        args: [arg("name", "Variable name.")],
+        flags: [
+            flag("environment", "Target environment.", {
+                acceptsValue: true,
+                required: true,
+                valueType: "string"
+            }),
+            flag("value", "Variable value.", {
+                acceptsValue: true,
+                required: true,
+                valueType: "string"
+            })
+        ],
+        requiresActiveOrg: true
+    }),
     command(["env", "replace"], "Replace the full runtime environment from JSON.", {
         labels: ["destructive", "env"],
         destructive: true,

package/dist/commands.js

@@ -3,7 +3,7 @@ import { executeAuthLogin, executeAuthLogout, executeAuthSignup, executeAuthWhoa
 import { getCliSchema, listCliSchemas } from "./schema-registry.js";
 import { createPlatformApiClient } from "./api-client.js";
 import { authProblem, genericProblem, notFoundProblem, usageProblem } from "./cli-errors.js";
-import { readOptionalNumberFlag, readOptionalStringFlag, readRequiredStringFlag } from "./command-flags.js";
+import { readOptionalNumberFlag, readOptionalStringFlag, readRequiredStringFlag, readRequiredStringFlagPreservingEmpty } from "./command-flags.js";
 import { executeArtifactDownload, executeArtifactArchive, executeArtifactInspect, executeArtifactInventory, executeArtifactList, executeArtifactPurge, executeArtifactRead, executeArtifactRestore, executeArtifactUpload } from "./artifact-commands.js";
 import { executeAudit } from "./audit-commands.js";
 import { isZipArchivePath, readArchiveBytes, readImportEntries, readJsonInputSpecifier, readWorkspaceTestEntries, readTextInputSpecifier, writeReleaseSourceFiles } from "./files.js";
@@ -164,6 +164,7 @@ export async function executeParsedCommand(parsed, context) {
             return executeExtensions(parsed, context, api, resolveOrgScope);
         case "env.list":
         case "env.get":
+        case "env.set":
         case "env.replace":
             return executeEnv(parsed, context, api);
         case "secrets.list":
@@ -421,58 +422,98 @@ async function executeActivityOptions(parsed, context, api) {
         meta: { command: "activity options", orgId: org.id }
     };
 }
+function readOptionalReleaseSnapshotSelector(parsed) {
+    const releaseId = readOptionalStringFlag(parsed, "release");
+    const environment = readCliEnvironmentFlag(parsed);
+    if (releaseId && environment) {
+        throw usageProblem("Use either --release or --environment, not both.", parsed.definition.id);
+    }
+    if (releaseId) {
+        return { releaseId };
+    }
+    if (environment) {
+        return { environment };
+    }
+    return undefined;
+}
+function readRequiredReleaseSnapshotSelector(parsed) {
+    const selector = readOptionalReleaseSnapshotSelector(parsed);
+    if (!selector) {
+        throw usageProblem("Provide either --release or --environment.", parsed.definition.id);
+    }
+    return selector;
+}
+function releaseSnapshotSelectorMeta(selector) {
+    if (!selector) {
+        return {};
+    }
+    if (typeof selector.releaseId === "string") {
+        return { releaseId: selector.releaseId };
+    }
+    if (typeof selector.environment === "string") {
+        return { environment: selector.environment };
+    }
+    return {};
+}
 async function executeWorkflowList(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
-    const data = await api.listWorkflows(session, org.id, readOptionalStringFlag(parsed, "release"));
+    const selector = readOptionalReleaseSnapshotSelector(parsed);
+    const data = await api.listWorkflows(session, org.id, selector ?? { live: true });
     return {
         data,
         human: renderTable(data.processes, [
             { key: "name", label: "Name" },
+            { key: "environmentKey", label: "Environment" },
+            { key: "liveReleaseId", label: "Live release" },
             { key: "latestVersion", label: "Latest" },
             { key: "deployedVersion", label: "Deployed" }
         ]),
         kind: "authoring_workflow_list",
-        meta: { command: "workflow list", orgId: org.id }
+        meta: { command: "workflow list", orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
     };
 }
 async function executeWorkflowGet(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
-    const data = await api.getWorkflow(session, org.id, readRequiredArg(parsed, "name"), readOptionalStringFlag(parsed, "release"));
+    const selector = readRequiredReleaseSnapshotSelector(parsed);
+    const data = await api.getWorkflow(session, org.id, readRequiredArg(parsed, "name"), selector);
     return {
         data,
         human: renderPrettyJson(data.process),
         kind: "authoring_workflow_get",
-        meta: { command: "workflow get", orgId: org.id }
+        meta: { command: "workflow get", orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
     };
 }
 async function executeWorkflowVersionGet(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
-    const data = await api.getWorkflowVersion(session, org.id, readRequiredArg(parsed, "name"), readRequiredIntegerArg(parsed, "version"), readOptionalStringFlag(parsed, "release"));
+    const selector = readRequiredReleaseSnapshotSelector(parsed);
+    const data = await api.getWorkflowVersion(session, org.id, readRequiredArg(parsed, "name"), readRequiredIntegerArg(parsed, "version"), selector);
     return {
         data,
         human: renderPrettyJson(data.process),
         kind: "authoring_workflow_version_get",
-        meta: { command: "workflow version get", orgId: org.id }
+        meta: { command: "workflow version get", orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
     };
 }
 async function executeWorkflowDependencies(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
-    const data = await api.getWorkflowDependencies(session, org.id, readRequiredArg(parsed, "name"), readRequiredIntegerArg(parsed, "version"), readOptionalStringFlag(parsed, "release"));
+    const selector = readRequiredReleaseSnapshotSelector(parsed);
+    const data = await api.getWorkflowDependencies(session, org.id, readRequiredArg(parsed, "name"), readRequiredIntegerArg(parsed, "version"), selector);
     return {
         data,
         human: renderPrettyJson(data.dependencies),
         kind: "authoring_workflow_dependencies",
-        meta: { command: "workflow dependencies", orgId: org.id }
+        meta: { command: "workflow dependencies", orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
     };
 }
 async function executeWorkflowContext(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
-    const data = await api.getWorkflowContext(session, org.id, readOptionalStringFlag(parsed, "release"));
+    const selector = readRequiredReleaseSnapshotSelector(parsed);
+    const data = await api.getWorkflowContext(session, org.id, selector);
     return {
         data,
         human: renderPrettyJson(data.context),
         kind: "authoring_workflow_context",
-        meta: { command: "workflow context", orgId: org.id }
+        meta: { command: "workflow context", orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
     };
 }
 async function executeWorkflowStart(parsed, context, api) {
@@ -483,7 +524,7 @@ async function executeWorkflowStart(parsed, context, api) {
     }
     const inputSpecifier = readOptionalStringFlag(parsed, "input");
     const inputData = inputSpecifier
-        ? await readJsonInputSpecifier(inputSpecifier, context.stdin, "workflow start")
+        ? await readJsonInputSpecifier(inputSpecifier, context.stdin, "workflow start", { flag: "input" })
         : undefined;
     const workflowName = readRequiredArg(parsed, "name");
     const resolvedEnvironment = resolveCliEnvironment(parsed, session);
@@ -513,7 +554,7 @@ async function executeWorkflowNodeTest(parsed, context, api) {
     const environment = readOptionalStringFlag(parsed, "environment");
     const inputSpecifier = readOptionalStringFlag(parsed, "input");
     const inputData = inputSpecifier
-        ? await readJsonInputSpecifier(inputSpecifier, context.stdin, "test node")
+        ? await readJsonInputSpecifier(inputSpecifier, context.stdin, "test node", { flag: "input" })
         : undefined;
     const data = await api.testWorkflowNode(session, org.id, workflowName, nodeId, {
         ...(environment ? { environment } : {}),
@@ -645,11 +686,8 @@ async function executeReleaseSource(parsed, context, api) {
 async function executeReleaseCreate(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
     const workspacePath = readRequiredArg(parsed, "workspace");
-    const label = readOptionalStringFlag(parsed, "label");
     if (isZipArchivePath(workspacePath)) {
-        const data = await api.createReleaseArchive(session, org.id, await readArchiveBytes(workspacePath, "release create"), {
-            ...(label ? { label } : {})
-        });
+        const data = await api.createReleaseArchive(session, org.id, await readArchiveBytes(workspacePath, "release create"));
         const summary = summarizeReleaseCreation(data.created.release.id);
         return {
             data,
@@ -660,8 +698,7 @@ async function executeReleaseCreate(parsed, context, api) {
     }
     const files = await readImportEntries(workspacePath);
     const data = await api.createRelease(session, org.id, {
-        files,
-        ...(label ? { label } : {})
+        files
     });
     const summary = summarizeReleaseCreation(data.created.release.id);
     return {
@@ -702,7 +739,7 @@ async function executeEnvironment(parsed, context, api) {
             const data = await api.getEnvironment(session, org.id, readRequiredArg(parsed, "environment"));
             return {
                 data,
-                human: renderPrettyJson(data.environment),
+                human: renderPrettyJson(data),
                 kind: "environment_get",
                 meta: { command: "environment get", orgId: org.id }
             };
@@ -942,7 +979,7 @@ async function executeTaskGet(parsed, context, api) {
 }
 async function executeTaskComplete(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
-    const outputData = await readJsonInputSpecifier(String(parsed.flags.output), context.stdin, "task complete");
+    const outputData = await readJsonInputSpecifier(String(parsed.flags.output), context.stdin, "task complete", { flag: "output" });
     const data = await api.completeTask(session, org.id, readRequiredArg(parsed, "task-id"), {
         outputData,
         workflowId: String(parsed.flags.run)
@@ -958,8 +995,9 @@ async function executeOrgModel(parsed, context, api) {
     const { org, session } = await resolveOrgScope(parsed, context, api);
     const section = parsed.definition.path[1] ?? "";
     const verb = parsed.definition.path[2] ?? "";
+    const selector = readRequiredReleaseSnapshotSelector(parsed);
     if (section === "operations") {
-        const editor = (await api.getOperationsEditor(session, org.id)).editor;
+        const editor = (await api.getOperationsEditor(session, org.id, selector)).editor;
         const record = verb === "get"
             ? requireFound(editor.operations.find((entry) => entry.name === parsed.args.name), `Operation '${parsed.args.name}' was not found.`, parsed.definition.id)
             : undefined;
@@ -972,17 +1010,17 @@ async function executeOrgModel(parsed, context, api) {
                     { key: "command", label: "Command" }
                 ]),
             kind: `authoring_${sanitizeKind(section)}_${verb}`,
-            meta: { command: parsed.definition.path.join(" "), orgId: org.id }
+            meta: { command: parsed.definition.path.join(" "), orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
         };
     }
-    const management = (await api.getOrganizationManagementContext(session, org.id)).context;
+    const management = (await api.getOrganizationManagementContext(session, org.id, selector)).context;
     if (section === "capabilities" && verb === "get") {
-        const detail = await api.getCapabilityEditor(session, org.id, readRequiredArg(parsed, "name"));
+        const detail = await api.getCapabilityEditor(session, org.id, readRequiredArg(parsed, "name"), selector);
         return {
             data: detail,
             human: renderPrettyJson(detail.editor),
             kind: "authoring_capabilities_get",
-            meta: { command: parsed.definition.path.join(" "), orgId: org.id }
+            meta: { command: parsed.definition.path.join(" "), orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
         };
     }
     const selection = selectOrgModelSection(management, section, verb === "get" ? parsed.args[section === "assignments" ? "role-name" : "name"] : undefined);
@@ -990,7 +1028,7 @@ async function executeOrgModel(parsed, context, api) {
         data: selection.data,
         human: selection.human,
         kind: `authoring_${sanitizeKind(section)}_${verb}`,
-        meta: { command: parsed.definition.path.join(" "), orgId: org.id }
+        meta: { command: parsed.definition.path.join(" "), orgId: org.id, ...releaseSnapshotSelectorMeta(selector) }
     };
 }
 async function executeAccess(parsed, context, api) {
@@ -1187,9 +1225,32 @@ async function executeEnv(parsed, context, api) {
                 meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
             };
         }
+        case "env.set": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const name = readRequiredArg(parsed, "name");
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.upsertRuntimeVariable(session, org.id, {
+                environment,
+                name,
+                value: readRequiredStringFlagPreservingEmpty(parsed, "value")
+            });
+            return {
+                data: {
+                    variable: {
+                        environmentKey: data.variable.environmentKey,
+                        name: data.variable.name,
+                        status: "defined",
+                        updatedAt: data.variable.updatedAt
+                    }
+                },
+                human: renderSuccess(`Saved runtime variable '${data.variable.name}' in ${environment}.`),
+                kind: "authoring_env_set",
+                meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
+            };
+        }
         case "env.replace": {
             const environment = readRequiredCliEnvironmentFlag(parsed);
-            const body = await readJsonInputSpecifier(String(parsed.flags.file), context.stdin, parsed.definition.id);
+            const body = await readJsonInputSpecifier(String(parsed.flags.file), context.stdin, parsed.definition.id, { flag: "file" });
             const rawVariables = body.variables;
             if (!Array.isArray(rawVariables)) {
                 throw usageProblem("Environment replace payload must contain a variables array.", parsed.definition.id);

package/dist/error-code.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizePublicErrorCode(code: string): string;
+export declare function readPublicErrorCodeFromType(type: string): string;

package/dist/error-code.js

@@ -0,0 +1,9 @@
+const PUBLIC_ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]*(?:\/[a-z][a-z0-9_]*)?$/u;
+export function normalizePublicErrorCode(code) {
+    return PUBLIC_ERROR_CODE_PATTERN.test(code) ? code : "internal/error";
+}
+export function readPublicErrorCodeFromType(type) {
+    return type.startsWith("https://errors.kora.dev/")
+        ? type.slice("https://errors.kora.dev/".length)
+        : "internal/error";
+}

package/dist/extension-commands.js

@@ -395,11 +395,11 @@ async function readOptionalPermissions(parsed, context) {
     if (!specifier) {
         return undefined;
     }
-    return normalizePermissions(await readJsonInputSpecifier(specifier, context.stdin, parsed.definition.id), parsed.definition.id);
+    return normalizePermissions(await readJsonInputSpecifier(specifier, context.stdin, parsed.definition.id, { flag: "permissions" }), parsed.definition.id);
 }
 async function readRequiredPermissions(parsed, context) {
     const specifier = readRequiredStringFlag(parsed, "permissions");
-    return normalizePermissions(await readJsonInputSpecifier(specifier, context.stdin, parsed.definition.id), parsed.definition.id);
+    return normalizePermissions(await readJsonInputSpecifier(specifier, context.stdin, parsed.definition.id, { flag: "permissions" }), parsed.definition.id);
 }
 function normalizePermissions(input, instance) {
     const permissions = input.grantedPermissions && isRecord(input.grantedPermissions)

package/dist/files.d.ts

@@ -1,5 +1,9 @@
+import { Buffer } from "node:buffer";
 import type { Readable } from "node:stream";
-export declare function readJsonInputSpecifier(specifier: string, stdin: Readable, instance: string): Promise<Record<string, unknown>>;
+interface ReadStructuredInputOptions {
+    flag?: string;
+}
+export declare function readJsonInputSpecifier(specifier: string, stdin: Readable, instance: string, options?: ReadStructuredInputOptions): Promise<Record<string, unknown>>;
 export declare function readTextInputSpecifier(specifier: string, stdin: Readable, instance: string): Promise<string>;
 export declare function readImportEntries(pathValue: string): Promise<Array<{
     content: string;
@@ -7,6 +11,12 @@ export declare function readImportEntries(pathValue: string): Promise<Array<{
 }>>;
 export declare function isZipArchivePath(pathValue: string): boolean;
 export declare function readArchiveBytes(pathValue: string, instance: string): Promise<Uint8Array>;
+export declare function readLocalFileBytes(pathValue: string, instance: string, options?: {
+    regularFileMessage?: string;
+}): Promise<{
+    absolutePath: string;
+    bytes: Buffer;
+}>;
 export declare function readWorkspaceTestEntries(pathValue: string): Promise<Array<{
     content: string;
     path: string;
@@ -38,3 +48,4 @@ export declare function readPackageFileEntries(pathValue: string, instance: stri
     contentBase64: string;
     path: string;
 }>>;
+export {};