prompt-language-shell 0.5.0 → 0.6.0

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/ANSWER.md

@@ -42,6 +42,8 @@ Provide a direct, helpful answer following these strict formatting rules:
 - Break long sentences naturally at phrase boundaries
 - If the answer requires more than 4 lines, prioritize the most essential
   information
+- **Do NOT use citation tags** like `<cite>` or any HTML/XML markup
+- Provide direct answers in plain text only
 
 ## Examples
 
@@ -112,8 +114,10 @@ They enable cleaner, more reusable component logic.
 ❌ Including unnecessary details
 ❌ Using overly technical jargon without explanation
 ❌ Repeating the question in the answer
+❌ Using citation tags like `<cite>` or any HTML/XML markup
 
 ✅ Direct, concise answers
 ✅ Proper line breaks at natural phrase boundaries
 ✅ Essential information only
 ✅ Clear, accessible language
+✅ Plain text only - no markup tags

package/dist/config/INTROSPECT.md

@@ -133,9 +133,10 @@ 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 (Validate, Plan,
-Report). Each task uses type "introspect" with an action describing the
-capability.
+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
 

package/dist/config/PLAN.md

@@ -280,6 +280,29 @@ Examples that should be aborted as offensive:
 - Requests to create malware or exploit vulnerabilities
 - Requests with offensive, discriminatory, or abusive language
 
+**CRITICAL: Distinguishing Questions from Actions**
+
+User requests fall into two categories:
+
+1. **Information requests (questions)** - Must use question keywords:
+   - "explain", "answer", "describe", "tell me", "say", "what is", "what are",
+     "how does", "how do", "find", "search", "lookup"
+   - Example: "pls explain TypeScript" → answer type
+   - Example: "pls what is the weather" → answer type
+
+2. **Action requests (commands)** - Must match available skills:
+   - Verbs like "test", "deploy", "process", "backup", "sync"
+   - If verb matches a skill → use that skill
+   - If verb does NOT match any skill → use "ignore" type
+   - Example: "pls test" with no test skill → ignore type
+   - Example: "pls reverberate" with no reverberate skill → ignore type
+   - Example: "pls shut down" with no shutdown skill → ignore type
+
+**Critical rule:** Requests using action verbs that don't match question
+keywords AND don't match any available skills should ALWAYS be classified
+as "ignore" type. Do NOT try to infer or create generic execute tasks for
+unrecognized verbs.
+
 **For requests with clear intent:**
 
 1. **Introspection requests** - Use "introspect" type when request asks about

package/dist/config/VALIDATE.md

@@ -29,12 +29,12 @@ For each CONFIG task, create a natural language description that:
 
 ## Description Format
 
-**Format:** "Brief description" (NO {config.path} at the end!)
+**Format:** "Brief description" (DO NOT include {config.path}!)
 
 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
+- NEVER include the config path in curly brackets like {config.path}
 
 ## Examples
 
@@ -50,7 +50,7 @@ The description should:
 message: ""
 tasks: [
   {
-    action: "Path to Alpha repository {project.alpha.repo}",
+    action: "Path to Alpha repository",
     type: "config",
     params: { key: "project.alpha.repo" }
   }
@@ -69,7 +69,7 @@ tasks: [
 message: ""
 tasks: [
   {
-    action: "Staging environment URL {env.staging.url}",
+    action: "Staging environment URL",
     type: "config",
     params: { key: "env.staging.url" }
   }
@@ -88,7 +88,7 @@ tasks: [
 message: ""
 tasks: [
   {
-    action: "Path to Beta workspace {workspace.beta.path}",
+    action: "Path to Beta workspace",
     type: "config",
     params: { key: "workspace.beta.path" }
   }
@@ -98,10 +98,10 @@ tasks: [
 ## 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
+2. **Be specific**: Don't just say "Repository path" - say "Path to Alpha repository"
+3. **Add helpful details**: Include information from the description when relevant
+4. **Keep it concise**: One brief phrase that clearly explains what's needed
+5. **Never include the path**: Do not append `{config.path}` - it's shown separately in debug mode
 
 ## Common Config Types
 
@@ -122,7 +122,7 @@ Return a message field (can be empty string) and an array of CONFIG tasks:
 message: ""
 tasks: [
   {
-    action: "Natural description {config.path}",
+    action: "Natural description without config path",
     type: "config",
     params: { key: "config.path" }
   },
@@ -136,4 +136,5 @@ tasks: [
 - 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
+- Keep descriptions to one brief phrase (3-6 words)
+- NEVER include the config path in the action/description - it's shown separately

package/dist/services/components.js

@@ -1,11 +1,10 @@
 import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
 import { ComponentName } from '../types/types.js';
-import { getConfigSchema, loadConfig, } from './configuration.js';
+import { parse as parseYaml } from 'yaml';
+import { getConfigPath, getConfigSchema, loadConfig, } from './configuration.js';
 import { getConfirmationMessage } from './messages.js';
 import { StepType } from '../ui/Config.js';
-export function markAsDone(component) {
-    return { ...component, state: { ...component.state, done: true } };
-}
 export function createWelcomeDefinition(app) {
     return {
         id: randomUUID(),
@@ -58,27 +57,43 @@ function getValidator(definition) {
 export function createConfigStepsFromSchema(keys) {
     const schema = getConfigSchema();
     let currentConfig = null;
+    let rawConfig = null;
+    // Load validated config (may fail if config has validation errors)
     try {
         currentConfig = loadConfig();
     }
     catch {
-        // Config doesn't exist yet, use defaults
+        // Config doesn't exist or has validation errors, use defaults
+    }
+    // Load raw config separately (for discovered keys not in schema)
+    try {
+        const configFile = getConfigPath();
+        if (existsSync(configFile)) {
+            const content = readFileSync(configFile, 'utf-8');
+            rawConfig = parseYaml(content);
+        }
+    }
+    catch {
+        // Config file doesn't exist or can't be parsed
     }
     return keys.map((key) => {
         // Check if key is in schema (built-in config)
         if (!(key in schema)) {
-            // Key is not in schema - it's from a skill
-            // Create a simple text step with placeholder description
+            // Key is not in schema - it's from a skill or discovered config
+            // Create a simple text step with the full path as description
             const keyParts = key.split('.');
             const shortKey = keyParts[keyParts.length - 1];
-            const description = keyParts
-                .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-                .join(' ');
+            // Load current value if it exists (use rawConfig since discovered keys aren't in validated config)
+            const currentValue = getConfigValue(rawConfig, key);
+            const value = currentValue !== undefined && typeof currentValue === 'string'
+                ? currentValue
+                : null;
             return {
-                description: `${description} {${key}}`,
+                description: key,
                 key: shortKey,
+                path: key,
                 type: StepType.Text,
-                value: null,
+                value,
                 validate: () => true, // Accept any string for now
             };
         }
@@ -98,6 +113,7 @@ export function createConfigStepsFromSchema(keys) {
                 return {
                     description: definition.description,
                     key: shortKey,
+                    path: key,
                     type: StepType.Text,
                     value,
                     validate: getValidator(definition),
@@ -112,6 +128,7 @@ export function createConfigStepsFromSchema(keys) {
                 return {
                     description: definition.description,
                     key: shortKey,
+                    path: key,
                     type: StepType.Text,
                     value,
                     validate: getValidator(definition),
@@ -127,6 +144,7 @@ export function createConfigStepsFromSchema(keys) {
                 return {
                     description: definition.description,
                     key: shortKey,
+                    path: key,
                     type: StepType.Selection,
                     options: definition.values.map((value) => ({
                         label: value,
@@ -143,6 +161,7 @@ export function createConfigStepsFromSchema(keys) {
                 return {
                     description: definition.description,
                     key: shortKey,
+                    path: key,
                     type: StepType.Selection,
                     options: [
                         { label: 'Yes', value: 'true' },
@@ -159,7 +178,7 @@ export function createConfigDefinition(onFinished, onAborted) {
     return {
         id: randomUUID(),
         name: ComponentName.Config,
-        state: { done: false },
+        state: {},
         props: {
             steps: createConfigSteps(),
             onFinished,
@@ -174,7 +193,7 @@ export function createConfigDefinitionWithKeys(keys, onFinished, onAborted) {
     return {
         id: randomUUID(),
         name: ComponentName.Config,
-        state: { done: false },
+        state: {},
         props: {
             steps: createConfigStepsFromSchema(keys),
             onFinished,
@@ -182,29 +201,22 @@ export function createConfigDefinitionWithKeys(keys, onFinished, onAborted) {
         },
     };
 }
-export function createCommandDefinition(command, service, onError, onComplete, onAborted) {
+export function createCommandDefinition(command, service) {
     return {
         id: randomUUID(),
         name: ComponentName.Command,
-        state: {
-            done: false,
-            isLoading: true,
-        },
+        state: {},
         props: {
             command,
             service,
-            onError,
-            onComplete,
-            onAborted,
         },
     };
 }
-export function createPlanDefinition(message, tasks, onAborted, onSelectionConfirmed) {
+export function createPlanDefinition(message, tasks, onSelectionConfirmed) {
     return {
         id: randomUUID(),
         name: ComponentName.Plan,
         state: {
-            done: false,
             highlightedIndex: null,
             currentDefineGroupIndex: 0,
             completedSelections: [],
@@ -213,7 +225,6 @@ export function createPlanDefinition(message, tasks, onAborted, onSelectionConfi
             message,
             tasks,
             onSelectionConfirmed,
-            onAborted,
         },
     };
 }
@@ -240,7 +251,7 @@ export function createRefinement(text, onAborted) {
     return {
         id: randomUUID(),
         name: ComponentName.Refinement,
-        state: { done: false },
+        state: {},
         props: {
             text,
             onAborted,
@@ -251,7 +262,7 @@ export function createConfirmDefinition(onConfirmed, onCancelled) {
     return {
         id: randomUUID(),
         name: ComponentName.Confirm,
-        state: { done: false },
+        state: {},
         props: {
             message: getConfirmationMessage(),
             onConfirmed,
@@ -259,20 +270,14 @@ export function createConfirmDefinition(onConfirmed, onCancelled) {
         },
     };
 }
-export function createIntrospectDefinition(tasks, service, onError, onComplete, onAborted) {
+export function createIntrospectDefinition(tasks, service) {
     return {
         id: randomUUID(),
         name: ComponentName.Introspect,
-        state: {
-            done: false,
-            isLoading: true,
-        },
+        state: {},
         props: {
             tasks,
             service,
-            onError,
-            onComplete,
-            onAborted,
         },
     };
 }
@@ -286,49 +291,37 @@ export function createReportDefinition(message, capabilities) {
         },
     };
 }
-export function createAnswerDefinition(question, service, onError, onComplete, onAborted) {
+export function createAnswerDefinition(question, service) {
     return {
         id: randomUUID(),
         name: ComponentName.Answer,
-        state: {
-            done: false,
-            isLoading: true,
-        },
+        state: {},
         props: {
             question,
             service,
-            onError,
-            onComplete,
-            onAborted,
-        },
-    };
-}
-export function createAnswerDisplayDefinition(answer) {
-    return {
-        id: randomUUID(),
-        name: ComponentName.AnswerDisplay,
-        props: {
-            answer,
         },
     };
 }
 export function isStateless(component) {
     return !('state' in component);
 }
-export function createExecuteDefinition(tasks, service, onError, onComplete, onAborted) {
+/**
+ * Mark a component as done. Returns the component to be added to timeline.
+ * Components use handlers.updateState to save their state before completion,
+ * so this function simply returns the component as-is.
+ */
+export function markAsDone(component) {
+    // State already updated via handlers.updateState
+    return component;
+}
+export function createExecuteDefinition(tasks, service) {
     return {
         id: randomUUID(),
         name: ComponentName.Execute,
-        state: {
-            done: false,
-            isLoading: true,
-        },
+        state: {},
         props: {
             tasks,
             service,
-            onError,
-            onComplete,
-            onAborted,
         },
     };
 }
@@ -336,10 +329,7 @@ export function createValidateDefinition(missingConfig, userRequest, service, on
     return {
         id: randomUUID(),
         name: ComponentName.Validate,
-        state: {
-            done: false,
-            isLoading: true,
-        },
+        state: {},
         props: {
             missingConfig,
             userRequest,

package/dist/services/configuration.js

@@ -123,6 +123,7 @@ export function saveConfig(section, config) {
 }
 export function saveAnthropicConfig(config) {
     saveConfig('anthropic', config);
+    return loadConfig();
 }
 export function saveDebugSetting(debug) {
     saveConfig('settings', { debug });
@@ -200,6 +201,67 @@ export function getConfigSchema() {
         // Future: ...loadSkillSchemas()
     };
 }
+/**
+ * Get missing required configuration keys
+ * Returns array of keys that are required but not present or invalid in config
+ */
+export function getMissingConfigKeys() {
+    const schema = getConfigSchema();
+    const missing = [];
+    let currentConfig = null;
+    try {
+        currentConfig = loadConfig();
+    }
+    catch {
+        // Config doesn't exist
+    }
+    for (const [key, definition] of Object.entries(schema)) {
+        if (!definition.required) {
+            continue;
+        }
+        // Get current value for this key
+        const parts = key.split('.');
+        let value = currentConfig;
+        for (const part of parts) {
+            if (value && typeof value === 'object' && part in value) {
+                value = value[part];
+            }
+            else {
+                value = undefined;
+                break;
+            }
+        }
+        // Check if value is missing or invalid
+        if (value === undefined || value === null) {
+            missing.push(key);
+            continue;
+        }
+        // Validate based on type
+        let isValid = false;
+        switch (definition.type) {
+            case 'regexp':
+                isValid = typeof value === 'string' && definition.pattern.test(value);
+                break;
+            case 'string':
+                isValid = typeof value === 'string';
+                break;
+            case 'enum':
+                isValid =
+                    typeof value === 'string' && definition.values.includes(value);
+                break;
+            case 'number':
+                isValid = typeof value === 'number';
+                break;
+            case 'boolean':
+                isValid = typeof value === 'boolean';
+                break;
+        }
+        if (!isValid) {
+            missing.push(key);
+        }
+    }
+    return missing;
+}
 /**
  * Get available config structure for CONFIG tool
  * Returns keys with descriptions only (no values for privacy)
@@ -246,3 +308,25 @@ export function getAvailableConfigStructure() {
     }
     return structure;
 }
+/**
+ * Unflatten dotted keys into nested structure
+ * Example: { "product.alpha.path": "value" } -> { product: { alpha: { path: "value" } } }
+ */
+export function unflattenConfig(dotted) {
+    const result = {};
+    for (const [dottedKey, value] of Object.entries(dotted)) {
+        const parts = dottedKey.split('.');
+        const section = parts[0];
+        // Initialize section if needed
+        result[section] = result[section] ?? {};
+        // Build nested structure for this section
+        let current = result[section];
+        for (let i = 1; i < parts.length - 1; i++) {
+            current[parts[i]] = current[parts[i]] ?? {};
+            current = current[parts[i]];
+        }
+        // Set final value
+        current[parts[parts.length - 1]] = value;
+    }
+    return result;
+}