prompt-language-shell 0.6.6 → 0.7.0

package/dist/services/skills.js

@@ -1,7 +1,42 @@
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
-import { parseSkillMarkdown } from './skill-parser.js';
+import { getUnknownSkillMessage } from './messages.js';
+import { parseSkillMarkdown, displayNameToKey } from './parser.js';
+/**
+ * Built-in skill names that user skills cannot override
+ */
+const BUILT_IN_SKILLS = new Set([
+    'plan',
+    'execute',
+    'answer',
+    'config',
+    'validate',
+    'introspect',
+]);
+/**
+ * Validate filename follows kebab-case pattern
+ * Valid: deploy-app.md, build-project-2.md, copy-files.md
+ * Invalid: Deploy_App.md, buildProject.md, DEPLOY.md, file name.md
+ */
+export function isValidSkillFilename(filename) {
+    // Must end with .md or .MD extension
+    if (!filename.endsWith('.md') && !filename.endsWith('.MD')) {
+        return false;
+    }
+    // Extract name without extension
+    const name = filename.slice(0, -3);
+    // Must match kebab-case pattern: lowercase letters, numbers, and hyphens only
+    // Must start with a letter, and not start or end with a hyphen
+    const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+    return kebabCasePattern.test(name);
+}
+/**
+ * Check if skill key conflicts with built-in skills
+ */
+export function conflictsWithBuiltIn(key) {
+    return BUILT_IN_SKILLS.has(key);
+}
 /**
  * Get the path to the skills directory
  */
@@ -10,7 +45,8 @@ export function getSkillsDirectory() {
 }
 /**
  * Load all skill markdown files from the skills directory
- * Returns an array of skill file contents
+ * Returns an array of objects with filename (key) and content
+ * Filters out invalid filenames and conflicts with built-in skills
  */
 export function loadSkills() {
     const skillsDir = getSkillsDirectory();
@@ -20,12 +56,27 @@ export function loadSkills() {
     }
     try {
         const files = readdirSync(skillsDir);
-        // Filter for markdown files
-        const skillFiles = files.filter((file) => file.endsWith('.md') || file.endsWith('.MD'));
-        // Read and return contents of each skill file
-        return skillFiles.map((file) => {
+        // Filter and map valid skill files
+        return files
+            .filter((file) => {
+            // Must follow kebab-case naming convention
+            if (!isValidSkillFilename(file)) {
+                return false;
+            }
+            // Extract key (filename without extension, handles both .md and .MD)
+            const key = file.slice(0, -3);
+            // Must not conflict with built-in skills
+            if (conflictsWithBuiltIn(key)) {
+                return false;
+            }
+            return true;
+        })
+            .map((file) => {
+            // Extract key (filename without extension, handles both .md and .MD)
+            const key = file.slice(0, -3);
             const filePath = join(skillsDir, file);
-            return readFileSync(filePath, 'utf-8');
+            const content = readFileSync(filePath, 'utf-8');
+            return { key, content };
         });
     }
     catch {
@@ -38,17 +89,17 @@ export function loadSkills() {
  * Returns structured skill definitions (including invalid skills)
  */
 export function loadSkillDefinitions() {
-    const skillContents = loadSkills();
-    return skillContents.map((content) => parseSkillMarkdown(content));
+    const skills = loadSkills();
+    return skills.map(({ key, content }) => parseSkillMarkdown(key, content));
 }
 /**
  * Load skills and mark incomplete ones in their markdown
  * Returns array of skill markdown with status markers
  */
 export function loadSkillsWithValidation() {
-    const skillContents = loadSkills();
-    return skillContents.map((content) => {
-        const parsed = parseSkillMarkdown(content);
+    const skills = loadSkills();
+    return skills.map(({ key, content }) => {
+        const parsed = parseSkillMarkdown(key, content);
         // If skill is incomplete (either validation failed or needs more documentation), append (INCOMPLETE) to the name
         if (parsed.isIncomplete) {
             return content.replace(/^(#{1,6}\s+Name\s*\n+)(.+?)(\n|$)/im, `$1$2 (INCOMPLETE)$3`);
@@ -58,13 +109,19 @@ export function loadSkillsWithValidation() {
 }
 /**
  * Create skill lookup function from definitions
+ * Lookup by key (display name is converted to kebab-case for matching)
+ * Example: "Deploy App" -> "deploy-app" -> matches skill with key "deploy-app"
  */
 export function createSkillLookup(definitions) {
-    const map = new Map();
+    const keyMap = new Map();
     for (const definition of definitions) {
-        map.set(definition.name, definition);
+        keyMap.set(definition.key, definition);
     }
-    return (name) => map.get(name) || null;
+    return (name) => {
+        // Convert display name to kebab-case key for lookup
+        const key = displayNameToKey(name);
+        return keyMap.get(key) || null;
+    };
 }
 /**
  * Format skills for inclusion in the planning prompt
@@ -74,7 +131,6 @@ export function formatSkillsForPrompt(skills) {
         return '';
     }
     const header = `
-
 ## Available Skills
 
 The following skills define domain-specific workflows. When the user's
@@ -90,6 +146,98 @@ brackets for additional information. Use commas instead. For example:
 - WRONG: "Build project Alpha (the legacy version)"
 
 `;
-    const skillsContent = skills.join('\n\n');
+    const skillsContent = skills.map((s) => s.trim()).join('\n\n');
     return header + skillsContent;
 }
+/**
+ * Parse skill reference from execution line
+ * Format: [ Display Name ] with mandatory spaces
+ * Returns display name if line matches format, otherwise null
+ * Example: "[ My Skill ]" -> "My Skill"
+ */
+export function parseSkillReference(line) {
+    // Must match format: [ content ] with at least one space before and after
+    const match = line.trim().match(/^\[\s+(.+?)\s+\]$/);
+    return match ? match[1] : null;
+}
+/**
+ * Check if execution line is a skill reference
+ * Must have format: [ content ] with spaces
+ */
+export function isSkillReference(line) {
+    return /^\[\s+.+?\s+\]$/.test(line.trim());
+}
+/**
+ * Expand skill references in execution commands
+ * Returns expanded execution lines with references replaced
+ * Throws error if circular reference detected or skill not found
+ * Reference format: [ Skill Name ]
+ */
+export function expandSkillReferences(execution, skillLookup, visited = new Set()) {
+    const expanded = [];
+    for (const line of execution) {
+        // First: Detect if line matches [ XXX ] format
+        const skillName = parseSkillReference(line);
+        if (!skillName) {
+            // Not a reference, keep command as-is
+            expanded.push(line);
+            continue;
+        }
+        // Check for circular reference
+        if (visited.has(skillName)) {
+            throw new Error(`Circular skill reference detected: ${Array.from(visited).join(' → ')} → ${skillName}`);
+        }
+        // Second: Match against skill name
+        const skill = skillLookup(skillName);
+        if (!skill) {
+            // Referenced skill not found - throw error to break execution
+            throw new Error(getUnknownSkillMessage(skillName));
+        }
+        // Recursively expand referenced skill's execution
+        const newVisited = new Set(visited);
+        newVisited.add(skillName);
+        const referencedExecution = expandSkillReferences(skill.execution, skillLookup, newVisited);
+        expanded.push(...referencedExecution);
+    }
+    return expanded;
+}
+/**
+ * Get all skill names referenced in execution (including nested)
+ * Returns unique set of skill names
+ */
+export function getReferencedSkills(execution, skillLookup, visited = new Set()) {
+    const referenced = new Set();
+    for (const line of execution) {
+        const skillName = parseSkillReference(line);
+        if (!skillName || visited.has(skillName)) {
+            continue;
+        }
+        referenced.add(skillName);
+        const skill = skillLookup(skillName);
+        if (skill) {
+            const newVisited = new Set(visited);
+            newVisited.add(skillName);
+            const nested = getReferencedSkills(skill.execution, skillLookup, newVisited);
+            for (const name of nested) {
+                referenced.add(name);
+            }
+        }
+    }
+    return referenced;
+}
+/**
+ * Validate skill references don't form cycles
+ * Returns true if valid, false if circular reference detected
+ */
+export function validateNoCycles(execution, skillLookup, visited = new Set()) {
+    try {
+        expandSkillReferences(execution, skillLookup, visited);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('Circular')) {
+            return false;
+        }
+        throw error;
+    }
+}

package/dist/services/{execution-validator.js → validator.js}

@@ -1,8 +1,7 @@
-import { extractPlaceholders, pathToString, resolveVariant, } from './placeholder-resolver.js';
-import { loadUserConfig, hasConfigPath } from './config-loader.js';
-import { loadSkills } from './skills.js';
-import { expandSkillReferences } from './skill-expander.js';
-import { getConfigType, parseSkillMarkdown } from './skill-parser.js';
+import { extractPlaceholders, pathToString, resolveVariant, } from './resolver.js';
+import { loadUserConfig, hasConfigPath } from './loader.js';
+import { loadSkillDefinitions, createSkillLookup, expandSkillReferences, } from './skills.js';
+import { getConfigType } from './parser.js';
 /**
  * Validate config requirements for execute tasks
  * Returns validation result with missing config and validation errors
@@ -14,9 +13,8 @@ export function validateExecuteTasks(tasks) {
     const validationErrors = [];
     const seenSkills = new Set();
     // Load all skills (including invalid ones for validation)
-    const skillContents = loadSkills();
-    const parsedSkills = skillContents.map((content) => parseSkillMarkdown(content));
-    const skillLookup = (name) => parsedSkills.find((s) => s.name === name) || null;
+    const parsedSkills = loadSkillDefinitions();
+    const skillLookup = createSkillLookup(parsedSkills);
     // Check for invalid skills being used in tasks
     for (const task of tasks) {
         const skillName = typeof task.params?.skill === 'string' ? task.params.skill : null;

package/dist/{config/ANSWER.md → skills/answer.md}

@@ -5,9 +5,9 @@ command-line concierge. Your role is to **answer questions** and provide
 up-to-date information when a task with type "answer" has been planned and
 confirmed.
 
-**IMPORTANT**: Use web search to find current, accurate information. This tool
-is designed for quick answers from the terminal without needing to open a web
-browser. Always search for the latest data rather than relying solely on
+**IMPORTANT**: Use web search to find current, accurate information. This
+tool is designed for quick answers from the terminal without needing to open a
+web browser. Always search for the latest data rather than relying solely on
 training data.
 
 ## Execution Flow
@@ -60,11 +60,11 @@ TypeScript code compiles to JavaScript and runs anywhere JavaScript runs.
 
 Bad answer (too verbose):
 ```
-TypeScript is a strongly typed programming language that builds on JavaScript,
-giving you better tooling at any scale. TypeScript adds additional syntax to
-JavaScript to support a tighter integration with your editor. It catches errors
-early in development by checking types. TypeScript code converts to JavaScript
-which runs anywhere.
+TypeScript is a strongly typed programming language that builds on
+JavaScript, giving you better tooling at any scale. TypeScript adds
+additional syntax to JavaScript to support a tighter integration with your
+editor. It catches errors early in development by checking types. TypeScript
+code converts to JavaScript which runs anywhere.
 ```
 
 ### Example 2: Technical explanation
@@ -101,7 +101,8 @@ They enable cleaner, more reusable component logic.
 
 ## Guidelines
 
-1. **Be direct**: Answer the question immediately, don't introduce your answer
+1. **Be direct**: Answer the question immediately, don't introduce your
+   answer
 2. **Be accurate**: Provide correct, factual information
 3. **Be concise**: Respect the 4-line, 80-character constraints strictly
 4. **Be helpful**: Focus on what the user needs to know

package/dist/{config/CONFIG.md → skills/config.md}

@@ -1,33 +1,40 @@
 ## Overview
 
-You are the CONFIG tool for "pls" (please), a professional command-line concierge.
-Your role is to determine which configuration settings the user wants to configure
-based on their query.
+You are the CONFIG tool for "pls" (please), a professional command-line
+concierge. Your role is to determine which configuration settings the user
+wants to configure based on their query.
 
 ## Input
 
 You will receive:
-- `configStructure`: Object mapping config keys to descriptions (e.g., {"anthropic.key": "Anthropic API key", "settings.debug": "Debug mode (optional)"})
-- `configuredKeys`: Array of keys that exist in the user's config file (e.g., ["anthropic.key", "anthropic.model", "settings.debug"])
+- `configStructure`: Object mapping config keys to descriptions (e.g.,
+  {"anthropic.key": "Anthropic API key", "settings.debug": "Debug mode
+  (optional)"})
+- `configuredKeys`: Array of keys that exist in the user's config file
+  (e.g., ["anthropic.key", "anthropic.model", "settings.debug"])
 - `query`: User's request (e.g., "app", "mode", "anthropic", or empty)
 
 ## Task
 
-Determine which config keys the user wants to configure and return them as tasks.
+Determine which config keys the user wants to configure and return them
+as tasks.
 
 ## Mapping Rules
 
 ### Query: "app" or empty/unclear
 - Return all **required** config keys (those needed for the app to work)
-- Also include any keys marked as "(optional)" that appear in `configuredKeys` (optional settings that exist in user's config file)
-- Also include any keys marked as "(discovered)" (they exist in user's config file but aren't in schema)
+- Also include any keys marked as "(optional)" that appear in
+  `configuredKeys` (optional settings that exist in user's config file)
+- Also include any keys marked as "(discovered)" (they exist in user's
+  config file but aren't in schema)
 - Required keys: `anthropic.key`, `anthropic.model`
 
 ### Query: "mode"
 - Return only: `settings.debug`
 
 ### Query: "anthropic"
-- Return all keys starting with `anthropic.` (usually `anthropic.key` and `anthropic.model`)
+- Return all keys starting with `anthropic.` (usually `anthropic.key` and
+  `anthropic.model`)
 
 ### Other queries
 - Match the query against config key names and descriptions

package/dist/{config/EXECUTE.md → skills/execute.md}

@@ -1,8 +1,8 @@
 ## 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.
+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
 
@@ -11,23 +11,23 @@ This tool is invoked AFTER:
 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.
+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")
+- 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
+- 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.
+**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
 
@@ -35,16 +35,18 @@ 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.
+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
+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
+4. **Substitute parameters**: Replace {PARAM} placeholders with actual
+   values from task params
 
 ### Example Skill
 
@@ -59,8 +61,8 @@ Process Data
 
 ### 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}
+- python3 transform.py --input {SOURCE}.csv --output data.csv
+- csvtool col 1-3 data.csv > output.{FORMAT}
 ```
 
 ### Matching Process
@@ -77,9 +79,9 @@ Given tasks from this skill:
 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.
+**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
 
@@ -90,9 +92,11 @@ Return a structured response with commands to execute:
 - **commands**: Array of command objects to execute sequentially
 
 **Command object structure:**
-- **description**: Brief description of what this command does (max 64 chars)
+- **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)
+- **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)
 
@@ -101,24 +105,31 @@ Return a structured response with commands to execute:
 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
+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 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)
+- 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" } }
+Task: {
+  action: "Create a new file called test.txt",
+  type: "execute",
+  params: { filename: "test.txt" }
+}
 
 Response:
 ```
@@ -130,7 +141,10 @@ commands:
 
 ### Example 2: Directory listing
 
-Task: { action: "Show files in the current directory", type: "execute" }
+Task: {
+  action: "Show files in the current directory",
+  type: "execute"
+}
 
 Response:
 ```
@@ -143,8 +157,11 @@ commands:
 ### Example 3: Multiple sequential commands
 
 Tasks:
-- { action: "Create project directory", type: "execute",
-    params: { path: "my-project" } }
+- {
+    action: "Create project directory",
+    type: "execute",
+    params: { path: "my-project" }
+  }
 - { action: "Initialize git repository", type: "execute" }
 - { action: "Create README file", type: "execute" }
 
@@ -164,7 +181,10 @@ commands:
 
 ### Example 4: Install dependencies
 
-Task: { action: "Install dependencies", type: "execute" }
+Task: {
+  action: "Install dependencies",
+  type: "execute"
+}
 
 Response:
 ```
@@ -177,20 +197,30 @@ commands:
 
 ### Example 5: Skill-based execution
 
-When executing from a skill like "Process Data", tasks include params.skill:
+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" } }
+- {
+    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}
+- Line 2: python3 transform.py --input {SOURCE}.csv --output data.csv
+- Line 3: csvtool col 1-3 data.csv > output.{FORMAT}
 
 Response (using skill's Execution commands):
 ```
@@ -200,19 +230,23 @@ commands:
     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"
+    command: "python3 transform.py --input sales.csv --output data.csv"
     timeout: 120000
   - description: "Export the results to json"
-    command: "csvtool col 1-3 processed.csv > output.json"
+    command: "csvtool col 1-3 data.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.
+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" } }
+Task: {
+  action: "Copy config to backup",
+  type: "execute",
+  params: { source: "~/.config/app", destination: "~/.config/app.backup" }
+}
 
 Response:
 ```
@@ -224,7 +258,10 @@ commands:
 
 ### Example 7: Checking system information
 
-Task: { action: "Check disk space", type: "execute" }
+Task: {
+  action: "Check disk space",
+  type: "execute"
+}
 
 Response:
 ```
@@ -240,11 +277,12 @@ 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
+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