@wardby/cli 0.5.3 → 0.7.0

package/dist/config/low-power.js

@@ -0,0 +1,18 @@
+const DEFAULT_IDLE_MINUTES = 30;
+export function loadLowPowerConfig(env = process.env) {
+    const flag = env.WARDBY_LOW_POWER?.trim();
+    if (flag !== undefined && flag !== "" && flag !== "0" && flag !== "1") {
+        throw new Error("WARDBY_LOW_POWER must be 0 or 1.");
+    }
+    // LOW_POWER_IDLE_MINUTES only matters with the mode on; off, it is ignored entirely.
+    if (flag !== "1")
+        return { enabled: false, idleMinutes: DEFAULT_IDLE_MINUTES };
+    const raw = env.LOW_POWER_IDLE_MINUTES?.trim();
+    if (!raw)
+        return { enabled: true, idleMinutes: DEFAULT_IDLE_MINUTES };
+    const idleMinutes = /^\d+$/.test(raw) ? Number(raw) : NaN;
+    if (!(idleMinutes >= 5 && idleMinutes <= 1440)) {
+        throw new Error("LOW_POWER_IDLE_MINUTES must be an integer from 5 to 1440.");
+    }
+    return { enabled: true, idleMinutes };
+}

package/dist/config/mobile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mobile app access (WARDBY_MOBILE_ENABLED, off by default). S1: the app's
+ * private-use OAuth redirect (RFC 8252 §7.1); later: push notifications.
+ */
+export declare const DEFAULT_MOBILE_REDIRECT_URI = "com.wardby.mobile:/oauth";
+export declare const MOBILE_DISABLED = "mobile_disabled";
+export interface MobileConfig {
+    enabled: boolean;
+    /** The one redirect URI mobile sign-in may use; matched exactly. */
+    redirectUri: string;
+}
+export declare function loadMobileConfig(env?: NodeJS.ProcessEnv): MobileConfig;

package/dist/config/mobile.js

@@ -0,0 +1,18 @@
+/**
+ * Mobile app access (WARDBY_MOBILE_ENABLED, off by default). S1: the app's
+ * private-use OAuth redirect (RFC 8252 §7.1); later: push notifications.
+ */
+export const DEFAULT_MOBILE_REDIRECT_URI = "com.wardby.mobile:/oauth";
+export const MOBILE_DISABLED = "mobile_disabled";
+/** A reverse-domain scheme (at least one dot), ":/", then a path — no host, query, or fragment. */
+const PRIVATE_USE_REDIRECT = /^[a-z][a-z0-9+-]*(\.[a-z0-9+-]+)+:\/(?!\/)[A-Za-z0-9/_-]*$/;
+export function loadMobileConfig(env = process.env) {
+    const raw = env.WARDBY_MOBILE_ENABLED?.trim().toLowerCase() ?? "";
+    if (raw !== "" && raw !== "true" && raw !== "false")
+        throw new Error("WARDBY_MOBILE_ENABLED must be true or false.");
+    const redirectUri = env.WARDBY_MOBILE_REDIRECT_URI?.trim() || DEFAULT_MOBILE_REDIRECT_URI;
+    if (!PRIVATE_USE_REDIRECT.test(redirectUri)) {
+        throw new Error("WARDBY_MOBILE_REDIRECT_URI must be a private-use redirect such as com.example.app:/oauth.");
+    }
+    return { enabled: raw === "true", redirectUri };
+}

package/dist/config/providers.d.ts

@@ -7,11 +7,13 @@
  * adapters) is added once the adapters exist.
  */
 import { type KubernetesPlatform } from "../providers/jobs/kubernetes-platform.js";
+import type { BlobStoreConfig } from "../providers/storage/index.js";
+import { type MobileConfig } from "./mobile.js";
 export type JobLauncherKind = "local" | "docker" | "kubernetes";
 export type EmailProviderKind = "smtp" | "ses";
 export type SecretCipherKind = "app-key" | "kms";
 export type AuthProviderKind = "delegating" | "self-hosted";
-export type BlobStoreKind = "local" | "s3";
+export type BlobStoreKind = "local" | "gcs" | "s3";
 export type ExecutorKind = "in-process" | "dbos";
 export type DatastoreKind = "postgres";
 export type EngineKind = "native" | "langgraph";
@@ -21,12 +23,15 @@ export interface ProviderConfig {
     email: EmailProviderKind;
     secrets: SecretCipherKind;
     auth: AuthProviderKind;
-    storage: BlobStoreKind;
+    /** Unset BLOB_STORE means no blob store is configured. */
+    storage: BlobStoreKind | undefined;
     executor: ExecutorKind;
     datastore: DatastoreKind;
     engine: EngineKind;
     vcs: VcsProviderKind;
 }
+/** Blob store settings from the environment; undefined when BLOB_STORE is unset (no blob store). */
+export declare function loadBlobStoreConfig(env?: NodeJS.ProcessEnv): BlobStoreConfig | undefined;
 /** Read provider selection from environment variables, defaulting to portable. */
 export declare function loadProviderConfig(env?: NodeJS.ProcessEnv): ProviderConfig;
 export interface GitHubVcsConfig {
@@ -40,9 +45,14 @@ export interface GitHubVcsConfig {
 /** Trusted roots for `local:` repositories (LOCAL_REPO_ROOTS, path-delimiter separated); unset = local repositories disabled. */
 export { loadLocalRepoRoots } from "../coding/local-repo.js";
 export declare function loadGitHubVcsConfig(env?: NodeJS.ProcessEnv): GitHubVcsConfig;
-/** GitHub App webhook settings for the code-review host ingress; unset = ingress disabled. */
+/**
+ * GitHub App webhook settings for the code-review host ingress; unset = ingress disabled.
+ * `mentionExplanations` (WARDBY_MENTION_EXPLANATIONS, default true): false = a mention that
+ * starts nothing gets no reply saying why.
+ */
 export declare function loadGitHubEventConfig(env?: NodeJS.ProcessEnv): {
     webhookSecret?: string;
+    mentionExplanations: boolean;
 };
 /**
  * The GitHub App's OAuth client credentials, for linking a principal's GitHub
@@ -79,6 +89,13 @@ export interface JiraConfig {
  * are rejected.
  */
 export declare function loadJiraConfig(env?: NodeJS.ProcessEnv): JiraConfig | null;
+export interface SlackConfig {
+    botToken: string;
+    apiBaseUrl: string;
+    customize: boolean;
+}
+/** Slack workflow notifications; null when WARDBY_SLACK_BOT_TOKEN is unset (and no other Slack variable is). */
+export declare function loadSlackConfig(env?: NodeJS.ProcessEnv): SlackConfig | null;
 export interface ContainerExecutorConfig {
     workerImage?: string;
     claudeWorkerImage?: string;
@@ -122,6 +139,49 @@ export interface CodingConcurrencyConfig {
  * before closing the executor (SHUTDOWN_DRAIN_SECONDS, default 600; 0 = do
  * not wait). Keep the platform's termination grace period above this.
  */
+/** The native sandbox (docs/native-sandbox.md): where sandbox-mode native runs execute. */
+interface NativeSandboxCommonConfig {
+    workerImage: string;
+    /** What a worker dials; undefined = the launcher's default (Docker: the gateway alias; Kubernetes: the Service's ClusterIP). */
+    gatewayUrl?: string;
+    cpus: number;
+    memoryMb: number;
+    /** Docker only: Kubernetes has no per-pod process limit (it is a node-level kubelet setting). */
+    pids: number;
+    /** NATIVE_SANDBOX_MAX_CONCURRENT: at most this many sandbox runs at once (unset = no cap). */
+    maxConcurrent?: number;
+    /** NATIVE_SANDBOX_WARM_POOL_SIZE: idle, isolated workers kept ready for runs to claim (0 = no pool). */
+    warmPoolSize: number;
+    /** NATIVE_SANDBOX_WARM_MAX_AGE_MS: an idle worker older than this is replaced, never claimed. */
+    warmMaxAgeMs: number;
+}
+export interface DockerNativeSandboxConfig extends NativeSandboxCommonConfig {
+    launcher: "docker";
+    /** The container running `wardby native-gateway`, joined to each run's network. */
+    gatewayContainer: string;
+}
+export interface KubernetesNativeSandboxConfig extends NativeSandboxCommonConfig {
+    launcher: "kubernetes";
+    /** Where run pods (and the native gateway) live. */
+    namespace: string;
+    context?: string;
+    /** The native gateway's Service in that namespace. */
+    gatewayService: string;
+    runtimeClassName?: string;
+    /** KUBERNETES_PLATFORM: worker pods are conformed to its admission rules. */
+    platform: KubernetesPlatform;
+    /** NATIVE_SANDBOX_PRIORITY_CLASS, else KUBERNETES_RUN_PRIORITY_CLASS. */
+    priorityClassName?: string;
+    /** How long a worker pod may take to start running (NATIVE_SANDBOX_READY_TIMEOUT_MS). */
+    readyTimeoutMs?: number;
+    /** How long its isolation may take to prove from inside (NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS). */
+    enforcementTimeoutMs?: number;
+}
+/** The native gateway Service (and Deployment) name when NATIVE_GATEWAY_SERVICE is unset. */
+export declare const DEFAULT_NATIVE_GATEWAY_SERVICE = "wardby-native-gateway";
+export type NativeSandboxConfig = DockerNativeSandboxConfig | KubernetesNativeSandboxConfig;
+/** Undefined when NATIVE_SANDBOX_LAUNCHER is unset (sandbox-mode runs then fail closed). Throws on a bad configuration. */
+export declare function loadNativeSandboxConfig(env?: NodeJS.ProcessEnv): NativeSandboxConfig | undefined;
 export declare function loadShutdownDrainSeconds(env?: NodeJS.ProcessEnv): number;
 export declare function loadCodingConcurrencyConfig(env?: NodeJS.ProcessEnv): CodingConcurrencyConfig;
 /** JOB_LAUNCHER=kubernetes: where coding-run pods go, how they reach the in-cluster proxy, and which platform's admission rules apply. */
@@ -200,6 +260,8 @@ export interface AuthConfig {
     signingKey?: string;
     credentialHashKey?: string;
     maxClients?: number;
+    /** Self-hosted mode: mobile sign-in (WARDBY_MOBILE_ENABLED, WARDBY_MOBILE_REDIRECT_URI). */
+    mobile: MobileConfig;
 }
 /** Read auth-adapter config (issuer/JWKS/audience/signing key) from the environment. */
 export declare function loadAuthConfig(env?: NodeJS.ProcessEnv): AuthConfig;

package/dist/config/providers.js

@@ -6,7 +6,45 @@
  * code change. The `assembleProviders` factory (which constructs the concrete
  * adapters) is added once the adapters exist.
  */
-import { KUBERNETES_PLATFORMS } from "../providers/jobs/kubernetes-platform.js";
+import { GVISOR_RUNTIME_CLASS, KUBERNETES_PLATFORMS, platformProfile, } from "../providers/jobs/kubernetes-platform.js";
+import { loadMobileConfig } from "./mobile.js";
+import { testSimulatorBase } from "./test-simulators.js";
+const BLOB_STORE_KINDS = ["local", "gcs", "s3"];
+function loadBlobStoreKind(env) {
+    const value = env.BLOB_STORE?.trim();
+    if (value === undefined || value === "")
+        return undefined;
+    if (!BLOB_STORE_KINDS.includes(value)) {
+        throw new Error(`BLOB_STORE must be one of ${BLOB_STORE_KINDS.join(", ")} (got "${value}").`);
+    }
+    return value;
+}
+/** Blob store settings from the environment; undefined when BLOB_STORE is unset (no blob store). */
+export function loadBlobStoreConfig(env = process.env) {
+    const kind = loadBlobStoreKind(env);
+    if (kind === undefined)
+        return undefined;
+    if (kind === "local") {
+        const localDir = env.BLOB_STORE_LOCAL_DIR?.trim();
+        if (!localDir)
+            throw new Error("BLOB_STORE_LOCAL_DIR is required when BLOB_STORE=local.");
+        return { kind, localDir };
+    }
+    if (kind === "gcs") {
+        const bucket = env.BLOB_STORE_GCS_BUCKET?.trim();
+        if (!bucket)
+            throw new Error("BLOB_STORE_GCS_BUCKET is required when BLOB_STORE=gcs.");
+        return { kind, bucket };
+    }
+    const bucket = env.BLOB_STORE_S3_BUCKET?.trim();
+    if (!bucket)
+        throw new Error("BLOB_STORE_S3_BUCKET is required when BLOB_STORE=s3.");
+    const region = env.BLOB_STORE_S3_REGION?.trim();
+    if (!region)
+        throw new Error("BLOB_STORE_S3_REGION is required when BLOB_STORE=s3.");
+    const endpoint = env.BLOB_STORE_S3_ENDPOINT?.trim();
+    return { kind, bucket, region, ...(endpoint ? { endpoint } : {}) };
+}
 /** Read provider selection from environment variables, defaulting to portable. */
 export function loadProviderConfig(env = process.env) {
     return {
@@ -14,7 +52,7 @@ export function loadProviderConfig(env = process.env) {
         email: env.EMAIL_PROVIDER ?? "smtp",
         secrets: env.SECRET_CIPHER ?? "app-key",
         auth: env.AUTH_PROVIDER ?? "delegating",
-        storage: env.BLOB_STORE ?? "local",
+        storage: loadBlobStoreKind(env),
         executor: env.EXECUTOR ?? "in-process",
         datastore: env.DATASTORE ?? "postgres",
         engine: env.ENGINE ?? "native",
@@ -41,13 +79,21 @@ export function loadGitHubVcsConfig(env = process.env) {
         maxDiffBytes: optionalPositiveInteger(env.VCS_MAX_DIFF_BYTES, "VCS_MAX_DIFF_BYTES"),
     };
 }
-/** GitHub App webhook settings for the code-review host ingress; unset = ingress disabled. */
+/**
+ * GitHub App webhook settings for the code-review host ingress; unset = ingress disabled.
+ * `mentionExplanations` (WARDBY_MENTION_EXPLANATIONS, default true): false = a mention that
+ * starts nothing gets no reply saying why.
+ */
 export function loadGitHubEventConfig(env = process.env) {
     const secret = env.GITHUB_APP_WEBHOOK_SECRET?.trim();
     if (secret !== undefined && secret !== "" && secret.length < 20) {
         throw new Error("GITHUB_APP_WEBHOOK_SECRET must be at least 20 characters.");
     }
-    return { webhookSecret: secret || undefined };
+    const explanations = env.WARDBY_MENTION_EXPLANATIONS?.trim() ?? "";
+    if (explanations !== "" && explanations !== "true" && explanations !== "false") {
+        throw new Error("WARDBY_MENTION_EXPLANATIONS must be true or false.");
+    }
+    return { webhookSecret: secret || undefined, mentionExplanations: explanations !== "false" };
 }
 /**
  * The GitHub App's OAuth client credentials, for linking a principal's GitHub
@@ -113,8 +159,11 @@ export function loadJiraConfig(env = process.env) {
         siteParsed.password) {
         throw new Error("WARDBY_JIRA_SITE_URL must be a bare https origin such as https://your-site.atlassian.net.");
     }
-    const apiBaseUrl = httpsOrigin(base, "WARDBY_JIRA_API_BASE_URL");
-    if (!JIRA_GATEWAY.test(apiBaseUrl)) {
+    // WARDBY_TEST_SIMULATORS (test only): the simulator stands in for the gateway; it refuses
+    // to start over plain http while Jira is configured, so Jira stays https-only.
+    const simulatorJira = testSimulatorBase("jira", env);
+    const apiBaseUrl = simulatorJira ?? httpsOrigin(base, "WARDBY_JIRA_API_BASE_URL");
+    if (!simulatorJira && !JIRA_GATEWAY.test(apiBaseUrl)) {
         throw new Error("WARDBY_JIRA_API_BASE_URL must be https://api.atlassian.com/ex/jira/<cloudId>, the only base a service " +
             "account's API token works against.");
     }
@@ -137,6 +186,32 @@ export function loadJiraConfig(env = process.env) {
         ...(epicLinkField ? { epicLinkField } : {}),
     };
 }
+/** Slack workflow notifications; null when WARDBY_SLACK_BOT_TOKEN is unset (and no other Slack variable is). */
+export function loadSlackConfig(env = process.env) {
+    const token = env.WARDBY_SLACK_BOT_TOKEN?.trim();
+    const base = env.WARDBY_SLACK_API_BASE_URL?.trim();
+    const customizeRaw = env.WARDBY_SLACK_CUSTOMIZE?.trim().toLowerCase();
+    if (!token) {
+        if (base || customizeRaw)
+            throw new Error("WARDBY_SLACK_API_BASE_URL/WARDBY_SLACK_CUSTOMIZE need WARDBY_SLACK_BOT_TOKEN.");
+        return null;
+    }
+    if (!token.startsWith("xoxb-"))
+        throw new Error("WARDBY_SLACK_BOT_TOKEN must be a bot token (xoxb-…).");
+    let apiBaseUrl = "https://slack.com/api";
+    if (base) {
+        const url = new URL(base);
+        if (url.protocol !== "https:")
+            throw new Error("WARDBY_SLACK_API_BASE_URL must be an https URL.");
+        apiBaseUrl = base.replace(/\/+$/, "");
+    }
+    if (customizeRaw && customizeRaw !== "true" && customizeRaw !== "false") {
+        throw new Error("WARDBY_SLACK_CUSTOMIZE must be true or false.");
+    }
+    // WARDBY_TEST_SIMULATORS (test only): the simulator's Slack Web API, whatever the override says.
+    apiBaseUrl = testSimulatorBase("slack", env) ?? apiBaseUrl;
+    return { botToken: token, apiBaseUrl, customize: customizeRaw === "true" };
+}
 function optionalPositiveNumber(value, name, fallback) {
     if (value === undefined)
         return fallback;
@@ -195,11 +270,67 @@ export function loadContainerExecutorConfig(env = process.env) {
         additionalWorkerImages,
     };
 }
-/**
- * How long a shutting-down instance waits for its in-flight native runs
- * before closing the executor (SHUTDOWN_DRAIN_SECONDS, default 600; 0 = do
- * not wait). Keep the platform's termination grace period above this.
- */
+/** The native gateway Service (and Deployment) name when NATIVE_GATEWAY_SERVICE is unset. */
+export const DEFAULT_NATIVE_GATEWAY_SERVICE = "wardby-native-gateway";
+/** Undefined when NATIVE_SANDBOX_LAUNCHER is unset (sandbox-mode runs then fail closed). Throws on a bad configuration. */
+export function loadNativeSandboxConfig(env = process.env) {
+    const launcher = env.NATIVE_SANDBOX_LAUNCHER?.trim();
+    if (!launcher)
+        return undefined;
+    if (launcher !== "docker" && launcher !== "kubernetes") {
+        throw new Error(`NATIVE_SANDBOX_LAUNCHER must be "docker" or "kubernetes" (got "${launcher}").`);
+    }
+    const workerImage = imageVariable(env.NATIVE_SANDBOX_WORKER_IMAGE);
+    if (!workerImage)
+        throw new Error(`NATIVE_SANDBOX_WORKER_IMAGE is required when NATIVE_SANDBOX_LAUNCHER=${launcher}.`);
+    const gatewayUrl = env.NATIVE_GATEWAY_URL?.trim();
+    if (gatewayUrl && !/^https?:\/\/[^\s]+$/.test(gatewayUrl)) {
+        throw new Error(`NATIVE_GATEWAY_URL must be an http(s) URL (got "${gatewayUrl}").`);
+    }
+    const common = {
+        workerImage,
+        ...(gatewayUrl ? { gatewayUrl } : {}),
+        cpus: optionalPositiveNumber(env.NATIVE_SANDBOX_CPUS, "NATIVE_SANDBOX_CPUS", 1),
+        memoryMb: optionalPositiveInteger(env.NATIVE_SANDBOX_MEMORY_MB, "NATIVE_SANDBOX_MEMORY_MB") ?? 512,
+        pids: optionalPositiveInteger(env.NATIVE_SANDBOX_PIDS, "NATIVE_SANDBOX_PIDS") ?? 128,
+        ...optionalField("maxConcurrent", optionalPositiveInteger(env.NATIVE_SANDBOX_MAX_CONCURRENT, "NATIVE_SANDBOX_MAX_CONCURRENT")),
+        warmPoolSize: optionalBoundedInteger(env.NATIVE_SANDBOX_WARM_POOL_SIZE?.trim() || undefined, "NATIVE_SANDBOX_WARM_POOL_SIZE", 0, 50) ?? 0,
+        warmMaxAgeMs: optionalBoundedInteger(env.NATIVE_SANDBOX_WARM_MAX_AGE_MS?.trim() || undefined, "NATIVE_SANDBOX_WARM_MAX_AGE_MS", 60_000, 21_600_000) ?? 1_800_000,
+    };
+    if (launcher === "kubernetes") {
+        // A cluster pulls by registry digest; a local image id means nothing to it.
+        if (!/@sha256:[0-9a-f]{64}$/.test(workerImage)) {
+            throw new Error("NATIVE_SANDBOX_WORKER_IMAGE must be a registry digest (repo@sha256:...) when NATIVE_SANDBOX_LAUNCHER=kubernetes.");
+        }
+        const namespace = env.NATIVE_SANDBOX_NAMESPACE?.trim() || env.KUBERNETES_NAMESPACE?.trim() || "wardby-coding";
+        const runtimeClassName = env.NATIVE_SANDBOX_RUNTIME_CLASS?.trim() || env.KUBERNETES_RUNTIME_CLASS?.trim() || undefined;
+        const context = env.KUBERNETES_CONTEXT?.trim() || undefined;
+        // The platform and run priority class are the coding launcher's settings, validated the same way.
+        const cluster = loadKubernetesJobConfig({
+            KUBERNETES_PLATFORM: env.KUBERNETES_PLATFORM,
+            KUBERNETES_RUN_PRIORITY_CLASS: env.NATIVE_SANDBOX_PRIORITY_CLASS?.trim() || env.KUBERNETES_RUN_PRIORITY_CLASS,
+        });
+        if (platformProfile(cluster.platform).requiresGvisor && runtimeClassName !== GVISOR_RUNTIME_CLASS) {
+            throw new Error(`KUBERNETES_PLATFORM=${cluster.platform} runs native workers only under gVisor: set NATIVE_SANDBOX_RUNTIME_CLASS (or KUBERNETES_RUNTIME_CLASS) to ${GVISOR_RUNTIME_CLASS} (found ${runtimeClassName ?? "unset"}).`);
+        }
+        return {
+            launcher,
+            ...common,
+            namespace,
+            gatewayService: env.NATIVE_GATEWAY_SERVICE?.trim() || DEFAULT_NATIVE_GATEWAY_SERVICE,
+            platform: cluster.platform,
+            ...(context ? { context } : {}),
+            ...(runtimeClassName ? { runtimeClassName } : {}),
+            ...optionalField("priorityClassName", cluster.priorityClassName),
+            ...optionalField("readyTimeoutMs", optionalBoundedInteger(env.NATIVE_SANDBOX_READY_TIMEOUT_MS, "NATIVE_SANDBOX_READY_TIMEOUT_MS", 1_000, 1_800_000)),
+            ...optionalField("enforcementTimeoutMs", optionalBoundedInteger(env.NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS, "NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS", 1_000, 600_000)),
+        };
+    }
+    const gatewayContainer = env.NATIVE_GATEWAY_CONTAINER?.trim();
+    if (!gatewayContainer)
+        throw new Error("NATIVE_GATEWAY_CONTAINER is required when NATIVE_SANDBOX_LAUNCHER=docker.");
+    return { launcher, ...common, gatewayContainer };
+}
 export function loadShutdownDrainSeconds(env = process.env) {
     const value = env.SHUTDOWN_DRAIN_SECONDS?.trim();
     if (!value)
@@ -293,6 +424,7 @@ export function loadAuthConfig(env = process.env) {
         signingKey: env.AUTH_SIGNING_KEY,
         credentialHashKey: env.AUTH_CREDENTIAL_HASH_KEY,
         maxClients: env.AUTH_MAX_CLIENTS ? Number(env.AUTH_MAX_CLIENTS) : undefined,
+        mobile: loadMobileConfig(env),
     };
 }
 /** Read secret-cipher config (the app-key master key) from the environment. */
@@ -309,3 +441,7 @@ export function loadDbosConfig(env = process.env) {
         executorId: env.DBOS_EXECUTOR_ID ?? crypto.randomUUID(),
     };
 }
+/** `{ [key]: value }` when value is set, else nothing: for spreading optional fields under exactOptionalPropertyTypes. */
+function optionalField(key, value) {
+    return (value === undefined ? {} : { [key]: value });
+}

package/dist/config/test-simulators.d.ts

@@ -0,0 +1,82 @@
+/** SHA-256 (hex) of the SPKI DER of the simulator's test GitHub App key (tools/wardby-sim/fixtures). */
+export declare const SIMULATOR_GITHUB_APP_KEY_FINGERPRINT = "dac6c80f55da011bbd2ed5868c61972f778853069f125946964e093e51a7d141";
+/** Where each simulated service is mounted under WARDBY_SIM_BASE_URL. */
+export declare const SIMULATOR_PREFIXES: {
+    readonly "github-api": "/github/api";
+    readonly "github-git": "/github/git";
+    readonly slack: "/slack/api";
+    readonly jira: "/jira";
+    readonly npm: "/npm";
+    readonly pypi: "/pypi";
+    readonly "pypi-files": "/pypi-files";
+    readonly osv: "/osv";
+    /** The scripted model (tools/wardby-sim/src/model): /model/anthropic and /model/openai. */
+    readonly model: "/model";
+};
+export type SimulatedService = keyof typeof SIMULATOR_PREFIXES;
+/** The real upstream host each registry simulator stands in for. */
+export declare const SIMULATED_REGISTRY_HOSTS: Readonly<Record<string, SimulatedService>>;
+export type TestSimulatorsRefusal = "partial" | "flag_value" | "release_image" | "base_url_invalid" | "base_url_credentials" | "base_url_form" | "base_host_not_local" | "node_env_production" | "github_app_key_not_simulator" | "github_oauth_not_simulator" | "slack_token_not_simulator" | "jira_token_not_simulator" | "jira_needs_https" | "public_hostname" | "model_mock_conflict" | "ca_file_invalid" | "bedrock_not_simulated";
+export declare class TestSimulatorsRefused extends Error {
+    readonly reason: TestSimulatorsRefusal;
+    constructor(reason: TestSimulatorsRefusal);
+}
+export interface TestSimulators {
+    /**
+     * WARDBY_SIM_CA_FILE: the simulator's throwaway CA (deploy/kind-coding/sim-ca.sh), trusted by the
+     * git commands wardby runs (GIT_SSL_CAINFO) so its https-only git can reach the simulator's
+     * git server. Node itself trusts it through NODE_EXTRA_CA_CERTS, set by the test harness.
+     */
+    caFile?: string;
+    /** The simulator's origin, without a trailing slash ("http://wardby-sim.wardby-sim.svc:8080"). */
+    origin: string;
+    /** The host, for the startup warning (never carries credentials: those are refused). */
+    host: string;
+    base(service: SimulatedService): string;
+}
+/** Loopback or cluster-local: the only hosts the simulator may live on. */
+export declare function isLocalSimulatorHost(hostname: string): boolean;
+/**
+ * The simulators, or null when the switch is off. Throws TestSimulatorsRefused on any
+ * refusal; with the switch off nothing here reads or changes any other setting.
+ */
+export declare function loadTestSimulators(env?: NodeJS.ProcessEnv): TestSimulators | null;
+/** Extra environment for the git commands wardby runs: the simulator's CA, under the switch only. */
+export declare function simulatorGitEnvironment(env?: NodeJS.ProcessEnv): Record<string, string>;
+/** The simulator's base for one service, or null when the switch is off (throws on a refusal). */
+export declare function testSimulatorBase(service: SimulatedService, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The registry upstream fetch under the switch: each real registry host (npm, PyPI, its file
+ * host, OSV) is rewritten to its simulator, with the same request; every other host is
+ * refused like the pinned fetch refuses it (`blocked`). Only https upstream URLs are taken,
+ * as the pinned fetch takes them.
+ */
+export declare function createSimulatorRegistryFetch(simulators: TestSimulators, blocked: () => Error, fetchImpl?: typeof globalThis.fetch): typeof globalThis.fetch;
+/**
+ * Process start-up: refuses (throws) on any refusal, and with the switch on logs one loud
+ * warning naming the simulator's host only.
+ */
+export declare function startupTestSimulators(component: string, env?: NodeJS.ProcessEnv): TestSimulators | null;
+/** A placeholder the provider SDKs require; createCredentialFreeFetch drops it before sending. */
+export declare const SIMULATOR_PLACEHOLDER_API_KEY = "sim-placeholder-not-a-credential";
+/**
+ * A fetch to the simulator only: drops every header that can carry a credential, and refuses
+ * any URL outside the simulator's origin (`blocked`).
+ */
+export declare function createCredentialFreeFetch(simulators: TestSimulators, blocked: () => Error, fetchImpl?: typeof globalThis.fetch): typeof globalThis.fetch;
+/**
+ * The coding proxy's model upstream under the switch: the OpenAI Responses and Anthropic
+ * Messages endpoints go to the scripted model, with no credential; every other URL is refused.
+ */
+export declare function createSimulatorModelFetch(simulators: TestSimulators, blocked: () => Error, fetchImpl?: typeof globalThis.fetch): typeof globalThis.fetch;
+/**
+ * Client options for a native provider SDK under the switch (null when off): the scripted
+ * model's base for that provider, a placeholder key, and the credential-free fetch.
+ */
+export declare function simulatorModelClientOptions(provider: "anthropic" | "openai", env?: NodeJS.ProcessEnv): {
+    baseURL: string;
+    apiKey: string;
+    fetch: typeof globalThis.fetch;
+} | null;
+/** Bedrock signs with AWS credentials and cannot be pointed at the simulator: refused under the switch. */
+export declare function refuseBedrockUnderTestSimulators(env?: NodeJS.ProcessEnv): void;