@coswic/aipay 0.2.0 → 0.4.0

package/dist/device.js

@@ -0,0 +1,122 @@
+/**
+ * RFC 8628 device authorization for `aipay login --device` (consultant §10.2, auth model A2):
+ * for machines without a browser (SSH boxes, containers, CI). The CLI asks the
+ * authorization server for a device code + a short user code, prints the verification
+ * URL and the code, then polls the token endpoint until the developer approves it in
+ * a browser on any device. No loopback listener, no ports.
+ */
+import { CliError, EXIT } from './output.js';
+export const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** POST /oauth2/device/auth — public client, so only client_id/scope/audience are sent. */
+export async function requestDeviceCode(cfg, fetchImpl = fetch) {
+    const form = new URLSearchParams({
+        client_id: cfg.clientId,
+        scope: cfg.scopes.join(' '),
+        audience: cfg.audience,
+    });
+    let res;
+    try {
+        res = await fetchImpl(new URL('/oauth2/device/auth', cfg.authOrigin), {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+    }
+    catch (e) {
+        throw new CliError('network', `cannot reach ${cfg.authOrigin}: ${e.message}`, EXIT.remote);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        const err = parseOAuthError(text);
+        if (err?.error === 'invalid_grant' || err?.error === 'unauthorized_client')
+            throw new CliError('device_unsupported', 'this AI-Pay does not allow device sign-in for the CLI yet — use `aipay login` on a machine with a browser', EXIT.remote);
+        throw new CliError('remote', `device authorization failed: HTTP ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
+    }
+    const j = JSON.parse(text);
+    if (typeof j.device_code !== 'string' ||
+        typeof j.user_code !== 'string' ||
+        typeof j.verification_uri !== 'string')
+        throw new CliError('remote', 'unexpected device authorization response', EXIT.remote);
+    return {
+        deviceCode: j.device_code,
+        userCode: j.user_code,
+        verificationUri: j.verification_uri,
+        verificationUriComplete: typeof j.verification_uri_complete === 'string' ? j.verification_uri_complete : null,
+        expiresInSeconds: typeof j.expires_in === 'number' ? j.expires_in : 600,
+        intervalSeconds: typeof j.interval === 'number' && j.interval > 0 ? j.interval : 5,
+    };
+}
+/**
+ * Poll POST /oauth2/token with the device grant until the developer approves, denies, or the
+ * code expires. `authorization_pending` → wait `interval`; `slow_down` → interval += 5s
+ * (RFC 8628 §3.5); anything else is final.
+ */
+export async function pollDeviceToken(cfg, auth, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + auth.expiresInSeconds * 1000;
+    let interval = auth.intervalSeconds;
+    for (;;) {
+        if (now() >= deadline)
+            throw new CliError('expired', 'the sign-in code expired — run `aipay login --device` again', EXIT.remote);
+        opts.onWait?.(Math.max(0, Math.round((deadline - now()) / 1000)));
+        await sleep(interval * 1000);
+        const form = new URLSearchParams({
+            grant_type: DEVICE_CODE_GRANT,
+            device_code: auth.deviceCode,
+            client_id: cfg.clientId,
+        });
+        let res;
+        try {
+            res = await fetchImpl(new URL('/oauth2/token', cfg.authOrigin), {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: form.toString(),
+            });
+        }
+        catch {
+            continue; // transient network blip: keep polling until the deadline
+        }
+        const text = await res.text();
+        if (res.ok) {
+            const j = JSON.parse(text);
+            if (typeof j.access_token !== 'string')
+                throw new CliError('remote', 'token response missing access_token', EXIT.remote);
+            return {
+                accessToken: j.access_token,
+                refreshToken: typeof j.refresh_token === 'string' ? j.refresh_token : null,
+                expiresInSeconds: typeof j.expires_in === 'number' ? j.expires_in : 0,
+                scope: typeof j.scope === 'string' ? j.scope : cfg.scopes.join(' '),
+            };
+        }
+        const err = parseOAuthError(text);
+        switch (err?.error) {
+            case 'authorization_pending':
+                continue;
+            case 'slow_down':
+                interval += 5;
+                continue;
+            case 'expired_token':
+                throw new CliError('expired', 'the sign-in code expired — run `aipay login --device` again', EXIT.remote);
+            case 'access_denied':
+                throw new CliError('denied', 'sign-in was denied in the browser', EXIT.remote);
+            default:
+                throw new CliError('remote', `token endpoint returned ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
+        }
+    }
+}
+function parseOAuthError(text) {
+    try {
+        const j = JSON.parse(text);
+        return {
+            ...(typeof j.error === 'string' ? { error: j.error } : {}),
+            ...(typeof j.error_description === 'string'
+                ? { error_description: j.error_description }
+                : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/** Programmatic surface (used by tests and by anyone embedding the commands). */
+export { AGENT_GUIDE_FILE, agentGuide } from './agent-guide.js';
+export { type ParsedArgs, parseArgs } from './args.js';
+export { configDir, createAuthStore, fileStore, type StoredAuth } from './auth-store.js';
+export { createApp, runApps } from './commands/apps.js';
+export { collectChecks, runDoctor } from './commands/doctor.js';
+export { DEFAULT_CALLBACK, runInit, SDK_PACKAGE } from './commands/init.js';
+export { fetchCliConfig, managementAuthorizeUrl, resolveApiBase, runLogin, } from './commands/login.js';
+export { runLogout, runWhoami } from './commands/session.js';
+export { runStatus } from './commands/status.js';
+export { formatUusd, pickModel, runTest } from './commands/test.js';
+export { runUnlink, stripEnvKeys } from './commands/unlink.js';
+export { detectFramework, detectPackageManager, detectProject, installCommand } from './detect.js';
+export { openDeveloperApi } from './developer-api.js';
+export { parseCallback, startLoopback } from './loopback.js';
+export { main } from './main.js';
+export { isEmpty404 } from './network.js';
+export { CliError, createReporter, EXIT, type Reporter } from './output.js';
+export { ENV_KEYS, isProjectConfig, mergeEnvFile, mergeGitignore, type ProjectConfig, readProject, writeProject, } from './project.js';
+export { createRemote, docsUrl, type Remote } from './remote.js';
+export { scaffoldFiles, startPathFor } from './templates.js';
+export { cliVersion } from './version.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+/** Programmatic surface (used by tests and by anyone embedding the commands). */
+export { AGENT_GUIDE_FILE, agentGuide } from './agent-guide.js';
+export { parseArgs } from './args.js';
+export { configDir, createAuthStore, fileStore } from './auth-store.js';
+export { createApp, runApps } from './commands/apps.js';
+export { collectChecks, runDoctor } from './commands/doctor.js';
+export { DEFAULT_CALLBACK, runInit, SDK_PACKAGE } from './commands/init.js';
+export { fetchCliConfig, managementAuthorizeUrl, resolveApiBase, runLogin, } from './commands/login.js';
+export { runLogout, runWhoami } from './commands/session.js';
+export { runStatus } from './commands/status.js';
+export { formatUusd, pickModel, runTest } from './commands/test.js';
+export { runUnlink, stripEnvKeys } from './commands/unlink.js';
+export { detectFramework, detectPackageManager, detectProject, installCommand } from './detect.js';
+export { openDeveloperApi } from './developer-api.js';
+export { parseCallback, startLoopback } from './loopback.js';
+export { main } from './main.js';
+export { isEmpty404 } from './network.js';
+export { CliError, createReporter, EXIT } from './output.js';
+export { ENV_KEYS, isProjectConfig, mergeEnvFile, mergeGitignore, readProject, writeProject, } from './project.js';
+export { createRemote, docsUrl } from './remote.js';
+export { scaffoldFiles, startPathFor } from './templates.js';
+export { cliVersion } from './version.js';

package/dist/loopback.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Loopback redirect receiver (RFC 8252 §7.3) for `aipay test`: listens on the exact
+ * registered callback URI (host + port + path), captures ONE redirect, answers the
+ * browser with a small HTML page, then closes. The authorization code never touches
+ * disk; the token exchange happens in the caller's memory.
+ */
+import { type Server } from 'node:http';
+export interface LoopbackTarget {
+    host: string;
+    port: number;
+    path: string;
+}
+/**
+ * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
+ * is ignored, so the CLI may receive the callback on any free port while the app keeps
+ * its registered URI. `localhost` is NOT treated as loopback by the server — exact port.
+ */
+export declare function portIsVariable(target: LoopbackTarget): boolean;
+/** The redirect_uri to send for a receiver bound to `port` (same host + path). */
+export declare function redirectUriFor(target: LoopbackTarget, port: number): string;
+export declare function parseCallback(callback: string): LoopbackTarget;
+export interface LoopbackResult {
+    /** Full callback URL as received (query included) — hand it to the SDK's handleCallback. */
+    url: string;
+}
+export interface LoopbackHandle {
+    /** Resolves with the first request on the callback path; rejects on timeout. */
+    waitForCallback: Promise<LoopbackResult>;
+    close(): Promise<void>;
+    server: Server;
+    /** Port actually bound (differs from target.port when target.port is 0 = ephemeral). */
+    port: number;
+}
+export declare function startLoopback(target: LoopbackTarget, opts?: {
+    timeoutMs?: number;
+    pageHtml?: (ok: boolean) => string;
+}): Promise<LoopbackHandle>;

package/dist/loopback.js

@@ -0,0 +1,95 @@
+/**
+ * Loopback redirect receiver (RFC 8252 §7.3) for `aipay test`: listens on the exact
+ * registered callback URI (host + port + path), captures ONE redirect, answers the
+ * browser with a small HTML page, then closes. The authorization code never touches
+ * disk; the token exchange happens in the caller's memory.
+ */
+import { createServer } from 'node:http';
+/**
+ * Hydra compares loopback redirect URIs per RFC 8252 §7.3: for 127.0.0.1 / [::1] the port
+ * is ignored, so the CLI may receive the callback on any free port while the app keeps
+ * its registered URI. `localhost` is NOT treated as loopback by the server — exact port.
+ */
+export function portIsVariable(target) {
+    return target.host === '127.0.0.1' || target.host === '::1';
+}
+/** The redirect_uri to send for a receiver bound to `port` (same host + path). */
+export function redirectUriFor(target, port) {
+    const host = target.host === '::1' ? '[::1]' : target.host;
+    return `http://${host}:${port}${target.path}`;
+}
+export function parseCallback(callback) {
+    const u = new URL(callback);
+    if (u.protocol !== 'http:')
+        throw new Error(`callback must be http:// on a loopback host (got ${callback})`);
+    const host = u.hostname;
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '[::1]' && host !== '::1')
+        throw new Error(`callback host must be a loopback address (got ${host})`);
+    const port = u.port ? Number(u.port) : 80;
+    return { host: host === '[::1]' ? '::1' : host, port, path: u.pathname || '/' };
+}
+export function startLoopback(target, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5 * 60_000;
+    const page = opts.pageHtml ?? defaultPage;
+    return new Promise((resolve, reject) => {
+        let settle = null;
+        let fail = null;
+        const waitForCallback = new Promise((res, rej) => {
+            settle = res;
+            fail = rej;
+        });
+        const server = createServer((req, res) => {
+            const addr = server.address();
+            const boundPort = typeof addr === 'object' && addr ? addr.port : target.port;
+            const url = new URL(req.url ?? '/', redirectUriFor(target, boundPort));
+            if (url.pathname !== target.path) {
+                res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+                res.end('not the callback path');
+                return;
+            }
+            const ok = !url.searchParams.get('error');
+            res.writeHead(200, {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+            });
+            res.end(page(ok));
+            settle?.({ url: url.toString() });
+            settle = null;
+        });
+        const timer = setTimeout(() => {
+            fail?.(new Error(`no callback received within ${Math.round(timeoutMs / 1000)}s`));
+            fail = null;
+        }, timeoutMs);
+        server.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        server.listen(target.port, target.host, () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : target.port;
+            resolve({
+                waitForCallback,
+                server,
+                port,
+                close: () => new Promise((done) => {
+                    clearTimeout(timer);
+                    server.close(() => done());
+                    // Keep-alive connections would otherwise hold the process open.
+                    server.closeAllConnections?.();
+                }),
+            });
+        });
+    });
+}
+function defaultPage(ok) {
+    const title = ok ? 'AI-Pay: signed in' : 'AI-Pay: authorization failed';
+    const body = ok
+        ? 'You can close this tab and return to the terminal.'
+        : 'The terminal shows the error. You can close this tab.';
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;margin:0;display:grid;place-items:center;min-height:100vh;background:#f6f7f9;color:#1b1f24}
+main{padding:32px 40px;border-radius:12px;background:#fff;box-shadow:0 2px 12px rgba(0,0,0,.08);text-align:center}
+h1{font-size:20px;margin:0 0 8px}</style></head>
+<body><main><h1>${title}</h1><p>${body}</p></main></body></html>`;
+}

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+export declare const HELP = "aipay \u2014 AI-Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\napps    list your apps / create one (Idempotency-Key: a retried create never makes a second app)\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI-Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
+export declare function main(argv: string[], io?: {
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+}): Promise<number>;

package/dist/main.js

@@ -0,0 +1,90 @@
+import { flagBool, parseArgs } from './args.js';
+import { runApps } from './commands/apps.js';
+import { runDoctor } from './commands/doctor.js';
+import { runInit } from './commands/init.js';
+import { runLogin } from './commands/login.js';
+import { runLogout, runWhoami } from './commands/session.js';
+import { runStatus } from './commands/status.js';
+import { runTest } from './commands/test.js';
+import { runUnlink } from './commands/unlink.js';
+import { CliError, createReporter, EXIT } from './output.js';
+import { cliVersion } from './version.js';
+export const HELP = `aipay — AI-Pay CLI
+
+Usage
+  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself
+  aipay whoami [--json] · aipay logout [--json]
+  aipay apps list [--json]
+  aipay apps create --name <name> [--callback <url>] [--json]
+  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]
+             [--framework next|express|fastify|hono|vite|node]  override detection
+             [--dir <path>] [--dry-run] [--no-install] [--json]
+  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it
+  aipay test [--model <id>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]
+  aipay doctor [--offline] [--dir <path>] [--json]
+  aipay status [--dir <path>] [--json]
+  aipay unlink [--dry-run] [--dir <path>] [--json]
+
+login   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the
+        OS keychain or a 0600 file — never into the project
+apps    list your apps / create one (Idempotency-Key: a retried create never makes a second app)
+init    link this project to an app: .aipay/project.json, .env.local, .gitignore,
+        a callback route for your framework, aipay-agent.md, and the SDK install
+        (--auth/--api are optional once you are signed in; --create makes the app first)
+test    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion → receipt
+doctor  check the link, files, SDK, and that AI-Pay is reachable
+status  what this directory is linked to
+unlink  forget the link (keeps your code)
+
+Exit codes: 0 ok · 1 problem you can fix · 2 usage · 3 network/auth
+`;
+export async function main(argv, io) {
+    const args = parseArgs(argv);
+    const json = flagBool(args.flags, 'json');
+    const out = createReporter({ json, ...(io ?? {}) });
+    if (args.flags.version || args.command === 'version') {
+        ;
+        (io?.stdout ?? ((s) => process.stdout.write(`${s}\n`)))(json ? JSON.stringify({ version: cliVersion() }) : cliVersion());
+        return EXIT.ok;
+    }
+    if (!args.command || args.flags.help || args.command === 'help') {
+        ;
+        (io?.stdout ?? ((s) => process.stdout.write(`${s}\n`)))(HELP);
+        return args.command || args.flags.help ? EXIT.ok : EXIT.usage;
+    }
+    try {
+        switch (args.command) {
+            case 'login':
+                return await runLogin(args, out);
+            case 'logout':
+                return await runLogout(args, out);
+            case 'whoami':
+                return await runWhoami(args, out);
+            case 'apps':
+                return await runApps(args, out);
+            case 'init':
+                return await runInit(args, out);
+            case 'test':
+                return await runTest(args, out);
+            case 'doctor':
+                return await runDoctor(args, out);
+            case 'status':
+                return runStatus(args, out);
+            case 'unlink':
+                return runUnlink(args, out);
+            default:
+                throw new CliError('usage', `unknown command "${args.command}" (see \`aipay help\`)`, EXIT.usage);
+        }
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            out.line('bad', e.message);
+            out.result({ ok: false, error: { code: e.code, message: e.message } });
+            return e.exitCode;
+        }
+        const msg = e instanceof Error ? e.message : String(e);
+        out.line('bad', msg);
+        out.result({ ok: false, error: { code: 'unexpected', message: msg } });
+        return EXIT.problem;
+    }
+}

package/dist/network.d.ts

@@ -0,0 +1,3 @@
+/** Describe the observed response without inferring its network or server-side cause. */
+export declare function isEmpty404(status: number, bodyText: string): boolean;
+export declare const EMPTY_404_HINT = "AI-Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.";

package/dist/network.js

@@ -0,0 +1,5 @@
+/** Describe the observed response without inferring its network or server-side cause. */
+export function isEmpty404(status, bodyText) {
+    return status === 404 && bodyText.trim() === '';
+}
+export const EMPTY_404_HINT = 'AI-Pay answered 404 with an empty body. Check the endpoint URL and network connectivity, then retry. An empty 404 alone does not identify the cause.';

package/dist/output.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Output channel: human-readable lines on stderr-ish stdout, or one JSON document when
+ * `--json` is set (agents parse it; humans read the other one). Both go to stdout so
+ * `aipay status --json | jq` works; diagnostics that must never pollute JSON go to stderr.
+ */
+export type Level = 'ok' | 'warn' | 'bad' | 'info';
+export interface Reporter {
+    readonly json: boolean;
+    line(level: Level, text: string): void;
+    kv(label: string, value: string): void;
+    blank(): void;
+    /** Final structured result — printed as JSON in --json mode, ignored otherwise. */
+    result(doc: Record<string, unknown>): void;
+    /** Debug/diagnostic text — always stderr, never in JSON. */
+    debug(text: string): void;
+}
+export declare function createReporter(opts: {
+    json: boolean;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+}): Reporter;
+/** Exit codes are part of the contract (agents branch on them). */
+export declare const EXIT: {
+    readonly ok: 0;
+    /** Something in the project/config is wrong and the user can fix it. */
+    readonly problem: 1;
+    /** Bad invocation (unknown command/flag, missing required flag). */
+    readonly usage: 2;
+    /** Network/auth failure talking to AI-Pay. */
+    readonly remote: 3;
+};
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly code: string;
+    constructor(code: string, message: string, exitCode?: number);
+}

package/dist/output.js

@@ -0,0 +1,52 @@
+const GLYPH = { ok: '✔', warn: '⚠', bad: '✘', info: '·' };
+export function createReporter(opts) {
+    const stdout = opts.stdout ?? ((s) => process.stdout.write(`${s}\n`));
+    const stderr = opts.stderr ?? ((s) => process.stderr.write(`${s}\n`));
+    const json = opts.json;
+    return {
+        json,
+        line(level, text) {
+            if (json)
+                return;
+            stdout(`${GLYPH[level]} ${text}`);
+        },
+        kv(label, value) {
+            if (json)
+                return;
+            stdout(`  ${label.padEnd(14)} ${value}`);
+        },
+        blank() {
+            if (json)
+                return;
+            stdout('');
+        },
+        result(doc) {
+            if (!json)
+                return;
+            stdout(JSON.stringify(doc, null, 2));
+        },
+        debug(text) {
+            stderr(text);
+        },
+    };
+}
+/** Exit codes are part of the contract (agents branch on them). */
+export const EXIT = {
+    ok: 0,
+    /** Something in the project/config is wrong and the user can fix it. */
+    problem: 1,
+    /** Bad invocation (unknown command/flag, missing required flag). */
+    usage: 2,
+    /** Network/auth failure talking to AI-Pay. */
+    remote: 3,
+};
+export class CliError extends Error {
+    exitCode;
+    code;
+    constructor(code, message, exitCode = EXIT.problem) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}

package/dist/project.d.ts

@@ -0,0 +1,61 @@
+export interface ProjectConfig {
+    /** Schema version of this file. */
+    version: 1;
+    app: {
+        client_id: string;
+        name: string | null;
+    };
+    /** Authorization server origin (Hydra public), e.g. https://auth.ai-pay.example */
+    auth_origin: string;
+    /** API base for the SDK client, e.g. https://api.ai-pay.example */
+    api_base: string;
+    /** Registered loopback callback the CLI and the sample route use. */
+    callback: string;
+    /** What `aipay init` detected/scaffolded, for `doctor`/`status` and for humans. */
+    scaffold: {
+        package_manager: 'pnpm' | 'npm' | 'yarn' | 'bun' | null;
+        framework: Framework | null;
+        files: string[];
+    };
+    linked_at: string;
+}
+export type Framework = 'next' | 'express' | 'fastify' | 'hono' | 'vite' | 'node';
+/** Accepted by `--framework`; detection picks server frameworks first, then Vite, then plain Node. */
+export declare const FRAMEWORKS: readonly Framework[];
+export declare function isFramework(v: unknown): v is Framework;
+export declare const PROJECT_DIR = ".aipay";
+export declare const PROJECT_FILE = "project.json";
+export declare const ENV_FILE = ".env.local";
+export declare function projectPath(dir: string): string;
+export declare function readProject(dir: string): ProjectConfig | null;
+export declare function writeProject(dir: string, cfg: ProjectConfig): string;
+export declare function isProjectConfig(v: unknown): v is ProjectConfig;
+/** Env var names the SDK samples and the scaffolded route read. Public values only. */
+export declare const ENV_KEYS: {
+    readonly clientId: 'AIPAY_CLIENT_ID';
+    readonly authOrigin: 'AIPAY_AUTH_ORIGIN';
+    readonly apiBase: 'AIPAY_API_BASE';
+    readonly callback: 'AIPAY_CALLBACK_URL';
+};
+/** Vite only exposes VITE_-prefixed values to browser code, so a Vite project gets the same four
+ * public values twice: the plain names (for any server-side tooling) and these aliases. */
+export declare const VITE_ENV_KEYS: {
+    readonly clientId: 'VITE_AIPAY_CLIENT_ID';
+    readonly authOrigin: 'VITE_AIPAY_AUTH_ORIGIN';
+    readonly apiBase: 'VITE_AIPAY_API_BASE';
+    readonly callback: 'VITE_AIPAY_CALLBACK_URL';
+};
+/**
+ * Merge our keys into `.env.local` without touching anything else in it: existing lines
+ * for our keys are replaced in place, missing ones appended under a marker comment.
+ * Returns the keys that actually changed (so `--dry-run` and `status` can report).
+ */
+export declare function mergeEnvFile(existing: string | null, values: Record<string, string>): {
+    content: string;
+    changed: string[];
+};
+/** Append missing ignore entries; never reorder or remove anything. */
+export declare function mergeGitignore(existing: string | null, entries: string[]): {
+    content: string;
+    added: string[];
+};