keystone-cli 0.2.0 → 0.3.0

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
@@ -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
@@ -332,10 +345,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,9 +392,9 @@ 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 |
 | `completion [shell]` | Generate shell completion script (zsh, bash) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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,7 +27,12 @@
     "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",

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' };
@@ -265,7 +265,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 +273,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 +340,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 +351,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 +485,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');
 
@@ -551,18 +624,35 @@ auth
       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');
-
-        const prompt = 'Token: ';
-        process.stdout.write(prompt);
-        for await (const line of console) {
-          token = line.trim();
-          break;
+        try {
+          const deviceLogin = await AuthManager.initGitHubDeviceLogin();
+
+          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;
+          }
         }
       }
 

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(),
 });

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.`);
         }