@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/lib/export.js

@@ -1,269 +0,0 @@
-/**
- * `agents export` — copy an ISOLATED install's config back out to the user's real
- * `~/.<agent>`, so they can keep their settings and delete agents-cli entirely.
- *
- * Isolation is currently a one-way door: `agents add <agent>@<v> --isolated` builds a
- * self-contained home under the version dir, and nothing ever brings that work back.
- * Reversibility is what makes a sandbox safe to try.
- *
- * Three modes, because "export" means different things depending on which config you
- * consider authoritative:
- *
- *   merge (default) — additive. Copy only paths the user doesn't already have. A
- *                     collision is NOT silently skipped: the incoming file is written
- *                     beside theirs as `<name>.from-agents-cli` so they can diff and
- *                     take the parts they want. Nothing of theirs is ever modified.
- *   replace         — the isolated config becomes `~/.<agent>`; theirs moves to
- *                     `backups/<agent>/<ts>`. For when you've been living in the
- *                     sandbox and want to promote it wholesale.
- *   staged          — write the whole tree to `~/.<agent>/.agents-export-<ts>/` and
- *                     activate nothing. For inspecting first.
- *
- * Every mode leaves a receipt at `~/.<agent>/.agents-cli-export.json` recording what
- * came from the export. That is what makes provenance answerable ("which of these
- * files are mine?") and the whole operation reversible.
- *
- * Deliberately NOT implemented: key-level merging of file *contents*. The TOML
- * library here does not preserve comments across parse+stringify, so auto-merging a
- * `config.toml` would silently delete the user's comments. Handing over both files
- * and a diff is honest; rewriting their config behind a "merge" flag is not.
- *
- * Split into a read-only {@link planExport} and a mutating {@link executeExport} so
- * `--dry-run` and the real run share one code path, mirroring `lib/uninstall.ts`.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { AGENTS } from './agents.js';
-import { getAgentConfigPath, getConfigSymlinkVersion } from './shims.js';
-import { getVersionHomePath, isVersionIsolated, isVersionInstalled } from './versions.js';
-import { getUserAgentsDir, getBackupsDir } from './state.js';
-import { copyDirStrippingAgentsSymlinks, moveDirCrossDevice } from './config-transfer.js';
-/** Filename of the provenance receipt written into the agent's config dir. */
-export const RECEIPT_NAME = '.agents-cli-export.json';
-/** Suffix for the incoming copy of a file the user already has. */
-export const CONFLICT_SUFFIX = '.from-agents-cli';
-/** The config dir's basename (`.codex`), used to locate it inside a version home. */
-function configBasename(agent) {
-    return path.basename(AGENTS[agent].configDir);
-}
-/**
- * Every regular file under `root`, as paths relative to it. Symlinks pointing back
- * into `~/.agents` are omitted for the same reason `copyDirStrippingAgentsSymlinks`
- * drops them: they dangle the moment `~/.agents` is disposed, and an export that
- * leaves dangling links is not an export.
- */
-function walkFiles(root, agentsDir, rel = '') {
-    const inside = agentsDir + path.sep;
-    const out = [];
-    let entries;
-    try {
-        entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
-    }
-    catch {
-        return out;
-    }
-    for (const entry of entries) {
-        const childRel = rel ? path.join(rel, entry.name) : entry.name;
-        const abs = path.join(root, childRel);
-        if (entry.isSymbolicLink()) {
-            try {
-                const tgt = path.resolve(path.dirname(abs), fs.readlinkSync(abs));
-                if (tgt === agentsDir || tgt.startsWith(inside))
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            out.push(childRel);
-            continue;
-        }
-        if (entry.isDirectory()) {
-            out.push(...walkFiles(root, agentsDir, childRel));
-            continue;
-        }
-        out.push(childRel);
-    }
-    return out;
-}
-/** Build a read-only plan. Performs no mutations. */
-export function planExport(agent, version, timestamp, mode = 'merge') {
-    const source = path.join(getVersionHomePath(agent, version), configBasename(agent));
-    const dest = getAgentConfigPath(agent);
-    const base = {
-        agent,
-        version,
-        mode,
-        source,
-        dest,
-        destKind: 'absent',
-        writes: [],
-        conflicts: [],
-        backupPath: null,
-        stagedPath: null,
-        receiptPath: path.join(dest, RECEIPT_NAME),
-    };
-    if (!isVersionInstalled(agent, version))
-        return { ...base, blocker: { kind: 'not-installed' } };
-    if (!isVersionIsolated(agent, version))
-        return { ...base, blocker: { kind: 'not-isolated' } };
-    if (!fs.existsSync(source))
-        return { ...base, blocker: { kind: 'no-config', source } };
-    // Refuse when `~/.<agent>` is a symlink agents-cli owns: the agent has a normal
-    // install that adopted it, so writing there would land inside a version home
-    // rather than in the user's real config, and silently mutate that other install.
-    const adopted = getConfigSymlinkVersion(agent);
-    if (adopted !== null) {
-        return { ...base, blocker: { kind: 'dest-adopted', realPath: dest, adoptedVersion: adopted } };
-    }
-    let destKind = 'absent';
-    try {
-        destKind = fs.lstatSync(dest).isSymbolicLink() ? 'foreign-symlink' : 'real-dir';
-    }
-    catch {
-        destKind = 'absent';
-    }
-    const agentsDir = getUserAgentsDir();
-    const rels = walkFiles(source, agentsDir).sort();
-    if (mode === 'staged') {
-        const stagedPath = path.join(dest, `.agents-export-${timestamp}`);
-        return {
-            ...base,
-            destKind,
-            stagedPath,
-            writes: rels.map((rel) => ({
-                rel,
-                source: path.join(source, rel),
-                target: path.join(stagedPath, rel),
-            })),
-            blocker: null,
-        };
-    }
-    if (mode === 'replace') {
-        return {
-            ...base,
-            destKind,
-            backupPath: destKind === 'real-dir' ? path.join(getBackupsDir(), agent, String(timestamp)) : null,
-            writes: rels.map((rel) => ({
-                rel,
-                source: path.join(source, rel),
-                target: path.join(dest, rel),
-            })),
-            blocker: null,
-        };
-    }
-    // merge: additive. Anything the user already has becomes a conflict written
-    // alongside, so their file is never the thing that changes.
-    const writes = [];
-    const conflicts = [];
-    for (const rel of rels) {
-        const target = path.join(dest, rel);
-        let exists = false;
-        try {
-            fs.lstatSync(target);
-            exists = true;
-        }
-        catch {
-            exists = false;
-        }
-        if (exists) {
-            conflicts.push({
-                rel,
-                source: path.join(source, rel),
-                target: target + CONFLICT_SUFFIX,
-                existing: target,
-            });
-        }
-        else {
-            writes.push({ rel, source: path.join(source, rel), target });
-        }
-    }
-    return { ...base, destKind, writes, conflicts, blocker: null };
-}
-/** Copy one file, creating parent dirs. Symlinks are recreated, not followed. */
-function placeFile(entry) {
-    fs.mkdirSync(path.dirname(entry.target), { recursive: true });
-    const st = fs.lstatSync(entry.source);
-    if (st.isSymbolicLink()) {
-        const link = fs.readlinkSync(entry.source);
-        try {
-            fs.unlinkSync(entry.target);
-        }
-        catch {
-            /* nothing there */
-        }
-        fs.symlinkSync(link, entry.target);
-        return;
-    }
-    fs.copyFileSync(entry.source, entry.target);
-}
-function writeReceipt(plan, result, timestamp) {
-    const receipt = {
-        exportedAt: new Date(timestamp).toISOString(),
-        from: `${plan.agent}@${plan.version} (isolated)`,
-        mode: plan.mode,
-        written: result.written,
-        conflicts: result.conflicts,
-        ...(result.backupPath ? { backupPath: result.backupPath } : {}),
-        ...(result.stagedPath ? { stagedAt: result.stagedPath } : {}),
-        note: plan.mode === 'merge'
-            ? `Files under "written" came from this export. Paths under "conflicts" already existed and were NOT modified — the incoming version sits beside yours with the ${CONFLICT_SUFFIX} suffix.`
-            : plan.mode === 'replace'
-                ? 'This config was replaced wholesale by the export; the previous one is at backupPath.'
-                : 'Nothing was activated — the exported tree sits under stagedAt.',
-    };
-    fs.mkdirSync(path.dirname(plan.receiptPath), { recursive: true });
-    fs.writeFileSync(plan.receiptPath, JSON.stringify(receipt, null, 2) + '\n');
-}
-/** Execute a plan from {@link planExport}. */
-export function executeExport(plan, timestamp) {
-    const result = {
-        exported: false,
-        dest: plan.dest,
-        written: [],
-        conflicts: [],
-        backupPath: null,
-        stagedPath: null,
-        receiptPath: null,
-        errors: [],
-    };
-    if (plan.blocker) {
-        result.errors.push(`refusing to export: ${plan.blocker.kind}`);
-        return result;
-    }
-    try {
-        if (plan.mode === 'replace') {
-            if (plan.backupPath) {
-                fs.mkdirSync(path.dirname(plan.backupPath), { recursive: true });
-                moveDirCrossDevice(plan.dest, plan.backupPath);
-                result.backupPath = plan.backupPath;
-            }
-            else if (plan.destKind === 'foreign-symlink') {
-                // Not ours to back up, but it must go or cpSync would write through it.
-                fs.unlinkSync(plan.dest);
-            }
-            copyDirStrippingAgentsSymlinks(plan.source, plan.dest, getUserAgentsDir());
-            result.written = plan.writes.map((w) => w.rel);
-        }
-        else {
-            // merge and staged both place individual files; neither disturbs anything
-            // the user already has.
-            for (const entry of plan.writes) {
-                placeFile(entry);
-                result.written.push(entry.rel);
-            }
-            for (const entry of plan.conflicts) {
-                placeFile(entry);
-                result.conflicts.push({ path: entry.rel, theirs: entry.target });
-            }
-            if (plan.stagedPath)
-                result.stagedPath = plan.stagedPath;
-        }
-        writeReceipt(plan, result, timestamp);
-        result.receiptPath = plan.receiptPath;
-        result.exported = true;
-    }
-    catch (err) {
-        result.errors.push(err instanceof Error ? err.message : String(err));
-    }
-    return result;
-}

package/dist/lib/lock.d.ts

@@ -1,93 +0,0 @@
-/**
- * `agents.lock` — a deterministic SHA-256 manifest of the resolved resource set
- * at a project root, plus the `--frozen` verification that fails closed on any
- * drift. This is the reproducible-CI slice of the governance work (#337); org
- * version pins and bundle signing are deferred follow-ups.
- *
- * Design:
- *  - Content hashing REUSES `fingerprintDir` / `fingerprintFile`
- *    (src/lib/staleness/fingerprint.ts) — the same two-tier fingerprinter every
- *    staleness checker uses. No new recursive file walker is introduced here.
- *  - The resource SET is the layered, resolved source union (project > user >
- *    system > extras), the same precedence `resolveResource` / `syncResourcesToVersion`
- *    read from. It is enumerated agent-independently on purpose: the lock must be
- *    reproducible on a fresh CI checkout that has no installed agent VERSIONS, so
- *    it snapshots the SOURCES sync copies FROM, not any per-version home.
- *
- * Lock shape (JSON): `{ "version": 1, "resources": { "<relpath>": "<sha256>" } }`,
- * keys sorted so the file is byte-stable across machines and runs.
- */
-export declare const LOCK_FILENAME = "agents.lock";
-export declare const LOCK_VERSION: 1;
-/**
- * Resource kinds captured by the lock — the file/dir-backed layered resources
- * shared across every agent. Presence-only kinds handled specially by the sync
- * differ (plugins/promptcuts) are intentionally out of this first slice.
- */
-export declare const LOCK_KINDS: readonly ["commands", "skills", "hooks", "rules", "mcp", "permissions", "subagents"];
-/** The on-disk lockfile: relpath -> sha256 hex digest, keys sorted. */
-export interface AgentsLock {
-    version: typeof LOCK_VERSION;
-    resources: Record<string, string>;
-}
-/**
- * One resolved resource to fingerprint. `path` is an absolute file or directory;
- * `key` is the stable relpath prefix under which its hashes are recorded
- * (e.g. `skills/debug` for a directory, `commands/plan.md` for a single file).
- */
-export interface LockSource {
-    path: string;
-    key: string;
-}
-/** Added/removed/changed keys between an expected lock and the live resources. */
-export interface LockDiff {
-    /** Present in the live resources, absent from the lock. */
-    added: string[];
-    /** Present in the lock, absent from the live resources. */
-    removed: string[];
-    /** Present in both but the sha256 differs. */
-    changed: string[];
-}
-/**
- * Hash every resolved source into a flat `relpath -> sha256` map. Directories are
- * expanded with `fingerprintDir` (every contained file, sorted); single files use
- * `fingerprintFile`. Unreadable / missing sources are skipped — enumeration only
- * ever hands us paths that existed at scan time.
- */
-export declare function hashLockSources(sources: LockSource[]): Record<string, string>;
-/** Build a fully-sorted lock object from a resolved source set. */
-export declare function buildLock(sources: LockSource[]): AgentsLock;
-/** Serialise a lock to the canonical, sorted, newline-terminated JSON form. */
-export declare function serializeLock(lock: AgentsLock): string;
-/** Absolute path to the lockfile for a project root. */
-export declare function lockPath(projectRoot: string): string;
-/**
- * Read + validate an existing lock. Returns null ONLY when the file is absent —
- * a present-but-malformed lock throws, so `--frozen` fails closed instead of
- * silently treating corruption as "no lock".
- */
-export declare function readLock(projectRoot: string): AgentsLock | null;
-/** Write the lock to `<projectRoot>/agents.lock`, returning the path written. */
-export declare function writeLock(projectRoot: string, lock: AgentsLock): string;
-/** Diff a recorded lock against a freshly-computed one. */
-export declare function diffLock(expected: AgentsLock, actual: AgentsLock): LockDiff;
-/** True when a diff has no added/removed/changed entries. */
-export declare function lockDiffIsClean(diff: LockDiff): boolean;
-/** Verify a recorded lock against the live resolved sources. */
-export declare function verifyLock(expected: AgentsLock, sources: LockSource[]): LockDiff;
-/**
- * The project root the lockfile lives at: the parent of the discovered project
- * `.agents/` dir, or the cwd itself when none is found.
- */
-export declare function resolveProjectRoot(cwd?: string): string;
-/**
- * Enumerate the resolved resource sources for a cwd: for each lockable kind, the
- * winning entry per name across layers (project > user > system > extras), keyed
- * `<kind>/<entryName>`. This is a single-level `readdir` per kind dir — the
- * recursive fingerprinting is delegated to `fingerprintDir`.
- *
- * Entry names keep their extension in the key, so a hook script `foo.sh` and its
- * sidecar `foo.yaml` stay distinct (a name-stripped enumerator would collide
- * them). Dotfiles at the kind-dir top level are skipped as noise.
- */
-export declare function enumerateLockSources(cwd?: string): LockSource[];

package/dist/lib/lock.js

@@ -1,207 +0,0 @@
-/**
- * `agents.lock` — a deterministic SHA-256 manifest of the resolved resource set
- * at a project root, plus the `--frozen` verification that fails closed on any
- * drift. This is the reproducible-CI slice of the governance work (#337); org
- * version pins and bundle signing are deferred follow-ups.
- *
- * Design:
- *  - Content hashing REUSES `fingerprintDir` / `fingerprintFile`
- *    (src/lib/staleness/fingerprint.ts) — the same two-tier fingerprinter every
- *    staleness checker uses. No new recursive file walker is introduced here.
- *  - The resource SET is the layered, resolved source union (project > user >
- *    system > extras), the same precedence `resolveResource` / `syncResourcesToVersion`
- *    read from. It is enumerated agent-independently on purpose: the lock must be
- *    reproducible on a fresh CI checkout that has no installed agent VERSIONS, so
- *    it snapshots the SOURCES sync copies FROM, not any per-version home.
- *
- * Lock shape (JSON): `{ "version": 1, "resources": { "<relpath>": "<sha256>" } }`,
- * keys sorted so the file is byte-stable across machines and runs.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { fingerprintDir, fingerprintFile } from './staleness/fingerprint.js';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
-export const LOCK_FILENAME = 'agents.lock';
-export const LOCK_VERSION = 1;
-/**
- * Resource kinds captured by the lock — the file/dir-backed layered resources
- * shared across every agent. Presence-only kinds handled specially by the sync
- * differ (plugins/promptcuts) are intentionally out of this first slice.
- */
-export const LOCK_KINDS = [
-    'commands',
-    'skills',
-    'hooks',
-    'rules',
-    'mcp',
-    'permissions',
-    'subagents',
-];
-/** Normalise a filesystem-relative path to POSIX separators for stable keys. */
-function toPosix(rel) {
-    return rel.split(path.sep).join('/');
-}
-/**
- * Hash every resolved source into a flat `relpath -> sha256` map. Directories are
- * expanded with `fingerprintDir` (every contained file, sorted); single files use
- * `fingerprintFile`. Unreadable / missing sources are skipped — enumeration only
- * ever hands us paths that existed at scan time.
- */
-export function hashLockSources(sources) {
-    const out = {};
-    for (const src of sources) {
-        let stat;
-        try {
-            stat = fs.statSync(src.path);
-        }
-        catch {
-            continue;
-        }
-        if (stat.isDirectory()) {
-            for (const fp of fingerprintDir(src.path)) {
-                const rel = toPosix(path.relative(src.path, fp.path));
-                out[`${src.key}/${rel}`] = fp.sha256;
-            }
-        }
-        else if (stat.isFile()) {
-            const fp = fingerprintFile(src.path);
-            if (fp)
-                out[src.key] = fp.sha256;
-        }
-    }
-    return out;
-}
-/** Build a fully-sorted lock object from a resolved source set. */
-export function buildLock(sources) {
-    return { version: LOCK_VERSION, resources: sortRecord(hashLockSources(sources)) };
-}
-/** Return a new record with keys inserted in sorted order (deterministic JSON). */
-function sortRecord(record) {
-    const out = {};
-    for (const key of Object.keys(record).sort())
-        out[key] = record[key];
-    return out;
-}
-/** Serialise a lock to the canonical, sorted, newline-terminated JSON form. */
-export function serializeLock(lock) {
-    return JSON.stringify({ version: lock.version, resources: sortRecord(lock.resources) }, null, 2) + '\n';
-}
-/** Absolute path to the lockfile for a project root. */
-export function lockPath(projectRoot) {
-    return path.join(projectRoot, LOCK_FILENAME);
-}
-/**
- * Read + validate an existing lock. Returns null ONLY when the file is absent —
- * a present-but-malformed lock throws, so `--frozen` fails closed instead of
- * silently treating corruption as "no lock".
- */
-export function readLock(projectRoot) {
-    const p = lockPath(projectRoot);
-    if (!fs.existsSync(p))
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
-    }
-    catch (e) {
-        throw new Error(`${LOCK_FILENAME} is not valid JSON: ${e.message}`);
-    }
-    if (!parsed || typeof parsed !== 'object') {
-        throw new Error(`${LOCK_FILENAME} is malformed (expected an object).`);
-    }
-    const obj = parsed;
-    if (obj.version !== LOCK_VERSION) {
-        throw new Error(`${LOCK_FILENAME} version ${String(obj.version)} is unsupported (expected ${LOCK_VERSION}).`);
-    }
-    if (!obj.resources || typeof obj.resources !== 'object') {
-        throw new Error(`${LOCK_FILENAME} is missing a resources map.`);
-    }
-    return { version: LOCK_VERSION, resources: obj.resources };
-}
-/** Write the lock to `<projectRoot>/agents.lock`, returning the path written. */
-export function writeLock(projectRoot, lock) {
-    const p = lockPath(projectRoot);
-    fs.writeFileSync(p, serializeLock(lock));
-    return p;
-}
-/** Diff a recorded lock against a freshly-computed one. */
-export function diffLock(expected, actual) {
-    const e = expected.resources;
-    const a = actual.resources;
-    const added = [];
-    const removed = [];
-    const changed = [];
-    for (const k of Object.keys(a))
-        if (!(k in e))
-            added.push(k);
-    for (const k of Object.keys(e)) {
-        if (!(k in a))
-            removed.push(k);
-        else if (e[k] !== a[k])
-            changed.push(k);
-    }
-    added.sort();
-    removed.sort();
-    changed.sort();
-    return { added, removed, changed };
-}
-/** True when a diff has no added/removed/changed entries. */
-export function lockDiffIsClean(diff) {
-    return diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0;
-}
-/** Verify a recorded lock against the live resolved sources. */
-export function verifyLock(expected, sources) {
-    return diffLock(expected, buildLock(sources));
-}
-/**
- * The project root the lockfile lives at: the parent of the discovered project
- * `.agents/` dir, or the cwd itself when none is found.
- */
-export function resolveProjectRoot(cwd = process.cwd()) {
-    const projectDir = getProjectAgentsDir(cwd);
-    return projectDir ? path.dirname(projectDir) : path.resolve(cwd);
-}
-/**
- * Enumerate the resolved resource sources for a cwd: for each lockable kind, the
- * winning entry per name across layers (project > user > system > extras), keyed
- * `<kind>/<entryName>`. This is a single-level `readdir` per kind dir — the
- * recursive fingerprinting is delegated to `fingerprintDir`.
- *
- * Entry names keep their extension in the key, so a hook script `foo.sh` and its
- * sidecar `foo.yaml` stay distinct (a name-stripped enumerator would collide
- * them). Dotfiles at the kind-dir top level are skipped as noise.
- */
-export function enumerateLockSources(cwd = process.cwd()) {
-    const roots = [];
-    const projectDir = getProjectAgentsDir(cwd);
-    if (projectDir)
-        roots.push(projectDir);
-    roots.push(getUserAgentsDir());
-    roots.push(getSystemAgentsDir());
-    for (const extra of getEnabledExtraRepos())
-        roots.push(extra.dir);
-    const sources = [];
-    const seen = new Set();
-    for (const kind of LOCK_KINDS) {
-        for (const root of roots) {
-            const kindDir = path.join(root, kind);
-            let entries;
-            try {
-                entries = fs.readdirSync(kindDir, { withFileTypes: true });
-            }
-            catch {
-                continue;
-            }
-            for (const entry of entries) {
-                if (entry.name.startsWith('.'))
-                    continue;
-                const key = `${kind}/${entry.name}`;
-                if (seen.has(key))
-                    continue; // project layer wins on same name
-                seen.add(key);
-                sources.push({ path: path.join(kindDir, entry.name), key });
-            }
-        }
-    }
-    return sources.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-}

package/dist/lib/wallet/index.d.ts

@@ -1,78 +0,0 @@
-/**
- * Wallet: device-local credit-card vault.
- *
- * Two-tier storage so listing the wallet doesn't pop Touch ID, but reading
- * a card always does:
- *
- *   Card metadata (id, nickname, brand, last4, expiry, created_at, kind)
- *     -> ~/.agents/wallet/cards.json, mode 0600
- *     -> Display-only data, equivalent of Apple Wallet's "card art" tier.
- *
- *   Card secret (PAN, CVC, cardholder)
- *     -> Keychain item `agents-cli.secrets.wallet.<id>` (JSON-encoded)
- *     -> Routed through the signed helper, so the OS gates decryption with
- *        Touch ID + biometryCurrentSet. Re-enrolling Touch ID invalidates
- *        the item, matching Apple Pay's AR-value rotation behavior.
- *
- * Not Apple Pay: we store a real PAN, not a network DPAN, and we do not
- * generate per-transaction cryptograms. Callers must surface this clearly.
- */
-/** Test seam: override the index path. Returns the previous override (or null). */
-export declare function _setIndexPathForTest(p: string | null): string | null;
-export type CardBrand = 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unionpay' | 'unknown';
-/** Storage kind discriminator. Reserved for future kind: 'stripe_token'. */
-export type CardKind = 'pan_encrypted';
-/** Non-sensitive card metadata. Safe to display without biometric auth. */
-export interface CardMetadata {
-    id: string;
-    nickname: string;
-    brand: CardBrand;
-    last4: string;
-    exp_month: string;
-    exp_year: string;
-    created_at: string;
-    kind: CardKind;
-}
-/** Sensitive card fields. Keychain-stored, Touch ID required to read. */
-export interface CardSecret {
-    pan: string;
-    cvc: string;
-    cardholder: string;
-}
-/** Card metadata plus its secret payload. Returned by show() only. */
-export interface CardFull extends CardMetadata, CardSecret {
-}
-/** Input shape for add(). */
-export interface AddCardInput {
-    nickname: string;
-    pan: string;
-    cvc: string;
-    cardholder: string;
-    exp_month: string;
-    exp_year: string;
-}
-/** Compute the Luhn checksum and verify a candidate PAN. */
-export declare function isValidLuhn(pan: string): boolean;
-/** Detect card brand from the BIN (first 6 digits). */
-export declare function detectBrand(pan: string): CardBrand;
-/** Atomically read the index file. Returns [] when missing. */
-export declare function readIndex(): CardMetadata[];
-/** List all stored cards. Does NOT trigger biometric auth. */
-export declare function listCards(): CardMetadata[];
-/** Look up a card by id (or by case-insensitive nickname). Returns undefined when missing. */
-export declare function findCard(idOrNickname: string): CardMetadata | undefined;
-/**
- * Add a new card. Validates Luhn + expiry. Returns the metadata for the
- * stored card. The PAN/CVC/cardholder are written to Keychain in a single
- * JSON blob; only metadata is mirrored to the index file.
- */
-export declare function addCard(input: AddCardInput): CardMetadata;
-/**
- * Reveal a card by id. **Triggers Touch ID on macOS.** Throws if the card
- * isn't in the index or if the keychain entry is missing/cancelled.
- */
-export declare function showCard(idOrNickname: string): CardFull;
-/** Delete a card from both the index and Keychain. Returns the removed metadata or undefined. */
-export declare function removeCard(idOrNickname: string): CardMetadata | undefined;
-/** Rename a card. Throws if the new nickname collides with an existing card. */
-export declare function renameCard(idOrNickname: string, newNickname: string): CardMetadata;