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

package/dist/environment-context.d.ts

@@ -0,0 +1,9 @@
+import type { ParsedCommand } from "./runner.js";
+import type { CliSessionState } from "./session.js";
+export interface ResolvedCliEnvironment {
+    environment: string;
+    source: "flag" | "profile" | "production";
+}
+export declare function readCliEnvironmentFlag(parsed: ParsedCommand): string | undefined;
+export declare function readRequiredCliEnvironmentFlag(parsed: ParsedCommand): string;
+export declare function resolveCliEnvironment(parsed: ParsedCommand, session: CliSessionState): ResolvedCliEnvironment;

package/dist/environment-context.js

@@ -0,0 +1,32 @@
+import { readOptionalStringFlag } from "./command-flags.js";
+import { usageProblem } from "./cli-errors.js";
+export function readCliEnvironmentFlag(parsed) {
+    return readOptionalStringFlag(parsed, "environment")?.trim() || undefined;
+}
+export function readRequiredCliEnvironmentFlag(parsed) {
+    const environment = readCliEnvironmentFlag(parsed);
+    if (!environment) {
+        throw usageProblem("Missing required flag --environment.", parsed.definition.id);
+    }
+    return environment;
+}
+export function resolveCliEnvironment(parsed, session) {
+    const fromFlag = readOptionalStringFlag(parsed, "environment")?.trim();
+    if (fromFlag) {
+        return {
+            environment: fromFlag,
+            source: "flag"
+        };
+    }
+    const fromProfile = session.defaultEnvironment?.trim();
+    if (fromProfile) {
+        return {
+            environment: fromProfile,
+            source: "profile"
+        };
+    }
+    return {
+        environment: "production",
+        source: "production"
+    };
+}

package/dist/{integration-commands.d.ts → extension-commands.d.ts}

@@ -1,11 +1,12 @@
 import type { createPlatformApiClient } from "./api-client.js";
 import type { CommandExecutionContext, ExecutedCommand } from "./command-types.js";
-import type { ParsedCommand } from "./runner.js";
 import type { CliSessionState } from "./session.js";
+import type { ParsedCommand } from "./runner.js";
 export type CliOrgScopeResolver = (parsed: ParsedCommand, context: CommandExecutionContext, api: ReturnType<typeof createPlatformApiClient>) => Promise<{
     org: {
         id: string;
+        slug: string;
     };
     session: CliSessionState;
 }>;
-export declare function executeIntegrations(parsed: ParsedCommand, context: CommandExecutionContext, api: ReturnType<typeof createPlatformApiClient>, resolveOrgScope: CliOrgScopeResolver): Promise<ExecutedCommand>;
+export declare function executeExtensions(parsed: ParsedCommand, context: CommandExecutionContext, api: ReturnType<typeof createPlatformApiClient>, resolveOrgScope: CliOrgScopeResolver): Promise<ExecutedCommand>;

package/dist/extension-commands.js

@@ -0,0 +1,446 @@
+import { readOptionalStringFlag, readRequiredStringFlag } from "./command-flags.js";
+import { genericProblem, usageProblem } from "./cli-errors.js";
+import { isZipArchivePath, readArchiveBytes, readJsonInputSpecifier, readPackageFileEntries, readWorkspaceExportMetadata, writeArchiveExport, writePackageExport } from "./files.js";
+import { renderKeyValue, renderPrettyJson, renderSuccess, renderTable } from "./format.js";
+import { confirmDestructive } from "./interaction.js";
+import { readCliEnvironmentFlag, readRequiredCliEnvironmentFlag } from "./environment-context.js";
+export async function executeExtensions(parsed, context, api, resolveOrgScope) {
+    const { org, session } = await resolveOrgScope(parsed, context, api);
+    switch (parsed.definition.id) {
+        case "extensions.export": {
+            const selector = resolveExtensionExportSelector(parsed);
+            const format = readOptionalStringFlag(parsed, "format");
+            const outPath = readOptionalStringFlag(parsed, "out");
+            if (format === "zip") {
+                if (!outPath) {
+                    throw usageProblem("Missing required flag --out when --format zip is used.", parsed.definition.id);
+                }
+                const archive = await api.exportExtensionPackageArchive(session, org.id, selector);
+                await writeArchiveExport(outPath, archive.body, parsed.definition.id);
+                return {
+                    data: { byteLength: archive.body.byteLength, outPath },
+                    human: renderSuccess(`Exported zip archive to ${outPath}.`),
+                    kind: "extensions_export",
+                    meta: withExtensionSummary({ command: parsed.definition.path.join(" "), orgId: org.id, outPath }, "Extension export completed.")
+                };
+            }
+            const data = await api.exportExtensionPackage(session, org.id, selector);
+            if (format === "json") {
+                return {
+                    data,
+                    human: renderPrettyJson(data.exported),
+                    kind: "extensions_export",
+                    meta: withExtensionSummary({ command: parsed.definition.path.join(" "), orgId: org.id }, "Extension export completed.")
+                };
+            }
+            if (!outPath) {
+                throw usageProblem("Missing required flag --out unless --format json is used.", parsed.definition.id);
+            }
+            await writePackageExport(outPath, {
+                files: data.exported.files,
+                metadata: data.exported.metadata
+            });
+            return {
+                data,
+                human: renderSuccess(`Exported ${data.exported.files.length} files to ${outPath}.`),
+                kind: "extensions_export",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), orgId: org.id, outPath }, "Extension export completed.")
+            };
+        }
+        case "extensions.validate": {
+            const path = readRequiredArg(parsed, "path");
+            const subdir = readOptionalStringFlag(parsed, "subdir");
+            const data = isZipArchivePath(path)
+                ? await api.validateExtensionPackageArchive(session, org.id, await readArchiveBytes(path, parsed.definition.id), {
+                    ...(subdir ? { subdir } : {})
+                })
+                : await api.validateExtensionPackage(session, org.id, { files: await readPackageFileEntries(path) });
+            return {
+                data,
+                exitCode: data.ok ? 0 : 1,
+                human: renderValidationHuman(data),
+                kind: "extensions_validate",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), orgId: org.id }, summarizeExtensionValidation(data))
+            };
+        }
+        case "extensions.publish": {
+            const path = readRequiredArg(parsed, "path");
+            const subdir = readOptionalStringFlag(parsed, "subdir");
+            const data = isZipArchivePath(path)
+                ? await api.publishExtensionPackageArchive(session, org.id, await readArchiveBytes(path, parsed.definition.id), {
+                    ...(subdir ? { subdir } : {})
+                })
+                : await api.publishExtensionPackage(session, org.id, { files: await readPackageFileEntries(path) });
+            return {
+                data,
+                human: renderSuccess(`Published extension ${data.package.name} revision ${data.revision.id}.`),
+                kind: "extensions_publish",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), mutated: true, orgId: org.id }, "Extension published.")
+            };
+        }
+        case "extensions.install": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const permissions = await readOptionalPermissions(parsed, context);
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.installExtension(session, org.id, {
+                environment,
+                ...(permissions ? { grantedPermissions: permissions } : {}),
+                packageRevisionId: readRequiredArg(parsed, "package-revision"),
+                slug: readRequiredArg(parsed, "slug")
+            });
+            return {
+                data,
+                human: renderSuccess(`Installed extension ${data.install.slug} in ${environment}.`),
+                kind: "extensions_install",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), environment, mutated: true, orgId: org.id }, "Extension installed.")
+            };
+        }
+        case "extensions.grant": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const permissions = await readRequiredPermissions(parsed, context);
+            const installRef = readRequiredArg(parsed, "install");
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.grantExtensionPermissions(session, org.id, installRef, {
+                environment,
+                ...await readInstallPreconditions(parsed, context, installRef),
+                grantedPermissions: permissions
+            });
+            return {
+                data,
+                human: renderSuccess(`Updated extension grants for ${data.install.slug} in ${environment}.`),
+                kind: "extensions_grant",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), environment, mutated: true, orgId: org.id }, "Extension grants updated.")
+            };
+        }
+        case "extensions.update": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const installRef = readRequiredArg(parsed, "install");
+            const input = {
+                environment,
+                ...await readInstallPreconditions(parsed, context, installRef),
+                packageRevisionId: readRequiredStringFlag(parsed, "revision")
+            };
+            if (parsed.flags["dry-run"] === true) {
+                const data = await api.planExtensionInstallUpdate(session, org.id, installRef, input);
+                const plan = data.plan;
+                return {
+                    data,
+                    exitCode: plan.updateAllowed === false ? 1 : 0,
+                    human: renderPrettyJson(data.plan),
+                    kind: "extensions_update_plan",
+                    meta: withExtensionSummary({ command: parsed.definition.path.join(" "), dryRun: true, environment, mutated: false, orgId: org.id }, summarizeExtensionUpdatePlan(plan))
+                };
+            }
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.updateExtensionInstall(session, org.id, installRef, input);
+            return {
+                data,
+                human: renderSuccess(`Updated extension ${data.install.slug} to ${data.install.packageRevisionId} in ${environment}.`),
+                kind: "extensions_update",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), environment, mutated: true, orgId: org.id }, "Extension updated.")
+            };
+        }
+        case "extensions.built-ins.list": {
+            const environment = readCliEnvironmentFlag(parsed);
+            const data = await api.listBuiltInExtensions(session, org.id, {
+                ...(environment ? { environment } : {})
+            });
+            return {
+                data,
+                human: renderBuiltInExtensionTable(data.builtIns),
+                kind: "extensions_built_ins_list",
+                meta: { command: parsed.definition.path.join(" "), ...(environment ? { environment } : {}), orgId: org.id }
+            };
+        }
+        case "extensions.built-ins.install": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const permissions = await readOptionalPermissions(parsed, context);
+            const slug = readOptionalStringFlag(parsed, "slug");
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.installBuiltInExtension(session, org.id, readRequiredArg(parsed, "built-in"), {
+                environment,
+                ...(permissions ? { grantedPermissions: permissions } : {}),
+                ...(slug ? { slug } : {})
+            });
+            return {
+                data,
+                human: renderSuccess(`Installed built-in extension ${data.install.slug} in ${environment}.`),
+                kind: "extensions_built_ins_install",
+                meta: withExtensionSummary({ command: parsed.definition.path.join(" "), environment, mutated: true, orgId: org.id }, "Built-in extension installed.")
+            };
+        }
+        case "extensions.list": {
+            const environment = readCliEnvironmentFlag(parsed);
+            const data = await api.listExtensionInstalls(session, org.id, {
+                ...(environment ? { environment } : {})
+            });
+            return {
+                data,
+                human: renderExtensionInstallTable(data.installs),
+                kind: "extensions_list",
+                meta: { command: parsed.definition.path.join(" "), ...(environment ? { environment } : {}), orgId: org.id }
+            };
+        }
+        case "extensions.inspect": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const data = await api.getExtensionInstall(session, org.id, readRequiredArg(parsed, "install"), {
+                environment
+            });
+            return {
+                data,
+                human: renderPrettyJson(data.install),
+                kind: "extensions_inspect",
+                meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
+            };
+        }
+        case "extensions.detail": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const data = await api.getExtensionInstallDetail(session, org.id, readRequiredArg(parsed, "install"), {
+                environment
+            });
+            return {
+                data,
+                human: renderExtensionInstallDetailHuman(data.detail),
+                kind: "extensions_detail",
+                meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
+            };
+        }
+        case "extensions.disable": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const installRef = readRequiredArg(parsed, "install");
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.disableExtensionInstall(session, org.id, installRef, {
+                environment
+            });
+            return {
+                data,
+                human: renderSuccess(`Disabled extension ${data.install.slug} in ${environment}.`),
+                kind: "extensions_disable",
+                meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
+            };
+        }
+        case "extensions.enable": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const installRef = readRequiredArg(parsed, "install");
+            announceResolvedEnvironment(parsed, context, environment);
+            const data = await api.enableExtensionInstall(session, org.id, installRef, {
+                environment
+            });
+            return {
+                data,
+                human: renderSuccess(`Enabled extension ${data.install.slug} in ${environment}.`),
+                kind: "extensions_enable",
+                meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
+            };
+        }
+        case "extensions.delete": {
+            const environment = readRequiredCliEnvironmentFlag(parsed);
+            const installRef = readRequiredArg(parsed, "install");
+            announceResolvedEnvironment(parsed, context, environment);
+            await confirmDestructive(parsed, context, `Delete extension install ${installRef} from ${environment}?`);
+            await api.deleteExtensionInstall(session, org.id, installRef, {
+                environment
+            });
+            return {
+                data: {},
+                human: renderSuccess(`Deleted extension install ${installRef} from ${environment}.`),
+                kind: "extensions_delete",
+                meta: { command: parsed.definition.path.join(" "), environment, orgId: org.id }
+            };
+        }
+        default:
+            throw genericProblem(`Unhandled extensions command ${parsed.definition.id}.`, parsed.definition.id);
+    }
+}
+function withExtensionSummary(meta, summary) {
+    const trimmed = summary?.trim();
+    return trimmed && trimmed.length > 0 ? { ...meta, summary: trimmed } : meta;
+}
+function summarizeExtensionValidation(input) {
+    return input.ok
+        ? `Extension validation passed${formatExtensionDiagnosticSuffix(input.diagnostics)}.`
+        : `Extension validation failed${formatExtensionDiagnosticSuffix(input.diagnostics)}.`;
+}
+function summarizeExtensionUpdatePlan(plan) {
+    const diagnostics = Array.isArray(plan.diagnostics)
+        ? plan.diagnostics.filter((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry))
+        : [];
+    return plan.updateAllowed === false
+        ? `Extension update dry run blocked${formatExtensionDiagnosticSuffix(diagnostics)}.`
+        : `Extension update dry run passed${formatExtensionDiagnosticSuffix(diagnostics)}.`;
+}
+function formatExtensionDiagnosticSuffix(diagnostics) {
+    if (diagnostics.length === 0) {
+        return "";
+    }
+    const message = diagnostics
+        .map((diagnostic) => typeof diagnostic.message === "string" ? diagnostic.message.trim() : "")
+        .find((entry) => entry.length > 0);
+    return ` with ${String(diagnostics.length)} diagnostic${diagnostics.length === 1 ? "" : "s"}${message ? `: ${truncateExtensionSummary(message)}` : ""}`;
+}
+function truncateExtensionSummary(value) {
+    return value.length <= 180 ? value : `${value.slice(0, 177)}...`;
+}
+function renderValidationHuman(input) {
+    const summary = renderKeyValue([
+        { label: "Valid", value: input.ok },
+        { label: "Files", value: input.fileCount },
+        { label: "Bytes", value: input.totalBytes },
+        { label: "Revision hash", value: input.revisionHash ?? "" }
+    ]);
+    if (input.diagnostics.length === 0) {
+        return summary;
+    }
+    return [
+        summary,
+        "",
+        renderTable(input.diagnostics, [
+            { key: "code", label: "Code" },
+            { key: "path", label: "Path" },
+            { key: "message", label: "Message" }
+        ])
+    ].join("\n");
+}
+function renderExtensionInstallTable(installs) {
+    return renderTable(installs, [
+        { key: "slug", label: "Slug" },
+        { key: "enabled", label: "Enabled" },
+        { key: "packageRevisionId", label: "Revision" },
+        { key: "grantedPermissions", label: "Grants" }
+    ]);
+}
+function renderBuiltInExtensionTable(builtIns) {
+    return renderTable(builtIns, [
+        { key: "slug", label: "Slug" },
+        { key: "title", label: "Title" },
+        { key: "availability", label: "Availability" },
+        { key: "installedSlug", label: "Installed" },
+        { key: "description", label: "Description" }
+    ]);
+}
+function renderExtensionInstallDetailHuman(detail) {
+    const registrations = readRecord(detail.registrations?.registrations);
+    const functions = Object.keys(readRecord(registrations?.functions) ?? {});
+    const tools = Object.keys(readRecord(registrations?.tools) ?? {});
+    return [
+        renderKeyValue([
+            { label: "Slug", value: detail.install.slug },
+            { label: "Package", value: detail.package.name },
+            { label: "Revision", value: detail.install.packageRevisionId },
+            { label: "Functions", value: functions.join(", ") },
+            { label: "Tools", value: tools.join(", ") }
+        ]),
+        "",
+        renderPrettyJson(detail)
+    ].join("\n");
+}
+function resolveExtensionExportSelector(parsed) {
+    const install = readOptionalStringFlag(parsed, "install");
+    const revision = readOptionalStringFlag(parsed, "revision");
+    const packageName = readOptionalStringFlag(parsed, "package");
+    const selectedCount = [Boolean(install), Boolean(revision), Boolean(packageName)].filter(Boolean).length;
+    if (selectedCount !== 1) {
+        throw usageProblem("Use exactly one of --install, --revision, or --package --latest.", parsed.definition.id);
+    }
+    if (install) {
+        const environment = readRequiredCliEnvironmentFlag(parsed);
+        return { install, ...(environment ? { environment } : {}) };
+    }
+    if (revision) {
+        return { revision };
+    }
+    if (packageName && parsed.flags.latest === true) {
+        return { latest: true, package: packageName };
+    }
+    throw usageProblem("Use --latest when exporting by package name.", parsed.definition.id);
+}
+async function readInstallPreconditions(parsed, context, installRef) {
+    const metadata = await readExtensionInstallExportMetadata(context.cwd, installRef);
+    const explicitBasePackageRevision = readOptionalStringFlag(parsed, "base-package-revision");
+    const explicitBaseUpdatedAt = readOptionalStringFlag(parsed, "base-updated-at");
+    return {
+        ...(metadata?.packageRevisionId
+            ? { basePackageRevisionId: metadata.packageRevisionId }
+            : {}),
+        ...(metadata?.installUpdatedAt
+            ? { baseUpdatedAt: metadata.installUpdatedAt }
+            : {}),
+        ...(explicitBasePackageRevision
+            ? { basePackageRevisionId: explicitBasePackageRevision }
+            : {}),
+        ...(explicitBaseUpdatedAt
+            ? { baseUpdatedAt: explicitBaseUpdatedAt }
+            : {})
+    };
+}
+async function readExtensionInstallExportMetadata(cwd, installRef) {
+    const metadata = await readWorkspaceExportMetadata(cwd);
+    if (!metadata ||
+        metadata.resourceKind !== "extension_package" ||
+        metadata.source !== "install" ||
+        (metadata.installId !== installRef && metadata.installSlug !== installRef)) {
+        return null;
+    }
+    return {
+        ...(typeof metadata.installUpdatedAt === "string"
+            ? { installUpdatedAt: metadata.installUpdatedAt }
+            : {}),
+        ...(typeof metadata.packageRevisionId === "string"
+            ? { packageRevisionId: metadata.packageRevisionId }
+            : {})
+    };
+}
+async function readOptionalPermissions(parsed, context) {
+    const specifier = readOptionalStringFlag(parsed, "permissions");
+    if (!specifier) {
+        return undefined;
+    }
+    return normalizePermissions(await readJsonInputSpecifier(specifier, context.stdin, parsed.definition.id), 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);
+}
+function normalizePermissions(input, instance) {
+    const permissions = input.grantedPermissions && isRecord(input.grantedPermissions)
+        ? input.grantedPermissions
+        : input;
+    const normalized = {};
+    for (const key of ["callbacks", "cloud", "schedules", "secrets", "storage"]) {
+        if (permissions[key] !== undefined) {
+            if (typeof permissions[key] !== "boolean") {
+                throw usageProblem(`Permission '${key}' must be a boolean.`, instance);
+            }
+            normalized[key] = permissions[key];
+        }
+    }
+    if (permissions.egress !== undefined) {
+        if (!Array.isArray(permissions.egress) || permissions.egress.some((entry) => typeof entry !== "string")) {
+            throw usageProblem("Permission 'egress' must be an array of host strings.", instance);
+        }
+        normalized.egress = [...new Set(permissions.egress)].sort();
+    }
+    const unknownKeys = Object.keys(permissions).filter((key) => !["callbacks", "cloud", "egress", "schedules", "secrets", "storage"].includes(key));
+    if (unknownKeys.length > 0) {
+        throw usageProblem(`Unknown extension permission: ${unknownKeys.join(", ")}.`, instance);
+    }
+    return normalized;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readRecord(value) {
+    return isRecord(value) ? value : null;
+}
+function announceResolvedEnvironment(parsed, context, environment) {
+    if (!parsed.json) {
+        context.stdout.write(`Environment: ${environment}\n`);
+    }
+}
+function readRequiredArg(parsed, name) {
+    const value = parsed.args[name];
+    if (!value) {
+        throw usageProblem(`Missing required argument <${name}>.`, parsed.definition.id);
+    }
+    return value;
+}

package/dist/files.d.ts

@@ -5,6 +5,39 @@ export declare function readImportEntries(pathValue: string): Promise<Array<{
     content: string;
     path: string;
 }>>;
+export declare function isZipArchivePath(pathValue: string): boolean;
+export declare function readArchiveBytes(pathValue: string, instance: string): Promise<Uint8Array>;
+export declare function readWorkspaceTestEntries(pathValue: string): Promise<Array<{
+    content: string;
+    path: string;
+}>>;
+export declare function readWorkspaceExportMetadata(pathValue: string): Promise<Record<string, unknown> | null>;
+export declare function writeWorkspaceExport(outPath: string, envelope: {
+    files: Array<{
+        content: string;
+        path: string;
+    }>;
+    metadata: Record<string, unknown>;
+}): Promise<void>;
+export declare function writeReleaseSourceFiles(outPath: string, envelope: {
+    files: Array<{
+        content: string;
+        path: string;
+    }>;
+    metadata: Record<string, unknown>;
+}): Promise<void>;
+export declare function writeArchiveExport(outPath: string, archive: Uint8Array, instance: string): Promise<void>;
+export declare function writePackageExport(outPath: string, envelope: {
+    files: Array<{
+        contentBase64: string;
+        path: string;
+    }>;
+    metadata: Record<string, unknown>;
+}): Promise<void>;
+export declare function readPackageFileEntries(pathValue: string): Promise<Array<{
+    contentBase64: string;
+    path: string;
+}>>;
 export declare function parseEnvFile(pathValue: string): Promise<Array<{
     name: string;
     value: string;