tarsk 0.3.43 → 0.4.4

package/dist/features/skills/skills.manager.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Skill Manager
+ *
+ * Loads and manages agent skills from SKILL.md files with frontmatter.
+ * Skills can be stored in:
+ * - Project-specific: ./.agents/skills/ (relative to thread path)
+ * - Global: ~/.agents/skills/
+ *
+ * Skills follow the Agent Skills format specification:
+ * https://agentskills.io/
+ */
+import type { Skill } from "@tarsk/shared";
+/**
+ * SkillManager handles loading and validating agent skills
+ */
+export declare class SkillManager {
+    /**
+     * Load all available skills for a given thread
+     * Project skills override global ones with the same name
+     */
+    loadSkills(threadPath: string): Promise<Skill[]>;
+    /**
+     * Load skills from a specific directory
+     */
+    private loadSkillsFromDir;
+    /**
+     * Get a specific skill by name
+     */
+    getSkill(name: string, threadPath: string): Promise<Skill | null>;
+    /**
+     * Validate skill name format (public utility method)
+     */
+    validateSkillName(name: string): boolean;
+}
+//# sourceMappingURL=skills.manager.d.ts.map

package/dist/features/skills/skills.manager.js

@@ -0,0 +1,251 @@
+/**
+ * Skill Manager
+ *
+ * Loads and manages agent skills from SKILL.md files with frontmatter.
+ * Skills can be stored in:
+ * - Project-specific: ./.agents/skills/ (relative to thread path)
+ * - Global: ~/.agents/skills/
+ *
+ * Skills follow the Agent Skills format specification:
+ * https://agentskills.io/
+ */
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+import { existsSync } from "fs";
+import { homedir } from "os";
+/**
+ * Parse frontmatter from SKILL.md content
+ * Returns { metadata, content } where content is the body after frontmatter
+ */
+function parseFrontmatter(markdown) {
+    const lines = markdown.split("\n");
+    // Check if file starts with ---
+    if (lines[0]?.trim() !== "---") {
+        return {
+            metadata: {},
+            content: markdown.trim(),
+        };
+    }
+    // Find the closing ---
+    let endIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === "---") {
+            endIndex = i;
+            break;
+        }
+    }
+    // No closing --- found
+    if (endIndex === -1) {
+        return {
+            metadata: {},
+            content: markdown.trim(),
+        };
+    }
+    // Parse frontmatter
+    const frontmatterLines = lines.slice(1, endIndex);
+    const metadata = {};
+    for (const line of frontmatterLines) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim();
+        const value = line.slice(colonIndex + 1).trim();
+        // Map YAML keys to TypeScript property names
+        if (key === "name") {
+            metadata.name = value;
+        }
+        else if (key === "description") {
+            metadata.description = value;
+        }
+        else if (key === "license") {
+            metadata.license = value;
+        }
+        else if (key === "compatibility") {
+            metadata.compatibility = value;
+        }
+        else if (key === "allowed-tools") {
+            metadata.allowedTools = value;
+        }
+        else if (key === "metadata") {
+            // Parse metadata object (simple key:value pairs)
+            // For now, we'll skip nested metadata parsing
+            // This would require a proper YAML parser for full support
+        }
+    }
+    // Content is everything after the closing ---
+    const content = lines
+        .slice(endIndex + 1)
+        .join("\n")
+        .trim();
+    return { metadata, content };
+}
+/**
+ * Get the global skills directory path
+ */
+function getGlobalSkillsDir() {
+    return join(homedir(), ".agents", "skills");
+}
+/**
+ * Get the project-specific skills directory path
+ */
+function getProjectSkillsDir(threadPath) {
+    return join(threadPath, ".agents", "skills");
+}
+/**
+ * Validate skill name format
+ * - Must be 1-64 characters
+ * - Lowercase alphanumeric and hyphens only
+ * - Must not start or end with hyphen
+ * - Must not contain consecutive hyphens
+ */
+function validateSkillName(name) {
+    if (!name || name.length === 0 || name.length > 64) {
+        return false;
+    }
+    // Check for valid characters (lowercase alphanumeric + hyphens)
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        return false;
+    }
+    // Must not start or end with hyphen
+    if (name.startsWith("-") || name.endsWith("-")) {
+        return false;
+    }
+    // Must not contain consecutive hyphens
+    if (name.includes("--")) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Validate skill description
+ * - Must be 1-1024 characters
+ * - Must be non-empty
+ */
+function validateDescription(description) {
+    return !!description && description.length > 0 && description.length <= 1024;
+}
+/**
+ * SkillManager handles loading and validating agent skills
+ */
+export class SkillManager {
+    /**
+     * Load all available skills for a given thread
+     * Project skills override global ones with the same name
+     */
+    async loadSkills(threadPath) {
+        const skills = new Map();
+        // Load global skills first
+        const globalDir = getGlobalSkillsDir();
+        if (existsSync(globalDir)) {
+            const globalSkills = await this.loadSkillsFromDir(globalDir, "global");
+            for (const skill of globalSkills) {
+                skills.set(skill.name, skill);
+            }
+        }
+        // Load project skills (override global)
+        const projectDir = getProjectSkillsDir(threadPath);
+        if (existsSync(projectDir)) {
+            const projectSkills = await this.loadSkillsFromDir(projectDir, "project");
+            for (const skill of projectSkills) {
+                skills.set(skill.name, skill);
+            }
+        }
+        return Array.from(skills.values());
+    }
+    /**
+     * Load skills from a specific directory
+     */
+    async loadSkillsFromDir(dir, scope) {
+        const skills = [];
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                // Skills must be directories
+                if (!entry.isDirectory())
+                    continue;
+                const skillDirName = entry.name;
+                const skillPath = join(dir, skillDirName);
+                const skillFilePath = join(skillPath, "SKILL.md");
+                // Skip if SKILL.md doesn't exist
+                if (!existsSync(skillFilePath)) {
+                    console.warn(`Skipping skill directory ${skillDirName}: SKILL.md not found`);
+                    continue;
+                }
+                try {
+                    // Read and parse SKILL.md
+                    const fileContent = await readFile(skillFilePath, "utf-8");
+                    const { metadata, content } = parseFrontmatter(fileContent);
+                    // Validate required fields
+                    if (!metadata.name) {
+                        console.warn(`Skipping skill in ${skillDirName}: missing 'name' in frontmatter`);
+                        continue;
+                    }
+                    if (!metadata.description) {
+                        console.warn(`Skipping skill in ${skillDirName}: missing 'description' in frontmatter`);
+                        continue;
+                    }
+                    // Validate name format
+                    if (!validateSkillName(metadata.name)) {
+                        console.warn(`Skipping skill in ${skillDirName}: invalid name format '${metadata.name}'. ` +
+                            `Name must be 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens.`);
+                        continue;
+                    }
+                    // Validate description length
+                    if (!validateDescription(metadata.description)) {
+                        console.warn(`Skipping skill in ${skillDirName}: description must be 1-1024 characters`);
+                        continue;
+                    }
+                    // Validate that directory name matches frontmatter name
+                    if (metadata.name !== skillDirName) {
+                        console.warn(`Skipping skill in ${skillDirName}: directory name must match frontmatter name '${metadata.name}'`);
+                        continue;
+                    }
+                    // Create skill object
+                    const skill = {
+                        name: metadata.name,
+                        description: metadata.description,
+                        scope,
+                        skillPath,
+                        instructions: content,
+                    };
+                    // Add optional fields if present
+                    if (metadata.license) {
+                        skill.license = metadata.license;
+                    }
+                    if (metadata.compatibility) {
+                        skill.compatibility = metadata.compatibility;
+                    }
+                    if (metadata.metadata) {
+                        skill.metadata = metadata.metadata;
+                    }
+                    if (metadata.allowedTools) {
+                        skill.allowedTools = metadata.allowedTools;
+                    }
+                    skills.push(skill);
+                }
+                catch (error) {
+                    console.error(`Failed to load skill from ${skillDirName}:`, error);
+                }
+            }
+        }
+        catch (error) {
+            // Directory doesn't exist or can't be read - that's okay
+            console.error(`Failed to load skills from ${dir}:`, error);
+        }
+        return skills;
+    }
+    /**
+     * Get a specific skill by name
+     */
+    async getSkill(name, threadPath) {
+        const skills = await this.loadSkills(threadPath);
+        return skills.find((skill) => skill.name === name) ?? null;
+    }
+    /**
+     * Validate skill name format (public utility method)
+     */
+    validateSkillName(name) {
+        return validateSkillName(name);
+    }
+}
+//# sourceMappingURL=skills.manager.js.map

package/dist/features/slash-commands/slash-commands-delete.route.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DELETE /api/slash-commands
+ * Delete a slash command
+ * Body: { filePath }
+ */
+import type { Context } from "hono";
+export declare function deleteSlashCommand(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        timestamp: string;
+    };
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    success: true;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details: import("hono/utils/types").JSONValue;
+        timestamp: string;
+    };
+}, 500, "json">)>;
+//# sourceMappingURL=slash-commands-delete.route.d.ts.map

package/dist/features/slash-commands/slash-commands-delete.route.js

@@ -0,0 +1,36 @@
+/**
+ * DELETE /api/slash-commands
+ * Delete a slash command
+ * Body: { filePath }
+ */
+import { SlashCommandManager } from "../slash-commands/slash-commands.manager.js";
+const slashCommandManager = new SlashCommandManager();
+export async function deleteSlashCommand(c) {
+    try {
+        const body = await c.req.json();
+        const { filePath } = body;
+        if (!filePath) {
+            return c.json({
+                error: {
+                    code: "MISSING_FILE_PATH",
+                    message: "filePath is required",
+                    timestamp: new Date().toISOString(),
+                },
+            }, 400);
+        }
+        await slashCommandManager.deleteCommand(filePath);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        console.error("Failed to delete slash command:", error);
+        return c.json({
+            error: {
+                code: "DELETE_FAILED",
+                message: error instanceof Error ? error.message : "Failed to delete slash command",
+                details: error,
+                timestamp: new Date().toISOString(),
+            },
+        }, 500);
+    }
+}
+//# sourceMappingURL=slash-commands-delete.route.js.map

package/dist/features/slash-commands/slash-commands-get.route.d.ts

@@ -0,0 +1,53 @@
+/**
+ * GET /api/slash-commands?threadId=xxx
+ * List all available slash commands for a thread
+ */
+import type { Context } from "hono";
+import type { ThreadManager } from "../threads/threads.manager.js";
+export declare function getSlashCommands(c: Context, threadManager: ThreadManager): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        timestamp: string;
+    };
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        timestamp: string;
+    };
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    commands: {
+        name: string;
+        content: string;
+        metadata: {
+            description?: string | undefined;
+            argumentHint?: string | undefined;
+            mode?: string | undefined;
+        };
+        scope: "project" | "global";
+        filePath: string;
+        isBuiltIn?: boolean | undefined;
+    }[];
+    skills?: {
+        name: string;
+        description: string;
+        scope: "project" | "global";
+        skillPath: string;
+        license?: string | undefined;
+        compatibility?: string | undefined;
+        metadata?: {
+            [x: string]: string;
+        } | undefined;
+        allowedTools?: string | undefined;
+        instructions: string;
+    }[] | undefined;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details: import("hono/utils/types").JSONValue;
+        timestamp: string;
+    };
+}, 500, "json">)>;
+//# sourceMappingURL=slash-commands-get.route.d.ts.map

package/dist/features/slash-commands/slash-commands-get.route.js

@@ -0,0 +1,54 @@
+/**
+ * GET /api/slash-commands?threadId=xxx
+ * List all available slash commands for a thread
+ */
+import { SlashCommandManager } from "../slash-commands/slash-commands.manager.js";
+import { SkillManager } from "../skills/skills.manager.js";
+const slashCommandManager = new SlashCommandManager();
+const skillManager = new SkillManager();
+export async function getSlashCommands(c, threadManager) {
+    const threadId = c.req.query("threadId");
+    if (!threadId) {
+        return c.json({
+            error: {
+                code: "MISSING_THREAD_ID",
+                message: "threadId query parameter is required",
+                timestamp: new Date().toISOString(),
+            },
+        }, 400);
+    }
+    try {
+        // Get thread path from thread manager
+        const thread = await threadManager.getThread(threadId);
+        if (!thread) {
+            return c.json({
+                error: {
+                    code: "THREAD_NOT_FOUND",
+                    message: `Thread not found: ${threadId}`,
+                    timestamp: new Date().toISOString(),
+                },
+            }, 404);
+        }
+        // Load commands for this thread
+        const commands = await slashCommandManager.loadCommands(thread.path);
+        // Load skills for this thread (for quick reference in command menu)
+        const skills = await skillManager.loadSkills(thread.path);
+        const response = {
+            commands,
+            skills,
+        };
+        return c.json(response);
+    }
+    catch (error) {
+        console.error("Failed to load slash commands:", error);
+        return c.json({
+            error: {
+                code: "LOAD_FAILED",
+                message: error instanceof Error ? error.message : "Failed to load slash commands",
+                details: error,
+                timestamp: new Date().toISOString(),
+            },
+        }, 500);
+    }
+}
+//# sourceMappingURL=slash-commands-get.route.js.map

package/dist/features/slash-commands/slash-commands-post.route.d.ts

@@ -0,0 +1,39 @@
+/**
+ * POST /api/slash-commands
+ * Create a new slash command
+ * Body: { name, content?, metadata, scope, threadId? }
+ */
+import type { Context } from "hono";
+import type { ThreadManager } from "../threads/threads.manager.js";
+export declare function createSlashCommand(c: Context, threadManager: ThreadManager): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        timestamp: string;
+    };
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        timestamp: string;
+    };
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    name: string;
+    content: string;
+    metadata: {
+        description?: string | undefined;
+        argumentHint?: string | undefined;
+        mode?: string | undefined;
+    };
+    scope: "project" | "global";
+    filePath: string;
+    isBuiltIn?: boolean | undefined;
+}, 201, "json">) | (Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details: import("hono/utils/types").JSONValue;
+        timestamp: string;
+    };
+}, 500, "json">)>;
+//# sourceMappingURL=slash-commands-post.route.d.ts.map

package/dist/features/slash-commands/slash-commands-post.route.js

@@ -0,0 +1,70 @@
+/**
+ * POST /api/slash-commands
+ * Create a new slash command
+ * Body: { name, content?, metadata, scope, threadId? }
+ */
+import { SlashCommandManager } from "../slash-commands/slash-commands.manager.js";
+const slashCommandManager = new SlashCommandManager();
+export async function createSlashCommand(c, threadManager) {
+    try {
+        const body = await c.req.json();
+        const { name, content, metadata, scope, threadId } = body;
+        if (!name) {
+            return c.json({
+                error: {
+                    code: "MISSING_FIELDS",
+                    message: "name is required",
+                    timestamp: new Date().toISOString(),
+                },
+            }, 400);
+        }
+        if (scope !== "global" && scope !== "project") {
+            return c.json({
+                error: {
+                    code: "INVALID_SCOPE",
+                    message: 'scope must be either "global" or "project"',
+                    timestamp: new Date().toISOString(),
+                },
+            }, 400);
+        }
+        // Get thread path if project scope
+        let threadPath;
+        if (scope === "project") {
+            if (!threadId) {
+                return c.json({
+                    error: {
+                        code: "MISSING_THREAD_ID",
+                        message: "threadId is required for project-scoped commands",
+                        timestamp: new Date().toISOString(),
+                    },
+                }, 400);
+            }
+            const thread = await threadManager.getThread(threadId);
+            if (!thread) {
+                return c.json({
+                    error: {
+                        code: "THREAD_NOT_FOUND",
+                        message: `Thread not found: ${threadId}`,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, 404);
+            }
+            threadPath = thread.path;
+        }
+        // Create command
+        const command = await slashCommandManager.createCommand(name, content, metadata ?? {}, scope, threadPath);
+        return c.json(command, 201);
+    }
+    catch (error) {
+        console.error("Failed to create slash command:", error);
+        return c.json({
+            error: {
+                code: "CREATE_FAILED",
+                message: error instanceof Error ? error.message : "Failed to create slash command",
+                details: error,
+                timestamp: new Date().toISOString(),
+            },
+        }, 500);
+    }
+}
+//# sourceMappingURL=slash-commands-post.route.js.map

package/dist/features/slash-commands/slash-commands-put.route.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PUT /api/slash-commands
+ * Update an existing slash command
+ * Body: { filePath, content, metadata }
+ */
+import type { Context } from "hono";
+export declare function updateSlashCommand(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        timestamp: string;
+    };
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    success: true;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details: import("hono/utils/types").JSONValue;
+        timestamp: string;
+    };
+}, 500, "json">)>;
+//# sourceMappingURL=slash-commands-put.route.d.ts.map

package/dist/features/slash-commands/slash-commands-put.route.js

@@ -0,0 +1,36 @@
+/**
+ * PUT /api/slash-commands
+ * Update an existing slash command
+ * Body: { filePath, content, metadata }
+ */
+import { SlashCommandManager } from "../slash-commands/slash-commands.manager.js";
+const slashCommandManager = new SlashCommandManager();
+export async function updateSlashCommand(c) {
+    try {
+        const body = await c.req.json();
+        const { filePath, content, metadata } = body;
+        if (!filePath || !content) {
+            return c.json({
+                error: {
+                    code: "MISSING_FIELDS",
+                    message: "filePath and content are required",
+                    timestamp: new Date().toISOString(),
+                },
+            }, 400);
+        }
+        await slashCommandManager.updateCommand(filePath, content, metadata ?? {});
+        return c.json({ success: true });
+    }
+    catch (error) {
+        console.error("Failed to update slash command:", error);
+        return c.json({
+            error: {
+                code: "UPDATE_FAILED",
+                message: error instanceof Error ? error.message : "Failed to update slash command",
+                details: error,
+                timestamp: new Date().toISOString(),
+            },
+        }, 500);
+    }
+}
+//# sourceMappingURL=slash-commands-put.route.js.map

package/dist/features/slash-commands/slash-commands.manager.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Slash Command Manager
+ *
+ * Loads and manages slash commands from markdown files with frontmatter.
+ * Commands can be stored in:
+ * - Project-specific: ./.agents/commands/ (relative to thread path)
+ * - Global: ~/.agents/commands/
+ */
+import type { SlashCommand, SlashCommandMetadata } from "@tarsk/shared";
+/**
+ * SlashCommandManager handles loading, creating, and managing slash commands
+ */
+export declare class SlashCommandManager {
+    /**
+     * Built-in commands that cannot be overridden
+     */
+    private static BUILT_IN_COMMANDS;
+    /**
+     * Load all available commands for a given thread
+     * Project commands override global ones with the same name
+     * Built-in commands cannot be overridden
+     */
+    loadCommands(threadPath: string): Promise<SlashCommand[]>;
+    /**
+     * Load commands from a specific directory
+     */
+    private loadCommandsFromDir;
+    /**
+     * Create a new command
+     * Creates the directory if it doesn't exist
+     */
+    createCommand(name: string, content: string, metadata: SlashCommandMetadata, scope: "global" | "project", threadPath?: string): Promise<SlashCommand>;
+    /**
+     * Update an existing command
+     */
+    updateCommand(filePath: string, content: string, metadata: SlashCommandMetadata): Promise<void>;
+    /**
+     * Delete a command
+     */
+    deleteCommand(filePath: string): Promise<void>;
+    /**
+     * Get a specific command by name
+     */
+    getCommand(name: string, threadPath: string): Promise<SlashCommand | null>;
+}
+//# sourceMappingURL=slash-commands.manager.d.ts.map