@augustdigital/config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 August Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# `@augustdigital/config`
+
+Private workspace package. Shared config, keystore, session, profiles,
+and SDK factory used by [`@augustdigital/cli`](../cli) and
+[`@augustdigital/mcp`](../mcp). Also owns the Zod schemas that define
+the stable JSON envelope they emit.
+
+Not published to npm.
+
+## Surface
+
+```ts
+import {
+  // config + paths
+  loadConfig,
+  saveConfig,
+  configFile,
+  activeConfigDir,
+  // profiles
+  saveProfile,
+  loadProfile,
+  listProfiles,
+  deleteProfile,
+  // keystore + session
+  Keystore,
+  readSession,
+  writeSession,
+  clearSession,
+  sessionActive,
+  // resolvers (precedence: flag → env → session → profile → config)
+  getApiKey,
+  getRpcUrl,
+  getDefaultChainId,
+  // SDK factory
+  createSDK,
+  // typed errors
+  AugustConfigError,
+  // output schemas
+  schemas,
+} from '@augustdigital/config';
+```
+
+## On-disk layout
+
+```
+~/.augustdigital/
+├── config.json    # default chain, RPCs, profile, telemetry
+├── keystore.json  # AES-256-GCM; holds named secrets (e.g. `august`)
+├── .session       # mode 0600; decrypted API key + expiry
+└── profiles/      # named overlays for chain + RPC sets
+```
+
+Override the root with `AUGUST_CONFIG_DIR`.

package/lib/config.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+declare const ConfigSchemaV1: z.ZodObject<{
+    schemaVersion: z.ZodDefault<z.ZodLiteral<1>>;
+    appName: z.ZodDefault<z.ZodString>;
+    defaultProfile: z.ZodDefault<z.ZodString>;
+    defaultChainId: z.ZodDefault<z.ZodNumber>;
+    rpcs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    telemetry: z.ZodDefault<z.ZodBoolean>;
+    auth: z.ZodDefault<z.ZodObject<{
+        sessionTtlSec: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        sessionTtlSec?: number;
+    }, {
+        sessionTtlSec?: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion?: 1;
+    appName?: string;
+    defaultProfile?: string;
+    defaultChainId?: number;
+    rpcs?: Record<string, string>;
+    telemetry?: boolean;
+    auth?: {
+        sessionTtlSec?: number;
+    };
+}, {
+    schemaVersion?: 1;
+    appName?: string;
+    defaultProfile?: string;
+    defaultChainId?: number;
+    rpcs?: Record<string, string>;
+    telemetry?: boolean;
+    auth?: {
+        sessionTtlSec?: number;
+    };
+}>;
+export type Config = z.infer<typeof ConfigSchemaV1>;
+export type PartialConfig = z.input<typeof ConfigSchemaV1>;
+export declare function loadConfig(path?: string): Config;
+export declare function saveConfig(patch: PartialConfig, path?: string): Config;
+export declare function configExists(path?: string): boolean;
+export declare function defaultConfig(): Config;
+export declare function activeConfigDir(): string;
+export {};

package/lib/config.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.configExists = configExists;
+exports.defaultConfig = defaultConfig;
+exports.activeConfigDir = activeConfigDir;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+const paths_1 = require("./paths");
+const RpcMapSchema = zod_1.z.record(zod_1.z.string().min(1), zod_1.z.string().url());
+const ConfigSchemaV1 = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1).default(1),
+    appName: zod_1.z.string().min(3).max(64).default('august-cli'),
+    defaultProfile: zod_1.z.string().min(1).default('default'),
+    defaultChainId: zod_1.z.number().int().default(1),
+    rpcs: RpcMapSchema.default({}),
+    telemetry: zod_1.z.boolean().default(false),
+    auth: zod_1.z
+        .object({
+        sessionTtlSec: zod_1.z.number().int().positive().default(3600),
+    })
+        .default({ sessionTtlSec: 3600 }),
+});
+const DEFAULT_CONFIG = ConfigSchemaV1.parse({});
+function ensureFileMode(path, mode) {
+    try {
+        (0, node_fs_1.chmodSync)(path, mode);
+    }
+    catch {
+    }
+}
+function loadConfig(path = (0, paths_1.configFile)()) {
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    let raw;
+    try {
+        raw = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch (err) {
+        throw new errors_1.AugustConfigError('CONFIG_INVALID', `Config file at ${path} is not valid JSON: ${err.message}`, 'Restore from backup or re-run `august init`.');
+    }
+    const result = ConfigSchemaV1.safeParse(raw);
+    if (!result.success) {
+        throw new errors_1.AugustConfigError('CONFIG_INVALID', `Config file at ${path} failed validation: ${result.error.message}`, 'Edit the file to match the schema, or re-run `august init`.');
+    }
+    return result.data;
+}
+function saveConfig(patch, path = (0, paths_1.configFile)()) {
+    const existing = (0, node_fs_1.existsSync)(path) ? loadConfig(path) : { ...DEFAULT_CONFIG };
+    const merged = ConfigSchemaV1.parse({
+        ...existing,
+        ...patch,
+        rpcs: { ...existing.rpcs, ...(patch.rpcs ?? {}) },
+        auth: { ...existing.auth, ...(patch.auth ?? {}) },
+    });
+    const dir = (0, node_path_1.dirname)(path);
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    }
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(merged, null, 2), {
+        encoding: 'utf8',
+        mode: 0o644,
+    });
+    ensureFileMode(dir, 0o700);
+    return merged;
+}
+function configExists(path = (0, paths_1.configFile)()) {
+    return (0, node_fs_1.existsSync)(path);
+}
+function defaultConfig() {
+    return { ...DEFAULT_CONFIG };
+}
+function activeConfigDir() {
+    return (0, paths_1.configDir)();
+}
+//# sourceMappingURL=config.js.map

package/lib/errors.d.ts

@@ -0,0 +1,6 @@
+export type AugustConfigErrorCode = 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'KEYSTORE_NOT_FOUND' | 'KEYSTORE_INVALID' | 'KEYSTORE_WRONG_PASSPHRASE' | 'KEY_NOT_FOUND' | 'SESSION_NOT_FOUND' | 'SESSION_EXPIRED' | 'SESSION_INVALID' | 'API_KEY_MISSING' | 'RPC_MISSING' | 'PROFILE_NOT_FOUND' | 'PROFILE_INVALID' | 'VAULT_NAME_NOT_FOUND' | 'VAULT_NAME_AMBIGUOUS' | 'VAULT_CHAIN_UNKNOWN';
+export declare class AugustConfigError extends Error {
+    readonly code: AugustConfigErrorCode;
+    readonly remediation?: string;
+    constructor(code: AugustConfigErrorCode, message: string, remediation?: string);
+}

package/lib/errors.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustConfigError = void 0;
+class AugustConfigError extends Error {
+    constructor(code, message, remediation) {
+        super(message);
+        this.name = 'AugustConfigError';
+        this.code = code;
+        this.remediation = remediation;
+    }
+}
+exports.AugustConfigError = AugustConfigError;
+//# sourceMappingURL=errors.js.map

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+export * from './paths';
+export * from './errors';
+export * from './config';
+export * from './profile';
+export * from './keystore';
+export * from './session';
+export * from './precedence';
+export * from './sdk';
+export * as schemas from './schemas';

package/lib/index.js

@@ -0,0 +1,49 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemas = void 0;
+__exportStar(require("./paths"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./profile"), exports);
+__exportStar(require("./keystore"), exports);
+__exportStar(require("./session"), exports);
+__exportStar(require("./precedence"), exports);
+__exportStar(require("./sdk"), exports);
+exports.schemas = __importStar(require("./schemas"));
+//# sourceMappingURL=index.js.map

package/lib/keystore.d.ts

@@ -0,0 +1,37 @@
+export interface KeystoreFile {
+    version: 1;
+    id: string;
+    crypto: {
+        cipher: 'aes-256-gcm';
+        ciphertext: string;
+        iv: string;
+        tag: string;
+        kdf: 'scrypt';
+        kdfparams: {
+            N: number;
+            r: number;
+            p: number;
+            dklen: number;
+            salt: string;
+        };
+    };
+}
+export type KeystoreContents = Record<string, string>;
+export declare class Keystore {
+    private contents;
+    private passphrase;
+    private readonly path;
+    private constructor();
+    static create(passphrase: string, path?: string): Promise<Keystore>;
+    static unlock(passphrase: string, path?: string): Promise<Keystore>;
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    set(name: string, value: string): void;
+    delete(name: string): void;
+    names(): string[];
+    rotate(newPassphrase: string): Promise<void>;
+    save(): Promise<void>;
+    static safeEqual(a: string, b: string): boolean;
+}
+export declare function keystoreExists(path?: string): boolean;
+export declare function ensureConfigDir(): void;

package/lib/keystore.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Keystore = void 0;
+exports.keystoreExists = keystoreExists;
+exports.ensureConfigDir = ensureConfigDir;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const errors_1 = require("./errors");
+const paths_1 = require("./paths");
+const scryptAsync = (0, node_util_1.promisify)(node_crypto_1.scrypt);
+const SCRYPT_PARAMS = {
+    N: 1 << 17,
+    r: 8,
+    p: 1,
+    maxmem: 256 * 1024 * 1024,
+};
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const SALT_BYTES = 16;
+async function deriveKey(passphrase, salt) {
+    return scryptAsync(passphrase, salt, KEY_BYTES, SCRYPT_PARAMS);
+}
+function encodePayload(contents) {
+    return Buffer.from(JSON.stringify(contents), 'utf8');
+}
+function decodePayload(plaintext) {
+    let parsed;
+    try {
+        parsed = JSON.parse(plaintext.toString('utf8'));
+    }
+    catch {
+        throw new errors_1.AugustConfigError('KEYSTORE_INVALID', 'Keystore payload is not valid JSON after decryption.', 'The keystore file may be corrupted. Restore from backup or re-run `august init`.');
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed) ||
+        Object.values(parsed).some((v) => typeof v !== 'string')) {
+        throw new errors_1.AugustConfigError('KEYSTORE_INVALID', 'Keystore payload has unexpected shape.', 'The keystore file may be corrupted. Restore from backup or re-run `august init`.');
+    }
+    return parsed;
+}
+function ensureFileMode(path, mode) {
+    try {
+        (0, node_fs_1.chmodSync)(path, mode);
+    }
+    catch {
+    }
+}
+class Keystore {
+    constructor(contents, passphrase, path) {
+        this.contents = contents;
+        this.passphrase = passphrase;
+        this.path = path;
+    }
+    static async create(passphrase, path = (0, paths_1.keystoreFile)()) {
+        return new Keystore({}, passphrase, path);
+    }
+    static async unlock(passphrase, path = (0, paths_1.keystoreFile)()) {
+        if (!(0, node_fs_1.existsSync)(path)) {
+            throw new errors_1.AugustConfigError('KEYSTORE_NOT_FOUND', `No keystore found at ${path}.`, 'Run `august init` to create one.');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        }
+        catch {
+            throw new errors_1.AugustConfigError('KEYSTORE_INVALID', `Keystore at ${path} is not valid JSON.`, 'Restore from backup or re-run `august init`.');
+        }
+        if (parsed?.version !== 1 ||
+            parsed.crypto?.cipher !== 'aes-256-gcm' ||
+            parsed.crypto.kdf !== 'scrypt') {
+            throw new errors_1.AugustConfigError('KEYSTORE_INVALID', `Keystore at ${path} has unsupported version or crypto fields.`, 'Re-run `august init` to recreate it with the current format.');
+        }
+        const { ciphertext, iv, tag, kdfparams } = parsed.crypto;
+        const salt = Buffer.from(kdfparams.salt, 'hex');
+        const key = await scryptAsync(passphrase, salt, kdfparams.dklen, {
+            N: kdfparams.N,
+            r: kdfparams.r,
+            p: kdfparams.p,
+            maxmem: SCRYPT_PARAMS.maxmem,
+        });
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, Buffer.from(iv, 'hex'));
+        decipher.setAuthTag(Buffer.from(tag, 'hex'));
+        let plaintext;
+        try {
+            plaintext = Buffer.concat([
+                decipher.update(Buffer.from(ciphertext, 'hex')),
+                decipher.final(),
+            ]);
+        }
+        catch {
+            throw new errors_1.AugustConfigError('KEYSTORE_WRONG_PASSPHRASE', 'Failed to decrypt keystore — passphrase is incorrect or file is corrupted.', 'Re-enter your passphrase, or run `august init --force` to recreate the keystore.');
+        }
+        const contents = decodePayload(plaintext);
+        return new Keystore(contents, passphrase, path);
+    }
+    get(name) {
+        return this.contents[name];
+    }
+    has(name) {
+        return Object.prototype.hasOwnProperty.call(this.contents, name);
+    }
+    set(name, value) {
+        this.contents[name] = value;
+    }
+    delete(name) {
+        delete this.contents[name];
+    }
+    names() {
+        return Object.keys(this.contents);
+    }
+    async rotate(newPassphrase) {
+        this.passphrase = newPassphrase;
+        await this.save();
+    }
+    async save() {
+        const salt = (0, node_crypto_1.randomBytes)(SALT_BYTES);
+        const iv = (0, node_crypto_1.randomBytes)(IV_BYTES);
+        const key = await deriveKey(this.passphrase, salt);
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+        const ciphertext = Buffer.concat([
+            cipher.update(encodePayload(this.contents)),
+            cipher.final(),
+        ]);
+        const tag = cipher.getAuthTag();
+        const file = {
+            version: 1,
+            id: (0, node_crypto_1.randomBytes)(16).toString('hex'),
+            crypto: {
+                cipher: 'aes-256-gcm',
+                ciphertext: ciphertext.toString('hex'),
+                iv: iv.toString('hex'),
+                tag: tag.toString('hex'),
+                kdf: 'scrypt',
+                kdfparams: {
+                    N: SCRYPT_PARAMS.N,
+                    r: SCRYPT_PARAMS.r,
+                    p: SCRYPT_PARAMS.p,
+                    dklen: KEY_BYTES,
+                    salt: salt.toString('hex'),
+                },
+            },
+        };
+        const dir = (0, node_path_1.dirname)(this.path);
+        if (!(0, node_fs_1.existsSync)(dir)) {
+            (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+        }
+        (0, node_fs_1.writeFileSync)(this.path, JSON.stringify(file, null, 2), {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        ensureFileMode(this.path, 0o600);
+        ensureFileMode(dir, 0o700);
+    }
+    static safeEqual(a, b) {
+        const ab = Buffer.from(a, 'utf8');
+        const bb = Buffer.from(b, 'utf8');
+        if (ab.length !== bb.length)
+            return false;
+        return (0, node_crypto_1.timingSafeEqual)(ab, bb);
+    }
+}
+exports.Keystore = Keystore;
+function keystoreExists(path = (0, paths_1.keystoreFile)()) {
+    return (0, node_fs_1.existsSync)(path);
+}
+function ensureConfigDir() {
+    const dir = (0, paths_1.configDir)();
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    }
+    ensureFileMode(dir, 0o700);
+}
+//# sourceMappingURL=keystore.js.map

package/lib/paths.d.ts

@@ -0,0 +1,6 @@
+export declare function configDir(): string;
+export declare function configFile(): string;
+export declare function keystoreFile(): string;
+export declare function sessionFile(): string;
+export declare function profilesDir(): string;
+export declare function profileFile(name: string): string;

package/lib/paths.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configDir = configDir;
+exports.configFile = configFile;
+exports.keystoreFile = keystoreFile;
+exports.sessionFile = sessionFile;
+exports.profilesDir = profilesDir;
+exports.profileFile = profileFile;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const DEFAULT_DIR_NAME = '.augustdigital';
+function configDir() {
+    const override = process.env.AUGUST_CONFIG_DIR?.trim();
+    if (override)
+        return (0, node_path_1.resolve)(override);
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), DEFAULT_DIR_NAME);
+}
+function configFile() {
+    return (0, node_path_1.join)(configDir(), 'config.json');
+}
+function keystoreFile() {
+    return (0, node_path_1.join)(configDir(), 'keystore.json');
+}
+function sessionFile() {
+    return (0, node_path_1.join)(configDir(), '.session');
+}
+function profilesDir() {
+    return (0, node_path_1.join)(configDir(), 'profiles');
+}
+function profileFile(name) {
+    return (0, node_path_1.join)(profilesDir(), `${name}.json`);
+}
+//# sourceMappingURL=paths.js.map

package/lib/precedence.d.ts

@@ -0,0 +1,11 @@
+import { Config } from './config';
+export interface ResolveOptions {
+    config?: Config;
+    profileName?: string;
+    cliApiKey?: string;
+    cliRpcUrl?: string;
+    cliRpcChainId?: number;
+}
+export declare function getApiKey(opts?: ResolveOptions): string;
+export declare function getRpcUrl(chainId: number, opts?: ResolveOptions): string;
+export declare function getDefaultChainId(opts?: ResolveOptions): number;

package/lib/precedence.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getApiKey = getApiKey;
+exports.getRpcUrl = getRpcUrl;
+exports.getDefaultChainId = getDefaultChainId;
+const sdk_1 = require("@augustdigital/sdk");
+const errors_1 = require("./errors");
+const config_1 = require("./config");
+const profile_1 = require("./profile");
+const session_1 = require("./session");
+function resolveProfile(config, profileName) {
+    const target = profileName ?? process.env.AUGUST_PROFILE ?? config.defaultProfile;
+    if (!target)
+        return null;
+    try {
+        return (0, profile_1.loadProfile)(target);
+    }
+    catch {
+        return null;
+    }
+}
+function getApiKey(opts = {}) {
+    if (opts.cliApiKey && opts.cliApiKey.length > 0)
+        return opts.cliApiKey;
+    const envKey = process.env.AUGUST_API_KEY?.trim();
+    if (envKey)
+        return envKey;
+    try {
+        const session = (0, session_1.readSession)();
+        if (session?.apiKey)
+            return session.apiKey;
+    }
+    catch {
+    }
+    throw new errors_1.AugustConfigError('API_KEY_MISSING', 'No August API key is available.', 'Run `august login` to unlock your keystore, or set AUGUST_API_KEY.');
+}
+function getRpcUrl(chainId, opts = {}) {
+    if (opts.cliRpcUrl &&
+        (opts.cliRpcChainId === undefined || opts.cliRpcChainId === chainId)) {
+        return opts.cliRpcUrl;
+    }
+    const envUrl = process.env[`AUGUST_RPC_${chainId}`]?.trim();
+    if (envUrl)
+        return envUrl;
+    const config = opts.config ?? (0, config_1.loadConfig)();
+    const profile = resolveProfile(config, opts.profileName);
+    const profileRpc = profile?.rpcs?.[String(chainId)];
+    if (profileRpc)
+        return profileRpc;
+    const configRpc = config.rpcs?.[String(chainId)];
+    if (configRpc)
+        return configRpc;
+    const [publicFallback] = (0, sdk_1.getFallbackRpcUrls)(chainId);
+    if (publicFallback)
+        return publicFallback;
+    throw new errors_1.AugustConfigError('RPC_MISSING', `No RPC URL configured for chain ${chainId} and no public fallback is available.`, `Set \`AUGUST_RPC_${chainId}=<url>\`, run \`august config set rpcs.${chainId} <url>\`, or pass \`--rpc <url> --chain ${chainId}\`.`);
+}
+function getDefaultChainId(opts = {}) {
+    if (opts.cliRpcChainId !== undefined)
+        return opts.cliRpcChainId;
+    const envChain = process.env.AUGUST_CHAIN_ID?.trim();
+    if (envChain && Number.isFinite(Number(envChain))) {
+        return Number(envChain);
+    }
+    const config = opts.config ?? (0, config_1.loadConfig)();
+    const profile = resolveProfile(config, opts.profileName);
+    return profile?.defaultChainId ?? config.defaultChainId;
+}
+//# sourceMappingURL=precedence.js.map

package/lib/profile.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+declare const ProfileSchema: z.ZodObject<{
+    schemaVersion: z.ZodDefault<z.ZodLiteral<1>>;
+    name: z.ZodString;
+    defaultChainId: z.ZodOptional<z.ZodNumber>;
+    rpcs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion?: 1;
+    defaultChainId?: number;
+    rpcs?: Record<string, string>;
+    name?: string;
+    notes?: string;
+}, {
+    schemaVersion?: 1;
+    defaultChainId?: number;
+    rpcs?: Record<string, string>;
+    name?: string;
+    notes?: string;
+}>;
+export type Profile = z.infer<typeof ProfileSchema>;
+export declare function saveProfile(profile: Profile): Profile;
+export declare function loadProfile(name: string): Profile;
+export declare function listProfiles(): string[];
+export declare function deleteProfile(name: string): void;
+export {};