runwork 0.5.0 → 0.6.0

package/dist/auth/login-flow.js

@@ -20,6 +20,106 @@ export async function performLogin(baseUrl) {
     console.log(`If browser didn't open, visit: ${loginUrl}`);
     console.log('');
     console.log('Waiting for authentication...');
+    return pollAndSave(client, sessionId, url);
+}
+/**
+ * Initiate a login session without opening the browser.
+ * Prints the login URL to stdout and polls for completion.
+ * If printOnly is true, prints the URL and returns null (exits without polling).
+ */
+export async function performLoginNoOpen(baseUrl, printOnly) {
+    const url = baseUrl || DEFAULT_BASE_URL;
+    const client = new ApiClient({ apiKey: '', email: '', baseUrl: url });
+    const { loginUrl } = await client.initiateLogin();
+    // Print the URL for the agent/human to use
+    console.log(loginUrl);
+    if (printOnly) {
+        return null;
+    }
+    console.error('Waiting for authentication...');
+    return pollAndSave(client, extractSessionId(loginUrl), url);
+}
+/**
+ * Resume a previously initiated login session by providing the login URL.
+ * Extracts the session ID from the URL and polls until authenticated.
+ */
+export async function performLoginFromUrl(loginUrl) {
+    const sessionId = extractSessionId(loginUrl);
+    const baseUrl = extractBaseUrl(loginUrl);
+    const client = new ApiClient({ apiKey: '', email: '', baseUrl });
+    console.log('Waiting for authentication...');
+    return pollAndSave(client, sessionId, baseUrl);
+}
+/**
+ * Authenticate directly with an API key (no browser flow).
+ * Validates the key by calling the API, then saves credentials.
+ */
+export async function performLoginWithApiKey(apiKey, baseUrl) {
+    const url = baseUrl || DEFAULT_BASE_URL;
+    const client = new ApiClient({ apiKey, email: '', baseUrl: url });
+    // Validate the key by fetching workspaces
+    try {
+        const workspaces = await client.listWorkspaces();
+        const defaultWs = workspaces[0];
+        const creds = {
+            apiKey,
+            email: 'api-key-auth',
+            baseUrl: url,
+            defaultWorkspaceId: defaultWs?.id,
+            defaultWorkspaceName: defaultWs?.name,
+        };
+        saveCredentials(creds);
+        await configureGitCredentials(url);
+        console.log('Logged in with API key.');
+        if (defaultWs) {
+            console.log(`Default workspace: ${defaultWs.name}`);
+        }
+        return creds;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Invalid API key: ${message}`);
+        process.exit(1);
+    }
+}
+/**
+ * Extract session ID from a login URL.
+ * Supports both query param (?session=xxx) and path segment formats.
+ */
+function extractSessionId(loginUrl) {
+    try {
+        const url = new URL(loginUrl);
+        const session = url.searchParams.get('session');
+        if (session)
+            return session;
+        // Try path-based: /cli-auth/SESSION_ID
+        const pathParts = url.pathname.split('/');
+        const authIdx = pathParts.indexOf('cli-auth');
+        if (authIdx >= 0 && pathParts[authIdx + 1]) {
+            return pathParts[authIdx + 1];
+        }
+    }
+    catch {
+        // Not a valid URL
+    }
+    console.error(`Could not extract session ID from URL: ${loginUrl}`);
+    process.exit(1);
+}
+/**
+ * Extract the base URL (origin) from a login URL.
+ */
+function extractBaseUrl(loginUrl) {
+    try {
+        return new URL(loginUrl).origin;
+    }
+    catch {
+        return DEFAULT_BASE_URL;
+    }
+}
+/**
+ * Poll for login completion and save credentials.
+ */
+async function pollAndSave(client, sessionId, baseUrl) {
     const maxAttempts = 60;
     const pollInterval = 5000;
     for (let i = 0; i < maxAttempts; i++) {
@@ -27,7 +127,7 @@ export async function performLogin(baseUrl) {
         const result = await client.pollLogin(sessionId);
         if (result) {
             saveCredentials(result);
-            await configureGitCredentials(result.baseUrl || url);
+            await configureGitCredentials(result.baseUrl || baseUrl);
             console.log(`Logged in as ${result.email}`);
             return result;
         }

package/dist/commands/clone.d.ts

@@ -1,5 +1,13 @@
 import { Command } from 'commander';
 import { ApiClient } from '../api/client.js';
 import type { AppInfo } from '../types.js';
-export declare function execClone(client: ApiClient, app: AppInfo, directory?: string): Promise<string>;
+export interface CloneResult {
+    appId: string;
+    appName: string;
+    slug: string;
+    directory: string;
+    workspaceId: string;
+    workspaceName: string;
+}
+export declare function execClone(client: ApiClient, app: AppInfo, directory?: string): Promise<CloneResult>;
 export declare const cloneCommand: Command;

package/dist/commands/clone.js

@@ -5,10 +5,13 @@ import { join, resolve } from 'path';
 import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { promptSelect } from '../utils/prompt.js';
+import { resolveApp } from '../utils/resolve.js';
 import { generateManifest, saveManifest } from '../template/manifest.js';
 import { extractZip } from '../utils/zip.js';
 import { removeNestedGitDirs } from '../utils/fs.js';
 import { runAgentWizard } from '../ui/banner.js';
+import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { buildCloneGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 export async function execClone(client, app, directory) {
     const slug = app.slug || app.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
     const dir = directory || slug;
@@ -39,7 +42,7 @@ export async function execClone(client, app, directory) {
         execFileSync('git', ['remote', 'add', 'runwork', remoteUrl], { cwd: dir, stdio: 'pipe' });
     }
     try {
-        execFileSync('git', ['fetch', 'runwork', 'main'], { cwd: dir, stdio: 'inherit' });
+        execFileSync('git', ['fetch', 'runwork', 'main'], { cwd: dir, stdio: 'pipe' });
         // Reset to remote HEAD - overlays git-tracked files on top of template
         execFileSync('git', ['reset', '--mixed', 'runwork/main'], { cwd: dir, stdio: 'pipe' });
         // Checkout git-tracked files (overwrites template files where they differ)
@@ -66,33 +69,58 @@ export async function execClone(client, app, directory) {
     catch {
         // App may be new with no registries yet
     }
-    console.log(`\nApp "${app.name}" cloned to ${dir}/`);
-    console.log(`Remote: ${client.getGitRemoteUrl(app.workspaceId, app.id)}`);
-    return resolve(dir);
+    return {
+        appId: app.id,
+        appName: app.name,
+        slug,
+        directory: resolve(dir),
+        workspaceId: app.workspaceId,
+        workspaceName: app.workspaceName,
+    };
 }
 export const cloneCommand = new Command('clone')
     .description('Clone a Runwork app to local development')
     .argument('[appId]', 'App ID to clone (interactive if omitted)')
     .argument('[directory]', 'Target directory')
-    .action(async (appId, directory) => {
+    .option('--app <name-or-id>', 'App name or ID (skips interactive selection)')
+    .action(async (appId, directory, options) => {
     const creds = requireAuth();
     const client = new ApiClient(creds);
+    const useJson = shouldOutputJson(undefined);
     let app;
-    if (appId) {
-        app = await client.getApp(appId);
+    const appRef = options?.app || appId;
+    if (appRef) {
+        app = await resolveApp(client, appRef);
     }
     else {
         const apps = await client.listApps();
         if (apps.length === 0) {
+            if (useJson) {
+                jsonOut(buildErrorResponse('clone', 'No apps found', 'No apps are available to clone.', ['Create an app first with: runwork init my-app']));
+                return;
+            }
             console.error('No apps found.');
             process.exit(1);
         }
         const choice = await promptSelect('Select app to clone:', apps.map(a => ({ label: `${a.name} (${a.workspaceName})`, value: a })));
         app = choice.value;
     }
-    console.log(`Cloning "${app.name}"...`);
-    const dir = await execClone(client, app, directory);
-    const slug = dir.split('/').pop() || dir;
-    await runAgentWizard(dir);
-    console.log(`Next: cd ${slug} && runwork dev`);
+    if (!useJson) {
+        console.log(`Cloning "${app.name}"...`);
+    }
+    const cloneResult = await execClone(client, app, directory);
+    if (useJson) {
+        const response = {
+            success: true,
+            command: 'clone',
+            result: cloneResult,
+            guide: buildCloneGuide(cloneResult.appName, cloneResult.slug),
+        };
+        jsonOut(response);
+        return;
+    }
+    console.log(`\nApp "${cloneResult.appName}" cloned to ${cloneResult.directory}/`);
+    console.log(`Remote: ${client.getGitRemoteUrl(cloneResult.workspaceId, cloneResult.appId)}`);
+    await runAgentWizard(cloneResult.directory);
+    console.log(`Next: cd ${cloneResult.slug} && runwork dev`);
 });

package/dist/commands/deploy.js

@@ -4,13 +4,14 @@ import { readFileSync, existsSync } from 'fs';
 import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { buildDeployGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 export const deployCommand = new Command('deploy')
     .description('Deploy the current app to production')
     .action(async (_opts, command) => {
     const useJson = shouldOutputJson(command.optsWithGlobals().json);
     if (!existsSync('.runwork.json')) {
         if (useJson) {
-            process.stderr.write(JSON.stringify({ error: 'No .runwork.json found. Run `runwork init` first.' }) + '\n');
+            jsonOut(buildErrorResponse('deploy', 'No .runwork.json found', 'This directory is not a Runwork app.', ['Run runwork init to create an app first', 'Or cd into an existing app directory']));
             process.exit(1);
         }
         console.error('No .runwork.json found. Run `runwork init` first.');
@@ -42,7 +43,7 @@ export const deployCommand = new Command('deploy')
     }
     else {
         if (useJson) {
-            process.stderr.write(JSON.stringify({ error: 'No commits to deploy. Commit your changes first.' }) + '\n');
+            jsonOut(buildErrorResponse('deploy', 'Sync failed before deployment', 'Files could not be synced to the remote.', ['Run runwork dev first to ensure files sync correctly', 'Check your network connection', 'Retry runwork deploy']));
             process.exit(1);
         }
         console.error('No commits to deploy. Commit your changes first.');
@@ -51,9 +52,31 @@ export const deployCommand = new Command('deploy')
     // Trigger deploy
     if (!useJson)
         console.log('Deploying...');
-    const result = await client.triggerDeploy(config.appId);
+    let result;
+    try {
+        result = await client.triggerDeploy(config.appId);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (useJson) {
+            jsonOut(buildErrorResponse('deploy', message, 'The deployment API returned an error.', ['Check for TypeScript errors in your code', 'Run runwork dev to test in the sandbox first', 'Retry runwork deploy']));
+            process.exit(1);
+        }
+        console.error(`Deploy failed: ${message}`);
+        process.exit(1);
+    }
     if (useJson) {
-        jsonOut({ deployed: true, url: result.deploymentUrl });
+        const response = {
+            success: true,
+            command: 'deploy',
+            result: {
+                deployed: true,
+                url: result.deploymentUrl,
+                appName: config.appName,
+            },
+            guide: buildDeployGuide(),
+        };
+        jsonOut(response);
         return;
     }
     console.log(`Deployed: ${result.deploymentUrl}`);

package/dist/commands/dev.js

@@ -16,6 +16,7 @@ import { createStatusLine } from '../ui/status-line.js';
 import { createKeyboardListener } from '../ui/keyboard.js';
 import { bold, dim, green, yellow, cyan } from '../ui/colors.js';
 import { shouldOutputJson, jsonLine } from '../utils/output.js';
+import { buildDevSessionGuide } from '../utils/agent-guidance.js';
 async function populateSkill(projectDir, client, appId) {
     try {
         const { skill } = await client.getAppSkill(appId);
@@ -110,6 +111,39 @@ export async function execDev(options) {
     const syncResult = syncWithRemote(cwd);
     if (useJson) {
         jsonLine({ event: 'startup', phase: 'sync', status: syncResult.status, pushed: syncResult.pushed, timestamp: ts() });
+        if (syncResult.status === 'sync-failed') {
+            if (syncResult.error === 'stash-conflict') {
+                jsonLine({
+                    event: 'error',
+                    phase: 'sync',
+                    timestamp: ts(),
+                    error: {
+                        message: 'Merge conflicts detected after stash pop',
+                        diagnosis: 'Local changes could not be automatically merged with the remote state. The stash pop resulted in conflicts that require manual resolution.',
+                        suggestions: [
+                            'Resolve the merge conflicts in the affected files',
+                            'Run git add on resolved files, then git commit',
+                            'Run runwork dev again after resolving conflicts',
+                        ],
+                    },
+                });
+                process.exit(1);
+            }
+            jsonLine({
+                event: 'error',
+                phase: 'sync',
+                timestamp: ts(),
+                error: {
+                    message: syncResult.error ?? 'File sync failed',
+                    diagnosis: 'Could not sync files to the sandbox. This usually means the sandbox session expired or the network connection was interrupted.',
+                    suggestions: [
+                        'Run runwork dev again to start a fresh session',
+                        'Check your network connection',
+                        'Run runwork doctor to diagnose environment issues',
+                    ],
+                },
+            });
+        }
     }
     else {
         switch (syncResult.status) {
@@ -139,7 +173,7 @@ export async function execDev(options) {
     }
     // Emit session_started (JSON) or show banner (human)
     if (useJson) {
-        jsonLine({ event: 'session_started', previewUrl: session.previewUrl, appName: config.appName, timestamp: ts() });
+        jsonLine({ event: 'session_started', previewUrl: session.previewUrl, appName: config.appName, timestamp: ts(), guide: buildDevSessionGuide() });
     }
     else {
         console.log(getDevBanner({ appName: config.appName, previewUrl: session.previewUrl, workspaceName: config.workspaceName }));

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const doctorCommand: Command;

package/dist/commands/doctor.js

@@ -0,0 +1,82 @@
+import { Command } from 'commander';
+import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { bold, dim, green, yellow, cyan } from '../ui/colors.js';
+import { runAllChecks } from '../health/runner.js';
+const STATUS_LABELS = {
+    pass: green('[pass]'),
+    warn: yellow('[warn]'),
+    fail: bold('[FAIL]'),
+    skip: dim('[skip]'),
+};
+const CHECK_LABELS = {
+    'system-deps': 'System dependencies',
+    'cli-version': 'CLI version',
+    'auth': 'Authentication',
+    'network': 'Network',
+    'project-config': 'Project config',
+    'app-exists': 'App exists',
+    'git-remote': 'Git remote',
+    'agent-setup': 'Agent setup',
+};
+function printHumanReport(report) {
+    console.log('');
+    console.log(bold('runwork doctor'));
+    console.log('');
+    for (const check of report.checks) {
+        const status = STATUS_LABELS[check.status] || check.status;
+        const label = (CHECK_LABELS[check.name] || check.name).padEnd(22);
+        console.log(`  ${status} ${label} ${dim(check.message)}`);
+        if (check.details && check.details.length > 1) {
+            for (const detail of check.details) {
+                console.log(`         ${dim('- ' + detail)}`);
+            }
+        }
+    }
+    // Summary
+    const failures = report.checks.filter(c => c.status === 'fail');
+    const warnings = report.checks.filter(c => c.status === 'warn');
+    console.log('');
+    if (failures.length > 0) {
+        console.log(`  ${failures.length} issue${failures.length !== 1 ? 's' : ''} found:`);
+        for (const f of failures) {
+            const label = CHECK_LABELS[f.name] || f.name;
+            if (f.fix) {
+                console.log(`    - ${label}: ${cyan(f.fix)}`);
+            }
+            else {
+                console.log(`    - ${label}: ${f.message}`);
+            }
+        }
+    }
+    if (warnings.length > 0 && failures.length === 0) {
+        console.log(`  ${warnings.length} warning${warnings.length !== 1 ? 's' : ''}:`);
+        for (const w of warnings) {
+            const label = CHECK_LABELS[w.name] || w.name;
+            if (w.fix) {
+                console.log(`    - ${label}: ${cyan(w.fix)}`);
+            }
+            else {
+                console.log(`    - ${label}: ${w.message}`);
+            }
+        }
+    }
+    if (failures.length === 0 && warnings.length === 0) {
+        console.log(`  ${green('All checks passed.')}`);
+    }
+    console.log('');
+}
+export const doctorCommand = new Command('doctor')
+    .description('Check system health: auth, network, project config, agent setup')
+    .action(async (_opts, command) => {
+    const asJson = shouldOutputJson(command.optsWithGlobals().json);
+    const report = await runAllChecks();
+    if (asJson) {
+        jsonOut(report);
+    }
+    else {
+        printHumanReport(report);
+    }
+    if (report.checks.some(c => c.status === 'fail')) {
+        process.exit(1);
+    }
+});

package/dist/commands/info.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { buildInfoGuide } from '../utils/agent-guidance.js';
 import { fetchAppInfo } from '../utils/app-info.js';
 import { bold, cyan, dim, green, yellow, gray } from '../ui/colors.js';
 import { VERSION } from '../generated/version.js';
@@ -186,7 +187,10 @@ export function formatSources(sources) {
 function printHumanOutput(data) {
     console.log('');
     const pad = (label) => label.padEnd(12);
-    console.log(`  ${dim(pad('Workspace:'))}${data.workspace.name || data.workspace.id}`);
+    const wsLabel = data.workspace.name && data.workspace.name !== data.workspace.id
+        ? `${data.workspace.name} ${dim('(' + data.workspace.id + ')')}`
+        : data.workspace.id;
+    console.log(`  ${dim(pad('Workspace:'))}${wsLabel}`);
     if (data.app) {
         console.log('');
         console.log(bold('App Info'));
@@ -368,7 +372,7 @@ export const infoCommand = new Command('info')
         },
     };
     if (asJson) {
-        jsonOut(output);
+        jsonOut({ ...output, guide: buildInfoGuide() });
     }
     else {
         printHumanOutput(output);

package/dist/commands/init.d.ts

@@ -1,7 +1,15 @@
 import { Command } from 'commander';
 import { ApiClient } from '../api/client.js';
 import type { WorkspaceInfo } from '../types.js';
-export declare function execInit(client: ApiClient, appName: string, workspace: WorkspaceInfo): Promise<string>;
+export interface InitResult {
+    appId: string;
+    appName: string;
+    slug: string;
+    directory: string;
+    workspaceId: string;
+    workspaceName: string;
+}
+export declare function execInit(client: ApiClient, appName: string, workspace: WorkspaceInfo): Promise<InitResult>;
 /** Full create flow: prompt for name/workspace, init, and run agent wizard */
-export declare function runCreateFlow(name?: string): Promise<void>;
+export declare function runCreateFlow(name?: string, workspaceFlag?: string): Promise<void>;
 export declare const initCommand: Command;

package/dist/commands/init.js

@@ -5,10 +5,13 @@ import { join, resolve } from 'path';
 import { requireAuth } from '../auth/store.js';
 import { ApiClient } from '../api/client.js';
 import { promptSelect, promptInput } from '../utils/prompt.js';
+import { resolveWorkspace } from '../utils/resolve.js';
 import { generateManifest, saveManifest } from '../template/manifest.js';
 import { extractZip } from '../utils/zip.js';
 import { removeNestedGitDirs } from '../utils/fs.js';
 import { runAgentWizard } from '../ui/banner.js';
+import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { buildInitGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 export async function execInit(client, appName, workspace) {
     const app = await client.initApp(workspace.id, appName);
     const slug = app.slug || appName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
@@ -42,7 +45,7 @@ export async function execInit(client, appName, workspace) {
     writeFileSync(join(dir, '.runwork.json'), JSON.stringify(config, null, 2));
     // Initialize git
     if (!existsSync(join(dir, '.git'))) {
-        execFileSync('git', ['init'], { cwd: dir, stdio: 'inherit' });
+        execFileSync('git', ['init'], { cwd: dir, stdio: 'pipe' });
     }
     // Add runwork remote
     const remoteUrl = client.getGitRemoteUrl(workspace.id, app.id);
@@ -64,34 +67,74 @@ export async function execInit(client, appName, workspace) {
     catch {
         // Nothing to commit is fine
     }
-    execFileSync('git', ['push', '-u', 'runwork', 'main'], { cwd: dir, stdio: 'inherit' });
+    execFileSync('git', ['push', '-u', 'runwork', 'main'], { cwd: dir, stdio: 'pipe' });
     console.log(`\nApp "${app.name}" initialized in ${dir}/`);
-    return resolve(dir);
+    return {
+        appId: app.id,
+        appName: app.name,
+        slug,
+        directory: resolve(dir),
+        workspaceId: workspace.id,
+        workspaceName: workspace.name,
+    };
 }
 /** Full create flow: prompt for name/workspace, init, and run agent wizard */
-export async function runCreateFlow(name) {
+export async function runCreateFlow(name, workspaceFlag) {
+    const useJson = shouldOutputJson(undefined);
     const creds = requireAuth();
     const client = new ApiClient(creds);
     const appName = name || await promptInput('App name');
     if (!appName) {
+        if (useJson) {
+            jsonOut(buildErrorResponse('init', 'App name is required.', 'No app name was provided.', ['Provide an app name as an argument: runwork init <name>']));
+            return;
+        }
         console.error('App name is required.');
         process.exit(1);
     }
-    const workspaces = await client.listWorkspaces();
-    if (workspaces.length === 0) {
-        console.error('No workspaces found. Create one at runwork.ai first.');
-        process.exit(1);
+    let workspace;
+    if (workspaceFlag) {
+        workspace = await resolveWorkspace(client, workspaceFlag);
+    }
+    else {
+        const workspaces = await client.listWorkspaces();
+        if (workspaces.length === 0) {
+            if (useJson) {
+                jsonOut(buildErrorResponse('init', 'No workspaces found.', 'The authenticated account has no workspaces.', ['Create a workspace at runwork.ai first.']));
+                return;
+            }
+            console.error('No workspaces found. Create one at runwork.ai first.');
+            process.exit(1);
+        }
+        if (workspaces.length === 1) {
+            workspace = workspaces[0];
+        }
+        else {
+            const workspaceChoice = await promptSelect('Select workspace:', workspaces.map(w => ({ label: w.name, value: w })));
+            workspace = workspaceChoice.value;
+        }
+    }
+    if (!useJson) {
+        console.log(`Creating "${appName}" in workspace "${workspace.name}"...`);
+    }
+    const initResult = await execInit(client, appName, workspace);
+    if (useJson) {
+        const response = {
+            success: true,
+            command: 'init',
+            result: initResult,
+            guide: buildInitGuide(initResult.appName, initResult.slug),
+        };
+        jsonOut(response);
+        return;
     }
-    const workspaceChoice = await promptSelect('Select workspace:', workspaces.map(w => ({ label: w.name, value: w })));
-    const workspace = workspaceChoice.value;
-    console.log(`Creating "${appName}" in workspace "${workspace.name}"...`);
-    const dir = await execInit(client, appName, workspace);
-    await runAgentWizard(dir);
+    await runAgentWizard(initResult.directory);
 }
 export const initCommand = new Command('init')
     .alias('create')
     .description('Create a new Runwork app')
     .argument('[name]', 'App name')
-    .action(async (name) => {
-    await runCreateFlow(name);
+    .option('--workspace <name-or-id>', 'Workspace name or ID (skips interactive selection)')
+    .action(async (name, options) => {
+    await runCreateFlow(name, options?.workspace);
 });