@dac-tech-team-tw/itsaplan-cli 0.0.0-stage → 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import { type Context, type GlobalOptions } from "./contracts.js";
+export type Storage = "keyring" | "file";
+export interface UserConfig {
+    api_url?: string;
+    credentials?: Record<string, {
+        storage: Storage;
+    }>;
+    project_defaults?: Record<string, string>;
+}
+export declare function getConfigPaths(): {
+    directory: string;
+    config: string;
+    credentials: string;
+};
+export declare function normalizeApiUrl(input: string): string;
+export declare function readUserConfig(): Promise<UserConfig>;
+export declare function resolveApiUrl(options: GlobalOptions): Promise<string | undefined>;
+export declare function resolveProject(options: GlobalOptions): Promise<string | undefined>;
+export interface ProjectSelection {
+    projectRef?: string;
+    source: "flag" | "env" | "directory" | "user" | "missing";
+}
+export declare function resolveProjectSelection(options: GlobalOptions): Promise<ProjectSelection>;
+export declare function saveUserProject(input: string, projectRef: string | undefined): Promise<{
+    changed: boolean;
+}>;
+export declare function saveAuth(input: string, token: string, storage?: Storage): Promise<void>;
+export declare function removeAuth(input: string): Promise<{
+    removed: boolean;
+    storage?: string;
+}>;
+export declare function createContext(options: GlobalOptions): Promise<Context>;

package/dist/config.js

@@ -0,0 +1,608 @@
+import { constants } from "node:fs";
+import { access, chmod, lstat, mkdir, open, readFile, rename, rm, } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { parse, stringify } from "smol-toml";
+import { CliError } from "./contracts.js";
+import { HttpClient, registerSecret } from "./http.js";
+const exec = promisify(execFile);
+const object = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const missing = (error) => object(error) && error.code === "ENOENT";
+export function getConfigPaths() {
+    let base;
+    if (process.platform === "darwin")
+        base = join(homedir(), "Library", "Application Support");
+    else if (process.platform === "win32") {
+        if (!process.env.APPDATA)
+            throw new CliError("CONFIG_PATH_UNAVAILABLE", "APPDATA is required to locate user configuration.");
+        base = process.env.APPDATA;
+    }
+    else
+        base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    if (!isAbsolute(base))
+        throw new CliError("INVALID_CONFIG_PATH", "The user configuration directory must be absolute.");
+    const directory = join(base, "itsaplan");
+    return {
+        directory,
+        config: join(directory, "config.toml"),
+        credentials: join(directory, "credentials.json"),
+    };
+}
+export function normalizeApiUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new CliError("INVALID_API_URL", "API URL must be an absolute HTTPS URL.");
+    }
+    const local = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "[::1]";
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && local)) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        input.includes("?") ||
+        input.includes("#") ||
+        /[\\\s]/u.test(input)) {
+        throw new CliError("INVALID_API_URL", "Use HTTPS (HTTP only on localhost), without userinfo, query, fragment, or backslashes.");
+    }
+    url.pathname = url.pathname.replace(/\/+$/u, "");
+    return url.toString().replace(/\/$/u, "");
+}
+async function readToml(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw new CliError("CONFIG_READ_FAILED", "Cannot read configuration file.");
+    }
+    try {
+        const parsed = parse(text);
+        if (object(parsed))
+            return parsed;
+    }
+    catch {
+        /* invalid TOML below */
+    }
+    throw new CliError("INVALID_CONFIG", "Configuration must be a valid TOML table.");
+}
+export async function readUserConfig() {
+    const raw = await readToml(getConfigPaths().config);
+    if (!raw)
+        return {};
+    const config = {};
+    if (raw.api_url !== undefined) {
+        if (typeof raw.api_url !== "string")
+            throw new CliError("INVALID_CONFIG", "User api_url must be a string.");
+        config.api_url = normalizeApiUrl(raw.api_url);
+    }
+    if (raw.credentials !== undefined) {
+        if (!object(raw.credentials))
+            throw new CliError("INVALID_CONFIG", "Credential metadata must be a table.");
+        config.credentials = {};
+        for (const [url, entry] of Object.entries(raw.credentials)) {
+            if (!object(entry) ||
+                (entry.storage !== "keyring" && entry.storage !== "file"))
+                throw new CliError("INVALID_CONFIG", "Unknown credential storage; use keyring or file.");
+            const normalized = normalizeApiUrl(url);
+            if (config.credentials[normalized])
+                throw new CliError("INVALID_CONFIG", "Duplicate normalized API credential endpoints.");
+            config.credentials[normalized] = { storage: entry.storage };
+        }
+    }
+    if (raw.project_defaults !== undefined) {
+        if (!object(raw.project_defaults))
+            throw new CliError("INVALID_CONFIG", "Project defaults must be a table.");
+        config.project_defaults = {};
+        for (const [url, ref] of Object.entries(raw.project_defaults)) {
+            if (typeof ref !== "string" ||
+                !/^[A-Za-z0-9_-]+\.[A-Za-z][A-Za-z0-9_-]*$/u.test(ref))
+                throw new CliError("INVALID_CONFIG", "Saved project defaults must be full team.KEY refs.");
+            const normalized = normalizeApiUrl(url);
+            if (Object.hasOwn(config.project_defaults, normalized))
+                throw new CliError("INVALID_CONFIG", "Duplicate normalized API project endpoints.");
+            config.project_defaults[normalized] = ref;
+        }
+    }
+    return config;
+}
+export async function resolveApiUrl(options) {
+    const value = options.apiUrl ??
+        process.env.ITSAPLAN_URL ??
+        (await readUserConfig()).api_url;
+    return value === undefined ? undefined : normalizeApiUrl(value);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw new CliError("CONFIG_READ_FAILED", "Cannot inspect project configuration boundary.");
+    }
+}
+export async function resolveProject(options) {
+    return (await resolveProjectSelection(options)).projectRef;
+}
+export async function resolveProjectSelection(options) {
+    const cwd = process.cwd();
+    const home = resolve(homedir());
+    let boundary = cwd;
+    const withinHome = cwd === home ||
+        (!relative(home, cwd).startsWith("..") && !isAbsolute(relative(home, cwd)));
+    let current = cwd;
+    while (true) {
+        if (await exists(join(current, ".git"))) {
+            boundary = current;
+            break;
+        }
+        if (withinHome && current === home) {
+            boundary = home;
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            boundary = withinHome ? home : cwd;
+            break;
+        }
+        current = parent;
+    }
+    let project;
+    current = cwd;
+    while (true) {
+        const repo = await readToml(join(current, ".itsaplan.toml"));
+        if (repo) {
+            if ("api_url" in repo)
+                throw new CliError("UNTRUSTED_ENDPOINT", "Repository api_url is forbidden; move the endpoint to user configuration or pass --api-url.");
+            if (repo.project_ref !== undefined &&
+                (typeof repo.project_ref !== "string" || !repo.project_ref.trim()))
+                throw new CliError("INVALID_CONFIG", "Repository project_ref must be a nonempty string.");
+            project =
+                typeof repo.project_ref === "string" ? repo.project_ref : undefined;
+            break;
+        }
+        if (current === boundary)
+            break;
+        current = dirname(current);
+    }
+    let chosen = options.project ?? process.env.ITSAPLAN_PROJECT ?? project;
+    let source = options.project !== undefined
+        ? "flag"
+        : process.env.ITSAPLAN_PROJECT !== undefined
+            ? "env"
+            : project !== undefined
+                ? "directory"
+                : "missing";
+    if (chosen === undefined) {
+        const apiUrl = await resolveApiUrl(options);
+        if (apiUrl !== undefined)
+            chosen = (await readUserConfig()).project_defaults?.[apiUrl];
+        if (chosen !== undefined)
+            source = "user";
+    }
+    if (chosen !== undefined &&
+        !/^(?:[A-Za-z0-9_-]+\.)?[A-Za-z][A-Za-z0-9_-]*$/u.test(chosen))
+        throw new CliError("INVALID_PROJECT", "Use a project key or team.KEY ref.");
+    return { projectRef: chosen, source };
+}
+async function windowsSid() {
+    try {
+        const { stdout } = await exec("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value",
+        ]);
+        const sid = stdout.trim();
+        if (!/^S-1-[0-9-]+$/u.test(sid))
+            throw new Error("Invalid SID");
+        return sid;
+    }
+    catch {
+        throw new CliError("SECURE_STORAGE_UNAVAILABLE", "Cannot determine the current Windows user SID; no credentials were saved.");
+    }
+}
+async function windowsPermissions(path, directory, set) {
+    try {
+        const sid = await windowsSid();
+        const grant = directory ? "(OI)(CI)F" : "F";
+        if (set)
+            await exec("icacls.exe", [
+                path,
+                "/inheritance:r",
+                "/grant:r",
+                `*${sid}:${grant}`,
+                `*S-1-5-18:${grant}`,
+                `*S-1-5-32-544:${grant}`,
+            ]);
+        const script = '$a=Get-Acl -LiteralPath $env:IAP_ACL_PATH; $sid=$env:IAP_ACL_SID; $ok=$a.AreAccessRulesProtected; $mine=$false; foreach($r in $a.Access){ $s=$r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value; if($s -notin @($sid,"S-1-5-18","S-1-5-32-544") -or $r.AccessControlType -ne "Allow"){ $ok=$false }; if($s -eq $sid -and ($r.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -eq [System.Security.AccessControl.FileSystemRights]::FullControl){ $mine=$true } }; if($ok -and $mine){"secure"}else{exit 1}';
+        const { stdout } = await exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { env: { ...process.env, IAP_ACL_PATH: path, IAP_ACL_SID: sid } });
+        if (stdout.trim() !== "secure")
+            throw new Error("ACL verification failed");
+    }
+    catch {
+        throw new CliError("INSECURE_CREDENTIAL_STORAGE", "Cannot enforce or verify Windows credential ACLs; use environment authentication instead.");
+    }
+}
+async function securePath(path, directory, set) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink() ||
+        (directory ? !stat.isDirectory() : !stat.isFile()))
+        throw new CliError("INSECURE_CREDENTIAL_STORAGE", "Credential paths must not be symbolic links or special files.");
+    if (process.platform === "win32")
+        return windowsPermissions(path, directory, set);
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new CliError("INSECURE_CREDENTIAL_STORAGE", "Credential storage must be owned by the current user.");
+    const expected = directory ? 0o700 : 0o600;
+    if (set)
+        await chmod(path, expected);
+    else if ((stat.mode & 0o777) !== expected)
+        throw new CliError("INSECURE_CREDENTIAL_STORAGE", "Credential directory/file permissions must be 0700/0600.");
+}
+async function prepareDirectory() {
+    const { directory } = getConfigPaths();
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await securePath(directory, true, true);
+}
+async function prepareAtomicWrite(path, content) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        try {
+            await securePath(path, false, false);
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const handle = await open(temporary, constants.O_WRONLY |
+            constants.O_CREAT |
+            constants.O_EXCL |
+            (constants.O_NOFOLLOW ?? 0), 0o600);
+        try {
+            await securePath(temporary, false, true);
+            await handle.writeFile(content, "utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        return {
+            async commit() {
+                try {
+                    await securePath(path, false, false);
+                }
+                catch (error) {
+                    if (!missing(error))
+                        throw error;
+                }
+                await rename(temporary, path);
+            },
+            async discard() {
+                await rm(temporary, { force: true });
+            },
+        };
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+async function atomicWrite(path, content) {
+    const prepared = await prepareAtomicWrite(path, content);
+    try {
+        await prepared.commit();
+    }
+    finally {
+        await prepared.discard();
+    }
+}
+export async function saveUserProject(input, projectRef) {
+    const apiUrl = normalizeApiUrl(input);
+    if (projectRef !== undefined &&
+        !/^[A-Za-z0-9_-]+\.[A-Za-z][A-Za-z0-9_-]*$/u.test(projectRef))
+        throw new CliError("INVALID_PROJECT", "Use a full team.KEY project ref.");
+    const config = await readUserConfig();
+    if (config.project_defaults?.[apiUrl] === projectRef)
+        return { changed: false };
+    if (projectRef === undefined) {
+        delete config.project_defaults?.[apiUrl];
+        if (Object.keys(config.project_defaults ?? {}).length === 0)
+            delete config.project_defaults;
+    }
+    else
+        config.project_defaults = {
+            ...config.project_defaults,
+            [apiUrl]: projectRef,
+        };
+    await prepareDirectory();
+    const prepared = await prepareAtomicWrite(getConfigPaths().config, stringify(config));
+    try {
+        await prepared.commit();
+    }
+    catch (error) {
+        await prepared.discard().catch(() => { });
+        throw error;
+    }
+    return { changed: true };
+}
+async function readCredentials() {
+    const { directory, credentials } = getConfigPaths();
+    if (!(await exists(credentials)))
+        return {};
+    await securePath(directory, true, false);
+    await securePath(credentials, false, false);
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(credentials, "utf8"));
+    }
+    catch {
+        throw new CliError("INVALID_CREDENTIAL_STORAGE", "Cannot parse credential storage.");
+    }
+    if (!object(parsed) ||
+        Object.values(parsed).some((value) => typeof value !== "string" || !value))
+        throw new CliError("INVALID_CREDENTIAL_STORAGE", "Credential storage must map endpoints to nonempty keys.");
+    const result = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === "string") {
+            result[key] = value;
+            registerSecret(value);
+        }
+    }
+    return result;
+}
+async function keyringEntry(apiUrl) {
+    // The native OS backend may not exist on the host; defer loading so env/file auth still works.
+    try {
+        const { AsyncEntry } = await import("@napi-rs/keyring");
+        return new AsyncEntry("itsaplan-cli", apiUrl);
+    }
+    catch {
+        throw new CliError("SECURE_STORAGE_UNAVAILABLE", "OS credential storage is unavailable; use environment authentication or explicit --storage file.");
+    }
+}
+async function storedToken(apiUrl, storage) {
+    if (storage === "file")
+        return (await readCredentials())[apiUrl];
+    try {
+        const token = await (await keyringEntry(apiUrl)).getPassword();
+        if (token)
+            registerSecret(token);
+        return token;
+    }
+    catch {
+        throw new CliError("SECURE_STORAGE_UNAVAILABLE", "Cannot read OS credential storage; no file fallback was attempted. Use environment authentication or explicit --storage file.");
+    }
+}
+export async function saveAuth(input, token, storage = "keyring") {
+    const apiUrl = normalizeApiUrl(input);
+    registerSecret(token);
+    if (!token || /[\r\n\0]/u.test(token))
+        throw new CliError("INVALID_TOKEN", "API key must be nonempty and contain no line breaks.");
+    const config = await readUserConfig();
+    await prepareDirectory();
+    const paths = getConfigPaths();
+    const previous = config.credentials?.[apiUrl]?.storage;
+    config.api_url = apiUrl;
+    config.credentials = { ...config.credentials, [apiUrl]: { storage } };
+    // Complete the secure configuration write before touching either credential backend.
+    const prepared = await prepareAtomicWrite(paths.config, stringify(config));
+    try {
+        let save;
+        let restore;
+        let inspect;
+        if (storage === "file") {
+            const credentials = await readCredentials();
+            const existed = await exists(paths.credentials);
+            const original = existed
+                ? await readFile(paths.credentials, "utf8")
+                : undefined;
+            const updated = JSON.stringify({ ...credentials, [apiUrl]: token });
+            save = () => atomicWrite(paths.credentials, updated);
+            restore = async () => {
+                if (original === undefined)
+                    await rm(paths.credentials, { force: true });
+                else
+                    await atomicWrite(paths.credentials, original);
+            };
+            inspect = async () => {
+                const current = await readCredentials();
+                const restored = original === undefined
+                    ? !(await exists(paths.credentials))
+                    : (await readFile(paths.credentials, "utf8")) === original;
+                return { restored, credentialSaved: current[apiUrl] === token };
+            };
+        }
+        else {
+            const entry = await keyringEntry(apiUrl);
+            let original;
+            try {
+                // A failed read is not evidence of absence: never overwrite an unknown credential.
+                original = await entry.getPassword();
+            }
+            catch {
+                throw new CliError("SECURE_STORAGE_UNAVAILABLE", "Cannot read the existing OS credential; no credentials were changed.");
+            }
+            if (original !== undefined)
+                registerSecret(original);
+            save = () => entry.setPassword(token);
+            restore = async () => {
+                if (original === undefined)
+                    await entry.deleteCredential();
+                else
+                    await entry.setPassword(original);
+            };
+            inspect = async () => {
+                const current = await entry.getPassword();
+                return {
+                    restored: current === original,
+                    credentialSaved: current === token,
+                };
+            };
+        }
+        try {
+            await save();
+            await prepared.commit();
+        }
+        catch {
+            // Native methods can throw after applying; only readback confirms restoration.
+            await restore().catch(() => { });
+            const state = await inspect().catch(() => undefined);
+            const rollbackConfirmed = state?.restored === true;
+            const recovery = storage === "file"
+                ? {
+                    path: paths.credentials,
+                    endpoint: apiUrl,
+                    instruction: "Inspect this endpoint in the credential file; restore its previous key or remove only this endpoint. Preserve other endpoints. The saved config was not changed.",
+                }
+                : {
+                    service: "itsaplan-cli",
+                    account: apiUrl,
+                    instruction: "Use the OS credential manager to inspect this service/account and restore its previous key or remove a newly created entry. The saved config was not changed; auth status/logout cannot find an entry without a config pointer.",
+                };
+            throw new CliError("LOCAL_AUTH_INCOMPLETE", rollbackConfirmed
+                ? "Authentication was not saved; the previous credential state was restored and configuration was not changed."
+                : "Authentication could not be saved and credential rollback could not be confirmed; inspect the recovery location before retrying.", rollbackConfirmed ? 1 : 6, {
+                outcome: rollbackConfirmed
+                    ? "not_applied"
+                    : state?.credentialSaved
+                        ? "applied"
+                        : "unknown",
+                verification: !rollbackConfirmed && state?.credentialSaved ? "failed" : "not_run",
+                retryable: false,
+                data: {
+                    action: "login",
+                    apiUrl,
+                    storage,
+                    credentialSaved: rollbackConfirmed ? false : state?.credentialSaved,
+                    configSaved: false,
+                    rollbackConfirmed,
+                    ...(!rollbackConfirmed && { recovery }),
+                },
+            });
+        }
+        if (previous && previous !== storage) {
+            try {
+                await deleteStored(apiUrl, previous);
+            }
+            catch {
+                throw new CliError("LOCAL_AUTH_INCOMPLETE", "The new credential and configuration were saved, but previous credential cleanup failed; inspect auth status before retrying.", 6, {
+                    outcome: "applied",
+                    verification: "failed",
+                    retryable: false,
+                    data: {
+                        action: "login",
+                        apiUrl,
+                        storage,
+                        credentialSaved: true,
+                        configSaved: true,
+                    },
+                });
+            }
+        }
+    }
+    finally {
+        // A nonsecret temporary config cleanup failure must not mask credential recovery details.
+        await prepared.discard().catch(() => { });
+    }
+}
+async function deleteStored(apiUrl, storage) {
+    if (storage === "file") {
+        const credentials = await readCredentials();
+        const existed = apiUrl in credentials;
+        delete credentials[apiUrl];
+        await atomicWrite(getConfigPaths().credentials, JSON.stringify(credentials));
+        return existed;
+    }
+    const entry = await keyringEntry(apiUrl);
+    try {
+        return await entry.deleteCredential();
+    }
+    catch {
+        throw new CliError("LOCAL_WRITE_OUTCOME_UNKNOWN", "OS credential storage did not confirm removal; inspect auth status before retrying.", 6, {
+            outcome: "unknown",
+            verification: "not_run",
+            retryable: false,
+            data: { action: "logout", apiUrl, storage },
+        });
+    }
+}
+export async function removeAuth(input) {
+    const apiUrl = normalizeApiUrl(input);
+    const config = await readUserConfig();
+    const storage = config.credentials?.[apiUrl]?.storage;
+    if (!storage)
+        return { removed: false };
+    await prepareDirectory();
+    const removed = await deleteStored(apiUrl, storage);
+    delete config.credentials?.[apiUrl];
+    try {
+        await atomicWrite(getConfigPaths().config, stringify(config));
+    }
+    catch (error) {
+        if (!removed)
+            throw error;
+        throw new CliError("LOCAL_AUTH_INCOMPLETE", "The credential was removed, but configuration cleanup failed; inspect local authentication before retrying.", 6, {
+            outcome: "applied",
+            verification: "failed",
+            retryable: false,
+            data: {
+                action: "logout",
+                apiUrl,
+                storage,
+                removed: true,
+                configSaved: false,
+            },
+        });
+    }
+    return { removed, storage };
+}
+export async function createContext(options) {
+    // Inspect the repository even when --project overrides its project, never its trust boundary.
+    const project = await resolveProject(options);
+    const envToken = process.env.ITSAPLAN_API_KEY;
+    if ((envToken !== undefined || options.apiKey !== undefined) &&
+        options.apiUrl === undefined &&
+        !process.env.ITSAPLAN_URL)
+        throw new CliError("EXPLICIT_ENDPOINT_REQUIRED", "Environment and one-off API keys require ITSAPLAN_URL or --api-url; a saved default is not a trusted destination.");
+    const apiUrl = await resolveApiUrl(options);
+    if (!apiUrl)
+        throw new CliError("MISSING_API_URL", "Set ITSAPLAN_URL, use --api-url, or run auth login.");
+    let token;
+    let source = "missing";
+    let storage;
+    if (envToken !== undefined) {
+        token = envToken;
+        source = "env";
+    }
+    else {
+        storage = (await readUserConfig()).credentials?.[apiUrl]?.storage;
+        if (storage) {
+            token = await storedToken(apiUrl, storage);
+            if (token)
+                source = "config";
+        }
+        if (!token && options.apiKey !== undefined) {
+            token = options.apiKey;
+            source = "flag";
+            storage = undefined;
+        }
+    }
+    if (token !== undefined && (!token || /[\r\n\0]/u.test(token)))
+        throw new CliError("INVALID_TOKEN", "API key must be nonempty and contain no line breaks.");
+    return {
+        options,
+        project,
+        client: new HttpClient(apiUrl, token),
+        auth: { apiUrl, source, storage, tokenAvailable: Boolean(token) },
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,47 @@
+export type ObjectData = Record<string, unknown>;
+export interface GlobalOptions {
+    json?: boolean;
+    apiUrl?: string;
+    apiKey?: string;
+    project?: string;
+}
+export interface Actor {
+    kind: "agent" | "human";
+    name?: "codex" | "claude";
+    source?: "flag" | "env";
+}
+export interface Result {
+    data: unknown;
+    meta?: ObjectData;
+    outcome?: "applied" | "not_applied" | "unknown";
+    verification?: "passed" | "failed" | "not_run";
+    exitCode?: number;
+    error?: ObjectData;
+}
+export declare class CliError extends Error {
+    code: string;
+    exitCode: number;
+    details: ObjectData;
+    constructor(code: string, message: string, exitCode?: number, details?: ObjectData);
+}
+export interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}
+export interface Client {
+    request(path: string, options?: RequestOptions): Promise<unknown>;
+}
+export interface Context {
+    client: Client;
+    options: GlobalOptions;
+    project?: string;
+    auth: {
+        apiUrl: string;
+        source: string;
+        storage?: string;
+        tokenAvailable: boolean;
+    };
+}
+export declare const CLI_VERSION: string;
+export declare const API_BASELINE = "1.9.0";