@stigg/terminal 0.0.1-alpha

package/dist/headless/init-phase1.js

@@ -0,0 +1,173 @@
+import pc from 'picocolors';
+import { listAccounts, listApiKeys, listEnvironments } from '../api/client.js';
+import { authenticate } from '../auth/oauth.js';
+import { loadSession, saveSession } from '../auth/storage.js';
+import { finalizeInitSetup } from './init-phase2.js';
+import { createReporter, fmt } from './reporter.js';
+const NEXT_STEP_HINT = [
+    'npx @stigg/terminal init --headless \\',
+    '    --account-id <id> \\',
+    '    --environment-id <id> \\',
+    '    --api-key-id <id>',
+].join('\n');
+export async function runInitPhase1(opts = {}) {
+    const reporter = createReporter({ json: opts.json });
+    const session = await loadOrAuthenticate(opts.forceLogin === true, !!opts.json, reporter, opts.callbackPort);
+    const accounts = await listAccounts(session.access_token);
+    // Build the public listing (no key values) AND keep raw envs/keys cached for
+    // the auto-pick path, so we don't re-fetch.
+    const rawEnvsByAccount = new Map();
+    const rawKeysByEnv = new Map();
+    const listing = {
+        user: session.email,
+        accounts: [],
+        nextStep: NEXT_STEP_HINT.replace(/\\\n\s+/g, ' '),
+    };
+    for (const acc of accounts) {
+        const envs = await listEnvironments(session.access_token, acc.id);
+        rawEnvsByAccount.set(acc.id, envs);
+        const accountEntry = {
+            id: acc.id,
+            name: acc.displayName,
+            environments: [],
+        };
+        for (const env of envs) {
+            const keys = await listApiKeys(session.access_token, acc.id, env.id);
+            rawKeysByEnv.set(env.id, keys);
+            accountEntry.environments.push({
+                id: env.id,
+                name: env.name,
+                slug: env.slug,
+                apiKeys: keys.map((k) => ({
+                    id: k.id,
+                    name: k.name,
+                    lastFour: k.lastFour,
+                    keyType: k.keyType,
+                    createdAt: k.createdAt,
+                })),
+            });
+        }
+        listing.accounts.push(accountEntry);
+    }
+    // Auto-pick path: exactly 1 account, 1 env in that account, 1 key in that env.
+    const autoPick = pickSoleTuple(accounts, rawEnvsByAccount, rawKeysByEnv);
+    if (autoPick) {
+        if (!opts.json) {
+            reporter.human(fmt.ok('Auto-selected', `${autoPick.account.displayName} / ${autoPick.env.name} / ${autoPick.apiKey.name}`));
+            reporter.human('');
+        }
+        const { ok } = await finalizeInitSetup({
+            session,
+            account: { id: autoPick.account.id, displayName: autoPick.account.displayName },
+            env: autoPick.env,
+            envs: autoPick.envs,
+            apiKey: autoPick.apiKey,
+        }, {
+            client: opts.client,
+            all: opts.all,
+            installSkills: opts.installSkills !== false,
+            json: opts.json,
+        });
+        process.exit(ok ? 0 : 1);
+    }
+    if (accounts.length === 0) {
+        reporter.stderr(`${pc.red('✗')} No accounts found for this user.`);
+        if (!opts.json) {
+            reporter.human('');
+        }
+        reporter.emit(listing);
+        process.exit(1);
+    }
+    if (!opts.json) {
+        printHumanListing(reporter, listing);
+    }
+    reporter.emit(listing);
+}
+async function loadOrAuthenticate(forceLogin, json, reporter, callbackPort) {
+    if (!forceLogin) {
+        const existing = await loadSession();
+        if (existing && existing.expires_at && existing.expires_at > Date.now()) {
+            if (!json) {
+                reporter.human(fmt.heading('init · authenticate'));
+                reporter.human(fmt.ok(`Using saved session for ${existing.email}`));
+                reporter.human('');
+            }
+            return existing;
+        }
+    }
+    if (!json) {
+        reporter.human(fmt.heading('init · authenticate'));
+        reporter.human('Opening browser for sign-in…');
+    }
+    const session = await authenticate({
+        port: callbackPort,
+        onAuthUrlReady: (url) => {
+            if (!json) {
+                reporter.human(`If your browser does not open, visit:\n  ${pc.cyan(url)}`);
+            }
+        },
+    });
+    const sessionPath = await saveSession(session);
+    if (!json) {
+        reporter.human(fmt.ok(`Signed in as ${session.email}`, sessionPath));
+        reporter.human('');
+    }
+    return session;
+}
+function pickSoleTuple(accounts, rawEnvsByAccount, rawKeysByEnv) {
+    if (accounts.length !== 1)
+        return null;
+    const account = accounts[0];
+    const envs = rawEnvsByAccount.get(account.id) ?? [];
+    if (envs.length !== 1)
+        return null;
+    const env = envs[0];
+    const keys = rawKeysByEnv.get(env.id) ?? [];
+    if (keys.length !== 1)
+        return null;
+    const apiKey = keys[0];
+    return { account, env, envs, apiKey };
+}
+function printHumanListing(reporter, listing) {
+    if (listing.accounts.length === 0) {
+        reporter.human(pc.yellow('No accounts found for this user.'));
+        return;
+    }
+    reporter.human('Accounts:');
+    for (const acc of listing.accounts) {
+        reporter.human(`  ${pc.cyan(acc.id)}  ${acc.name}`);
+    }
+    for (const acc of listing.accounts) {
+        reporter.human('');
+        reporter.human(`Environments (${pc.cyan(acc.id)}):`);
+        if (acc.environments.length === 0) {
+            reporter.human(`  ${pc.dim('(none)')}`);
+            continue;
+        }
+        for (const env of acc.environments) {
+            const slug = env.slug ? `  ${pc.dim(`(slug: ${env.slug})`)}` : '';
+            reporter.human(`  ${pc.cyan(env.id.padEnd(20))}  ${env.name}${slug}`);
+        }
+        for (const env of acc.environments) {
+            reporter.human('');
+            reporter.human(`API keys (${pc.cyan(env.id)}):`);
+            if (env.apiKeys.length === 0) {
+                reporter.human(`  ${pc.dim('(none)')}`);
+                continue;
+            }
+            for (const k of env.apiKeys) {
+                reporter.human(`  ${pc.cyan(k.id.padEnd(20))}  ` +
+                    `${k.name.padEnd(24)}  ` +
+                    `sk_***...${k.lastFour}  ` +
+                    `${pc.dim(k.keyType.padEnd(8))}  ` +
+                    `${pc.dim(k.createdAt)}`);
+            }
+        }
+    }
+    reporter.human('');
+    reporter.human('Next step — pick one account / env / api-key and run:');
+    reporter.human('');
+    for (const line of NEXT_STEP_HINT.split('\n')) {
+        reporter.human(`  ${line}`);
+    }
+}

package/dist/headless/init-phase2.d.ts

@@ -0,0 +1,36 @@
+import type { AuthSession } from '../auth/oauth.js';
+import type { Account, ApiKey, Environment } from '../types.js';
+export interface PhaseTwoOptions {
+    accountId: string;
+    environmentId: string;
+    apiKeyId: string;
+    client?: string[];
+    all?: boolean;
+    installSkills: boolean;
+    json?: boolean;
+}
+export interface FinalizeContext {
+    session: AuthSession;
+    account: Account;
+    env: Environment;
+    envs: Environment[];
+    apiKey: ApiKey;
+}
+export interface FinalizeOptions {
+    client?: string[];
+    all?: boolean;
+    installSkills: boolean;
+    json?: boolean;
+}
+export declare function runInitPhase2(opts: PhaseTwoOptions): Promise<void>;
+/**
+ * Complete the setup using fully-resolved (account, env, apiKey).
+ * Used by `runInitPhase2` after validating CLI flags, and by `runInitPhase1`
+ * after auto-picking when there's exactly one of each.
+ *
+ * Does NOT call `process.exit`. Returns the success flag for the caller to
+ * decide on exit code.
+ */
+export declare function finalizeInitSetup(ctx: FinalizeContext, opts: FinalizeOptions): Promise<{
+    ok: boolean;
+}>;

package/dist/headless/init-phase2.js

@@ -0,0 +1,150 @@
+import pc from 'picocolors';
+import { listAccounts, listApiKeys, listEnvironments } from '../api/client.js';
+import { loadSession } from '../auth/storage.js';
+import { getClientById } from '../mcp/clients/index.js';
+import { saveSetup } from '../setup/storage.js';
+import { detectHostAgent } from './host-agent.js';
+import { nextStepPrompt, restartHint } from './next-step-prompt.js';
+import { HeadlessOptionsError, resolveClientSelectionForInit, } from './options.js';
+import { createReporter, fmt } from './reporter.js';
+import { runHeadlessSetup } from './setup.js';
+export async function runInitPhase2(opts) {
+    const session = await loadSession();
+    if (!session) {
+        throw new HeadlessOptionsError('No saved session. Run `terminal init --headless` first to authenticate.');
+    }
+    const accounts = await listAccounts(session.access_token);
+    const account = accounts.find((a) => a.id === opts.accountId);
+    if (!account) {
+        throw new HeadlessOptionsError(`account-id "${opts.accountId}" not found. Available: ${accounts.map((a) => a.id).join(', ') || '(none)'}`);
+    }
+    const envs = await listEnvironments(session.access_token, account.id);
+    const env = envs.find((e) => e.id === opts.environmentId);
+    if (!env) {
+        throw new HeadlessOptionsError(`environment-id "${opts.environmentId}" not found in account ${account.id}. Available: ${envs.map((e) => e.id).join(', ') || '(none)'}`);
+    }
+    const keys = await listApiKeys(session.access_token, account.id, env.id);
+    const apiKey = keys.find((k) => k.id === opts.apiKeyId);
+    if (!apiKey) {
+        throw new HeadlessOptionsError(`api-key-id "${opts.apiKeyId}" not found in env ${env.id}. Available: ${keys.map((k) => k.id).join(', ') || '(none)'}`);
+    }
+    const { ok } = await finalizeInitSetup({ session, account: { id: account.id, displayName: account.displayName }, env, envs, apiKey }, {
+        client: opts.client,
+        all: opts.all,
+        installSkills: opts.installSkills,
+        json: opts.json,
+    });
+    process.exit(ok ? 0 : 1);
+}
+/**
+ * Complete the setup using fully-resolved (account, env, apiKey).
+ * Used by `runInitPhase2` after validating CLI flags, and by `runInitPhase1`
+ * after auto-picking when there's exactly one of each.
+ *
+ * Does NOT call `process.exit`. Returns the success flag for the caller to
+ * decide on exit code.
+ */
+export async function finalizeInitSetup(ctx, opts) {
+    const reporter = createReporter({ json: opts.json });
+    const { session, account, env, envs, apiKey } = ctx;
+    if (!apiKey.value) {
+        throw new HeadlessOptionsError(`api-key "${apiKey.id}" did not return a token value from the API`);
+    }
+    if (!opts.json) {
+        reporter.human(fmt.heading('init'));
+        reporter.human(`Account:     ${pc.cyan(account.displayName)}  ${pc.dim(account.id)}`);
+        reporter.human(`Environment: ${pc.cyan(env.name)}  ${pc.dim(env.id)}`);
+        reporter.human(`API key:     ${pc.cyan(apiKey.name)}  ${pc.dim(`sk_***...${apiKey.lastFour}`)}`);
+        reporter.human('');
+    }
+    const hostAgent = detectHostAgent();
+    const clients = await resolveClientsWithHostFallback({ client: opts.client, all: opts.all }, hostAgent, reporter);
+    const result = await runHeadlessSetup({
+        apiKey: apiKey.value,
+        clients,
+        installSkills: opts.installSkills,
+    }, {
+        onClientResult: (write, { name }) => {
+            if (!opts.json)
+                reporter.human(fmt.ok(name, write.path));
+        },
+        onClientFail: (_id, name, reason) => {
+            reporter.stderr(fmt.fail(name, reason));
+        },
+        onSkillsResult: (skillsResult) => {
+            if (skillsResult.claudeCode) {
+                if (skillsResult.claudeCode.ok) {
+                    if (!opts.json)
+                        reporter.human(fmt.ok('Claude Code plugin', 'stigg@stigg-marketplace'));
+                }
+                else {
+                    reporter.stderr(fmt.fail('Claude Code plugin', skillsResult.claudeCode.reason));
+                }
+            }
+            if (skillsResult.agentSkills) {
+                if (skillsResult.agentSkills.ok) {
+                    if (!opts.json)
+                        reporter.human(fmt.ok('Agent skills', 'stiggio/skills'));
+                }
+                else {
+                    reporter.stderr(fmt.fail('Agent skills', skillsResult.agentSkills.reason));
+                }
+            }
+        },
+    });
+    let setupPath;
+    if (result.ok) {
+        const writtenClients = result.writes
+            .filter((w) => w.written && w.client !== undefined)
+            .map((w) => w.client);
+        const setupInfo = {
+            user: session.email,
+            account: account.displayName,
+            accountId: account.id,
+            environment: env.name,
+            environmentId: env.id,
+            credentialLabel: `${apiKey.name} · sk_***${apiKey.lastFour}`,
+            environments: envs,
+            clients: writtenClients,
+            completedAt: new Date().toISOString(),
+        };
+        setupPath = await saveSetup(setupInfo);
+    }
+    const restart = restartHint(hostAgent);
+    const prompt = nextStepPrompt(env.name);
+    if (!opts.json) {
+        if (result.ok) {
+            reporter.human('');
+            if (setupPath)
+                reporter.human(fmt.ok('Saved setup', setupPath));
+            reporter.human('Done.');
+            reporter.human('');
+            reporter.human(`⚠  ${restart}`);
+        }
+        reporter.human(prompt);
+    }
+    reporter.emit({
+        ok: result.ok,
+        writes: result.writes,
+        skipped: result.skipped,
+        skillsInstall: result.skillsInstall,
+        setupPath,
+        hostAgent: hostAgent ? { id: hostAgent.id, name: hostAgent.name } : null,
+        restartHint: restart,
+        nextStepPrompt: prompt,
+    });
+    return { ok: result.ok };
+}
+async function resolveClientsWithHostFallback(flags, hostAgent, reporter) {
+    const hasExplicit = (flags.client?.length ?? 0) > 0 || flags.all === true;
+    if (hasExplicit)
+        return resolveClientSelectionForInit(flags, null);
+    if (hostAgent) {
+        const client = getClientById(hostAgent.id);
+        if (client && (await client.isClientSupported())) {
+            return { kind: 'explicit', ids: [hostAgent.id] };
+        }
+        reporter.stderr(`⚠  Host agent ${hostAgent.name} detected but not configurable on this machine; falling back to --all detected.`);
+    }
+    return { kind: 'all' };
+}

package/dist/headless/next-step-prompt.d.ts

@@ -0,0 +1,7 @@
+import type { HostAgent } from './host-agent.js';
+/**
+ * One-line restart instruction tailored to the host agent if known, else generic.
+ * Returned without the leading ⚠ marker — the caller decides how to surface it.
+ */
+export declare function restartHint(hostAgent: HostAgent | null): string;
+export declare function nextStepPrompt(envName: string): string;

package/dist/headless/next-step-prompt.js

@@ -0,0 +1,25 @@
+const GENERIC_RESTART_HINT = 'Restart your AI agent (Claude Code, Cursor, Codex, VS Code, Claude Desktop) to load Stigg MCP.';
+/**
+ * One-line restart instruction tailored to the host agent if known, else generic.
+ * Returned without the leading ⚠ marker — the caller decides how to surface it.
+ */
+export function restartHint(hostAgent) {
+    return hostAgent ? hostAgent.restartHint : GENERIC_RESTART_HINT;
+}
+export function nextStepPrompt(envName) {
+    return `
+Hi User/Agent! Welcome to Stigg.
+Stigg is the runtime for AI credits, usage governance, and real-time access decisions.
+Connected to: ${envName}
+
+Choose a starting point:
+  1  Meter Usage              Track usage and understand consumption
+  2  Add Credit               Create wallets, balances, and burn-down logic
+  3  Pricing & Packaging      Model products, plans, and usage pricing
+  4  Usage Governance         Create budgets, limits, and AI spend controls
+  5  Integrate Stigg          Generate implementation code
+  6  Help me choose
+
+(you can do the others later · type back anytime)
+`;
+}

package/dist/headless/options.d.ts

@@ -0,0 +1,30 @@
+import type { ClientId } from '../types.js';
+import type { HostAgent } from './host-agent.js';
+export type ClientSelection = {
+    kind: 'all';
+} | {
+    kind: 'explicit';
+    ids: ClientId[];
+};
+export declare class HeadlessOptionsError extends Error {
+    constructor(message: string);
+}
+export interface ClientFlagOptions {
+    client?: string[];
+    all?: boolean;
+}
+export declare function validClientIds(): ClientId[];
+export declare function parseClientSelection(opts: ClientFlagOptions, { required }?: {
+    required?: boolean;
+}): ClientSelection;
+export declare function requireApiKey(flagValue?: string): string;
+/**
+ * Resolve the client selection for `init --headless` (phase 2), applying the
+ * host-agent fallback when neither `--client` nor `--all` is explicit.
+ *
+ * Priority: explicit flag (>--client or --all) > host agent > all detected.
+ *
+ * Used only by `init` — standalone `mcp add` / `skills add` keep the strict
+ * "explicit required" rule via `parseClientSelection({ required: true })`.
+ */
+export declare function resolveClientSelectionForInit(opts: ClientFlagOptions, hostAgent: HostAgent | null): ClientSelection;

package/dist/headless/options.js

@@ -0,0 +1,77 @@
+import { getAllClients } from '../mcp/clients/index.js';
+export class HeadlessOptionsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HeadlessOptionsError';
+    }
+}
+export function validClientIds() {
+    return getAllClients().map((c) => c.id);
+}
+export function parseClientSelection(opts, { required = false } = {}) {
+    const hasClient = (opts.client?.length ?? 0) > 0;
+    const hasAll = opts.all === true;
+    if (hasClient && hasAll) {
+        throw new HeadlessOptionsError('--client and --all are mutually exclusive');
+    }
+    if (!hasClient && !hasAll) {
+        if (required) {
+            throw new HeadlessOptionsError(`one of --client or --all is required (valid clients: ${validClientIds().join(', ')})`);
+        }
+        return { kind: 'all' };
+    }
+    if (hasAll)
+        return { kind: 'all' };
+    const valid = validClientIds();
+    const ids = [];
+    for (const raw of opts.client ?? []) {
+        const id = raw.trim();
+        if (!id)
+            continue;
+        if (!valid.includes(id)) {
+            throw new HeadlessOptionsError(`unknown client: ${id} (valid: ${valid.join(', ')})`);
+        }
+        ids.push(id);
+    }
+    if (ids.length === 0) {
+        throw new HeadlessOptionsError('--client given but no valid IDs');
+    }
+    return { kind: 'explicit', ids };
+}
+export function requireApiKey(flagValue) {
+    const fromFlag = sanitize(flagValue);
+    if (fromFlag)
+        return fromFlag;
+    const fromEnv = sanitize(process.env.STIGG_API_KEY);
+    if (fromEnv)
+        return fromEnv;
+    throw new HeadlessOptionsError('--api-key is required (or set STIGG_API_KEY env var)');
+}
+function sanitize(v) {
+    if (!v)
+        return null;
+    const trimmed = v.trim();
+    if (!trimmed || trimmed.startsWith('<'))
+        return null;
+    return trimmed;
+}
+/**
+ * Resolve the client selection for `init --headless` (phase 2), applying the
+ * host-agent fallback when neither `--client` nor `--all` is explicit.
+ *
+ * Priority: explicit flag (>--client or --all) > host agent > all detected.
+ *
+ * Used only by `init` — standalone `mcp add` / `skills add` keep the strict
+ * "explicit required" rule via `parseClientSelection({ required: true })`.
+ */
+export function resolveClientSelectionForInit(opts, hostAgent) {
+    const hasClient = (opts.client?.length ?? 0) > 0;
+    const hasAll = opts.all === true;
+    if (hasClient || hasAll) {
+        return parseClientSelection(opts);
+    }
+    if (hostAgent) {
+        return { kind: 'explicit', ids: [hostAgent.id] };
+    }
+    return { kind: 'all' };
+}

package/dist/headless/reporter.d.ts

@@ -0,0 +1,16 @@
+export interface Reporter {
+    /** Write a progress line to stdout. JSON reporter no-ops. */
+    human(line: string): void;
+    /** Write a failure line to stderr. Both reporters write this. */
+    stderr(line: string): void;
+    /** Emit the final structured payload. Human reporter no-ops; JSON reporter prints JSON. */
+    emit(payload: Record<string, unknown>): void;
+}
+export declare const fmt: {
+    heading(text: string): string;
+    ok(text: string, detail?: string): string;
+    fail(text: string, reason?: string): string;
+};
+export declare function createReporter(opts: {
+    json?: boolean;
+}): Reporter;

package/dist/headless/reporter.js

@@ -0,0 +1,41 @@
+import pc from 'picocolors';
+export const fmt = {
+    heading(text) {
+        return `${pc.dim('stigg · ')}${text}`;
+    },
+    ok(text, detail) {
+        if (!detail)
+            return `${pc.green('  ✓')} ${text}`;
+        return `${pc.green('  ✓')} ${text.padEnd(26)} ${pc.dim(detail)}`;
+    },
+    fail(text, reason) {
+        if (!reason)
+            return `${pc.red('  ✗')} ${text}`;
+        return `${pc.red('  ✗')} ${text}: ${reason}`;
+    },
+};
+class HumanReporter {
+    human(line) {
+        process.stdout.write(line + '\n');
+    }
+    stderr(line) {
+        process.stderr.write(line + '\n');
+    }
+    emit() {
+        /* no-op */
+    }
+}
+class JsonReporter {
+    human() {
+        /* no-op */
+    }
+    stderr(line) {
+        process.stderr.write(line + '\n');
+    }
+    emit(payload) {
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    }
+}
+export function createReporter(opts) {
+    return opts.json ? new JsonReporter() : new HumanReporter();
+}

package/dist/headless/setup.d.ts

@@ -0,0 +1,29 @@
+import { type InstallResult as SkillsInstallResult } from '../skills/install.js';
+import type { ClientId, WriteResult } from '../types.js';
+import { type ClientSelection } from './options.js';
+export interface SkippedClient {
+    id: ClientId;
+    reason: 'unsupported' | 'unknown';
+}
+export interface HeadlessSetupOptions {
+    apiKey: string;
+    clients: ClientSelection;
+    installSkills: boolean;
+    /** Skip the MCP loop entirely. Used by `skills add`. */
+    skipMcp?: boolean;
+}
+export interface HeadlessResult {
+    writes: WriteResult[];
+    skipped: SkippedClient[];
+    skillsInstall?: SkillsInstallResult;
+    ok: boolean;
+}
+export interface ProgressCallbacks {
+    onClientResult?: (write: WriteResult, client: {
+        id: ClientId;
+        name: string;
+    }) => void;
+    onClientFail?: (id: ClientId, name: string, reason: string) => void;
+    onSkillsResult?: (result: SkillsInstallResult) => void;
+}
+export declare function runHeadlessSetup(opts: HeadlessSetupOptions, progress?: ProgressCallbacks): Promise<HeadlessResult>;

package/dist/headless/setup.js

@@ -0,0 +1,80 @@
+import { getAllClients, getClientById, getSupportedClients, } from '../mcp/clients/index.js';
+import { installStiggSkills, } from '../skills/install.js';
+import { HeadlessOptionsError } from './options.js';
+async function resolveClients(selection, progress, result) {
+    if (selection.kind === 'all') {
+        const supported = await getSupportedClients();
+        if (supported.length === 0) {
+            throw new HeadlessOptionsError('no supported AI clients detected on this machine');
+        }
+        return supported.map((c) => ({ id: c.id, name: c.name, client: c }));
+    }
+    const resolved = [];
+    for (const id of selection.ids) {
+        const c = getClientById(id);
+        if (!c) {
+            // Defensive: parseClientSelection should have rejected unknowns.
+            result.skipped.push({ id, reason: 'unknown' });
+            result.ok = false;
+            continue;
+        }
+        if (!(await c.isClientSupported())) {
+            // Explicit selection of an unsupported client is a hard failure.
+            const reason = 'client not detected on this machine';
+            progress.onClientFail?.(id, c.name, reason);
+            result.writes.push({ client: id, path: c.installTarget(), written: false });
+            result.ok = false;
+            continue;
+        }
+        resolved.push({ id: c.id, name: c.name, client: c });
+    }
+    return resolved;
+}
+async function runMcpLoop(clients, credential, progress, result) {
+    const writtenIds = [];
+    for (const { id, name, client } of clients) {
+        const installResult = await client.addServer(credential);
+        const write = client.toWriteResult(installResult);
+        result.writes.push(write);
+        if (installResult.ok) {
+            writtenIds.push(id);
+            progress.onClientResult?.(write, { id, name });
+        }
+        else {
+            progress.onClientFail?.(id, name, installResult.reason ?? 'install failed');
+            result.ok = false;
+        }
+    }
+    return writtenIds;
+}
+async function resolveSkillsTargets(selection) {
+    if (selection.kind === 'all') {
+        const supported = await getSupportedClients();
+        if (supported.length === 0) {
+            throw new HeadlessOptionsError('no supported AI clients detected on this machine');
+        }
+        return supported.map((c) => c.id);
+    }
+    const valid = new Set(getAllClients().map((c) => c.id));
+    return selection.ids.filter((id) => valid.has(id));
+}
+export async function runHeadlessSetup(opts, progress = {}) {
+    const result = { writes: [], skipped: [], ok: true };
+    let writtenIds = [];
+    if (!opts.skipMcp) {
+        const resolved = await resolveClients(opts.clients, progress, result);
+        const credential = { value: opts.apiKey };
+        writtenIds = await runMcpLoop(resolved, credential, progress, result);
+    }
+    if (opts.installSkills) {
+        const targets = opts.skipMcp ? await resolveSkillsTargets(opts.clients) : writtenIds;
+        if (targets.length > 0) {
+            const skillsResult = await installStiggSkills(targets);
+            result.skillsInstall = skillsResult;
+            progress.onSkillsResult?.(skillsResult);
+            if (!skillsResult.ok)
+                result.ok = false;
+        }
+    }
+    return result;
+}