prompt-language-shell 0.4.9 → 0.5.0

package/dist/services/placeholder-resolver.js

@@ -0,0 +1,120 @@
+/**
+ * Check if a string is all uppercase (variant placeholder indicator)
+ */
+function isUpperCase(str) {
+    return str === str.toUpperCase() && str !== str.toLowerCase();
+}
+/**
+ * Parse placeholder from string
+ * Returns placeholder info or null if no valid placeholder found
+ */
+export function parsePlaceholder(text) {
+    // Match {path.to.property} format
+    const match = text.match(/\{([^}]+)\}/);
+    if (!match) {
+        return null;
+    }
+    const original = match[0];
+    const pathString = match[1];
+    const path = pathString.split('.');
+    // Check if any path component is uppercase (variant placeholder)
+    const variantIndex = path.findIndex((part) => isUpperCase(part));
+    const hasVariant = variantIndex !== -1;
+    return {
+        original,
+        path,
+        hasVariant,
+        variantIndex: hasVariant ? variantIndex : undefined,
+    };
+}
+/**
+ * Extract all placeholders from text
+ */
+export function extractPlaceholders(text) {
+    const placeholders = [];
+    const regex = /\{([^}]+)\}/g;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        const pathString = match[1];
+        const path = pathString.split('.');
+        const variantIndex = path.findIndex((part) => isUpperCase(part));
+        const hasVariant = variantIndex !== -1;
+        placeholders.push({
+            original: match[0],
+            path,
+            hasVariant,
+            variantIndex: hasVariant ? variantIndex : undefined,
+        });
+    }
+    return placeholders;
+}
+/**
+ * Replace uppercase component in path with actual variant name
+ * Returns new path with variant replaced
+ */
+export function resolveVariant(path, variantName) {
+    return path.map((part) => (isUpperCase(part) ? variantName : part));
+}
+/**
+ * Convert path array to dot notation string
+ */
+export function pathToString(path) {
+    return path.join('.');
+}
+/**
+ * Resolve placeholder value from config
+ * Returns the value at the specified path or undefined if not found
+ */
+export function resolveFromConfig(config, path) {
+    let current = config;
+    for (const part of path) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    if (typeof current === 'string' ||
+        typeof current === 'boolean' ||
+        typeof current === 'number') {
+        return current;
+    }
+    return undefined;
+}
+/**
+ * Replace all placeholders in text with values from config
+ * Note: Variant placeholders (with uppercase components) must be resolved first
+ */
+export function replacePlaceholders(text, config) {
+    return text.replace(/\{([^}]+)\}/g, (_match, pathString) => {
+        const path = pathString.split('.');
+        const value = resolveFromConfig(config, path);
+        if (value === undefined) {
+            // Keep placeholder if not found in config
+            return `{${pathString}}`;
+        }
+        return String(value);
+    });
+}
+/**
+ * Check if text contains any placeholders
+ */
+export function hasPlaceholders(text) {
+    return /\{[^}]+\}/.test(text);
+}
+/**
+ * Get all unique config paths required by placeholders in text
+ * Note: Variant placeholders (with uppercase components) must be resolved first
+ */
+export function getRequiredConfigPaths(text) {
+    const placeholders = extractPlaceholders(text);
+    const paths = new Set();
+    for (const placeholder of placeholders) {
+        if (!placeholder.hasVariant) {
+            paths.add(pathToString(placeholder.path));
+        }
+    }
+    return Array.from(paths);
+}

package/dist/services/shell.js

@@ -4,6 +4,7 @@ export var ExecutionStatus;
     ExecutionStatus["Running"] = "running";
     ExecutionStatus["Success"] = "success";
     ExecutionStatus["Failed"] = "failed";
+    ExecutionStatus["Aborted"] = "aborted";
 })(ExecutionStatus || (ExecutionStatus = {}));
 export var ExecutionResult;
 (function (ExecutionResult) {

package/dist/services/skill-expander.js

@@ -0,0 +1,91 @@
+/**
+ * Parse skill reference from execution line
+ * Returns skill name if line is a reference, otherwise null
+ */
+export function parseSkillReference(line) {
+    const match = line.match(/^\[(.+)\]$/);
+    return match ? match[1].trim() : null;
+}
+/**
+ * Check if execution line is a skill reference
+ */
+export function isSkillReference(line) {
+    return /^\[.+\]$/.test(line.trim());
+}
+/**
+ * Expand skill references in execution commands
+ * Returns expanded execution lines with references replaced
+ * Throws error if circular reference detected
+ */
+export function expandSkillReferences(execution, skillLookup, visited = new Set()) {
+    const expanded = [];
+    for (const line of execution) {
+        const skillName = parseSkillReference(line);
+        if (!skillName) {
+            // Not a reference, keep 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}`);
+        }
+        // Look up referenced skill
+        const skill = skillLookup(skillName);
+        if (!skill) {
+            // Referenced skill not found, keep as-is
+            expanded.push(line);
+            continue;
+        }
+        if (!skill.execution || skill.execution.length === 0) {
+            // Referenced skill has no execution, skip
+            continue;
+        }
+        // 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 && skill.execution) {
+            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/skill-parser.js

@@ -0,0 +1,169 @@
+import YAML from 'yaml';
+/**
+ * Parse a skill markdown file into structured definition
+ */
+export function parseSkillMarkdown(content) {
+    const sections = extractSections(content);
+    // Name is required
+    if (!sections.name) {
+        return null;
+    }
+    // Description is required
+    if (!sections.description) {
+        return null;
+    }
+    // Steps are required
+    if (!sections.steps || sections.steps.length === 0) {
+        return null;
+    }
+    // Validate execution and steps have same count (if execution exists)
+    if (sections.execution &&
+        sections.execution.length !== sections.steps.length) {
+        return null;
+    }
+    const skill = {
+        name: sections.name,
+        description: sections.description,
+        steps: sections.steps,
+    };
+    if (sections.aliases && sections.aliases.length > 0) {
+        skill.aliases = sections.aliases;
+    }
+    if (sections.config) {
+        skill.config = sections.config;
+    }
+    if (sections.execution && sections.execution.length > 0) {
+        skill.execution = sections.execution;
+    }
+    return skill;
+}
+/**
+ * Extract sections from markdown content
+ */
+function extractSections(content) {
+    const lines = content.split('\n');
+    const sections = {};
+    let currentSection = null;
+    let sectionLines = [];
+    for (const line of lines) {
+        // Check for section headers (### SectionName)
+        const headerMatch = line.match(/^###\s+(.+)$/);
+        if (headerMatch) {
+            // Process previous section
+            if (currentSection) {
+                processSectionContent(currentSection, sectionLines, sections);
+            }
+            // Start new section
+            currentSection = headerMatch[1].trim().toLowerCase();
+            sectionLines = [];
+        }
+        else if (currentSection) {
+            // Accumulate lines for current section
+            sectionLines.push(line);
+        }
+    }
+    // Process final section
+    if (currentSection) {
+        processSectionContent(currentSection, sectionLines, sections);
+    }
+    return sections;
+}
+/**
+ * Process accumulated section content
+ */
+function processSectionContent(sectionName, lines, sections) {
+    const content = lines.join('\n').trim();
+    if (!content) {
+        return;
+    }
+    switch (sectionName) {
+        case 'name':
+            sections.name = content;
+            break;
+        case 'description':
+            sections.description = content;
+            break;
+        case 'aliases':
+            sections.aliases = extractBulletList(content);
+            break;
+        case 'config':
+            sections.config = parseConfigSchema(content);
+            break;
+        case 'steps':
+            sections.steps = extractBulletList(content);
+            break;
+        case 'execution':
+            sections.execution = extractBulletList(content);
+            break;
+    }
+}
+/**
+ * Extract bullet list items from content
+ */
+function extractBulletList(content) {
+    const lines = content.split('\n');
+    const items = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Match bullet points: "- text" or "* text"
+        const bulletMatch = trimmed.match(/^[-*]\s+(.+)$/);
+        if (bulletMatch) {
+            items.push(bulletMatch[1].trim());
+        }
+    }
+    return items;
+}
+/**
+ * Parse YAML config schema
+ */
+function parseConfigSchema(content) {
+    try {
+        const parsed = YAML.parse(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Generate all config paths from schema
+ */
+export function generateConfigPaths(schema, prefix = '') {
+    const paths = [];
+    for (const [key, value] of Object.entries(schema)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === 'string') {
+            // Leaf node with type annotation
+            paths.push(fullKey);
+        }
+        else if (typeof value === 'object') {
+            // Nested object - recurse
+            paths.push(...generateConfigPaths(value, fullKey));
+        }
+    }
+    return paths;
+}
+/**
+ * Get config type for a specific path
+ */
+export function getConfigType(schema, path) {
+    const parts = path.split('.');
+    let current = schema;
+    for (const part of parts) {
+        if (typeof current === 'string') {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    if (typeof current === 'string' &&
+        (current === 'string' || current === 'boolean' || current === 'number')) {
+        return current;
+    }
+    return undefined;
+}

package/dist/services/skills.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { parseSkillMarkdown } from './skill-parser.js';
 /**
  * Get the path to the skills directory
  */
@@ -32,6 +33,31 @@ export function loadSkills() {
         return [];
     }
 }
+/**
+ * Load and parse all skill definitions
+ * Returns structured skill definitions
+ */
+export function loadSkillDefinitions() {
+    const skillContents = loadSkills();
+    const definitions = [];
+    for (const content of skillContents) {
+        const parsed = parseSkillMarkdown(content);
+        if (parsed) {
+            definitions.push(parsed);
+        }
+    }
+    return definitions;
+}
+/**
+ * Create skill lookup function from definitions
+ */
+export function createSkillLookup(definitions) {
+    const map = new Map();
+    for (const definition of definitions) {
+        map.set(definition.name, definition);
+    }
+    return (name) => map.get(name) || null;
+}
 /**
  * Format skills for inclusion in the planning prompt
  */

package/dist/services/timing.js

@@ -0,0 +1,38 @@
+/**
+ * Timing utilities for UI components
+ */
+/**
+ * Waits for at least the minimum processing time.
+ * Ensures async operations don't complete too quickly for good UX.
+ *
+ * @param startTime - The timestamp when the operation started
+ * @param minimumTime - The minimum total time the operation should take
+ */
+export async function ensureMinimumTime(startTime, minimumTime) {
+    const elapsed = Date.now() - startTime;
+    const remainingTime = Math.max(0, minimumTime - elapsed);
+    if (remainingTime > 0) {
+        await new Promise((resolve) => setTimeout(resolve, remainingTime));
+    }
+}
+/**
+ * Wraps an async operation with minimum processing time UX polish.
+ * Ensures successful operations take at least `minimumTime` milliseconds.
+ * Errors are thrown immediately without delay for better UX.
+ *
+ * @param operation - The async operation to perform
+ * @param minimumTime - Minimum time in milliseconds for UX polish on success
+ * @returns The result of the operation
+ */
+export async function withMinimumTime(operation, minimumTime) {
+    const startTime = Date.now();
+    try {
+        const result = await operation();
+        await ensureMinimumTime(startTime, minimumTime);
+        return result;
+    }
+    catch (error) {
+        // Don't wait on error - fail fast for better UX
+        throw error;
+    }
+}

package/dist/services/tool-registry.js

@@ -38,6 +38,7 @@ import { configTool } from '../tools/config.tool.js';
 import { executeTool } from '../tools/execute.tool.js';
 import { introspectTool } from '../tools/introspect.tool.js';
 import { planTool } from '../tools/plan.tool.js';
+import { validateTool } from '../tools/validate.tool.js';
 toolRegistry.register('plan', {
     schema: planTool,
     instructionsPath: 'config/PLAN.md',
@@ -58,3 +59,7 @@ toolRegistry.register('execute', {
     schema: executeTool,
     instructionsPath: 'config/EXECUTE.md',
 });
+toolRegistry.register('validate', {
+    schema: validateTool,
+    instructionsPath: 'config/VALIDATE.md',
+});

package/dist/tools/validate.tool.js

@@ -0,0 +1,43 @@
+export const validateTool = {
+    name: 'validate',
+    description: 'Validate skill requirements and generate natural language descriptions for missing configuration values. Given skill context and missing config paths, create CONFIG tasks with helpful, contextual descriptions.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            message: {
+                type: 'string',
+                description: 'Empty string or brief message (not shown to user, can be left empty)',
+            },
+            tasks: {
+                type: 'array',
+                description: 'Array of CONFIG tasks with natural language descriptions for missing config values',
+                items: {
+                    type: 'object',
+                    properties: {
+                        action: {
+                            type: 'string',
+                            description: 'Natural language description explaining what the config value is for, followed by the config path in curly brackets {config.path}. Example: "Path to Alpha project repository (legacy implementation) {project.alpha.repo}"',
+                        },
+                        type: {
+                            type: 'string',
+                            description: 'Must be "config" for all tasks returned by this tool',
+                        },
+                        params: {
+                            type: 'object',
+                            description: 'Must include key field with the config path',
+                            properties: {
+                                key: {
+                                    type: 'string',
+                                    description: 'The config path (e.g., "opera.gx.repo")',
+                                },
+                            },
+                            required: ['key'],
+                        },
+                    },
+                    required: ['action', 'type', 'params'],
+                },
+            },
+        },
+        required: ['message', 'tasks'],
+    },
+};

package/dist/types/skills.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the structured skill system
+ */
+export {};

package/dist/types/types.js

@@ -13,6 +13,7 @@ export var ComponentName;
     ComponentName["Answer"] = "answer";
     ComponentName["AnswerDisplay"] = "answerDisplay";
     ComponentName["Execute"] = "execute";
+    ComponentName["Validate"] = "validate";
 })(ComponentName || (ComponentName = {}));
 export var TaskType;
 (function (TaskType) {

package/dist/ui/Answer.js

@@ -4,6 +4,7 @@ import { Box, Text } from 'ink';
 import { Colors, getTextColor } from '../services/colors.js';
 import { useInput } from '../services/keyboard.js';
 import { formatErrorMessage } from '../services/messages.js';
+import { withMinimumTime } from '../services/timing.js';
 import { Spinner } from './Spinner.js';
 const MINIMUM_PROCESSING_TIME = 400;
 export function Answer({ question, state, service, onError, onComplete, onAborted, }) {
@@ -30,13 +31,9 @@ export function Answer({ question, state, service, onError, onComplete, onAborte
         }
         let mounted = true;
         async function process(svc) {
-            const startTime = Date.now();
             try {
-                // Call answer tool
-                const result = await svc.processWithTool(question, 'answer');
-                const elapsed = Date.now() - startTime;
-                const remainingTime = Math.max(0, MINIMUM_PROCESSING_TIME - elapsed);
-                await new Promise((resolve) => setTimeout(resolve, remainingTime));
+                // Call answer tool with minimum processing time for UX polish
+                const result = await withMinimumTime(() => svc.processWithTool(question, 'answer'), MINIMUM_PROCESSING_TIME);
                 if (mounted) {
                     // Extract answer from result
                     const answer = result.answer || '';
@@ -45,9 +42,6 @@ export function Answer({ question, state, service, onError, onComplete, onAborte
                 }
             }
             catch (err) {
-                const elapsed = Date.now() - startTime;
-                const remainingTime = Math.max(0, MINIMUM_PROCESSING_TIME - elapsed);
-                await new Promise((resolve) => setTimeout(resolve, remainingTime));
                 if (mounted) {
                     const errorMessage = formatErrorMessage(err);
                     setIsLoading(false);

package/dist/ui/Command.js

@@ -5,6 +5,7 @@ import { TaskType } from '../types/types.js';
 import { Colors } from '../services/colors.js';
 import { useInput } from '../services/keyboard.js';
 import { formatErrorMessage } from '../services/messages.js';
+import { ensureMinimumTime } from '../services/timing.js';
 import { Spinner } from './Spinner.js';
 const MIN_PROCESSING_TIME = 1000; // purely for visual effect
 export function Command({ command, state, service, children, onError, onComplete, onAborted, }) {
@@ -42,18 +43,14 @@ export function Command({ command, state, service, children, onError, onComplete
                     // Call CONFIG tool to get specific config keys
                     result = await svc.processWithTool(query, 'config');
                 }
-                const elapsed = Date.now() - startTime;
-                const remainingTime = Math.max(0, MIN_PROCESSING_TIME - elapsed);
-                await new Promise((resolve) => setTimeout(resolve, remainingTime));
+                await ensureMinimumTime(startTime, MIN_PROCESSING_TIME);
                 if (mounted) {
                     setIsLoading(false);
                     onComplete?.(result.message, result.tasks);
                 }
             }
             catch (err) {
-                const elapsed = Date.now() - startTime;
-                const remainingTime = Math.max(0, MIN_PROCESSING_TIME - elapsed);
-                await new Promise((resolve) => setTimeout(resolve, remainingTime));
+                await ensureMinimumTime(startTime, MIN_PROCESSING_TIME);
                 if (mounted) {
                     const errorMessage = formatErrorMessage(err);
                     setIsLoading(false);

package/dist/ui/Component.js

@@ -13,6 +13,7 @@ import { Message } from './Message.js';
 import { Plan } from './Plan.js';
 import { Refinement } from './Refinement.js';
 import { Report } from './Report.js';
+import { Validate } from './Validate.js';
 import { Welcome } from './Welcome.js';
 export const Component = React.memo(function Component({ def, debug, }) {
     switch (def.name) {
@@ -21,7 +22,7 @@ export const Component = React.memo(function Component({ def, debug, }) {
         case ComponentName.Config: {
             const props = def.props;
             const state = def.state;
-            return _jsx(Config, { ...props, state: state });
+            return _jsx(Config, { ...props, state: state, debug: debug });
         }
         case ComponentName.Command: {
             const props = def.props;
@@ -66,5 +67,10 @@ export const Component = React.memo(function Component({ def, debug, }) {
             const state = def.state;
             return _jsx(Execute, { ...props, state: state });
         }
+        case ComponentName.Validate: {
+            const props = def.props;
+            const state = def.state;
+            return _jsx(Validate, { ...props, state: state });
+        }
     }
 });

package/dist/ui/Config.js

@@ -57,7 +57,7 @@ function SelectionStep({ options, selectedIndex, isCurrentStep, }) {
             return (_jsx(Box, { marginRight: 2, children: _jsx(Text, { dimColor: !isSelected || !isCurrentStep, bold: isSelected, children: option.label }) }, option.value));
         }) }));
 }
-export function Config({ steps, state, onFinished, onAborted }) {
+export function Config({ steps, state, debug, onFinished, onAborted }) {
     const done = state?.done ?? false;
     const [step, setStep] = React.useState(done ? steps.length : 0);
     const [values, setValues] = React.useState(() => {
@@ -220,6 +220,6 @@ export function Config({ steps, state, onFinished, onAborted }) {
             if (!shouldShow) {
                 return null;
             }
-            return (_jsxs(Box, { flexDirection: "column", marginTop: index === 0 ? 0 : 1, children: [_jsx(Box, { children: _jsxs(Text, { children: [stepConfig.description, ":"] }) }), _jsxs(Box, { children: [_jsx(Text, { children: " " }), _jsx(Text, { color: Colors.Action.Select, dimColor: !isCurrentStep, children: ">" }), _jsx(Text, { children: " " }), renderStepInput(stepConfig, isCurrentStep)] })] }, stepConfig.key));
+            return (_jsxs(Box, { flexDirection: "column", marginTop: index === 0 ? 0 : 1, children: [_jsxs(Box, { children: [_jsx(Text, { children: stepConfig.description }), _jsx(Text, { children: ": " }), debug && stepConfig.path && (_jsxs(Text, { color: Colors.Type.Define, children: ['{', stepConfig.path, '}'] }))] }), _jsxs(Box, { children: [_jsx(Text, { children: " " }), _jsx(Text, { color: Colors.Action.Select, dimColor: !isCurrentStep, children: ">" }), _jsx(Text, { children: " " }), renderStepInput(stepConfig, isCurrentStep)] })] }, stepConfig.key));
         }) }));
 }