keystone-cli 0.8.0 → 1.0.0

package/src/templates/dev.yaml

@@ -0,0 +1,134 @@
+name: dev
+description: "Self-bootstrapping DevMode workflow for Keystone CLI"
+
+inputs:
+  task:
+    type: string
+    description: "The development task to perform"
+  auto_approve:
+    type: boolean
+    default: false
+    description: "If true, skip the plan approval step"
+
+outputs:
+  summary: ${{ steps.implement.output.summary }}
+  files_changed: ${{ steps.implement.output.files_changed }}
+
+steps:
+  - id: analyze
+    type: llm
+    agent: keystone-architect
+    useStandardTools: true
+    prompt: |
+      Analyze the following task and the current project structure.
+      Task: ${{ inputs.task }}
+      
+      Identify the relevant files and components that need to be modified or created.
+      Provide a high-level summary of your analysis.
+    outputSchema:
+      type: object
+      properties:
+        analysis: { type: string }
+        affected_files: { type: array, items: { type: string } }
+      required: [analysis, affected_files]
+
+  - id: plan
+    type: llm
+    agent: keystone-architect
+    needs: [analyze]
+    prompt: |
+      Based on the analysis, create a detailed implementation plan for:
+      ${{ inputs.task }}
+
+      Analysis:
+      ${{ steps.analyze.output.analysis }}
+
+      Proposed Implementation Strategy:
+      1. What changes are needed in which files?
+      2. Are there any new files to be created?
+      3. What are the potential risks or breaking changes?
+      4. How will the changes be verified?
+    outputSchema:
+      type: object
+      properties:
+        plan_summary: { type: string }
+        detailed_steps: { type: array, items: { type: string } }
+      required: [plan_summary, detailed_steps]
+
+  - id: approve_plan
+    type: human
+    if: "!${{ inputs.auto_approve }}"
+    needs: [plan]
+    message: |
+      Proposed Plan for: ${{ inputs.task }}
+
+      Summary:
+      ${{ steps.plan.output.plan_summary }}
+
+      Detailed Steps:
+      ${{ steps.plan.output.detailed_steps.join('\n') }}
+
+      Do you want to proceed with this plan? (yes/no)
+    inputType: confirm
+
+  - id: implement
+    type: llm
+    agent: software-engineer
+    needs: [approve_plan]
+    useStandardTools: true
+    allowInsecure: true
+    prompt: |
+      Implement the following plan for the task:
+      ${{ inputs.task }}
+
+      Plan:
+      ${{ steps.plan.output.plan_summary }}
+
+      Detailed Steps:
+      ${{ steps.plan.output.detailed_steps.join('\n') }}
+
+      Use your tools to modify or create the necessary files.
+    outputSchema:
+      type: object
+      properties:
+        summary: { type: string }
+        files_changed: { type: array, items: { type: string } }
+      required: [summary]
+
+  - id: verify
+    type: llm
+    agent: tester
+    needs: [implement]
+    useStandardTools: true
+    allowInsecure: true
+    prompt: |
+      Verify the changes made for the task:
+      ${{ inputs.task }}
+
+      Files changed:
+      ${{ steps.implement.output.files_changed.join(', ') }}
+
+      Run relevant tests and perform any necessary checks to ensure the implementation is correct and hasn't introduced regressions.
+    outputSchema:
+      type: object
+      properties:
+        test_results: { type: string }
+        success: { type: boolean }
+      required: [test_results, success]
+
+  - id: final_review
+    type: human
+    needs: [verify]
+    message: |
+      Implementation Complete for: ${{ inputs.task }}
+
+      Summary of changes:
+      ${{ steps.implement.output.summary }}
+
+      Test Results:
+      ${{ steps.verify.output.test_results }}
+
+      Status: ${{ steps.verify.output.success ? 'PASSED' : 'FAILED' }}
+
+      Should we finalize these changes? (yes/no)
+    inputType: confirm

package/src/templates/engine-example.yaml

@@ -0,0 +1,33 @@
+name: engine-example
+description: "Run an allowlisted external CLI and capture a structured summary"
+
+# Requires an allowlisted engine in .keystone/config.yaml:
+# engines:
+#   allowlist:
+#     bun:
+#       command: bun
+#       version: "1.3."
+#       versionArgs: ["--version"]
+
+inputs:
+  message:
+    type: string
+    default: "Hello engine"
+
+steps:
+  - id: run_engine
+    type: engine
+    command: bun
+    args:
+      - -e
+      - 'const fs = require("node:fs"); const input = fs.readFileSync(0, "utf8"); const data = input ? JSON.parse(input) : {}; const summary = { received: data.message || null }; fs.writeFileSync(process.env.KEYSTONE_ENGINE_SUMMARY_PATH, JSON.stringify(summary));'
+    input:
+      message: ${{ inputs.message }}
+    env:
+      PATH: ${{ env.PATH }}
+    cwd: .
+    outputSchema:
+      type: object
+      properties:
+        received: { type: string }
+      required: [received]

package/src/templates/fan-out-fan-in.yaml

@@ -0,0 +1,61 @@
+name: fan-out-fan-in-example
+description: Demonstrates dynamic join conditions and nested compensations
+
+inputs:
+  should_fail:
+    type: boolean
+    default: false
+
+steps:
+  - id: prepare
+    type: shell
+    run: echo "Preparing..."
+    compensate:
+      id: cleanup_prepare
+      type: shell
+      run: echo "Cleaning up preparation..."
+
+  - id: parallel_1
+    type: shell
+    run: sleep 2 && echo "Parallel 1 done"
+    needs: [prepare]
+    compensate:
+      id: undo_1
+      type: shell
+      run: echo "Undoing Parallel 1..."
+
+  - id: parallel_2
+    type: shell
+    run: |
+      echo "Parallel 2 failing intentionally..."
+      exit 1
+    needs: [prepare]
+    compensate:
+      id: undo_2
+      type: shell
+      run: echo "Undoing Parallel 2..."
+
+  - id: early_join
+    type: join
+    condition: any
+    needs: [parallel_1, parallel_2]
+
+  - id: after_early_join
+    type: shell
+    run: echo "One of the parallel steps finished! Proceeding early..."
+    needs: [early_join]
+
+  - id: final_join
+    type: join
+    condition: all
+    needs: [parallel_1, parallel_2]
+
+  - id: conclude
+    type: shell
+    run: echo "Both parallel steps finished! Workflow complete."
+    needs: [final_join]
+
+compensate:
+  id: workflow_cleanup
+  type: shell
+  run: echo "Performing final top-level workflow cleanup..."

package/src/templates/memory-service.yaml

@@ -38,7 +38,7 @@ steps:
       ${{ steps.recall_preference.output[0].content }}
 
       What programming language should I use? Answer in one word.
-    schema:
+    outputSchema:
       type: object
       properties:
         language:

package/src/templates/parent-rollback.yaml

@@ -0,0 +1,16 @@
+name: nested-rollback-parent
+description: Parent workflow that triggers a child and then fails
+
+steps:
+  - id: run_child
+    type: workflow
+    path: ./child-rollback.yaml
+    compensate:
+      id: parent_post_child_undo
+      type: shell
+      run: echo "Parent cleanup after child rollback..."
+
+  - id: fail_step
+    type: shell
+    run: exit 1
+    needs: [run_child]

package/src/templates/robust-automation.yaml

@@ -23,7 +23,7 @@ steps:
     needs: [auto_heal_demo]
     prompt: |
       Generate a list of 3 random colors. Just list them.
-    schema:
+    outputSchema:
       type: object
       properties:
         colors:

package/src/templates/scaffold-feature.yaml

@@ -7,37 +7,39 @@ steps:
     message: "Describe the workflow you want to build:"
     inputType: text
 
-  - id: design
-    type: llm
-    agent: keystone-architect
+  - id: blueprint
+    type: blueprint
     needs: [get_requirements]
-    allowClarification: true
-    useStandardTools: true
+    agent: keystone-architect
     prompt: |
-      The user wants to build the following:
-      <user_requirements>
-        ${{ steps.get_requirements.output }}
-      </user_requirements>
-      Generate the necessary Keystone workflow and optionally create an agent where appropriate.
-    schema:
-      type: object
-      properties:
-        files:
-          type: array
-          items:
-            type: object
-            properties:
-              path:
-                type: string
-              content:
-                type: string
-            required: [path, content]
-      required: [files]
+      Generate a system blueprint for the following requirements:
+      ${{ steps.get_requirements.output }}
+
+  - id: plan
+    type: workflow
+    needs: [blueprint]
+    path: scaffold-plan
+    inputs:
+      requirements: ${{ steps.get_requirements.output }}
+      blueprint: ${{ steps.blueprint.output }}
+    outputMapping:
+      files: files
+
+  - id: generate
+    type: workflow
+    needs: [blueprint, plan]
+    path: scaffold-generate
+    inputs:
+      requirements: ${{ steps.get_requirements.output }}
+      blueprint: ${{ steps.blueprint.output }}
+      files: ${{ steps.plan.outputs.files }}
+    outputMapping:
+      files: files
 
   - id: write_files
     type: file
-    needs: [design]
-    foreach: ${{ steps.design.output.files }}
+    needs: [generate]
+    foreach: ${{ steps.generate.outputs.files }}
     op: write
     path: ${{ item.path }}
     content: ${{ item.content }}
@@ -47,4 +49,4 @@ steps:
     needs: [write_files]
     run: |
       echo "Scaffolding complete. Files created:"
-      echo "${{ steps.design.output.files.map(f => f.path).join('\n') }}"
+      echo "${{ steps.generate.outputs && steps.generate.outputs.files ? steps.generate.outputs.files.map(f => f.path).join('\n') : '(dry run: no files generated)' }}"

package/src/templates/scaffold-generate.yaml

@@ -0,0 +1,41 @@
+name: scaffold-generate
+description: "Generate file contents from a file plan"
+
+inputs:
+  requirements: { type: string }
+  blueprint: { type: object }
+  files: { type: array }
+
+outputs:
+  files: ${{ steps.generate.output }}
+
+steps:
+  - id: generate
+    type: llm
+    agent: software-engineer
+    allowClarification: true
+    useStandardTools: true
+    foreach: ${{ inputs.files }}
+    prompt: |
+      You are generating the content for a single file based on a system blueprint and a specific file spec.
+
+      <system_blueprint>
+        ${{ inputs.blueprint }}
+      </system_blueprint>
+
+      Overall user requirements:
+      ${{ inputs.requirements }}
+
+      File spec for this file:
+      ${{ item }}
+
+      Produce the full file content for the given path. Ensure it aligns with the architectural constraints and dependencies defined in the blueprint.
+      Return only JSON with fields: path, content.
+    outputSchema:
+      type: object
+      properties:
+        path:
+          type: string
+        content:
+          type: string
+      required: [path, content]

package/src/templates/scaffold-plan.yaml

@@ -0,0 +1,53 @@
+name: scaffold-plan
+description: "Plan the files for a new workflow and optional agents"
+
+inputs:
+  requirements: { type: string }
+  blueprint: { type: object }
+
+outputs:
+  files: ${{ steps.plan.output.files }}
+
+steps:
+  - id: plan
+    type: llm
+    agent: keystone-architect
+    allowClarification: true
+    useStandardTools: true
+    prompt: |
+      You are planning a file structure based on a system blueprint.
+      
+      <system_blueprint>
+        ${{ inputs.blueprint }}
+      </system_blueprint>
+
+      User requirements:
+      ${{ inputs.requirements }}
+
+      Create a file plan. Follow the architecture and file list provided in the blueprint.
+      Use paths under:
+      - .keystone/workflows/ for workflows
+      - .keystone/workflows/agents/ for agents
+
+      Each file should include:
+      - path: relative path
+      - purpose: short purpose statement
+      - notes: optional implementation guidance
+
+      Return only the structured JSON required by the schema.
+    outputSchema:
+      type: object
+      properties:
+        files:
+          type: array
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+              purpose:
+                type: string
+              notes:
+                type: string
+            required: [path, purpose]
+      required: [files]

package/src/types/status.ts

@@ -10,6 +10,8 @@ export const StepStatus = {
   SUSPENDED: 'suspended',
   SKIPPED: 'skipped',
   RUNNING: 'running',
+  CANCELED: 'canceled',
+  WAITING: 'waiting', // Waiting on durable timer
 } as const;
 
 export type StepStatusType = (typeof StepStatus)[keyof typeof StepStatus];
@@ -20,6 +22,7 @@ export const WorkflowStatus = {
   PAUSED: 'paused',
   SUSPENDED: 'suspended',
   RUNNING: 'running',
+  CANCELED: 'canceled',
 } as const;
 
 export type WorkflowStatusType = (typeof WorkflowStatus)[keyof typeof WorkflowStatus];

package/src/ui/dashboard.tsx

@@ -1,6 +1,7 @@
 import { Box, Newline, Text, render, useInput } from 'ink';
 import React, { useState, useEffect, useCallback, useMemo } from 'react';
 import { WorkflowDb } from '../db/workflow-db.ts';
+import { ConsoleLogger } from '../utils/logger.ts';
 
 interface Run {
   id: string;
@@ -10,6 +11,8 @@ interface Run {
   total_tokens?: number;
 }
 
+const logger = new ConsoleLogger();
+
 const Dashboard = () => {
   const [runs, setRuns] = useState<Run[]>([]);
   const [loading, setLoading] = useState(true);
@@ -50,9 +53,7 @@ const Dashboard = () => {
       );
       setRuns(runsWithUsage);
     } catch (error) {
-      // Dashboard is UI, console.error is acceptable but let's be consistent if possible.
-      // For now we keep it as is or could use a toast.
-      console.error('Failed to fetch runs:', error);
+      logger.error(`Failed to fetch runs: ${String(error)}`);
     } finally {
       setLoading(false);
     }

package/src/utils/assets.macro.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * Bun macro to read all files in a directory and return them as a map.
+ * This runs at build-time.
+ */
+export function bundleAssets(): Record<string, string> {
+  const dirPath = process.env.ASSETS_DIR || '.keystone';
+  const assets: Record<string, string> = {};
+
+  if (!existsSync(dirPath)) {
+    // If directory doesn't exist, return empty (e.g. during dev of CLI itself)
+    return {};
+  }
+
+  function walk(currentDir: string) {
+    const files = readdirSync(currentDir);
+    for (const file of files) {
+      const fullPath = join(currentDir, file);
+      const stats = statSync(fullPath);
+
+      if (stats.isDirectory()) {
+        walk(fullPath);
+      } else if (stats.isFile()) {
+        // Use relative path as key
+        const relPath = relative(dirPath, fullPath);
+        assets[relPath] = readFileSync(fullPath, 'utf8');
+      }
+    }
+  }
+
+  walk(dirPath);
+
+  return assets;
+}