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

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,51 +690,68 @@ 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.", {

package/dist/commands.js

@@ -421,58 +421,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 +523,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 +553,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 +685,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 +697,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 +738,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 +978,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 +994,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 +1009,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 +1027,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) {
@@ -1189,7 +1226,7 @@ async function executeEnv(parsed, context, api) {
         }
         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 {};

package/dist/files.js

@@ -7,14 +7,38 @@ const MAX_IMPORT_FILE_COUNT = 500;
 const MAX_IMPORT_FILE_BYTES = 1_000_000;
 const MAX_PACKAGE_FILE_BYTES = 2_000_000;
 const MAX_IMPORT_TOTAL_BYTES = 10_000_000;
-export async function readJsonInputSpecifier(specifier, stdin, instance) {
+export async function readJsonInputSpecifier(specifier, stdin, instance, options = {}) {
     if (specifier === "-") {
-        return readJsonObject(await readStream(stdin), instance);
+        return readJsonObject(await readStream(stdin), instance, {
+            source: "stdin",
+            ...options
+        });
     }
     if (!specifier.startsWith("@")) {
-        throw usageProblem("Structured JSON input must use @file.json or - for stdin.", instance);
+        throw usageProblem("Structured JSON input must use @file.json or - for stdin.", instance, {
+            ...(options.flag ? { flag: options.flag } : {})
+        });
+    }
+    const filePath = resolve(specifier.slice(1));
+    let source;
+    try {
+        source = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const nativeCode = readNodeErrorCode(error);
+        if (nativeCode && isLocalPathReadErrorCode(nativeCode)) {
+            throw usageProblem(`Structured JSON input file ${filePath} could not be read: ${nativeCode}.`, instance, {
+                filePath,
+                ...(options.flag ? { flag: options.flag } : {}),
+                nativeCode
+            });
+        }
+        throw error;
     }
-    return readJsonObject(await readFile(specifier.slice(1), "utf8"), instance);
+    return readJsonObject(source, instance, {
+        filePath,
+        ...options
+    });
 }
 export async function readTextInputSpecifier(specifier, stdin, instance) {
     if (specifier === "-") {
@@ -35,12 +59,26 @@ export function isZipArchivePath(pathValue) {
     return extname(pathValue).toLowerCase() === ".zip";
 }
 export async function readArchiveBytes(pathValue, instance) {
+    const file = await readLocalFileBytes(pathValue, instance, {
+        regularFileMessage: "Archive path must be a regular .zip file, not a directory or symbolic link."
+    });
+    return file.bytes;
+}
+export async function readLocalFileBytes(pathValue, instance, options = {}) {
     const absolutePath = resolve(pathValue);
-    const pathStat = await lstat(absolutePath);
+    const pathStat = await readLocalPathStat(absolutePath, instance);
     if (pathStat.isSymbolicLink() || !pathStat.isFile()) {
-        throw usageProblem("Archive path must be a regular .zip file, not a directory or symbolic link.", instance);
+        throw usageProblem(options.regularFileMessage ?? "Path must be a regular file, not a directory or symbolic link.", instance);
+    }
+    try {
+        return {
+            absolutePath,
+            bytes: await readFile(absolutePath)
+        };
+    }
+    catch (error) {
+        throwLocalPathReadProblem(error, absolutePath, instance);
     }
-    return await readFile(absolutePath);
 }
 export async function readWorkspaceTestEntries(pathValue) {
     return await readUtf8Entries(pathValue, {
@@ -50,7 +88,7 @@ export async function readWorkspaceTestEntries(pathValue) {
 }
 async function readUtf8Entries(pathValue, options) {
     const absolutePath = resolve(pathValue);
-    const pathStat = await lstat(absolutePath);
+    const pathStat = await readLocalPathStat(absolutePath, options.instance);
     if (pathStat.isSymbolicLink()) {
         throw usageProblem("Import path must be a regular file or directory, not a symbolic link.", options.instance);
     }
@@ -151,7 +189,7 @@ export async function writePackageExport(outPath, envelope) {
 }
 export async function readPackageFileEntries(pathValue, instance) {
     const absolutePath = resolve(pathValue);
-    const pathStat = await lstat(absolutePath);
+    const pathStat = await readLocalPathStat(absolutePath, instance);
     if (pathStat.isSymbolicLink()) {
         throw usageProblem("Package path must be a regular file or directory, not a symbolic link.", instance);
     }
@@ -161,7 +199,9 @@ export async function readPackageFileEntries(pathValue, instance) {
             totalBytes: 0
         }, instance);
         return [{
-                contentBase64: (await readFile(absolutePath)).toString("base64"),
+                contentBase64: (await readLocalFileBytes(absolutePath, instance, {
+                    regularFileMessage: "Package path must be a regular file or directory, not a symbolic link."
+                })).bytes.toString("base64"),
                 path: basename(absolutePath)
             }];
     }
@@ -173,16 +213,24 @@ export async function readPackageFileEntries(pathValue, instance) {
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return entries;
 }
-function readJsonObject(source, instance) {
+function readJsonObject(source, instance, options) {
     let parsed;
     try {
         parsed = JSON.parse(source);
     }
     catch {
-        throw usageProblem("Structured JSON input must be valid JSON.", instance);
+        const sourceLabel = "filePath" in options ? `file ${options.filePath}` : "from stdin";
+        throw usageProblem(`Structured JSON input ${sourceLabel} must be valid JSON.`, instance, {
+            ...("filePath" in options ? { filePath: options.filePath } : { source: options.source }),
+            ...(options.flag ? { flag: options.flag } : {})
+        });
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw usageProblem("Structured JSON input must be a JSON object.", instance);
+        const sourceLabel = "filePath" in options ? `file ${options.filePath}` : "from stdin";
+        throw usageProblem(`Structured JSON input ${sourceLabel} must be a JSON object.`, instance, {
+            ...("filePath" in options ? { filePath: options.filePath } : { source: options.source }),
+            ...(options.flag ? { flag: options.flag } : {})
+        });
     }
     return parsed;
 }
@@ -232,10 +280,10 @@ async function walkPackageDirectory(root, current, entries, counters, instance)
         if (!child.isFile()) {
             continue;
         }
-        const childStat = await lstat(childPath);
+        const childStat = await readLocalPathStat(childPath, instance);
         assertPackageFileCanBeRead(childStat.size, relativePath, counters, instance);
         entries.push({
-            contentBase64: (await readFile(childPath)).toString("base64"),
+            contentBase64: (await readLocalFileBytes(childPath, instance)).bytes.toString("base64"),
             path: relativePath
         });
     }
@@ -289,7 +337,13 @@ async function readLimitedUtf8File(filePath, displayPath, counters, options) {
     if (counters.fileCount >= MAX_IMPORT_FILE_COUNT) {
         throw usageProblem(`Import has more than ${String(MAX_IMPORT_FILE_COUNT)} files.`, options.instance);
     }
-    const content = await readFile(filePath, "utf8");
+    let content;
+    try {
+        content = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        throwLocalPathReadProblem(error, filePath, options.instance);
+    }
     const bytes = Buffer.byteLength(content, "utf8");
     if (bytes > options.maxFileBytes) {
         throw usageProblem(`Import file ${displayPath} exceeds the per-file byte limit.`, options.instance);
@@ -320,3 +374,35 @@ function isNodeErrorWithCode(error, code) {
         "code" in error &&
         error.code === code;
 }
+function readNodeErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" && code.length > 0 ? code : undefined;
+}
+function isLocalPathReadErrorCode(code) {
+    return code === "EACCES" ||
+        code === "EISDIR" ||
+        code === "ENOENT" ||
+        code === "ENOTDIR" ||
+        code === "EPERM";
+}
+async function readLocalPathStat(absolutePath, instance) {
+    try {
+        return await lstat(absolutePath);
+    }
+    catch (error) {
+        throwLocalPathReadProblem(error, absolutePath, instance);
+    }
+}
+function throwLocalPathReadProblem(error, absolutePath, instance) {
+    const nativeCode = readNodeErrorCode(error);
+    if (nativeCode && isLocalPathReadErrorCode(nativeCode)) {
+        throw usageProblem(`Local path ${absolutePath} could not be read: ${nativeCode}.`, instance, {
+            nativeCode,
+            path: absolutePath
+        });
+    }
+    throw error;
+}