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

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;
+}

package/dist/format.d.ts

@@ -10,6 +10,7 @@ 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;

package/dist/format.js

@@ -7,12 +7,17 @@ export function renderJsonEnvelope(input) {
 }
 export function renderProblemJson(input) {
     return `${JSON.stringify({
-        detail: input.detail,
-        ...(input.details ? { details: input.details } : {}),
-        instance: input.instance,
-        status: input.status,
-        title: input.title,
-        type: input.type
+        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) {

package/dist/runner.js

@@ -89,6 +89,7 @@ export async function runCli(argv, input = {}) {
                     : `${problem.title}: ${formatProblemDetail(problem.detail, details)}`}\n`,
             stdout: wantsJson
                 ? renderProblemJson({
+                    code: problem.code,
                     detail: problem.detail,
                     ...(details ? { details } : {}),
                     instance: problem.instance,
@@ -231,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"
@@ -246,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(" "));

package/dist/session-store.js

@@ -1,5 +1,10 @@
+import { mkdir, open, rm, stat } from "node:fs/promises";
+import { dirname } from "node:path";
 import { readSessionFile, removeSessionFile, writeSessionFile } from "./session.js";
+const REFRESH_LOCK_STALE_MS = 30_000;
+const REFRESH_LOCK_RETRY_MS = 25;
 export function createFileSessionStore(path) {
+    const refreshLockPath = `${path}.refresh.lock`;
     return {
         async clear() {
             await removeSessionFile(path);
@@ -9,11 +14,15 @@ export function createFileSessionStore(path) {
         },
         async write(session) {
             await writeSessionFile(path, session);
+        },
+        async withRefreshLock(operation) {
+            return withFileRefreshLock(refreshLockPath, operation);
         }
     };
 }
 export function createMemorySessionStore(initial = null) {
     let current = initial;
+    let refreshLock = Promise.resolve();
     return {
         async clear() {
             current = null;
@@ -23,6 +32,77 @@ export function createMemorySessionStore(initial = null) {
         },
         async write(session) {
             current = session;
+        },
+        async withRefreshLock(operation) {
+            const previous = refreshLock;
+            let release;
+            refreshLock = new Promise((resolve) => {
+                release = resolve;
+            });
+            await previous;
+            try {
+                return await operation();
+            }
+            finally {
+                release();
+            }
         }
     };
 }
+async function withFileRefreshLock(lockPath, operation) {
+    const release = await acquireFileRefreshLock(lockPath);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+async function acquireFileRefreshLock(lockPath) {
+    await mkdir(dirname(lockPath), { recursive: true });
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            try {
+                await handle.writeFile(`${String(process.pid)} ${new Date().toISOString()}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+            return async () => {
+                await rm(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            if (!isFileExistsError(error)) {
+                throw error;
+            }
+            await removeStaleFileRefreshLock(lockPath);
+            await sleep(REFRESH_LOCK_RETRY_MS);
+        }
+    }
+}
+async function removeStaleFileRefreshLock(lockPath) {
+    try {
+        const fileStat = await stat(lockPath);
+        if (Date.now() - fileStat.mtimeMs > REFRESH_LOCK_STALE_MS) {
+            await rm(lockPath, { force: true });
+        }
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            throw error;
+        }
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isFileExistsError(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "EEXIST");
+}
+function isMissingFileError(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}

package/dist/transport-refresh.d.ts

@@ -0,0 +1,10 @@
+import type { CliSessionState } from "./session.js";
+import type { SessionStore } from "./transport.js";
+export declare function refreshSessionWithCoordination(input: {
+    isRefreshTokenInvalidError: (error: unknown) => boolean;
+    refreshSessionDirect: (session: CliSessionState) => Promise<CliSessionState>;
+    session: CliSessionState;
+    sessionStore: SessionStore;
+    shouldRefresh: (session: CliSessionState) => boolean;
+}): Promise<CliSessionState>;
+export declare function resolveEffectiveSession(requestSession: CliSessionState | null, sessionStore: SessionStore): Promise<CliSessionState | null>;

package/dist/transport-refresh.js

@@ -0,0 +1,51 @@
+export async function refreshSessionWithCoordination(input) {
+    return withRefreshLock(input.sessionStore, async () => {
+        const effectiveSession = (await resolveEffectiveSession(input.session, input.sessionStore)) ?? input.session;
+        if (isSessionNewer(effectiveSession, input.session) && !input.shouldRefresh(effectiveSession)) {
+            return effectiveSession;
+        }
+        try {
+            return await input.refreshSessionDirect(effectiveSession);
+        }
+        catch (error) {
+            if (input.isRefreshTokenInvalidError(error)) {
+                const recoveredSession = await resolveEffectiveSession(input.session, input.sessionStore);
+                if (recoveredSession &&
+                    isSessionNewer(recoveredSession, input.session) &&
+                    !input.shouldRefresh(recoveredSession)) {
+                    return recoveredSession;
+                }
+            }
+            throw error;
+        }
+    });
+}
+async function withRefreshLock(sessionStore, operation) {
+    return sessionStore.withRefreshLock
+        ? sessionStore.withRefreshLock(operation)
+        : operation();
+}
+export async function resolveEffectiveSession(requestSession, sessionStore) {
+    if (!requestSession) {
+        return null;
+    }
+    const storedSession = await sessionStore.read();
+    if (!storedSession || !isSameSessionIdentity(storedSession, requestSession)) {
+        return requestSession;
+    }
+    return isSessionNewer(storedSession, requestSession) ? storedSession : requestSession;
+}
+function isSameSessionIdentity(candidate, current) {
+    return candidate.baseUrl === current.baseUrl
+        && candidate.user.id === current.user.id
+        && candidate.accessTokenPayload.sub === current.accessTokenPayload.sub;
+}
+function isSessionNewer(candidate, current) {
+    if (candidate.accessToken === current.accessToken && candidate.refreshToken === current.refreshToken) {
+        return false;
+    }
+    if (candidate.accessTokenPayload.exp !== current.accessTokenPayload.exp) {
+        return candidate.accessTokenPayload.exp > current.accessTokenPayload.exp;
+    }
+    return candidate.accessTokenPayload.iat >= current.accessTokenPayload.iat;
+}

package/dist/transport.d.ts

@@ -2,6 +2,7 @@ import { type CliSessionState } from "./session.js";
 export interface SessionStore {
     clear(): Promise<void>;
     read(): Promise<CliSessionState | null>;
+    withRefreshLock?<T>(operation: () => Promise<T>): Promise<T>;
     write(session: CliSessionState): Promise<void>;
 }
 export interface CliAuthSettings {
@@ -10,6 +11,19 @@ export interface CliAuthSettings {
     oidcEnabled: boolean;
     selfServiceOrgCreationEnabled: boolean;
 }
+export interface CliDeviceLoginStart {
+    deviceCode: string;
+    expiresAt: string;
+    pollIntervalSeconds: number;
+    userCode: string;
+    verificationPath: string;
+}
+export type CliDeviceLoginClaim = {
+    session: CliSessionState;
+    status: "approved";
+} | {
+    status: "denied" | "expired" | "pending";
+};
 export type ApiErrorDetails = Record<string, unknown>;
 type RequestBody = unknown | ((session: CliSessionState) => unknown);
 type BytesRequest = {
@@ -26,6 +40,7 @@ type BytesRequest = {
     validateHeaders?: (headers: Headers) => void;
 };
 export declare class ApiError extends Error {
+    readonly code: string;
     readonly detail: string;
     readonly details?: ApiErrorDetails;
     readonly instance: string;
@@ -34,6 +49,7 @@ export declare class ApiError extends Error {
     readonly title: string;
     readonly type: string;
     constructor(input: {
+        code?: string;
         detail: string;
         details?: ApiErrorDetails;
         instance: string;
@@ -59,6 +75,11 @@ export declare function createPlatformTransport(input: {
         name: string;
         password: string;
     }): Promise<CliSessionState>;
+    startDeviceLogin(baseUrl: string): Promise<CliDeviceLoginStart>;
+    claimDeviceLogin(claim: {
+        baseUrl: string;
+        deviceCode: string;
+    }): Promise<CliDeviceLoginClaim>;
     refreshSession(session: CliSessionState): Promise<CliSessionState>;
     requestJson<T>(request: {
         body?: RequestBody;