shortcutxl 0.2.0

package/dist/core/skills.js

@@ -0,0 +1,382 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'fs';
+import ignore from 'ignore';
+import { homedir } from 'os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
+import { CONFIG_DIR_NAME, getAgentDir } from '../config.js';
+import { parseFrontmatter } from '../utils/frontmatter.js';
+/** Max name length per spec */
+const MAX_NAME_LENGTH = 64;
+/** Max description length per spec */
+const MAX_DESCRIPTION_LENGTH = 1024;
+const IGNORE_FILE_NAMES = ['.gitignore', '.ignore', '.fdignore'];
+function toPosixPath(p) {
+    return p.split(sep).join('/');
+}
+function prefixIgnorePattern(line, prefix) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('#') && !trimmed.startsWith('\\#'))
+        return null;
+    let pattern = line;
+    let negated = false;
+    if (pattern.startsWith('!')) {
+        negated = true;
+        pattern = pattern.slice(1);
+    }
+    else if (pattern.startsWith('\\!')) {
+        pattern = pattern.slice(1);
+    }
+    if (pattern.startsWith('/')) {
+        pattern = pattern.slice(1);
+    }
+    const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+    return negated ? `!${prefixed}` : prefixed;
+}
+function addIgnoreRules(ig, dir, rootDir) {
+    const relativeDir = relative(rootDir, dir);
+    const prefix = relativeDir ? `${toPosixPath(relativeDir)}/` : '';
+    for (const filename of IGNORE_FILE_NAMES) {
+        const ignorePath = join(dir, filename);
+        if (!existsSync(ignorePath))
+            continue;
+        try {
+            const content = readFileSync(ignorePath, 'utf-8');
+            const patterns = content
+                .split(/\r?\n/)
+                .map((line) => prefixIgnorePattern(line, prefix))
+                .filter((line) => Boolean(line));
+            if (patterns.length > 0) {
+                ig.add(patterns);
+            }
+        }
+        catch { }
+    }
+}
+/**
+ * Parse a skill block from message text.
+ * Returns null if the text doesn't contain a skill block.
+ */
+export function parseSkillBlock(text) {
+    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+    if (!match)
+        return null;
+    return {
+        name: match[1],
+        location: match[2],
+        content: match[3],
+        userMessage: match[4]?.trim() || undefined
+    };
+}
+/**
+ * Validate skill name per Agent Skills spec.
+ * Returns array of validation error messages (empty if valid).
+ */
+function validateName(name, parentDirName) {
+    const errors = [];
+    if (name !== parentDirName) {
+        errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        errors.push(`name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)`);
+    }
+    if (name.startsWith('-') || name.endsWith('-')) {
+        errors.push(`name must not start or end with a hyphen`);
+    }
+    if (name.includes('--')) {
+        errors.push(`name must not contain consecutive hyphens`);
+    }
+    return errors;
+}
+/**
+ * Validate description per Agent Skills spec.
+ */
+function validateDescription(description) {
+    const errors = [];
+    if (!description || description.trim() === '') {
+        errors.push('description is required');
+    }
+    else if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+    }
+    return errors;
+}
+/**
+ * Load skills from a directory.
+ *
+ * Discovery rules:
+ * - direct .md children in the root
+ * - recursive SKILL.md under subdirectories
+ */
+export function loadSkillsFromDir(options) {
+    const { dir, source } = options;
+    return loadSkillsFromDirInternal(dir, source, true);
+}
+function loadSkillsFromDirInternal(dir, source, includeRootFiles, ignoreMatcher, rootDir) {
+    const skills = [];
+    const diagnostics = [];
+    if (!existsSync(dir)) {
+        return { skills, diagnostics };
+    }
+    const root = rootDir ?? dir;
+    const ig = ignoreMatcher ?? ignore();
+    addIgnoreRules(ig, dir, root);
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.')) {
+                continue;
+            }
+            // Skip node_modules to avoid scanning dependencies
+            if (entry.name === 'node_modules') {
+                continue;
+            }
+            const fullPath = join(dir, entry.name);
+            // For symlinks, check if they point to a directory and follow them
+            let isDirectory = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                try {
+                    const stats = statSync(fullPath);
+                    isDirectory = stats.isDirectory();
+                    isFile = stats.isFile();
+                }
+                catch {
+                    // Broken symlink, skip it
+                    continue;
+                }
+            }
+            const relPath = toPosixPath(relative(root, fullPath));
+            const ignorePath = isDirectory ? `${relPath}/` : relPath;
+            if (ig.ignores(ignorePath)) {
+                continue;
+            }
+            if (isDirectory) {
+                const subResult = loadSkillsFromDirInternal(fullPath, source, false, ig, root);
+                skills.push(...subResult.skills);
+                diagnostics.push(...subResult.diagnostics);
+                continue;
+            }
+            if (!isFile) {
+                continue;
+            }
+            const isRootMd = includeRootFiles && entry.name.endsWith('.md');
+            const isSkillMd = !includeRootFiles && entry.name === 'SKILL.md';
+            if (!isRootMd && !isSkillMd) {
+                continue;
+            }
+            const result = loadSkillFromFile(fullPath, source);
+            if (result.skill) {
+                skills.push(result.skill);
+            }
+            diagnostics.push(...result.diagnostics);
+        }
+    }
+    catch { }
+    return { skills, diagnostics };
+}
+function loadSkillFromFile(filePath, source) {
+    const diagnostics = [];
+    try {
+        const rawContent = readFileSync(filePath, 'utf-8');
+        const { frontmatter } = parseFrontmatter(rawContent);
+        const skillDir = dirname(filePath);
+        const parentDirName = basename(skillDir);
+        // Validate description
+        const descErrors = validateDescription(frontmatter.description);
+        for (const error of descErrors) {
+            diagnostics.push({ type: 'warning', message: error, path: filePath });
+        }
+        // Use name from frontmatter, or fall back to parent directory name
+        const name = frontmatter.name || parentDirName;
+        // Validate name
+        const nameErrors = validateName(name, parentDirName);
+        for (const error of nameErrors) {
+            diagnostics.push({ type: 'warning', message: error, path: filePath });
+        }
+        // Still load the skill even with warnings (unless description is completely missing)
+        if (!frontmatter.description || frontmatter.description.trim() === '') {
+            return { skill: null, diagnostics };
+        }
+        return {
+            skill: {
+                name,
+                description: frontmatter.description,
+                filePath,
+                baseDir: skillDir,
+                source,
+                disableModelInvocation: frontmatter['disable-model-invocation'] === true
+            },
+            diagnostics
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'failed to parse skill file';
+        diagnostics.push({ type: 'warning', message, path: filePath });
+        return { skill: null, diagnostics };
+    }
+}
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt
+ * (they can only be invoked explicitly via /skill:name commands).
+ */
+export function formatSkillsForPrompt(skills) {
+    const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
+    if (visibleSkills.length === 0) {
+        return '';
+    }
+    const lines = [
+        '\n\nThe following skills provide specialized instructions for specific tasks.',
+        "Use the read tool to load a skill's file when the task matches its description.",
+        'When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.',
+        ''
+    ];
+    for (const skill of visibleSkills) {
+        lines.push(`${skill.name}: ${skill.description}`);
+        lines.push(`\t${skill.filePath}`);
+    }
+    return lines.join('\n');
+}
+function _escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function normalizePath(input) {
+    const trimmed = input.trim();
+    if (trimmed === '~')
+        return homedir();
+    if (trimmed.startsWith('~/'))
+        return join(homedir(), trimmed.slice(2));
+    if (trimmed.startsWith('~'))
+        return join(homedir(), trimmed.slice(1));
+    return trimmed;
+}
+function resolveSkillPath(p, cwd) {
+    const normalized = normalizePath(p);
+    return isAbsolute(normalized) ? normalized : resolve(cwd, normalized);
+}
+/**
+ * Load skills from all configured locations.
+ * Returns skills and any validation diagnostics.
+ */
+export function loadSkills(options = {}) {
+    const { cwd = process.cwd(), agentDir, skillPaths = [], includeDefaults = true } = options;
+    // Resolve agentDir - if not provided, use default from config
+    const resolvedAgentDir = agentDir ?? getAgentDir();
+    const skillMap = new Map();
+    const realPathSet = new Set();
+    const allDiagnostics = [];
+    const collisionDiagnostics = [];
+    function addSkills(result) {
+        allDiagnostics.push(...result.diagnostics);
+        for (const skill of result.skills) {
+            // Resolve symlinks to detect duplicate files
+            let realPath;
+            try {
+                realPath = realpathSync(skill.filePath);
+            }
+            catch {
+                realPath = skill.filePath;
+            }
+            // Skip silently if we've already loaded this exact file (via symlink)
+            if (realPathSet.has(realPath)) {
+                continue;
+            }
+            const existing = skillMap.get(skill.name);
+            if (existing) {
+                collisionDiagnostics.push({
+                    type: 'collision',
+                    message: `name "${skill.name}" collision`,
+                    path: skill.filePath,
+                    collision: {
+                        resourceType: 'skill',
+                        name: skill.name,
+                        winnerPath: existing.filePath,
+                        loserPath: skill.filePath
+                    }
+                });
+            }
+            else {
+                skillMap.set(skill.name, skill);
+                realPathSet.add(realPath);
+            }
+        }
+    }
+    if (includeDefaults) {
+        addSkills(loadSkillsFromDirInternal(join(resolvedAgentDir, 'skills'), 'user', true));
+        addSkills(loadSkillsFromDirInternal(resolve(cwd, CONFIG_DIR_NAME, 'skills'), 'project', true));
+    }
+    const userSkillsDir = join(resolvedAgentDir, 'skills');
+    const projectSkillsDir = resolve(cwd, CONFIG_DIR_NAME, 'skills');
+    const isUnderPath = (target, root) => {
+        const normalizedRoot = resolve(root);
+        if (target === normalizedRoot) {
+            return true;
+        }
+        const prefix = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
+        return target.startsWith(prefix);
+    };
+    const getSource = (resolvedPath) => {
+        if (!includeDefaults) {
+            if (isUnderPath(resolvedPath, userSkillsDir))
+                return 'user';
+            if (isUnderPath(resolvedPath, projectSkillsDir))
+                return 'project';
+        }
+        return 'path';
+    };
+    for (const rawPath of skillPaths) {
+        const resolvedPath = resolveSkillPath(rawPath, cwd);
+        if (!existsSync(resolvedPath)) {
+            allDiagnostics.push({
+                type: 'warning',
+                message: 'skill path does not exist',
+                path: resolvedPath
+            });
+            continue;
+        }
+        try {
+            const stats = statSync(resolvedPath);
+            const source = getSource(resolvedPath);
+            if (stats.isDirectory()) {
+                addSkills(loadSkillsFromDirInternal(resolvedPath, source, true));
+            }
+            else if (stats.isFile() && resolvedPath.endsWith('.md')) {
+                const result = loadSkillFromFile(resolvedPath, source);
+                if (result.skill) {
+                    addSkills({ skills: [result.skill], diagnostics: result.diagnostics });
+                }
+                else {
+                    allDiagnostics.push(...result.diagnostics);
+                }
+            }
+            else {
+                allDiagnostics.push({
+                    type: 'warning',
+                    message: 'skill path is not a markdown file',
+                    path: resolvedPath
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'failed to read skill path';
+            allDiagnostics.push({ type: 'warning', message, path: resolvedPath });
+        }
+    }
+    return {
+        skills: Array.from(skillMap.values()),
+        diagnostics: [...allDiagnostics, ...collisionDiagnostics]
+    };
+}
+//# sourceMappingURL=skills.js.map

package/dist/core/slash-commands.js

@@ -0,0 +1,31 @@
+const ALL_BUILTIN_SLASH_COMMANDS = [
+    // Auth
+    { name: 'login', description: 'Login with OAuth provider' },
+    { name: 'logout', description: 'Logout from OAuth provider' },
+    // Session
+    { name: 'clear', description: 'Start a new session' },
+    { name: 'quit', description: 'Quit' },
+    // Model
+    { name: 'model', description: 'Select model' },
+    { name: 'thinking', description: 'Select thinking level' },
+    { name: 'hide-thinking', description: 'Toggle visibility of thinking blocks' },
+    // Checkpointing
+    { name: 'resume', description: 'Resume a different session' },
+    { name: 'tree', description: 'Navigate session tree (go back to previous messages)' },
+    { name: 'session', description: 'Show session info and stats' },
+    // Everything else
+    { name: 'settings', description: 'Open settings menu' },
+    { name: 'trace', description: 'Open session traces in browser' },
+    { name: 'hotkeys', description: 'Show all keyboard shortcuts' },
+    { name: 'skills', description: 'Show loaded skills' },
+    { name: 'reload', description: 'Reload extensions, skills, prompts, and themes' }
+];
+/** Dev-only slash commands, consumed by custom/dev/ to keep env checks out of vendor code. */
+export const ALL_DEV_SLASH_COMMANDS = ALL_BUILTIN_SLASH_COMMANDS.filter((cmd) => cmd.dev);
+/** All builtin command names (including dev), used to prevent extension collisions. */
+export const ALL_BUILTIN_SLASH_COMMAND_NAMES = new Set(ALL_BUILTIN_SLASH_COMMANDS.map((cmd) => cmd.name));
+/** Returns the base (non-dev) slash commands. Dev commands are added via custom/dev/. */
+export function getBuiltinSlashCommands() {
+    return ALL_BUILTIN_SLASH_COMMANDS.filter((cmd) => !cmd.dev);
+}
+//# sourceMappingURL=slash-commands.js.map

package/dist/core/system-prompt.js

@@ -0,0 +1,161 @@
+/**
+ * System prompt construction and project context loading
+ */
+import { getDocsPath, getExamplesPath, getReadmePath } from '../config.js';
+import { BASH, EDIT, FIND, GREP, LS, READ, WRITE } from '../tool-names.js';
+import { formatSkillsForPrompt } from './skills.js';
+/** Tool descriptions for system prompt */
+const toolDescriptions = {
+    [READ]: 'Read file contents',
+    [BASH]: 'Execute bash commands (ls, grep, find, etc.)',
+    [EDIT]: 'Make surgical edits to files (find exact text and replace)',
+    [WRITE]: 'Create or overwrite files',
+    [GREP]: 'Search file contents for patterns (respects .gitignore)',
+    [FIND]: 'Find files by glob pattern (respects .gitignore)',
+    [LS]: 'List directory contents'
+};
+/** Build the system prompt with tools, guidelines, and context */
+export function buildSystemPrompt(options = {}) {
+    const { customPrompt, selectedTools, toolSnippets, promptGuidelines, appendSystemPrompt, cwd, contextFiles: providedContextFiles, skills: providedSkills } = options;
+    const resolvedCwd = cwd ?? process.cwd();
+    const now = new Date();
+    const dateTime = now.toLocaleString('en-US', {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short'
+    });
+    const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : '';
+    const contextFiles = providedContextFiles ?? [];
+    const skills = providedSkills ?? [];
+    if (customPrompt) {
+        let prompt = customPrompt;
+        if (appendSection) {
+            prompt += appendSection;
+        }
+        // Append project context files
+        if (contextFiles.length > 0) {
+            prompt += '\n\n# Project Context\n\n';
+            prompt += 'Project-specific instructions and guidelines:\n\n';
+            for (const { path: filePath, content } of contextFiles) {
+                prompt += `## ${filePath}\n\n${content}\n\n`;
+            }
+        }
+        // Append skills section (only if read tool is available)
+        const customPromptHasRead = !selectedTools || selectedTools.includes(READ);
+        if (customPromptHasRead && skills.length > 0) {
+            prompt += formatSkillsForPrompt(skills);
+        }
+        // Add date/time and working directory last
+        prompt += `\nCurrent date and time: ${dateTime}`;
+        prompt += `\nCurrent working directory: ${resolvedCwd}`;
+        return prompt;
+    }
+    // Get absolute paths to documentation and examples
+    const readmePath = getReadmePath();
+    const docsPath = getDocsPath();
+    const examplesPath = getExamplesPath();
+    // Build tools list based on selected tools.
+    // Built-ins use toolDescriptions. Custom tools can provide one-line snippets.
+    // SHORTCUT PATCH: no default tools — empty if none specified
+    const tools = selectedTools || [];
+    const toolsList = tools.length > 0
+        ? tools
+            .map((name) => {
+            const snippet = toolSnippets?.[name] ?? toolDescriptions[name] ?? name;
+            return `- ${name}: ${snippet}`;
+        })
+            .join('\n')
+        : '(none)';
+    // Build guidelines based on which tools are actually available
+    const guidelinesList = [];
+    const guidelinesSet = new Set();
+    const addGuideline = (guideline) => {
+        if (guidelinesSet.has(guideline)) {
+            return;
+        }
+        guidelinesSet.add(guideline);
+        guidelinesList.push(guideline);
+    };
+    const hasBash = tools.includes(BASH);
+    const hasEdit = tools.includes(EDIT);
+    const hasWrite = tools.includes(WRITE);
+    const hasGrep = tools.includes(GREP);
+    const hasFind = tools.includes(FIND);
+    const hasLs = tools.includes(LS);
+    const hasRead = tools.includes(READ);
+    // File exploration guidelines
+    if (hasBash && !hasGrep && !hasFind && !hasLs) {
+        addGuideline('Use bash for file operations like ls, rg, find');
+    }
+    else if (hasBash && (hasGrep || hasFind || hasLs)) {
+        addGuideline('Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)');
+    }
+    // Read before edit guideline
+    if (hasRead && hasEdit) {
+        addGuideline('Use read to examine files before editing. You must use this tool instead of cat or sed.');
+    }
+    // Edit guideline
+    if (hasEdit) {
+        addGuideline('Use edit for precise changes (old text must match exactly)');
+    }
+    // Write guideline
+    if (hasWrite) {
+        addGuideline('Use write only for new files or complete rewrites');
+    }
+    // Output guideline (only when actually writing or executing)
+    if (hasEdit || hasWrite) {
+        addGuideline('When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did');
+    }
+    for (const guideline of promptGuidelines ?? []) {
+        const normalized = guideline.trim();
+        if (normalized.length > 0) {
+            addGuideline(normalized);
+        }
+    }
+    // Always include these
+    addGuideline('Be concise in your responses');
+    addGuideline('Show file paths clearly when working with files');
+    const guidelines = guidelinesList.map((g) => `- ${g}`).join('\n');
+    let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+${toolsList}
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+${guidelines}
+
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+- Main documentation: ${readmePath}
+- Additional docs: ${docsPath}
+- Examples: ${examplesPath} (extensions, custom tools, SDK)
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
+- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
+- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+    if (appendSection) {
+        prompt += appendSection;
+    }
+    // Append project context files
+    if (contextFiles.length > 0) {
+        prompt += '\n\n# Project Context\n\n';
+        prompt += 'Project-specific instructions and guidelines:\n\n';
+        for (const { path: filePath, content } of contextFiles) {
+            prompt += `## ${filePath}\n\n${content}\n\n`;
+        }
+    }
+    // Append skills section (only if read tool is available)
+    if (hasRead && skills.length > 0) {
+        prompt += formatSkillsForPrompt(skills);
+    }
+    // Add date/time and working directory last
+    prompt += `\nCurrent date and time: ${dateTime}`;
+    prompt += `\nCurrent working directory: ${resolvedCwd}`;
+    return prompt;
+}
+//# sourceMappingURL=system-prompt.js.map