@knowttl/kubernetes-axi 0.0.0-stage → 0.1.0

package/dist/runner.js

@@ -0,0 +1,367 @@
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, rm, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { Ajv } from 'ajv';
+import { Failure } from './errors.js';
+import { privateDirectory, writePrivate } from './private-files.js';
+import { readPrivate } from './private-files.js';
+import { nativeConfig, inspectNative } from './native.js';
+import { mutationSession } from './mutations.js';
+import { byteProcess } from './byte-process.js';
+import { clientOnly } from './grammar.js';
+const execute = promisify(execFile);
+const pins = JSON.parse(await readFile(new URL('../kubectl-pins.json', import.meta.url), 'utf8'));
+const ajv = new Ajv();
+const validVersion = ajv.compile({
+    type: 'object', required: ['major', 'minor', 'gitVersion'],
+    properties: { major: { const: '1' }, minor: { type: 'string', pattern: '^[0-9]+\\+?$' }, gitVersion: { type: 'string' } },
+});
+function compatibleVersion(value) {
+    if (!validVersion(value))
+        throw new Failure('UPSTREAM_INVALID', 'The server version response is invalid.');
+    if (!pins.supportedServerMinors.includes(Number.parseInt(value.minor, 10)))
+        throw new Failure('BINARY_INCOMPATIBLE', 'Server version is outside the recorded kubectl skew matrix.');
+}
+const validObject = ajv.compile({
+    type: 'object', required: ['metadata'], properties: {
+        apiVersion: { type: 'string' }, kind: { type: 'string' },
+        metadata: { type: 'object', required: ['name'], properties: { name: { type: 'string', minLength: 1 }, namespace: { type: 'string' } } },
+        status: { type: 'object', properties: {
+                phase: { type: 'string' }, availableReplicas: { type: 'integer' },
+                conditions: { type: 'array', items: { type: 'object', required: ['type', 'status'], properties: { type: { type: 'string' }, status: { type: 'string' } } } },
+            } },
+        spec: { type: 'object', properties: { replicas: { type: 'integer' } } },
+        usage: { type: 'object', required: ['cpu', 'memory'], properties: { cpu: { type: 'string' }, memory: { type: 'string' } } },
+        containers: { type: 'array', items: { type: 'object', required: ['name', 'usage'], properties: {
+                    name: { type: 'string' }, usage: { type: 'object', required: ['cpu', 'memory'], properties: { cpu: { type: 'string' }, memory: { type: 'string' } } },
+                } } },
+    },
+});
+const validPage = ajv.compile({
+    type: 'object', required: ['apiVersion', 'kind', 'metadata', 'items'], properties: {
+        apiVersion: { type: 'string' }, kind: { type: 'string' }, items: { type: 'array' },
+        metadata: { type: 'object', properties: { continue: { type: 'string' }, resourceVersion: { type: 'string' }, remainingItemCount: { type: 'integer', minimum: 0 } } },
+    },
+});
+const validDiscovery = ajv.compile({
+    type: 'object', required: ['groupVersion', 'resources'], properties: {
+        groupVersion: { type: 'string' }, resources: { type: 'array', items: {
+                type: 'object', required: ['name', 'singularName', 'namespaced', 'kind', 'verbs'], properties: {
+                    name: { type: 'string', pattern: '^[a-z0-9][a-z0-9./-]*$' }, singularName: { type: 'string' }, kind: { type: 'string', minLength: 1 }, namespaced: { type: 'boolean' },
+                    verbs: { type: 'array', items: { type: 'string' } }, shortNames: { type: 'array', items: { type: 'string' } },
+                },
+            } },
+    },
+});
+const validCore = ajv.compile({
+    type: 'object', required: ['versions'], properties: { versions: { type: 'array', minItems: 1, items: { type: 'string', pattern: '^v[0-9]+((alpha|beta)[0-9]+)?$' } } },
+});
+const groupVersionSchema = { type: 'object', required: ['groupVersion'], properties: { groupVersion: { type: 'string', pattern: '^[a-z0-9][a-z0-9.-]*/v[0-9]+((alpha|beta)[0-9]+)?$' } } };
+const validGroups = ajv.compile({
+    type: 'object', required: ['groups'], properties: { groups: { type: 'array', items: {
+                type: 'object', required: ['name', 'versions', 'preferredVersion'], properties: {
+                    name: { type: 'string', pattern: '^[a-z0-9][a-z0-9.-]*$' },
+                    versions: { type: 'array', minItems: 1, items: groupVersionSchema },
+                    preferredVersion: groupVersionSchema,
+                },
+            } } },
+});
+export async function readCluster(identity, invocation, redactor, byteExecution) {
+    const pin = pins.binaries[`${process.platform}-${process.arch}`];
+    if (!pin)
+        throw new Failure('BINARY_UNSUPPORTED', 'Use a recorded Linux or Windows amd64 runtime.');
+    const binary = await realpath(fileURLToPath(new URL(`../vendor/${pin.file}`, import.meta.url)));
+    const digest = createHash('sha256').update(await readFile(binary)).digest('hex');
+    if (digest !== pin.sha256)
+        throw new Failure('BINARY_INTEGRITY', 'Restore the recorded managed kubectl binary; PATH fallback is disabled.');
+    const flags = invocation.flags;
+    let namespace = flags.get('namespace') ?? identity?.profile.namespace ?? 'default';
+    const all = flags.get('all-namespaces') === 'true';
+    if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(namespace) || namespace.length > 63)
+        throw new Failure('USAGE', 'Use a valid Kubernetes namespace.', 2);
+    const directory = join(tmpdir(), `kubernetes-axi-${randomUUID()}`);
+    await privateDirectory(directory);
+    const profile = identity?.profile;
+    const secret = identity?.secret;
+    const user = profile?.auth === 'token' ? { token: secret } : {
+        'client-certificate-data': Buffer.from(profile?.clientCertificate ?? '').toString('base64'), 'client-key-data': Buffer.from(secret ?? '').toString('base64'),
+    };
+    const config = join(directory, 'config.json');
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort('SIGINT');
+    const terminate = () => cancellation.abort('SIGTERM');
+    const hangup = () => cancellation.abort('SIGHUP');
+    byteExecution?.signal.addEventListener('abort', cancel, { once: true });
+    process.once('SIGTERM', terminate);
+    process.once('SIGINT', cancel);
+    process.once('SIGHUP', hangup);
+    const deadline = Date.now() + 15_000;
+    let requests = 0;
+    let retainedBytes = 0;
+    const env = {
+        HOME: directory, USERPROFILE: directory, XDG_CONFIG_HOME: directory, XDG_CACHE_HOME: directory,
+        TMPDIR: directory, TEMP: directory, TMP: directory,
+        ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot, WINDIR: process.env.WINDIR } : {}),
+    };
+    const invoke = async (args, format = 'json') => {
+        if (format === 'native' && byteExecution) {
+            const exitCode = await byteProcess(binary, ['--kubeconfig', config, '--cache-dir', directory, '--request-timeout=0', ...args], env, byteExecution, redactor);
+            return { native: true, stdout: '', stderr: '', exitCode };
+        }
+        if (++requests > 64 || Date.now() >= deadline)
+            throw new Failure('UPSTREAM_TIMEOUT', 'The bounded operation exhausted its request or time budget.');
+        let result;
+        try {
+            result = await execute(binary, ['--kubeconfig', config, '--cache-dir', directory, '--request-timeout=5s', ...args], { env, signal: cancellation.signal, timeout: Math.min(10_000, deadline - Date.now()), maxBuffer: 4 * 1024 * 1024, windowsHide: true });
+        }
+        catch (error) {
+            const failed = error;
+            if (failed.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
+                throw new Failure('OUTPUT_LIMIT', 'Output exceeded 4 MiB; narrow the selection.', 1, { cause: 'byte_limit' });
+            if (failed.killed)
+                throw new Failure('UPSTREAM_TIMEOUT', 'The bounded request timed out.', 1, { cause: 'timeout' });
+            if (format === 'native' && typeof failed.code === 'number')
+                return { native: true, stdout: failed.stdout ?? '', stderr: failed.stderr ?? '', exitCode: failed.code };
+            const stderr = failed.stderr ?? '';
+            const reason = /^Error from server \(([^)]+)\):/m.exec(stderr)?.[1]
+                ?? (/^error: You must be logged in to the server \(/m.test(stderr) ? 'Unauthorized' : undefined);
+            const errors = [
+                [['Unauthorized'], 'AUTH_REQUIRED', 401, 'The selected identity was rejected.'],
+                [['Forbidden'], 'ACCESS_DENIED', 403, 'The selected identity cannot perform this read.'],
+                [['Expired', 'Gone'], 'RESOURCE_EXPIRED', 410, 'The continuation expired; start a new read.'],
+                [['Timeout', 'ServerTimeout'], 'UPSTREAM_TIMEOUT', 504, 'The bounded request timed out.'],
+                [['NotFound'], args.includes('explain') ? 'SCHEMA_UNAVAILABLE' : args.some(arg => arg.startsWith('--raw=/apis/metrics.k8s.io/')) ? 'API_UNAVAILABLE' : 'RESOURCE_NOT_FOUND', 404, 'The selected resource or API was not found.'],
+            ];
+            for (const [reasons, code, upstreamStatus, message] of errors)
+                if (reason && reasons.includes(reason))
+                    throw new Failure(code, message, 1, { upstreamStatus, cause: code });
+            if (!reason) {
+                if (/^(?:error: )?(?:Unable to connect to the server: |net\/http: |context )[^\n]*(?:deadline exceeded|timed out|Timeout)/m.test(stderr))
+                    throw new Failure('UPSTREAM_TIMEOUT', 'The bounded request timed out.', 1, { cause: 'timeout' });
+                if (args.includes('explain') && /^error: (?:failed to (?:download|fetch) openapi|error loading schema)/mi.test(stderr)) {
+                    // Explain loses HTTP failure reasons; a raw read retains the server's status.
+                    const schema = /^error: failed to fetch openapi schema for ((?:api|apis\/[a-z0-9][a-z0-9.-]*)\/v[0-9]+(?:(?:alpha|beta)[0-9]+)?):/m.exec(stderr)?.[1];
+                    if (schema) {
+                        try {
+                            await invoke(['get', `--raw=/openapi/v3/${schema}`]);
+                        }
+                        catch (error) {
+                            if (!(error instanceof Failure) || !['RESOURCE_NOT_FOUND', 'UPSTREAM_INVALID'].includes(error.code))
+                                throw error;
+                        }
+                    }
+                    throw new Failure('SCHEMA_UNAVAILABLE', 'The selected resource schema is unavailable or invalid.', 1, { cause: 'schema' });
+                }
+                if (/^error: (?:invalid character|unexpected end|[^\n]*cannot unmarshal|invalid JSON)/mi.test(stderr))
+                    throw new Failure('UPSTREAM_INVALID', 'The API returned a malformed response.', 1, { cause: 'malformed' });
+            }
+            throw new Failure('UPSTREAM_FAILED', 'The bounded Kubernetes read failed; check endpoint, TLS trust and identity.', 1, { cause: 'transport' });
+        }
+        retainedBytes += Buffer.byteLength(result.stdout) + Buffer.byteLength(result.stderr);
+        if (retainedBytes > 4 * 1024 * 1024)
+            throw new Failure('OUTPUT_LIMIT', 'The operation exceeded its 4 MiB retained-output budget.');
+        if (format === 'native')
+            return { native: true, stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
+        if (format === 'text')
+            return result.stdout;
+        try {
+            return JSON.parse(result.stdout);
+        }
+        catch {
+            throw new Failure('UPSTREAM_INVALID', 'The API returned malformed JSON.', 1, { cause: 'malformed' });
+        }
+    };
+    const raw = (path) => invoke(['get', `--raw=${path}`]);
+    let close = async () => { };
+    let source = identity?.source ?? '';
+    let binding = JSON.stringify(identity);
+    try {
+        if (clientOnly(invocation)) {
+            if (invocation.command.path === 'plugin list')
+                env.PATH = process.env.PATH;
+            return await invoke(invocation.argv, 'native');
+        }
+        if (invocation.nativeConfig && invocation.native && invocation.command.path.startsWith('config ')) {
+            if (invocation.nativeConfig === 'ambient')
+                throw new Failure('CONFIG_INVALID', 'Native config operations require one explicitly selected source file.');
+            if (invocation.command.effect === 'localWrite' && /^(true|1)$/i.test(process.env.KUBERNETES_AXI_READ_ONLY ?? ''))
+                throw new Failure('READ_ONLY', 'Native config writes are disabled by read-only policy.');
+            await writePrivate(config, await readPrivate(invocation.nativeConfig, false));
+            await inspectNative(binary, config, redactor, cancellation.signal);
+            const result = await invoke(invocation.argv, 'native');
+            if (result.exitCode === 0 && invocation.command.effect === 'localWrite')
+                await writePrivate(invocation.nativeConfig, await readPrivate(config, true));
+            return result;
+        }
+        if (invocation.nativeConfig) {
+            const loaded = await nativeConfig(binary, invocation.nativeConfig, flags.get('context'), directory, invocation.trustExec, redactor, cancellation.signal, Boolean(invocation.workflow) || invocation.command.effect === 'clusterWrite');
+            close = loaded.close;
+            namespace = flags.get('namespace') ?? loaded.namespace;
+            source = loaded.source;
+            binding = loaded.binding;
+            await writePrivate(config, JSON.stringify(loaded.config));
+        }
+        else
+            await writePrivate(config, JSON.stringify({
+                apiVersion: 'v1', kind: 'Config',
+                clusters: [{ name: 'selected', cluster: { server: profile.origin, 'certificate-authority-data': Buffer.from(profile.certificateAuthority).toString('base64') } }],
+                users: [{ name: 'selected', user }], contexts: [{ name: 'selected', context: { cluster: 'selected', user: 'selected', namespace } }], 'current-context': 'selected',
+            }));
+        if (invocation.workflow || invocation.command.effect === 'authorization') {
+            const session = await mutationSession(config, invocation, namespace, redactor, cancellation.signal, compatibleVersion, binding);
+            const closeIdentity = close;
+            close = async () => { await session.close(); await closeIdentity(); };
+            if (invocation.workflow?.kind === 'confirm' && !session.argv || session.prepared)
+                return await session.finish();
+            await writePrivate(config, JSON.stringify(session.config));
+            const args = [...(session.argv ?? invocation.argv)];
+            if (session.rawPath) {
+                // RequestURI replaces the configured prefix, so the raw URI must carry it.
+                for (let index = 0; index < args.length; index++) {
+                    if (args[index] === '--raw')
+                        args[++index] = session.rawPath;
+                    else if (args[index].startsWith('--raw='))
+                        args[index] = `--raw=${session.rawPath}`;
+                }
+            }
+            if (invocation.workflow && !session.argv) {
+                if (!invocation.flags.has('raw') && invocation.command.flags.some(flag => flag.name === 'dry-run'))
+                    args.push('--dry-run=server');
+                if (invocation.command.flags.some(flag => flag.name === 'wait'))
+                    args.push('--wait=false');
+            }
+            const result = await invoke(args, 'native');
+            if (session.argv) {
+                await session.finish(result.exitCode === 0);
+                return result;
+            }
+            if (invocation.command.effect === 'authorization') {
+                const review = await session.finish(result.exitCode === 0);
+                process.exitCode = result.exitCode;
+                return invocation.native ? result : review;
+            }
+            if (result.exitCode !== 0) {
+                // Expose a guarded refusal before falling back to the native failure.
+                await session.finish(false);
+                if (invocation.native)
+                    return result;
+                throw new Failure('UPSTREAM_FAILED', 'The operation could not be prepared or validated; check its resource, permissions and arguments.');
+            }
+            const finished = await session.finish();
+            return finished;
+        }
+        const client = await invoke(['version', '--client=true', '-o', 'json']);
+        if (client.clientVersion?.gitVersion !== pins.version)
+            throw new Failure('BINARY_VERSION', 'Restore the recorded managed kubectl version.');
+        const version = await raw('/version');
+        compatibleVersion(version);
+        const provenance = { source, kubectlVersion: pins.version, kubectlSha256: digest };
+        if (invocation.native)
+            return await invoke(invocation.argv, 'native');
+        const command = invocation.command.path;
+        if (command === 'version')
+            return { ...provenance, gitVersion: version.gitVersion };
+        if (command === 'logs') {
+            const logs = await invoke([...invocation.argv, ...(flags.has('tail') ? [] : ['--tail=100']), ...(flags.has('limit-bytes') ? [] : ['--limit-bytes=65536'])], 'text');
+            return { ...provenance, logs, complete: false, truncated: Buffer.byteLength(logs) >= Number(flags.get('limit-bytes') ?? 65536), bound: 'tail and byte limits; snapshot only' };
+        }
+        if (['describe', 'explain', 'rollout history', 'rollout status'].includes(command))
+            return { ...provenance, text: await invoke(invocation.argv, 'text'), complete: false, bound: 'execution and byte limits' };
+        const core = await raw('/api');
+        const groups = await raw('/apis');
+        if (!validCore(core) || !validGroups(groups) || groups.groups.some(group => !group.versions.some(version => version.groupVersion === group.preferredVersion.groupVersion) || group.versions.some(version => !version.groupVersion.startsWith(`${group.name}/`))))
+            throw new Failure('UPSTREAM_INVALID', 'API discovery returned an invalid envelope.');
+        if (command === 'api-versions')
+            return { ...provenance, versions: core.versions, groups: groups.groups.map(group => ({ name: group.name, versions: group.versions.map(version => version.groupVersion), preferredVersion: group.preferredVersion.groupVersion })) };
+        const candidates = [...core.versions.map(version => ({ version, prefix: `/api/${version}` })), ...groups.groups.flatMap(group => [group.preferredVersion, ...group.versions.filter(version => version.groupVersion !== group.preferredVersion.groupVersion)].map(({ groupVersion }) => ({ version: groupVersion, prefix: `/apis/${groupVersion}` })))];
+        const resources = [];
+        const requested = invocation.home ? 'pods' : command.startsWith('top ') ? (command === 'top node' ? 'nodes' : 'pods') : invocation.positionals[0];
+        for (const candidate of candidates) {
+            if (command.startsWith('top ') && !candidate.version.startsWith('metrics.k8s.io/'))
+                continue;
+            const listing = await raw(candidate.prefix);
+            if (!validDiscovery(listing) || listing.groupVersion !== candidate.version)
+                throw new Failure('UPSTREAM_INVALID', 'Resource discovery returned an invalid envelope.');
+            for (const resource of listing.resources)
+                if (!resource.name.includes('/'))
+                    resources.push({ ...resource, prefix: candidate.prefix, apiVersion: candidate.version });
+            if (command !== 'api-resources' && resources.some(resource => matches(resource, requested)))
+                break;
+        }
+        if (command === 'api-resources')
+            return { ...provenance, resources: resources.map(resource => ({ name: resource.name, aliases: resource.shortNames ?? [], namespaced: resource.namespaced, kind: resource.kind, verbs: resource.verbs, apiVersion: resource.apiVersion })), complete: true };
+        const resource = resources.find(resource => matches(resource, requested));
+        if (!resource)
+            throw new Failure('API_UNAVAILABLE', 'Discovery does not advertise the requested resource.');
+        const name = command.startsWith('top ') ? invocation.positionals[0] : invocation.positionals[1];
+        if (name && !/^[a-z0-9][a-z0-9.-]*$/.test(name))
+            throw new Failure('USAGE', 'Supply one Kubernetes resource name.', 2);
+        const route = `${resource.prefix}${resource.namespaced && !all ? `/namespaces/${namespace}` : ''}/${resource.name}${name ? `/${name}` : ''}`;
+        const query = new URLSearchParams();
+        if (!name && !command.startsWith('top '))
+            query.set('limit', '100');
+        for (const [flag, parameter] of [['selector', 'labelSelector'], ['field-selector', 'fieldSelector']])
+            if (flags.has(flag))
+                query.set(parameter, flags.get(flag));
+        const body = await raw(`${route}${query.size ? `?${query}` : ''}`);
+        let items;
+        let page = {};
+        if (name) {
+            if (!validObject(body) || body.kind !== resource.kind || body.apiVersion !== resource.apiVersion || body.metadata.name !== name)
+                throw new Failure('UPSTREAM_INVALID', 'The named response does not match the selected resource.');
+            items = [body];
+        }
+        else {
+            if (!validPage(body) || body.kind !== `${resource.kind}List` || body.apiVersion !== resource.apiVersion || !body.items.every(item => validObject(item)))
+                throw new Failure('UPSTREAM_INVALID', 'The resource list does not match the discovered schema.');
+            items = body.items;
+            page = body.metadata;
+        }
+        if (resource.namespaced && items.some(item => !item.metadata.namespace || (!all && item.metadata.namespace !== namespace)))
+            throw new Failure('UPSTREAM_INVALID', 'The response does not match the selected namespace.');
+        const rows = items.slice(0, 100).map(item => compact(item, resource.kind));
+        const state = { complete: !page.continue && !page.remainingItemCount && items.length <= 100, truncated: items.length > 100, continue: page.continue ?? '', resourceVersion: page.resourceVersion ?? '', ...(page.remainingItemCount === undefined ? {} : { remainingItemCount: page.remainingItemCount }) };
+        if (invocation.home)
+            return { ...provenance, bin: process.argv[1], description: 'Read Kubernetes with isolated credentials and pinned kubectl.', context: 'selected', namespace, pods: rows, ...state };
+        return { ...provenance, [command.startsWith('top ') ? 'metrics' : resource.name]: rows, ...state };
+    }
+    finally {
+        cancellation.abort();
+        await close();
+        await rm(directory, { recursive: true, force: true });
+        process.removeListener('SIGTERM', terminate);
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGHUP', hangup);
+        byteExecution?.signal.removeEventListener('abort', cancel);
+    }
+}
+function matches(resource, requested) {
+    return requested !== undefined && [resource.name, resource.singularName, resource.kind.toLowerCase(), ...(resource.shortNames ?? []), `${resource.name}.${resource.apiVersion.split('/')[0]}`].includes(requested);
+}
+function compact(item, kind) {
+    const row = { name: item.metadata.name, ...(item.metadata.namespace ? { namespace: item.metadata.namespace } : {}) };
+    if (kind === 'Node')
+        return { ...row, ready: item.status?.conditions?.find(condition => condition.type === 'Ready')?.status ?? 'Unknown' };
+    if (kind === 'Deployment')
+        return { ...row, desired: item.spec?.replicas ?? 1, available: item.status?.availableReplicas ?? 0 };
+    if (kind === 'Pod' || kind === 'Namespace')
+        return { ...row, phase: item.status?.phase ?? 'Unknown' };
+    if (kind === 'NodeMetrics' || kind === 'PodMetrics') {
+        const usages = kind === 'NodeMetrics' ? [item.usage] : item.containers?.map(container => container.usage);
+        if (!usages?.length || usages.some(usage => !usage || typeof usage.cpu !== 'string' || typeof usage.memory !== 'string'))
+            throw new Failure('UPSTREAM_INVALID', 'Metrics usage is missing or invalid.');
+        return { ...row, cpu: `${usages.reduce((sum, usage) => sum + quantity(usage.cpu, 'cpu'), 0)}m`, memory: `${usages.reduce((sum, usage) => sum + quantity(usage.memory, 'memory'), 0)}Mi` };
+    }
+    return { ...row, kind };
+}
+function quantity(value, type) {
+    const match = /^(\d+(?:\.\d+)?)(n|u|m|Ki|Mi|Gi|Ti|k|M|G|T)?$/.exec(value);
+    const units = { '': 1, n: 1e-9, u: 1e-6, m: 1e-3, Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4, k: 1000, M: 1e6, G: 1e9, T: 1e12 };
+    if (!match)
+        throw new Failure('UPSTREAM_INVALID', 'Metrics contain an invalid quantity.');
+    return Number((Number(match[1]) * units[match[2] ?? ''] * (type === 'cpu' ? 1000 : 1 / 1024 ** 2)).toPrecision(12));
+}

package/dist/workspace-tar.d.ts

@@ -0,0 +1,6 @@
+export declare function relativeFile(path: string): string;
+export declare function workspaceTar(root: string, path: string, name?: string): Promise<Buffer>;
+export declare function readWorkspaceTar(archive: Buffer): {
+    path: string;
+    bytes: Buffer;
+}[];

package/dist/workspace-tar.js

@@ -0,0 +1,109 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { join, posix } from 'node:path';
+import { Failure } from './errors.js';
+const fileLimit = 100 * 1024 * 1024;
+const totalLimit = 250 * 1024 * 1024;
+export function relativeFile(path) {
+    if (!path || /[\\:\x00-\x1f\x7f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new Failure('PATH_REFUSED', 'Use regular files at canonical relative workspace paths.');
+    return path;
+}
+export async function workspaceTar(root, path, name = posix.basename(path)) {
+    relativeFile(path);
+    relativeFile(name);
+    const parts = path.split('/');
+    for (let count = 1; count <= parts.length; count++) {
+        if ((await lstat(join(root, ...parts.slice(0, count)))).isSymbolicLink())
+            throw new Failure('PATH_REFUSED', 'Workspace links are refused.');
+    }
+    const chunks = [];
+    let count = 0;
+    let total = 0;
+    const add = async (source, name) => {
+        const info = await lstat(source);
+        if (info.isSymbolicLink() || !info.isDirectory() && !info.isFile())
+            throw new Failure('PATH_REFUSED', 'Workspace transfers accept only regular files and directories.');
+        if (info.isDirectory()) {
+            for (const child of (await readdir(source)).sort())
+                await add(join(source, child), `${name}/${child}`);
+            return;
+        }
+        if (++count > 100 || info.size > fileLimit || (total += info.size) > totalLimit)
+            throw new Failure('TRANSFER_LIMIT', 'The workspace exceeds its file count or byte limits.');
+        const bytes = await readFile(source);
+        if (bytes.length !== info.size)
+            throw new Failure('WORKSPACE_CHANGED', 'A workspace file changed during preparation.');
+        const header = Buffer.alloc(512);
+        const separator = name.lastIndexOf('/');
+        const leaf = Buffer.byteLength(name) <= 100 ? name : name.slice(separator + 1);
+        const prefix = Buffer.byteLength(name) <= 100 ? '' : name.slice(0, separator);
+        if (Buffer.byteLength(leaf) > 100 || Buffer.byteLength(prefix) > 155 || separator < 0 && prefix)
+            throw new Failure('PATH_REFUSED', 'The file path exceeds the portable tar header limits.');
+        header.write(leaf, 0, 100);
+        header.write(prefix, 345, 155);
+        const octal = (value, offset, length) => { header.write(value.toString(8).padStart(length - 1, '0') + '\0', offset, length); };
+        octal(0o600, 100, 8);
+        octal(0, 108, 8);
+        octal(0, 116, 8);
+        octal(bytes.length, 124, 12);
+        octal(0, 136, 12);
+        header.fill(32, 148, 156);
+        header[156] = 48;
+        header.write('ustar\0', 257);
+        header.write('00', 263);
+        const checksum = header.reduce((sum, byte) => sum + byte, 0);
+        header.write(checksum.toString(8).padStart(6, '0') + '\0 ', 148, 8);
+        chunks.push(header, bytes, Buffer.alloc((512 - bytes.length % 512) % 512));
+    };
+    await add(join(root, path), name);
+    return Buffer.concat([...chunks, Buffer.alloc(1024)]);
+}
+export function readWorkspaceTar(archive) {
+    if (archive.length > totalLimit + 102400)
+        throw new Failure('TRANSFER_LIMIT', 'The archive exceeds the workspace limit.');
+    const files = [];
+    const names = new Set();
+    let total = 0;
+    let offset = 0;
+    const number = (header, start, length) => {
+        const text = header.subarray(start, start + length).toString('ascii').replace(/\0.*$/, '').trim();
+        if (!/^[0-7]+$/.test(text))
+            throw new Failure('ARCHIVE_REFUSED', 'The archive contains an invalid numeric header.');
+        return Number.parseInt(text, 8);
+    };
+    const field = (header, start, length) => header.subarray(start, start + length).toString('utf8').replace(/\0.*$/, '');
+    while (offset + 512 <= archive.length) {
+        const header = archive.subarray(offset, offset + 512);
+        if (header.every(byte => byte === 0)) {
+            if (!archive.subarray(offset).every(byte => byte === 0))
+                throw new Failure('ARCHIVE_REFUSED', 'The archive has trailing nonzero data.');
+            return files;
+        }
+        const expected = number(header, 148, 8);
+        const checksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+        if (checksum !== expected)
+            throw new Failure('ARCHIVE_REFUSED', 'The archive checksum is invalid.');
+        const prefix = field(header, 345, 155);
+        const name = relativeFile((prefix ? `${prefix}/` : '') + field(header, 0, 100).replace(/\/$/, ''));
+        const size = number(header, 124, 12);
+        const type = header[156];
+        if (![0, 48, 53].includes(type))
+            throw new Failure('PATH_REFUSED', 'Links, extended headers and special archive entries are refused.');
+        if (size > fileLimit || (total += size) > totalLimit || offset + 512 + size > archive.length)
+            throw new Failure('TRANSFER_LIMIT', 'The archive exceeds its declared or permitted size.');
+        if (names.has(name) || [...names].some(other => other.startsWith(name + '/') || name.startsWith(other + '/')))
+            throw new Failure('PATH_REFUSED', 'The archive has duplicate or conflicting paths.');
+        if (type === 53) {
+            if (size !== 0)
+                throw new Failure('ARCHIVE_REFUSED', 'Directory entries must have no payload.');
+        }
+        else {
+            if (files.length >= 100)
+                throw new Failure('TRANSFER_LIMIT', 'The archive exceeds 100 files.');
+            names.add(name);
+            files.push({ path: name, bytes: Buffer.from(archive.subarray(offset + 512, offset + 512 + size)) });
+        }
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    throw new Failure('ARCHIVE_REFUSED', 'The archive ended before its EOF marker.');
+}

package/docs/hooks.md

@@ -0,0 +1,35 @@
+# Optional session guidance
+
+Read Kubernetes resources using isolated credentials and pinned kubectl v1.32.2.
+Use --profile <name> to select an AXI identity.
+Use native -- <kubectl arguments> for native output; native --profile is upstream profiling and is blocked because it writes files.
+Reads are bounded; inspect complete, truncated and continue before treating output as complete.
+Writes default off.
+Explicitly enable KUBERNETES_AXI_READ_ONLY=false, then use prepare -- <mutation>, preview <request-key>, and confirm <request-key> --digest <preview-digest>.
+Preparation reads exact targets; local preview makes no API calls.
+Confirmation is one-shot and refuses stale or changed targets.
+Bulk deletion also requires KUBERNETES_AXI_COLLECTION_DELETE=true.
+Use server-dry-run -- <mutation> for explicit API validation without persistence.
+Exec/attach and named debug mutations require preparation and confirmation.
+In 0.1.x, managed interactive exec/attach/debug and standalone watch, follow and port-forward requests are refused before effects.
+Credentials come only from existing config/profile and secure credential references; tool-managed sessions never read credential secrets from terminal prompts.
+Bounded noninteractive execution and existing hosted bounded sessions remain supported.
+Streaming redaction and interactive execution redesigns are tracked at https://github.com/knowttl/kubernetes-axi/issues/34 and https://github.com/knowttl/kubernetes-axi/issues/35.
+Native Windows support remains pending.
+Token issuance additionally requires KUBERNETES_AXI_ACQUIRE_CREDENTIAL=true, a duration of at most one hour, and --credential-fd <inherited-private-pipe> before confirm.
+Issued tokens are delivered once and never retained.
+Hosted workspace transfer, byte sessions, followed logs, watches and multi-port forwarding use caller-owned authenticated Artium sessions.
+In 0.1.x, run editors, plugins and external render/diff helpers outside the CLI, then prepare the resulting manifest or patch and confirm its preview.
+Their execution inside the CLI is refused before effects.
+Generic proxy listeners and credential overrides remain refused.
+Native completion, options, plugin list and version --client=true work without credentials.
+In 0.1.x, run diff and its external helpers outside the CLI.
+Submit resulting changes through prepare, preview and confirm.
+Run kubernetes-axi --help for available commands and kubernetes-axi native -- <command> --help for generated upstream flags.
+
+Install a session hook only with explicit user opt-in.
+Claude Code and Codex SessionStart hooks can run `kubernetes-axi` for the bounded home view.
+OpenCode can inject the same home view through a user-managed plugin.
+Use a PATH-verified binary or the absolute installed executable path.
+No hook is installed by package installation, CLI reads or tests.
+The installable skill is an alternative when session hooks are unavailable.

package/kubectl-pins.json

@@ -0,0 +1,18 @@
+{
+  "version": "v1.32.2",
+  "supportedServerMinors": [31, 32, 33],
+  "matrixStatus": "observational until live commissioning",
+  "decision": "kubectl pin v1.32.2 - captain-delegated (overnight), plan-named selection; revisit at commissioning.",
+  "binaries": {
+    "linux-x64": {
+      "file": "kubectl-linux-amd64",
+      "url": "https://dl.k8s.io/release/v1.32.2/bin/linux/amd64/kubectl",
+      "sha256": "4f6a959dcc5b702135f8354cc7109b542a2933c46b808b248a214c1f69f817ea"
+    },
+    "win32-x64": {
+      "file": "kubectl-windows-amd64.exe",
+      "url": "https://dl.k8s.io/release/v1.32.2/bin/windows/amd64/kubectl.exe",
+      "sha256": "cf51a1c6bf3b6ba6a5b549d1debf8aa6afb00c4c5a3d5d4bb1072f54cbe4390f"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@knowttl/kubernetes-axi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Agent-facing Kubernetes CLI backed by pinned kubectl",
+  "repository": { "type": "git", "url": "git+https://github.com/knowttl/kubernetes-axi.git" },
+  "type": "module",
+  "engines": { "node": "24.14.0", "npm": "11.9.0" },
+  "packageManager": "npm@11.9.0",
+  "publishConfig": { "access": "public" },
+  "bin": { "kubernetes-axi": "bin/kubernetes-axi.js" },
+  "files": ["bin", "dist", "vendor", "third-party", "THIRD_PARTY_NOTICES.md", "axi-credential.schema.json", "kubectl-pins.json", "command-metadata.json", "skills", "docs/hooks.md"],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "node scripts/check-binaries.mjs && tsc",
+    "lint": "tsc --noEmit && tsc -p tsconfig.tools.json && tsc -p tsconfig.verify.json",
+    "test": "unshare --user --map-root-user --net -- sh -c 'ip link set lo up && GOPROXY=off node scripts/generate-metadata.ts --check && GOPROXY=off node scripts/generate-protobuf.ts --check && python3 scripts/verify.py task B1.1 --mode offline --pack evidence && node test/private-files.ts && node test/b2.ts && node test/package-contract.ts'",
+    "generate:metadata": "node scripts/generate-metadata.ts",
+    "check:metadata": "GOPROXY=off node scripts/generate-metadata.ts --check",
+    "check": "npm run lint && npm test"
+  },
+  "dependencies": { "@toon-format/toon": "4.4.0", "@types/node": "24.10.0", "ajv": "8.17.1", "protobufjs": "7.6.6" },
+  "devDependencies": { "typescript": "5.9.3" }
+}

package/skills/kubernetes-axi/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: kubernetes-axi
+description: Inspect Kubernetes resources, discovery, metrics and logs with bounded output and isolated credentials.
+---
+
+Read Kubernetes resources using isolated credentials and pinned kubectl v1.32.2.
+Use --profile <name> to select an AXI identity.
+Use native -- <kubectl arguments> for native output; native --profile is upstream profiling and is blocked because it writes files.
+Reads are bounded; inspect complete, truncated and continue before treating output as complete.
+Writes default off.
+Explicitly enable KUBERNETES_AXI_READ_ONLY=false, then use prepare -- <mutation>, preview <request-key>, and confirm <request-key> --digest <preview-digest>.
+Preparation reads exact targets; local preview makes no API calls.
+Confirmation is one-shot and refuses stale or changed targets.
+Bulk deletion also requires KUBERNETES_AXI_COLLECTION_DELETE=true.
+Use server-dry-run -- <mutation> for explicit API validation without persistence.
+Exec/attach and named debug mutations require preparation and confirmation.
+In 0.1.x, managed interactive exec/attach/debug and standalone watch, follow and port-forward requests are refused before effects.
+Credentials come only from existing config/profile and secure credential references; tool-managed sessions never read credential secrets from terminal prompts.
+Bounded noninteractive execution and existing hosted bounded sessions remain supported.
+Streaming redaction and interactive execution redesigns are tracked at https://github.com/knowttl/kubernetes-axi/issues/34 and https://github.com/knowttl/kubernetes-axi/issues/35.
+Native Windows support remains pending.
+Token issuance additionally requires KUBERNETES_AXI_ACQUIRE_CREDENTIAL=true, a duration of at most one hour, and --credential-fd <inherited-private-pipe> before confirm.
+Issued tokens are delivered once and never retained.
+Hosted workspace transfer, byte sessions, followed logs, watches and multi-port forwarding use caller-owned authenticated Artium sessions.
+In 0.1.x, run editors, plugins and external render/diff helpers outside the CLI, then prepare the resulting manifest or patch and confirm its preview.
+Their execution inside the CLI is refused before effects.
+Generic proxy listeners and credential overrides remain refused.
+Native completion, options, plugin list and version --client=true work without credentials.
+In 0.1.x, run diff and its external helpers outside the CLI.
+Submit resulting changes through prepare, preview and confirm.
+Run npx -y @knowttl/kubernetes-axi --help for available commands and npx -y @knowttl/kubernetes-axi native -- <command> --help for generated upstream flags.
+