prompt-language-shell 0.4.9 → 0.5.2

package/README.md

@@ -2,6 +2,9 @@
 
 Your personal command-line concierge. Ask politely, and it gets things done.
 
+> **Note:** This project is in early preview. Features and APIs may change as
+> development continues.
+
 ## Installation
 
 ```bash
@@ -14,30 +17,74 @@ On first run, `pls` walks you through a quick setup. Your settings will be saved
 
 ## Usage
 
-Type `pls` followed by your request in natural language:
+Type `pls` followed by your request in natural language.
+
+To see what `pls` can
+do, start by listing available capabilities:
 
-```bash
-pls change dir to ~
 ```
+$ pls list skills
+
+Here's what I can help with:
+
+  - Introspect - list available capabilities and skills
+  - Config - manage and configure system settings
+  - Answer - respond to questions and provide information
+  - Execute - run shell commands and process operations
+  ```
 
-Your command will be interpreted and organized into a list of tasks:
+Skills are custom workflows you can define to teach `pls` about your specific
+projects and commands. Once defined, you can use them naturally:
 
 ```
-> pls change dir to ~
-  - Change directory to the home folder
+$ pls build project
+
+Here's my plan.
+
+  - Navigate to project directory
+  - Compile source code
 ```
 
 You can provide multiple requests at once:
 
 ```
-> pls install deps, run tests and deploy
+$ pls install deps, run tests and build
+
+Here's what I'll do.
+
   - Install dependencies
   - Run tests
-  - Deploy to server
+  - Build the project
+```
+
+When `pls` needs clarification, it will present options to choose from:
+
+```
+$ pls deploy
+
+Let me clarify.
+
+  → Choose which environment to deploy to:
+    - Deploy to staging
+    - Deploy to production
 ```
 
 Run `pls` without arguments to see the welcome screen.
 
+## How It Works
+
+When you make a request, `pls` interprets your intent and creates a structured
+plan breaking down the work into individual tasks. You'll see this plan
+displayed in your terminal before anything executes.
+
+After reviewing the plan, you can confirm to proceed or cancel if something
+doesn't look right. Once confirmed, `pls` executes each task sequentially and
+shows real-time progress and results.
+
+If you've defined custom skills, `pls` uses them to understand your
+project-specific workflows and translate high-level requests into the exact
+commands your environment requires.
+
 ## Configuration
 
 Your configuration is stored in `~/.plsrc` as a YAML file. Supported settings:
@@ -47,9 +94,66 @@ Your configuration is stored in `~/.plsrc` as a YAML file. Supported settings:
 
 ## Skills
 
-You can extend `pls` with custom workflows by creating markdown files in `~/.pls/skills/`. Skills define domain-specific operations, parameters, and steps that guide both planning and execution of tasks.
+Skills let you teach `pls` about your project-specific workflows. Create
+markdown files in `~/.pls/skills/` to define custom operations that `pls` can
+understand and execute.
+
+### Structure
+
+Each skill file uses a simple markdown format:
+
+- **Name**: What you call this workflow (e.g., "Build Project")
+- **Description**: What it does and any variants or options
+- **Steps**: What needs to happen, in order
+- **Execution** (optional): The actual shell commands to run
+
+### Example
+
+Here's a skill that builds different project variants:
+
+```markdown
+### Name
+Build Project
+
+### Description
+Build a project in different configurations:
+- dev (debug build with source maps)
+- prod (optimized build)
+- test (with test coverage)
+
+### Steps
+- Navigate to the project directory
+- Install dependencies if needed
+- Run the {ENV} build script
+- Generate build artifacts
 
-Your skills are referenced when planning requests, enabling `pls` to understand specific workflows, create and execute structured plans tailored to your environment.
+### Execution
+- cd ~/projects/next
+- npm install
+- npm run build:{ENV}
+- cp -r dist/ builds/{ENV}/
+```
+
+With this skill defined, you can use natural language like:
+```
+$ pls build project for production
+$ pls build dev environment
+$ pls build with testing enabled
+```
+The `{ENV}` placeholder gets replaced with the variant you specify.
+Instead of remembering the exact commands and paths for each environment, just
+tell `pls` what you want in plain English. The Execution section ensures the right commands run every time.
+
+### Keep It Short
+
+Skills also work with concise commands. Once you've taught `pls` about your
+workflow, you can use minimal phrasing:
+
+```
+$ pls build prod
+$ pls build dev
+$ pls build test
+```
 
 ## Development
 

package/dist/config/INTROSPECT.md

@@ -75,12 +75,13 @@ These MUST appear FIRST, in this EXACT sequence:
 3. **Answer** ← ALWAYS THIRD
 4. **Execute** ← ALWAYS FOURTH
 
-### Position 5-6: Indirect Workflow Capabilities
+### Position 5-7: Indirect Workflow Capabilities
 
 These MUST appear AFTER Execute and BEFORE user skills:
 
 5. **Plan** ← NEVER FIRST, ALWAYS position 5 (after Execute)
-6. **Report** ← NEVER FIRST, ALWAYS position 6 (after Plan)
+6. **Validate** ← ALWAYS position 6 (after Plan)
+7. **Report** ← NEVER FIRST, ALWAYS position 7 (after Validate)
 
 ### 3. User-Defined Skills
 
@@ -132,7 +133,9 @@ Examples:
 
 When user asks "list your skills", create an introductory message like "here
 are my capabilities:" followed by tasks for built-in capabilities (Introspect,
-Config, Answer, Execute), then indirect workflow capabilities (Plan, Report).
+Config, Answer, Execute), then indirect workflow capabilities (Plan, Validate,
+Report).
+
 Each task uses type "introspect" with an action describing the capability.
 
 ### Example 2: Filtered Skills
@@ -146,8 +149,9 @@ with its description.
 
 When user asks "what can you do" and user-defined skills like "process data"
 and "backup files" exist, create an introductory message like "i can help with
-these operations:" followed by all built-in capabilities plus the user-defined
-skills. Each capability and skill becomes a task with type "introspect".
+these operations:" followed by all built-in capabilities (Introspect, Config,
+Answer, Execute, Validate, Plan, Report) plus the user-defined skills. Each
+capability and skill becomes a task with type "introspect".
 
 ## Final Validation
 

package/dist/config/PLAN.md

@@ -113,6 +113,26 @@ executable operations.
      Extract the individual steps from the skill's "Execution" or "Steps"
      section (prefer Execution if available)
    - Replace ALL parameter placeholders with the specified value
+   - **CRITICAL - Variant Placeholder Resolution**: If the execution commands
+     contain variant placeholders (any uppercase word in a placeholder path,
+     e.g., {section.VARIANT.property}, {project.TARGET.path}, {env.TYPE.name}),
+     you MUST:
+     1. Identify the variant name from the user's request (e.g., "alpha", "beta")
+     2. Normalize the variant to lowercase (e.g., "alpha", "beta")
+     3. Replace the uppercase placeholder component with the actual variant name
+        in ALL task actions
+     4. Examples:
+        - User says "process alpha target" → variant is "alpha"
+          - Execution line: `cd {project.VARIANT.path}`
+          - Task action MUST be: `cd {project.alpha.path}` (NOT `cd {project.VARIANT.path}`)
+        - User says "deploy to staging environment" → variant is "staging"
+          - Execution line: `setup {env.TYPE.config}`
+          - Task action MUST be: `setup {env.staging.config}` (NOT `setup {env.TYPE.config}`)
+     5. This applies to ALL placeholders in task actions, whether from direct
+        execution lines or from referenced skills (e.g., [Navigate To Target])
+     6. The uppercase word can be ANY name (VARIANT, TARGET, TYPE, PRODUCT, etc.) -
+        all uppercase path components indicate variant placeholders that must
+        be resolved
 
 4. **Handle partial execution:**
    - Keywords indicating partial execution: "only", "just", specific verbs
@@ -129,11 +149,16 @@ executable operations.
      - type: category of operation (if the skill specifies it or you can infer it)
      - 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.)
+       - variant: the resolved variant value (REQUIRED if skill has variant placeholders)
+       - All other 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
+   - The params.variant field is CRITICAL for config validation to resolve
+     variant placeholders in the skill's Execution section
+   - Example: If user selects "Deploy to production" and skill has {env.VARIANT.url},
+     params must include variant: "production" so validator can resolve to {env.production.url}
 
 6. **Handle additional requirements beyond the skill:**
    - If the user's query includes additional requirements beyond the skill,
@@ -157,6 +182,19 @@ Example 1 - Skill with parameter, variant specified:
       params: { skill: "Process Data", target: "Alpha" } }
 - WRONG: Tasks without params.skill or single task "Process Alpha"
 
+Example 1b - Skill with variant placeholder in config:
+- Skill name: "Navigate To Target"
+- Skill config defines: target.alpha.path, target.beta.path, target.gamma.path
+- Skill execution: "cd {target.VARIANT.path}"
+- User: "navigate to beta"
+- Variant matched: "beta"
+- Correct task: { action: "Navigate to Beta target directory", type: "execute",
+    params: { skill: "Navigate To Target", variant: "beta" } }
+- WRONG: params without variant field
+- WRONG: task action "cd {target.VARIANT.path}" (uppercase VARIANT not resolved!)
+- Note: The config validator will use params.variant="beta" to resolve
+  {target.VARIANT.path} → {target.beta.path}, then check if it exists in ~/.plsrc
+
 Example 2 - Skill with parameter, variant NOT specified:
 - Same skill as Example 1
 - User: "process"

package/dist/config/VALIDATE.md

@@ -0,0 +1,139 @@
+## Overview
+
+You are the validation component of "pls" (please), responsible for validating skill requirements and generating natural language descriptions for missing configuration values.
+
+Your role is to help users understand what configuration values are needed and why, using context from skill descriptions to create clear, helpful prompts.
+
+## Input
+
+You will receive information about missing configuration values:
+- Config path (e.g., "project.alpha.repo")
+- Skill name that requires this config
+- Variant (if applicable)
+- Config type (string, boolean, number)
+
+## Your Task
+
+Generate a response with two required fields:
+
+1. **message**: An empty string `""`
+2. **tasks**: An array of CONFIG tasks, one for each missing config value
+
+For each CONFIG task, create a natural language description that:
+
+1. **Explains what the value is for** using context from the skill's description
+2. **Keeps it SHORT** - one brief phrase (3-6 words max)
+3. **Does NOT include the config path** - the path will be shown separately in debug mode
+
+**CRITICAL**: You MUST include both the `message` field (set to empty string) and the `tasks` array in your response.
+
+## Description Format
+
+**Format:** "Brief description" (NO {config.path} at the end!)
+
+The description should:
+- Start with what the config value represents (e.g., "Path to...", "URL for...", "Name of...")
+- Be SHORT and direct - no extra details or variant explanations
+- NOT include the config path in curly brackets - that's added automatically
+
+## Examples
+
+### Example 1: Repository Path
+
+**Input:**
+- Config path: `project.alpha.repo`
+- Skill: "Navigate To Project"
+- Variant: "alpha"
+
+**Correct output:**
+```
+message: ""
+tasks: [
+  {
+    action: "Path to Alpha repository {project.alpha.repo}",
+    type: "config",
+    params: { key: "project.alpha.repo" }
+  }
+]
+```
+
+### Example 2: Environment URL
+
+**Input:**
+- Config path: `env.staging.url`
+- Skill: "Deploy Service"
+- Variant: "staging"
+
+**Correct output:**
+```
+message: ""
+tasks: [
+  {
+    action: "Staging environment URL {env.staging.url}",
+    type: "config",
+    params: { key: "env.staging.url" }
+  }
+]
+```
+
+### Example 3: Project Directory
+
+**Input:**
+- Config path: `workspace.beta.path`
+- Skill: "Process Workspace"
+- Variant: "beta"
+
+**Correct output:**
+```
+message: ""
+tasks: [
+  {
+    action: "Path to Beta workspace {workspace.beta.path}",
+    type: "config",
+    params: { key: "workspace.beta.path" }
+  }
+]
+```
+
+## Guidelines
+
+1. **Use skill context**: Read the skill's Description section to understand what the variant represents
+2. **Be specific**: Don't just say "Repository path" - say "Alpha project repository path"
+3. **Add helpful details**: Include information from the description (e.g., "legacy implementation")
+4. **Keep it concise**: One sentence that clearly explains what's needed
+5. **Always include the path**: End with `{config.path}` for technical reference
+
+## Common Config Types
+
+- **repo / repository**: "Path to [name] repository"
+- **path / dir / directory**: "Path to [name] directory"
+- **url**: "[Name] URL"
+- **host**: "[Name] host address"
+- **port**: "[Name] port number"
+- **name**: "Name of [context]"
+- **key / token / secret**: "[Name] authentication key/token/secret"
+- **enabled**: "Enable/disable [feature]"
+
+## Response Format
+
+Return a message field (can be empty string) and an array of CONFIG tasks:
+
+```
+message: ""
+tasks: [
+  {
+    action: "Natural description {config.path}",
+    type: "config",
+    params: { key: "config.path" }
+  },
+  // ... more tasks
+]
+```
+
+## Important Notes
+
+- All tasks must have type "config"
+- All tasks must include params.key with the config path
+- Descriptions should be helpful and contextual, not just technical
+- Use information from Available Skills section to provide context
+- Keep descriptions to one concise sentence

package/dist/handlers/config.js

@@ -1,6 +1,6 @@
 import { ComponentName, FeedbackType } from '../types/types.js';
 import { createAnthropicService, } from '../services/anthropic.js';
-import { createCommandDefinition, createFeedback, markAsDone, } from '../services/components.js';
+import { createCommandDefinition, createExecuteDefinition, createFeedback, markAsDone, } from '../services/components.js';
 import { saveAnthropicConfig, saveConfig } from '../services/configuration.js';
 import { FeedbackMessages } from '../services/messages.js';
 import { exitApp } from '../services/process.js';
@@ -33,18 +33,27 @@ export function createConfigHandlers(ops, handleAborted, command, commandHandler
 }
 /**
  * Creates config execution finished handler for CONFIG skill
- * Saves arbitrary config keys and exits
+ * Saves arbitrary config keys and optionally continues with execution
  */
-export function createConfigExecutionFinishedHandler(addToTimeline, keys) {
+export function createConfigExecutionFinishedHandler(addToTimeline, keys, tasks, service, executeHandlers) {
     return (config) => {
+        // Group by top-level section
         const sections = {};
         for (const fullKey of keys) {
             const parts = fullKey.split('.');
             const shortKey = parts[parts.length - 1];
-            const section = parts.slice(0, -1).join('.');
-            sections[section] = sections[section] ?? {};
+            const topSection = parts[0];
+            // Initialize section if needed
+            sections[topSection] = sections[topSection] ?? {};
             if (shortKey in config) {
-                sections[section][shortKey] = config[shortKey];
+                const value = config[shortKey];
+                // Build nested structure recursively
+                let current = sections[topSection];
+                for (let i = 1; i < parts.length - 1; i++) {
+                    current[parts[i]] = current[parts[i]] ?? {};
+                    current = current[parts[i]];
+                }
+                current[parts[parts.length - 1]] = value;
             }
         }
         for (const [section, sectionConfig] of Object.entries(sections)) {
@@ -52,6 +61,14 @@ export function createConfigExecutionFinishedHandler(addToTimeline, keys) {
         }
         return withQueueHandler(ComponentName.Config, (first, rest) => {
             addToTimeline(markAsDone(first), createFeedback(FeedbackType.Succeeded, FeedbackMessages.ConfigurationComplete));
+            // If tasks are provided, continue with execution
+            if (tasks && service && executeHandlers) {
+                return [
+                    ...rest,
+                    createExecuteDefinition(tasks, service, executeHandlers.onError, executeHandlers.onComplete, executeHandlers.onAborted),
+                ];
+            }
+            // Otherwise, exit (legacy behavior for initial setup)
             exitApp(0);
             return rest;
         }, false, 0);

package/dist/handlers/execute.js

@@ -8,6 +8,7 @@ import { withQueueHandler } from '../services/queue.js';
  * Creates all execute handlers
  */
 export function createExecuteHandlers(ops, handleAborted) {
+    void handleAborted;
     const onError = (error) => {
         ops.setQueue(withQueueHandler(ComponentName.Execute, (first) => {
             ops.addToTimeline(markAsDone(first), createFeedback(FeedbackType.Failed, error));
@@ -31,8 +32,15 @@ export function createExecuteHandlers(ops, handleAborted) {
             return [];
         }));
     };
-    const onAborted = () => {
-        handleAborted('Execution');
+    const onAborted = (elapsedTime) => {
+        ops.setQueue(withQueueHandler(ComponentName.Execute, (first) => {
+            const message = elapsedTime > 0
+                ? `The execution was cancelled after ${formatDuration(elapsedTime)}.`
+                : 'The execution was cancelled.';
+            ops.addToTimeline(markAsDone(first), createFeedback(FeedbackType.Aborted, message));
+            exitApp(0);
+            return [];
+        }));
     };
     return { onError, onComplete, onAborted };
 }

package/dist/handlers/execution.js

@@ -1,9 +1,11 @@
 import { ComponentName, FeedbackType, TaskType } from '../types/types.js';
-import { createAnswerDefinition, createConfigDefinitionWithKeys, createExecuteDefinition, createFeedback, createIntrospectDefinition, markAsDone, } from '../services/components.js';
+import { createAnswerDefinition, createConfigDefinitionWithKeys, createExecuteDefinition, createFeedback, createIntrospectDefinition, createValidateDefinition, markAsDone, } from '../services/components.js';
+import { StepType } from '../ui/Config.js';
 import { getCancellationMessage } from '../services/messages.js';
 import { exitApp } from '../services/process.js';
 import { withQueueHandler } from '../services/queue.js';
 import { createConfigExecutionAbortedHandler, createConfigExecutionFinishedHandler, } from './config.js';
+import { validateExecuteTasks } from '../services/execution-validator.js';
 /**
  * Creates all execution handlers
  */
@@ -49,6 +51,71 @@ export function createExecutionHandlers(ops, taskHandlers) {
                 ];
             }
             else if (allExecute && tasks.length > 0) {
+                // Validate config requirements before execution
+                const missingConfig = validateExecuteTasks(tasks);
+                if (missingConfig.length > 0) {
+                    // Config is missing - call VALIDATE tool to get contextual descriptions
+                    const keys = missingConfig.map((req) => req.path);
+                    const userRequest = tasks.map((t) => t.action).join(', ');
+                    ops.addToTimeline(markAsDone(first));
+                    // Create handlers for Validate completion
+                    const handleValidateComplete = (configWithDescriptions) => {
+                        ops.setQueue(withQueueHandler(ComponentName.Validate, (first) => {
+                            // Create CONFIG component with descriptions from VALIDATE
+                            const handleConfigFinished = (config) => {
+                                ops.setQueue(createConfigExecutionFinishedHandler(ops.addToTimeline, keys, tasks, service, taskHandlers.execute)(config));
+                            };
+                            const handleConfigAborted = () => {
+                                ops.setQueue(createConfigExecutionAbortedHandler(ops.addToTimeline)());
+                            };
+                            // Create config steps from validated descriptions
+                            const steps = configWithDescriptions.map((req) => {
+                                const keyParts = req.path.split('.');
+                                const shortKey = keyParts[keyParts.length - 1];
+                                // Extract description without the {path} suffix
+                                // Format from VALIDATE: "Description {path}"
+                                let description = req.description || req.path;
+                                const pathPattern = /\s*\{[^}]+\}\s*$/;
+                                description = description.replace(pathPattern, '').trim();
+                                const step = {
+                                    description,
+                                    key: shortKey,
+                                    path: req.path,
+                                    type: StepType.Text,
+                                    value: null,
+                                    validate: () => true,
+                                };
+                                return step;
+                            });
+                            // Mark Validate as done and move to timeline
+                            ops.addToTimeline(markAsDone(first));
+                            return [
+                                {
+                                    id: crypto.randomUUID(),
+                                    name: ComponentName.Config,
+                                    state: { done: false },
+                                    props: {
+                                        steps,
+                                        onFinished: handleConfigFinished,
+                                        onAborted: handleConfigAborted,
+                                    },
+                                },
+                            ];
+                        }));
+                    };
+                    const handleValidateError = (error) => {
+                        ops.addToTimeline(createFeedback(FeedbackType.Failed, error));
+                        exitApp(1);
+                    };
+                    const handleValidateAborted = () => {
+                        ops.addToTimeline(createFeedback(FeedbackType.Aborted, 'Configuration validation cancelled'));
+                        exitApp(0);
+                    };
+                    return [
+                        createValidateDefinition(missingConfig, userRequest, service, handleValidateError, handleValidateComplete, handleValidateAborted),
+                    ];
+                }
+                // No missing config - execute directly
                 ops.addToTimeline(markAsDone(first));
                 return [
                     createExecuteDefinition(tasks, service, taskHandlers.execute.onError, taskHandlers.execute.onComplete, taskHandlers.execute.onAborted),

package/dist/services/anthropic.js

@@ -18,7 +18,8 @@ export class AnthropicService {
         // Add skills section for applicable tools
         if (toolName === 'plan' ||
             toolName === 'introspect' ||
-            toolName === 'execute') {
+            toolName === 'execute' ||
+            toolName === 'validate') {
             const skills = loadSkills();
             const skillsSection = formatSkillsForPrompt(skills);
             systemPrompt += skillsSection;
@@ -114,7 +115,7 @@ export class AnthropicService {
             };
         }
         // Handle plan and introspect tool responses
-        if (!input.message || typeof input.message !== 'string') {
+        if (input.message === undefined || typeof input.message !== 'string') {
             throw new Error('Invalid tool response: missing or invalid message field');
         }
         if (!input.tasks || !Array.isArray(input.tasks)) {

package/dist/services/colors.js

@@ -15,8 +15,8 @@ export const Palette = {
     BrightGreen: '#3e9a3e',
     Yellow: '#cccc5c',
     LightYellow: '#d4d47a',
-    Orange: '#cc9c5c',
-    DarkOrange: '#a85c3f',
+    Orange: '#f48c80',
+    DarkOrange: '#ab5e40',
     BurntOrange: '#cc7a5c',
     Red: '#cc5c5c',
     Cyan: '#5c9ccc',

package/dist/services/components.js

@@ -65,8 +65,22 @@ export function createConfigStepsFromSchema(keys) {
         // Config doesn't exist yet, use defaults
     }
     return keys.map((key) => {
+        // Check if key is in schema (built-in config)
         if (!(key in schema)) {
-            throw new Error(`Unknown config key: ${key}`);
+            // Key is not in schema - it's from a skill
+            // Create a simple text step with placeholder description
+            const keyParts = key.split('.');
+            const shortKey = keyParts[keyParts.length - 1];
+            const description = keyParts
+                .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+                .join(' ');
+            return {
+                description: `${description} {${key}}`,
+                key: shortKey,
+                type: StepType.Text,
+                value: null,
+                validate: () => true, // Accept any string for now
+            };
         }
         const definition = schema[key];
         const currentValue = getConfigValue(currentConfig, key);
@@ -318,3 +332,21 @@ export function createExecuteDefinition(tasks, service, onError, onComplete, onA
         },
     };
 }
+export function createValidateDefinition(missingConfig, userRequest, service, onError, onComplete, onAborted) {
+    return {
+        id: randomUUID(),
+        name: ComponentName.Validate,
+        state: {
+            done: false,
+            isLoading: true,
+        },
+        props: {
+            missingConfig,
+            userRequest,
+            service,
+            onError,
+            onComplete,
+            onAborted,
+        },
+    };
+}