agentopology 0.1.0

package/dist/bindings/gemini-cli.js

@@ -0,0 +1,1327 @@
+/**
+ * Google Gemini CLI binding.
+ *
+ * Generates the `.gemini/` directory structure and supporting files from a
+ * parsed {@link TopologyAST}.
+ *
+ * Gemini CLI structure:
+ *   .gemini/CONTEXT.md            — Main instructions (never root GEMINI.md)
+ *   .gemini/settings.json         — Model config, permissions, MCP, hooks, sandbox
+ *   .gemini/instructions.md       — Detailed project instructions
+ *   .gemini/commands/<name>.toml  — Custom command files from triggers
+ *
+ * @module
+ */
+import { deduplicateFiles } from "./types.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert a kebab-case id to Title Case. */
+function toTitle(id) {
+    return id
+        .split(/[-_]/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/** Generate a shell script stub with a header comment. */
+function shellStub(description) {
+    return [
+        "#!/usr/bin/env bash",
+        `# ${description}`,
+        "# Auto-generated by agentopology scaffold — edit as needed.",
+        'set -euo pipefail',
+        "",
+        'echo "TODO: implement this script"',
+        "",
+    ].join("\n");
+}
+/** Generate an empty directory marker (a .gitkeep file). */
+function gitkeep(dirPath) {
+    return { path: `${dirPath}/.gitkeep`, content: "", category: "machine" };
+}
+/**
+ * Map topology permission strings to Gemini CLI defaultApprovalMode.
+ *
+ * Gemini CLI approval modes:
+ *   "default"   — asks for approval (supervised)
+ *   "auto_edit" — auto-approve edits (autonomous)
+ *   "plan"      — plan mode (read-only)
+ */
+function mapApprovalMode(perm) {
+    switch (perm) {
+        case "supervised":
+        case "interactive":
+            return "default";
+        case "autonomous":
+        case "unrestricted":
+            return "auto_edit";
+        case "plan":
+            return "plan";
+        default:
+            return "default";
+    }
+}
+/** Format a SchemaType to a human-readable string. */
+function formatSchemaType(t) {
+    switch (t.kind) {
+        case "primitive":
+            return t.value;
+        case "array":
+            return `${formatSchemaType(t.itemType)}[]`;
+        case "enum":
+            return t.values.join(" | ");
+        case "ref":
+            return t.name;
+    }
+}
+/** Format a SchemaFieldDef to a readable line. */
+function formatSchemaField(f) {
+    const opt = f.optional ? "?" : "";
+    return `- ${f.name}${opt}: ${formatSchemaType(f.type)}`;
+}
+/**
+ * Map topology hook event names to Gemini CLI hook event names.
+ */
+function mapHookEvent(on) {
+    switch (on) {
+        case "PreToolUse":
+            return "BeforeTool";
+        case "PostToolUse":
+        case "ToolUse":
+            return "AfterTool";
+        case "AgentStart":
+            return "BeforeAgent";
+        case "AgentStop":
+            return "AfterAgent";
+        case "Error":
+            return "Notification";
+        default:
+            return on;
+    }
+}
+/**
+ * Determine if a hook run command is an inline command (not a file path).
+ * Inline commands are things like "exit 1", not file paths like "scripts/foo.sh".
+ */
+function isInlineCommand(run) {
+    // If it doesn't contain a path separator and doesn't end in a script extension,
+    // treat it as an inline command.
+    if (run.includes("/") || run.includes("\\"))
+        return false;
+    if (/\.\w+$/.test(run))
+        return false;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Section generators
+// ---------------------------------------------------------------------------
+/**
+ * Generate the main GEMINI.md file.
+ *
+ * This is the primary instructions file that Gemini CLI reads. It contains
+ * the topology description, agent roles, flow, and orchestration instructions.
+ */
+function generateGeminiMd(ast) {
+    const sections = [];
+    // Header
+    sections.push(`# ${toTitle(ast.topology.name)}`);
+    sections.push("");
+    if (ast.topology.description) {
+        sections.push(ast.topology.description);
+        sections.push("");
+    }
+    sections.push(`Version: ${ast.topology.version}`);
+    if (ast.topology.patterns.length > 0) {
+        sections.push(`Patterns: ${ast.topology.patterns.join(", ")}`);
+    }
+    sections.push("");
+    // Orchestrator section
+    const orch = ast.nodes.find((n) => n.type === "orchestrator");
+    if (orch) {
+        sections.push("## Orchestrator");
+        sections.push("");
+        sections.push(`Model: ${orch.model}`);
+        if (orch.handles?.length > 0) {
+            sections.push(`Handles: ${orch.handles.join(", ")}`);
+        }
+        if (orch.generates) {
+            sections.push(`Generates: ${orch.generates}`);
+        }
+        sections.push("");
+    }
+    // Agent sections
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    if (agents.length > 0) {
+        sections.push("## Agents");
+        sections.push("");
+        for (const agent of agents) {
+            sections.push(`### ${toTitle(agent.id)}`);
+            sections.push("");
+            const roleText = ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
+            if (agent.description) {
+                sections.push(agent.description);
+                sections.push("");
+            }
+            else if (roleText) {
+                sections.push(roleText);
+                sections.push("");
+            }
+            if (agent.prompt) {
+                sections.push(agent.prompt);
+                sections.push("");
+            }
+            if (agent.model)
+                sections.push(`- Model: ${agent.model}`);
+            if (agent.phase != null)
+                sections.push(`- Phase: ${agent.phase}`);
+            if (agent.tools && agent.tools.length > 0) {
+                sections.push(`- Tools: ${agent.tools.join(", ")}`);
+            }
+            if (agent.disallowedTools && agent.disallowedTools.length > 0) {
+                sections.push(`- Disallowed tools: ${agent.disallowedTools.join(", ")}`);
+            }
+            if (agent.skills && agent.skills.length > 0) {
+                sections.push(`- Skills: ${agent.skills.join(", ")}`);
+            }
+            if (agent.reads && agent.reads.length > 0) {
+                sections.push(`- Reads: ${agent.reads.join(", ")}`);
+            }
+            if (agent.writes && agent.writes.length > 0) {
+                sections.push(`- Writes: ${agent.writes.join(", ")}`);
+            }
+            if (agent.behavior)
+                sections.push(`- Behavior: ${agent.behavior}`);
+            if (agent.skip)
+                sections.push(`- Skip when: ${agent.skip}`);
+            // Outputs
+            if (agent.outputs) {
+                sections.push("- Outputs:");
+                for (const [field, values] of Object.entries(agent.outputs)) {
+                    sections.push(`  - ${field}: ${values.join(" | ")}`);
+                }
+            }
+            // Timeout
+            if (agent.timeout) {
+                sections.push(`- Maximum execution time: ${agent.timeout}`);
+            }
+            // On-fail
+            if (agent.onFail) {
+                sections.push(`- On failure: ${agent.onFail}`);
+            }
+            // Retry
+            if (agent.retry != null) {
+                if (typeof agent.retry === "number") {
+                    sections.push(`- Retry: up to ${agent.retry} times on failure`);
+                }
+                else {
+                    const r = agent.retry;
+                    const parts = [`max ${r.max} attempts`];
+                    if (r.backoff)
+                        parts.push(`${r.backoff} backoff`);
+                    if (r.interval)
+                        parts.push(`interval ${r.interval}`);
+                    if (r.maxInterval)
+                        parts.push(`max interval ${r.maxInterval}`);
+                    if (r.jitter)
+                        parts.push(`with jitter`);
+                    if (r.nonRetryable && r.nonRetryable.length > 0) {
+                        parts.push(`non-retryable: ${r.nonRetryable.join(", ")}`);
+                    }
+                    sections.push(`- Retry strategy: ${parts.join(", ")}`);
+                }
+            }
+            // Output format
+            if (agent.outputFormat) {
+                sections.push(`- Output format: ${agent.outputFormat}`);
+            }
+            // Log level
+            if (agent.logLevel) {
+                sections.push(`- Log verbosity: ${agent.logLevel}`);
+            }
+            // Model params
+            if (agent.temperature != null) {
+                sections.push(`- Temperature: ${agent.temperature}`);
+            }
+            if (agent.maxTokens != null) {
+                sections.push(`- Max tokens: ${agent.maxTokens}`);
+            }
+            if (agent.topP != null) {
+                sections.push(`- Top-p: ${agent.topP}`);
+            }
+            if (agent.topK != null) {
+                sections.push(`- Top-k: ${agent.topK}`);
+            }
+            if (agent.seed != null) {
+                sections.push(`- Seed: ${agent.seed}`);
+            }
+            if (agent.thinking) {
+                sections.push(`- Thinking: ${agent.thinking}`);
+            }
+            if (agent.thinkingBudget != null) {
+                sections.push(`- Thinking budget: ${agent.thinkingBudget} tokens`);
+            }
+            if (agent.maxTurns != null) {
+                sections.push(`- Max turns: ${agent.maxTurns}`);
+            }
+            // Join semantics
+            if (agent.join) {
+                sections.push(`- Wait for: ${agent.join} (upstream join strategy)`);
+            }
+            // Circuit breaker
+            if (agent.circuitBreaker) {
+                const cb = agent.circuitBreaker;
+                sections.push(`- Circuit breaker: threshold=${cb.threshold}, window=${cb.window}, cooldown=${cb.cooldown}`);
+            }
+            // Compensates
+            if (agent.compensates) {
+                sections.push(`- Compensates: ${agent.compensates} (can undo its side effects)`);
+            }
+            // Input/Output schemas
+            if (agent.inputSchema && agent.inputSchema.length > 0) {
+                sections.push("- Input schema:");
+                for (const field of agent.inputSchema) {
+                    sections.push(`  ${formatSchemaField(field)}`);
+                }
+            }
+            if (agent.outputSchema && agent.outputSchema.length > 0) {
+                sections.push("- Output schema:");
+                for (const field of agent.outputSchema) {
+                    sections.push(`  ${formatSchemaField(field)}`);
+                }
+            }
+            // Rate limit
+            if (agent.rateLimit) {
+                sections.push(`- Rate limit: ${agent.rateLimit}`);
+            }
+            // Artifacts: produces/consumes
+            if (agent.produces && agent.produces.length > 0) {
+                sections.push(`- Produces: ${agent.produces.join(", ")}`);
+            }
+            if (agent.consumes && agent.consumes.length > 0) {
+                sections.push(`- Consumes: ${agent.consumes.join(", ")}`);
+            }
+            // Variants
+            if (agent.variants && agent.variants.length > 0) {
+                sections.push("- Variants:");
+                for (const v of agent.variants) {
+                    const parts = [`${v.id} (weight: ${v.weight})`];
+                    if (v.model)
+                        parts.push(`model: ${v.model}`);
+                    if (v.temperature != null)
+                        parts.push(`temperature: ${v.temperature}`);
+                    sections.push(`  - ${parts.join(", ")}`);
+                }
+            }
+            sections.push("");
+        }
+    }
+    // Human nodes
+    const humans = ast.nodes.filter((n) => n.type === "human");
+    if (humans.length > 0) {
+        sections.push("## Human Checkpoints");
+        sections.push("");
+        for (const human of humans) {
+            sections.push(`### ${toTitle(human.id)}`);
+            sections.push("");
+            if (human.description) {
+                sections.push(human.description);
+                sections.push("");
+            }
+            sections.push("**This is a human pause point.** Execution stops here until a human provides input or approval.");
+            if (human.timeout)
+                sections.push(`- Timeout: ${human.timeout}`);
+            if (human.onTimeout)
+                sections.push(`- On timeout: ${human.onTimeout}`);
+            sections.push("");
+        }
+    }
+    // Group nodes
+    const groups = ast.nodes.filter((n) => n.type === "group");
+    if (groups.length > 0) {
+        sections.push("## Group Chats");
+        sections.push("");
+        for (const group of groups) {
+            sections.push(`### ${toTitle(group.id)}`);
+            sections.push("");
+            if (group.description) {
+                sections.push(group.description);
+                sections.push("");
+            }
+            sections.push(`- Members: ${group.members.join(", ")}`);
+            if (group.speakerSelection)
+                sections.push(`- Speaker selection: ${group.speakerSelection}`);
+            if (group.maxRounds != null)
+                sections.push(`- Max rounds: ${group.maxRounds}`);
+            if (group.termination)
+                sections.push(`- Termination: ${group.termination}`);
+            if (group.timeout)
+                sections.push(`- Timeout: ${group.timeout}`);
+            sections.push("");
+        }
+    }
+    // Flow section
+    if (ast.edges.length > 0) {
+        sections.push("## Flow");
+        sections.push("");
+        for (const edge of ast.edges) {
+            const arrow = edge.isError ? `-x->` : `->`;
+            let line = `${edge.from} ${arrow} ${edge.to}`;
+            if (edge.errorType)
+                line += ` [error: ${edge.errorType}]`;
+            if (edge.condition)
+                line += ` [when ${edge.condition}]`;
+            if (edge.maxIterations)
+                line += ` [max ${edge.maxIterations}]`;
+            if (edge.weight != null)
+                line += ` [weight ${edge.weight}]`;
+            if (edge.race)
+                line += ` [race]`;
+            if (edge.tolerance != null)
+                line += ` [tolerance: ${edge.tolerance}]`;
+            if (edge.wait)
+                line += ` [wait ${edge.wait}]`;
+            if (edge.reflection)
+                line += ` [reflection]`;
+            sections.push(`- ${line}`);
+        }
+        sections.push("");
+    }
+    // Gates section
+    const gates = ast.nodes.filter((n) => n.type === "gate");
+    if (gates.length > 0) {
+        sections.push("## Gates");
+        sections.push("");
+        for (const gate of gates) {
+            sections.push(`### ${toTitle(gate.id)}`);
+            if (gate.after)
+                sections.push(`- After: ${gate.after}`);
+            if (gate.before)
+                sections.push(`- Before: ${gate.before}`);
+            if (gate.run)
+                sections.push(`- Run: ${gate.run}`);
+            if (gate.checks && gate.checks.length > 0) {
+                sections.push(`- Checks: ${gate.checks.join(", ")}`);
+            }
+            if (gate.onFail)
+                sections.push(`- On fail: ${gate.onFail}`);
+            sections.push(`- Enforcement: script-level — run gate script manually between agents`);
+            sections.push("");
+        }
+    }
+    // Actions section
+    const actions = ast.nodes.filter((n) => n.type === "action");
+    if (actions.length > 0) {
+        sections.push("## Actions");
+        sections.push("");
+        for (const action of actions) {
+            sections.push(`### ${toTitle(action.id)}`);
+            if (action.description)
+                sections.push(action.description);
+            if (action.kind)
+                sections.push(`- Kind: ${action.kind}`);
+            if (action.source)
+                sections.push(`- Source: ${action.source}`);
+            if (action.commands && action.commands.length > 0) {
+                sections.push(`- Commands:`);
+                for (const cmd of action.commands) {
+                    sections.push(`  - \`${cmd}\``);
+                }
+            }
+            if (action.timeout)
+                sections.push(`- Timeout: ${action.timeout}`);
+            if (action.onFail)
+                sections.push(`- On fail: ${action.onFail}`);
+            if (action.join)
+                sections.push(`- Join: ${action.join}`);
+            sections.push("");
+        }
+    }
+    // Triggers section
+    if (ast.triggers.length > 0) {
+        sections.push("## Commands");
+        sections.push("");
+        for (const trigger of ast.triggers) {
+            sections.push(`- \`/${trigger.name}\`: ${trigger.pattern}`);
+        }
+        sections.push("");
+    }
+    // Include references
+    if (ast.context.includes && ast.context.includes.length > 0) {
+        sections.push("## References");
+        sections.push("");
+        for (const inc of ast.context.includes) {
+            sections.push(`- ${inc}`);
+        }
+        sections.push("");
+    }
+    const DEFAULT_PATH = ".gemini/CONTEXT.md";
+    let contextPath = ast.context.file ?? DEFAULT_PATH;
+    // Safety: never overwrite the user's root-level GEMINI.md
+    if (contextPath === "GEMINI.md" || contextPath === "./GEMINI.md") {
+        contextPath = DEFAULT_PATH;
+    }
+    return {
+        path: contextPath,
+        content: sections.join("\n") + "\n",
+        category: "agent",
+    };
+}
+/**
+ * Generate .gemini/settings.json.
+ *
+ * Maps topology to the real Gemini CLI settings structure:
+ *   general.defaultApprovalMode — permission level
+ *   model.name — model name
+ *   modelConfigs.overrides — temperature, maxTokens, topP, topK
+ *   tools.sandbox — sandbox mode
+ *   context.fileName — context file path
+ *   mcpServers — MCP server configuration
+ *   hooks — hook definitions
+ *   hooksConfig.enabled — hooks toggle
+ *   experimental.enableAgents — agent support
+ */
+function generateSettings(ast) {
+    const settings = {};
+    // --- general.defaultApprovalMode ---
+    let globalPermission;
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    for (const agent of agents) {
+        if (agent.permissions) {
+            // Use the most restrictive: 'supervised' takes priority
+            if (!globalPermission || agent.permissions === "supervised") {
+                globalPermission = agent.permissions;
+            }
+        }
+    }
+    if (globalPermission) {
+        settings.general = { defaultApprovalMode: mapApprovalMode(globalPermission) };
+    }
+    // --- model ---
+    // Only set model.name if it looks like a Gemini model or if a Google
+    // provider is configured.  Non-Gemini model names (haiku, opus, sonnet,
+    // gpt-4o, etc.) would be invalid and could crash the CLI.
+    const defaults = ast.defaults;
+    const firstAgent = agents[0];
+    const hasGoogleProvider = ast.providers?.some((p) => p.name === "google" || p.name === "gemini");
+    const modelName = firstAgent?.model;
+    const isGeminiModel = modelName && /^gemini/i.test(modelName);
+    if (isGeminiModel || (modelName && hasGoogleProvider)) {
+        settings.model = { name: modelName };
+    }
+    // Note: modelConfigs.overrides requires a model match pattern and is
+    // complex — omitted to avoid crashing Gemini CLI.  Temperature, topP,
+    // topK are documented in CONTEXT.md per-agent instead.
+    // --- tools.sandbox ---
+    const toolsConfig = {};
+    const settingsSandbox = ast.settings?.sandbox;
+    if (settingsSandbox !== undefined && settingsSandbox !== null) {
+        if (typeof settingsSandbox === "boolean") {
+            toolsConfig.sandbox = settingsSandbox;
+        }
+        else if (settingsSandbox === "true" || settingsSandbox === "false") {
+            toolsConfig.sandbox = settingsSandbox === "true";
+        }
+        else {
+            // String values like "docker", "network-only" — map to true
+            toolsConfig.sandbox = true;
+        }
+    }
+    else if (globalPermission === "unrestricted") {
+        toolsConfig.sandbox = false;
+    }
+    if (Object.keys(toolsConfig).length > 0) {
+        settings.tools = toolsConfig;
+    }
+    // --- context.fileName ---
+    const DEFAULT_CONTEXT = ".gemini/CONTEXT.md";
+    let contextPath = ast.context.file ?? DEFAULT_CONTEXT;
+    if (contextPath === "GEMINI.md" || contextPath === "./GEMINI.md") {
+        contextPath = DEFAULT_CONTEXT;
+    }
+    settings.context = { fileName: contextPath };
+    // --- mcpServers ---
+    if (Object.keys(ast.mcpServers).length > 0) {
+        const mcpServers = {};
+        for (const [name, config] of Object.entries(ast.mcpServers)) {
+            const entry = {};
+            for (const [key, value] of Object.entries(config)) {
+                entry[key] = value;
+            }
+            // Gemini CLI auto-detects stdio when command is present — strip type
+            if (entry.command) {
+                delete entry.type;
+            }
+            // Ensure env exists
+            if (!entry.env) {
+                entry.env = {};
+            }
+            mcpServers[name] = entry;
+        }
+        settings.mcpServers = mcpServers;
+    }
+    // --- hooks ---
+    const allHooks = collectAllHooks(ast);
+    if (allHooks.length > 0) {
+        const hooksMap = {};
+        for (const hook of allHooks) {
+            const geminiEvent = mapHookEvent(hook.on);
+            if (!hooksMap[geminiEvent]) {
+                hooksMap[geminiEvent] = [];
+            }
+            const hookEntry = {};
+            const hookDef = {
+                type: "command",
+                name: hook.name,
+            };
+            // Inline command vs file path
+            if (isInlineCommand(hook.run)) {
+                hookDef.command = hook.run;
+            }
+            else {
+                // Scripts are generated into .gemini/scripts/, so rewrite the path
+                const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+                hookDef.command = `./.gemini/scripts/${scriptName}`;
+            }
+            if (hook.timeout != null) {
+                hookDef.timeout = hook.timeout;
+            }
+            if (hook.matcher) {
+                hookEntry.matcher = hook.matcher;
+                hookEntry.hooks = [hookDef];
+            }
+            else {
+                // No matcher — just the hook definition
+                hookEntry.hooks = [hookDef];
+            }
+            hooksMap[geminiEvent].push(hookEntry);
+        }
+        settings.hooks = hooksMap;
+        settings.hooksConfig = { enabled: true };
+    }
+    // --- experimental ---
+    if (agents.length > 1) {
+        settings.experimental = { enableAgents: true };
+    }
+    // --- Environment variables ---
+    const envVars = {};
+    for (const [key, val] of Object.entries(ast.env)) {
+        if (typeof val === "string") {
+            // Plain string — check for vault:// prefix
+            envVars[key] = val.startsWith("vault://") ? "<set-via-environment>" : val;
+        }
+        else {
+            // SensitiveValue — use placeholder if sensitive or vault URI
+            const sv = val;
+            if (sv.sensitive || sv.secretRef || sv.value.startsWith("vault://")) {
+                envVars[key] = "<set-via-environment>";
+            }
+            else {
+                envVars[key] = sv.value;
+            }
+        }
+    }
+    // If a google provider exists, scaffold the GEMINI_API_KEY env var
+    if (ast.providers && ast.providers.length > 0) {
+        const googleProvider = ast.providers.find((p) => p.name === "google");
+        if (googleProvider?.apiKey) {
+            const envVarMatch = googleProvider.apiKey.match(/^\$\{(.+)\}$/);
+            if (envVarMatch) {
+                envVars[envVarMatch[1]] = googleProvider.apiKey;
+            }
+        }
+    }
+    if (Object.keys(envVars).length > 0) {
+        settings.env = envVars;
+    }
+    return {
+        path: ".gemini/settings.json",
+        content: JSON.stringify(settings, null, 2) + "\n",
+        category: "machine",
+    };
+}
+/**
+ * Collect all hooks from both the global hooks array and per-agent hooks.
+ */
+function collectAllHooks(ast) {
+    const hooks = [...ast.hooks];
+    // Collect per-agent hooks
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    for (const agent of agents) {
+        if (agent.hooks && agent.hooks.length > 0) {
+            hooks.push(...agent.hooks);
+        }
+    }
+    return hooks;
+}
+/**
+ * Generate .gemini/instructions.md with detailed project instructions.
+ *
+ * Contains agent definitions, role descriptions, skill details, memory
+ * configuration, and workspace protocol information.
+ */
+function generateInstructions(ast) {
+    const sections = [];
+    const name = ast.topology.name;
+    sections.push(`# ${toTitle(name)} — Project Instructions`);
+    sections.push("");
+    if (ast.topology.description) {
+        sections.push(ast.topology.description);
+        sections.push("");
+    }
+    // Roles
+    if (Object.keys(ast.roles).length > 0) {
+        sections.push("## Roles");
+        sections.push("");
+        for (const [role, desc] of Object.entries(ast.roles)) {
+            sections.push(`### ${toTitle(role)}`);
+            sections.push(desc);
+            sections.push("");
+        }
+    }
+    // Skills
+    if (ast.skills.length > 0) {
+        sections.push("## Skills");
+        sections.push("");
+        for (const skill of ast.skills) {
+            sections.push(`### ${toTitle(skill.id)}`);
+            if (skill.description)
+                sections.push(skill.description);
+            if (skill.scripts && skill.scripts.length > 0) {
+                sections.push(`Scripts: ${skill.scripts.join(", ")}`);
+            }
+            if (skill.domains && skill.domains.length > 0) {
+                sections.push(`Domains: ${skill.domains.join(", ")}`);
+            }
+            if (skill.references && skill.references.length > 0) {
+                sections.push(`References: ${skill.references.join(", ")}`);
+            }
+            sections.push("");
+        }
+    }
+    // Memory configuration
+    const memory = ast.memory;
+    if (Object.keys(memory).length > 0) {
+        sections.push("## Memory");
+        sections.push("");
+        if (memory.domains)
+            sections.push("- Domains: configured");
+        if (memory.references)
+            sections.push("- References: configured");
+        if (memory.metrics)
+            sections.push("- Metrics: configured");
+        if (memory.workspace)
+            sections.push("- Workspace: configured");
+        sections.push("");
+    }
+    // Workspace protocol
+    const workspace = memory.workspace;
+    if (workspace?.protocol) {
+        sections.push("## Workspace Protocol");
+        sections.push("");
+        const structure = workspace.structure;
+        if (structure && Array.isArray(structure)) {
+            sections.push("### Directory Structure");
+            for (const item of structure) {
+                sections.push(`- ${item}`);
+            }
+            sections.push("");
+        }
+        // Read/write rules from agents
+        const agents = ast.nodes.filter((n) => n.type === "agent");
+        const rwAgents = agents.filter((a) => (a.reads && a.reads.length > 0) || (a.writes && a.writes.length > 0));
+        if (rwAgents.length > 0) {
+            sections.push("### Read/Write Rules");
+            for (const agent of rwAgents) {
+                sections.push(`#### ${toTitle(agent.id)}`);
+                if (agent.reads && agent.reads.length > 0) {
+                    sections.push(`- Reads: ${agent.reads.join(", ")}`);
+                }
+                if (agent.writes && agent.writes.length > 0) {
+                    sections.push(`- Writes: ${agent.writes.join(", ")}`);
+                }
+                sections.push("");
+            }
+        }
+    }
+    // Depth configuration
+    if (ast.depth.levels.length > 0) {
+        sections.push("## Depth Levels");
+        sections.push("");
+        if (ast.depth.factors.length > 0) {
+            sections.push(`Factors: ${ast.depth.factors.join(", ")}`);
+            sections.push("");
+        }
+        for (const level of ast.depth.levels) {
+            let line = `- Level ${level.level}: ${level.label}`;
+            if (level.omit.length > 0) {
+                line += ` (omit: ${level.omit.join(", ")})`;
+            }
+            sections.push(line);
+        }
+        sections.push("");
+    }
+    // Tool definitions
+    if (ast.toolDefs.length > 0) {
+        sections.push("## Tools");
+        sections.push("");
+        for (const tool of ast.toolDefs) {
+            sections.push(`### ${tool.id}`);
+            sections.push(tool.description);
+            sections.push(`Script: ${tool.script} (${tool.lang ?? "bash"})`);
+            if (tool.args && tool.args.length > 0) {
+                sections.push(`Args: ${tool.args.join(", ")}`);
+            }
+            sections.push("");
+        }
+    }
+    // Schedules section
+    if (ast.schedules.length > 0) {
+        sections.push("## Schedules");
+        sections.push("");
+        for (const job of ast.schedules) {
+            const expr = job.cron ? `cron: ${job.cron}` : job.every ? `every: ${job.every}` : "";
+            const target = job.agent ? `agent: ${job.agent}` : job.action ? `action: ${job.action}` : "";
+            sections.push(`- **${job.id}**: ${expr}${target ? ` -> ${target}` : ""}${job.enabled === false ? " (disabled)" : ""}`);
+        }
+        sections.push("");
+    }
+    // Interfaces section
+    if (ast.interfaces.length > 0) {
+        sections.push("## Interfaces");
+        sections.push("");
+        for (const iface of ast.interfaces) {
+            const typePart = iface.type ? ` (${iface.type})` : "";
+            const configKeys = Object.keys(iface.config);
+            const configPart = configKeys.length > 0 ? ` — ${configKeys.map((k) => `${k}: ${iface.config[k]}`).join(", ")}` : "";
+            sections.push(`- **${iface.id}**${typePart}${configPart}`);
+        }
+        sections.push("");
+    }
+    // Fallback chain from settings
+    const fallbackChain = ast.settings?.["fallback-chain"];
+    if (fallbackChain) {
+        sections.push("## Fallback Chain");
+        sections.push("");
+        if (Array.isArray(fallbackChain)) {
+            sections.push(`Models: ${fallbackChain.join(" -> ")}`);
+        }
+        else {
+            sections.push(`Fallback chain: ${fallbackChain}`);
+        }
+        sections.push("");
+    }
+    // Metering
+    if (ast.metering) {
+        const m = ast.metering;
+        sections.push("## Metering");
+        sections.push("");
+        sections.push(`- Track: ${m.track.join(", ")}`);
+        sections.push(`- Per: ${m.per.join(", ")}`);
+        sections.push(`- Output: ${m.output} (${m.format})`);
+        sections.push(`- Pricing: ${m.pricing}`);
+        sections.push("");
+    }
+    // Defaults
+    if (ast.defaults) {
+        const d = ast.defaults;
+        sections.push("## Defaults");
+        sections.push("");
+        if (d.temperature != null)
+            sections.push(`- Temperature: ${d.temperature}`);
+        if (d.maxTokens != null)
+            sections.push(`- Max tokens: ${d.maxTokens}`);
+        if (d.topP != null)
+            sections.push(`- Top-p: ${d.topP}`);
+        if (d.topK != null)
+            sections.push(`- Top-k: ${d.topK}`);
+        if (d.stop)
+            sections.push(`- Stop sequences: ${d.stop.join(", ")}`);
+        if (d.seed != null)
+            sections.push(`- Seed: ${d.seed}`);
+        if (d.thinking)
+            sections.push(`- Thinking: ${d.thinking}`);
+        if (d.thinkingBudget != null)
+            sections.push(`- Thinking budget: ${d.thinkingBudget} tokens`);
+        if (d.outputFormat)
+            sections.push(`- Output format: ${d.outputFormat}`);
+        if (d.timeout)
+            sections.push(`- Timeout: ${d.timeout}`);
+        if (d.logLevel)
+            sections.push(`- Log level: ${d.logLevel}`);
+        sections.push("");
+    }
+    // Observability
+    if (ast.observability) {
+        const o = ast.observability;
+        sections.push("## Observability");
+        sections.push("");
+        sections.push(`- Enabled: ${o.enabled}`);
+        sections.push(`- Level: ${o.level}`);
+        sections.push(`- Exporter: ${o.exporter}`);
+        if (o.endpoint)
+            sections.push(`- Endpoint: ${o.endpoint}`);
+        if (o.service)
+            sections.push(`- Service: ${o.service}`);
+        sections.push(`- Sample rate: ${o.sampleRate}`);
+        sections.push(`- Capture: prompts=${o.capture.prompts}, completions=${o.capture.completions}, toolArgs=${o.capture.toolArgs}, toolResults=${o.capture.toolResults}`);
+        sections.push(`- Spans: agents=${o.spans.agents}, tools=${o.spans.tools}, gates=${o.spans.gates}, memory=${o.spans.memory}`);
+        sections.push("");
+    }
+    // Checkpoint
+    if (ast.checkpoint) {
+        const c = ast.checkpoint;
+        sections.push("## Checkpoint");
+        sections.push("");
+        sections.push(`- Backend: ${c.backend}`);
+        if (c.connection)
+            sections.push(`- Connection: ${c.connection}`);
+        sections.push(`- Strategy: ${c.strategy}`);
+        if (c.ttl)
+            sections.push(`- TTL: ${c.ttl}`);
+        if (c.replay) {
+            sections.push(`- Replay: enabled=${c.replay.enabled}`);
+            if (c.replay.maxHistory != null)
+                sections.push(`  - Max history: ${c.replay.maxHistory}`);
+            if (c.replay.branch != null)
+                sections.push(`  - Branch: ${c.replay.branch}`);
+        }
+        sections.push("");
+    }
+    // Artifacts
+    if (ast.artifacts.length > 0) {
+        sections.push("## Artifacts");
+        sections.push("");
+        for (const art of ast.artifacts) {
+            let line = `- **${art.id}** (${art.type})`;
+            if (art.path)
+                line += ` — path: ${art.path}`;
+            if (art.retention)
+                line += `, retention: ${art.retention}`;
+            if (art.dependsOn && art.dependsOn.length > 0)
+                line += `, depends on: ${art.dependsOn.join(", ")}`;
+            sections.push(line);
+        }
+        sections.push("");
+    }
+    // Schemas
+    if (ast.schemas.length > 0) {
+        sections.push("## Schemas");
+        sections.push("");
+        for (const schema of ast.schemas) {
+            sections.push(`### ${toTitle(schema.id)}`);
+            for (const field of schema.fields) {
+                sections.push(formatSchemaField(field));
+            }
+            sections.push("");
+        }
+    }
+    // Composition: params
+    if (ast.params && ast.params.length > 0) {
+        sections.push("## Parameters");
+        sections.push("");
+        for (const p of ast.params) {
+            const req = p.required ? " (required)" : "";
+            const def = p.default != null ? ` = ${p.default}` : "";
+            sections.push(`- **${p.name}**: ${p.type}${req}${def}`);
+        }
+        sections.push("");
+    }
+    // Composition: interface endpoints
+    if (ast.interfaceEndpoints) {
+        sections.push("## Interface");
+        sections.push("");
+        sections.push(`- Entry: ${ast.interfaceEndpoints.entry}`);
+        sections.push(`- Exit: ${ast.interfaceEndpoints.exit}`);
+        sections.push("");
+    }
+    // Composition: imports
+    if (ast.imports && ast.imports.length > 0) {
+        sections.push("## Imports");
+        sections.push("");
+        for (const imp of ast.imports) {
+            let line = `- **${imp.alias}** from \`${imp.source}\``;
+            if (imp.sha256)
+                line += ` (sha256: ${imp.sha256})`;
+            if (imp.registry)
+                line += ` [registry: ${imp.registryPackage}@${imp.registryVersion}]`;
+            sections.push(line);
+            if (Object.keys(imp.params).length > 0) {
+                for (const [k, v] of Object.entries(imp.params)) {
+                    sections.push(`  - ${k}: ${v}`);
+                }
+            }
+        }
+        sections.push("");
+    }
+    // Composition: includes
+    if (ast.includes && ast.includes.length > 0) {
+        sections.push("## Includes");
+        sections.push("");
+        for (const inc of ast.includes) {
+            sections.push(`- ${inc.source}`);
+        }
+        sections.push("");
+    }
+    return {
+        path: ".gemini/instructions.md",
+        content: sections.join("\n") + "\n",
+        category: "agent",
+    };
+}
+/**
+ * Generate .gemini/commands/<name>.toml for each trigger.
+ *
+ * Gemini CLI supports custom commands defined as TOML files
+ * in the .gemini/commands/ directory.
+ */
+function generateCommandFiles(ast) {
+    const files = [];
+    // Collect agents sorted by phase for orchestration prompts
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    const sortedAgents = [...agents].sort((a, b) => (a.phase ?? 999) - (b.phase ?? 999));
+    // Collect human/group nodes for special handling
+    const humans = ast.nodes.filter((n) => n.type === "human");
+    const groups = ast.nodes.filter((n) => n.type === "group");
+    // Build workspace paths from agent reads/writes
+    const workspacePaths = new Set();
+    for (const agent of agents) {
+        for (const p of agent.writes ?? [])
+            workspacePaths.add(p);
+        for (const p of agent.reads ?? [])
+            workspacePaths.add(p);
+    }
+    for (const trigger of ast.triggers) {
+        const promptLines = [];
+        // Opening instruction
+        const argRef = trigger.argument ? ` {{args}}` : "";
+        promptLines.push(`Execute the ${toTitle(ast.topology.name)} topology${argRef}.`);
+        promptLines.push("");
+        promptLines.push("Follow the phases below in order. Complete each phase fully before moving to the next.");
+        if (workspacePaths.size > 0) {
+            promptLines.push("Write outputs to the workspace directory at each step.");
+        }
+        // Generate a phase section for each agent
+        for (const agent of sortedAgents) {
+            promptLines.push("");
+            const phaseLabel = agent.phase != null ? `Phase ${agent.phase}` : "Step";
+            promptLines.push(`## ${phaseLabel}: ${toTitle(agent.id)}`);
+            // Role / description
+            if (agent.description) {
+                promptLines.push(`Act as the **${toTitle(agent.id)}** agent. ${agent.description}`);
+            }
+            else if (agent.prompt) {
+                promptLines.push(`Act as the **${toTitle(agent.id)}** agent.`);
+                promptLines.push(agent.prompt);
+            }
+            else {
+                promptLines.push(`Act as the **${toTitle(agent.id)}** agent.`);
+            }
+            // Read/write paths
+            if (agent.reads && agent.reads.length > 0) {
+                promptLines.push(`Read from: ${agent.reads.join(", ")}`);
+            }
+            if (agent.writes && agent.writes.length > 0) {
+                promptLines.push(`Write results to: ${agent.writes.join(", ")}`);
+            }
+            // Outputs / routing
+            if (agent.outputs) {
+                promptLines.push("");
+                for (const [field, values] of Object.entries(agent.outputs)) {
+                    promptLines.push(`Determine ${field}: ${values.join(" | ")}`);
+                }
+            }
+            // Conditional edges from this agent
+            const outEdges = ast.edges.filter((e) => e.from === agent.id);
+            const conditionalEdges = outEdges.filter((e) => e.condition);
+            if (conditionalEdges.length > 0) {
+                promptLines.push("");
+                promptLines.push("Routing:");
+                for (const edge of conditionalEdges) {
+                    const maxNote = edge.maxIterations
+                        ? ` (max ${edge.maxIterations} times)`
+                        : "";
+                    promptLines.push(`- If ${edge.condition} → proceed to ${toTitle(edge.to)}${maxNote}`);
+                }
+            }
+            // Timeout
+            if (agent.timeout) {
+                promptLines.push(`Maximum time: ${agent.timeout}`);
+            }
+        }
+        // Human checkpoints
+        for (const human of humans) {
+            // Find which agents flow into the human node
+            const inEdges = ast.edges.filter((e) => e.to === human.id);
+            if (inEdges.length > 0) {
+                promptLines.push("");
+                promptLines.push(`## Checkpoint: ${toTitle(human.id)}`);
+                if (human.description)
+                    promptLines.push(human.description);
+                promptLines.push("**STOP and wait for human approval before proceeding.**");
+                if (human.timeout) {
+                    promptLines.push(`Timeout: ${human.timeout}`);
+                }
+            }
+        }
+        // Group discussions
+        for (const group of groups) {
+            promptLines.push("");
+            promptLines.push(`## Discussion: ${toTitle(group.id)}`);
+            if (group.description)
+                promptLines.push(group.description);
+            promptLines.push(`Conduct a multi-perspective discussion considering the viewpoints of: ${group.members.join(", ")}.`);
+            if (group.maxRounds != null) {
+                promptLines.push(`Limit to ${group.maxRounds} rounds of discussion.`);
+            }
+            if (group.termination) {
+                promptLines.push(`End when: ${group.termination}`);
+            }
+        }
+        // Final instruction
+        promptLines.push("");
+        promptLines.push("## Summary");
+        promptLines.push("After completing all phases, provide a summary of what happened at each phase and the final outcome.");
+        // Build TOML
+        const description = trigger.argument
+            ? `${trigger.name} — ${ast.topology.description || toTitle(ast.topology.name)} (arg: ${trigger.argument})`
+            : `${trigger.name} — ${ast.topology.description || toTitle(ast.topology.name)}`;
+        // Replace argument placeholder with {{args}}
+        let promptText = promptLines.join("\n");
+        if (trigger.argument) {
+            promptText = promptText.replace(new RegExp(`<${trigger.argument}>`, "g"), "{{args}}");
+        }
+        const tomlContent = [
+            `description = ${JSON.stringify(description)}`,
+            `prompt = """`,
+            promptText,
+            `"""`,
+            "",
+        ].join("\n");
+        files.push({
+            path: `.gemini/commands/${trigger.name}.toml`,
+            content: tomlContent,
+            category: "machine",
+        });
+    }
+    return files;
+}
+/** Generate gate script stubs. */
+function generateGateScripts(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "gate")
+            continue;
+        const gate = node;
+        if (gate.run) {
+            const scriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+            files.push({
+                path: `.gemini/scripts/${scriptName}`,
+                content: shellStub(`Gate: ${gate.id} — ${gate.run}`),
+                category: "script",
+            });
+        }
+    }
+    return files;
+}
+/**
+ * Generate hook script stubs for hooks that reference script files.
+ * Inline commands (like "exit 1") do NOT get script stubs.
+ */
+function generateHookScripts(ast) {
+    const files = [];
+    const allHooks = collectAllHooks(ast);
+    for (const hook of allHooks) {
+        if (!hook.run)
+            continue;
+        // Skip inline commands — they go directly into settings.json
+        if (isInlineCommand(hook.run))
+            continue;
+        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        files.push({
+            path: `.gemini/scripts/${scriptName}`,
+            content: [
+                "#!/usr/bin/env bash",
+                `# Hook: ${hook.name} — fires on ${hook.on}`,
+                "# Auto-generated by agentopology scaffold — edit as needed.",
+                'set -euo pipefail',
+                "",
+                `echo "TODO: implement ${hook.name} hook"`,
+                "",
+            ].join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/** Generate tool script stubs. */
+function generateToolScripts(ast) {
+    const files = [];
+    for (const tool of ast.toolDefs) {
+        const ext = tool.lang === "python" ? "py" : tool.lang === "node" ? "js" : "sh";
+        const shebang = tool.lang === "python"
+            ? "#!/usr/bin/env python3"
+            : tool.lang === "node"
+                ? "#!/usr/bin/env node"
+                : "#!/usr/bin/env bash";
+        const lines = [
+            shebang,
+            `# Tool: ${tool.id} — ${tool.description}`,
+            "# Auto-generated by agentopology scaffold — edit as needed.",
+            "",
+        ];
+        if (tool.lang === "bash" || !tool.lang) {
+            lines.push('set -euo pipefail');
+            lines.push("");
+        }
+        if (tool.args && tool.args.length > 0) {
+            lines.push(`# Args: ${tool.args.join(", ")}`);
+            lines.push("");
+        }
+        if (tool.lang === "python") {
+            lines.push(`print("TODO: implement ${tool.id}")`);
+        }
+        else if (tool.lang === "node") {
+            lines.push(`console.log("TODO: implement ${tool.id}");`);
+        }
+        else {
+            lines.push(`echo "TODO: implement ${tool.id}"`);
+        }
+        lines.push("");
+        files.push({
+            path: `.gemini/scripts/${tool.id}.${ext}`,
+            content: lines.join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/** Generate memory structure directories. */
+function generateMemory(ast) {
+    const files = [];
+    const memory = ast.memory;
+    if (memory.domains) {
+        files.push(gitkeep(".gemini/context/domains"));
+    }
+    if (memory.references) {
+        files.push(gitkeep(".gemini/context/references"));
+    }
+    if (memory.metrics) {
+        files.push({
+            path: ".gemini/metrics.jsonl",
+            content: "",
+            category: "machine",
+        });
+    }
+    if (memory.workspace) {
+        files.push(gitkeep(".gemini/workspace"));
+    }
+    return files;
+}
+/** Generate metering script stub. */
+function generateMetering(ast) {
+    if (!ast.metering)
+        return null;
+    const m = ast.metering;
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# Metering / cost tracking script",
+        "# Auto-generated by agentopology scaffold — edit as needed.",
+        'set -euo pipefail',
+        "",
+        `# Track: ${m.track.join(", ")}`,
+        `# Per: ${m.per.join(", ")}`,
+        `# Output: ${m.output} (${m.format})`,
+        `# Pricing: ${m.pricing}`,
+        "",
+        'echo "TODO: implement metrics collection"',
+        "",
+    ];
+    return {
+        path: "scripts/collect-metrics.sh",
+        content: lines.join("\n"),
+        category: "script",
+    };
+}
+/**
+ * Generate `.gemini/skills/<skill-id>/SKILL.md` files.
+ *
+ * Gemini CLI discovers skills from this directory structure. Each SKILL.md has
+ * YAML front-matter (name, description) and a body with instructions.
+ */
+function generateSkills(ast) {
+    const files = [];
+    for (const skill of ast.skills) {
+        const lines = [];
+        // YAML front-matter
+        lines.push("---");
+        lines.push(`name: ${skill.id}`);
+        lines.push(`description: ${skill.description}`);
+        lines.push("---");
+        lines.push("");
+        // Body text
+        if (skill.prompt) {
+            lines.push(skill.prompt);
+        }
+        else {
+            // Generate a body from scripts, domains, references
+            const bodyParts = [];
+            if (skill.scripts && skill.scripts.length > 0) {
+                bodyParts.push(`Scripts: ${skill.scripts.join(", ")}`);
+            }
+            if (skill.domains && skill.domains.length > 0) {
+                bodyParts.push(`Domains: ${skill.domains.join(", ")}`);
+            }
+            if (skill.references && skill.references.length > 0) {
+                bodyParts.push(`References: ${skill.references.join(", ")}`);
+            }
+            if (bodyParts.length > 0) {
+                lines.push(bodyParts.join("\n"));
+            }
+            else {
+                lines.push(skill.description);
+            }
+        }
+        lines.push("");
+        files.push({
+            path: `.gemini/skills/${skill.id}/SKILL.md`,
+            content: lines.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Binding export
+// ---------------------------------------------------------------------------
+/** Google Gemini CLI binding. */
+export const geminiCliBinding = {
+    name: "gemini-cli",
+    description: "Google Gemini CLI — generates GEMINI.md, .gemini/ directory structure, and scripts.",
+    scaffold(ast) {
+        const files = [];
+        // Main instructions file (.gemini/CONTEXT.md — never root GEMINI.md)
+        files.push(generateGeminiMd(ast));
+        // Settings file (permissions, model, sandbox, MCP, hooks, env)
+        files.push(generateSettings(ast));
+        // Detailed project instructions
+        files.push(generateInstructions(ast));
+        // Command files from triggers (.toml format)
+        files.push(...generateCommandFiles(ast));
+        // Gate scripts
+        files.push(...generateGateScripts(ast));
+        // Hook scripts (only for file-based hooks, not inline commands)
+        files.push(...generateHookScripts(ast));
+        // Tool scripts
+        files.push(...generateToolScripts(ast));
+        // Skill files (.gemini/skills/<id>/SKILL.md)
+        files.push(...generateSkills(ast));
+        // Memory directories
+        files.push(...generateMemory(ast));
+        // Metering
+        const meteringFile = generateMetering(ast);
+        if (meteringFile)
+            files.push(meteringFile);
+        return deduplicateFiles(files);
+    },
+};
+//# sourceMappingURL=gemini-cli.js.map