prompt-language-shell 0.9.8 → 1.0.2

package/README.md

@@ -2,9 +2,6 @@
 
 Your personal command-line concierge. Ask politely, and it gets things done.
 
-> **Note:** This project is in early preview. Features and APIs will change.
-> See [roadmap](#roadmap).
-
 ## Installation
 
 ```bash
@@ -37,24 +34,23 @@ Skills are custom workflows you can define to teach `pls` about your specific
 projects and commands. Once defined, you can use them naturally:
 
 ```
-$ pls build project
+$ pls convert video.mp4
 
 Here's my plan.
 
-  - Navigate to project directory
-  - Compile source code
+  - Compress video.mp4 with H.264 codec
 ```
 
 You can provide multiple requests at once:
 
 ```
-$ pls install deps, run tests and build
+$ pls backup photos, compress and upload
 
 Here's what I'll do.
 
-  - Install dependencies
-  - Run tests
-  - Build the project
+  - Copy photos to backup folder
+  - Create zip archive
+  - Upload to cloud storage
 ```
 
 When `pls` needs clarification, it will present options to choose from:
@@ -129,6 +125,46 @@ 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.
 
+### Creating Skills
+
+The easiest way to create a new skill is with the guided walkthrough:
+
+```
+$ pls learn
+
+Creating a new skill...
+
+Skill name (e.g., "Deploy Project"):
+> Build Frontend
+
+Description (min 20 characters):
+> Build the frontend application using npm
+
+Step 1 - What does this step do?
+> Install dependencies
+
+How should this step be executed?
+> shell command
+
+Enter the shell command:
+> npm install
+
+Add another step?
+> yes
+
+...
+```
+
+The walkthrough guides you through defining:
+- **Name**: A unique name for the skill
+- **Description**: What the skill does (min 20 characters)
+- **Aliases**: Example commands that invoke the skill (optional)
+- **Config**: Configuration properties needed (optional)
+- **Steps**: Each step with either a shell command or reference to another skill
+
+Skills are saved to `~/.pls/skills/` as markdown files. File names use
+kebab-case (e.g., "Build Frontend" becomes `build-frontend.md`).
+
 For complete documentation, see [docs/SKILLS.md](./docs/SKILLS.md).
 
 ### Structure
@@ -138,60 +174,121 @@ 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
+- **Execution**: The actual shell commands to run
 
 ### Example
 
-Here's a skill that builds different project variants:
+Here's a skill for building a product from source:
 
 ```markdown
 ### Name
-Build Project
+Build Product
 
 ### Description
-Build a project in different configurations:
-- dev (debug build with source maps)
-- prod (optimized build)
-- test (with test coverage)
+Build a product from source. Handles the full compilation pipeline.
+
+The company maintains two product lines:
+- Stable: the flagship product
+- Beta: the experimental product
+
+If the user says "just compile" or "recompile", dependency installation and
+tests MUST be skipped. Tests MUST also be skipped if the user says "without
+tests". Deployment MUST only run if the user explicitly asks. Compile and
+package steps are MANDATORY.
 
 ### Steps
 - Navigate to the project directory
-- Install dependencies if needed
-- Run the {ENV} build script
-- Generate build artifacts
+- Install build dependencies
+- Run the test suite
+- Compile source code
+- Package build artifacts
+- Deploy to server
 
 ### Execution
-- cd ~/projects/next
-- npm install
-- npm run build:{ENV}
-- cp -r dist/ builds/{ENV}/
+- [ Navigate To Project ]
+- ./configure && make deps
+- make test
+- make build
+- make package
+- ./scripts/deploy.sh
 ```
 
-With this skill defined, you can use natural language like:
+The `[ Navigate To Project ]` reference invokes another skill by name. When `pls`
+plans this workflow, it expands the reference inline, inserting that skill's
+execution steps at this position. This lets you compose complex workflows from
+simpler, reusable skills. Here's what that skill might look like:
+
+```markdown
+### Name
+Navigate To Project
+
+### Description
+The company maintains two product lines:
+- Stable: the flagship product
+- Beta: the experimental product
+
+### Aliases
+- go to project
+- navigate to repo
+
+### Config
+project:
+  stable:
+    path: string
+  beta:
+    path: string
+
+### Steps
+- Navigate to project directory
+
+### Execution
+- cd {project.PRODUCT.path}
 ```
-$ pls build project for production
-$ pls build dev environment
-$ pls build with testing enabled
+
+The `{project.PRODUCT.path}` placeholder uses config values from `~/.plsrc`. The
+PRODUCT is matched from user intent (e.g., "build stable" resolves to
+`project.stable.path`).
+
+The Description tells `pls` when to skip optional steps. This lets you say:
+
 ```
-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.
+$ pls build stable
 
-### Keep It Short
+  - Navigate to the Stable directory
+  - Install build dependencies
+  - Run the test suite
+  - Compile source code
+  - Package build artifacts
+```
 
-Skills also work with concise commands. Once you've taught `pls` about your
-workflow, you can use minimal phrasing:
+Here "stable" matches the PRODUCT, so `pls` looks up `project.stable.path` in your
+config. All steps run except deploy (not requested). When iterating quickly:
+
+```
+$ pls just recompile experimental
 
+  - Navigate to the Beta directory
+  - Compile source code
+  - Package build artifacts
 ```
-$ pls build prod
-$ pls build dev
-$ pls build test
+
+Now "experimental" resolves to `project.beta.path`. And when you're ready to ship:
+
 ```
+$ pls build and deploy main
 
-## Roadmap
+  - Navigate to the Stable directory
+  - Install build dependencies
+  - Run the test suite
+  - Compile source code
+  - Package build artifacts
+  - Deploy to server
+```
 
-- **0.9** - Learn skill, codebase refinement, complex dependency handling
-- **1.0** - Production release
+The same skill handles all cases based on your intent, something an alias or
+script can't do. Skills are fully dynamic: you can add new variants, change step
+conditions, or introduce new options anytime by editing the markdown file - no
+code changes required.
 
 ## Development
 

package/dist/components/Component.js

@@ -10,6 +10,7 @@ import { Debug } from './views/Debug.js';
 import { Execute, ExecuteView, mapStateToViewProps, } from './controllers/Execute.js';
 import { Feedback } from './views/Feedback.js';
 import { Introspect, IntrospectView } from './controllers/Introspect.js';
+import { Learn, LearnView } from './controllers/Learn.js';
 import { Message } from './views/Message.js';
 import { Refinement, RefinementView } from './controllers/Refinement.js';
 import { Report } from './views/Report.js';
@@ -51,8 +52,8 @@ export const SimpleComponent = memo(function SimpleComponent({ def, }) {
 export const ControllerComponent = memo(function ControllerComponent({ def, debug, requestHandlers, lifecycleHandlers, workflowHandlers, }) {
     switch (def.name) {
         case ComponentName.Config: {
-            const { props: { steps, onFinished, onAborted }, status, } = def;
-            return (_jsx(Config, { steps: steps, onFinished: onFinished, onAborted: onAborted, requestHandlers: requestHandlers, lifecycleHandlers: lifecycleHandlers, status: status, debug: debug }));
+            const { props: { steps, query, service, onFinished, onAborted }, status, } = def;
+            return (_jsx(Config, { steps: steps, query: query, service: service, onFinished: onFinished, onAborted: onAborted, requestHandlers: requestHandlers, lifecycleHandlers: lifecycleHandlers, workflowHandlers: workflowHandlers, status: status, debug: debug }));
         }
         case ComponentName.Command: {
             const { props: { command, service, onAborted }, status, } = def;
@@ -86,6 +87,10 @@ export const ControllerComponent = memo(function ControllerComponent({ def, debu
             const { props: { tasks, service, upcoming, label }, status, } = def;
             return (_jsx(Execute, { tasks: tasks, service: service, upcoming: upcoming, label: label, requestHandlers: requestHandlers, lifecycleHandlers: lifecycleHandlers, workflowHandlers: workflowHandlers, status: status }));
         }
+        case ComponentName.Learn: {
+            const { props: { suggestedName, onFinished, onAborted }, status, } = def;
+            return (_jsx(Learn, { suggestedName: suggestedName, onFinished: onFinished, onAborted: onAborted, requestHandlers: requestHandlers, lifecycleHandlers: lifecycleHandlers, workflowHandlers: workflowHandlers, status: status }));
+        }
         default:
             throw new Error(`Unknown managed component: ${def.name}`);
     }
@@ -100,7 +105,9 @@ export const ViewComponent = memo(function ViewComponent({ def, }) {
             return (_jsx(ConfirmView, { status: status, message: message, selectedIndex: state.selectedIndex }));
         }
         case ComponentName.Config: {
-            const { props: { steps }, state, status, } = def;
+            const { props: { steps: propSteps = [] }, state, status, } = def;
+            // Use resolved steps from state if available (for query-based configs)
+            const steps = state.steps ?? propSteps;
             return _jsx(ConfigView, { steps: steps, state: state, status: status });
         }
         case ComponentName.Schedule: {
@@ -135,6 +142,10 @@ export const ViewComponent = memo(function ViewComponent({ def, }) {
             const { props: { text }, status, } = def;
             return _jsx(RefinementView, { text: text, status: status });
         }
+        case ComponentName.Learn: {
+            const { state, status } = def;
+            return (_jsx(LearnView, { state: state, status: status, onInputChange: () => { }, onInputSubmit: () => { } }));
+        }
         default:
             throw new Error(`Unknown managed component: ${def.name}`);
     }
@@ -161,6 +172,7 @@ export const TimelineComponent = ({ def, }) => {
         case ComponentName.Execute:
         case ComponentName.Answer:
         case ComponentName.Introspect:
+        case ComponentName.Learn:
             return _jsx(ViewComponent, { def: def });
         default:
             throw new Error('Unknown component type');

package/dist/components/controllers/Command.js

@@ -34,28 +34,12 @@ export function Command({ command, status, service, requestHandlers, lifecycleHa
         async function process(svc) {
             const startTime = Date.now();
             try {
-                let result = await svc.processWithTool(command, 'schedule');
-                // Save schedule debug output before potentially delegating
-                const scheduleDebug = result.debug || [];
-                // If all tasks are configure type, delegate to CONFIGURE tool
-                const allConfig = result.tasks.length > 0 &&
-                    result.tasks.every((task) => task.type === TaskType.Config);
-                if (allConfig) {
-                    // Extract query from first config task params, default to 'app'
-                    const query = result.tasks[0].params?.query || 'app';
-                    // Call CONFIGURE tool to get specific config keys
-                    result = await svc.processWithTool(query, 'configure');
-                }
+                const result = await svc.processWithTool(command, 'schedule');
                 await ensureMinimumTime(startTime, MIN_PROCESSING_TIME);
                 if (mounted) {
                     // Add debug components to timeline if present
-                    // If we delegated to configure, include both schedule and configure debug
-                    // If not, only include schedule debug (result.debug is same as scheduleDebug)
-                    const debugComponents = allConfig
-                        ? [...scheduleDebug, ...(result.debug || [])]
-                        : scheduleDebug;
-                    if (debugComponents.length > 0) {
-                        workflowHandlers.addToTimeline(...debugComponents);
+                    if (result.debug?.length) {
+                        workflowHandlers.addToTimeline(...result.debug);
                     }
                     // Update local state
                     setMessage(result.message);

package/dist/components/controllers/Config.js

@@ -1,24 +1,57 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
-import { ComponentStatus } from '../../types/components.js';
-import { FeedbackType } from '../../types/types.js';
+import { Box, Text } from 'ink';
+import { ComponentStatus, } from '../../types/components.js';
+import { FeedbackType, TaskType } from '../../types/types.js';
 import { createFeedback } from '../../services/components.js';
+import { createConfigStepsFromSchema } from '../../configuration/steps.js';
+import { saveConfigLabels } from '../../configuration/labels.js';
 import { DebugLevel } from '../../configuration/types.js';
 import { useInput } from '../../services/keyboard.js';
 import { ConfigView, StepType } from '../views/Config.js';
+import { Spinner } from '../views/Spinner.js';
 export { ConfigView, StepType, } from '../views/Config.js';
+/**
+ * Resolve query to config steps via CONFIGURE tool
+ */
+async function resolveQueryToSteps(query, service) {
+    const result = await service.processWithTool(query, 'configure');
+    const configTasks = result.tasks.filter((task) => task.type === TaskType.Config && task.params?.key);
+    if (configTasks.length === 0) {
+        throw new Error('No configuration settings matched your query.');
+    }
+    const keys = configTasks.map((task) => task.params?.key);
+    const labels = {};
+    for (const task of configTasks) {
+        const key = task.params?.key;
+        if (key && task.action) {
+            labels[key] = task.action;
+        }
+    }
+    if (Object.keys(labels).length > 0) {
+        saveConfigLabels(labels);
+    }
+    const steps = createConfigStepsFromSchema(keys);
+    return {
+        steps: steps.map((step, i) => ({
+            ...step,
+            description: labels[keys[i]] || step.description,
+        })),
+        debug: result.debug || [],
+    };
+}
 /**
  * Config controller: Multi-step wizard logic
  */
 export function Config(props) {
-    const { steps, status, debug = DebugLevel.None, requestHandlers, lifecycleHandlers, onFinished, onAborted, } = props;
+    const { steps: initialSteps, query, service, status, debug = DebugLevel.None, requestHandlers, lifecycleHandlers, workflowHandlers, onFinished, onAborted, } = props;
     const isActive = status === ComponentStatus.Active;
+    const [steps, setSteps] = useState(initialSteps || []);
+    const [resolving, setResolving] = useState(!initialSteps?.length && !!query);
     const [step, setStep] = useState(0);
     const [values, setValues] = useState(() => {
-        // Initialize from step defaults
         const initial = {};
-        steps.forEach((stepConfig) => {
-            // Use full path if available, otherwise use key
+        (initialSteps || []).forEach((stepConfig) => {
             const configKey = stepConfig.path || stepConfig.key;
             switch (stepConfig.type) {
                 case StepType.Text:
@@ -30,45 +63,83 @@ export function Config(props) {
                     initial[configKey] =
                         stepConfig.options[stepConfig.defaultIndex].value;
                     break;
-                default: {
-                    const _exhaustiveCheck = stepConfig;
-                    throw new Error('Unsupported step type');
-                }
             }
         });
         return initial;
     });
-    const [inputValue, setInputValue] = useState(() => {
-        // Initialize with the current step's value if available
-        if (step < steps.length) {
+    const [inputValue, setInputValue] = useState('');
+    const [selectedIndex, setSelectedIndex] = useState(() => {
+        if (!initialSteps?.length)
+            return 0;
+        const first = initialSteps[0];
+        return first.type === StepType.Selection ? first.defaultIndex : 0;
+    });
+    // Resolve query to steps
+    useEffect(() => {
+        if (!isActive || !query || !service || initialSteps?.length)
+            return;
+        resolveQueryToSteps(query, service)
+            .then((result) => {
+            // Add debug components to timeline if present
+            if (result.debug.length) {
+                workflowHandlers.addToTimeline(...result.debug);
+            }
+            setSteps(result.steps);
+            setResolving(false);
+            // Initialize values for resolved steps
+            const initial = {};
+            result.steps.forEach((stepConfig) => {
+                const configKey = stepConfig.path || stepConfig.key;
+                switch (stepConfig.type) {
+                    case StepType.Text:
+                        if (stepConfig.value !== null) {
+                            initial[configKey] = stepConfig.value;
+                        }
+                        break;
+                    case StepType.Selection:
+                        initial[configKey] =
+                            stepConfig.options[stepConfig.defaultIndex].value;
+                        break;
+                }
+            });
+            setValues(initial);
+        })
+            .catch((err) => {
+            setResolving(false);
+            lifecycleHandlers.completeActive(createFeedback({
+                type: FeedbackType.Failed,
+                message: err instanceof Error ? err.message : 'Failed to resolve',
+            }));
+        });
+    }, [
+        isActive,
+        query,
+        service,
+        initialSteps,
+        lifecycleHandlers,
+        workflowHandlers,
+    ]);
+    // Update inputValue and selectedIndex when step changes
+    useEffect(() => {
+        if (isActive && step < steps.length) {
             const stepConfig = steps[step];
             const configKey = stepConfig.path || stepConfig.key;
-            return values[configKey] || '';
+            setInputValue(values[configKey] || '');
+            if (stepConfig.type === StepType.Selection) {
+                setSelectedIndex(stepConfig.defaultIndex);
+            }
         }
-        return '';
-    });
-    const [selectedIndex, setSelectedIndex] = useState(0);
+    }, [step, isActive, steps, values]);
     const normalizeValue = (value) => {
-        if (value === null || value === undefined) {
+        if (value === null || value === undefined)
             return '';
-        }
         return value.replace(/\n/g, '').trim();
     };
-    // Update inputValue when step changes
-    useEffect(() => {
-        if (isActive && step < steps.length) {
-            const stepConfig = steps[step];
-            const configKey = stepConfig.path || stepConfig.key;
-            const value = values[configKey] || '';
-            setInputValue(value);
-        }
-    }, [step, isActive, steps]);
     useInput((_, key) => {
         if (!isActive || step >= steps.length)
             return;
         const currentStepConfig = steps[step];
         if (key.escape) {
-            // Save current value before aborting
             const configKey = currentStepConfig.path || currentStepConfig.key;
             let currentValue = '';
             switch (currentStepConfig.type) {
@@ -78,28 +149,20 @@ export function Config(props) {
                 case StepType.Selection:
                     currentValue = values[configKey] || '';
                     break;
-                default: {
-                    const _exhaustiveCheck = currentStepConfig;
-                    throw new Error('Unsupported step type');
-                }
             }
             const finalValues = currentValue
                 ? { ...values, [configKey]: currentValue }
                 : values;
-            // Expose final state
-            const finalState = {
+            requestHandlers.onCompleted({
                 values: finalValues,
                 completedStep: step,
                 selectedIndex,
-            };
-            requestHandlers.onCompleted(finalState);
-            // Abort configuration
+                steps,
+            });
             if (onAborted) {
-                // Let Workflow handler complete and add feedback
                 onAborted('configuration');
             }
             else {
-                // Fallback: complete with abort feedback directly
                 lifecycleHandlers.completeActive(createFeedback({
                     type: FeedbackType.Aborted,
                     message: 'Configuration cancelled.',
@@ -107,7 +170,6 @@ export function Config(props) {
             }
             return;
         }
-        // Handle selection step navigation
         if (currentStepConfig.type === StepType.Selection) {
             if (key.tab) {
                 setSelectedIndex((prev) => (prev + 1) % currentStepConfig.options.length);
@@ -122,13 +184,10 @@ export function Config(props) {
         let finalValue = '';
         switch (currentStepConfig.type) {
             case StepType.Selection:
-                // For selection, value is already validated by options
                 finalValue = value;
                 break;
             case StepType.Text: {
-                // For text input
                 const normalizedInput = normalizeValue(value);
-                // Try user input first, then fall back to default
                 if (normalizedInput && currentStepConfig.validate(normalizedInput)) {
                     finalValue = normalizedInput;
                 }
@@ -138,63 +197,41 @@ export function Config(props) {
                 }
                 break;
             }
-            default: {
-                const _exhaustiveCheck = currentStepConfig;
-                throw new Error('Unsupported step type');
-            }
         }
-        // Don't allow empty or invalid value
-        if (!finalValue) {
+        if (!finalValue)
             return;
-        }
-        // Use full path if available, otherwise use key
         const configKey = currentStepConfig.path || currentStepConfig.key;
         const newValues = { ...values, [configKey]: finalValue };
         setValues(newValues);
         setInputValue('');
         if (step === steps.length - 1) {
-            // Last step completed
-            // Expose final state
-            const finalState = {
+            requestHandlers.onCompleted({
                 values: newValues,
                 completedStep: steps.length,
                 selectedIndex,
-            };
-            requestHandlers.onCompleted(finalState);
-            // Call onFinished callback and handle result
+                steps,
+            });
             try {
-                if (onFinished) {
-                    onFinished(newValues);
-                }
-                // Success - complete with success feedback
+                onFinished?.(newValues);
                 lifecycleHandlers.completeActive(createFeedback({
                     type: FeedbackType.Succeeded,
                     message: 'Configuration saved successfully.',
                 }));
             }
             catch (error) {
-                // Failure - complete with error feedback
-                const errorMessage = error instanceof Error ? error.message : 'Configuration failed';
-                lifecycleHandlers.completeActive(createFeedback({ type: FeedbackType.Failed, message: errorMessage }));
+                lifecycleHandlers.completeActive(createFeedback({
+                    type: FeedbackType.Failed,
+                    message: error instanceof Error ? error.message : 'Configuration failed',
+                }));
             }
             setStep(steps.length);
         }
         else {
-            const nextStep = step + 1;
-            setStep(nextStep);
-            // Reset selectedIndex for next step
-            if (nextStep < steps.length &&
-                steps[nextStep].type === StepType.Selection) {
-                setSelectedIndex(steps[nextStep].defaultIndex);
-            }
+            setStep(step + 1);
         }
     };
-    // Build current state for View
-    // Controller always renders View, passing current state and callbacks
-    const state = {
-        values,
-        completedStep: step,
-        selectedIndex,
-    };
-    return (_jsx(ConfigView, { steps: steps, state: state, status: status, debug: debug, onInputChange: setInputValue, onInputSubmit: handleSubmit }));
+    if (resolving) {
+        return (_jsxs(Box, { marginLeft: 1, children: [_jsx(Text, { children: "Resolving configuration... " }), _jsx(Spinner, {})] }));
+    }
+    return (_jsx(ConfigView, { steps: steps, state: { values, completedStep: step, selectedIndex }, status: status, debug: debug, onInputChange: setInputValue, onInputSubmit: handleSubmit }));
 }