prompt-language-shell 0.5.0 → 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

@@ -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/ui/Introspect.js

@@ -78,6 +78,7 @@ export function Introspect({ tasks, state, service, children, debug = false, onE
                     // Filter out internal capabilities when not in debug mode
                     if (!debug) {
                         capabilities = capabilities.filter((cap) => cap.name.toUpperCase() !== 'PLAN' &&
+                            cap.name.toUpperCase() !== 'VALIDATE' &&
                             cap.name.toUpperCase() !== 'REPORT');
                     }
                     setIsLoading(false);

package/dist/ui/Welcome.js

@@ -1,22 +1,29 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
+import { Palette } from '../services/colors.js';
 import { Panel } from './Panel.js';
+export function Welcome({ app }) {
+    return (_jsx(Box, { alignSelf: "flex-start", children: _jsxs(Panel, { children: [_jsx(Header, { app: app }), _jsx(Description, { description: app.description }), _jsx(Usage, {})] }) }));
+}
 function Header({ app }) {
     const words = app.name
         .split('-')
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1));
-    return (_jsxs(Box, { marginBottom: 1, gap: 1, children: [words.map((word, index) => (_jsx(Text, { color: "greenBright", bold: true, children: word }, index))), _jsxs(Text, { color: "whiteBright", dimColor: true, children: ["v", app.version] }), app.isDev && _jsx(Text, { color: "yellowBright", children: "dev" })] }));
+    return (_jsxs(Box, { marginBottom: 1, gap: 1, children: [words.map((word, index) => (_jsx(Text, { color: Palette.BrightGreen, bold: true, children: word }, index))), _jsxs(Text, { color: Palette.AshGray, children: ["v", app.version] }), app.isDev && _jsx(Text, { color: Palette.Yellow, children: "dev" })] }));
 }
 function Description({ description }) {
     const lines = description
         .split('. ')
         .map((line) => line.replace(/\.$/, ''))
         .filter(Boolean);
-    return (_jsx(_Fragment, { children: lines.map((line, index) => (_jsx(Box, { children: _jsxs(Text, { color: "white", children: [line, "."] }) }, index))) }));
+    return (_jsx(_Fragment, { children: lines.map((line, index) => (_jsx(Box, { children: _jsxs(Text, { color: Palette.White, children: [line, "."] }) }, index))) }));
 }
 function Usage() {
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "brightWhite", bold: true, children: "Usage:" }), _jsxs(Box, { gap: 1, children: [_jsx(Text, { color: "whiteBright", dimColor: true, children: ">" }), _jsxs(Box, { gap: 1, children: [_jsx(Text, { color: "greenBright", bold: true, children: "pls" }), _jsx(Text, { color: "yellow", bold: true, children: "[describe your request]" })] })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, gap: 1, children: [_jsx(Section, { title: "Get started:", children: _jsx(Example, { children: "list skills" }) }), _jsx(Section, { title: "Usage:", children: _jsx(Example, { children: "[describe your request]" }) })] }));
 }
-export function Welcome({ app }) {
-    return (_jsx(Box, { alignSelf: "flex-start", children: _jsxs(Panel, { children: [_jsx(Header, { app: app }), _jsx(Description, { description: app.description }), _jsx(Usage, {})] }) }));
+function Section({ title, children, }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: Palette.White, children: title }), children] }));
+}
+function Example({ children }) {
+    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: Palette.Gray, children: ">" }), _jsx(Text, { color: Palette.BrightGreen, bold: true, children: "pls" }), _jsx(Text, { color: Palette.Yellow, children: children })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-language-shell",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Your personal command-line concierge. Ask politely, and it gets things done.",
   "type": "module",
   "main": "dist/index.js",