keystone-cli 0.1.1 → 0.2.0

package/src/templates/agents/keystone-architect.md

@@ -0,0 +1,54 @@
+---
+name: keystone-architect
+description: "Expert at designing Keystone workflows and agents"
+model: gpt-4o
+---
+
+# Role
+You are the Keystone Architect. Your goal is to design and generate high-quality Keystone workflows (.yaml) and agents (.md). You understand the underlying schema and expression syntax perfectly.
+
+# Knowledge Base
+
+## Workflow Schema (.yaml)
+- **name**: Unique identifier for the workflow.
+- **inputs**: Map of `{ type: string, default: any, description: string }` under the `inputs` key.
+- **outputs**: Map of expressions (e.g., `${{ steps.id.output }}`) under the `outputs` key.
+- **steps**: Array of step objects. Each step MUST have an `id` and a `type`:
+  - **shell**: `{ id, type: 'shell', run, dir, env, transform }`
+  - **llm**: `{ id, type: 'llm', agent, prompt, schema }`
+  - **workflow**: `{ id, type: 'workflow', path, inputs }`
+  - **file**: `{ id, type: 'file', path, op: 'read'|'write'|'append', content }`
+  - **request**: `{ id, type: 'request', url, method, body, headers }`
+  - **human**: `{ id, type: 'human', message, inputType: 'confirm'|'text' }`
+  - **sleep**: `{ id, type: 'sleep', duration }`
+- **Common Step Fields**: `needs` (array of IDs), `if` (expression), `retry`, `foreach`, `concurrency`.
+- **IMPORTANT**: Steps run in **parallel** by default. To ensure sequential execution, a step must explicitly list the previous step's ID in its `needs` array.
+
+## Agent Schema (.md)
+Markdown files with YAML frontmatter:
+- **name**: Agent name.
+- **model**: (Optional) e.g., `gpt-4o`, `claude-sonnet-4.5`.
+- **tools**: Array of `{ name, parameters, execution }` where `execution` is a standard Step object.
+- **Body**: The Markdown body is the `systemPrompt`.
+
+## Expression Syntax
+- `${{ inputs.name }}`
+- `${{ steps.id.output }}`
+- `${{ steps.id.status }}`
+- `${{ args.paramName }}` (used inside agent tools)
+- Standard JS-like expressions: `${{ steps.count > 0 ? 'yes' : 'no' }}`
+
+# Output Instructions
+When asked to design a feature:
+1. Provide the necessary Keystone files (Workflows and Agents).
+2. **IMPORTANT**: Return ONLY a raw JSON object. Do not include markdown code blocks, preamble, or postamble.
+
+The JSON structure must be:
+{
+  "files": [
+    {
+      "path": "workflows/...",
+      "content": "..."
+    }
+  ]
+}

package/src/templates/agents/my-agent.md

@@ -0,0 +1,3 @@
+---
+name: my-agent
+---

package/src/templates/agents/summarizer.md

@@ -0,0 +1,28 @@
+---
+name: summarizer
+description: "Summarizes text content"
+model: gpt-4o
+tools:
+  - name: read_file
+    description: "Read the contents of a file"
+    parameters:
+      type: object
+      properties:
+        filepath:
+          type: string
+          description: "The path to the file to read"
+      required: ["filepath"]
+    execution:
+      type: file
+      op: read
+      path: "${{ args.filepath }}"
+---
+
+# Identity
+You are a concise summarizer. Your goal is to extract the key points from any text and present them in a clear, brief format.
+
+## Guidelines
+- Focus on the main ideas and key takeaways
+- Keep summaries under 3-5 sentences unless more detail is explicitly requested
+- Use clear, simple language
+- Maintain objectivity and accuracy

package/src/templates/agents/test-agent.md

@@ -0,0 +1,10 @@
+---
+name: test-agent
+model: gpt-4
+tools:
+  - name: test-tool
+    execution:
+      type: shell
+      run: echo "tool executed with ${{ args.val }}"
+---
+You are a test agent.

package/src/templates/approval-process.yaml

@@ -0,0 +1,36 @@
+name: approval-process
+description: "A workflow demonstrating human-in-the-loop and conditional logic"
+
+inputs:
+  request_details: { type: string, default: "Access to production database" }
+
+steps:
+  - id: request_approval
+    type: human
+    message: "Do you approve the following request: ${{ inputs.request_details }}?"
+    inputType: confirm
+
+  - id: log_approval
+    type: shell
+    if: ${{ steps.request_approval.output == true }}
+    run: echo "Request approved. Proceeding with implementation."
+    needs: [request_approval]
+
+  - id: log_rejection
+    type: shell
+    if: ${{ steps.request_approval.output == false }}
+    run: echo "Request rejected. Notifying requester."
+    needs: [request_approval]
+
+  - id: get_rejection_reason
+    type: human
+    if: ${{ steps.request_approval.output == false }}
+    message: "Please provide a reason for rejection:"
+    inputType: text
+    needs: [request_approval]
+
+  - id: finalize_rejection
+    type: shell
+    if: ${{ steps.request_approval.output == false }}
+    run: echo "Rejection reason - ${{ steps.get_rejection_reason.output }}"
+    needs: [get_rejection_reason]

package/src/templates/basic-inputs.yaml

@@ -0,0 +1,19 @@
+name: basic-inputs
+description: "A simple workflow that greets a user with optional repetition"
+inputs:
+  user_name:
+    type: string
+    description: "The name of the person to greet"
+    default: "World"
+  count:
+    type: number
+    description: "Number of times to greet"
+    default: 1
+
+steps:
+  - id: hello
+    type: shell
+    run: |
+      for i in $(seq 1 ${{ inputs.count }}); do
+        echo "Hello, ${{ escape(inputs.user_name) }}! (Attempt $i)"
+      done

package/src/templates/basic-shell.yaml

@@ -0,0 +1,20 @@
+name: basic-shell
+description: "A simple example workflow demonstrating basic features"
+
+inputs:
+  greeting: { type: string, default: "Hello" }
+  name: { type: string, default: "World" }
+
+outputs:
+  message: ${{ steps.create_message.output }}
+
+steps:
+  - id: create_message
+    type: shell
+    run: echo "${{ escape(inputs.greeting) }}, ${{ escape(inputs.name) }}!"
+    transform: "stdout.trim()"
+
+  - id: print_message
+    type: shell
+    needs: [create_message]
+    run: echo "Generated message - ${{ steps.create_message.output }}"

package/src/templates/batch-processor.yaml

@@ -0,0 +1,43 @@
+name: batch-processor
+description: "Process multiple files in parallel"
+
+inputs:
+  target_dir: { type: string, default: "./data" }
+
+outputs:
+  processed_count: ${{ steps.process_files.outputs.length }}
+
+env:
+  API_KEY: ${{ secrets.API_KEY }}
+
+steps:
+  # 1. Dynamic Input Generation
+  - id: list_files
+    type: shell
+    run: "ls ${{ inputs.target_dir }}/*.txt"
+    # Extract stdout lines into an array
+    transform: "stdout.split('\\n').filter(Boolean)"
+
+  # 2. Matrix/Looping (The Missing Piece)
+  - id: process_files
+    type: llm
+    needs: [list_files]
+    # Iterates over the array from the previous step
+    foreach: ${{ steps.list_files.output }}
+    concurrency: 5
+    # Robustness (The Missing Piece)
+    retry:
+      count: 3
+      backoff: "exponential"
+    timeout: 30000 # 30s limit per item
+    # Step Definition
+    agent: summarizer
+    prompt: "Summarize this file: ${{ item }}"
+
+  # 3. Conditional Logic
+  - id: notify
+    type: request
+    needs: [process_files]
+    if: ${{ steps.process_files.items.every(s => s.status == 'success') }}
+    method: POST
+    url: "https://webhook.site/..."

package/src/templates/cleanup-finally.yaml

@@ -0,0 +1,22 @@
+name: cleanup-finally
+description: "Test the finally block"
+
+steps:
+  - id: step1
+    type: shell
+    run: echo "Main step 1"
+
+  - id: fail_step
+    type: shell
+    run: "exit 1"
+    if: ${{ inputs.should_fail }}
+
+finally:
+  - id: cleanup
+    type: shell
+    run: echo "Cleanup task executed"
+  
+  - id: cleanup_with_dep
+    type: shell
+    needs: [cleanup]
+    run: echo "Cleanup with dependency executed"

package/src/templates/composition-child.yaml

@@ -0,0 +1,13 @@
+name: composition-child
+description: "A simple child workflow"
+
+inputs:
+  name: { type: string }
+
+outputs:
+  result: "Hello from child, ${{ inputs.name }}!"
+
+steps:
+  - id: echo_step
+    type: shell
+    run: echo "Processing ${{ inputs.name }}"

package/src/templates/composition-parent.yaml

@@ -0,0 +1,14 @@
+name: composition-parent
+description: "A parent workflow that calls a child workflow"
+
+steps:
+  - id: run_child
+    type: workflow
+    path: "workflows/composition-child.yaml"
+    inputs:
+      name: "Keystone User"
+
+  - id: print_result
+    type: shell
+    needs: [run_child]
+    run: echo "Child workflow result - ${{ steps.run_child.outputs.result }}"

package/src/templates/data-pipeline.yaml

@@ -0,0 +1,38 @@
+name: data-pipeline
+description: "A workflow that demonstrates file operations and cleanup with 'finally'"
+
+inputs:
+  input_file: { type: string, default: "input.txt" }
+  output_file: { type: string, default: "output.txt" }
+
+steps:
+  - id: prepare_data
+    type: file
+    op: write
+    path: ${{ inputs.input_file }}
+    content: "line 1\nline 2\nline 3"
+
+  - id: read_data
+    type: file
+    op: read
+    path: ${{ inputs.input_file }}
+    needs: [prepare_data]
+
+  - id: process_data
+    type: shell
+    run: |
+      echo "${{ steps.read_data.output }}" | tr '[:lower:]' '[:upper:]'
+    transform: "stdout.trim()"
+    needs: [read_data]
+
+  - id: save_result
+    type: file
+    op: write
+    path: ${{ inputs.output_file }}
+    content: ${{ steps.process_data.output }}
+    needs: [process_data]
+
+finally:
+  - id: cleanup
+    type: shell
+    run: rm ${{ inputs.input_file }}

package/src/templates/full-feature-demo.yaml

@@ -0,0 +1,64 @@
+name: full-feature-demo
+description: "A comprehensive workflow demonstrating multiple feature types"
+
+inputs:
+  message:
+    type: string
+    default: "Hello from Keystone!"
+
+outputs:
+  greeting: ${{ steps.greet.output }}
+  file_count: ${{ steps.count_files.output }}
+  timestamp: ${{ steps.get_date.output }}
+
+steps:
+  # Test shell execution
+  - id: greet
+    type: shell
+    run: echo "${{ inputs.message }}"
+
+  # Test shell with transform
+  - id: get_date
+    type: shell
+    run: date +%s
+    transform: parseInt(stdout.trim())
+
+  # Test file write
+  - id: write_file
+    type: file
+    op: write
+    path: /tmp/keystone-test.txt
+    content: "Test file created at ${{ steps.get_date.output }}"
+
+  # Test file read
+  - id: read_file
+    type: file
+    op: read
+    path: /tmp/keystone-test.txt
+    needs: [write_file]
+
+  # Test shell with dependencies
+  - id: count_files
+    type: shell
+    needs: [write_file]
+    run: ls /tmp/keystone-*.txt | wc -l
+    transform: parseInt(stdout.trim())
+
+  # Test conditional execution
+  - id: success_message
+    type: shell
+    if: ${{ steps.count_files.output > 0 }}
+    needs: [count_files]
+    run: echo "Found files!"
+
+  # Test HTTP request
+  - id: api_test
+    type: request
+    url: https://httpbin.org/get
+    method: GET
+
+  # Test sleep
+  - id: wait
+    type: sleep
+    duration: 100
+    needs: [api_test]

package/src/templates/human-interaction.yaml

@@ -0,0 +1,12 @@
+name: human-interaction
+description: A workflow that prompts the user for input and uses it in another step.
+
+steps:
+  - id: ask_name
+    type: human
+    message: "What is your name?"
+    inputType: text
+
+  - id: greet
+    type: shell
+    run: echo "Hello, ${{ escape(steps.ask_name.output) }}!"

package/src/templates/invalid.yaml

@@ -0,0 +1,5 @@
+name: invalid-workflow
+steps:
+  - id: step1
+    type: shell
+    # Missing 'run' property

package/src/templates/llm-agent.yaml

@@ -0,0 +1,8 @@
+name: llm-agent
+description: "Test LLM step"
+
+steps:
+  - id: ask_llm
+    type: llm
+    agent: summarizer
+    prompt: "Hello, who are you?"

package/src/templates/loop-parallel.yaml

@@ -0,0 +1,37 @@
+name: loop-parallel
+description: "Test the foreach race condition fix and .every() support"
+
+outputs:
+  all_success: ${{ steps.process_items.items.every(s => s.status == 'success') }}
+  item_count: ${{ steps.process_items.outputs.length }}
+  first_output: ${{ steps.process_items.items[0].output }}
+
+steps:
+  # Generate test data
+  - id: generate_items
+    type: shell
+    run: "echo 'item1\nitem2\nitem3\nitem4\nitem5'"
+    transform: "stdout.split('\\n').filter(Boolean)"
+
+  # Process items with concurrency (tests race condition fix)
+  - id: process_items
+    type: shell
+    needs: [generate_items]
+    foreach: ${{ steps.generate_items.output }}
+    concurrency: 3
+    run: "echo 'Processing: ${{ item }}' && sleep 0.1"
+    transform: "stdout.trim()"
+
+  # Test conditional using .every() (tests aggregation fix)
+  - id: success_notification
+    type: shell
+    needs: [process_items]
+    if: ${{ steps.process_items.items.every(s => s.status == 'success') }}
+    run: "echo 'All items processed successfully!'"
+
+  # Test accessing individual item status
+  - id: check_first
+    type: shell
+    needs: [process_items]
+    if: ${{ steps.process_items.items[0].status == 'success' }}
+    run: "echo 'First item was successful'"

package/src/templates/retry-policy.yaml

@@ -0,0 +1,36 @@
+name: retry-policy
+description: "Test retry and timeout features"
+
+steps:
+  # Test retry with a command that fails first few times
+  - id: flaky_command
+    type: shell
+    run: |
+      if [ ! -f /tmp/keystone-retry-test ]; then
+        echo "1" > /tmp/keystone-retry-test
+        exit 1
+      else
+        count=$(cat /tmp/keystone-retry-test)
+        count=$((count + 1))
+        echo $count > /tmp/keystone-retry-test
+        if [ $count -lt 3 ]; then
+          exit 1
+        fi
+        echo "Success after $count attempts"
+      fi
+    retry:
+      count: 3
+      backoff: exponential
+
+  # Test timeout (should complete before timeout)
+  - id: quick_task
+    type: shell
+    run: sleep 0.1 && echo "Completed"
+    timeout: 5000
+    needs: [flaky_command]
+
+  # Cleanup
+  - id: cleanup
+    type: shell
+    run: rm -f /tmp/keystone-retry-test
+    needs: [quick_task]

package/src/templates/scaffold-feature.yaml

@@ -0,0 +1,48 @@
+name: scaffold-feature
+description: "Autonomously build new Keystone workflows and agents"
+
+steps:
+  - id: get_requirements
+    type: human
+    message: "Describe the workflow you want to build:"
+    inputType: text
+
+  - id: design
+    type: llm
+    agent: keystone-architect
+    needs: [get_requirements]
+    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]
+
+  - id: write_files
+    type: file
+    needs: [design]
+    foreach: ${{ steps.design.output.files }}
+    op: write
+    path: ${{ item.path }}
+    content: ${{ item.content }}
+
+  - id: summary
+    type: shell
+    needs: [write_files]
+    run: |
+      echo "Scaffolding complete. Files created:"
+      echo "${{ steps.design.output.files.map(f => f.path).join('\n') }}"

package/src/templates/stop-watch.yaml

@@ -0,0 +1,17 @@
+name: stop-watch
+description: "A simple stopwatch workflow"
+steps:
+  - id: get_duration
+    type: human
+    message: "Please enter the duration (in seconds) for the stopwatch."
+    inputType: text
+  - id: waiting_period
+    type: sleep
+    needs: [get_duration]
+    duration: ${{ Number(steps.get_duration.output) * 1000 }}
+  - id: notify_completion
+    type: human
+    needs: [waiting_period]
+    message: "The stopwatch is complete."
+    inputType: confirm
+outputs: {}

package/src/utils/config-loader.test.ts

@@ -1,6 +1,6 @@
-import { describe, expect, it, afterEach } from 'bun:test';
-import { ConfigLoader } from './config-loader';
+import { afterEach, describe, expect, it } from 'bun:test';
 import type { Config } from '../parser/config-schema';
+import { ConfigLoader } from './config-loader';
 
 describe('ConfigLoader', () => {
   afterEach(() => {