@coswic/aipay 0.2.0 → 0.3.0

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 { GATE_ENV, gatedFetch, gateHeaders, looksGated } from './gate.js';
+export { parseCallback, startLoopback } from './loopback.js';
+export { main } from './main.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 { GATE_ENV, gatedFetch, gateHeaders, looksGated } from './gate.js';
+export { parseCallback, startLoopback } from './loopback.js';
+export { main } from './main.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\nPilot gate: export AIPAY_GATE_TOKEN=<token from the Console>; never write it to files.\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,91 @@
+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
+Pilot gate: export AIPAY_GATE_TOKEN=<token from the Console>; never write it to files.
+`;
+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/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[];
+};

package/dist/project.js

@@ -0,0 +1,127 @@
+/**
+ * Local artifacts (consultant report §6.5):
+ *   .aipay/project.json  — committable: which app this project is linked to (no secrets)
+ *   .env.local           — NOT committed: only public values today (client_id, URLs); the
+ *                          gate token is read from the environment and never written
+ *   .gitignore           — gets `.env.local` and `.aipay/local/` appended once
+ *
+ * Tokens live only in memory for the duration of `aipay test`. Nothing here writes them.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Accepted by `--framework`; detection picks server frameworks first, then Vite, then plain Node. */
+export const FRAMEWORKS = [
+    'next',
+    'express',
+    'fastify',
+    'hono',
+    'vite',
+    'node',
+];
+export function isFramework(v) {
+    return typeof v === 'string' && FRAMEWORKS.includes(v);
+}
+export const PROJECT_DIR = '.aipay';
+export const PROJECT_FILE = 'project.json';
+export const ENV_FILE = '.env.local';
+export function projectPath(dir) {
+    return join(dir, PROJECT_DIR, PROJECT_FILE);
+}
+export function readProject(dir) {
+    const p = projectPath(dir);
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!isProjectConfig(parsed))
+        throw new Error(`${p} is not a valid AI-Pay project file`);
+    return parsed;
+}
+export function writeProject(dir, cfg) {
+    mkdirSync(join(dir, PROJECT_DIR), { recursive: true });
+    const p = projectPath(dir);
+    writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`);
+    return p;
+}
+export function isProjectConfig(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    const app = o.app;
+    return (o.version === 1 &&
+        !!app &&
+        typeof app.client_id === 'string' &&
+        typeof o.auth_origin === 'string' &&
+        typeof o.api_base === 'string' &&
+        typeof o.callback === 'string');
+}
+/** Env var names the SDK samples and the scaffolded route read. Public values only. */
+export const ENV_KEYS = {
+    clientId: 'AIPAY_CLIENT_ID',
+    authOrigin: 'AIPAY_AUTH_ORIGIN',
+    apiBase: 'AIPAY_API_BASE',
+    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 const VITE_ENV_KEYS = {
+    clientId: 'VITE_AIPAY_CLIENT_ID',
+    authOrigin: 'VITE_AIPAY_AUTH_ORIGIN',
+    apiBase: 'VITE_AIPAY_API_BASE',
+    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 function mergeEnvFile(existing, values) {
+    const lines = existing ? existing.split(/\r?\n/) : [];
+    if (lines.length && lines[lines.length - 1] === '')
+        lines.pop();
+    const changed = [];
+    const seen = new Set();
+    const out = lines.map((line) => {
+        const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=(.*)$/.exec(line);
+        if (!m)
+            return line;
+        const key = m[1];
+        if (!(key in values))
+            return line;
+        seen.add(key);
+        const want = values[key];
+        if (unquote(m[2] ?? '') === want)
+            return line;
+        changed.push(key);
+        return `${key}=${want}`;
+    });
+    const missing = Object.keys(values).filter((k) => !seen.has(k));
+    if (missing.length) {
+        if (out.length)
+            out.push('');
+        out.push('# AI-Pay (written by `aipay init`; public values, safe to keep local)');
+        for (const k of missing) {
+            out.push(`${k}=${values[k]}`);
+            changed.push(k);
+        }
+    }
+    return { content: `${out.join('\n')}\n`, changed };
+}
+function unquote(s) {
+    const t = s.trim();
+    if (t.length >= 2 &&
+        ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))))
+        return t.slice(1, -1);
+    return t;
+}
+/** Append missing ignore entries; never reorder or remove anything. */
+export function mergeGitignore(existing, entries) {
+    const lines = existing ? existing.split(/\r?\n/) : [];
+    const have = new Set(lines.map((l) => l.trim()));
+    const added = entries.filter((e) => !have.has(e));
+    if (!added.length)
+        return { content: existing ?? '', added };
+    const base = existing ? (existing.endsWith('\n') ? existing : `${existing}\n`) : '';
+    const block = `${base}${base ? '\n' : ''}# AI-Pay local files (never commit)\n${added.join('\n')}\n`;
+    return { content: block, added };
+}

package/dist/remote.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Everything that talks to AI-Pay over the network, in one place so the commands stay
+ * readable and tests can stub it. Gate header via the environment (see gate.ts).
+ */
+import { GATE_HINT } from './gate.js';
+export interface Remote {
+    fetchDocs(apiBase: string, locale?: 'en' | 'zh-Hant'): Promise<{
+        markdown: string | null;
+        gated: boolean;
+        status: number;
+    }>;
+    probe(url: string): Promise<{
+        ok: boolean;
+        status: number;
+        gated: boolean;
+        error?: string;
+    }>;
+}
+export declare function createRemote(env?: NodeJS.ProcessEnv): Remote;
+export declare function docsUrl(apiBase: string, locale?: 'en' | 'zh-Hant'): string;
+export { GATE_HINT };

package/dist/remote.js

@@ -0,0 +1,41 @@
+/**
+ * Everything that talks to AI-Pay over the network, in one place so the commands stay
+ * readable and tests can stub it. Gate header via the environment (see gate.ts).
+ */
+import { GATE_HINT, gatedFetch, looksGated } from './gate.js';
+import { CliError, EXIT } from './output.js';
+export function createRemote(env = process.env) {
+    const f = gatedFetch(env);
+    return {
+        async fetchDocs(apiBase, locale = 'en') {
+            const url = docsUrl(apiBase, locale);
+            let res;
+            try {
+                res = await f(url, { headers: { accept: 'text/markdown, text/plain' } });
+            }
+            catch (e) {
+                throw new CliError('network', `cannot reach ${url}: ${e.message}`, EXIT.remote);
+            }
+            const text = await res.text();
+            if (res.ok)
+                return { markdown: text, gated: false, status: res.status };
+            return { markdown: null, gated: looksGated(res.status, text), status: res.status };
+        },
+        async probe(url) {
+            try {
+                const res = await f(url, { method: 'GET', redirect: 'manual' });
+                const text = await res.text();
+                return { ok: res.ok, status: res.status, gated: looksGated(res.status, text) };
+            }
+            catch (e) {
+                return { ok: false, status: 0, gated: false, error: e.message };
+            }
+        },
+    };
+}
+export function docsUrl(apiBase, locale = 'en') {
+    const u = new URL('/docs.md', apiBase);
+    u.searchParams.set('lang', locale);
+    return u.toString();
+}
+export { GATE_HINT };

package/dist/setup-events.d.ts

@@ -0,0 +1,3 @@
+import type { Reporter } from './output.js';
+export type SetupEventKind = 'cli.init' | 'cli.test' | 'cli.doctor';
+export declare function reportSetupEvent(appId: string, kind: SetupEventKind, detail: Record<string, string | number | boolean | string[]>, out: Reporter, env?: NodeJS.ProcessEnv): Promise<boolean>;

package/dist/setup-events.js

@@ -0,0 +1,28 @@
+/**
+ * Setup-session events (consultant §6.3): after `init` / `test` the CLI tells the Console
+ * what happened so the "waiting for the tool" line turns into "the CLI finished init".
+ * Best effort and strictly opt-in by state: only when the developer is signed in with the
+ * CLI (`aipay login`); never blocks the command, never sends tokens or file contents.
+ */
+import { createAuthStore } from './auth-store.js';
+import { openDeveloperApi } from './developer-api.js';
+export async function reportSetupEvent(appId, kind, detail, out, env = process.env) {
+    const store = createAuthStore(env);
+    if (!store.load())
+        return false; // not signed in with the CLI → the Console still sees server facts
+    try {
+        const api = await openDeveloperApi(store, env);
+        const res = await api.request('POST', `/v1/developer/apps/${encodeURIComponent(appId)}/setup-events`, {
+            body: { kind, detail },
+        });
+        if (res.status === 201) {
+            out.line('info', `reported ${kind} to the Console`);
+            return true;
+        }
+        out.debug(`setup event ${kind} not recorded (HTTP ${res.status})`);
+    }
+    catch (e) {
+        out.debug(`setup event ${kind} skipped: ${e.message}`);
+    }
+    return false;
+}