keystone-cli 0.2.0 → 0.3.1

package/README.md

@@ -80,6 +80,11 @@ Add your API keys to the generated `.env` file:
 OPENAI_API_KEY=sk-...
 ANTHROPIC_API_KEY=sk-ant-...
 ```
+Alternatively, you can use the built-in authentication management:
+```bash
+keystone auth login openai
+keystone auth login anthropic
+```
 
 ### 3. Run a Workflow
 ```bash
@@ -131,8 +136,8 @@ mcp_servers:
   github:
     command: npx
     args: ["-y", "@modelcontextprotocol/server-github"]
-      env:
-        GITHUB_PERSONAL_ACCESS_TOKEN: "your-github-pat" # Or omit if GITHUB_TOKEN is in your .env
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "your-github-pat" # Or omit if GITHUB_TOKEN is in your .env
 
 storage:
 
@@ -175,7 +180,7 @@ You can add any OpenAI-compatible provider (Groq, Together AI, Perplexity, Local
 Keystone supports using your GitHub Copilot subscription directly. To authenticate (using the GitHub Device Flow):
 
 ```bash
-keystone auth login
+keystone auth login github
 ```
 
 Then, you can use Copilot in your configuration:
@@ -187,10 +192,18 @@ providers:
     default_model: gpt-4o
 ```
 
-Authentication tokens for Copilot are managed automatically after the initial login. For other providers, API keys should be stored in a `.env` file in your project root:
+Authentication tokens for Copilot are managed automatically after the initial login. 
+
+### API Key Management
+
+For other providers, you can either store API keys in a `.env` file in your project root:
 - `OPENAI_API_KEY`
 - `ANTHROPIC_API_KEY`
 
+Or use the `keystone auth login` command to securely store them in your local machine's configuration:
+- `keystone auth login openai`
+- `keystone auth login anthropic`
+
 ---
 
 ## 📝 Workflow Example
@@ -252,6 +265,7 @@ Keystone supports several specialized step types:
   - `inputType: confirm`: Simple Enter-to-continue prompt.
   - `inputType: text`: Prompt for a string input, available via `${{ steps.id.output }}`.
 - `workflow`: Trigger another workflow as a sub-step.
+- `script`: Run arbitrary JavaScript in a secure sandbox (`isolated-vm` with fallback to `node:vm`).
 - `sleep`: Pause execution for a specified duration.
 
 All steps support common features like `needs` (dependencies), `if` (conditionals), `retry`, `timeout`, `foreach` (parallel iteration), and `transform` (post-process output using expressions).
@@ -314,7 +328,7 @@ You are a software developer. You can use tools to explore the codebase.
 Keystone can itself act as an MCP server, allowing other agents (like Claude Desktop or GitHub Copilot) to discover and run your workflows as tools.
 
 ```bash
-keystone mcp
+keystone mcp start
 ```
 
 > **Note:** Workflow execution via the Keystone MCP server is synchronous. This provides a better experience for agents as they receive the final results directly, though it means the connection remains open for the duration of the workflow run.
@@ -332,10 +346,13 @@ mcp_servers:
     command: npx
     args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
 
-  # Remote server (SSE)
+  # Remote server (via proxy)
   atlassian:
-    type: remote
-    url: https://mcp.atlassian.com/v1/sse
+    type: local
+    command: npx
+    args: ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
+    oauth:
+      scope: tools:read
 ```
 
 #### Using MCP in Steps
@@ -376,11 +393,12 @@ In these examples, the agent will have access to all tools provided by the MCP s
 | `logs <run_id>` | View logs and step status for a specific run |
 | `graph <workflow>` | Generate a Mermaid diagram of the workflow |
 | `config` | Show current configuration and providers |
-| `auth status` | Show authentication status |
-| `auth login` | Login to an authentication provider (GitHub) |
-| `auth logout` | Logout and clear authentication tokens |
+| `auth status [provider]` | Show authentication status |
+| `auth login [provider]` | Login to an authentication provider (github, openai, anthropic) |
+| `auth logout [provider]` | Logout and clear authentication tokens |
 | `ui` | Open the interactive TUI dashboard |
-| `mcp` | Start the Keystone MCP server |
+| `mcp start` | Start the Keystone MCP server |
+| `mcp login <server>` | Login to a remote MCP server |
 | `completion [shell]` | Generate shell completion script (zsh, bash) |
 | `prune [--days N]` | Cleanup old run data from the database |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A local-first, declarative, agentic workflow orchestrator built on Bun",
   "type": "module",
   "bin": {
@@ -13,7 +13,13 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write ."
   },
-  "keywords": ["workflow", "orchestrator", "agentic", "automation", "bun"],
+  "keywords": [
+    "workflow",
+    "orchestrator",
+    "agentic",
+    "automation",
+    "bun"
+  ],
   "author": "Mark Hingston",
   "license": "MIT",
   "repository": {
@@ -21,15 +27,22 @@
     "url": "https://github.com/mhingston/keystone-cli.git"
   },
   "homepage": "https://github.com/mhingston/keystone-cli#readme",
-  "files": ["src", "README.md", "LICENSE", "logo.png"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "logo.png"
+  ],
   "dependencies": {
     "@jsep-plugin/arrow": "^1.0.6",
     "@jsep-plugin/object": "^1.2.2",
     "@types/react": "^19.2.7",
     "commander": "^12.1.0",
+    "dagre": "^0.8.5",
     "ink": "^6.5.1",
     "ink-select-input": "3.1.2",
     "ink-spinner": "^5.0.0",
+    "isolated-vm": "^6.0.2",
     "js-yaml": "^4.1.0",
     "jsep": "^1.4.0",
     "react": "^19.2.3",
@@ -37,7 +50,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@types/js-yaml": "^4.0.9"
+    "@types/bun": "^1.3.5",
+    "@types/dagre": "^0.7.53",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.0.3"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { Command } from 'commander';
 
 import exploreAgent from './templates/agents/explore.md' with { type: 'text' };
@@ -12,7 +12,7 @@ import scaffoldWorkflow from './templates/scaffold-feature.yaml' with { type: 't
 import { WorkflowDb } from './db/workflow-db.ts';
 import { WorkflowParser } from './parser/workflow-parser.ts';
 import { ConfigLoader } from './utils/config-loader.ts';
-import { generateMermaidGraph, renderMermaidAsAscii } from './utils/mermaid.ts';
+import { generateMermaidGraph, renderWorkflowAsAscii } from './utils/mermaid.ts';
 import { WorkflowRegistry } from './utils/workflow-registry.ts';
 
 import pkg from '../package.json' with { type: 'json' };
@@ -204,12 +204,11 @@ program
     try {
       const resolvedPath = WorkflowRegistry.resolvePath(workflowPath);
       const workflow = WorkflowParser.loadWorkflow(resolvedPath);
-      const mermaid = generateMermaidGraph(workflow);
-
-      const ascii = await renderMermaidAsAscii(mermaid);
+      const ascii = renderWorkflowAsAscii(workflow);
       if (ascii) {
         console.log(`\n${ascii}\n`);
       } else {
+        const mermaid = generateMermaidGraph(workflow);
         console.log('\n```mermaid');
         console.log(mermaid);
         console.log('```\n');
@@ -265,7 +264,7 @@ program
 
       // Import WorkflowRunner dynamically
       const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
-      const runner = new WorkflowRunner(workflow, { inputs });
+      const runner = new WorkflowRunner(workflow, { inputs, workflowDir: dirname(resolvedPath) });
 
       const outputs = await runner.run();
 
@@ -273,6 +272,7 @@ program
         console.log('Outputs:');
         console.log(JSON.stringify(runner.redact(outputs), null, 2));
       }
+      process.exit(0);
     } catch (error) {
       console.error(
         '✗ Failed to execute workflow:',
@@ -339,7 +339,10 @@ program
 
       // Import WorkflowRunner dynamically
       const { WorkflowRunner } = await import('./runner/workflow-runner.ts');
-      const runner = new WorkflowRunner(workflow, { resumeRunId: runId });
+      const runner = new WorkflowRunner(workflow, {
+        resumeRunId: runId,
+        workflowDir: dirname(workflowPath),
+      });
 
       const outputs = await runner.run();
 
@@ -347,6 +350,7 @@ program
         console.log('Outputs:');
         console.log(JSON.stringify(runner.redact(outputs), null, 2));
       }
+      process.exit(0);
     } catch (error) {
       console.error('✗ Failed to resume workflow:', error instanceof Error ? error.message : error);
       process.exit(1);
@@ -480,9 +484,77 @@ program
   });
 
 // ===== keystone mcp =====
-program
-  .command('mcp')
-  .description('Start the Model Context Protocol server')
+const mcp = program.command('mcp').description('Model Context Protocol management');
+
+mcp
+  .command('login')
+  .description('Login to an MCP server')
+  .argument('<server>', 'Server name (from config)')
+  .action(async (serverName) => {
+    const { ConfigLoader } = await import('./utils/config-loader.ts');
+    const { AuthManager } = await import('./utils/auth-manager.ts');
+
+    const config = ConfigLoader.load();
+    const server = config.mcp_servers[serverName];
+
+    if (!server || !server.oauth) {
+      console.error(`✗ MCP server '${serverName}' is not configured with OAuth.`);
+      process.exit(1);
+    }
+
+    let url = server.url;
+
+    // If it's a local server using mcp-remote, try to find the URL in args
+    if (!url && server.type === 'local' && server.args) {
+      url = server.args.find((arg) => arg.startsWith('http'));
+    }
+
+    if (!url) {
+      console.error(
+        `✗ MCP server '${serverName}' does not have a URL configured for authentication.`
+      );
+      console.log('  Please add a "url" property to your server configuration.');
+      process.exit(1);
+    }
+
+    console.log(`\n🔐 Authenticating with MCP server: ${serverName}`);
+    console.log(`   URL: ${url}\n`);
+
+    // For now, we'll support a manual token entry until we have a full browser redirect flow
+    // Most MCP OAuth servers provide a way to get a token via a URL
+    const authUrl = url.replace('/sse', '/authorize') || url;
+    console.log('1. Visit the following URL to authorize:');
+    console.log(`   ${authUrl}`);
+    console.log(
+      '\n   Note: If you encounter errors, ensure the server is correctly configured and accessible.'
+    );
+    console.log('   You can still manually provide an OAuth token below if you have one.');
+    console.log('\n2. Paste the access token below:\n');
+
+    const prompt = 'Access Token: ';
+    process.stdout.write(prompt);
+
+    let token = '';
+    for await (const line of console) {
+      token = line.trim();
+      break;
+    }
+
+    if (token) {
+      const auth = AuthManager.load();
+      const mcp_tokens = auth.mcp_tokens || {};
+      mcp_tokens[serverName] = { access_token: token };
+      AuthManager.save({ mcp_tokens });
+      console.log(`\n✓ Successfully saved token for MCP server: ${serverName}`);
+    } else {
+      console.error('✗ No token provided.');
+      process.exit(1);
+    }
+  });
+
+mcp
+  .command('start')
+  .description('Start the Keystone MCP server (to use Keystone as a tool)')
   .action(async () => {
     const { MCPServer } = await import('./runner/mcp-server.ts');
 
@@ -541,28 +613,49 @@ const auth = program.command('auth').description('Authentication management');
 auth
   .command('login')
   .description('Login to an authentication provider')
-  .option('-p, --provider <provider>', 'Authentication provider', 'github')
+  .argument('[provider]', 'Authentication provider', 'github')
+  .option(
+    '-p, --provider <provider>',
+    'Authentication provider (deprecated, use positional argument)'
+  )
   .option('-t, --token <token>', 'Personal Access Token (if not using interactive mode)')
-  .action(async (options) => {
+  .action(async (providerArg, options) => {
     const { AuthManager } = await import('./utils/auth-manager.ts');
-    const provider = options.provider.toLowerCase();
+    const provider = (options.provider || providerArg).toLowerCase();
 
     if (provider === 'github') {
       let token = options.token;
 
       if (!token) {
-        console.log('\nTo login with GitHub:');
-        console.log(
-          '1. Generate a Personal Access Token (Classic) with "copilot" scope (or full repo access).'
-        );
-        console.log('   https://github.com/settings/tokens/new');
-        console.log('2. Paste the token below:\n');
+        try {
+          const deviceLogin = await AuthManager.initGitHubDeviceLogin();
 
-        const prompt = 'Token: ';
-        process.stdout.write(prompt);
-        for await (const line of console) {
-          token = line.trim();
-          break;
+          console.log('\nTo login with GitHub:');
+          console.log(`1. Visit: ${deviceLogin.verification_uri}`);
+          console.log(`2. Enter code: ${deviceLogin.user_code}\n`);
+
+          console.log('Waiting for authorization...');
+          token = await AuthManager.pollGitHubDeviceLogin(deviceLogin.device_code);
+        } catch (error) {
+          console.error(
+            '\n✗ Failed to login with GitHub device flow:',
+            error instanceof Error ? error.message : error
+          );
+          console.log('\nFalling back to manual token entry...');
+
+          console.log('\nTo login with GitHub manually:');
+          console.log(
+            '1. Generate a Personal Access Token (Classic) with "copilot" scope (or full repo access).'
+          );
+          console.log('   https://github.com/settings/tokens/new');
+          console.log('2. Paste the token below:\n');
+
+          const prompt = 'Token: ';
+          process.stdout.write(prompt);
+          for await (const line of console) {
+            token = line.trim();
+            break;
+          }
         }
       }
 
@@ -585,6 +678,31 @@ auth
         console.error('✗ No token provided.');
         process.exit(1);
       }
+    } else if (provider === 'openai' || provider === 'anthropic') {
+      let key = options.token; // Use --token if provided as the API key
+
+      if (!key) {
+        console.log(`\n🔑 Login to ${provider.toUpperCase()}`);
+        console.log(`   Please provide your ${provider.toUpperCase()} API key.\n`);
+        const prompt = 'API Key: ';
+        process.stdout.write(prompt);
+        for await (const line of console) {
+          key = line.trim();
+          break;
+        }
+      }
+
+      if (key) {
+        if (provider === 'openai') {
+          AuthManager.save({ openai_api_key: key });
+        } else {
+          AuthManager.save({ anthropic_api_key: key });
+        }
+        console.log(`\n✓ Successfully saved ${provider.toUpperCase()} API key.`);
+      } else {
+        console.error('✗ No API key provided.');
+        process.exit(1);
+      }
     } else {
       console.error(`✗ Unsupported provider: ${provider}`);
       process.exit(1);
@@ -612,13 +730,33 @@ auth
         }
       } else if (provider) {
         console.log(
-          `  ⊘ Not logged into GitHub. Run "keystone auth login --provider github" to authenticate.`
+          `  ⊘ Not logged into GitHub. Run "keystone auth login github" to authenticate.`
+        );
+      }
+    }
+
+    if (!provider || provider === 'openai') {
+      if (auth.openai_api_key) {
+        console.log('  ✓ OpenAI API key configured');
+      } else if (provider) {
+        console.log(
+          `  ⊘ OpenAI API key not configured. Run "keystone auth login openai" to authenticate.`
+        );
+      }
+    }
+
+    if (!provider || provider === 'anthropic') {
+      if (auth.anthropic_api_key) {
+        console.log('  ✓ Anthropic API key configured');
+      } else if (provider) {
+        console.log(
+          `  ⊘ Anthropic API key not configured. Run "keystone auth login anthropic" to authenticate.`
         );
       }
     }
 
-    if (!auth.github_token && !provider) {
-      console.log('  ⊘ Not logged in. Run "keystone auth login" to authenticate.');
+    if (!auth.github_token && !auth.openai_api_key && !auth.anthropic_api_key && !provider) {
+      console.log('  ⊘ No providers configured. Run "keystone auth login" to authenticate.');
     }
   });
 
@@ -641,6 +779,12 @@ auth
         copilot_expires_at: undefined,
       });
       console.log('✓ Successfully logged out of GitHub.');
+    } else if (provider === 'openai') {
+      AuthManager.save({ openai_api_key: undefined });
+      console.log('✓ Successfully cleared OpenAI API key.');
+    } else if (provider === 'anthropic') {
+      AuthManager.save({ anthropic_api_key: undefined });
+      console.log('✓ Successfully cleared Anthropic API key.');
     } else {
       console.error(`✗ Unknown provider: ${provider}`);
       process.exit(1);

package/src/expression/evaluator.test.ts

@@ -59,6 +59,10 @@ describe('ExpressionEvaluator', () => {
     expect(ExpressionEvaluator.evaluate('${{ false && 1 }}', context)).toBe(false);
     expect(ExpressionEvaluator.evaluate('${{ true || 1 }}', context)).toBe(true);
     expect(ExpressionEvaluator.evaluate('${{ false || 1 }}', context)).toBe(1);
+    // Explicit short-circuit tests
+    expect(ExpressionEvaluator.evaluate('${{ false && undefined_var }}', context)).toBe(false);
+    expect(ExpressionEvaluator.evaluate('${{ true || undefined_var }}', context)).toBe(true);
+    expect(ExpressionEvaluator.evaluate('${{ true && 2 }}', context)).toBe(2);
   });
 
   test('should support comparison operators', () => {

package/src/expression/evaluator.ts

@@ -83,7 +83,15 @@ export class ExpressionEvaluator {
         return '';
       }
 
-      if (typeof result === 'object') {
+      if (typeof result === 'object' && result !== null) {
+        // Special handling for shell command results to avoid [object Object] or JSON in commands
+        if (
+          'stdout' in result &&
+          'exitCode' in result &&
+          typeof (result as Record<string, unknown>).stdout === 'string'
+        ) {
+          return (result as Record<string, unknown>).stdout.trim();
+        }
         return JSON.stringify(result, null, 2);
       }
 

package/src/parser/agent-parser.ts

@@ -44,11 +44,18 @@ export function parseAgent(filePath: string): Agent {
   return result.data;
 }
 
-export function resolveAgentPath(agentName: string): string {
-  const possiblePaths = [
+export function resolveAgentPath(agentName: string, baseDir?: string): string {
+  const possiblePaths: string[] = [];
+
+  if (baseDir) {
+    possiblePaths.push(join(baseDir, 'agents', `${agentName}.md`));
+    possiblePaths.push(join(baseDir, '..', 'agents', `${agentName}.md`));
+  }
+
+  possiblePaths.push(
     join(process.cwd(), '.keystone', 'workflows', 'agents', `${agentName}.md`),
-    join(homedir(), '.keystone', 'workflows', 'agents', `${agentName}.md`),
-  ];
+    join(homedir(), '.keystone', 'workflows', 'agents', `${agentName}.md`)
+  );
 
   for (const path of possiblePaths) {
     if (existsSync(path)) {

package/src/parser/config-schema.ts

@@ -48,11 +48,22 @@ export const ConfigSchema = z.object({
           command: z.string(),
           args: z.array(z.string()).optional(),
           env: z.record(z.string()).optional(),
+          url: z.string().url().optional(),
+          oauth: z
+            .object({
+              scope: z.string().optional(),
+            })
+            .optional(),
         }),
         z.object({
           type: z.literal('remote'),
           url: z.string().url(),
           headers: z.record(z.string()).optional(),
+          oauth: z
+            .object({
+              scope: z.string().optional(),
+            })
+            .optional(),
         }),
       ])
     )

package/src/parser/schema.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 // ===== Input/Output Schema =====
 
 const InputSchema = z.object({
-  type: z.string(),
+  type: z.enum(['string', 'number', 'boolean', 'array', 'object']),
   default: z.any().optional(),
   description: z.string().optional(),
 });
@@ -105,17 +105,26 @@ const SleepStepSchema = BaseStepSchema.extend({
   duration: z.union([z.number().int().positive(), z.string()]),
 });
 
+const ScriptStepSchema = BaseStepSchema.extend({
+  type: z.literal('script'),
+  run: z.string(),
+});
+
 // ===== Discriminated Union for Steps =====
 
-export const StepSchema = z.discriminatedUnion('type', [
-  ShellStepSchema,
-  LlmStepSchema,
-  WorkflowStepSchema,
-  FileStepSchema,
-  RequestStepSchema,
-  HumanStepSchema,
-  SleepStepSchema,
-]);
+// biome-ignore lint/suspicious/noExplicitAny: Recursive Zod type
+export const StepSchema: z.ZodType<any> = z.lazy(() =>
+  z.discriminatedUnion('type', [
+    ShellStepSchema,
+    LlmStepSchema,
+    WorkflowStepSchema,
+    FileStepSchema,
+    RequestStepSchema,
+    HumanStepSchema,
+    SleepStepSchema,
+    ScriptStepSchema,
+  ])
+);
 
 // ===== Workflow Schema =====
 
@@ -152,6 +161,7 @@ export type FileStep = z.infer<typeof FileStepSchema>;
 export type RequestStep = z.infer<typeof RequestStepSchema>;
 export type HumanStep = z.infer<typeof HumanStepSchema>;
 export type SleepStep = z.infer<typeof SleepStepSchema>;
+export type ScriptStep = z.infer<typeof ScriptStepSchema>;
 export type Workflow = z.infer<typeof WorkflowSchema>;
 export type AgentTool = z.infer<typeof AgentToolSchema>;
 export type Agent = z.infer<typeof AgentSchema>;

package/src/parser/workflow-parser.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import * as yaml from 'js-yaml';
 import { z } from 'zod';
 import { ExpressionEvaluator } from '../expression/evaluator.ts';
@@ -15,6 +15,7 @@ export class WorkflowParser {
       const content = readFileSync(path, 'utf-8');
       const raw = yaml.load(content);
       const workflow = WorkflowSchema.parse(raw);
+      const workflowDir = dirname(path);
 
       // Resolve implicit dependencies from expressions
       WorkflowParser.resolveImplicitDependencies(workflow);
@@ -23,7 +24,7 @@ export class WorkflowParser {
       WorkflowParser.validateDAG(workflow);
 
       // Validate agents exist
-      WorkflowParser.validateAgents(workflow);
+      WorkflowParser.validateAgents(workflow, workflowDir);
 
       // Validate finally block
       WorkflowParser.validateFinally(workflow);
@@ -121,12 +122,12 @@ export class WorkflowParser {
   /**
    * Validate that all agents referenced in LLM steps exist
    */
-  private static validateAgents(workflow: Workflow): void {
+  private static validateAgents(workflow: Workflow, baseDir?: string): void {
     const allSteps = [...workflow.steps, ...(workflow.finally || [])];
     for (const step of allSteps) {
       if (step.type === 'llm') {
         try {
-          resolveAgentPath(step.agent);
+          resolveAgentPath(step.agent, baseDir);
         } catch (error) {
           throw new Error(`Agent "${step.agent}" referenced in step "${step.id}" not found.`);
         }