@guildai/cli 0.6.1 → 0.7.0

package/README.md

@@ -229,6 +229,8 @@ guild version                           # Show version info
 ```bash
 guild setup                             # Install skills + configure MCP server
 guild setup --claude-md                 # Also create a CLAUDE.md template
+guild setup --codex                     # Install Codex skills + configure MCP server
+guild setup --codex --agents-md         # Also create an AGENTS.md template
 guild setup --no-mcp                    # Install skills only, skip MCP configuration
 guild mcp                               # Start MCP server (used by Claude Code, etc.)
 ```
@@ -243,7 +245,7 @@ The CLI includes an [MCP](https://modelcontextprotocol.io/) server that exposes
 guild setup
 ```
 
-This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Claude Code (and other MCP-compatible tools) will automatically connect when they detect it.
+This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Use `guild setup --codex` to install Codex skills instead. Claude Code and other MCP-compatible tools will automatically connect when they detect `.mcp.json`.
 
 **What it provides:**
 

package/dist/commands/agent/chat.js

@@ -16,7 +16,6 @@ import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
 import { format } from '../../lib/progress.js';
 import { showBetaGuidance } from '../../lib/auth.js';
 import { pollUntilComplete } from '../../lib/polling.js';
-import { runGit } from '../../lib/git.js';
 import { suppressScrollbackClear } from '../../lib/alternate-screen.js';
 import * as readline from 'readline';
 import { pollForResponse } from '../../lib/session-polling.js';
@@ -34,7 +33,7 @@ export function createAgentChatCommand() {
         .option('--path <dir>', 'Path to agent directory (defaults to current directory)')
         .option('--workspace <identifier>', 'Workspace ID or full name (e.g., owner/workspace-name)')
         .option('--mode <format>', 'Input mode: json (one-shot) or jsonl (line-by-line)')
-        .option('--ephemeral', 'Chat using unsaved changes (no guild agent save required)')
+        .option('--version <id>', 'Chat with a specific version (UUID or version number)')
         .option('--no-splash', 'Skip the splash screen animation')
         .option('--resume <session-id>', 'Resume an existing session')
         .option('--open', 'Open session in web dashboard')
@@ -67,10 +66,23 @@ export function createAgentChatCommand() {
             const quiet = isQuietMode();
             const resolvedPath = path.resolve(agentPath);
             // Resolve the version to chat with.
-            // Default: use the latest saved version (requires clean working tree).
-            // --ephemeral: read local files and create an ephemeral version.
+            // Default: create ephemeral version from working directory.
+            // --version: use a specific existing version.
             let version;
-            if (options.ephemeral) {
+            if (options.version) {
+                // Explicit version: look it up by ID or version number
+                const existingVersions = (await client.get(`/agents/${agentId}/versions`));
+                const match = existingVersions.items.find((v) => v.id === options.version || v.version_number === options.version);
+                if (!match) {
+                    console.error(`Error: Version not found: ${options.version}`);
+                    console.error('');
+                    console.error('List available versions:');
+                    console.error(`  guild agent versions ${agentId}`);
+                    process.exit(1);
+                }
+                version = match;
+            }
+            else {
                 if (!quiet) {
                     console.error('Building agent...');
                 }
@@ -81,43 +93,6 @@ export function createAgentChatCommand() {
                     version_type: 'EPHEMERAL',
                 }));
             }
-            else {
-                // Require clean working tree
-                const { stdout: statusOutput } = await runGit(['status', '--porcelain'], {
-                    cwd: resolvedPath,
-                });
-                if (statusOutput.trim().length > 0) {
-                    console.error('Error: Working tree has unsaved changes');
-                    console.error('');
-                    console.error('Options:');
-                    console.error('  1. Save your changes first:');
-                    console.error('       guild agent save --message "your changes"');
-                    console.error('');
-                    console.error('  2. Chat with unsaved changes:');
-                    console.error('       guild agent chat --ephemeral');
-                    process.exit(1);
-                }
-                // Get commit SHA and look for an existing version
-                const { stdout: shaOutput } = await runGit(['rev-parse', 'HEAD'], {
-                    cwd: resolvedPath,
-                });
-                const commitSha = shaOutput.trim();
-                const existingVersions = (await client.get(`/agents/${agentId}/versions`));
-                const existing = existingVersions.items.find((v) => v.sha === commitSha);
-                if (existing) {
-                    version = existing;
-                }
-                else {
-                    if (!quiet) {
-                        console.error('Building agent...');
-                    }
-                    version = (await client.post(`/agents/${agentId}/versions`, {
-                        commit_sha: commitSha,
-                        summary: '[Chat] Development version',
-                        version_type: 'COMMITTED',
-                    }));
-                }
-            }
             // Wait for build to complete (skip if version already validated)
             if (version.validation_status === 'PENDING' ||
                 version.validation_status === 'RUNNING') {

package/dist/commands/agent/publish.js

@@ -4,8 +4,8 @@ import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { getAgentId, resolveAgentRef } from '../../lib/agent-helpers.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
-import { pollUntilComplete } from '../../lib/polling.js';
 import { createOutputWriter } from '../../lib/output.js';
+import { waitForValidation, waitForPublish } from '../../lib/version-helpers.js';
 export function createAgentPublishCommand() {
     const cmd = new Command('publish');
     cmd
@@ -37,71 +37,31 @@ export function createAgentPublishCommand() {
                 process.exit(1);
             }
             // Check validation status before attempting publish
-            let validationStatus = versionToPublish.validation_status;
             let currentVersion = versionToPublish;
+            const validationStatus = currentVersion.validation_status;
             if (validationStatus === 'PENDING' || validationStatus === 'RUNNING') {
                 if (options.wait) {
-                    // Wait for validation to complete
-                    const result = await pollUntilComplete({
-                        resourceId: versionToPublish.id,
-                        endpoint: `/versions/${versionToPublish.id}`,
-                        isComplete: (response) => response.validation_status !== 'PENDING' &&
-                            response.validation_status !== 'RUNNING',
-                        message: 'Waiting for validation to complete...',
-                        successMessage: 'Validation complete',
-                        timeoutMessage: 'Validation timed out',
-                        maxAttempts: 120, // 2 minutes
-                        delayMs: 1000,
-                    });
-                    if (!result.success || !result.response) {
-                        output.error('Validation did not complete in time', 'Check status manually:\n  guild agent versions');
-                        process.exit(1);
-                    }
-                    currentVersion = result.response;
-                    validationStatus = currentVersion.validation_status;
-                    // Re-check validation status after waiting - will be handled below
-                    // by the main validation check
+                    currentVersion = await waitForValidation(currentVersion.id, output);
                 }
                 else {
-                    output.error('Cannot publish: validation is still in progress', `Validation status: ${validationStatus === 'PENDING' ? 'Waiting to start' : 'Running'}\n\nThe version number is extracted from package.json during validation.\n\nOptions:\n  • Wait for validation: guild agent publish --wait\n  • Check status: guild agent versions`);
+                    output.error('Cannot publish: validation is still in progress', `Validation status: ${validationStatus === 'PENDING' ? 'Waiting to start' : 'Running'}\n\nOptions:\n  • Wait for validation: guild agent publish --wait\n  • Check status: guild agent versions`);
                     process.exit(1);
                 }
             }
-            if (validationStatus === 'FAILED') {
-                // Fetch validation steps to show the actual error
-                let failureDetails = '';
-                try {
-                    const stepsResponse = await client.get(`/versions/${currentVersion.id}/validation/steps`);
-                    const failedSteps = stepsResponse.steps.filter((step) => step.status === 'FAILED');
-                    if (failedSteps.length > 0) {
-                        const stepMessages = failedSteps.map((step) => {
-                            let msg = `Step "${step.name}" failed:`;
-                            if (step.content) {
-                                msg += `\n  ${step.content}`;
-                            }
-                            return msg;
-                        });
-                        failureDetails = stepMessages.join('\n\n');
-                    }
-                    else {
-                        failureDetails =
-                            'No failed steps found. Check validation logs for details.';
-                    }
-                }
-                catch {
-                    // If we can't fetch steps, just show generic message
-                    failureDetails = 'Could not fetch validation details.';
-                }
-                output.error('Cannot publish: validation failed', `${failureDetails}\n\nFix the issues, then save a new version:\n  guild agent save --message "Fix validation errors"`);
+            else if (validationStatus === 'FAILED') {
+                output.error('Cannot publish: validation failed', 'Fix the issues, then save a new version:\n  guild agent save --message "Fix validation errors"');
                 process.exit(1);
             }
-            // Note: version_number is only set after validation extracts it from package.json,
-            // and only enforced at publish time (drafts don't require versions)
             // Publish version
-            await client.post(`/versions/${currentVersion.id}/publish`, {});
+            currentVersion = await client.post(`/versions/${currentVersion.id}/publish`, {});
+            if (options.wait && currentVersion.status !== 'PUBLISHED') {
+                currentVersion = await waitForPublish(currentVersion.id, output);
+            }
             const details = {
                 agent: `${currentVersion.agent?.name || config?.name || agentId}${config ? '' : ` (${agentId})`}`,
-                status: 'DRAFT → PUBLISHED',
+                status: currentVersion.status === 'PUBLISHED'
+                    ? 'DRAFT → PUBLISHED'
+                    : 'DRAFT → PUBLISHING',
             };
             if (currentVersion.version_number) {
                 details.version = currentVersion.version_number;

package/dist/commands/agent/save.js

@@ -9,7 +9,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { getAuthenticatedUrl } from '../../lib/auth.js';
 import { runGit, GitError, formatGitError } from '../../lib/git.js';
-import { pollUntilComplete } from '../../lib/polling.js';
+import { waitForValidation, waitForPublish } from '../../lib/version-helpers.js';
 export function createAgentSaveCommand() {
     const cmd = new Command('save');
     cmd
@@ -255,58 +255,18 @@ export function createAgentSaveCommand() {
                 version_type: 'COMMITTED',
             });
             output.progress(`✓ Created version (${version.id})`);
-            // --publish implies --wait
-            const shouldWait = options.wait || options.publish;
-            // If --wait or --publish, wait for validation to complete
-            if (shouldWait) {
-                const pollResult = await pollUntilComplete({
-                    resourceId: version.id,
-                    endpoint: `/versions/${version.id}`,
-                    isComplete: (response) => response.validation_status !== 'PENDING' &&
-                        response.validation_status !== 'RUNNING',
-                    message: 'Waiting for validation to complete...',
-                    successMessage: 'Validation complete',
-                    timeoutMessage: 'Validation timed out',
-                    maxAttempts: 120, // 2 minutes
-                    delayMs: 1000,
-                });
-                if (!pollResult.success || !pollResult.response) {
-                    output.error('Validation did not complete in time', 'Check status manually:\n  guild agent versions');
-                    process.exit(1);
-                }
-                version = pollResult.response;
-                // Check validation status
-                if (version.validation_status === 'FAILED') {
-                    let failureDetails = '';
-                    // Fetch validation steps to show the actual error
-                    try {
-                        const stepsResponse = await client.get(`/versions/${version.id}/validation/steps`);
-                        const failedSteps = stepsResponse.steps.filter((step) => step.status === 'FAILED');
-                        if (failedSteps.length > 0) {
-                            const stepMessages = failedSteps.map((step) => step.content
-                                ? `Step "${step.name}" failed: ${step.content}`
-                                : `Step "${step.name}" failed`);
-                            failureDetails = stepMessages.join('\n');
-                        }
-                        else {
-                            failureDetails =
-                                'No failed steps found. Check validation logs for details.';
-                        }
-                    }
-                    catch {
-                        failureDetails = 'Could not fetch validation details.';
-                    }
-                    failureDetails +=
-                        '\n\nFix the issues, commit, and save a new version:\n  git add . && git commit -m "Fix validation errors"\n  guild agent save';
-                    output.error('Validation failed', failureDetails);
-                    process.exit(1);
-                }
+            if (options.wait) {
+                version = await waitForValidation(version.id, output);
             }
-            // If --publish and validation passed, publish the version
             if (options.publish) {
                 output.progress('Validation passed, publishing...');
                 version = await client.post(`/versions/${version.id}/publish`, {});
-                output.progress('✓ Published');
+                if (options.wait && version.status !== 'PUBLISHED') {
+                    version = await waitForPublish(version.id, output);
+                }
+                else {
+                    output.progress('✓ Published');
+                }
             }
             output.progress('');
             output.progress('Version details:');
@@ -317,10 +277,14 @@ export function createAgentSaveCommand() {
                 output.progress(`  Published at: ${version.published_at}`);
             }
             output.progress(`  Summary: ${version.summary}`);
-            if (options.publish) {
+            if (options.publish && version.status === 'PUBLISHED') {
                 output.progress('');
                 output.progress('Version is now published and available in the catalog.');
             }
+            else if (options.publish) {
+                output.progress('');
+                output.progress('Publish is in progress. Use --wait to wait for completion.');
+            }
             else {
                 output.progress('');
                 output.progress('To publish this version:');

package/dist/commands/agent/test.js

@@ -17,7 +17,7 @@ import { isQuietMode, getOutputMode } from '../../lib/output-mode.js';
 import { pollForResponse } from '../../lib/session-polling.js';
 import { readStdinAsJSON, ensureInteractiveStdin } from '../../lib/stdin.js';
 import { loadLocalConfig, getWorkspaceId } from '../../lib/guild-config.js';
-import { runGit, GitError, formatGitError } from '../../lib/git.js';
+import { GitError, formatGitError } from '../../lib/git.js';
 import { pollUntilComplete } from '../../lib/polling.js';
 import { readAgentFiles } from '../../lib/agent-helpers.js';
 import { fetchSession, fetchSessionEvents } from '../../lib/session-resume.js';
@@ -33,7 +33,7 @@ export function createAgentTestCommand() {
         .description('Test agent in interactive REPL session')
         .option('--workspace <identifier>', 'Workspace ID or full name (e.g., owner/workspace-name)')
         .option('--mode <format>', 'Input mode: json (one-shot) or jsonl (line-by-line)')
-        .option('--ephemeral', 'Test unsaved changes via ephemeral version (no guild agent save required)')
+        .option('--version <id>', 'Test a specific version (UUID or version number)')
         .option('--resume <session-id>', 'Resume an existing test session')
         .option('--open', 'Open session in web dashboard')
         .action(async (options) => {
@@ -75,12 +75,10 @@ export function createAgentTestCommand() {
                 console.error('  guild agent clone <agent-id>');
                 process.exit(1);
             }
-            // For ephemeral mode, we skip git checks and read files directly
-            // For committed mode, we require a clean working tree
-            let commitSha = null;
+            // Read agent files from disk for ephemeral version creation.
+            // Skipped when --version is provided (testing a specific existing version).
             let agentFiles = null;
-            if (options.ephemeral) {
-                // Ephemeral mode: read files from disk
+            if (!options.version) {
                 try {
                     agentFiles = await readAgentFiles(cwd);
                 }
@@ -96,28 +94,6 @@ export function createAgentTestCommand() {
                     process.exit(1);
                 }
             }
-            else {
-                // Committed mode: require clean working tree
-                const { stdout: statusOutput } = await runGit(['status', '--porcelain'], {
-                    cwd,
-                });
-                if (statusOutput.trim().length > 0) {
-                    console.error('Error: Working tree has unsaved changes');
-                    console.error('');
-                    console.error('Options:');
-                    console.error('  1. Save your changes first:');
-                    console.error('       guild agent save --message "your changes"');
-                    console.error('');
-                    console.error('  2. Test unsaved changes:');
-                    console.error('       guild agent test --ephemeral');
-                    process.exit(1);
-                }
-                // Get commit SHA
-                const { stdout: shaOutput } = await runGit(['rev-parse', 'HEAD'], {
-                    cwd,
-                });
-                commitSha = shaOutput.trim();
-            }
             // If using JSON input, read and validate it early (before auth/session creation)
             // This provides better UX - fail fast on bad JSON without needing auth
             let inputData;
@@ -156,33 +132,31 @@ export function createAgentTestCommand() {
             }
             // Validate auth before any API calls or UI rendering
             await ensureAuthenticated();
-            // Create version for testing
+            // Resolve version for testing
             const client = new GuildAPIClient();
             let version;
             try {
-                if (options.ephemeral && agentFiles) {
-                    // Ephemeral version: send file contents directly
+                if (options.version) {
+                    // Explicit version: look it up by ID or version number
+                    const existingVersions = (await client.get(`/agents/${guildConfig.agent_id}/versions`));
+                    const match = existingVersions.items.find((v) => v.id === options.version || v.version_number === options.version);
+                    if (!match) {
+                        console.error(`Error: Version not found: ${options.version}`);
+                        console.error('');
+                        console.error('List available versions:');
+                        console.error(`  guild agent versions ${guildConfig.agent_id}`);
+                        process.exit(1);
+                    }
+                    version = match;
+                }
+                else {
+                    // Default: create ephemeral version from working directory
                     version = (await client.post(`/agents/${guildConfig.agent_id}/versions`, {
                         files: agentFiles,
                         summary: '[Test] Ephemeral development version',
                         version_type: 'EPHEMERAL',
                     }));
                 }
-                else {
-                    // Committed mode: check if a version for this commit already exists
-                    const existingVersions = (await client.get(`/agents/${guildConfig.agent_id}/versions`));
-                    const existing = existingVersions.items.find((v) => v.sha === commitSha);
-                    if (existing) {
-                        version = existing;
-                    }
-                    else {
-                        version = (await client.post(`/agents/${guildConfig.agent_id}/versions`, {
-                            commit_sha: commitSha,
-                            summary: '[Test] Development version',
-                            version_type: 'COMMITTED',
-                        }));
-                    }
-                }
             }
             catch (error) {
                 const formattedError = handleAxiosError(error);
@@ -280,9 +254,9 @@ export function createAgentTestCommand() {
             const quiet = isQuietMode();
             if (!quiet) {
                 console.log(`✓ Agent: ${guildConfig.name} (${guildConfig.agent_id})`);
-                const versionDisplay = options.ephemeral
-                    ? 'ephemeral (unsaved changes)'
-                    : commitSha?.substring(0, 12) || 'unknown';
+                const versionDisplay = options.version
+                    ? options.version
+                    : 'ephemeral (working directory)';
                 console.log(`✓ Version: ${versionDisplay}`);
                 console.log(`✓ Workspace: ${workspaceId}`);
                 const sessionLink = session.session_url
@@ -452,7 +426,6 @@ export function createAgentTestCommand() {
             console.error('Failed to start test session. Troubleshooting:');
             console.error('  - Verify the agent exists: guild agent get');
             console.error('  - Check your workspace: guild workspace list');
-            console.error('  - Test unsaved changes: guild agent test --ephemeral');
             if (formattedError.code) {
                 console.error(`  - Error code: ${formattedError.code}`);
             }

package/dist/commands/chat.d.ts

@@ -17,8 +17,9 @@ export interface ChatAppProps {
     resumeEvents?: SessionEvent[];
     resumeCommand?: string;
     openDashboard?: boolean;
+    eventFilter?: Set<string>;
 }
-export declare function ChatApp({ initialPrompt, version, workspaceId, versionId, agentName, showSplash, resumeSession, resumeEvents, resumeCommand, openDashboard, }: ChatAppProps): React.JSX.Element;
+export declare function ChatApp({ initialPrompt, version, workspaceId, versionId, agentName, showSplash, resumeSession, resumeEvents, resumeCommand, openDashboard, eventFilter, }: ChatAppProps): React.JSX.Element;
 export declare function ensureAuthenticated(): Promise<string>;
 export declare function createSession(client: GuildAPIClient, workspaceId: string | undefined, initialPrompt: string, versionId?: string, onProgress?: (status: string) => void): Promise<Session>;
 export declare function createChatCommand(): Command;