@coswic/aipay 0.2.0 → 0.4.0

package/dist/commands/doctor.js

@@ -0,0 +1,145 @@
+/**
+ * `aipay doctor [--dir] [--json] [--offline]` — checks the link, the local files, the
+ * SDK install, and (unless --offline) reachability of the authorization server and the
+ * API. Exit 0 = nothing to fix, 1 = at least one problem.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { flagBool, flagString } from '../args.js';
+import { detectProject } from '../detect.js';
+import { parseCallback } from '../loopback.js';
+import { EXIT } from '../output.js';
+import { ENV_FILE, ENV_KEYS, readProject } from '../project.js';
+import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
+export async function runDoctor(args, out, deps = {}) {
+    const dir = resolve(flagString(args.flags, 'dir') ?? '.');
+    const checks = await collectChecks(dir, { offline: flagBool(args.flags, 'offline') }, deps);
+    for (const c of checks)
+        out.line(c.level, c.text);
+    const problems = checks.filter((c) => c.level === 'bad');
+    out.blank();
+    out.line(problems.length ? 'bad' : 'ok', problems.length ? `${problems.length} problem(s)` : 'all good');
+    out.result({ ok: problems.length === 0, dir, checks });
+    return problems.length ? EXIT.problem : EXIT.ok;
+}
+export async function collectChecks(dir, opts, deps) {
+    const checks = [];
+    const major = Number((deps.nodeVersion ?? process.versions.node).split('.')[0]);
+    checks.push(major >= 20
+        ? { id: 'node', level: 'ok', text: `Node ${deps.nodeVersion ?? process.versions.node}` }
+        : {
+            id: 'node',
+            level: 'bad',
+            text: `Node ${deps.nodeVersion ?? process.versions.node} — the SDK needs 20+`,
+        });
+    let project = null;
+    try {
+        project = readProject(dir);
+    }
+    catch (e) {
+        checks.push({ id: 'project', level: 'bad', text: e.message });
+        return checks;
+    }
+    if (!project) {
+        checks.push({
+            id: 'project',
+            level: 'bad',
+            text: 'not linked — run `aipay init --app <client_id> --auth <origin> --api <base>`',
+        });
+        return checks;
+    }
+    checks.push({
+        id: 'project',
+        level: 'ok',
+        text: `linked to ${project.app.name ?? project.app.client_id} (.aipay/project.json)`,
+    });
+    try {
+        const t = parseCallback(project.callback);
+        checks.push({
+            id: 'callback',
+            level: 'ok',
+            text: `callback ${project.callback} (loopback, port ${t.port})`,
+        });
+    }
+    catch (e) {
+        checks.push({ id: 'callback', level: 'bad', text: `callback: ${e.message}` });
+    }
+    const envPath = join(dir, ENV_FILE);
+    if (!existsSync(envPath))
+        checks.push({ id: 'env', level: 'bad', text: `${ENV_FILE} missing — rerun \`aipay init\`` });
+    else {
+        const content = readFileSync(envPath, 'utf8');
+        const want = {
+            [ENV_KEYS.clientId]: project.app.client_id,
+            [ENV_KEYS.authOrigin]: project.auth_origin,
+            [ENV_KEYS.apiBase]: project.api_base,
+            [ENV_KEYS.callback]: project.callback,
+        };
+        const wrong = Object.entries(want)
+            .filter(([k, v]) => !new RegExp(`^\\s*(?:export\\s+)?${k}\\s*=\\s*["']?${escapeRe(v)}["']?\\s*$`, 'm').test(content))
+            .map(([k]) => k);
+        checks.push(wrong.length
+            ? {
+                id: 'env',
+                level: 'bad',
+                text: `${ENV_FILE} out of sync: ${wrong.join(', ')} — rerun \`aipay init\``,
+            }
+            : { id: 'env', level: 'ok', text: `${ENV_FILE} has the four AIPAY_* values` });
+    }
+    const gi = join(dir, '.gitignore');
+    if (existsSync(gi) &&
+        !readFileSync(gi, 'utf8')
+            .split(/\r?\n/)
+            .some((l) => l.trim() === ENV_FILE))
+        checks.push({ id: 'gitignore', level: 'warn', text: `.gitignore does not list ${ENV_FILE}` });
+    const det = detectProject(dir);
+    if (det.hasPackageJson) {
+        const installed = det.sdkInstalled && existsSync(join(dir, 'node_modules', '@coswic', 'aipay-sdk'));
+        checks.push(installed
+            ? { id: 'sdk', level: 'ok', text: '@coswic/aipay-sdk installed' }
+            : det.sdkInstalled
+                ? {
+                    id: 'sdk',
+                    level: 'bad',
+                    text: '@coswic/aipay-sdk is in package.json but not installed — run your package manager install',
+                }
+                : {
+                    id: 'sdk',
+                    level: 'bad',
+                    text: '@coswic/aipay-sdk not a dependency — rerun `aipay init` (or add it yourself)',
+                });
+        for (const f of project.scaffold.files)
+            if (!existsSync(join(dir, f)))
+                checks.push({ id: 'scaffold', level: 'warn', text: `scaffolded file removed: ${f}` });
+    }
+    if (!opts.offline) {
+        const remote = deps.remote ?? createRemote();
+        const oidc = await remote.probe(new URL('/.well-known/openid-configuration', project.auth_origin).toString());
+        checks.push(oidc.ok
+            ? {
+                id: 'auth',
+                level: 'ok',
+                text: `authorization server reachable (${project.auth_origin})`,
+            }
+            : {
+                id: 'auth',
+                level: 'bad',
+                text: `authorization server ${project.auth_origin}: ${oidc.error ?? `HTTP ${oidc.status}`}`,
+            });
+        const api = await remote.probe(docsUrl(project.api_base, 'en'));
+        if (api.ok)
+            checks.push({ id: 'api', level: 'ok', text: `API reachable (${project.api_base})` });
+        else if (api.empty404)
+            checks.push({ id: 'api', level: 'bad', text: `API ${project.api_base}: ${EMPTY_404_HINT}` });
+        else
+            checks.push({
+                id: 'api',
+                level: 'bad',
+                text: `API ${project.api_base}: ${api.error ?? `HTTP ${api.status}`}`,
+            });
+    }
+    return checks;
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,18 @@
+import { type ParsedArgs } from '../args.js';
+import { type StoredAuth } from '../auth-store.js';
+import { type DeveloperApi } from '../developer-api.js';
+import { type Reporter } from '../output.js';
+import { type Remote } from '../remote.js';
+export declare const DEFAULT_CALLBACK = "http://127.0.0.1:3000/auth/aipay/callback";
+export declare const SDK_PACKAGE = "@coswic/aipay-sdk";
+export interface InitDeps {
+    remote?: Remote;
+    /** Injected for tests: the developer login (null = signed out). */
+    login?: StoredAuth | null;
+    developerApi?: DeveloperApi;
+    now?: () => Date;
+    /** Runs the package-manager install; returns exit code. Injected for tests. */
+    run?: (cmd: string[], cwd: string, quiet: boolean) => number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function runInit(args: ParsedArgs, out: Reporter, deps?: InitDeps): Promise<number>;

package/dist/commands/init.js

@@ -0,0 +1,265 @@
+/**
+ * `aipay init --app <client_id> --auth <origin> --api <base> [--dir] [--callback]
+ *              [--name] [--json] [--dry-run] [--no-install]`
+ *
+ * Links the project to an app and scaffolds the integration. Idempotent: rerunning
+ * updates .aipay/project.json + .env.local and never overwrites files it did not write
+ * this run. Linking an existing app uses public client info.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { AGENT_GUIDE_FILE, agentGuide } from '../agent-guide.js';
+import { flagBool, flagString } from '../args.js';
+import { createAuthStore } from '../auth-store.js';
+import { detectProject, installCommand } from '../detect.js';
+import { openDeveloperApi } from '../developer-api.js';
+import { parseCallback } from '../loopback.js';
+import { CliError, EXIT } from '../output.js';
+import { ENV_FILE, ENV_KEYS, FRAMEWORKS, isFramework, mergeEnvFile, mergeGitignore, readProject, VITE_ENV_KEYS, writeProject, } from '../project.js';
+import { createRemote, docsUrl, EMPTY_404_HINT } from '../remote.js';
+import { reportSetupEvent } from '../setup-events.js';
+import { scaffoldFiles } from '../templates.js';
+import { cliVersion } from '../version.js';
+import { createApp } from './apps.js';
+export const DEFAULT_CALLBACK = 'http://127.0.0.1:3000/auth/aipay/callback';
+export const SDK_PACKAGE = '@coswic/aipay-sdk';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function runInit(args, out, deps = {}) {
+    const env = deps.env ?? process.env;
+    const dir = resolve(flagString(args.flags, 'dir') ?? '.');
+    const existing = safeReadProject(dir);
+    const callback = flagString(args.flags, 'callback') ?? existing?.callback ?? DEFAULT_CALLBACK;
+    // Signed in as a developer? Then --auth/--api can come from the login, and --create can
+    // make the app first (Idempotency-Key: rerunning never makes a second app).
+    const login = deps.login === undefined ? createAuthStore(env).load() : deps.login;
+    let clientId = flagString(args.flags, 'app');
+    let createdName = null;
+    const createName = flagString(args.flags, 'create');
+    if (createName) {
+        if (clientId)
+            throw new CliError('usage', 'pass either --app <client_id> or --create <name>, not both', EXIT.usage);
+        if (!login)
+            throw new CliError('not_logged_in', '--create needs a developer sign-in first: `aipay login --api <base>`', EXIT.problem);
+        const api = deps.developerApi ?? (await openDeveloperApi(createAuthStore(env)));
+        const created = await createApp(api, {
+            name: createName,
+            callback,
+            key: flagString(args.flags, 'key'),
+        });
+        clientId = created.client_id;
+        createdName = createName;
+        out.line('ok', `${created.replayed ? 'app already existed' : 'created app'} "${createName}" — client_id ${clientId}`);
+    }
+    if (!clientId)
+        throw new CliError('usage', 'missing --app <client_id> (from the Console, after creating the app) or --create <name>', EXIT.usage);
+    if (!UUID_RE.test(clientId))
+        throw new CliError('usage', `--app must be the app's client_id (a UUID), got "${clientId}"`, EXIT.usage);
+    const authOrigin = originOf(flagString(args.flags, 'auth') ?? existing?.auth_origin ?? login?.auth_origin ?? null, '--auth');
+    const apiBase = originOf(flagString(args.flags, 'api') ?? existing?.api_base ?? login?.api_base ?? null, '--api');
+    const target = parseCallback(callback); // throws on non-loopback
+    const dryRun = flagBool(args.flags, 'dry-run');
+    const install = flagBool(args.flags, 'install', true);
+    const name = flagString(args.flags, 'name') ?? createdName ?? existing?.app.name ?? null;
+    const remote = deps.remote ?? createRemote();
+    const now = (deps.now ?? (() => new Date()))();
+    const det = detectProject(dir);
+    // --framework: detection can be wrong (monorepos, unusual layouts) — the developer/agent may
+    // name the target; the value must be one we have templates for.
+    const forced = flagString(args.flags, 'framework');
+    if (forced !== undefined && forced !== null) {
+        if (!isFramework(forced))
+            throw new CliError('usage', `--framework must be one of ${FRAMEWORKS.join(', ')} (got "${forced}")`, EXIT.usage);
+        det.framework = forced;
+    }
+    out.line('info', `project: ${dir}`);
+    out.kv('package.json', det.hasPackageJson ? 'found' : 'none (plain directory)');
+    out.kv('manager', det.packageManager ?? '—');
+    out.kv('framework', `${det.framework ?? '—'}${forced ? ' (from --framework)' : ''}`);
+    out.kv('language', det.typescript ? 'TypeScript' : 'JavaScript');
+    out.kv('callback', callback);
+    const plan = [];
+    const writes = [];
+    // 1. project file
+    const project = {
+        version: 1,
+        app: { client_id: clientId, name },
+        auth_origin: authOrigin,
+        api_base: apiBase,
+        callback,
+        scaffold: {
+            package_manager: det.packageManager,
+            framework: det.framework,
+            files: existing?.scaffold.files ?? [],
+        },
+        linked_at: now.toISOString(),
+    };
+    // 2. env file (merge)
+    const envPath = join(dir, ENV_FILE);
+    const envBefore = existsSync(envPath) ? readFileSync(envPath, 'utf8') : null;
+    const envMerged = mergeEnvFile(envBefore, {
+        [ENV_KEYS.clientId]: clientId,
+        [ENV_KEYS.authOrigin]: authOrigin,
+        [ENV_KEYS.apiBase]: apiBase,
+        [ENV_KEYS.callback]: callback,
+        // Vite exposes only VITE_-prefixed values to the browser: same four public values, aliased.
+        ...(det.framework === 'vite'
+            ? {
+                [VITE_ENV_KEYS.clientId]: clientId,
+                [VITE_ENV_KEYS.authOrigin]: authOrigin,
+                [VITE_ENV_KEYS.apiBase]: apiBase,
+                [VITE_ENV_KEYS.callback]: callback,
+            }
+            : {}),
+    });
+    if (envMerged.changed.length) {
+        plan.push({
+            path: ENV_FILE,
+            action: envBefore === null ? 'write' : 'update',
+            why: envMerged.changed.join(', '),
+        });
+        writes.push({ path: envPath, content: envMerged.content });
+    }
+    else
+        plan.push({ path: ENV_FILE, action: 'skip', why: 'up to date' });
+    // 3. gitignore (append)
+    const giPath = join(dir, '.gitignore');
+    const giBefore = existsSync(giPath) ? readFileSync(giPath, 'utf8') : null;
+    const gi = mergeGitignore(giBefore, [ENV_FILE, '.aipay/local/']);
+    if (gi.added.length) {
+        plan.push({
+            path: '.gitignore',
+            action: giBefore === null ? 'write' : 'update',
+            why: gi.added.join(', '),
+        });
+        writes.push({ path: giPath, content: gi.content });
+    }
+    else
+        plan.push({ path: '.gitignore', action: 'skip', why: 'already ignores them' });
+    // 4. scaffold (never overwrite)
+    const scaffolded = [];
+    if (det.hasPackageJson && det.framework) {
+        for (const f of scaffoldFiles({
+            framework: det.framework,
+            typescript: det.typescript,
+            srcDir: det.srcDir,
+            callbackPath: target.path,
+        })) {
+            const abs = join(dir, f.path);
+            if (existsSync(abs))
+                plan.push({ path: f.path, action: 'skip', why: 'exists' });
+            else {
+                plan.push({ path: f.path, action: 'write' });
+                writes.push({ path: abs, content: f.content });
+                scaffolded.push(f.path);
+            }
+        }
+    }
+    else
+        plan.push({ path: '(scaffold)', action: 'skip', why: 'no package.json — link only' });
+    project.scaffold.files = Array.from(new Set([...project.scaffold.files, ...scaffolded]));
+    // 5. docs → agent guide
+    const docs = await remote.fetchDocs(apiBase, 'en');
+    if (docs.empty404)
+        out.line('warn', EMPTY_404_HINT);
+    else if (!docs.markdown)
+        out.line('warn', `docs fetch failed (${docs.status}); guide written without the docs body`);
+    const guidePath = join(dir, AGENT_GUIDE_FILE);
+    writes.push({
+        path: guidePath,
+        content: agentGuide({
+            project,
+            scaffolded: project.scaffold.files,
+            docsMarkdown: docs.markdown,
+            docsUrl: docsUrl(apiBase, 'en'),
+        }),
+    });
+    plan.push({ path: AGENT_GUIDE_FILE, action: existsSync(guidePath) ? 'update' : 'write' });
+    plan.push({ path: '.aipay/project.json', action: existing ? 'update' : 'write' });
+    // 6. install
+    let installCmd = null;
+    if (det.hasPackageJson && !det.sdkInstalled && install && det.packageManager)
+        installCmd = installCommand(det.packageManager, SDK_PACKAGE);
+    out.blank();
+    for (const p of plan)
+        out.line(p.action === 'skip' ? 'info' : 'ok', `${p.action.padEnd(6)} ${p.path}${p.why ? `  (${p.why})` : ''}`);
+    if (installCmd)
+        out.line('info', `${dryRun ? 'would run' : 'run   '} ${installCmd.join(' ')}`);
+    else if (det.hasPackageJson && det.sdkInstalled)
+        out.line('info', `skip   ${SDK_PACKAGE} (already a dependency)`);
+    let installExit = null;
+    if (!dryRun) {
+        for (const w of writes) {
+            mkdirSync(dirname(w.path), { recursive: true });
+            writeFileSync(w.path, w.content);
+        }
+        writeProject(dir, project);
+        if (installCmd) {
+            const run = deps.run ?? defaultRun;
+            // --json: the install's own output must not land in stdout (it would corrupt the document)
+            installExit = run(installCmd, dir, out.json);
+            if (installExit !== 0)
+                out.line('bad', `install failed (exit ${installExit}); run it yourself: ${installCmd.join(' ')}`);
+            else
+                out.line('ok', `installed ${SDK_PACKAGE}`);
+        }
+    }
+    // C2 setup session：登入狀態下回報 init（Console 的「等待工具連線」變綠）；失敗不影響結果
+    let reported = false;
+    if (!dryRun)
+        reported = await reportSetupEvent(clientId, 'cli.init', {
+            framework: det.framework ?? 'none',
+            package_manager: det.packageManager ?? 'none',
+            typescript: det.typescript,
+            files: project.scaffold.files,
+            cli_version: cliVersion(),
+        }, out, env);
+    out.blank();
+    out.line('ok', dryRun ? 'dry run — nothing written' : `linked to app ${name ?? clientId}`);
+    out.line('info', 'next: run `aipay test` — it receives the callback on a free loopback port, so your dev server can keep running');
+    out.result({
+        ok: installExit === null || installExit === 0,
+        dry_run: dryRun,
+        dir,
+        project,
+        detection: det,
+        plan,
+        install: installCmd ? { command: installCmd, exit: installExit } : null,
+        docs: { fetched: !!docs.markdown, empty404: docs.empty404, status: docs.status },
+        reported,
+    });
+    return installExit === null || installExit === 0 ? EXIT.ok : EXIT.problem;
+}
+function safeReadProject(dir) {
+    try {
+        return readProject(dir);
+    }
+    catch {
+        return null;
+    }
+}
+function originOf(v, flag) {
+    if (!v)
+        throw new CliError('usage', `missing ${flag} <url> (the Console prompt lists both the authorization server and the API base)`, EXIT.usage);
+    let u;
+    try {
+        u = new URL(v);
+    }
+    catch {
+        throw new CliError('usage', `${flag} must be a URL, got "${v}"`, EXIT.usage);
+    }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:')
+        throw new CliError('usage', `${flag} must be http(s)`, EXIT.usage);
+    return u.origin;
+}
+function defaultRun(cmd, cwd, quiet) {
+    const [bin, ...rest] = cmd;
+    const r = spawnSync(bin, rest, {
+        cwd,
+        stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+        encoding: 'utf8',
+    });
+    if (quiet && r.status !== 0)
+        process.stderr.write(`${r.stdout ?? ''}${r.stderr ?? ''}`);
+    return r.status ?? 1;
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,34 @@
+import { type ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export interface CliConfig {
+    client_id: string;
+    auth_origin: string;
+    scopes: string[];
+    redirect_path: string;
+    audience: string;
+    /** A2: the server allows the device grant for the CLI (older APIs omit it = false). */
+    device_authorization: boolean;
+}
+export interface LoginDeps {
+    env?: NodeJS.ProcessEnv;
+    open?: (url: string) => boolean;
+    onAuthorizeUrl?: (url: string) => void;
+    /** A2: called with the verification URL and the user code (tests / drivers). */
+    onDeviceCode?: (info: {
+        url: string;
+        userCode: string;
+    }) => void;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function fetchCliConfig(apiBase: string): Promise<CliConfig>;
+/** Resolve the API base: flag → env → linked project → error. */
+export declare function resolveApiBase(args: ParsedArgs, env: NodeJS.ProcessEnv, dir: string): string;
+/** Authorization URL for the management login. The SDK's createConnectUrl fixes the
+ * audience to aipay-api (apps), so the CLI builds its own with the developer audience. */
+export declare function managementAuthorizeUrl(cfg: CliConfig, redirectUri: string): {
+    url: string;
+    state: string;
+    codeVerifier: string;
+};
+export declare function runLogin(args: ParsedArgs, out: Reporter, deps?: LoginDeps): Promise<number>;

package/dist/commands/login.js

@@ -0,0 +1,187 @@
+/**
+ * `aipay login [--api <base>] [--device] [--no-open] [--timeout <s>] [--json]`
+ *
+ * Developer sign-in for the CLI itself (consultant §10.2, auth model A): the CLI is a
+ * first-party public client. It asks the API for its client config, then either
+ *   A1 — runs loopback PKCE against the authorization server (a browser on this machine), or
+ *   A2 — `--device`: RFC 8628 device authorization (no browser here: SSH boxes, containers,
+ *        CI) — prints a URL + short code, the developer approves on any device, the CLI polls.
+ * Both use audience aipay-developer-api and the management scope, and keep the tokens in
+ * the OS keychain (or a 0600 file). No app secrets exist.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { exchangeCode, getUserInfo } from '@coswic/aipay-sdk';
+import { flagBool, flagString } from '../args.js';
+import { createAuthStore } from '../auth-store.js';
+import { openBrowser } from '../browser.js';
+import { pollDeviceToken, requestDeviceCode } from '../device.js';
+import { startLoopback } from '../loopback.js';
+import { isEmpty404 } from '../network.js';
+import { CliError, EXIT } from '../output.js';
+import { readProject } from '../project.js';
+import { EMPTY_404_HINT } from '../remote.js';
+export async function fetchCliConfig(apiBase) {
+    const f = fetch;
+    let res;
+    try {
+        res = await f(new URL('/v1/cli/config', apiBase));
+    }
+    catch (e) {
+        throw new CliError('network', `cannot reach ${apiBase}: ${e.message}. Check the endpoint URL and network connectivity, then retry.`, EXIT.remote);
+    }
+    const text = await res.text();
+    if (isEmpty404(res.status, text))
+        throw new CliError('empty_404', EMPTY_404_HINT, EXIT.remote);
+    if (res.status === 404)
+        throw new CliError('cli_disabled', `${apiBase} does not offer CLI sign-in (developer management is not enabled there)`, EXIT.remote);
+    if (!res.ok)
+        throw new CliError('remote', `GET /v1/cli/config → HTTP ${res.status}`, EXIT.remote);
+    const cfg = JSON.parse(text);
+    if (typeof cfg.client_id !== 'string' ||
+        typeof cfg.auth_origin !== 'string' ||
+        !Array.isArray(cfg.scopes))
+        throw new CliError('remote', 'unexpected /v1/cli/config shape', EXIT.remote);
+    return {
+        client_id: cfg.client_id,
+        auth_origin: cfg.auth_origin,
+        scopes: cfg.scopes.filter((s) => typeof s === 'string'),
+        redirect_path: typeof cfg.redirect_path === 'string' ? cfg.redirect_path : '/cli/callback',
+        audience: typeof cfg.audience === 'string' ? cfg.audience : 'aipay-developer-api',
+        device_authorization: cfg.device_authorization === true,
+    };
+}
+/** Resolve the API base: flag → env → linked project → error. */
+export function resolveApiBase(args, env, dir) {
+    const v = flagString(args.flags, 'api') ?? env.AIPAY_API_BASE ?? readProjectSafe(dir)?.api_base ?? null;
+    if (!v)
+        throw new CliError('usage', 'which AI-Pay? pass --api <api base> (the Console prompt lists it) or set AIPAY_API_BASE', EXIT.usage);
+    try {
+        return new URL(v).origin;
+    }
+    catch {
+        throw new CliError('usage', `--api must be a URL, got "${v}"`, EXIT.usage);
+    }
+}
+function readProjectSafe(dir) {
+    try {
+        return readProject(dir);
+    }
+    catch {
+        return null;
+    }
+}
+/** Authorization URL for the management login. The SDK's createConnectUrl fixes the
+ * audience to aipay-api (apps), so the CLI builds its own with the developer audience. */
+export function managementAuthorizeUrl(cfg, redirectUri) {
+    const codeVerifier = randomBytes(32).toString('base64url');
+    const state = randomBytes(16).toString('base64url');
+    const challenge = createHash('sha256').update(codeVerifier).digest('base64url');
+    const u = new URL('/oauth2/auth', cfg.auth_origin);
+    u.searchParams.set('client_id', cfg.client_id);
+    u.searchParams.set('response_type', 'code');
+    u.searchParams.set('scope', cfg.scopes.join(' '));
+    u.searchParams.set('state', state);
+    u.searchParams.set('redirect_uri', redirectUri);
+    u.searchParams.set('code_challenge', challenge);
+    u.searchParams.set('code_challenge_method', 'S256');
+    u.searchParams.set('audience', cfg.audience);
+    return { url: u.toString(), state, codeVerifier };
+}
+export async function runLogin(args, out, deps = {}) {
+    const env = deps.env ?? process.env;
+    const dir = flagString(args.flags, 'dir') ?? '.';
+    const apiBase = resolveApiBase(args, env, dir);
+    const cfg = await fetchCliConfig(apiBase);
+    const timeoutS = Number(flagString(args.flags, 'timeout') ?? '300');
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    if (flagBool(args.flags, 'device', false))
+        return deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps);
+    const loop = await startLoopback({ host: '127.0.0.1', port: 0, path: cfg.redirect_path }, { timeoutMs: timeoutS * 1000 });
+    const redirectUri = `http://127.0.0.1:${loop.port}${cfg.redirect_path}`;
+    const { url, state, codeVerifier } = managementAuthorizeUrl(cfg, redirectUri);
+    out.line('info', `signing in to ${apiBase} as a developer — approve "AI-Pay CLI" in your browser:\n\n  ${url}\n`);
+    if (cfg.device_authorization)
+        out.line('info', 'no browser on this machine? run `aipay login --device` instead');
+    if (out.json)
+        out.debug(`authorize_url ${url}`);
+    deps.onAuthorizeUrl?.(url);
+    if (flagBool(args.flags, 'open', true))
+        (deps.open ?? openBrowser)(url);
+    try {
+        const cb = await loop.waitForCallback;
+        const u = new URL(cb.url);
+        const err = u.searchParams.get('error');
+        if (err)
+            throw new CliError('denied', `authorization failed: ${err} ${u.searchParams.get('error_description') ?? ''}`.trim(), EXIT.remote);
+        if (u.searchParams.get('state') !== state)
+            throw new CliError('state', 'state mismatch — restart `aipay login`', EXIT.remote);
+        const code = u.searchParams.get('code');
+        if (!code)
+            throw new CliError('remote', 'callback without a code', EXIT.remote);
+        const tokens = await exchangeCode({ hydraPublicUrl: cfg.auth_origin, clientId: cfg.client_id, redirectUri }, { code, codeVerifier, fetchImpl });
+        return finishLogin({
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresInSeconds: tokens.expiresInSeconds,
+            scope: tokens.scope,
+        }, cfg, apiBase, fetchImpl, env, out);
+    }
+    finally {
+        await loop.close();
+    }
+}
+/** A2 (RFC 8628): print URL + code, poll until approved on another device. */
+async function deviceLogin(cfg, apiBase, timeoutS, fetchImpl, env, out, deps) {
+    if (!cfg.device_authorization)
+        throw new CliError('device_unsupported', `${apiBase} does not offer device sign-in yet — run \`aipay login\` on a machine with a browser`, EXIT.remote);
+    const client = {
+        authOrigin: cfg.auth_origin,
+        clientId: cfg.client_id,
+        scopes: cfg.scopes,
+        audience: cfg.audience,
+    };
+    const auth = await requestDeviceCode(client, fetchImpl);
+    const url = auth.verificationUriComplete ?? auth.verificationUri;
+    out.line('info', `signing in to ${apiBase} as a developer — on any device with a browser, open:\n\n  ${url}\n\n  and enter the code:  ${auth.userCode}\n`);
+    out.line('info', `waiting for approval (the code expires in ${Math.round(auth.expiresInSeconds / 60)} min)…`);
+    if (out.json) {
+        out.debug(`device_url ${url}`);
+        out.debug(`user_code ${auth.userCode}`);
+    }
+    deps.onDeviceCode?.({ url, userCode: auth.userCode });
+    const tokens = await pollDeviceToken(client, { ...auth, expiresInSeconds: Math.min(auth.expiresInSeconds, timeoutS) }, { fetchImpl, ...(deps.sleep ? { sleep: deps.sleep } : {}) });
+    return finishLogin(tokens, cfg, apiBase, fetchImpl, env, out);
+}
+/** Shared tail of both flows: identity → keychain/file → summary. */
+async function finishLogin(tokens, cfg, apiBase, fetchImpl, env, out) {
+    const user = await getUserInfo({ hydraPublicUrl: cfg.auth_origin }, tokens.accessToken, {
+        fetchImpl,
+    });
+    const store = createAuthStore(env);
+    const auth = {
+        api_base: apiBase,
+        auth_origin: cfg.auth_origin,
+        client_id: cfg.client_id,
+        access_token: tokens.accessToken,
+        refresh_token: tokens.refreshToken,
+        expires_at: Date.now() + tokens.expiresInSeconds * 1000,
+        scope: tokens.scope,
+        email: user.email ?? null,
+        sub: user.sub,
+    };
+    store.save(auth);
+    out.line('ok', `signed in as ${auth.email ?? auth.sub}`);
+    out.line('info', `tokens kept in ${store.where}${store.kind === 'file' ? ' — no keychain tool found; the file is readable only by you' : ''}`);
+    if (!tokens.refreshToken)
+        out.line('warn', 'no refresh token was granted; you will need to sign in again when this one expires');
+    out.result({
+        ok: true,
+        api_base: apiBase,
+        email: auth.email,
+        sub: auth.sub,
+        scope: auth.scope,
+        store: store.kind,
+        expires_at: auth.expires_at,
+    });
+    return EXIT.ok;
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,6 @@
+/** `aipay whoami` and `aipay logout`. */
+import type { ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export declare function runWhoami(_args: ParsedArgs, out: Reporter, env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function runLogout(_args: ParsedArgs, out: Reporter, env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function requireLogin(env: NodeJS.ProcessEnv): void;