@kora-platform/cli 0.7.0-rc1 → 0.8.0-rc10

package/dist/files.js

@@ -1,16 +1,44 @@
 import { Buffer } from "node:buffer";
-import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, join, relative, resolve } from "node:path";
+import { lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { usageProblem } from "./cli-errors.js";
-import { parseDotEnv } from "./dotenv.js";
-export async function readJsonInputSpecifier(specifier, stdin, instance) {
+import { shouldIgnoreWorkspacePath } from "./workspace-source.js";
+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, 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");
     }
-    return readJsonObject(await readFile(specifier.slice(1), "utf8"), instance);
+    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(source, instance, {
+        filePath,
+        ...options
+    });
 }
 export async function readTextInputSpecifier(specifier, stdin, instance) {
     if (specifier === "-") {
@@ -22,36 +50,187 @@ export async function readTextInputSpecifier(specifier, stdin, instance) {
     return readFile(specifier.slice(1), "utf8");
 }
 export async function readImportEntries(pathValue) {
+    return await readUtf8Entries(pathValue, {
+        instance: "org.import",
+        maxFileBytes: MAX_IMPORT_FILE_BYTES
+    });
+}
+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 stat(absolutePath);
+    const pathStat = await readLocalPathStat(absolutePath, instance);
+    if (pathStat.isSymbolicLink() || !pathStat.isFile()) {
+        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);
+    }
+}
+export async function readWorkspaceTestEntries(pathValue) {
+    return await readUtf8Entries(pathValue, {
+        instance: "test node",
+        maxFileBytes: MAX_PACKAGE_FILE_BYTES
+    });
+}
+async function readUtf8Entries(pathValue, options) {
+    const absolutePath = resolve(pathValue);
+    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);
+    }
     if (pathStat.isFile()) {
+        const pathName = basename(absolutePath);
+        if (shouldIgnoreSourceImportPath(pathName)) {
+            return [];
+        }
+        const content = await readLimitedUtf8File(absolutePath, pathName, {
+            fileCount: 0,
+            totalBytes: 0
+        }, options);
         return [{
-                content: await readFile(absolutePath, "utf8"),
+                content: content.content,
                 path: basename(absolutePath)
             }];
     }
     const entries = [];
-    await walkImportDirectory(absolutePath, absolutePath, entries);
+    await walkImportDirectory(absolutePath, absolutePath, entries, {
+        fileCount: 0,
+        totalBytes: 0
+    }, options);
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return entries;
 }
-export async function parseEnvFile(pathValue) {
-    const content = await readFile(pathValue, "utf8");
-    return Object.entries(parseDotEnv(content)).map(([name, value]) => ({
-        name,
-        value
-    }));
+export async function readWorkspaceExportMetadata(pathValue) {
+    const absolutePath = resolve(pathValue);
+    try {
+        const metadata = await readFile(join(absolutePath, ".kora", "export.json"), "utf8");
+        const parsed = JSON.parse(metadata);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT") || isNodeErrorWithCode(error, "ENOTDIR")) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeWorkspaceExport(outPath, envelope) {
+    const absolutePath = resolve(outPath);
+    await assertExportOutputIsEmpty(absolutePath, "org.export");
+    await mkdir(absolutePath, { recursive: true });
+    for (const file of envelope.files) {
+        const targetPath = resolveExportTargetPath(absolutePath, file.path, "org.export");
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, file.content, "utf8");
+    }
+    const metadataPath = join(absolutePath, ".kora", "export.json");
+    await mkdir(dirname(metadataPath), { recursive: true });
+    await writeFile(metadataPath, `${JSON.stringify(envelope.metadata, null, 2)}\n`, "utf8");
+}
+export async function writeReleaseSourceFiles(outPath, envelope) {
+    const absolutePath = resolve(outPath);
+    await assertExportOutputIsEmpty(absolutePath, "release source", "Release source");
+    await mkdir(absolutePath, { recursive: true });
+    const seenPaths = new Set();
+    for (const file of envelope.files) {
+        if (seenPaths.has(file.path)) {
+            throw usageProblem(`Release source contains duplicate file path '${file.path}'.`, "release source");
+        }
+        seenPaths.add(file.path);
+        const targetPath = resolveExportTargetPath(absolutePath, file.path, "release source");
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, file.content, "utf8");
+    }
+    const metadataPath = join(absolutePath, ".kora", "release-source.json");
+    await mkdir(dirname(metadataPath), { recursive: true });
+    await writeFile(metadataPath, `${JSON.stringify(envelope.metadata, null, 2)}\n`, "utf8");
 }
-function readJsonObject(source, instance) {
+export async function writeArchiveExport(outPath, archive, instance) {
+    const absolutePath = resolve(outPath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    try {
+        await writeFile(absolutePath, archive, { flag: "wx" });
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "EEXIST")) {
+            throw usageProblem("Export output file already exists.", instance);
+        }
+        throw error;
+    }
+}
+export async function writePackageExport(outPath, envelope) {
+    const absolutePath = resolve(outPath);
+    await assertExportOutputIsEmpty(absolutePath, "extensions.export");
+    await mkdir(absolutePath, { recursive: true });
+    for (const file of envelope.files) {
+        const targetPath = resolveExportTargetPath(absolutePath, file.path, "extensions.export");
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, Buffer.from(file.contentBase64, "base64"));
+    }
+    const metadataPath = join(absolutePath, ".kora", "export.json");
+    await mkdir(dirname(metadataPath), { recursive: true });
+    await writeFile(metadataPath, `${JSON.stringify(envelope.metadata, null, 2)}\n`, "utf8");
+}
+export async function readPackageFileEntries(pathValue, instance) {
+    const absolutePath = resolve(pathValue);
+    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);
+    }
+    if (pathStat.isFile()) {
+        assertPackageFileCanBeRead(pathStat.size, basename(absolutePath), {
+            fileCount: 0,
+            totalBytes: 0
+        }, instance);
+        return [{
+                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)
+            }];
+    }
+    const entries = [];
+    await walkPackageDirectory(absolutePath, absolutePath, entries, {
+        fileCount: 0,
+        totalBytes: 0
+    }, instance);
+    entries.sort((left, right) => left.path.localeCompare(right.path));
+    return entries;
+}
+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;
 }
@@ -62,24 +241,168 @@ async function readStream(stream) {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-async function walkImportDirectory(root, current, entries) {
+async function walkImportDirectory(root, current, entries, counters, options) {
     const children = await readdir(current, { withFileTypes: true });
     children.sort((left, right) => left.name.localeCompare(right.name));
     for (const child of children) {
-        if (shouldIgnoreImportSegment(child.name)) {
+        const childPath = join(current, child.name);
+        const relativePath = relative(root, childPath).replaceAll("\\", "/");
+        if (shouldIgnoreSourceImportPath(relativePath)) {
+            continue;
+        }
+        if (child.isDirectory()) {
+            await walkImportDirectory(root, childPath, entries, counters, options);
+            continue;
+        }
+        if (!child.isFile()) {
             continue;
         }
+        const content = await readLimitedUtf8File(childPath, relativePath, counters, options);
+        entries.push({
+            content: content.content,
+            path: relativePath
+        });
+    }
+}
+async function walkPackageDirectory(root, current, entries, counters, instance) {
+    const children = await readdir(current, { withFileTypes: true });
+    children.sort((left, right) => left.name.localeCompare(right.name));
+    for (const child of children) {
         const childPath = join(current, child.name);
+        const relativePath = relative(root, childPath).replaceAll("\\", "/");
+        if (shouldIgnoreImportPath(relativePath)) {
+            continue;
+        }
         if (child.isDirectory()) {
-            await walkImportDirectory(root, childPath, entries);
+            await walkPackageDirectory(root, childPath, entries, counters, instance);
             continue;
         }
+        if (!child.isFile()) {
+            continue;
+        }
+        const childStat = await readLocalPathStat(childPath, instance);
+        assertPackageFileCanBeRead(childStat.size, relativePath, counters, instance);
         entries.push({
-            content: await readFile(childPath, "utf8"),
-            path: relative(root, childPath).replaceAll("\\", "/")
+            contentBase64: (await readLocalFileBytes(childPath, instance)).bytes.toString("base64"),
+            path: relativePath
         });
     }
 }
-function shouldIgnoreImportSegment(segment) {
-    return new Set([".git", ".kora", "coverage", "dist", "node_modules"]).has(segment);
+function shouldIgnoreImportPath(pathValue) {
+    return shouldIgnoreWorkspacePath(pathValue);
+}
+function shouldIgnoreSourceImportPath(pathValue) {
+    return shouldIgnoreImportPath(pathValue) || isRemovedRuntimeEnvironmentPath(pathValue);
+}
+function isRemovedRuntimeEnvironmentPath(pathValue) {
+    return pathValue === ".env" || pathValue === ".env.example";
+}
+async function assertExportOutputIsEmpty(absolutePath, instance, outputLabel = "Export") {
+    try {
+        const pathStat = await lstat(absolutePath);
+        if (pathStat.isSymbolicLink()) {
+            throw usageProblem(`${outputLabel} output path must not be a symbolic link.`, instance);
+        }
+        if (!pathStat.isDirectory()) {
+            throw usageProblem(`${outputLabel} output path must be a directory.`, instance);
+        }
+        const children = await readdir(absolutePath);
+        if (children.length > 0) {
+            throw usageProblem(`${outputLabel} output directory must be empty or not exist.`, instance);
+        }
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+}
+function resolveExportTargetPath(root, filePath, instance) {
+    const normalizedPath = filePath.replaceAll("\\", "/");
+    const segments = normalizedPath.split("/");
+    if (normalizedPath.trim().length === 0 ||
+        isAbsolute(normalizedPath) ||
+        segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        throw usageProblem("Export file paths must be relative paths inside the output directory.", instance);
+    }
+    const targetPath = resolve(root, normalizedPath);
+    const relativeTarget = relative(root, targetPath);
+    if (relativeTarget === "" || relativeTarget.startsWith("..") || isAbsolute(relativeTarget)) {
+        throw usageProblem("Export file paths must be relative paths inside the output directory.", instance);
+    }
+    return targetPath;
+}
+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);
+    }
+    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);
+    }
+    if (counters.totalBytes + bytes > MAX_IMPORT_TOTAL_BYTES) {
+        throw usageProblem(`Import exceeds the ${String(MAX_IMPORT_TOTAL_BYTES)} byte limit.`, options.instance);
+    }
+    counters.fileCount += 1;
+    counters.totalBytes += bytes;
+    return { content };
+}
+function assertPackageFileCanBeRead(bytes, displayPath, counters, instance) {
+    if (counters.fileCount >= MAX_IMPORT_FILE_COUNT) {
+        throw usageProblem(`Package has more than ${String(MAX_IMPORT_FILE_COUNT)} files.`, instance);
+    }
+    if (bytes > MAX_PACKAGE_FILE_BYTES) {
+        throw usageProblem(`Package file ${displayPath} exceeds the per-file byte limit.`, instance);
+    }
+    if (counters.totalBytes + bytes > MAX_IMPORT_TOTAL_BYTES) {
+        throw usageProblem(`Package exceeds the ${String(MAX_IMPORT_TOTAL_BYTES)} byte limit.`, instance);
+    }
+    counters.fileCount += 1;
+    counters.totalBytes += bytes;
+}
+function isNodeErrorWithCode(error, code) {
+    return typeof error === "object" &&
+        error !== null &&
+        "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;
 }

package/dist/format.d.ts

@@ -1,4 +1,5 @@
 export interface CommandOutput {
+    exitCode?: number;
     human: string;
     kind: string;
     meta?: Record<string, unknown>;
@@ -9,7 +10,9 @@ export declare function renderJsonEnvelope(input: {
     meta?: Record<string, unknown>;
 }): string;
 export declare function renderProblemJson(input: {
+    code: string;
     detail: string;
+    details?: Record<string, unknown>;
     instance: string;
     status: number;
     title: string;
@@ -27,12 +30,15 @@ export declare function renderPrettyJson(value: unknown): string;
 export declare function renderVerboseHuman(base: string, data: unknown): string;
 export declare function renderVerboseProblem(input: {
     detail: string;
+    details?: Record<string, unknown>;
     instance: string;
     rawDetail?: string;
     title: string;
     type: string;
 }): string;
 export declare function renderSuccess(message: string): string;
+export declare function formatProblemDetail(detail: string, details?: Record<string, unknown>): string;
+export declare function formatProblemDetailsSummary(details: Record<string, unknown> | undefined): string | null;
 export declare function renderDiffSummary(input: {
     added: string[];
     changed: string[];

package/dist/format.js

@@ -6,7 +6,19 @@ export function renderJsonEnvelope(input) {
     }, null, 2)}\n`;
 }
 export function renderProblemJson(input) {
-    return `${JSON.stringify(input, null, 2)}\n`;
+    return `${JSON.stringify({
+        error: {
+            code: input.code,
+            details: {
+                ...(input.details ?? {}),
+                instance: input.instance,
+                status: input.status,
+                title: input.title,
+                type: input.type
+            },
+            message: input.detail
+        }
+    }, null, 2)}\n`;
 }
 export function renderTable(rows, columns) {
     if (rows.length === 0) {
@@ -38,8 +50,10 @@ export function renderVerboseHuman(base, data) {
     return `${base}\n\nDetails:\n${detail}`;
 }
 export function renderVerboseProblem(input) {
+    const detailsSummary = formatProblemDetailsSummary(input.details);
     const lines = [
         `${input.title}: ${input.detail}`,
+        ...(detailsSummary ? ["", detailsSummary] : []),
         "",
         "Details:",
         `Type: ${input.type}`,
@@ -48,11 +62,79 @@ export function renderVerboseProblem(input) {
     if (input.rawDetail && input.rawDetail !== input.detail) {
         lines.push(`Raw backend message: ${input.rawDetail}`);
     }
+    if (input.details) {
+        lines.push(`Structured details: ${renderPrettyJson(input.details)}`);
+    }
     return lines.join("\n");
 }
 export function renderSuccess(message) {
     return message;
 }
+export function formatProblemDetail(detail, details) {
+    const detailsSummary = formatProblemDetailsSummary(details);
+    return detailsSummary ? `${detail}\n${detailsSummary}` : detail;
+}
+export function formatProblemDetailsSummary(details) {
+    if (!details) {
+        return null;
+    }
+    const diagnostics = formatProblemDetailsList(details.diagnostics, "Diagnostics", formatDiagnosticLikeEntry);
+    if (diagnostics) {
+        return diagnostics;
+    }
+    const errors = formatProblemDetailsList(details.errors, "Errors", formatUnknownDetailEntry);
+    if (errors) {
+        return errors;
+    }
+    return formatProblemDetailsList(details.issues, "Issues", formatUnknownDetailEntry);
+}
+function formatProblemDetailsList(value, label, formatter) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return null;
+    }
+    const lines = value
+        .map(formatter)
+        .filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    if (lines.length === 0) {
+        return null;
+    }
+    return [label, ...lines.slice(0, 5).map((entry) => `- ${entry}`)].join("\n");
+}
+function formatDiagnosticLikeEntry(entry) {
+    if (!isRecord(entry)) {
+        return formatUnknownDetailEntry(entry);
+    }
+    const message = readString(entry.message);
+    if (!message) {
+        return formatUnknownDetailEntry(entry);
+    }
+    const path = readString(entry.path) ?? readString(entry.filePath) ?? readString(entry.instancePath);
+    const code = readString(entry.code);
+    return [
+        path ? `${path}:` : null,
+        message,
+        code && !path ? `(${code})` : null
+    ].filter((part) => typeof part === "string" && part.length > 0).join(" ");
+}
+function formatUnknownDetailEntry(entry) {
+    if (typeof entry === "string") {
+        return entry.trim() || null;
+    }
+    if (isRecord(entry)) {
+        const message = readString(entry.message);
+        if (message) {
+            const path = readString(entry.path) ?? readString(entry.instancePath);
+            return path ? `${path}: ${message}` : message;
+        }
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
 export function renderDiffSummary(input) {
     const lines = [
         `Add: ${input.added.length}`,

package/dist/runner.js

@@ -2,7 +2,7 @@ import { defaultGlobalConfigPath, loadCliConfig } from "./config.js";
 import { authProblem, exitCodeFromError, toProblem, usageProblem } from "./cli-errors.js";
 import { buildHelpJson, findCommandDefinition, listSubcommands, resolveCommandAliases } from "./command-registry.js";
 import { executeParsedCommand } from "./commands.js";
-import { renderJsonEnvelope, renderProblemJson, renderVerboseHuman, renderVerboseProblem } from "./format.js";
+import { formatProblemDetail, renderJsonEnvelope, renderProblemJson, renderVerboseHuman, renderVerboseProblem } from "./format.js";
 import { createFileSessionStore, createMemorySessionStore } from "./session-store.js";
 import { defaultSessionPath, readSessionFromEnv } from "./session.js";
 const VISIBLE_COMMAND_LABELS_ENV = "KORA_VISIBLE_COMMAND_LABELS";
@@ -57,7 +57,7 @@ export async function runCli(argv, input = {}) {
             stdout
         });
         return {
-            exitCode: 0,
+            exitCode: executed.exitCode ?? 0,
             stderr: "",
             stdout: parsed.json
                 ? renderJsonEnvelope({
@@ -72,6 +72,7 @@ export async function runCli(argv, input = {}) {
         const wantsJson = tokens.includes("--json");
         const wantsVerbose = tokens.includes("--verbose");
         const problem = toProblem(error, tokens.join(" "));
+        const details = hasProblemDetails(problem) ? problem.details : undefined;
         return {
             exitCode: exitCodeFromError(problem),
             stderr: wantsJson
@@ -79,15 +80,18 @@ export async function runCli(argv, input = {}) {
                 : `${wantsVerbose
                     ? renderVerboseProblem({
                         detail: problem.detail,
+                        ...(details ? { details } : {}),
                         instance: problem.instance,
                         ...(hasRawDetail(problem) ? { rawDetail: problem.rawDetail } : {}),
                         title: problem.title,
                         type: problem.type
                     })
-                    : `${problem.title}: ${problem.detail}`}\n`,
+                    : `${problem.title}: ${formatProblemDetail(problem.detail, details)}`}\n`,
             stdout: wantsJson
                 ? renderProblemJson({
+                    code: problem.code,
                     detail: problem.detail,
+                    ...(details ? { details } : {}),
                     instance: problem.instance,
                     status: problem.status,
                     title: problem.title,
@@ -137,6 +141,9 @@ function resolveHelpInvocation(tokens, commandFilter) {
 function hasRawDetail(problem) {
     return "rawDetail" in problem && typeof problem.rawDetail === "string";
 }
+function hasProblemDetails(problem) {
+    return "details" in problem && typeof problem.details === "object" && problem.details !== null && !Array.isArray(problem.details);
+}
 function normalizeHelpPath(tokens, commandFilter) {
     if (tokens.length === 0) {
         return [];
@@ -213,7 +220,10 @@ function parseInvocation(tokens, commandFilter) {
         throw usageProblem(withHelpSuggestion(`Unknown command: ${tokens.join(" ")}.`, resolved.commandPath, commandFilter), tokens.join(" "));
     }
     const definition = resolved.definition;
-    const flagDefinitions = new Map(definition.flags.map((entry) => [entry.name, entry]));
+    const visibleFlags = commandFilter
+        ? definition.flags.filter((entry) => !entry.hiddenWhenCommandFiltered)
+        : definition.flags;
+    const flagDefinitions = new Map(visibleFlags.map((entry) => [entry.name, entry]));
     const positionals = [];
     const flags = {};
     for (let index = 0; index < resolved.remainder.length; index += 1) {
@@ -222,7 +232,10 @@ function parseInvocation(tokens, commandFilter) {
             positionals.push(token);
             continue;
         }
-        const [rawName = "", maybeValue] = token.slice(2).split("=", 2);
+        const rawFlag = token.slice(2);
+        const valueSeparatorIndex = rawFlag.indexOf("=");
+        const rawName = valueSeparatorIndex === -1 ? rawFlag : rawFlag.slice(0, valueSeparatorIndex);
+        const maybeValue = valueSeparatorIndex === -1 ? undefined : rawFlag.slice(valueSeparatorIndex + 1);
         const flag = flagDefinitions.get(rawName);
         if (!flag) {
             const detail = rawName === "output"
@@ -237,11 +250,16 @@ function parseInvocation(tokens, commandFilter) {
             flags[rawName] = true;
             continue;
         }
-        const valueSource = maybeValue ?? resolved.remainder[index + 1];
-        if (!valueSource || valueSource.startsWith("--")) {
-            throw usageProblem(`Flag '--${rawName}' requires a value.`, definition.path.join(" "));
+        let valueSource;
+        if (maybeValue !== undefined) {
+            valueSource = maybeValue;
         }
-        if (maybeValue === undefined) {
+        else {
+            const nextValue = resolved.remainder[index + 1];
+            if (!nextValue || nextValue.startsWith("--")) {
+                throw usageProblem(`Flag '--${rawName}' requires a value.`, definition.path.join(" "));
+            }
+            valueSource = nextValue;
             index += 1;
         }
         const coercedValue = coerceFlagValue(flag.valueType ?? "string", valueSource, rawName, definition.path.join(" "));
@@ -254,7 +272,7 @@ function parseInvocation(tokens, commandFilter) {
     if (positionals.length > definition.args.length) {
         throw usageProblem(`Too many positional arguments for '${definition.path.join(" ")}'.`, definition.path.join(" "));
     }
-    for (const flag of definition.flags) {
+    for (const flag of visibleFlags) {
         if (flag.required && flags[flag.name] === undefined) {
             throw usageProblem(`Missing required flag '--${flag.name}'.`, definition.path.join(" "));
         }