@jinn-network/client 0.1.0

package/dist/cli/introspection-context.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared gather for introspection verbs (local SQLite + fleet + RPC).
+ *
+ * When the HTTP API is reachable, merges a healthier `rpc` snapshot from GET /v1/status
+ * into the local gather (short timeout; failures are ignored).
+ */
+import type { GatheredStatusRaw } from '../api/status-build.js';
+export declare function gatherIntrospectionRaw(opts?: {
+    argv?: string[];
+}): Promise<GatheredStatusRaw>;

package/dist/cli/introspection-context.js

@@ -0,0 +1,60 @@
+/**
+ * Shared gather for introspection verbs (local SQLite + fleet + RPC).
+ *
+ * When the HTTP API is reachable, merges a healthier `rpc` snapshot from GET /v1/status
+ * into the local gather (short timeout; failures are ignored).
+ */
+import { gatherGatheredStatusRaw } from '../api/gather-status.js';
+import { loadConfig, getConfigPathFromArgs } from '../config.js';
+import { Store } from '../store/store.js';
+async function tryMergeStatusFromHttp(config, local) {
+    const url = `http://127.0.0.1:${config.apiPort}/v1/status`;
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), 500);
+    try {
+        const res = await fetch(url, { signal: ac.signal });
+        if (!res.ok)
+            return local;
+        const remote = (await res.json());
+        if (remote.rpc?.ok && !local.rpc.ok) {
+            return {
+                ...local,
+                rpc: {
+                    ok: remote.rpc.ok,
+                    chainId: remote.rpc.chainId,
+                    blockNumber: remote.rpc.blockNumber,
+                    ...(remote.rpc.error ? { error: remote.rpc.error } : {}),
+                },
+            };
+        }
+    }
+    catch {
+        /* ignore — local gather is authoritative */
+    }
+    finally {
+        clearTimeout(t);
+    }
+    return local;
+}
+export async function gatherIntrospectionRaw(opts) {
+    const fromVerbFlags = getConfigPathFromArgs(opts?.argv ?? []);
+    const fromProcess = typeof process !== 'undefined' ? getConfigPathFromArgs(process.argv.slice(2)) : undefined;
+    const configPath = fromVerbFlags ?? fromProcess;
+    const config = loadConfig(configPath);
+    const store = new Store(config.dbPath);
+    const status = {
+        earningDir: config.earningDir,
+        rpcUrl: config.rpcUrl,
+        network: config.network,
+        pollIntervalMs: config.pollIntervalMs,
+        masterEthDailyEstimateWei: config.masterEthDailyEstimateWei,
+        rewardClaimIntervalMs: config.rewardClaimIntervalMs,
+        testnetL2DeploymentPath: config.testnetL2DeploymentPath,
+        testnetL2TokenDeploymentPath: config.testnetL2TokenDeploymentPath,
+        testnetMechDeploymentPath: config.testnetMechDeploymentPath,
+        testnetStolasDeploymentPath: config.testnetStolasDeploymentPath,
+    };
+    const local = await gatherGatheredStatusRaw(store, status);
+    return tryMergeStatusFromHttp(config, local);
+}
+//# sourceMappingURL=introspection-context.js.map

package/dist/cli/introspection-context.js.map

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

package/dist/cli/output.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CLI output helpers.
+ *
+ * Operational verbs emit JSON unless `--human` is set (TTY does not change
+ * the default). `stdoutIsTty` is kept for callers/tests; `isJsonMode` only
+ * keys off `human`.
+ *
+ * Spec note: `spec/2026-04-14-client-surface.md` §7.2 still describes a
+ * TTY-based default; implementation and packaged README follow this module.
+ * - NO_COLOR strips ANSI in human mode.
+ */
+export interface JsonModeInput {
+    json: boolean;
+    human: boolean;
+    stdoutIsTty: boolean;
+}
+export declare function isJsonMode(input: JsonModeInput): boolean;
+export declare function formatJson(value: unknown): string;
+export interface HumanModeOpts {
+    noColor: boolean;
+}
+export declare function formatHuman(text: string, opts: HumanModeOpts): string;
+/**
+ * Decide the effective output mode for a verb and write the value.
+ * Production callers pass `process.stdout`; tests inject a writer.
+ */
+export interface EmitOpts {
+    json: boolean;
+    human?: boolean;
+    writer?: {
+        write: (s: string) => boolean;
+    };
+    stdoutIsTty?: boolean;
+    noColor?: boolean;
+}
+export declare function emitResult(value: unknown, humanRender: (v: unknown) => string, opts: EmitOpts): void;

package/dist/cli/output.js

@@ -0,0 +1,35 @@
+/**
+ * CLI output helpers.
+ *
+ * Operational verbs emit JSON unless `--human` is set (TTY does not change
+ * the default). `stdoutIsTty` is kept for callers/tests; `isJsonMode` only
+ * keys off `human`.
+ *
+ * Spec note: `spec/2026-04-14-client-surface.md` §7.2 still describes a
+ * TTY-based default; implementation and packaged README follow this module.
+ * - NO_COLOR strips ANSI in human mode.
+ */
+export function isJsonMode(input) {
+    return !input.human;
+}
+export function formatJson(value) {
+    return JSON.stringify(value) + '\n';
+}
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+export function formatHuman(text, opts) {
+    if (opts.noColor)
+        return text.replace(ANSI_PATTERN, '');
+    return text;
+}
+export function emitResult(value, humanRender, opts) {
+    const writer = opts.writer ?? process.stdout;
+    const stdoutIsTty = opts.stdoutIsTty ?? Boolean(process.stdout.isTTY);
+    const noColor = opts.noColor ?? Boolean(process.env['NO_COLOR']);
+    if (isJsonMode({ json: opts.json, human: Boolean(opts.human), stdoutIsTty })) {
+        writer.write(formatJson(value));
+    }
+    else {
+        writer.write(formatHuman(humanRender(value), { noColor }) + '\n');
+    }
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;AACtC,CAAC;AAED,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAMzC,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAmB;IAC3D,IAAI,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC;AACd,CAAC;AAcD,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,WAAmC,EAAE,IAAc;IAC5F,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;IACjE,IAAI,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;QAC7E,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/dist/cli/password.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI password resolution: JINN_PASSWORD env or --password-fd N (reads once, trims).
+ */
+export declare function parsePasswordFdFromArgv(argv: string[]): number | undefined;
+export declare function readPasswordFromFd(fd: number): string;
+export declare function resolveCliPassword(argv?: string[], env?: NodeJS.ProcessEnv): {
+    ok: true;
+    password: string;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/cli/password.js

@@ -0,0 +1,51 @@
+/**
+ * CLI password resolution: JINN_PASSWORD env or --password-fd N (reads once, trims).
+ */
+import { readFileSync } from 'node:fs';
+export function parsePasswordFdFromArgv(argv) {
+    const idx = argv.indexOf('--password-fd');
+    if (idx === -1)
+        return undefined;
+    const raw = argv[idx + 1];
+    const n = raw !== undefined ? parseInt(raw, 10) : NaN;
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return n;
+}
+export function readPasswordFromFd(fd) {
+    const buf = readFileSync(fd, { encoding: 'utf8' });
+    return buf.replace(/\r?\n$/, '').trim();
+}
+function mergeArgv(argv) {
+    const fromVerb = argv ?? [];
+    const fromProcess = typeof process !== 'undefined' ? process.argv.slice(2) : [];
+    return [...fromVerb, ...fromProcess];
+}
+export function resolveCliPassword(argv, env = process.env) {
+    const merged = mergeArgv(argv);
+    const fd = parsePasswordFdFromArgv(merged);
+    if (fd !== undefined) {
+        try {
+            const password = readPasswordFromFd(fd);
+            if (!password) {
+                return { ok: false, message: 'Password from --password-fd is empty.' };
+            }
+            return { ok: true, password };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                message: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }
+    const p = env['JINN_PASSWORD'];
+    if (!p) {
+        return {
+            ok: false,
+            message: 'Set JINN_PASSWORD or pass --password-fd N with a readable file descriptor.',
+        };
+    }
+    return { ok: true, password: p };
+}
+//# sourceMappingURL=password.js.map

package/dist/cli/password.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password.js","sourceRoot":"","sources":["../../src/cli/password.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,UAAU,uBAAuB,CAAC,IAAc;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACnD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACnD,OAAO,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED,SAAS,SAAS,CAAC,IAAe;IAChC,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,OAAO,CAAC,GAAG,QAAQ,EAAE,GAAG,WAAW,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,IAAe,EACf,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,EAAE,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,uCAAuC,EAAE,CAAC;YACzE,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAChC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;aACpD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,4EAA4E;SACtF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AACnC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Config loader for jinn-client.
+ *
+ * Resolution order (highest priority wins):
+ *   1. Environment variables (JINN_*, BASE_RPC_URL, BASE_SEPOLIA_RPC_URL)
+ *   2. Config file (--config flag or ~/.jinn-client/config.json)
+ *   3. Built-in defaults
+ *
+ * JINN_PASSWORD is always env-only — never written to config files.
+ *
+ * Operator UX: JINN_DEBUG=1 enables full stack traces. JINN_MASTER_ETH_DAILY_WEI
+ * (wei, integer string) tunes master wallet low-ETH runway warnings.
+ * Router claims: JINN_ROUTER_CLAIM_DELIVERY_VERSION=v1|v2 overrides chain default
+ * (mainnet V1, testnet V2) for JinnRouter claimDelivery encoding.
+ */
+import { z } from 'zod';
+export declare const JinnConfigSchema: z.ZodObject<{
+    /**
+     * Network to connect to.
+     * 'testnet' → Base Sepolia (default during Phase 1b; fast epochs, free funds).
+     * 'mainnet' → Base mainnet (flipped on at Phase 2 launch).
+     * Operators should not normally need to set this — the default tracks whatever
+     * phase the protocol is in.
+     */
+    network: z.ZodDefault<z.ZodEnum<["mainnet", "testnet"]>>;
+    /**
+     * Base RPC endpoint.
+     * Defaults to https://mainnet.base.org for 'mainnet' and
+     * https://sepolia.base.org for 'testnet'. Set explicitly to override.
+     */
+    rpcUrl: z.ZodOptional<z.ZodString>;
+    /** Earning state directory */
+    earningDir: z.ZodDefault<z.ZodString>;
+    /** SQLite database path */
+    dbPath: z.ZodDefault<z.ZodString>;
+    /** Chain poll interval in ms */
+    pollIntervalMs: z.ZodDefault<z.ZodNumber>;
+    /**
+     * How often the daemon attempts stOLAS ExternalStakingDistributor.claim for each staked
+     * fleet service (ms). Default 600000 (10 min) — well under typical checkpoint liveness windows
+     * on Base while limiting RPC/gas churn. Set to 0 to disable auto-claim.
+     * Env: JINN_REWARD_CLAIM_INTERVAL_MS
+     */
+    rewardClaimIntervalMs: z.ZodDefault<z.ZodNumber>;
+    /** HTTP API port */
+    apiPort: z.ZodDefault<z.ZodNumber>;
+    /** Path to claude CLI binary */
+    claudePath: z.ZodDefault<z.ZodString>;
+    /** Model for restoration/evaluation agent */
+    claudeModel: z.ZodDefault<z.ZodString>;
+    /** Comma-separated or array of peer URLs */
+    peers: z.ZodDefault<z.ZodUnion<[z.ZodEffects<z.ZodString, string[], string>, z.ZodArray<z.ZodString, "many">]>>;
+    /** The Graph subgraph URL for artifact discovery */
+    subgraphUrl: z.ZodOptional<z.ZodString>;
+    /** This node's public HTTP endpoint (for 8004 registration) */
+    nodeEndpoint: z.ZodOptional<z.ZodString>;
+    /** Desired states to create and restore */
+    desiredStates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        description: string;
+        context?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        description: string;
+        context?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    /** IPFS upload endpoint */
+    ipfsRegistryUrl: z.ZodDefault<z.ZodString>;
+    /** IPFS read endpoint */
+    ipfsGatewayUrl: z.ZodDefault<z.ZodString>;
+    /** Optional Base Sepolia Phase 1a staking deployment artifact path */
+    testnetL2DeploymentPath: z.ZodOptional<z.ZodString>;
+    /** Optional Base Sepolia Phase 1a token deployment artifact path */
+    testnetL2TokenDeploymentPath: z.ZodOptional<z.ZodString>;
+    /** Optional Base Sepolia mech marketplace deployment artifact path */
+    testnetMechDeploymentPath: z.ZodOptional<z.ZodString>;
+    /** Optional Base Sepolia stOLAS deployment artifact path */
+    testnetStolasDeploymentPath: z.ZodOptional<z.ZodString>;
+    /** Staking mode: 'standard' uses stOLAS (no OLAS needed), 'self-bond' uses operator-provided OLAS. */
+    stakingMode: z.ZodDefault<z.ZodEnum<["standard", "self-bond"]>>;
+    /** Number of services to bootstrap and run. */
+    targetServices: z.ZodDefault<z.ZodNumber>;
+    /**
+     * When true, log full error objects and stack traces from bootstrap / main.
+     * Env: JINN_DEBUG=1|true|yes
+     */
+    debug: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Estimated master wallet gas usage per day (wei string), for low-ETH runway warnings.
+     * Default is applied in bootstrap when unset. Env: JINN_MASTER_ETH_DAILY_WEI
+     */
+    masterEthDailyEstimateWei: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    network: "testnet" | "mainnet";
+    earningDir: string;
+    dbPath: string;
+    pollIntervalMs: number;
+    rewardClaimIntervalMs: number;
+    apiPort: number;
+    claudePath: string;
+    claudeModel: string;
+    peers: string[];
+    desiredStates: {
+        id: string;
+        description: string;
+        context?: Record<string, unknown> | undefined;
+    }[];
+    ipfsRegistryUrl: string;
+    ipfsGatewayUrl: string;
+    stakingMode: "standard" | "self-bond";
+    targetServices: number;
+    debug: boolean;
+    rpcUrl?: string | undefined;
+    subgraphUrl?: string | undefined;
+    nodeEndpoint?: string | undefined;
+    testnetL2DeploymentPath?: string | undefined;
+    testnetL2TokenDeploymentPath?: string | undefined;
+    testnetMechDeploymentPath?: string | undefined;
+    testnetStolasDeploymentPath?: string | undefined;
+    masterEthDailyEstimateWei?: string | undefined;
+}, {
+    network?: "testnet" | "mainnet" | undefined;
+    rpcUrl?: string | undefined;
+    earningDir?: string | undefined;
+    dbPath?: string | undefined;
+    pollIntervalMs?: number | undefined;
+    rewardClaimIntervalMs?: number | undefined;
+    apiPort?: number | undefined;
+    claudePath?: string | undefined;
+    claudeModel?: string | undefined;
+    peers?: string | string[] | undefined;
+    subgraphUrl?: string | undefined;
+    nodeEndpoint?: string | undefined;
+    desiredStates?: {
+        id: string;
+        description: string;
+        context?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    ipfsRegistryUrl?: string | undefined;
+    ipfsGatewayUrl?: string | undefined;
+    testnetL2DeploymentPath?: string | undefined;
+    testnetL2TokenDeploymentPath?: string | undefined;
+    testnetMechDeploymentPath?: string | undefined;
+    testnetStolasDeploymentPath?: string | undefined;
+    stakingMode?: "standard" | "self-bond" | undefined;
+    targetServices?: number | undefined;
+    debug?: boolean | undefined;
+    masterEthDailyEstimateWei?: string | undefined;
+}>;
+/** JinnConfig with rpcUrl guaranteed to be resolved (never undefined). */
+export type JinnConfig = Omit<z.infer<typeof JinnConfigSchema>, 'rpcUrl'> & {
+    rpcUrl: string;
+};
+export type ConfigLoadErrorCode = 'config_file_not_found' | 'config_json_invalid' | 'desired_states_file_not_found' | 'desired_states_json_invalid' | 'config_invalid';
+export declare class ConfigLoadError extends Error {
+    readonly code: ConfigLoadErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ConfigLoadErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Load config with resolution: env > config file > defaults.
+ *
+ * @param configPath — explicit config file path (e.g. from --config flag).
+ *   Falls back to ~/.jinn-client/config.json if it exists.
+ */
+export declare function loadConfig(configPath?: string): JinnConfig;
+/**
+ * Get the config file path from --config CLI arg, if provided.
+ */
+export declare function getConfigPathFromArgs(argv?: string[]): string | undefined;

package/dist/config.js

@@ -0,0 +1,252 @@
+/**
+ * Config loader for jinn-client.
+ *
+ * Resolution order (highest priority wins):
+ *   1. Environment variables (JINN_*, BASE_RPC_URL, BASE_SEPOLIA_RPC_URL)
+ *   2. Config file (--config flag or ~/.jinn-client/config.json)
+ *   3. Built-in defaults
+ *
+ * JINN_PASSWORD is always env-only — never written to config files.
+ *
+ * Operator UX: JINN_DEBUG=1 enables full stack traces. JINN_MASTER_ETH_DAILY_WEI
+ * (wei, integer string) tunes master wallet low-ETH runway warnings.
+ * Router claims: JINN_ROUTER_CLAIM_DELIVERY_VERSION=v1|v2 overrides chain default
+ * (mainnet V1, testnet V2) for JinnRouter claimDelivery encoding.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+// ── Schema ──────────────────────────────────────────────────────────────────
+const DesiredStateSchema = z.object({
+    id: z.string(),
+    description: z.string().min(1),
+    context: z.record(z.unknown()).optional(),
+});
+export const JinnConfigSchema = z.object({
+    /**
+     * Network to connect to.
+     * 'testnet' → Base Sepolia (default during Phase 1b; fast epochs, free funds).
+     * 'mainnet' → Base mainnet (flipped on at Phase 2 launch).
+     * Operators should not normally need to set this — the default tracks whatever
+     * phase the protocol is in.
+     */
+    network: z.enum(['mainnet', 'testnet']).default('testnet'),
+    /**
+     * Base RPC endpoint.
+     * Defaults to https://mainnet.base.org for 'mainnet' and
+     * https://sepolia.base.org for 'testnet'. Set explicitly to override.
+     */
+    rpcUrl: z.string().optional(),
+    /** Earning state directory */
+    earningDir: z.string().default(join(homedir(), '.jinn-client', 'earning')),
+    /** SQLite database path */
+    dbPath: z.string().default(join(homedir(), '.jinn-client', 'jinn.db')),
+    /** Chain poll interval in ms */
+    pollIntervalMs: z.number().int().positive().default(5000),
+    /**
+     * How often the daemon attempts stOLAS ExternalStakingDistributor.claim for each staked
+     * fleet service (ms). Default 600000 (10 min) — well under typical checkpoint liveness windows
+     * on Base while limiting RPC/gas churn. Set to 0 to disable auto-claim.
+     * Env: JINN_REWARD_CLAIM_INTERVAL_MS
+     */
+    rewardClaimIntervalMs: z.number().int().min(0).default(600_000),
+    /** HTTP API port */
+    apiPort: z.number().int().positive().default(7331),
+    /** Path to claude CLI binary */
+    claudePath: z.string().default('claude'),
+    /** Model for restoration/evaluation agent */
+    claudeModel: z.string().default('claude-haiku-4-5-20251001'),
+    /** Comma-separated or array of peer URLs */
+    peers: z.union([
+        z.string().transform(s => s.split(',').filter(Boolean)),
+        z.array(z.string()),
+    ]).default([]),
+    /** The Graph subgraph URL for artifact discovery */
+    subgraphUrl: z.string().optional(),
+    /** This node's public HTTP endpoint (for 8004 registration) */
+    nodeEndpoint: z.string().optional(),
+    /** Desired states to create and restore */
+    desiredStates: z.array(DesiredStateSchema).default([
+        {
+            id: 'health-check',
+            description: 'The service is running and participating in the Jinn protocol loop.',
+        },
+    ]),
+    /** IPFS upload endpoint */
+    ipfsRegistryUrl: z.string().default('https://registry.autonolas.tech'),
+    /** IPFS read endpoint */
+    ipfsGatewayUrl: z.string().default('https://gateway.autonolas.tech'),
+    /** Optional Base Sepolia Phase 1a staking deployment artifact path */
+    testnetL2DeploymentPath: z.string().optional(),
+    /** Optional Base Sepolia Phase 1a token deployment artifact path */
+    testnetL2TokenDeploymentPath: z.string().optional(),
+    /** Optional Base Sepolia mech marketplace deployment artifact path */
+    testnetMechDeploymentPath: z.string().optional(),
+    /** Optional Base Sepolia stOLAS deployment artifact path */
+    testnetStolasDeploymentPath: z.string().optional(),
+    /** Staking mode: 'standard' uses stOLAS (no OLAS needed), 'self-bond' uses operator-provided OLAS. */
+    stakingMode: z.enum(['standard', 'self-bond']).default('standard'),
+    /** Number of services to bootstrap and run. */
+    targetServices: z.number().int().positive().default(1),
+    /**
+     * When true, log full error objects and stack traces from bootstrap / main.
+     * Env: JINN_DEBUG=1|true|yes
+     */
+    debug: z.boolean().default(false),
+    /**
+     * Estimated master wallet gas usage per day (wei string), for low-ETH runway warnings.
+     * Default is applied in bootstrap when unset. Env: JINN_MASTER_ETH_DAILY_WEI
+     */
+    masterEthDailyEstimateWei: z
+        .string()
+        .regex(/^\d+$/, 'must be a non-negative integer string')
+        .optional(),
+});
+// ── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_DIR = join(homedir(), '.jinn-client');
+const DEFAULT_CONFIG_PATH = join(DEFAULT_DIR, 'config.json');
+export class ConfigLoadError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'ConfigLoadError';
+        this.code = code;
+        this.details = details;
+    }
+}
+// ── Loader ──────────────────────────────────────────────────────────────────
+/**
+ * Load config with resolution: env > config file > defaults.
+ *
+ * @param configPath — explicit config file path (e.g. from --config flag).
+ *   Falls back to ~/.jinn-client/config.json if it exists.
+ */
+export function loadConfig(configPath) {
+    // 1. Load config file (if any)
+    const filePath = configPath ?? DEFAULT_CONFIG_PATH;
+    let fileValues = {};
+    if (existsSync(filePath)) {
+        const raw = readFileSync(filePath, 'utf-8');
+        try {
+            fileValues = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new ConfigLoadError('config_json_invalid', `Invalid JSON in config file: ${filePath}`, {
+                path: filePath,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        console.error(`[config] Loaded ${filePath}`);
+    }
+    else if (configPath) {
+        throw new ConfigLoadError('config_file_not_found', `Config file not found: ${configPath}`, {
+            path: configPath,
+        });
+    }
+    // 2. Apply env var overrides
+    const env = process.env;
+    const merged = { ...fileValues };
+    if (env['JINN_NETWORK'])
+        merged.network = env['JINN_NETWORK'];
+    if (env['JINN_EARNING_DIR'])
+        merged.earningDir = env['JINN_EARNING_DIR'];
+    if (env['JINN_DB_PATH'])
+        merged.dbPath = env['JINN_DB_PATH'];
+    if (env['JINN_POLL_INTERVAL_MS'])
+        merged.pollIntervalMs = parseInt(env['JINN_POLL_INTERVAL_MS'], 10);
+    if (env['JINN_REWARD_CLAIM_INTERVAL_MS'] !== undefined) {
+        merged.rewardClaimIntervalMs = parseInt(env['JINN_REWARD_CLAIM_INTERVAL_MS'], 10);
+    }
+    if (env['JINN_API_PORT'])
+        merged.apiPort = parseInt(env['JINN_API_PORT'], 10);
+    if (env['JINN_CLAUDE_PATH'])
+        merged.claudePath = env['JINN_CLAUDE_PATH'];
+    if (env['JINN_CLAUDE_MODEL'])
+        merged.claudeModel = env['JINN_CLAUDE_MODEL'];
+    if (env['JINN_PEERS'])
+        merged.peers = env['JINN_PEERS'];
+    if (env['JINN_SUBGRAPH_URL'])
+        merged.subgraphUrl = env['JINN_SUBGRAPH_URL'];
+    if (env['JINN_NODE_ENDPOINT'])
+        merged.nodeEndpoint = env['JINN_NODE_ENDPOINT'];
+    if (env['JINN_IPFS_REGISTRY_URL'])
+        merged.ipfsRegistryUrl = env['JINN_IPFS_REGISTRY_URL'];
+    if (env['JINN_IPFS_GATEWAY_URL'])
+        merged.ipfsGatewayUrl = env['JINN_IPFS_GATEWAY_URL'];
+    if (env['JINN_TESTNET_L2_DEPLOYMENT'])
+        merged.testnetL2DeploymentPath = env['JINN_TESTNET_L2_DEPLOYMENT'];
+    if (env['JINN_TESTNET_TOKEN_DEPLOYMENT'])
+        merged.testnetL2TokenDeploymentPath = env['JINN_TESTNET_TOKEN_DEPLOYMENT'];
+    if (env['JINN_TESTNET_MECH_DEPLOYMENT'])
+        merged.testnetMechDeploymentPath = env['JINN_TESTNET_MECH_DEPLOYMENT'];
+    if (env['JINN_STAKING_MODE'])
+        merged.stakingMode = env['JINN_STAKING_MODE'];
+    if (env['JINN_TARGET_SERVICES'])
+        merged.targetServices = parseInt(env['JINN_TARGET_SERVICES'], 10);
+    if (env['JINN_DEBUG'] !== undefined) {
+        const v = env['JINN_DEBUG'].trim().toLowerCase();
+        merged.debug = v === '1' || v === 'true' || v === 'yes';
+    }
+    if (env['JINN_MASTER_ETH_DAILY_WEI']) {
+        merged.masterEthDailyEstimateWei = env['JINN_MASTER_ETH_DAILY_WEI'].trim();
+    }
+    const resolvedNetwork = merged.network === 'testnet' ? 'testnet' : 'mainnet';
+    // Keep the legacy BASE_RPC_URL override for Base mainnet only. Testnet must
+    // not silently inherit a mainnet RPC from client/.env during bootstrap.
+    if (env['JINN_RPC_URL']) {
+        merged.rpcUrl = env['JINN_RPC_URL'];
+    }
+    else if (resolvedNetwork === 'testnet') {
+        if (env['BASE_SEPOLIA_RPC_URL']) {
+            merged.rpcUrl = env['BASE_SEPOLIA_RPC_URL'];
+        }
+    }
+    else if (env['BASE_RPC_URL']) {
+        merged.rpcUrl = env['BASE_RPC_URL'];
+    }
+    // desiredStates from env points to a JSON file
+    if (env['JINN_DESIRED_STATES']) {
+        const statesPath = env['JINN_DESIRED_STATES'];
+        if (!existsSync(statesPath)) {
+            throw new ConfigLoadError('desired_states_file_not_found', `JINN_DESIRED_STATES file not found: ${statesPath}`, { path: statesPath });
+        }
+        try {
+            merged.desiredStates = JSON.parse(readFileSync(statesPath, 'utf-8'));
+        }
+        catch (error) {
+            throw new ConfigLoadError('desired_states_json_invalid', `Invalid JSON in JINN_DESIRED_STATES file: ${statesPath}`, {
+                path: statesPath,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // 3. Validate
+    const result = JinnConfigSchema.safeParse(merged);
+    if (!result.success) {
+        throw new ConfigLoadError('config_invalid', 'Invalid config.', {
+            issues: result.error.issues.map((issue) => ({
+                path: issue.path.join('.'),
+                message: issue.message,
+            })),
+        });
+    }
+    // 4. Resolve rpcUrl default based on network (if not explicitly set)
+    const parsed = result.data;
+    const defaultRpcUrl = parsed.network === 'testnet'
+        ? 'https://sepolia.base.org'
+        : 'https://mainnet.base.org';
+    return {
+        ...parsed,
+        rpcUrl: parsed.rpcUrl ?? defaultRpcUrl,
+    };
+}
+/**
+ * Get the config file path from --config CLI arg, if provided.
+ */
+export function getConfigPathFromArgs(argv = process.argv) {
+    const idx = argv.indexOf('--config');
+    return idx >= 0 && argv[idx + 1] ? argv[idx + 1] : undefined;
+}
+//# sourceMappingURL=config.js.map