@alpacakit/agents 0.1.0-beta.19

package/dist/core/env.js

@@ -0,0 +1,39 @@
+/**
+ * Env mutation as data (design A8): activating one auth mechanism must be
+ * able to clear competing variables, so a patch carries both directions.
+ */
+// Shared default: frozen at both levels so no caller can mutate it in place.
+export const EMPTY_ENV_PATCH = Object.freeze({ set: {}, unset: [] });
+Object.freeze(EMPTY_ENV_PATCH.set);
+Object.freeze(EMPTY_ENV_PATCH.unset);
+export function applyEnvPatch(env, patch) {
+    const next = { ...env };
+    for (const name of patch.unset) {
+        delete next[name];
+    }
+    for (const [name, value] of Object.entries(patch.set)) {
+        next[name] = value;
+    }
+    return next;
+}
+export function mergeEnvPatches(first, second) {
+    return {
+        set: { ...first.set, ...second.set },
+        unset: [...first.unset, ...second.unset],
+    };
+}
+/**
+ * Snapshot `process.env` as a defined-only `Record<string, string>` — the
+ * `baseEnv` shape `createAgentRuntime` and `runAgent` expect. Exposed so
+ * callers stop reaching for `process.env as Record<string, string>`, which
+ * lies about the `undefined` values Node keeps on the object.
+ */
+export function processEnv() {
+    const env = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            env[name] = value;
+        }
+    }
+    return env;
+}

package/dist/core/error.d.ts

@@ -0,0 +1,121 @@
+/**
+ * One throwable type crosses the library boundary (design: "Errors are
+ * data"). Error data is typed per code through the `AgentErrorData` map;
+ * a `Record<string, unknown>` grab-bag is banned.
+ */
+export declare const AGENT_ERROR_CODE: {
+    readonly invalidInput: "invalid_input";
+    readonly notAvailable: "not_available";
+    readonly capacity: "capacity";
+    readonly quota: "quota";
+    readonly auth: "auth";
+    readonly timeout: "timeout";
+    readonly limit: "limit";
+    readonly cancelled: "cancelled";
+    readonly outputRejected: "output_rejected";
+    readonly failed: "failed";
+};
+export type AgentErrorCode = (typeof AGENT_ERROR_CODE)[keyof typeof AGENT_ERROR_CODE];
+export declare const AUTH_FAILURE_REASON: {
+    readonly notLoggedIn: "not_logged_in";
+    readonly invalidApiKey: "invalid_api_key";
+    readonly invalidToken: "invalid_token";
+    readonly invalidCredentials: "invalid_credentials";
+    readonly refreshTokenReused: "refresh_token_reused";
+    readonly tokenInvalidated: "token_invalidated";
+    readonly authenticationFailed: "authentication_failed";
+    readonly unauthorized: "unauthorized";
+    readonly forbidden: "forbidden";
+    readonly unknown: "unknown";
+};
+export type AuthFailureReason = (typeof AUTH_FAILURE_REASON)[keyof typeof AUTH_FAILURE_REASON];
+export declare const NOT_AVAILABLE_CAUSE: {
+    readonly notInstalled: "not_installed";
+    readonly engineMissing: "engine_missing";
+    readonly badConfig: "bad_config";
+    readonly unreachable: "unreachable";
+};
+export type NotAvailableCause = (typeof NOT_AVAILABLE_CAUSE)[keyof typeof NOT_AVAILABLE_CAUSE];
+export declare const TIMEOUT_KIND: {
+    readonly total: "total";
+    readonly idle: "idle";
+};
+export type TimeoutKind = (typeof TIMEOUT_KIND)[keyof typeof TIMEOUT_KIND];
+export type GuardViolation = {
+    guardId: string;
+    reason: string;
+};
+export type Issue = {
+    path: Array<string | number>;
+    code: string;
+    message: string;
+};
+export type AgentErrorData = {
+    [AGENT_ERROR_CODE.invalidInput]: {
+        reason: string;
+    };
+    [AGENT_ERROR_CODE.notAvailable]: {
+        cause: NotAvailableCause;
+    };
+    [AGENT_ERROR_CODE.capacity]: {
+        cooldownUntil: string | null;
+    };
+    [AGENT_ERROR_CODE.quota]: {
+        cooldownUntil: string | null;
+    };
+    [AGENT_ERROR_CODE.auth]: {
+        reason: AuthFailureReason;
+        detail: string | null;
+    };
+    [AGENT_ERROR_CODE.timeout]: {
+        kind: TimeoutKind;
+        limitMs: number;
+    };
+    [AGENT_ERROR_CODE.limit]: {
+        violation: GuardViolation;
+    };
+    [AGENT_ERROR_CODE.cancelled]: {
+        reason: string | null;
+    };
+    [AGENT_ERROR_CODE.outputRejected]: {
+        issues: Issue[];
+        attempts: number;
+    };
+    [AGENT_ERROR_CODE.failed]: {
+        exitCode: number | null;
+        stdoutTail: string | null;
+        stderrTail: string | null;
+    };
+};
+export type AgentErrorOptions<C extends AgentErrorCode> = {
+    code: C;
+    message: string;
+    data: AgentErrorData[C];
+    runId?: string;
+    agentId?: string;
+    started?: boolean;
+    durationMs?: number;
+    cause?: unknown;
+};
+export declare class AgentError<C extends AgentErrorCode = AgentErrorCode> extends Error {
+    readonly code: C;
+    readonly data: AgentErrorData[C];
+    readonly runId: string | null;
+    readonly agentId: string | null;
+    readonly started: boolean;
+    readonly durationMs: number;
+    constructor(options: AgentErrorOptions<C>);
+}
+/**
+ * Brand-based guard, not `instanceof`: survives duplicated package copies
+ * in one dependency tree.
+ */
+export declare function isAgentError<C extends AgentErrorCode>(value: unknown, code?: C): value is AgentError<C>;
+/** Rebuild an AgentError with run identity the thrower could not know. */
+export declare function withRunIdentity<C extends AgentErrorCode>(error: AgentError<C>, identity: {
+    runId: string;
+    agentId: string;
+    started: boolean;
+    durationMs: number;
+}): AgentError<C>;
+//# sourceMappingURL=error.d.ts.map

package/dist/core/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"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"}

package/dist/core/error.js

@@ -0,0 +1,88 @@
+/**
+ * One throwable type crosses the library boundary (design: "Errors are
+ * data"). Error data is typed per code through the `AgentErrorData` map;
+ * a `Record<string, unknown>` grab-bag is banned.
+ */
+export const AGENT_ERROR_CODE = {
+    invalidInput: "invalid_input",
+    notAvailable: "not_available",
+    capacity: "capacity",
+    quota: "quota",
+    auth: "auth",
+    timeout: "timeout",
+    limit: "limit",
+    cancelled: "cancelled",
+    outputRejected: "output_rejected",
+    failed: "failed",
+};
+export const AUTH_FAILURE_REASON = {
+    notLoggedIn: "not_logged_in",
+    invalidApiKey: "invalid_api_key",
+    invalidToken: "invalid_token",
+    invalidCredentials: "invalid_credentials",
+    refreshTokenReused: "refresh_token_reused",
+    tokenInvalidated: "token_invalidated",
+    authenticationFailed: "authentication_failed",
+    unauthorized: "unauthorized",
+    forbidden: "forbidden",
+    unknown: "unknown",
+};
+export const NOT_AVAILABLE_CAUSE = {
+    notInstalled: "not_installed",
+    engineMissing: "engine_missing",
+    badConfig: "bad_config",
+    unreachable: "unreachable",
+};
+export const TIMEOUT_KIND = {
+    total: "total",
+    idle: "idle",
+};
+const AGENT_ERROR_BRAND = Symbol.for("@alpacakit/agents.AgentError");
+export class AgentError extends Error {
+    code;
+    data;
+    runId;
+    agentId;
+    started;
+    durationMs;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "AgentError";
+        this.code = options.code;
+        this.data = options.data;
+        this.runId = options.runId ?? null;
+        this.agentId = options.agentId ?? null;
+        this.started = options.started ?? false;
+        this.durationMs = options.durationMs ?? 0;
+        Object.defineProperty(this, AGENT_ERROR_BRAND, {
+            value: true,
+            enumerable: false,
+        });
+    }
+}
+/**
+ * Brand-based guard, not `instanceof`: survives duplicated package copies
+ * in one dependency tree.
+ */
+export function isAgentError(value, code) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    if (Reflect.get(value, AGENT_ERROR_BRAND) !== true) {
+        return false;
+    }
+    return code === undefined || Reflect.get(value, "code") === code;
+}
+/** Rebuild an AgentError with run identity the thrower could not know. */
+export function withRunIdentity(error, identity) {
+    return new AgentError({
+        code: error.code,
+        message: error.message,
+        data: error.data,
+        runId: error.runId ?? identity.runId,
+        agentId: error.agentId ?? identity.agentId,
+        started: error.started || identity.started,
+        durationMs: error.durationMs > 0 ? error.durationMs : identity.durationMs,
+        cause: error.cause,
+    });
+}

package/dist/core/fs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared filesystem discipline for the package's private state files:
+ * errno narrowing without `instanceof` on Node internals, and the
+ * 0700-directory / 0600-file atomic write ritual (temp + rename) every
+ * store uses.
+ */
+export declare const PRIVATE_DIRECTORY_MODE = 448;
+export declare const PRIVATE_FILE_MODE = 384;
+/** Narrowing over Node fs errors without `instanceof` on internals. */
+export declare function isErrnoCode(error: unknown, code: string): boolean;
+/**
+ * Write a private (0600) file atomically: create the 0700 parent, write
+ * a pid-suffixed temp file, then rename over the destination.
+ */
+export declare function writeFileAtomically(filePath: string, content: string): Promise<void>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/core/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/core/fs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,eAAO,MAAM,sBAAsB,MAAQ,CAAC;AAC5C,eAAO,MAAM,iBAAiB,MAAQ,CAAC;AAGvC,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAMjE;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/core/fs.js

@@ -0,0 +1,30 @@
+/**
+ * Shared filesystem discipline for the package's private state files:
+ * errno narrowing without `instanceof` on Node internals, and the
+ * 0700-directory / 0600-file atomic write ritual (temp + rename) every
+ * store uses.
+ */
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const PRIVATE_DIRECTORY_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+const TEMP_FILE_SUFFIX = "tmp";
+/** Narrowing over Node fs errors without `instanceof` on internals. */
+export function isErrnoCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === code);
+}
+/**
+ * Write a private (0600) file atomically: create the 0700 parent, write
+ * a pid-suffixed temp file, then rename over the destination.
+ */
+export async function writeFileAtomically(filePath, content) {
+    await mkdir(path.dirname(filePath), {
+        recursive: true,
+        mode: PRIVATE_DIRECTORY_MODE,
+    });
+    const tempPath = [filePath, String(process.pid), TEMP_FILE_SUFFIX].join(".");
+    await writeFile(tempPath, content, { mode: PRIVATE_FILE_MODE });
+    await rename(tempPath, filePath);
+}

package/dist/core/json.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Narrowing readers over parsed JSON (rule: no `any`, no throwing on
+ * shape mismatch — `null` is "not there"). Shared by NDJSON line parsing
+ * in the built-in agents and host-plane CLI output parsing.
+ */
+/**
+ * Foreign JSON before field-level narrowing. This alias is the ONE place
+ * the broad record shape is spelled (biome.json exempts this module from
+ * the no-broad-record plugin); every reader boundary references it so
+ * contract types elsewhere stay explicitly modeled.
+ */
+export type UnknownRecord = Record<string, unknown>;
+export declare function readUnknownRecord(value: unknown): UnknownRecord | null;
+export declare function readJsonRecord(line: string): UnknownRecord | null;
+export declare function readString(record: UnknownRecord, key: string): string | null;
+export declare function readNumber(record: UnknownRecord, key: string): number | null;
+export declare function readRecord(record: UnknownRecord, key: string): UnknownRecord | null;
+export declare function readBoolean(record: UnknownRecord, key: string): boolean | null;
+export declare function readArray(record: UnknownRecord, key: string): readonly unknown[] | null;
+//# sourceMappingURL=json.d.ts.map

package/dist/core/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/core/json.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAKtE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAUjE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5E;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,GACV,aAAa,GAAG,IAAI,CAEtB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,GACV,OAAO,GAAG,IAAI,CAGhB;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,GACV,SAAS,OAAO,EAAE,GAAG,IAAI,CAG3B"}

package/dist/core/json.js

@@ -0,0 +1,42 @@
+/**
+ * Narrowing readers over parsed JSON (rule: no `any`, no throwing on
+ * shape mismatch — `null` is "not there"). Shared by NDJSON line parsing
+ * in the built-in agents and host-plane CLI output parsing.
+ */
+export function readUnknownRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+export function readJsonRecord(line) {
+    if (!line.startsWith("{") || !line.endsWith("}")) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(line);
+        return readUnknownRecord(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : null;
+}
+export function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" ? value : null;
+}
+export function readRecord(record, key) {
+    return readUnknownRecord(record[key]);
+}
+export function readBoolean(record, key) {
+    const value = record[key];
+    return typeof value === "boolean" ? value : null;
+}
+export function readArray(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value : null;
+}

package/dist/core/node-ports.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Production port defaults. This is the only module (besides the "env"
+ * secret resolver) that touches Node process APIs directly.
+ */
+import type { Clock, Exec, HttpClient } from "./ports.js";
+export declare const systemClock: Clock;
+export declare const fetchHttp: HttpClient;
+export declare const nodeExec: Exec;
+//# sourceMappingURL=node-ports.d.ts.map

package/dist/core/node-ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../src/core/node-ports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EACV,KAAK,EACL,IAAI,EAIJ,UAAU,EAGX,MAAM,YAAY,CAAC;AAOpB,eAAO,MAAM,WAAW,EAAE,KAOzB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,UAEvB,CAAC;AA+HF,eAAO,MAAM,QAAQ,EAAE,IAGtB,CAAC"}

package/dist/core/node-ports.js

@@ -0,0 +1,135 @@
+/**
+ * Production port defaults. This is the only module (besides the "env"
+ * secret resolver) that touches Node process APIs directly.
+ */
+import { spawn } from "node:child_process";
+import { access, constants } from "node:fs";
+import path from "node:path";
+import { AsyncQueue } from "./async-queue.js";
+import { OUTPUT_CHANNEL, TEXT_ENCODING } from "./values.js";
+const PATH_ENV_VAR = "PATH";
+const PATHEXT_ENV_VAR = "PATHEXT";
+const DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS = ".COM;.EXE;.BAT;.CMD";
+export const systemClock = {
+    now: () => Date.now(),
+    setTimeout: (callback, delayMs) => {
+        const timer = setTimeout(callback, delayMs);
+        timer.unref();
+        return () => clearTimeout(timer);
+    },
+};
+export const fetchHttp = {
+    fetch: (url, init) => fetch(url, init),
+};
+/**
+ * Node-bin-first PATH (E5): the wrapped CLIs are node scripts, so both
+ * resolving them and letting them find `node` needs the running node's
+ * bin directory first on PATH. Reading `process.execPath` is this
+ * production adapter's boundary job, like `process.env` is the env
+ * resolver's.
+ */
+const nodeBinDir = path.dirname(process.execPath);
+function pathKeyOf(env) {
+    for (const key of Object.keys(env)) {
+        if (key.toUpperCase() === PATH_ENV_VAR) {
+            return key;
+        }
+    }
+    return PATH_ENV_VAR;
+}
+function withNodeBinFirst(env) {
+    const key = pathKeyOf(env);
+    const entries = (env[key] ?? "")
+        .split(path.delimiter)
+        .filter((entry) => entry !== "");
+    if (entries[0] === nodeBinDir) {
+        return env;
+    }
+    const rest = entries.filter((entry) => entry !== nodeBinDir);
+    return { ...env, [key]: [nodeBinDir, ...rest].join(path.delimiter) };
+}
+function spawnProcess(options) {
+    const child = spawn(options.command, options.args, {
+        cwd: options.cwd,
+        env: withNodeBinFirst(options.env),
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const chunks = new AsyncQueue();
+    let settleExit = () => { };
+    let failExit = () => { };
+    const exit = new Promise((resolve, reject) => {
+        settleExit = resolve;
+        failExit = reject;
+    });
+    child.stdout.setEncoding(TEXT_ENCODING);
+    child.stderr.setEncoding(TEXT_ENCODING);
+    child.stdout.on("data", (text) => {
+        chunks.push({ channel: OUTPUT_CHANNEL.stdout, text });
+    });
+    child.stderr.on("data", (text) => {
+        chunks.push({ channel: OUTPUT_CHANNEL.stderr, text });
+    });
+    child.on("error", (error) => {
+        chunks.end();
+        failExit(error);
+    });
+    child.on("close", (code, signal) => {
+        chunks.end();
+        settleExit({ code, signal });
+    });
+    // A child that exits without reading stdin emits EPIPE here; without a
+    // listener that unhandled 'error' event would crash the host process.
+    child.stdin.on("error", () => { });
+    if (options.stdin !== null) {
+        child.stdin.write(options.stdin);
+    }
+    if (!("keepStdinOpen" in options)) {
+        child.stdin.end();
+    }
+    return {
+        chunks,
+        exit,
+        writeStdin: (text) => {
+            child.stdin.write(text);
+        },
+        endStdin: () => {
+            child.stdin.end();
+        },
+        kill: (signal) => {
+            child.kill(signal);
+        },
+    };
+}
+function isExecutable(candidate) {
+    return new Promise((resolve) => {
+        access(candidate, constants.X_OK, (error) => {
+            resolve(error === null);
+        });
+    });
+}
+async function whichOnPath(command, env) {
+    if (command.includes(path.sep)) {
+        return (await isExecutable(command)) ? command : null;
+    }
+    const layered = withNodeBinFirst(env);
+    const pathValue = layered[pathKeyOf(layered)] ?? "";
+    const extensions = process.platform === "win32"
+        ? (env[PATHEXT_ENV_VAR] ?? DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS).split(";")
+        : [""];
+    for (const directory of pathValue.split(path.delimiter)) {
+        if (directory === "") {
+            continue;
+        }
+        for (const extension of extensions) {
+            const candidate = path.join(directory, command + extension);
+            if (await isExecutable(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+export const nodeExec = {
+    spawn: spawnProcess,
+    which: whichOnPath,
+};

package/dist/core/ports.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Ports for every effect (design principle 4): subprocess spawn, clock,
+ * secrets, HTTP, and telemetry are injected interfaces with production
+ * defaults. No library module reads `process.env` or spawns directly —
+ * the sole exception is the built-in "env" secret resolver, whose entire
+ * job is that boundary.
+ */
+import type { Clock, HttpClient, SecretResolvers } from "@alpacakit/core";
+import type { RunTelemetry } from "./run.js";
+import type { OutputChannel, ProcessSignal } from "./values.js";
+export type { Clock, HttpClient, SecretResolver, SecretResolvers, } from "@alpacakit/core";
+export type ExecChunk = {
+    channel: OutputChannel;
+    text: string;
+};
+export type ExecExit = {
+    code: number | null;
+    signal: string | null;
+};
+export type ExecSpawnOptions = {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    stdin: string | null;
+};
+/** Interactive spawn: stdin stays open for incremental writes. */
+export type InteractiveExecSpawnOptions = ExecSpawnOptions & {
+    keepStdinOpen: true;
+};
+export interface ExecProcess {
+    readonly chunks: AsyncIterable<ExecChunk>;
+    readonly exit: Promise<ExecExit>;
+    kill(signal: ProcessSignal): void;
+}
+/** Returned by interactive spawns; stdin capability is carried by the type. */
+export interface InteractiveExecProcess extends ExecProcess {
+    writeStdin(text: string): void;
+    endStdin(): void;
+}
+export interface Exec {
+    spawn(options: InteractiveExecSpawnOptions): InteractiveExecProcess;
+    spawn(options: ExecSpawnOptions): ExecProcess;
+    /** Resolve a command against the given env's PATH; null when absent. */
+    which(command: string, env: Record<string, string>): Promise<string | null>;
+}
+export interface TelemetrySink {
+    emit(telemetry: RunTelemetry): void;
+}
+export declare const LOG_LEVEL: {
+    readonly debug: "debug";
+    readonly info: "info";
+    readonly warn: "warn";
+    readonly error: "error";
+};
+export type LogLevel = (typeof LOG_LEVEL)[keyof typeof LOG_LEVEL];
+export interface Logger {
+    log(level: LogLevel, message: string, data?: unknown): void;
+}
+/** The RESOLVED shape (rule 2): every port present. */
+export type Ports = {
+    exec: Exec;
+    clock: Clock;
+    secrets: SecretResolvers;
+    http: HttpClient;
+    telemetry: TelemetrySink;
+    logger: Logger;
+};
+export declare const noopTelemetry: TelemetrySink;
+export declare const noopLogger: Logger;
+//# sourceMappingURL=ports.d.ts.map

package/dist/core/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/core/ports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,YAAY,EACV,KAAK,EACL,UAAU,EACV,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,GAAG;IAC3D,aAAa,EAAE,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;CACnC;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,CAAC,OAAO,EAAE,2BAA2B,GAAG,sBAAsB,CAAC;IACpE,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAC9C,wEAAwE;IACxE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC;AAED,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAElE,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7D;AAED,uDAAuD;AACvD,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,eAAe,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,aAE3B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAExB,CAAC"}

package/dist/core/ports.js

@@ -0,0 +1,19 @@
+/**
+ * Ports for every effect (design principle 4): subprocess spawn, clock,
+ * secrets, HTTP, and telemetry are injected interfaces with production
+ * defaults. No library module reads `process.env` or spawns directly —
+ * the sole exception is the built-in "env" secret resolver, whose entire
+ * job is that boundary.
+ */
+export const LOG_LEVEL = {
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+};
+export const noopTelemetry = {
+    emit: () => { },
+};
+export const noopLogger = {
+    log: () => { },
+};

package/dist/core/redact.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Library-wide rule (design F7): every surfaced diagnostic passes secret
+ * redaction before it can appear in an error message or telemetry event.
+ */
+import type { JsonValue } from "@alpacakit/core";
+export declare function redactSecrets(text: string): string;
+export declare function redactJsonSecrets(value: JsonValue): JsonValue;
+//# sourceMappingURL=redact.d.ts.map

package/dist/core/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/core/redact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAuCjD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASlD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAgB7D"}