@knowttl/kubernetes-axi 0.0.0-stage → 0.1.0

package/dist/byte-process.d.ts

@@ -0,0 +1,9 @@
+import type { Redactor } from './redaction.js';
+export interface ByteExecution {
+    input: Buffer;
+    signal: AbortSignal;
+    timeoutMs: number;
+    controlStdout?: boolean;
+    output: (channel: 'stdout' | 'stderr', bytes: Buffer) => Promise<void>;
+}
+export declare function byteProcess(binary: string, args: string[], env: NodeJS.ProcessEnv, execution: ByteExecution, redactor: Redactor): Promise<number>;

package/dist/byte-process.js

@@ -0,0 +1,56 @@
+import { spawn } from 'node:child_process';
+import { Failure } from './errors.js';
+export async function byteProcess(binary, args, env, execution, redactor) {
+    if (execution.signal.aborted)
+        throw new Failure('CANCELLED', 'The session was cancelled.');
+    const child = spawn(binary, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    let killTimer;
+    let timedOut = false;
+    const stop = () => {
+        child.kill('SIGTERM');
+        killTimer ??= setTimeout(() => { child.kill('SIGKILL'); }, 1000);
+    };
+    execution.signal.addEventListener('abort', stop, { once: true });
+    const timer = setTimeout(() => { timedOut = true; stop(); }, execution.timeoutMs);
+    child.stdin.on('error', () => { });
+    child.stdin.end(execution.input);
+    const exit = new Promise((resolve, reject) => {
+        child.once('error', () => reject(new Failure('UPSTREAM_FAILED', 'The bounded process could not start.')));
+        child.once('close', code => resolve(code ?? 1));
+    });
+    const channels = ['stdout', 'stderr'].map(async (channel) => {
+        const guard = redactor.byteStream();
+        try {
+            for await (const chunk of child[channel]) {
+                const safe = channel === 'stdout' && execution.controlStdout ? Buffer.from(chunk) : guard.push(Buffer.from(chunk));
+                if (safe.length)
+                    await execution.output(channel, safe);
+            }
+            const tail = guard.end();
+            if (tail.length)
+                await execution.output(channel, tail);
+        }
+        catch (error) {
+            stop();
+            if (error instanceof Failure)
+                throw error;
+            throw new Failure('CREDENTIAL_OUTPUT_REFUSED', 'Binary output was withheld or its consumer disconnected.');
+        }
+    });
+    try {
+        const outcomes = await Promise.allSettled([exit, ...channels]);
+        const failure = outcomes.find(outcome => outcome.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
+        if (execution.signal.aborted)
+            throw new Failure('CANCELLED', 'The session was cancelled.');
+        if (timedOut)
+            throw new Failure('UPSTREAM_TIMEOUT', 'The session reached its time limit.');
+        return outcomes[0].value;
+    }
+    finally {
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        execution.signal.removeEventListener('abort', stop);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,68 @@
+import { encode } from '@toon-format/toon';
+import { identity, configPath, profiles, validateEnvironment } from './credentials.js';
+import { Failure } from './errors.js';
+import { readCluster } from './runner.js';
+import { parse, commandHelp, clientOnly } from './grammar.js';
+import { guidance } from './metadata-pin.js';
+import { Redactor } from './redaction.js';
+import { preview } from './mutations.js';
+const help = {
+    description: guidance,
+    commands: ['version', 'get <resource> [name]', 'api-versions', 'api-resources', 'logs <pod>', 'top node', 'top pod', 'describe <resource> <name>', 'explain <resource>', 'auth status', 'profile list', 'config path', 'doctor', 'prepare -- <mutation>', 'preview <request-key>', 'confirm <request-key> --digest <digest>', 'server-dry-run -- <mutation>', 'native -- <arguments>'],
+    flags: ['--config <absolute-path>', '--profile <name>', '--namespace <name>', '--native-config <absolute-path|ambient>', '--trust-exec', '--credential-fd <inherited-private-pipe> (confirm only)', '--help'],
+    examples: ['kubernetes-axi version --profile <name>', 'kubernetes-axi get pods --profile <name> --namespace <namespace>'],
+};
+export async function main(args) {
+    const redactor = new Redactor();
+    let native = false;
+    let json = false;
+    const output = (value) => {
+        if ('native' in value && value.native === true) {
+            const result = value;
+            process.stdout.write(redactor.text(result.stdout));
+            process.stderr.write(redactor.text(result.stderr));
+            process.exitCode = result.exitCode;
+        }
+        else
+            process.stdout.write(`${json ? JSON.stringify(redactor.value(value)) : encode(redactor.value(value))}\n`);
+    };
+    try {
+        if (args.length === 1 && args[0] === '--help') {
+            output(help);
+            return;
+        }
+        const invocation = parse(args);
+        validateEnvironment();
+        native = invocation.native;
+        json = invocation.flags.get('output') === 'json';
+        if (invocation.help) {
+            output(commandHelp(invocation.command));
+            return;
+        }
+        if (invocation.workflow?.kind === 'preview') {
+            output(await preview(invocation));
+            return;
+        }
+        if (invocation.command.path === 'config path') {
+            output({ path: configPath(invocation.config) });
+            return;
+        }
+        if (invocation.command.path === 'profile list') {
+            const config = await profiles(invocation.config);
+            output({ profiles: Object.keys(config.profiles).map(name => ({ name, default: name === config.defaultProfile })) });
+            return;
+        }
+        const selected = invocation.nativeConfig || clientOnly(invocation) ? undefined : await identity(invocation.config, invocation.profile, ['auth status', 'doctor'].includes(invocation.command.path));
+        redactor.register(selected?.secret, selected?.profile.clientCertificate);
+        if (selected && ['auth status', 'doctor'].includes(invocation.command.path)) {
+            output({ source: selected.source, origin: selected.profile.origin, auth: selected.profile.auth, secretSource: selected.profile.token ?? selected.profile.privateKey ?? { env: `KUBERNETES_AXI_${selected.profile.auth === 'token' ? 'TOKEN' : 'PRIVATE_KEY'}` }, permissions: 'verified' });
+            return;
+        }
+        output(await readCluster(selected, invocation, redactor));
+    }
+    catch (error) {
+        const failure = error instanceof Failure ? error : new Failure('CONFIG_INVALID', 'Check the selected profile, protected files and installed package.');
+        output({ error: { code: failure.code, message: failure.message, ...failure.details }, ...(native ? { native: false } : {}) });
+        process.exitCode = failure.exitCode;
+    }
+}

package/dist/credentials.d.ts

@@ -0,0 +1,28 @@
+type SecretRef = {
+    env: string;
+} | {
+    file: string;
+};
+export interface Profile {
+    origin: string;
+    auth: 'token' | 'certificate';
+    namespace?: string;
+    certificateAuthority: string;
+    token?: SecretRef;
+    clientCertificate?: string;
+    privateKey?: SecretRef;
+}
+export interface Identity {
+    profile: Profile;
+    source: string;
+    secret: string;
+}
+export declare function profiles(config?: string, diagnostic?: boolean): Promise<{
+    version: 1;
+    defaultProfile?: string;
+    profiles: Record<string, Profile>;
+}>;
+export declare function configPath(explicit?: string): string;
+export declare function validateEnvironment(): void;
+export declare function identity(config?: string, selected?: string, diagnostic?: boolean): Promise<Identity>;
+export {};

package/dist/credentials.js

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { Ajv } from 'ajv';
+import { Failure } from './errors.js';
+import { readPrivate } from './private-files.js';
+const ajv = new Ajv({ strict: true, strictRequired: false });
+ajv.addKeyword('x-secret');
+const schema = JSON.parse(await readFile(new URL('../axi-credential.schema.json', import.meta.url), 'utf8'));
+const validateProfile = ajv.compile(schema);
+const validateConfig = ajv.compile({
+    type: 'object', additionalProperties: false, required: ['version', 'profiles'],
+    properties: {
+        version: { const: 1 },
+        defaultProfile: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' },
+        profiles: {
+            type: 'object', propertyNames: { pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' },
+            additionalProperties: { $ref: 'urn:kubernetes-axi:credential-profile' },
+        },
+    },
+});
+export async function profiles(config, diagnostic = false) {
+    const value = JSON.parse(await readPrivate(configPath(config), false, { diagnostic }));
+    if (!validateConfig(value))
+        throw new Failure('CONFIG_INVALID', 'Use strict profiles; token and privateKey fields require SecretRefs, never inline values.');
+    for (const profile of Object.values(value.profiles))
+        for (const ref of [profile.token, profile.privateKey]) {
+            if (ref && 'file' in ref && (!isAbsolute(ref.file) || (process.platform === 'win32' && !/^[A-Za-z]:\\/.test(ref.file))))
+                throw new Failure('CONFIG_INVALID', 'SecretRef file paths must be absolute local paths.');
+        }
+    return value;
+}
+export function configPath(explicit) {
+    const base = process.platform === 'win32'
+        ? process.env.APPDATA
+        : (process.env.XDG_CONFIG_HOME && isAbsolute(process.env.XDG_CONFIG_HOME) ? process.env.XDG_CONFIG_HOME : join(homedir(), '.config'));
+    if (!base)
+        throw new Failure('CONFIG_INVALID', 'Set APPDATA to an absolute directory.');
+    const path = explicit ?? process.env.KUBERNETES_AXI_CONFIG ?? join(base, 'kubernetes-axi', 'config.json');
+    if (!isAbsolute(path))
+        throw new Failure('CONFIG_INVALID', 'Use an absolute config path.');
+    return path;
+}
+async function resolveSecret(ref, diagnostic) {
+    let value;
+    if ('env' in ref)
+        value = process.env[ref.env];
+    else {
+        if (!isAbsolute(ref.file) || (process.platform === 'win32' && !/^[A-Za-z]:\\/.test(ref.file))) {
+            throw new Failure('CONFIG_INVALID', 'Secret file must use an absolute local path.');
+        }
+        value = (await readPrivate(ref.file, true, { diagnostic })).replace(/^\uFEFF/, '').trimEnd();
+    }
+    if (!value)
+        throw new Failure('AUTH_REQUIRED', 'Supply the selected secret through its environment or protected-file reference.');
+    return value;
+}
+export function validateEnvironment() {
+    const readOnly = process.env.KUBERNETES_AXI_READ_ONLY;
+    if (readOnly !== undefined && !/^(true|false|0|1)$/i.test(readOnly)) {
+        throw new Failure('CONFIG_INVALID', 'KUBERNETES_AXI_READ_ONLY must be true, false, 1 or 0.');
+    }
+}
+export async function identity(config, selected, diagnostic = false) {
+    validateEnvironment();
+    const name = selected ?? process.env.KUBERNETES_AXI_PROFILE;
+    const fields = ['ORIGIN', 'AUTH', 'NAMESPACE', 'CERTIFICATE_AUTHORITY', 'TOKEN', 'CLIENT_CERTIFICATE', 'PRIVATE_KEY'];
+    let profile;
+    let source;
+    if (!name && fields.some(field => process.env[`KUBERNETES_AXI_${field}`] !== undefined)) {
+        const env = process.env;
+        profile = Object.fromEntries([
+            ['origin', env.KUBERNETES_AXI_ORIGIN], ['auth', env.KUBERNETES_AXI_AUTH],
+            ['namespace', env.KUBERNETES_AXI_NAMESPACE], ['certificateAuthority', env.KUBERNETES_AXI_CERTIFICATE_AUTHORITY],
+            ['clientCertificate', env.KUBERNETES_AXI_CLIENT_CERTIFICATE],
+            ['token', env.KUBERNETES_AXI_TOKEN === undefined ? undefined : { env: 'KUBERNETES_AXI_TOKEN' }],
+            ['privateKey', env.KUBERNETES_AXI_PRIVATE_KEY === undefined ? undefined : { env: 'KUBERNETES_AXI_PRIVATE_KEY' }],
+        ].filter(([, value]) => value !== undefined));
+        source = 'environment';
+        if (!(env.KUBERNETES_AXI_AUTH === 'token' ? env.KUBERNETES_AXI_TOKEN : env.KUBERNETES_AXI_PRIVATE_KEY))
+            throw new Failure('CONFIG_INVALID', 'Supply every required environment profile field, including its secret.');
+    }
+    else {
+        let file;
+        try {
+            file = await profiles(config, diagnostic);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new Failure('AUTH_REQUIRED', 'Supply a complete environment profile or select a configured profile.');
+            }
+            throw error;
+        }
+        const names = Object.keys(file.profiles);
+        const chosen = name ?? file.defaultProfile ?? (names.length === 1 ? names[0] : undefined);
+        if (!chosen)
+            throw new Failure(names.length ? 'PROFILE_AMBIGUOUS' : 'PROFILE_REQUIRED', 'Select a profile with --profile <name>.');
+        if (!Object.hasOwn(file.profiles, chosen))
+            throw new Failure('PROFILE_NOT_FOUND', 'Select a profile present in the config file.');
+        profile = file.profiles[chosen];
+        source = `file:${chosen}`;
+    }
+    if (!validateProfile(profile))
+        throw new Failure('CONFIG_INVALID', 'Supply a complete profile; token and privateKey must be valid SecretRefs.');
+    const origin = new URL(profile.origin);
+    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) {
+        throw new Failure('CONFIG_INVALID', 'origin must be an HTTPS origin without credentials, path, query or fragment.');
+    }
+    const secret = await resolveSecret(profile.auth === 'token'
+        ? profile.token ?? { env: 'KUBERNETES_AXI_TOKEN' }
+        : profile.privateKey ?? { env: 'KUBERNETES_AXI_PRIVATE_KEY' }, diagnostic);
+    return { profile, source, secret };
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class Failure extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details: {
+        upstreamStatus?: number;
+        cause?: string;
+    };
+    constructor(code: string, message: string, exitCode?: number, details?: {
+        upstreamStatus?: number;
+        cause?: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class Failure extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = 1, details = {}) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}

package/dist/exec-shim.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/exec-shim.js

@@ -0,0 +1,16 @@
+import { connect } from 'node:net';
+// Only kubectl invokes this shim. Its stdout is the private ExecCredential pipe.
+const socket = connect(process.argv[2]);
+let response = '';
+socket.setEncoding('utf8');
+socket.setTimeout(10_000, () => socket.destroy());
+socket.on('connect', () => socket.end(JSON.stringify({ info: process.env.KUBERNETES_EXEC_INFO })));
+socket.on('data', chunk => { response += chunk; if (response.length > 1024 * 1024)
+    socket.destroy(); });
+socket.on('error', () => { process.exitCode = 1; });
+socket.on('end', () => {
+    if (response)
+        process.stdout.write(response);
+    else
+        process.exitCode = 1;
+});

package/dist/grammar.d.ts

@@ -0,0 +1,50 @@
+export interface Flag {
+    name: string;
+    short: string;
+    type: string;
+    default: string;
+    noOpt: string;
+    usage: string;
+    effect: string;
+}
+export interface Command {
+    path: string;
+    aliases: string[];
+    flags: Flag[];
+    use: string;
+    description: string;
+    effect: string;
+    operations?: string[];
+    compatibilityLimit?: string;
+}
+export declare const metadata: {
+    version: string;
+    commands: Command[];
+};
+export interface Invocation {
+    session?: boolean;
+    inputSha256?: string;
+    workflow?: {
+        kind: 'prepare' | 'server-dry-run';
+    } | {
+        kind: 'preview' | 'confirm';
+        key: string;
+        digest: string;
+    };
+    native: boolean;
+    config?: string;
+    profile?: string;
+    nativeConfig?: string;
+    trustExec: boolean;
+    credentialFd?: number;
+    command: Command;
+    argv: string[];
+    positionals: string[];
+    flags: Map<string, string>;
+    help: boolean;
+    home: boolean;
+}
+export declare function parse(args: string[], session?: boolean): Invocation;
+export declare function requireWrites(): void;
+export declare function clientOnly(invocation: Invocation): boolean;
+export declare function commandHelp(command: Command): object;

package/dist/grammar.js

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { Failure } from './errors.js';
+import { metadataSha256, executionLimit } from './metadata-pin.js';
+import { routeEffect } from './route-policy.js';
+const bytes = await readFile(new URL('../command-metadata.json', import.meta.url));
+export const metadata = JSON.parse(bytes.toString());
+export function parse(args, session = false) {
+    if (createHash('sha256').update(bytes).digest('hex') !== metadataSha256 || metadata.version !== 'v1.32.2') {
+        throw new Failure('METADATA_STALE', 'Rebuild reviewed command metadata for the installed kubectl pin.');
+    }
+    const own = { trustExec: false };
+    const argv = [];
+    let native = session;
+    let workflow;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--credential-fd' || arg.startsWith('--credential-fd=')) {
+            const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : args[++index] ?? '';
+            if (!/^(?:[3-9]|[1-9][0-9]+)$/.test(value) || own.credentialFd !== undefined)
+                throw new Failure('USAGE', 'Supply --credential-fd once with an inherited private pipe descriptor of at least 3.', 2);
+            own.credentialFd = Number(value);
+            continue;
+        }
+        if (argv.length === 0 && ['prepare', 'preview', 'confirm', 'server-dry-run'].includes(arg) && args[index + 1] === '--help' && index + 2 === args.length) {
+            const uses = { prepare: 'prepare -- <Kubernetes mutation>', preview: 'preview <request-key>', confirm: 'confirm <request-key> --digest <preview-digest>', 'server-dry-run': 'server-dry-run -- <Kubernetes mutation>' };
+            return { ...own, native: false, command: { path: arg, aliases: [], flags: [], use: uses[arg], description: 'Prepare frozen targets, preview them offline, confirm their exact digest, or explicitly request server dry run.', effect: arg === 'preview' ? 'localRead' : 'clusterWrite' }, argv: [], positionals: [], flags: new Map(), help: true, home: false };
+        }
+        if (argv.length === 0 && ['prepare', 'server-dry-run'].includes(arg)) {
+            if (args[index + 1] !== '--')
+                throw new Failure('USAGE', `Use ${arg} -- <Kubernetes command and arguments>.`, 2);
+            workflow = { kind: arg };
+            argv.push(...args.slice(index + 2));
+            break;
+        }
+        if (argv.length === 0 && ['preview', 'confirm'].includes(arg)) {
+            const key = args[index + 1] ?? '';
+            const tail = args.slice(index + 2);
+            if (!/^[a-f0-9-]{36}$/.test(key) || (arg === 'preview' ? tail.length !== 0 : tail.length !== 2 || tail[0] !== '--digest' || !/^[a-f0-9]{64}$/.test(tail[1] ?? '')))
+                throw new Failure('USAGE', 'Use preview <request-key> or confirm <request-key> --digest <preview-digest>.', 2);
+            workflow = { kind: arg, key, digest: tail[1] ?? '' };
+            validateSelection(own);
+            return { ...own, native: false, workflow, command: { path: arg, aliases: [], flags: [], use: arg, description: 'Inspect or confirm a frozen request.', effect: arg === 'preview' ? 'localRead' : 'clusterWrite' }, argv: [], positionals: [], flags: new Map(), help: false, home: false };
+        }
+        if (arg === 'native' && argv.length === 0) {
+            if (args[index + 1] !== '--')
+                throw new Failure('USAGE', 'Use kubernetes-axi [--profile <name>] native -- <kubectl arguments>.', 2);
+            native = true;
+            argv.push(...args.slice(index + 2));
+            break;
+        }
+        if (arg === '--') {
+            argv.push(...args.slice(index));
+            break;
+        }
+        const [name, ...valueParts] = arg.split('=');
+        if (arg === '--trust-exec') {
+            own.trustExec = true;
+            continue;
+        }
+        if (name === '--config' || name === '--profile' || name === '--native-config') {
+            const value = valueParts.length ? valueParts.join('=') : args[++index];
+            if (!value || value.startsWith('-'))
+                throw new Failure('USAGE', `${name} requires a value.`, 2);
+            const key = name === '--config' ? 'config' : name === '--profile' ? 'profile' : 'nativeConfig';
+            if (own[key] !== undefined)
+                throw new Failure('USAGE', `Supply ${name} once.`, 2);
+            own[key] = value;
+        }
+        else
+            argv.push(arg);
+    }
+    if (own.credentialFd !== undefined)
+        throw new Failure('USAGE', '--credential-fd is only available before confirm.', 2);
+    const localCommand = argv.filter(arg => !['--help', '-h'].includes(arg)).join(' ');
+    if (['auth status', 'profile list', 'config path', 'doctor'].includes(localCommand)) {
+        if (own.nativeConfig || own.trustExec)
+            throw new Failure('USAGE', 'Use native -- for native configuration diagnostics.', 2);
+        return { native: false, ...own, command: { path: localCommand, aliases: [], flags: ['config', 'profile', 'help'].map(name => ({ name, short: '', type: name === 'help' ? 'bool' : 'string', default: '', noOpt: name === 'help' ? 'true' : '', usage: '', effect: 'argument' })), use: localCommand, description: 'Inspect standard credential configuration without a cluster request.', effect: 'localRead' }, argv, positionals: [], flags: new Map(), help: argv.some(arg => ['--help', '-h'].includes(arg)), home: false };
+    }
+    // Resolve the longest command path while respecting values of inherited flags.
+    let command = metadata.commands.find(item => item.path === '');
+    const positionals = [];
+    const flags = new Map();
+    const tokens = [...argv];
+    let ended = false;
+    for (let index = 0; index < tokens.length; index++) {
+        const arg = tokens[index];
+        if (arg === '--') {
+            ended = true;
+            continue;
+        }
+        if (ended || !arg.startsWith('-') || arg === '-') {
+            const child = !ended && positionals.length === 0 ? metadata.commands.find(item => {
+                const words = item.path.split(' ');
+                const parent = words.slice(0, -1).join(' ');
+                return item.path !== '' && parent === command.path && (words.at(-1) === arg || item.aliases.includes(arg));
+            }) : undefined;
+            if (child)
+                command = child;
+            else
+                positionals.push(arg);
+            continue;
+        }
+        const long = arg.startsWith('--');
+        const name = long ? arg.slice(2).split('=')[0] : arg.slice(1, 2);
+        // Command flags may precede their command, as Cobra permits inherited options.
+        const flag = command.flags.find(flag => long ? flag.name === name : flag.short === name);
+        if (!flag) {
+            throw new Failure('USAGE', `Unknown flag for ${command.path || 'home'}. Valid flags: ${command.flags.map(flag => `--${flag.name}`).join(', ')}.`, 2);
+        }
+        let value = long ? (arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : undefined) : arg.slice(2).replace(/^=/, '') || undefined;
+        if (!long && flag.type === 'bool' && arg.length > 2 && arg[2] !== '=') {
+            tokens.splice(index + 1, 0, `-${arg.slice(2)}`);
+            value = flag.noOpt;
+        }
+        if (value === undefined)
+            value = flag.noOpt || tokens[++index];
+        if (value === undefined || (!flag.noOpt && value.startsWith('--')))
+            throw new Failure('USAGE', `--${flag.name} requires a ${flag.type} value.`, 2);
+        if (flag.type === 'bool' && !/^(true|false|1|0|t|f|TRUE|FALSE|True|False|T|F)$/.test(value))
+            throw new Failure('USAGE', `--${flag.name} requires a boolean.`, 2);
+        if (/^u?int(32|64)?$/.test(flag.type) && !/^-?\d+$/.test(value))
+            throw new Failure('USAGE', `--${flag.name} requires an integer.`, 2);
+        if (session && (flag.effect === 'fileRead' || flag.name === 'kustomize')) {
+            const workspace = join(process.env.TMPDIR ?? '', 'workspace');
+            for (const path of value.split(',')) {
+                const selected = relative(workspace, resolve(path));
+                if (path !== '-' && (!process.env.TMPDIR || selected.startsWith('..') || isAbsolute(selected)))
+                    throw new Failure('WORKSPACE_REQUIRED', 'Session file inputs must come from the owned workspace.');
+            }
+        }
+        flags.set(flag.name, flag.type === 'bool' ? (/^(true|1|t)$/i.test(value) ? 'true' : 'false') : value);
+    }
+    const help = flags.get('help') === 'true' || command.path === 'help';
+    if (command.path === '' && positionals.length)
+        throw new Failure('USAGE', 'Unknown command. Run kubernetes-axi --help.', 2);
+    if (!command.effect)
+        throw new Failure('EFFECT_UNCLASSIFIED', 'The command has no reviewed effect classification.');
+    if (!help) {
+        if (['exec', 'attach', 'debug'].includes(command.path) && (flags.get('tty') === 'true' || !session && flags.get('stdin') === 'true') || command.path === 'debug' && flags.get('attach') !== 'false' || !session && command.path === 'port-forward')
+            throw new Failure('LOCAL_TERMINAL_REQUIRED', executionLimit);
+        const guarded = ['exec', 'attach', 'create token', ...(session ? ['port-forward'] : [])].includes(command.path);
+        if (flags.has('raw')) {
+            const effect = routeEffect(command.path === 'get' ? 'GET' : command.path === 'delete' ? 'DELETE' : command.path === 'replace' ? 'PUT' : 'POST', flags.get('raw'));
+            if (effect !== 'read')
+                requireWrites();
+            if (!['read', 'clusterWrite'].includes(effect))
+                throw new Failure('CAPABILITY_UNAVAILABLE', `Raw ${effect} routes require the corresponding explicit guarded command.`);
+            if (/\/secrets(?:\/|\?|$)/.test(flags.get('raw')))
+                throw new Failure('CREDENTIAL_OUTPUT_REFUSED', 'Use compact get secrets for metadata.');
+        }
+        if (guarded) {
+            requireWrites();
+            if (!workflow || workflow.kind !== 'prepare')
+                throw new Failure('PREVIEW_REQUIRED', 'Use prepare -- <command>, preview <request-key>, then confirm <request-key> --digest <digest>.');
+            if (command.path === 'create token' && !/^(true|1)$/i.test(process.env.KUBERNETES_AXI_ACQUIRE_CREDENTIAL ?? ''))
+                throw new Failure('CAPABILITY_UNAVAILABLE', 'Token issuance requires KUBERNETES_AXI_ACQUIRE_CREDENTIAL=true and a private delivery pipe on confirmation.');
+        }
+        if (native && ['get', 'describe'].includes(command.path) && positionals.some((value, index) => (index === 0 || value.includes('/')) && value.split(',').some(resource => /^secrets?(?:$|[/.])/i.test(resource))))
+            throw new Failure('CREDENTIAL_OUTPUT_REFUSED', 'Use compact get secrets for metadata; public native Secret output is unavailable.');
+        if (own.nativeConfig && ['config set', 'config set-credentials', 'config view'].includes(command.path))
+            throw new Failure('USAGE', 'Raw native credential inspection and credential argv writes are unavailable.', 2);
+        if (command.compatibilityLimit)
+            throw new Failure('NOT_YET_SUPPORTED_STAGED', command.compatibilityLimit);
+        for (const flag of command.flags) {
+            if (!session && flag.effect === 'stream' && (flags.get(flag.name) ?? flag.default) !== 'false')
+                throw new Failure('USAGE', `--${flag.name} must be false in standalone mode. ${executionLimit}`, 2);
+        }
+        for (const name of flags.keys()) {
+            const flag = command.flags.find(flag => flag.name === name);
+            if (!flag.effect)
+                throw new Failure('EFFECT_UNCLASSIFIED', 'The flag has no reviewed effect classification.');
+            if (flag.effect === 'stream')
+                continue;
+            const writeInput = workflow && ['prepare', 'server-dry-run'].includes(workflow.kind) && (flag.effect === 'fileRead' && ['filename', 'patch-file'].includes(flag.name) || session && flag.name === 'kustomize' || flag.effect === 'clusterWrite' && (['dry-run', 'server-side', 'force-conflicts', 'force', 'prune', 'prune-allowlist'].includes(flag.name) || command.path === 'debug' && flag.name === 'profile'));
+            const boundedExecution = (guarded || command.path === 'debug') && ['stdin', 'tty', 'attach'].includes(name) && (flags.get(name) === 'false' || session && name === 'stdin');
+            const raw = name === 'raw' && (command.path === 'get' || Boolean(workflow) && command.effect === 'clusterWrite');
+            if (!(own.nativeConfig && flag.name === 'context') && !raw && !writeInput && !boundedExecution && !['argument', 'presentation'].includes(flag.effect))
+                throw new Failure('USAGE', `--${flag.name} is unavailable under the isolated bounded-read policy (${flag.effect}).`, 2);
+            if (flag.name === 'output' && /file[=\s]|template-file/.test(flags.get(flag.name)))
+                throw new Failure('USAGE', 'File templates require a later local-file capability.', 2);
+        }
+        if (command.effect === 'clusterWrite') {
+            requireWrites();
+            if (!workflow)
+                throw new Failure('PREVIEW_REQUIRED', 'Use prepare -- <command>, preview <request-key>, then confirm <request-key> --digest <digest>.');
+            if (flags.has('dry-run'))
+                throw new Failure('USAGE', 'Use server-dry-run -- <command> for server validation, or prepare -- <command> for a frozen request.', 2);
+        }
+        else if (workflow && !guarded)
+            throw new Failure('USAGE', 'Preparation and server dry run require a resource mutation command.', 2);
+        if (!(own.nativeConfig && native && command.path.startsWith('config ')) && !(native && command.path === 'plugin list') && !guarded && !['read', 'local', 'clusterWrite', 'authorization'].includes(command.effect))
+            throw new Failure('CAPABILITY_UNAVAILABLE', `The ${command.effect} capability is not available in this milestone.`);
+        if (['wait', 'events'].includes(command.path))
+            throw new Failure('CAPABILITY_UNAVAILABLE', 'Bounded event reads use get events; wait and streaming sessions require a later capability.');
+        if (!native) {
+            const allowed = {
+                '': ['namespace'], version: [], get: ['namespace', 'all-namespaces', 'selector', 'field-selector', 'output'],
+                'api-versions': [], 'api-resources': [],
+                'top node': ['namespace', 'selector'], 'top pod': ['namespace', 'all-namespaces', 'selector'],
+            };
+            if (Object.hasOwn(allowed, command.path)) {
+                for (const name of flags.keys())
+                    if (!allowed[command.path].includes(name))
+                        throw new Failure('USAGE', `--${name} requires native -- ${command.path} for upstream semantics.`, 2);
+            }
+            else if (!guarded && !['logs', 'describe', 'explain', 'rollout history', 'rollout status'].includes(command.path) && !['clusterWrite', 'authorization'].includes(command.effect))
+                throw new Failure('CAPABILITY_UNAVAILABLE', 'Use native -- for this upstream read.');
+            const maxArgs = command.path === 'get' ? 2 : command.path.startsWith('top ') ? 1 : command.path === '' || command.path === 'version' || command.path.startsWith('api-') ? 0 : undefined;
+            if (maxArgs !== undefined && (positionals.length > maxArgs || (command.path === 'get' && positionals.length === 0)))
+                throw new Failure('USAGE', 'Supply one resource type and at most one resource name.', 2);
+            if (command.path === 'get' && flags.has('output') && flags.get('output') !== 'json')
+                throw new Failure('USAGE', 'Compact reads support -o json; use native -- for other output formats.', 2);
+        }
+    }
+    validateSelection(own);
+    return { native, ...own, ...(session ? { session } : {}), ...(workflow ? { workflow } : {}), command, argv, positionals, flags, help, home: command.path === '' && positionals.length === 0 };
+}
+function validateSelection(own) {
+    if (own.trustExec && !own.nativeConfig)
+        throw new Failure('USAGE', '--trust-exec requires --native-config.', 2);
+    if (own.nativeConfig && own.nativeConfig !== 'ambient' && !isAbsolute(own.nativeConfig))
+        throw new Failure('CONFIG_INVALID', 'Select an absolute native kubeconfig path or ambient.');
+    if (own.nativeConfig && (own.config || own.profile || ['CONFIG', 'PROFILE', 'ORIGIN', 'AUTH', 'NAMESPACE', 'CERTIFICATE_AUTHORITY', 'TOKEN', 'CLIENT_CERTIFICATE', 'PRIVATE_KEY'].some(field => process.env[`KUBERNETES_AXI_${field}`] !== undefined)))
+        throw new Failure('CONFIG_INVALID', 'Native selection cannot override a standard or hosted profile.');
+}
+export function requireWrites() {
+    if (!/^(false|0)$/i.test(process.env.KUBERNETES_AXI_READ_ONLY ?? ''))
+        throw new Failure('READ_ONLY', 'Writes require KUBERNETES_AXI_READ_ONLY=false and explicit confirmation.');
+}
+export function clientOnly(invocation) {
+    return invocation.native && (['completion', 'options', 'plugin list'].includes(invocation.command.path) || invocation.command.path === 'version' && invocation.flags.get('client') === 'true');
+}
+export function commandHelp(command) {
+    return {
+        command: command.path || 'kubernetes-axi', description: command.description,
+        usage: command.use, effect: command.effect,
+        ...(['exec', 'attach', 'debug', 'get', 'logs', 'port-forward'].includes(command.path) ? { capabilityBoundary: executionLimit } : {}),
+        ...(command.operations ? { operations: command.operations } : {}),
+        ...(command.compatibilityLimit ? { compatibilityLimit: command.compatibilityLimit } : {}),
+        flags: command.flags.map(flag => ({ name: `--${flag.name}`, short: flag.short ? `-${flag.short}` : '', type: flag.type, default: flag.default })),
+        examples: ['prepare', 'preview', 'confirm', 'server-dry-run'].includes(command.path) ?
+            ['kubernetes-axi --profile <name> prepare -- patch deployment <name> --type=merge -p \'{"spec":{"replicas":3}}\'', 'kubernetes-axi --profile <name> preview <request-key>', 'kubernetes-axi --profile <name> confirm <request-key> --digest <preview-digest>'] :
+            ['kubernetes-axi --profile <name> get pods -n <namespace>', 'kubernetes-axi --profile <name> native -- get pods -n <namespace> -o json'],
+    };
+}

package/dist/hosted-session.d.ts

@@ -0,0 +1 @@
+export {};