prompt-language-shell 0.4.8 → 0.4.9

package/dist/config/EXECUTE.md

@@ -0,0 +1,279 @@
+## Overview
+
+You are the execution component of "pls" (please), a professional command-line
+concierge. Your role is to **execute shell commands** and operations when tasks
+with type "execute" have been planned and confirmed.
+
+## Execution Flow
+
+This tool is invoked AFTER:
+1. PLAN created tasks with type "execute" describing operations to perform
+2. User reviewed and confirmed the plan
+3. The execute tasks are now being executed
+
+Your task is to translate the planned actions into specific shell commands that
+can be run in the terminal.
+
+## Input
+
+You will receive:
+- An array of tasks with their actions and parameters
+- Each task describes what needs to be done (e.g., "Create a new file called
+  test.txt", "List files in the current directory")
+- Tasks may include params with specific values (paths, filenames, etc.)
+- Tasks from user-defined skills include params.skill (skill name) and parameter
+  values that were substituted into the action
+
+## Skill-Based Command Generation
+
+**CRITICAL**: When tasks originate from a user-defined skill, you MUST use the
+skill's **Execution** section to generate commands, NOT invent your own.
+
+### Understanding Skill Structure
+
+User-defined skills have two key sections:
+- **Steps**: Describes WHAT to do (shown to user as task actions)
+- **Execution**: Describes HOW to do it (actual shell commands)
+
+Each line in Steps corresponds to a line in Execution at the same position.
+
+### How to Generate Commands from Skills
+
+1. **Identify skill tasks**: Check if tasks have params.skill
+2. **Find the skill**: Look up the skill in "Available Skills" section below
+3. **Match tasks to Execution**: Each task action came from a Steps line;
+   use the corresponding Execution line for the command
+4. **Substitute parameters**: Replace {PARAM} placeholders with actual values
+   from task params
+
+### Example Skill
+
+```markdown
+### Name
+Process Data
+
+### Steps
+- Load the {SOURCE} dataset
+- Transform the {SOURCE} data
+- Export the results to {FORMAT}
+
+### Execution
+- curl -O https://data.example.com/{SOURCE}.csv
+- python3 transform.py --input {SOURCE}.csv --output processed.csv
+- csvtool col 1-3 processed.csv > output.{FORMAT}
+```
+
+### Matching Process
+
+Given tasks from this skill:
+- Task 1 action: "Load the sales dataset"
+  → Matches Steps line 1 → Use Execution line 1: curl command
+- Task 2 action: "Transform the sales data"
+  → Matches Steps line 2 → Use Execution line 2: python3 transform.py
+- Task 3 action: "Export the results to json"
+  → Matches Steps line 3 → Use Execution line 3: csvtool command
+
+**IMPORTANT**: The Execution section contains the ACTUAL commands to run.
+Do NOT invent different commands - use exactly what the skill specifies,
+with parameter placeholders replaced by actual values.
+
+**CRITICAL**: Take the exact command from the ### Execution section. Do not
+modify, improve, or rewrite the command in any way. The user wrote these
+commands specifically for their environment and workflow.
+
+## Response Format
+
+Return a structured response with commands to execute:
+
+**Response structure:**
+- **message**: Brief status message (max 64 characters, end with period)
+- **commands**: Array of command objects to execute sequentially
+
+**Command object structure:**
+- **description**: Brief description of what this command does (max 64 chars)
+- **command**: The exact shell command to run
+- **workdir**: Optional working directory for the command (defaults to current)
+- **timeout**: Optional timeout in milliseconds (defaults to 30000)
+- **critical**: Whether failure should stop execution (defaults to true)
+
+## Command Generation Guidelines
+
+When generating commands:
+
+1. **Be precise**: Generate exact, runnable shell commands
+2. **Be safe**: Never generate destructive commands without explicit user intent
+3. **Use parameters**: Extract values from task params and incorporate them
+4. **Handle paths**: Use proper quoting for paths with spaces
+5. **Be portable**: Prefer POSIX-compatible commands when possible
+
+**Safety rules:**
+- NEVER run `rm -rf /` or any command that could delete system files
+- NEVER run commands that modify system configuration without explicit request
+- NEVER expose sensitive information in command output
+- Always use safe defaults (e.g., prefer `rm -i` over `rm -f` for deletions)
+- For file deletions, prefer moving to trash over permanent deletion
+
+## Examples
+
+### Example 1: Simple file creation
+
+Task: { action: "Create a new file called test.txt", type: "execute",
+params: { filename: "test.txt" } }
+
+Response:
+```
+message: "Creating the file."
+commands:
+  - description: "Create test.txt"
+    command: "touch test.txt"
+```
+
+### Example 2: Directory listing
+
+Task: { action: "Show files in the current directory", type: "execute" }
+
+Response:
+```
+message: "Listing directory contents."
+commands:
+  - description: "List files with details"
+    command: "ls -la"
+```
+
+### Example 3: Multiple sequential commands
+
+Tasks:
+- { action: "Create project directory", type: "execute",
+    params: { path: "my-project" } }
+- { action: "Initialize git repository", type: "execute" }
+- { action: "Create README file", type: "execute" }
+
+Response:
+```
+message: "Setting up the project."
+commands:
+  - description: "Create project directory"
+    command: "mkdir -p my-project"
+  - description: "Initialize git repository"
+    command: "git init"
+    workdir: "my-project"
+  - description: "Create README file"
+    command: "echo '# My Project' > README.md"
+    workdir: "my-project"
+```
+
+### Example 4: Install dependencies
+
+Task: { action: "Install dependencies", type: "execute" }
+
+Response:
+```
+message: "Installing dependencies."
+commands:
+  - description: "Install npm packages"
+    command: "npm install"
+    timeout: 120000
+```
+
+### Example 5: Skill-based execution
+
+When executing from a skill like "Process Data", tasks include params.skill:
+
+Tasks:
+- { action: "Load the sales dataset", type: "execute",
+    params: { skill: "Process Data", source: "sales", format: "json" } }
+- { action: "Transform the sales data", type: "execute",
+    params: { skill: "Process Data", source: "sales", format: "json" } }
+- { action: "Export the results to json", type: "execute",
+    params: { skill: "Process Data", source: "sales", format: "json" } }
+
+The "Process Data" skill's Execution section specifies:
+- Line 1: curl -O https://data.example.com/{SOURCE}.csv
+- Line 2: python3 transform.py --input {SOURCE}.csv --output processed.csv
+- Line 3: csvtool col 1-3 processed.csv > output.{FORMAT}
+
+Response (using skill's Execution commands):
+```
+message: "Processing sales data."
+commands:
+  - description: "Load the sales dataset"
+    command: "curl -O https://data.example.com/sales.csv"
+    timeout: 60000
+  - description: "Transform the sales data"
+    command: "python3 transform.py --input sales.csv --output processed.csv"
+    timeout: 120000
+  - description: "Export the results to json"
+    command: "csvtool col 1-3 processed.csv > output.json"
+```
+
+Note: Commands come directly from the skill's Execution section, with {SOURCE}
+replaced by "sales" and {FORMAT} replaced by "json" from task params.
+
+### Example 6: File operations with paths
+
+Task: { action: "Copy config to backup", type: "execute",
+params: { source: "~/.config/app", destination: "~/.config/app.backup" } }
+
+Response:
+```
+message: "Creating backup."
+commands:
+  - description: "Copy config directory"
+    command: "cp -r ~/.config/app ~/.config/app.backup"
+```
+
+### Example 7: Checking system information
+
+Task: { action: "Check disk space", type: "execute" }
+
+Response:
+```
+message: "Checking disk space."
+commands:
+  - description: "Show disk usage"
+    command: "df -h"
+```
+
+## Handling Complex Operations
+
+For complex multi-step operations:
+
+1. **Sequential dependencies**: Mark early commands as critical so failure
+   stops the chain
+2. **Long-running processes**: Set appropriate timeouts (build processes may
+   need 10+ minutes)
+3. **Working directories**: Use workdir to ensure commands run in the right
+   location
+4. **Error handling**: For non-critical cleanup steps, set critical: false
+
+## Common Mistakes to Avoid
+
+❌ Generating commands that don't match the task description
+❌ Using platform-specific commands without consideration
+❌ Forgetting to quote paths with spaces
+❌ Setting unrealistic timeouts for long operations
+❌ Running destructive commands without safeguards
+❌ Ignoring task parameters when generating commands
+❌ Inventing commands instead of using skill's Execution section
+❌ Ignoring params.skill and making up your own commands
+❌ Not substituting parameter placeholders in skill commands
+
+✅ Match commands precisely to task descriptions
+✅ Use task params to fill in specific values
+✅ Quote all file paths properly
+✅ Set appropriate timeouts for each operation type
+✅ Include safety checks for destructive operations
+✅ Generate portable commands when possible
+✅ Always use skill's Execution section when params.skill is present
+✅ Replace all {PARAM} placeholders with values from task params
+
+## Final Validation
+
+Before returning commands:
+
+1. Verify each command matches its task description
+2. Check that all task params are incorporated
+3. Ensure paths are properly quoted
+4. Confirm timeouts are reasonable for each operation
+5. Validate that critical flags are set appropriately
+6. Review for any safety concerns

package/dist/config/PLAN.md

@@ -127,8 +127,13 @@ executable operations.
    - Create a task definition for each step with:
      - action: clear, professional description starting with a capital letter
      - type: category of operation (if the skill specifies it or you can infer it)
-     - params: any specific parameters mentioned in the step
+     - params: MUST include:
+       - skill: the skill name (REQUIRED for all skill-based tasks)
+       - All parameter values used in the step (e.g., target, environment, etc.)
+       - Any other specific parameters mentioned in the step
    - NEVER replace the skill's detailed steps with a generic restatement
+   - The params.skill field is CRITICAL for execution to use the skill's
+     Execution section
 
 6. **Handle additional requirements beyond the skill:**
    - If the user's query includes additional requirements beyond the skill,
@@ -138,13 +143,19 @@ executable operations.
    - NEVER create generic execute tasks for unmatched requirements
 
 Example 1 - Skill with parameter, variant specified:
+- Skill name: "Process Data"
 - Skill has {TARGET} parameter with variants: Alpha, Beta, Gamma
 - Skill steps: "- Navigate to the {TARGET} root directory. - Execute the
   {TARGET} generation script. - Run the {TARGET} processing pipeline"
 - User: "process Alpha"
-- Correct: Three tasks with actions following the skill's steps, with
-  {TARGET} replaced by "Alpha"
-- WRONG: One task with action "Process Alpha"
+- Correct: Three tasks with params including skill name:
+  - { action: "Navigate to the Alpha root directory", type: "execute",
+      params: { skill: "Process Data", target: "Alpha" } }
+  - { action: "Execute the Alpha generation script", type: "execute",
+      params: { skill: "Process Data", target: "Alpha" } }
+  - { action: "Run the Alpha processing pipeline", type: "execute",
+      params: { skill: "Process Data", target: "Alpha" } }
+- WRONG: Tasks without params.skill or single task "Process Alpha"
 
 Example 2 - Skill with parameter, variant NOT specified:
 - Same skill as Example 1
@@ -658,8 +669,10 @@ Examples showing proper use of skills and disambiguation:
   Delta"] }. NOTE: If variants have descriptions, format as "Process Alpha, the
   legacy version" NOT "Process Alpha (the legacy version)"
 - "process Alpha" with same process skill → Three tasks extracted from skill
-  steps: "Navigate to the Alpha target's root directory", "Execute the Alpha
-  target generation script", "Run the Alpha processing pipeline"
+  steps, each with params: { skill: "Process Data", target: "Alpha" }:
+  - "Navigate to the Alpha target's root directory"
+  - "Execute the Alpha target generation script"
+  - "Run the Alpha processing pipeline"
 - "process all" with same process skill → Twelve tasks (3 steps × 4 targets)
 - "deploy" with deploy skill (staging, production, canary) → One task: type
   "define", action "Clarify which environment to deploy to:", params

package/dist/handlers/answer.js

@@ -2,27 +2,20 @@ import { ComponentName } from '../types/types.js';
 import { createAnswerDisplayDefinition } from '../services/components.js';
 import { createErrorHandler, withQueueHandler } from '../services/queue.js';
 /**
- * Creates answer error handler
+ * Creates all answer handlers
  */
-export function createAnswerErrorHandler(addToTimeline) {
-    return (error) => createErrorHandler(ComponentName.Answer, addToTimeline)(error);
-}
-/**
- * Creates answer completion handler
- */
-export function createAnswerCompleteHandler(addToTimeline) {
-    return (answer) => withQueueHandler(ComponentName.Answer, () => {
-        // Don't add the Answer component to timeline (it renders null)
-        // Only add the AnswerDisplay component
-        addToTimeline(createAnswerDisplayDefinition(answer));
-        return undefined;
-    }, true, 0);
-}
-/**
- * Creates answer aborted handler
- */
-export function createAnswerAbortedHandler(handleAborted) {
-    return () => {
+export function createAnswerHandlers(ops, handleAborted) {
+    const onError = (error) => {
+        ops.setQueue(createErrorHandler(ComponentName.Answer, ops.addToTimeline)(error));
+    };
+    const onComplete = (answer) => {
+        ops.setQueue(withQueueHandler(ComponentName.Answer, () => {
+            ops.addToTimeline(createAnswerDisplayDefinition(answer));
+            return undefined;
+        }, true, 0));
+    };
+    const onAborted = () => {
         handleAborted('Answer');
     };
+    return { onError, onComplete, onAborted };
 }

package/dist/handlers/command.js

@@ -2,37 +2,33 @@ import { ComponentName, TaskType } from '../types/types.js';
 import { createConfirmDefinition, createPlanDefinition, markAsDone, } from '../services/components.js';
 import { createErrorHandler, withQueueHandler } from '../services/queue.js';
 /**
- * Creates command error handler
+ * Creates all command handlers
  */
-export function createCommandErrorHandler(addToTimeline) {
-    return (error) => createErrorHandler(ComponentName.Command, addToTimeline)(error);
-}
-/**
- * Creates command completion handler
- */
-export function createCommandCompleteHandler(addToTimeline, createPlanAbortHandler, handlePlanSelectionConfirmed, handleExecutionConfirmed, handleExecutionCancelled) {
-    return (message, tasks) => withQueueHandler(ComponentName.Command, (first) => {
-        // Check if tasks contain a Define task that requires user interaction
-        const hasDefineTask = tasks.some((task) => task.type === TaskType.Define);
-        const planDefinition = createPlanDefinition(message, tasks, createPlanAbortHandler(tasks), hasDefineTask ? handlePlanSelectionConfirmed : undefined);
-        if (hasDefineTask) {
-            // Don't exit - keep the plan in the queue for interaction
-            addToTimeline(markAsDone(first));
-            return [planDefinition];
-        }
-        else {
-            // No define task - show plan and confirmation
-            const confirmDefinition = createConfirmDefinition(handleExecutionConfirmed, handleExecutionCancelled);
-            addToTimeline(markAsDone(first), planDefinition);
-            return [confirmDefinition];
-        }
-    }, false, 0);
-}
-/**
- * Creates command aborted handler
- */
-export function createCommandAbortedHandler(handleAborted) {
-    return () => {
+export function createCommandHandlers(ops, handleAborted, planHandlers, executionHandlers) {
+    const onError = (error) => {
+        ops.setQueue(createErrorHandler(ComponentName.Command, ops.addToTimeline)(error));
+    };
+    const onComplete = (message, tasks) => {
+        ops.setQueue(withQueueHandler(ComponentName.Command, (first) => {
+            const hasDefineTask = tasks.some((task) => task.type === TaskType.Define);
+            const planDefinition = createPlanDefinition(message, tasks, planHandlers.createAbortHandler(tasks), hasDefineTask ? planHandlers.onSelectionConfirmed : undefined);
+            if (hasDefineTask) {
+                ops.addToTimeline(markAsDone(first));
+                return [planDefinition];
+            }
+            else {
+                const confirmDefinition = createConfirmDefinition(() => {
+                    executionHandlers.onConfirmed(tasks);
+                }, () => {
+                    executionHandlers.onCancelled(tasks);
+                });
+                ops.addToTimeline(markAsDone(first), planDefinition);
+                return [confirmDefinition];
+            }
+        }, false, 0));
+    };
+    const onAborted = () => {
         handleAborted('Request');
     };
+    return { onError, onComplete, onAborted };
 }

package/dist/handlers/config.js

@@ -6,36 +6,30 @@ import { FeedbackMessages } from '../services/messages.js';
 import { exitApp } from '../services/process.js';
 import { withQueueHandler } from '../services/queue.js';
 /**
- * Creates config finished handler
+ * Creates all config handlers
  */
-export function createConfigFinishedHandler(addToTimeline, command, handleCommandError, handleCommandComplete, handleCommandAborted, setService) {
-    return (config) => {
+export function createConfigHandlers(ops, handleAborted, command, commandHandlers, setService) {
+    const onFinished = (config) => {
         const anthropicConfig = config;
         saveAnthropicConfig(anthropicConfig);
         const newService = createAnthropicService(anthropicConfig);
         setService(newService);
-        return withQueueHandler(ComponentName.Config, (first, rest) => {
-            addToTimeline(markAsDone(first), createFeedback(FeedbackType.Succeeded, FeedbackMessages.ConfigurationComplete));
-            // Add command to queue if we have one
+        ops.setQueue(withQueueHandler(ComponentName.Config, (first, rest) => {
+            ops.addToTimeline(markAsDone(first), createFeedback(FeedbackType.Succeeded, FeedbackMessages.ConfigurationComplete));
             if (command) {
                 return [
                     ...rest,
-                    createCommandDefinition(command, newService, handleCommandError, handleCommandComplete, handleCommandAborted),
+                    createCommandDefinition(command, newService, commandHandlers.onError, commandHandlers.onComplete, commandHandlers.onAborted),
                 ];
             }
-            // No command - exit after showing completion message
             exitApp(0);
             return rest;
-        }, false, 0);
+        }, false, 0));
     };
-}
-/**
- * Creates config aborted handler
- */
-export function createConfigAbortedHandler(handleAborted) {
-    return () => {
+    const onAborted = () => {
         handleAborted('Configuration');
     };
+    return { onFinished, onAborted };
 }
 /**
  * Creates config execution finished handler for CONFIG skill
@@ -43,8 +37,6 @@ export function createConfigAbortedHandler(handleAborted) {
  */
 export function createConfigExecutionFinishedHandler(addToTimeline, keys) {
     return (config) => {
-        // Map short keys back to full keys and save
-        // Group by section (e.g., "anthropic", "settings")
         const sections = {};
         for (const fullKey of keys) {
             const parts = fullKey.split('.');
@@ -55,7 +47,6 @@ export function createConfigExecutionFinishedHandler(addToTimeline, keys) {
                 sections[section][shortKey] = config[shortKey];
             }
         }
-        // Save each section
         for (const [section, sectionConfig] of Object.entries(sections)) {
             saveConfig(section, sectionConfig);
         }

package/dist/handlers/execute.js

@@ -0,0 +1,38 @@
+import { ComponentName, FeedbackType } from '../types/types.js';
+import { createFeedback, createMessage, markAsDone, } from '../services/components.js';
+import { formatDuration } from '../services/messages.js';
+import { exitApp } from '../services/process.js';
+import { ExecutionResult } from '../services/shell.js';
+import { withQueueHandler } from '../services/queue.js';
+/**
+ * Creates all execute handlers
+ */
+export function createExecuteHandlers(ops, handleAborted) {
+    const onError = (error) => {
+        ops.setQueue(withQueueHandler(ComponentName.Execute, (first) => {
+            ops.addToTimeline(markAsDone(first), createFeedback(FeedbackType.Failed, error));
+            exitApp(1);
+            return [];
+        }));
+    };
+    const onComplete = (outputs, totalElapsed) => {
+        ops.setQueue(withQueueHandler(ComponentName.Execute, (first) => {
+            const failed = outputs.find((out) => out.result !== ExecutionResult.Success);
+            if (failed) {
+                const errorMessage = failed.error
+                    ? `${failed.description}: ${failed.error}`
+                    : `${failed.description} failed`;
+                ops.addToTimeline(markAsDone(first), createFeedback(FeedbackType.Failed, errorMessage));
+                exitApp(1);
+                return [];
+            }
+            ops.addToTimeline(markAsDone(first), createMessage(`Execution completed in ${formatDuration(totalElapsed)}.`));
+            exitApp(0);
+            return [];
+        }));
+    };
+    const onAborted = () => {
+        handleAborted('Execution');
+    };
+    return { onError, onComplete, onAborted };
+}