@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.js

@@ -0,0 +1,189 @@
+/**
+ * `codex-mcp` scaffolder preset.
+ *
+ * Codex and OMX both resolve persistent MCP servers from Codex's config home
+ * (`$CODEX_HOME/config.toml`, falling back to `~/.codex/config.toml`).  Keep
+ * the patch tiny and deterministic: per-server upserts, no TOML parser
+ * dependency, no edits to unrelated user config.
+ *
+ * Two managed blocks today:
+ *   1. `[mcp_servers.playwright]` — points at the npm-published Playwright
+ *      MCP server through Vite+'s `vp dlx` facade.
+ *   2. `[mcp_servers.webpresso]` — points at webpresso's own MCP server.
+ *      Path-stability requires discovery: webpresso lives in different
+ *      locations depending on how the user installed it (Claude plugin
+ *      install, bun global, pnpm/npm global). Discovery happens at scaffold
+ *      time; the resolved absolute path is written into the codex config.
+ *      When the unified-cli sibling cutover lands (`webpresso mcp serve`
+ *      from a path-stable bin), this block collapses to a fixed `command`.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const PLAYWRIGHT_MCP_SERVER_NAME = 'playwright';
+export const PLAYWRIGHT_MCP_HEADER = `[mcp_servers.${PLAYWRIGHT_MCP_SERVER_NAME}]`;
+export const PLAYWRIGHT_MCP_BLOCK = `${PLAYWRIGHT_MCP_HEADER}
+command = "vp"
+args = ["dlx", "@playwright/mcp@latest", "--caps=testing,storage,network,devtools"]
+enabled = true
+startup_timeout_sec = 30
+`;
+export const WEBPRESSO_MCP_SERVER_NAME = 'webpresso';
+export const WEBPRESSO_MCP_HEADER = `[mcp_servers.${WEBPRESSO_MCP_SERVER_NAME}]`;
+function defaultConfigPath() {
+    const codexHome = process.env.CODEX_HOME || join(process.env.HOME || homedir(), '.codex');
+    return join(codexHome, 'config.toml');
+}
+export function upsertPlaywrightMcpServer(raw) {
+    const lines = raw.trimEnd().split(/\r?\n/);
+    const hasContent = raw.trim().length > 0;
+    const start = lines.findIndex((line) => line.trim() === PLAYWRIGHT_MCP_HEADER);
+    if (start === -1) {
+        const prefix = hasContent ? `${raw.trimEnd()}\n\n` : '';
+        return `${prefix}${PLAYWRIGHT_MCP_BLOCK}`;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (lines[i].trim().startsWith('[')) {
+            end = i;
+            break;
+        }
+    }
+    return ([
+        ...lines.slice(0, start),
+        ...PLAYWRIGHT_MCP_BLOCK.trimEnd().split('\n'),
+        ...lines.slice(end),
+    ].join('\n') + '\n');
+}
+export function ensureCodexPlaywrightMcp(input) {
+    const configPath = input.configPath ?? defaultConfigPath();
+    if (input.options.dryRun) {
+        return { kind: 'codex-playwright-mcp-skipped-dry-run', path: configPath };
+    }
+    const existing = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+    const next = upsertPlaywrightMcpServer(existing);
+    if (next === existing) {
+        return { kind: 'codex-playwright-mcp-unchanged', path: configPath };
+    }
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, next, 'utf8');
+    return { kind: 'codex-playwright-mcp-written', path: configPath };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Agent-kit MCP server registration
+// ────────────────────────────────────────────────────────────────────────────
+const SOURCE_MCP_ENTRY_RELATIVE = join('src', 'mcp', 'cli.ts');
+const BUILT_MCP_ENTRY_RELATIVE = join('dist', 'esm', 'mcp', 'cli.js');
+/**
+ * Resolve the absolute path to webpresso's MCP entry on this machine. Probes
+ * the locations consumers use to install webpresso, in order of stability:
+ *
+ *   1. Claude plugin install — `~/.claude/plugins/cache/webpresso/webpresso/`
+ *      (path-stable; updated by Claude Code's plugin manager)
+ *   2. bun global — `~/.bun/install/global/node_modules/webpresso/`
+ *   3. pnpm global — `$(pnpm root -g)/webpresso/`
+ *   4. npm global — `$(npm root -g)/webpresso/`
+ *
+ * Returns `null` when none of the candidates contain `src/mcp/cli.ts`. The
+ * caller surfaces a clear error in that case rather than writing a broken
+ * codex config.
+ */
+export function findWebpressoMcpEntry(probe = {}) {
+    const candidates = probe.candidates ?? defaultCandidates(probe);
+    for (const root of candidates) {
+        if (!root)
+            continue;
+        const sourceEntry = join(root, SOURCE_MCP_ENTRY_RELATIVE);
+        if (existsSync(sourceEntry))
+            return sourceEntry;
+        const builtEntry = join(root, BUILT_MCP_ENTRY_RELATIVE);
+        if (existsSync(builtEntry))
+            return builtEntry;
+    }
+    return null;
+}
+function defaultCandidates(probe) {
+    const home = process.env.HOME || homedir();
+    const claudePlugin = join(home, '.claude', 'plugins', 'cache', 'webpresso', 'webpresso');
+    const bunGlobal = join(home, '.bun', 'install', 'global', 'node_modules', '@webpresso', 'webpresso');
+    const pnpmRoot = (probe.pnpmGlobalRoot ?? probePnpmGlobalRoot)();
+    const npmRoot = (probe.npmGlobalRoot ?? probeNpmGlobalRoot)();
+    return [
+        claudePlugin,
+        bunGlobal,
+        pnpmRoot ? join(pnpmRoot, '@webpresso', 'webpresso') : '',
+        npmRoot ? join(npmRoot, '@webpresso', 'webpresso') : '',
+    ];
+}
+function probePnpmGlobalRoot() {
+    return runQuiet('pnpm', ['root', '-g']);
+}
+function probeNpmGlobalRoot() {
+    return runQuiet('npm', ['root', '-g']);
+}
+function runQuiet(cmd, args) {
+    try {
+        const output = execFileSync(cmd, [...args], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const trimmed = output.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function agentKitMcpLaunchCommand(entryPath) {
+    return entryPath.endsWith('.ts')
+        ? { command: 'bun', args: [entryPath] }
+        : { command: 'node', args: [entryPath] };
+}
+export function agentKitMcpBlock(entryPath) {
+    const launch = agentKitMcpLaunchCommand(entryPath);
+    return `${WEBPRESSO_MCP_HEADER}
+command = "${launch.command}"
+args = [${launch.args.map((arg) => `"${arg}"`).join(', ')}]
+enabled = true
+`;
+}
+export function upsertWebpressoMcpServer(raw, entryPath) {
+    const block = agentKitMcpBlock(entryPath);
+    const lines = raw.trimEnd().split(/\r?\n/);
+    const hasContent = raw.trim().length > 0;
+    const start = lines.findIndex((line) => line.trim() === WEBPRESSO_MCP_HEADER);
+    if (start === -1) {
+        const prefix = hasContent ? `${raw.trimEnd()}\n\n` : '';
+        return `${prefix}${block}`;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (lines[i].trim().startsWith('[')) {
+            end = i;
+            break;
+        }
+    }
+    return ([...lines.slice(0, start), ...block.trimEnd().split('\n'), ...lines.slice(end)].join('\n') +
+        '\n');
+}
+export function ensureCodexWebpressoMcp(input) {
+    const configPath = input.configPath ?? defaultConfigPath();
+    if (input.options.dryRun) {
+        return { kind: 'codex-webpresso-mcp-skipped-dry-run', path: configPath };
+    }
+    const entryPath = input.entryPath ?? findWebpressoMcpEntry(input.probe);
+    if (!entryPath) {
+        const checked = (input.probe?.candidates ?? defaultCandidates(input.probe ?? {})).filter((p) => Boolean(p));
+        return { kind: 'codex-webpresso-mcp-not-installed', path: configPath, checked };
+    }
+    const existing = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+    const next = upsertWebpressoMcpServer(existing, entryPath);
+    if (next === existing) {
+        return { kind: 'codex-webpresso-mcp-unchanged', path: configPath, entryPath };
+    }
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, next, 'utf8');
+    return { kind: 'codex-webpresso-mcp-written', path: configPath, entryPath };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/context-mode/index.d.ts

@@ -0,0 +1,24 @@
+import { spawnSync } from 'node:child_process';
+import { type MergeOptions, type MergeResult } from '#cli/commands/init/merge';
+import { type SpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+export interface EnsureContextModeInput {
+    repoRoot: string;
+    options: MergeOptions;
+    spawn?: typeof spawnSync;
+    codexConfigPath?: string;
+    opencodeConfigPath?: string;
+    pinFilePath?: string;
+    strict?: boolean;
+    spinnerFactory?: SpinnerFactory;
+    globalInstall?: boolean;
+}
+export type EnsureContextModeResult = {
+    codexFeatures: MergeResult;
+    codexGlobalHooks: MergeResult;
+    opencodeConfig: MergeResult;
+    installed: boolean;
+};
+export declare function upsertCodexContextModeFeatures(raw: string): string;
+export declare function patchOpenCodeContextModeConfig(existing: Record<string, unknown>, agentKitCommand?: string[]): Record<string, unknown>;
+export declare function ensureContextMode(input: EnsureContextModeInput): EnsureContextModeResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/context-mode/index.js

@@ -0,0 +1,165 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { patchJsonFile } from '#cli/commands/init/merge';
+import { agentKitMcpLaunchCommand, findWebpressoMcpEntry, } from '#cli/commands/init/scaffolders/codex-mcp/index';
+import { defaultCodexHooksPathFromConfig, normalizeGlobalCodexHooksFile, resolveBinaryOnPath, } from '#cli/commands/init/scaffolders/agent-hooks/codex-global-normalize';
+import { makeNoopSpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+import { checkVersionPin } from '#cli/commands/init/scaffolders/version-pin';
+const CODEX_CONTEXT_MODE_FEATURES = {
+    plugin_hooks: 'true',
+    hooks: 'true',
+};
+function defaultCodexConfigPath() {
+    const codexHome = process.env.CODEX_HOME || join(process.env.HOME || homedir(), '.codex');
+    return join(codexHome, 'config.toml');
+}
+function defaultOpenCodeConfigPath(repoRoot) {
+    return join(repoRoot, 'opencode.json');
+}
+export function upsertCodexContextModeFeatures(raw) {
+    const trimmed = raw.trimEnd();
+    const lines = trimmed.length > 0 ? trimmed.split(/\r?\n/) : [];
+    const hasContent = raw.trim().length > 0;
+    const start = lines.findIndex((line) => line.trim() === '[features]');
+    if (start === -1) {
+        const prefix = hasContent ? `${raw.trimEnd()}\n\n` : '';
+        return `${prefix}[features]\n${Object.entries(CODEX_CONTEXT_MODE_FEATURES)
+            .map(([key, value]) => `${key} = ${value}`)
+            .join('\n')}\n`;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (lines[i].trim().startsWith('[')) {
+            end = i;
+            break;
+        }
+    }
+    const seen = new Set();
+    const body = lines.slice(start + 1, end).map((line) => {
+        const match = line.match(/^(\s*)(hooks|plugin_hooks)\s*=/);
+        if (!match)
+            return line;
+        const key = match[2];
+        seen.add(key);
+        return `${match[1]}${key} = ${CODEX_CONTEXT_MODE_FEATURES[key]}`;
+    });
+    const trailingBlankLines = [];
+    while (body.length > 0 && body[body.length - 1]?.trim() === '') {
+        trailingBlankLines.unshift(body.pop());
+    }
+    for (const [key, value] of Object.entries(CODEX_CONTEXT_MODE_FEATURES)) {
+        if (!seen.has(key))
+            body.push(`${key} = ${value}`);
+    }
+    body.push(...trailingBlankLines);
+    return [...lines.slice(0, start + 1), ...body, ...lines.slice(end)].join('\n') + '\n';
+}
+export function patchOpenCodeContextModeConfig(existing, agentKitCommand = ['vp', 'exec', 'wp', 'mcp']) {
+    const currentMcp = existing.mcp && typeof existing.mcp === 'object' && !Array.isArray(existing.mcp)
+        ? { ...existing.mcp }
+        : {};
+    currentMcp['context-mode'] = {
+        type: 'local',
+        command: ['context-mode'],
+    };
+    currentMcp['webpresso'] = {
+        type: 'local',
+        command: agentKitCommand,
+    };
+    const currentPlugins = Array.isArray(existing.plugin)
+        ? existing.plugin.filter((value) => typeof value === 'string')
+        : [];
+    const plugins = currentPlugins.includes('context-mode')
+        ? currentPlugins
+        : [...currentPlugins, 'context-mode'];
+    return {
+        ...existing,
+        $schema: 'https://opencode.ai/config.json',
+        mcp: currentMcp,
+        plugin: plugins,
+    };
+}
+function resolveOpenCodeWebpressoCommand(repoRoot, globalInstall = false) {
+    const repoLocalRoot = join(repoRoot, 'node_modules', '@webpresso', 'webpresso');
+    const entryPath = findWebpressoMcpEntry({ candidates: [repoLocalRoot] }) ?? findWebpressoMcpEntry();
+    if (!entryPath)
+        return globalInstall ? ['wp', 'mcp'] : ['vp', 'exec', 'wp', 'mcp'];
+    const launch = agentKitMcpLaunchCommand(entryPath);
+    return [launch.command, ...launch.args];
+}
+function ensureCodexContextModeFeatures(configPath, options) {
+    if (options.dryRun)
+        return { targetPath: configPath, action: 'skipped-dry' };
+    const existed = existsSync(configPath);
+    const existing = existed ? readFileSync(configPath, 'utf8') : '';
+    const next = upsertCodexContextModeFeatures(existing);
+    if (next === existing)
+        return { targetPath: configPath, action: 'identical' };
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, next, 'utf8');
+    return { targetPath: configPath, action: existed ? 'overwritten' : 'created' };
+}
+const CONTEXT_MODE_NOT_FOUND_HINT = 'context-mode is not on PATH after `vp install -g context-mode`. Install it manually and re-run.';
+function ensureContextModeBinary(spawn, spinner) {
+    let installed = false;
+    spinner.start();
+    let probe = spawn('context-mode', ['--help'], { stdio: 'ignore' });
+    if (probe.error || (probe.status !== null && probe.status !== 0)) {
+        const install = spawn('vp', ['install', '-g', 'context-mode'], { stdio: 'inherit' });
+        if (install.status !== 0) {
+            spinner.fail('context-mode install failed');
+            throw new Error(CONTEXT_MODE_NOT_FOUND_HINT);
+        }
+        installed = true;
+        probe = spawn('context-mode', ['--help'], { stdio: 'ignore' });
+        if (probe.error || (probe.status !== null && probe.status !== 0)) {
+            spinner.fail('context-mode not found after install');
+            throw new Error(CONTEXT_MODE_NOT_FOUND_HINT);
+        }
+    }
+    else {
+        spawn('vp', ['update', '-g', 'context-mode'], { stdio: 'inherit' });
+    }
+    // Detect installed version for pin check
+    const versionProbe = spawn('context-mode', ['--version'], { encoding: 'utf8' });
+    const version = String(versionProbe.stdout ?? '').trim();
+    const binaryPath = resolveBinaryOnPath('context-mode');
+    if (binaryPath === null) {
+        spinner.fail('context-mode path not resolvable after install');
+        throw new Error(CONTEXT_MODE_NOT_FOUND_HINT);
+    }
+    spinner.succeed('context-mode ready');
+    return { installed, version, binaryPath };
+}
+export function ensureContextMode(input) {
+    const codexConfigPath = input.codexConfigPath ?? defaultCodexConfigPath();
+    const opencodeConfigPath = input.opencodeConfigPath ?? defaultOpenCodeConfigPath(input.repoRoot);
+    const codexHooksPath = defaultCodexHooksPathFromConfig(codexConfigPath);
+    if (input.options.dryRun) {
+        return {
+            codexFeatures: { targetPath: codexConfigPath, action: 'skipped-dry' },
+            codexGlobalHooks: { targetPath: codexHooksPath, action: 'skipped-dry' },
+            opencodeConfig: { targetPath: opencodeConfigPath, action: 'skipped-dry' },
+            installed: false,
+        };
+    }
+    const spawn = input.spawn ?? spawnSync;
+    const spinner = (input.spinnerFactory ?? makeNoopSpinnerFactory())('context-mode');
+    const { installed, version, binaryPath } = ensureContextModeBinary(spawn, spinner);
+    const pinCheck = checkVersionPin('context_mode', version, input.pinFilePath ?? join(input.repoRoot, 'compatible-versions.json'));
+    if (!pinCheck.ok) {
+        if (input.strict) {
+            throw new Error(pinCheck.warning);
+        }
+        console.warn(pinCheck.warning);
+    }
+    return {
+        codexFeatures: ensureCodexContextModeFeatures(codexConfigPath, input.options),
+        codexGlobalHooks: normalizeGlobalCodexHooksFile(codexHooksPath, { contextModeBinary: binaryPath }, input.options),
+        opencodeConfig: patchJsonFile(opencodeConfigPath, (existing) => patchOpenCodeContextModeConfig(existing, resolveOpenCodeWebpressoCommand(input.repoRoot, input.globalInstall)), input.options),
+        installed,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/example-skill/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `example-skill` scaffolder preset.
+ *
+ * Copies the `hello-webpresso` SKILL.md template into `.agent/skills/hello-webpresso/`
+ * so new consumers have an immediately runnable skill that verifies webpresso is wired.
+ *
+ * After writing, attempts `wp compile` non-fatally so IDEs pick up the new skill.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+export declare function scaffoldExampleSkill(cwd: string, { spawn, exists, }?: {
+    spawn?: typeof spawnSync;
+    exists?: typeof existsSync;
+}): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/cli/commands/init/scaffolders/example-skill/index.js

@@ -0,0 +1,31 @@
+/**
+ * `example-skill` scaffolder preset.
+ *
+ * Copies the `hello-webpresso` SKILL.md template into `.agent/skills/hello-webpresso/`
+ * so new consumers have an immediately runnable skill that verifies webpresso is wired.
+ *
+ * After writing, attempts `wp compile` non-fatally so IDEs pick up the new skill.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SKILL_SLUG = 'hello-webpresso';
+const TEMPLATE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'SKILL.md.template');
+export async function scaffoldExampleSkill(cwd, { spawn = spawnSync, exists = existsSync, } = {}) {
+    const skillDir = join(cwd, '.agent', 'skills', SKILL_SLUG);
+    const skillFile = join(skillDir, 'SKILL.md');
+    if (exists(skillFile))
+        return;
+    mkdirSync(skillDir, { recursive: true });
+    const template = readFileSync(TEMPLATE_PATH, 'utf-8');
+    writeFileSync(skillFile, template, 'utf-8');
+    // Non-fatal: `wp compile` may not be on PATH in all environments.
+    try {
+        spawn('wp', ['compile'], { cwd, stdio: 'ignore' });
+    }
+    catch {
+        // compile failure is non-fatal
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/init/scaffolders/gstack/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `gstack` scaffolder preset.
+ *
+ * gstack uses a canonical checkout installed at `~/.claude/skills/gstack/`.
+ * Agent-kit owns that checkout bootstrap, then lets gstack's own host-aware
+ * setup command materialize additional surfaces such as Codex from the same
+ * checkout.
+ *
+ * Detection for the canonical checkout is path-based, NOT PATH-based: gstack
+ * itself is not a CLI binary on $PATH. Checkout bootstrap is a clone +
+ * `./setup --team`. When Codex is detected, webpresso runs gstack's explicit
+ * `./setup --host codex --team` flow from that same checkout so Codex is
+ * materialized without accidentally fanning out to every host binary on PATH.
+ *
+ * Side-effect outside the consumer repo: writes to the user's home dir.
+ * This is intentional — gstack is global by design.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import type { MergeOptions } from '#cli/commands/init/merge';
+import { type SpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+export interface EnsureGstackInput {
+    repoRoot: string;
+    options: MergeOptions;
+    /** Override gstack install root (defaults to ~/.claude/skills/gstack). Useful in tests. */
+    installRoot?: string;
+    /** Override Codex config path (defaults to ~/.codex/config.toml). Useful in tests. */
+    codexConfigPath?: string;
+    /** Override Codex skills root (defaults to ~/.codex/skills). Useful in tests. */
+    codexSkillsRoot?: string;
+    /** DI seam for child_process.spawnSync. */
+    spawn?: typeof spawnSync;
+    /** DI seam for fs.existsSync. */
+    exists?: typeof existsSync;
+    /** DI seam for Codex detection in tests. */
+    detectCodex?: (input: {
+        spawn: typeof spawnSync;
+        exists: typeof existsSync;
+        codexConfigPath: string;
+    }) => boolean;
+    /** DI seam for spinner. Defaults to noop when !process.stdout.isTTY, ora otherwise. */
+    spinnerFactory?: SpinnerFactory;
+    /** DI seam for environment-backed host/output policy. */
+    env?: NodeJS.ProcessEnv;
+    /** DI seam for user-visible progress lines. */
+    log?: (message: string) => void;
+    /** DI seam for timing. */
+    now?: () => number;
+}
+export type GstackCodexResult = {
+    kind: 'gstack-codex-installed';
+    skillsRoot: string;
+} | {
+    kind: 'gstack-codex-updated';
+    skillsRoot: string;
+} | {
+    kind: 'gstack-codex-skipped';
+    reason: 'not-detected' | 'not-requested';
+    skillsRoot: string;
+};
+export type EnsureGstackResult = {
+    kind: 'gstack-installed';
+    root: string;
+    codex: GstackCodexResult;
+} | {
+    kind: 'gstack-updated';
+    root: string;
+    codex: GstackCodexResult;
+} | {
+    kind: 'gstack-skipped-dry-run';
+} | {
+    kind: 'gstack-clone-failed';
+    exitCode: number;
+} | {
+    kind: 'gstack-pull-failed';
+    exitCode: number;
+} | {
+    kind: 'gstack-setup-failed';
+    exitCode: number;
+    command: GstackSetupCommand;
+};
+type GstackSetupHost = 'auto' | 'codex';
+type GstackSetupCommand = '--team' | `--host ${GstackSetupHost} --team`;
+/**
+ * Ensure gstack is installed and up-to-date.
+ * - Not present: clone from main + setup.
+ * - Already present: pull latest main + re-run setup.
+ * - If Codex is detected: materialize Codex skills from the canonical checkout.
+ */
+export declare function ensureGstack(input: EnsureGstackInput): EnsureGstackResult;
+export {};
+//# sourceMappingURL=index.d.ts.map