@agirails/sdk 4.4.9 → 4.6.0

package/dist/cli/agirails.js

@@ -2,10 +2,19 @@
 /**
  * npx agirails — One Command Entry Point
  *
- * 60-second quickstart: ask 3 questions → generate {slug}.md → real Sentinel
+ * 60-second quickstart: ask 3 questions → generate {slug}.md → bootstrap a
+ * real testnet wallet (Smart Wallet + 1K test USDC) → run a real Sentinel
  * onboarding request on Base Sepolia → reflection. PRD-event-driven-provider-
  * listening §5.7 replaced the prior MockRuntime earning-loop simulation with
  * a live Level 1 request against the deployed Sentinel agent.
+ *
+ * FIX-2 (2026-06): the wizard previously wrote a `mock` config with a random
+ * address and immediately invoked `runTest({ network: 'testnet' })`. The
+ * downstream `resolvePrivateKey` returned `undefined` and ACTPClient crashed.
+ * The wizard now runs `runInit({ mode: 'testnet', wallet: 'auto' })` BEFORE
+ * `runTest` so the keystore + Smart Wallet exist and the first transaction
+ * has a real signer behind it.
+ *
  * Re-entrant: if identity already exists, skips onboarding and runs test.
  *
  * @module cli/agirails
@@ -34,14 +43,17 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.__test = exports.runWizard = exports.buildIdentityFile = exports.hasKeystoreDefault = exports.defaultWizardDeps = void 0;
 const fs = __importStar(require("fs"));
 const readline = __importStar(require("readline"));
+const path = __importStar(require("path"));
 const ethers_1 = require("ethers");
 const output_1 = require("./utils/output");
 const config_1 = require("./utils/config");
 const config_2 = require("./utils/config");
 const slugUtils_1 = require("../config/slugUtils");
 const test_1 = require("./commands/test");
+const init_1 = require("./commands/init");
 const slugUtils_2 = require("../config/slugUtils");
 const agirailsmd_1 = require("../config/agirailsmd");
 const defaults_1 = require("../config/defaults");
@@ -57,167 +69,401 @@ function ask(rl, question) {
 // Service type menu
 // ============================================================================
 const SERVICE_MENU = defaults_1.V4_CONSTRAINTS.KNOWN_SERVICES.map((s, i) => `  ${i + 1}. ${s}`).join('\n');
+/**
+ * Production wiring for the wizard. Tests substitute individual fields.
+ */
+function defaultWizardDeps() {
+    return {
+        collectAnswers: collectAnswersInteractive,
+        ensurePassword: ensurePasswordDefault,
+        runInit: async (opts, output) => {
+            // runInit's signature is `(options, output, cmd?)`. The wizard doesn't
+            // have a Commander instance, and `isExplicit(...)` calls inside runInit
+            // safely fall back to "not explicit" when `cmd` is undefined, so all
+            // CLI-flag values we pass are treated as defaults that AGIRAILS.md /
+            // {slug}.md may override. That's exactly what we want during wizard
+            // onboarding — the freshly written {slug}.md is the source of truth.
+            //
+            // runInit's InitOptions interface isn't exported from commands/init.ts.
+            // Round-tripping through `unknown` keeps strict mode happy and is the
+            // explicitly-sanctioned escape hatch for "I know the shape, the type
+            // checker can't see it through the module boundary."
+            await (0, init_1.runInit)(opts, output);
+        },
+        runTest: test_1.runTest,
+        hasKeystore: hasKeystoreDefault,
+        // process.stdin.isTTY is `true | undefined`. Normalize to boolean so
+        // tests can stub without TS narrowing pain.
+        isTTY: () => Boolean(process.stdin.isTTY),
+    };
+}
+exports.defaultWizardDeps = defaultWizardDeps;
+/**
+ * A keystore is "present" when `.actp/keystore.json` exists OR the user
+ * has provided `ACTP_KEYSTORE_BASE64` / `ACTP_PRIVATE_KEY` env vars. Any
+ * of those satisfies `resolvePrivateKey()` in `runTest`.
+ */
+function hasKeystoreDefault(projectRoot = process.cwd()) {
+    try {
+        if (process.env.ACTP_PRIVATE_KEY && process.env.ACTP_PRIVATE_KEY.length > 0)
+            return true;
+        if (process.env.ACTP_KEYSTORE_BASE64 && process.env.ACTP_KEYSTORE_BASE64.length > 0)
+            return true;
+        const keystorePath = path.join((0, config_1.getActpDir)(projectRoot), 'keystore.json');
+        return fs.existsSync(keystorePath);
+    }
+    catch {
+        return false;
+    }
+}
+exports.hasKeystoreDefault = hasKeystoreDefault;
 // ============================================================================
-// Main
+// Interactive collectors
 // ============================================================================
-async function main() {
-    const args = process.argv.slice(2);
-    const jsonMode = args.includes('--json');
-    const quietMode = args.includes('-q') || args.includes('--quiet');
-    const output = new output_1.Output(jsonMode ? 'json' : quietMode ? 'quiet' : 'human');
+async function collectAnswersInteractive(output) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const name = await ask(rl, output_1.fmt.cyan('? ') + 'What does your agent do? (name) ' + output_1.fmt.dim('> '));
+        if (!name.trim()) {
+            output.error('Agent name is required.');
+            return null;
+        }
+        output.print('');
+        output.print(output_1.fmt.dim('Service types:'));
+        output.print(SERVICE_MENU);
+        const serviceInput = await ask(rl, output_1.fmt.cyan('? ') + 'Pick a service type ' + output_1.fmt.dim('[1-7, or custom] > '));
+        const serviceIdx = parseInt(serviceInput, 10);
+        const service = (serviceIdx >= 1 && serviceIdx <= defaults_1.V4_CONSTRAINTS.KNOWN_SERVICES.length)
+            ? defaults_1.V4_CONSTRAINTS.KNOWN_SERVICES[serviceIdx - 1]
+            : serviceInput.trim().toLowerCase().replace(/[^a-z0-9-]+/g, '-') || 'automation';
+        const priceInput = await ask(rl, output_1.fmt.cyan('? ') + 'Base price in USDC? ' + output_1.fmt.dim('[default: 1.00] > '));
+        const price = parseFloat(priceInput) || 1.0;
+        return { name: name.trim(), service, price };
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Resolve ACTP_KEY_PASSWORD.
+ *
+ * Priority:
+ *   1. Existing env var (developer-set / CI secret)
+ *   2. Interactive prompt (TTY only)
+ *   3. Auto-generated password (non-TTY — see FIX-3 follow-up; current
+ *      behavior is to surface a clear error so the user can set the env
+ *      var explicitly).
+ *
+ * Returns the password (already written to process.env.ACTP_KEY_PASSWORD)
+ * or `null` if no password could be obtained.
+ */
+async function ensurePasswordDefault(output) {
+    if (process.env.ACTP_KEY_PASSWORD && process.env.ACTP_KEY_PASSWORD.length >= 8) {
+        return process.env.ACTP_KEY_PASSWORD;
+    }
+    if (!process.stdin.isTTY) {
+        // Non-TTY without an explicit password — fail closed with a clear hint
+        // instead of letting `runInit` throw a generic error. FIX-3 will replace
+        // this branch with auto-generated passwords + claim-code persistence.
+        output.error('ACTP_KEY_PASSWORD is required in non-interactive environments.\n' +
+            'Set ACTP_KEY_PASSWORD=<min 8 chars> and re-run, or use --interactive.');
+        return null;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(output_1.fmt.cyan('? ') + 'Pick a password to encrypt your wallet ' + output_1.fmt.dim('(min 8 chars) > '), resolve);
+        });
+        const password = answer.trim();
+        if (password.length < 8) {
+            output.error('Password must be at least 8 characters.');
+            return null;
+        }
+        process.env.ACTP_KEY_PASSWORD = password;
+        return password;
+    }
+    finally {
+        rl.close();
+    }
+}
+// ============================================================================
+// Wizard orchestrator (the testable core)
+// ============================================================================
+/**
+ * Build the V4 frontmatter + body for a fresh {slug}.md from wizard answers.
+ *
+ * Extracted so tests can verify the structure without going through the
+ * full wizard flow.
+ */
+function buildIdentityFile(answers) {
+    const slug = (0, slugUtils_2.generateSlug)(answers.name);
+    const slugError = (0, slugUtils_1.validateSlug)(slug);
+    if (slugError) {
+        throw new Error(`Invalid agent name: ${slugError}`);
+    }
+    const minPrice = Math.max(0.01, answers.price * 0.99);
+    const maxPrice = answers.price * 1.01;
+    const frontmatter = {
+        name: answers.name,
+        slug,
+        version: '1.0.0',
+        // Default to testnet — the wizard's whole point is to put the user on
+        // Base Sepolia with a real keystore and a real Sentinel transaction.
+        network: 'base-sepolia',
+        services: [
+            {
+                type: answers.service,
+                price: String(answers.price),
+                min_price: minPrice,
+                max_price: maxPrice,
+            },
+        ],
+        pricing: {
+            base: answers.price,
+            currency: defaults_1.V4_DEFAULTS.pricing.currency,
+            unit: defaults_1.V4_DEFAULTS.pricing.unit,
+            min_price: minPrice,
+            max_price: maxPrice,
+            negotiable: false,
+        },
+        sla: { ...defaults_1.V4_DEFAULTS.sla },
+        payment: { modes: [...defaults_1.V4_DEFAULTS.payment.modes] },
+    };
+    const body = `\n# ${answers.name}\n\nDescribe what your agent does here.\n\n## How to Request This Service\n\nExplain how clients should structure their requests.\n`;
+    const content = (0, agirailsmd_1.serializeAgirailsMd)(frontmatter, body);
+    return { filename: `${slug}.md`, content, slug };
+}
+exports.buildIdentityFile = buildIdentityFile;
+/**
+ * Orchestrate the wizard. Pure-ish: every side effect goes through `deps`,
+ * so the test suite can verify behavior without ever touching the network,
+ * the keystore encrypt path, or a real Sentinel deployment.
+ *
+ * Returns the exit code instead of calling process.exit so callers (and
+ * tests) can decide what to do with failures.
+ */
+async function runWizard(output, deps = defaultWizardDeps()) {
     try {
-        // Re-entrant: if identity exists, skip onboarding
+        // ── Re-entrant fast path ────────────────────────────────────────────
+        // If an identity file already exists, skip onboarding entirely and
+        // jump straight to the test transaction. We still require a keystore
+        // — if there's an identity but no wallet, init must run.
         const existingIdentity = (0, config_1.resolveIdentityPath)();
         if (existingIdentity) {
             output.print(output_1.fmt.dim('Identity found: ' + existingIdentity));
             output.print('');
-            await (0, test_1.runTest)(output);
-            return;
+            if (!deps.hasKeystore(process.cwd())) {
+                // Identity but no keystore — typical for users who ran the wizard
+                // before FIX-2 landed and left a stale mock config behind. Run
+                // init now so runTest has something to sign with.
+                const password = await deps.ensurePassword(output);
+                if (!password)
+                    return output_1.ExitCode.INVALID_INPUT;
+                try {
+                    await deps.runInit({ mode: 'testnet', wallet: 'auto', force: true, test: false }, output);
+                }
+                catch (error) {
+                    output.error('Wallet bootstrap failed: ' + extractMessage(error));
+                    printSetupHint(output);
+                    return output_1.ExitCode.ERROR;
+                }
+            }
+            try {
+                await deps.runTest(output);
+                return output_1.ExitCode.SUCCESS;
+            }
+            catch (error) {
+                return handleTestError(error, output);
+            }
         }
-        // Banner
+        // ── Banner ──────────────────────────────────────────────────────────
         if (output.mode === 'human') {
-            const { renderBanner } = await Promise.resolve().then(() => __importStar(require('./utils/banner')));
-            output.print('');
-            output.print(renderBanner());
-            output.print('');
-            output.print(output_1.fmt.dim('Your agent earns in 60 seconds.'));
-            output.print('');
-        }
-        // Interactive questions
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        try {
-            // Q1: Agent name
-            const name = await ask(rl, output_1.fmt.cyan('? ') + 'What does your agent do? (name) ' + output_1.fmt.dim('> '));
-            if (!name.trim()) {
-                output.error('Agent name is required.');
-                process.exit(output_1.ExitCode.INVALID_INPUT);
-            }
-            // Q2: Service type
-            output.print('');
-            output.print(output_1.fmt.dim('Service types:'));
-            output.print(SERVICE_MENU);
-            const serviceInput = await ask(rl, output_1.fmt.cyan('? ') + 'Pick a service type ' + output_1.fmt.dim('[1-7, or custom] > '));
-            const serviceIdx = parseInt(serviceInput, 10);
-            const service = (serviceIdx >= 1 && serviceIdx <= defaults_1.V4_CONSTRAINTS.KNOWN_SERVICES.length)
-                ? defaults_1.V4_CONSTRAINTS.KNOWN_SERVICES[serviceIdx - 1]
-                : serviceInput.trim().toLowerCase().replace(/[^a-z0-9-]+/g, '-') || 'automation';
-            // Q3: Base price
-            const priceInput = await ask(rl, output_1.fmt.cyan('? ') + 'Base price in USDC? ' + output_1.fmt.dim('[default: 1.00] > '));
-            const price = parseFloat(priceInput) || 1.00;
-            rl.close();
-            // Generate and validate slug
-            const slug = (0, slugUtils_2.generateSlug)(name.trim());
-            const slugError = (0, slugUtils_1.validateSlug)(slug);
-            if (slugError) {
-                output.error(`Invalid agent name: ${slugError}`);
-                process.exit(output_1.ExitCode.INVALID_INPUT);
+            try {
+                const { renderBanner } = await Promise.resolve().then(() => __importStar(require('./utils/banner')));
+                output.print('');
+                output.print(renderBanner());
+                output.print('');
+                output.print(output_1.fmt.dim('Your agent earns in 60 seconds.'));
+                output.print('');
             }
-            // Build frontmatter.
-            //
-            // Services emit as objects { type, price, min_price, max_price } —
-            // not plain strings — because the SDK publish pipeline
-            // (`extractRegistrationParams`) reads `svc.type` and `svc.min_price`/
-            // `svc.max_price` to populate per-service on-chain price bands on
-            // AgentRegistry. Plain strings throw "Empty service type" at publish.
-            // Default band is 1% around base price to avoid the 0..1000 USDC
-            // fallback when min/max are absent.
-            const minPrice = Math.max(0.01, price * 0.99);
-            const maxPrice = price * 1.01;
-            const frontmatter = {
-                name: name.trim(),
-                slug,
-                version: '1.0.0',
-                network: defaults_1.V4_DEFAULTS.network,
-                services: [
-                    {
-                        type: service,
-                        price: String(price),
-                        min_price: minPrice,
-                        max_price: maxPrice,
-                    },
-                ],
-                pricing: {
-                    base: price,
-                    currency: defaults_1.V4_DEFAULTS.pricing.currency,
-                    unit: defaults_1.V4_DEFAULTS.pricing.unit,
-                    min_price: minPrice,
-                    max_price: maxPrice,
-                    negotiable: false,
-                },
-                sla: { ...defaults_1.V4_DEFAULTS.sla },
-                payment: { modes: [...defaults_1.V4_DEFAULTS.payment.modes] },
-            };
-            // Build body
-            const body = `\n# ${name.trim()}\n\nDescribe what your agent does here.\n\n## How to Request This Service\n\nExplain how clients should structure their requests.\n`;
-            // Write {slug}.md (guard against overwriting existing files)
-            const filename = `${slug}.md`;
-            if (fs.existsSync(filename)) {
-                output.error(`File already exists: ${filename}. Remove it or choose a different name.`);
-                process.exit(output_1.ExitCode.INVALID_INPUT);
+            catch {
+                // Banner failure is purely cosmetic — never block the wizard on it.
             }
-            const content = (0, agirailsmd_1.serializeAgirailsMd)(frontmatter, body);
-            fs.writeFileSync(filename, content, 'utf-8');
-            output.print('');
-            output.success(`Created ${output_1.fmt.bold(filename)}`);
-            // Bootstrap .actp/ or backfill identity pointer
-            if (!(0, config_1.isInitialized)()) {
-                const randomAddress = ethers_1.ethers.Wallet.createRandom().address;
-                (0, config_1.saveConfig)({
-                    ...config_1.CONFIG_DEFAULTS,
-                    mode: 'mock',
-                    address: randomAddress,
-                    identity: filename,
-                });
-                (0, config_2.addToGitignore)();
-                output.success('Initialized .actp/ (mock mode)');
+        }
+        // ── Collect answers ────────────────────────────────────────────────
+        const answers = await deps.collectAnswers(output);
+        if (!answers) {
+            return output_1.ExitCode.INVALID_INPUT;
+        }
+        // ── Build & write {slug}.md ────────────────────────────────────────
+        let identity;
+        try {
+            identity = buildIdentityFile(answers);
+        }
+        catch (error) {
+            output.error(extractMessage(error));
+            return output_1.ExitCode.INVALID_INPUT;
+        }
+        if (fs.existsSync(identity.filename)) {
+            output.error(`File already exists: ${identity.filename}. Remove it or choose a different name.`);
+            return output_1.ExitCode.INVALID_INPUT;
+        }
+        try {
+            fs.writeFileSync(identity.filename, identity.content, 'utf-8');
+        }
+        catch (error) {
+            output.error('Could not write identity file: ' + extractMessage(error));
+            return output_1.ExitCode.ERROR;
+        }
+        output.print('');
+        output.success(`Created ${output_1.fmt.bold(identity.filename)}`);
+        // ── Resolve password BEFORE runInit ────────────────────────────────
+        // We deliberately resolve the password before *any* on-chain or
+        // keystore-encrypt work — that way we can fail fast if no password
+        // is available, and the user doesn't see a half-baked .actp/ dir.
+        const password = await deps.ensurePassword(output);
+        if (!password) {
+            // ensurePassword already printed the actionable error.
+            return output_1.ExitCode.INVALID_INPUT;
+        }
+        // ── Run init: keystore + Smart Wallet + mint test USDC ─────────────
+        // runInit picks up the freshly written {slug}.md via its own scan logic
+        // and uses it to pre-fill the .actp/config.json values, so we don't
+        // need to push answers in twice.
+        try {
+            await deps.runInit({
+                mode: 'testnet',
+                wallet: 'auto',
+                // We *just* wrote the file; if it existed before, we already
+                // bailed above. `force: false` keeps init from clobbering a
+                // pre-existing .actp/ that the user might still want.
+                force: false,
+                // Don't run the post-init prompt — we run runTest ourselves
+                // immediately after so we have full control over UX.
+                test: false,
+            }, output);
+        }
+        catch (error) {
+            output.error('Wallet bootstrap failed: ' + extractMessage(error));
+            printSetupHint(output);
+            // Critical: do NOT proceed to runTest. Without a keystore, runTest
+            // crashes hard with a "Cannot read property 'getAddress' of
+            // undefined" stack — exactly what FIX-2 set out to eliminate.
+            return output_1.ExitCode.ERROR;
+        }
+        // ── Defensive fallback for an init that "succeeded" but left no
+        // keystore behind (e.g. test mocks, partial failures). Without this
+        // guard, runTest would still crash — so we treat it as a hard stop.
+        if (!deps.hasKeystore(process.cwd())) {
+            output.error('Wallet bootstrap completed but no keystore was found at .actp/keystore.json.');
+            printSetupHint(output);
+            return output_1.ExitCode.ERROR;
+        }
+        // ── Backfill identity pointer if init didn't pick it up ────────────
+        // runInit writes config.json — but its identity-detection scan can
+        // miss freshly-created files in rare race conditions. Always make
+        // sure the pointer is set after init.
+        if ((0, config_1.isInitialized)() && !(0, config_1.resolveIdentityPath)()) {
+            try {
+                (0, config_1.updateConfig)({ identity: identity.filename });
             }
-            else if (!(0, config_1.resolveIdentityPath)()) {
-                // Existing config without identity pointer — backfill it
-                (0, config_1.updateConfig)({ identity: filename });
-                output.success('Updated .actp/config.json with identity pointer');
+            catch {
+                // updateConfig failing here is non-fatal — runTest's own
+                // resolveIdentityPath() will still find the file via the scan.
             }
-            // Run a real Sentinel onboarding request on Base Sepolia. Requires a
-            // wallet at ~/.actp/wallets/base-sepolia (or ACTP_KEYSTORE_BASE64) and
-            // small testnet ETH + USDC. The PRD §5.7 rewrite intentionally
-            // dropped the pre-4.0.0 MockRuntime simulation — "mock success" was a
-            // lie and onboarding deserves the real loop.
-            output.print('');
-            await (0, test_1.runTest)(output);
-            // Next steps
-            output.print('');
-            output.section('Next Steps');
-            output.print(`  1. Edit your agent: ${output_1.fmt.bold(filename)}`);
-            output.print(`  2. Go live on testnet: ${output_1.fmt.bold('actp publish')}`);
-            output.print(`  3. Your agent page: ${output_1.fmt.cyan(`agirails.app/a/${slug}`)} ${output_1.fmt.dim('(after publish)')}`);
-            output.print('');
         }
-        finally {
-            rl.close();
+        // ── Run the Sentinel test transaction ──────────────────────────────
+        output.print('');
+        try {
+            await deps.runTest(output);
+        }
+        catch (error) {
+            return handleTestError(error, output);
         }
+        // ── Next steps ─────────────────────────────────────────────────────
+        output.print('');
+        output.section('Next Steps');
+        output.print(`  1. Edit your agent: ${output_1.fmt.bold(identity.filename)}`);
+        output.print(`  2. Go live on testnet: ${output_1.fmt.bold('actp publish')}`);
+        output.print(`  3. Your agent page: ${output_1.fmt.cyan(`agirails.app/a/${identity.slug}`)} ${output_1.fmt.dim('(after publish)')}`);
+        output.print('');
+        return output_1.ExitCode.SUCCESS;
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        output.error(message);
-        // Surface the 4.0.0 setup expectation that runTest() now imposes. The
-        // common first-run failure modes — no keystore, no testnet ETH, no
-        // sentinel address — all flow through here, and a bare error message
-        // gives a new developer nothing to act on. The hint is conditional on
-        // the error shape so non-runtime errors (e.g. file-write failures
-        // earlier in onboarding) don't get the wrong remediation glued on.
-        if (looksLikeRunTestSetupError(message)) {
-            output.print('');
-            output.print('agirails now runs a real onboarding request against Sentinel on Base Sepolia.\n' +
-                'First-run setup:\n' +
-                "  1. `actp init` to generate a wallet (or set ACTP_KEYSTORE_BASE64).\n" +
-                "  2. Fund the wallet with a small amount of Base Sepolia ETH (gas) + test USDC.\n" +
-                "  3. Rerun `npx agirails`.\n" +
-                'Override Sentinel\'s address with ACTP_SENTINEL_ADDRESS=0x... if needed.');
+        // Last-resort catch — should be unreachable given the inner try/catch
+        // blocks above, but better to surface a clean message than a stack.
+        output.error(extractMessage(error));
+        return output_1.ExitCode.ERROR;
+    }
+}
+exports.runWizard = runWizard;
+/**
+ * Map a runTest error to a structured output + the right exit code.
+ * Mirrors the existing setup-hint heuristic so users with no wallet / no
+ * funds / missing Sentinel address still get actionable next-step guidance.
+ */
+function handleTestError(error, output) {
+    const message = extractMessage(error);
+    output.error(message);
+    if (looksLikeRunTestSetupError(message)) {
+        printSetupHint(output);
+    }
+    return output_1.ExitCode.ERROR;
+}
+function extractMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+function printSetupHint(output) {
+    output.print('');
+    output.print('agirails now runs a real onboarding request against Sentinel on Base Sepolia.\n' +
+        'First-run setup:\n' +
+        '  1. `actp init` to generate a wallet (or set ACTP_KEYSTORE_BASE64).\n' +
+        '  2. Fund the wallet with a small amount of Base Sepolia ETH (gas) + test USDC.\n' +
+        '  3. Rerun `npx agirails`.\n' +
+        "Override Sentinel's address with ACTP_SENTINEL_ADDRESS=0x... if needed.");
+}
+// ============================================================================
+// Main entry point
+// ============================================================================
+async function main() {
+    const args = process.argv.slice(2);
+    const jsonMode = args.includes('--json');
+    const quietMode = args.includes('-q') || args.includes('--quiet');
+    const output = new output_1.Output(jsonMode ? 'json' : quietMode ? 'quiet' : 'human');
+    // FIX-2: the wizard previously bootstrapped a mock config with a random
+    // address and called runTest in testnet mode → crash. We now invoke
+    // runInit({mode:'testnet',wallet:'auto'}) before runTest, so the keystore
+    // and Smart Wallet exist by the time runTest needs a signer.
+    //
+    // Backwards-compat note for existing mock configs: if a previous wizard
+    // run left a `.actp/config.json` in `mode: 'mock'` with a random address
+    // and no keystore, treat that as the "no real onboarding yet" state and
+    // re-run the wizard. Identity is preserved (we don't overwrite the .md),
+    // but the config gets upgraded by runInit.
+    if ((0, config_1.isInitialized)()) {
+        try {
+            const { loadConfig } = await Promise.resolve().then(() => __importStar(require('./utils/config')));
+            const cfg = loadConfig();
+            const looksLikeStaleMock = cfg.mode === 'mock' && !defaultWizardDeps().hasKeystore(process.cwd());
+            if (looksLikeStaleMock && (0, config_1.resolveIdentityPath)()) {
+                output.print(output_1.fmt.dim('Detected stale mock config — upgrading to testnet wallet so the Sentinel transaction can run.'));
+            }
+        }
+        catch {
+            // ignore — runWizard handles missing/broken config gracefully
         }
-        process.exit(output_1.ExitCode.ERROR);
     }
+    const code = await runWizard(output, defaultWizardDeps());
+    process.exit(code);
 }
 /** Heuristic — match the four most common runRequest / resolveAgent first-run
  *  failure-message shapes so the setup hint only fires when actionable. */
@@ -227,21 +473,50 @@ function looksLikeRunTestSetupError(message) {
         /Agent ['"]?sentinel['"]?/i.test(message) ||
         /ACTP_SENTINEL_ADDRESS/i.test(message) ||
         /insufficient funds/i.test(message) ||
-        /BASE_SEPOLIA_RPC/i.test(message));
+        /BASE_SEPOLIA_RPC/i.test(message) ||
+        /keystore/i.test(message) ||
+        /ACTP_KEY_PASSWORD/i.test(message));
 }
+// Internal helpers exposed for unit tests only. Not part of the public CLI API.
+exports.__test = {
+    looksLikeRunTestSetupError,
+    handleTestError,
+    extractMessage,
+    // Retain the pre-FIX-2 mock-config bootstrap so legacy callers can still
+    // construct a mock config inline (used by agirails.test.ts and as a
+    // fallback if the wizard ever needs to fall back to mock mode).
+    bootstrapMockConfig: (filename) => {
+        const randomAddress = ethers_1.ethers.Wallet.createRandom().address;
+        (0, config_1.saveConfig)({
+            ...config_1.CONFIG_DEFAULTS,
+            mode: 'mock',
+            address: randomAddress,
+            identity: filename,
+        });
+        (0, config_2.addToGitignore)();
+    },
+};
 // ============================================================================
 // Subcommand routing: agirails find [query] [options]
 // ============================================================================
+const isMainModule = require.main === module;
 const subCmd = process.argv[2];
-if (subCmd === 'find') {
-    const sub = new commander_1.Command('agirails');
-    sub.addCommand((0, find_1.createFindCommand)());
-    sub.parse(process.argv);
-}
-else {
-    main().catch((error) => {
-        console.error(error?.message || error);
-        process.exit(1);
-    });
+if (isMainModule) {
+    if (subCmd === 'find') {
+        const sub = new commander_1.Command('agirails');
+        sub.addCommand((0, find_1.createFindCommand)());
+        sub.parse(process.argv);
+    }
+    else {
+        main().catch((error) => {
+            // Final safety net — runWizard should already have caught & printed,
+            // but if something escapes (e.g. an import failure) we still want a
+            // single-line error rather than a raw stack trace.
+            const message = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.error(message);
+            process.exit(1);
+        });
+    }
 }
 //# sourceMappingURL=agirails.js.map