tarsk 0.3.43 → 0.4.4

package/dist/features/projects/projects-ai-files.route.js

@@ -0,0 +1,425 @@
+/**
+ * AI Files routes for the REST API
+ *
+ * Handles listing and editing AI-related files in a project:
+ * - GET /api/projects/:id/ai-files - List AI file tree (skills, rules, commands, markdown files)
+ * - GET /api/projects/:id/ai-file?path=... - Read file content
+ * - PUT /api/projects/:id/ai-file - Write file content
+ * - DELETE /api/projects/:id/ai-file?path=... - Delete file or folder
+ * - POST /api/projects/:id/ai-files/skill - Create a new skill
+ */
+import { readdir, readFile, writeFile, mkdir, access, rm } from "fs/promises";
+import { join, extname, basename } from "path";
+import { existsSync } from "fs";
+import { errorResponse } from "../../core/route-helpers.js";
+import { ErrorCodes } from "../../core/error-responses.js";
+const IGNORED_DIRS = new Set([
+    ".git",
+    "node_modules",
+    ".tarsk",
+    "dist",
+    "build",
+    ".next",
+    "__pycache__",
+    ".venv",
+    "venv",
+]);
+const MARKDOWN_EXTS = new Set([".md", ".mdc"]);
+/**
+ * Recursively build a full file tree for a directory (all files).
+ * Used for .agents/ subfolders.
+ */
+async function buildFullTree(dirPath, relativeDirPath) {
+    const nodes = [];
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryRelPath = join(relativeDirPath, entry.name);
+            const entryAbsPath = join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                const children = await buildFullTree(entryAbsPath, entryRelPath);
+                nodes.push({
+                    id: entryRelPath,
+                    name: entry.name,
+                    type: "folder",
+                    path: entryRelPath,
+                    children,
+                });
+            }
+            else if (entry.isFile()) {
+                nodes.push({
+                    id: entryRelPath,
+                    name: entry.name,
+                    type: "file",
+                    path: entryRelPath,
+                });
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read
+    }
+    return nodes;
+}
+/**
+ * Recursively find folders that contain markdown files, building a filtered tree.
+ * Returns nodes for folders containing .md/.mdc files and the .md/.mdc files themselves.
+ */
+async function buildMarkdownFilteredTree(dirPath, relativeDirPath) {
+    const nodes = [];
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryRelPath = join(relativeDirPath, entry.name);
+            const entryAbsPath = join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                const children = await buildMarkdownFilteredTree(entryAbsPath, entryRelPath);
+                if (children.length > 0) {
+                    nodes.push({
+                        id: entryRelPath,
+                        name: entry.name,
+                        type: "folder",
+                        path: entryRelPath,
+                        children,
+                    });
+                }
+            }
+            else if (entry.isFile() && MARKDOWN_EXTS.has(extname(entry.name))) {
+                nodes.push({
+                    id: entryRelPath,
+                    name: basename(entry.name, extname(entry.name)),
+                    type: "file",
+                    path: entryRelPath,
+                });
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read
+    }
+    return nodes;
+}
+/**
+ * Build the full AI file tree for a project or thread.
+ * - Always shows .agents/skills, .agents/rules, .agents/commands (virtual if missing)
+ * - Shows markdown files at root level
+ * - Shows folders that contain markdown files
+ */
+export async function buildAIFileTree(projectPath) {
+    const nodes = [];
+    // 1. Always-shown .agents subfolders
+    const agentsFolders = [
+        { key: "skills", label: "Skills" },
+        { key: "rules", label: "Rules" },
+        { key: "commands", label: "Commands" },
+        { key: "agents", label: "Agents" },
+    ];
+    for (const { key, label } of agentsFolders) {
+        const relPath = join(".agents", key);
+        const absPath = join(projectPath, relPath);
+        const exists = existsSync(absPath);
+        if (exists) {
+            const children = await buildFullTree(absPath, relPath);
+            nodes.push({
+                id: relPath,
+                name: label,
+                type: "folder",
+                path: relPath,
+                children,
+            });
+        }
+        else {
+            nodes.push({
+                id: relPath,
+                name: label,
+                type: "folder",
+                path: relPath,
+                children: [],
+                virtual: true,
+            });
+        }
+    }
+    // 2. Always add AGENTS.md as a virtual file in root
+    nodes.push({
+        id: "AGENTS.md",
+        name: "AGENTS",
+        type: "file",
+        path: "AGENTS.md",
+        virtual: true,
+    });
+    // 3. Scan root for markdown files and folders containing markdown files
+    try {
+        const rootEntries = await readdir(projectPath, { withFileTypes: true });
+        for (const entry of rootEntries) {
+            // Skip .agents (already handled), AGENTS.md (already added as virtual), and other ignored dirs
+            if (entry.name === ".agents" || entry.name === "AGENTS.md" || IGNORED_DIRS.has(entry.name))
+                continue;
+            const entryRelPath = entry.name;
+            const entryAbsPath = join(projectPath, entry.name);
+            if (entry.isFile() && MARKDOWN_EXTS.has(extname(entry.name))) {
+                nodes.push({
+                    id: entryRelPath,
+                    name: basename(entry.name, extname(entry.name)),
+                    type: "file",
+                    path: entryRelPath,
+                });
+            }
+            else if (entry.isDirectory()) {
+                const children = await buildMarkdownFilteredTree(entryAbsPath, entryRelPath);
+                if (children.length > 0) {
+                    nodes.push({
+                        id: entryRelPath,
+                        name: entry.name,
+                        type: "folder",
+                        path: entryRelPath,
+                        children,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // Can't read root directory
+    }
+    return nodes;
+}
+/**
+ * Validate that a file path is safe (no path traversal, within project or thread)
+ */
+export function validateFilePath(projectPath, filePath) {
+    if (!filePath)
+        return null;
+    const abs = join(projectPath, filePath);
+    if (!abs.startsWith(projectPath + "/") && abs !== projectPath)
+        return null;
+    return abs;
+}
+/**
+ * GET /api/projects/:id/ai-files
+ */
+export async function handleGetAIFiles(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        const project = await projectManager.getProject(projectId);
+        if (!project) {
+            return errorResponse(c, ErrorCodes.PROJECT_NOT_FOUND, `Project not found: ${projectId}`, 404);
+        }
+        const nodes = await buildAIFileTree(project.path);
+        return c.json({ nodes });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.INTERNAL_ERROR, "Failed to list AI files", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * GET /api/projects/:id/ai-file?path=...
+ */
+export async function handleGetAIFile(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        const filePath = c.req.query("path");
+        if (!filePath) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "path query parameter is required" } }, 400);
+        }
+        const project = await projectManager.getProject(projectId);
+        if (!project) {
+            return errorResponse(c, ErrorCodes.PROJECT_NOT_FOUND, `Project not found: ${projectId}`, 404);
+        }
+        const absPath = validateFilePath(project.path, filePath);
+        if (!absPath) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "Invalid file path" } }, 400);
+        }
+        // Special handling for AGENTS.md - return default content if it doesn't exist
+        if (filePath === "AGENTS.md") {
+            try {
+                await access(absPath);
+            }
+            catch {
+                // File doesn't exist, return default content
+                const defaultContent = `# AGENTS.md
+
+This file contains configuration and instructions for AI agents working on this repository.
+
+## Overview
+Add information about your project that would be helpful for AI agents to understand:
+
+- Project purpose and goals
+- Architecture and technology stack
+- Development workflows and conventions
+- Testing strategies
+- Deployment processes
+
+## Guidelines
+Provide specific guidelines for AI agents:
+
+- Code style preferences
+- File organization patterns
+- Review processes
+- Communication protocols
+
+## Resources
+Links to important documentation, tools, or references.
+
+---
+
+*This file was automatically created. Edit it to provide context for AI agents.*
+`;
+                return c.json({ content: defaultContent, path: filePath });
+            }
+        }
+        try {
+            await access(absPath);
+        }
+        catch {
+            return c.json({ error: { code: "NOT_FOUND", message: `File not found: ${filePath}` } }, 404);
+        }
+        const content = await readFile(absPath, "utf-8");
+        return c.json({ content, path: filePath });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.INTERNAL_ERROR, "Failed to read file", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * PUT /api/projects/:id/ai-file
+ * Body: { path: string, content: string }
+ */
+export async function handleSaveAIFile(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: { code: "BAD_REQUEST", message: "Invalid JSON body" } }, 400);
+        }
+        const { path: filePath, content } = body;
+        if (!filePath || content === undefined) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "path and content are required" } }, 400);
+        }
+        const project = await projectManager.getProject(projectId);
+        if (!project) {
+            return errorResponse(c, ErrorCodes.PROJECT_NOT_FOUND, `Project not found: ${projectId}`, 404);
+        }
+        const absPath = validateFilePath(project.path, filePath);
+        if (!absPath) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "Invalid file path" } }, 400);
+        }
+        // Ensure parent directory exists
+        const parentDir = join(absPath, "..");
+        await mkdir(parentDir, { recursive: true });
+        await writeFile(absPath, content, "utf-8");
+        return c.json({ success: true, path: filePath });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.INTERNAL_ERROR, "Failed to save file", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * DELETE /api/projects/:id/ai-file?path=...
+ * Deletes a file or folder at the specified path
+ */
+export async function handleDeleteAIFile(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        const filePath = c.req.query("path");
+        if (!filePath) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "path query parameter is required" } }, 400);
+        }
+        const project = await projectManager.getProject(projectId);
+        if (!project) {
+            return errorResponse(c, ErrorCodes.PROJECT_NOT_FOUND, `Project not found: ${projectId}`, 404);
+        }
+        const absPath = validateFilePath(project.path, filePath);
+        if (!absPath) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "Invalid file path" } }, 400);
+        }
+        try {
+            await access(absPath);
+        }
+        catch {
+            return c.json({ error: { code: "NOT_FOUND", message: `File or folder not found: ${filePath}` } }, 404);
+        }
+        // Delete file or folder recursively
+        await rm(absPath, { recursive: true, force: true });
+        return c.json({ success: true, path: filePath });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.INTERNAL_ERROR, "Failed to delete file", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * POST /api/projects/:id/ai-files/skill
+ * Body: { name: string, description: string, isGlobal?: boolean }
+ * Creates .agents/skills/{name}/SKILL.md
+ */
+export async function handleCreateSkill(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: { code: "BAD_REQUEST", message: "Invalid JSON body" } }, 400);
+        }
+        const { name, description, isGlobal } = body;
+        if (!name || !description) {
+            return c.json({ error: { code: "BAD_REQUEST", message: "name and description are required" } }, 400);
+        }
+        // Validate name: lowercase, alphanumeric and hyphens only
+        if (!/^[a-z0-9-]+$/.test(name) ||
+            name.startsWith("-") ||
+            name.endsWith("-") ||
+            name.includes("--")) {
+            return c.json({
+                error: {
+                    code: "BAD_REQUEST",
+                    message: "Skill name must be lowercase alphanumeric with hyphens (no leading/trailing/consecutive hyphens)",
+                },
+            }, 400);
+        }
+        if (isGlobal) {
+            return c.json({
+                error: {
+                    code: "BAD_REQUEST",
+                    message: "Global skills are not yet supported via this endpoint",
+                },
+            }, 400);
+        }
+        const project = await projectManager.getProject(projectId);
+        if (!project) {
+            return errorResponse(c, ErrorCodes.PROJECT_NOT_FOUND, `Project not found: ${projectId}`, 404);
+        }
+        const skillRelPath = join(".agents", "skills", name);
+        const skillAbsPath = join(project.path, skillRelPath);
+        const skillFileRelPath = join(skillRelPath, "SKILL.md");
+        const skillFileAbsPath = join(skillAbsPath, "SKILL.md");
+        // Check skill doesn't already exist
+        if (existsSync(skillAbsPath)) {
+            return c.json({ error: { code: "CONFLICT", message: `Skill '${name}' already exists` } }, 409);
+        }
+        // Create skill directory and SKILL.md
+        await mkdir(skillAbsPath, { recursive: true });
+        const skillContent = `---
+name: ${name}
+description: ${description}
+---
+
+Place your skill instructions here as markdown. This will be used when Tarsk is prompted with a request related to the description of this skill.
+`;
+        await writeFile(skillFileAbsPath, skillContent, "utf-8");
+        return c.json({
+            success: true,
+            path: skillFileRelPath,
+            content: skillContent,
+        });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.INTERNAL_ERROR, "Failed to create skill", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=projects-ai-files.route.js.map

package/dist/features/projects/projects-commands.route.d.ts

@@ -0,0 +1,27 @@
+/**
+ * POST /api/projects/:id/commands
+ * Add or update a command for a project
+ */
+import { Context } from "hono";
+import { ProjectManager } from "../projects/projects.manager.js";
+export declare function handleSaveCommand(c: Context, projectManager: ProjectManager): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details?: import("hono/utils/types").JSONValue | undefined;
+        timestamp: string;
+    };
+}, any, "json">) | (Response & import("hono").TypedResponse<import("hono/utils/types").JSONValue, any, "json">)>;
+/**
+ * DELETE /api/projects/:id/commands/:commandId
+ * Delete a command from a project
+ */
+export declare function handleDeleteCommand(c: Context, projectManager: ProjectManager): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details?: import("hono/utils/types").JSONValue | undefined;
+        timestamp: string;
+    };
+}, any, "json">) | (Response & import("hono").TypedResponse<import("hono/utils/types").JSONValue, any, "json">)>;
+//# sourceMappingURL=projects-commands.route.d.ts.map

package/dist/features/projects/projects-commands.route.js

@@ -0,0 +1,39 @@
+/**
+ * POST /api/projects/:id/commands
+ * Add or update a command for a project
+ */
+import { errorResponse, successResponse } from "../../core/route-helpers.js";
+import { ErrorCodes } from "../../core/error-responses.js";
+export async function handleSaveCommand(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        const command = await c.req.json();
+        if (!projectId) {
+            return errorResponse(c, ErrorCodes.INVALID_REQUEST, "Project ID is required", 400);
+        }
+        await projectManager.saveCommand(projectId, command);
+        return successResponse(c, { success: true, message: "Command saved" });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.SAVE_COMMAND_ERROR, "Failed to save command", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * DELETE /api/projects/:id/commands/:commandId
+ * Delete a command from a project
+ */
+export async function handleDeleteCommand(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        const commandId = c.req.param("commandId");
+        if (!projectId || !commandId) {
+            return errorResponse(c, ErrorCodes.INVALID_REQUEST, "Project ID and Command ID are required", 400);
+        }
+        await projectManager.deleteCommand(projectId, commandId);
+        return successResponse(c, { success: true, message: "Command deleted" });
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.DELETE_COMMAND_ERROR, "Failed to delete command", 500, error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=projects-commands.route.js.map

package/dist/features/projects/projects-create.route.d.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /api/projects
+ * Create a new project from a git URL
+ *
+ * Request body:
+ * {
+ *   "gitUrl": "https://github.com/user/repo.git"
+ * }
+ *
+ * Response: Newline-delimited JSON stream of ProjectEvent objects
+ *
+ * Requirements:
+ * - 6.2 - THE App SHALL send a POST request with the git URL to the CLI
+ * - 8.2 - THE CLI SHALL support streaming responses to the client
+ */
+import { Context } from "hono";
+import { ProjectManager } from "../projects/projects.manager.js";
+export declare function handleCreateProject(c: Context, projectManager: ProjectManager): Promise<Response>;
+//# sourceMappingURL=projects-create.route.d.ts.map

package/dist/features/projects/projects-create.route.js

@@ -0,0 +1,37 @@
+/**
+ * POST /api/projects
+ * Create a new project from a git URL
+ *
+ * Request body:
+ * {
+ *   "gitUrl": "https://github.com/user/repo.git"
+ * }
+ *
+ * Response: Newline-delimited JSON stream of ProjectEvent objects
+ *
+ * Requirements:
+ * - 6.2 - THE App SHALL send a POST request with the git URL to the CLI
+ * - 8.2 - THE CLI SHALL support streaming responses to the client
+ */
+import { streamAsyncGenerator } from "../../core/stream-helper.js";
+import { CommitMethods, isValidCommitMethod } from "@tarsk/shared";
+import { errorResponse } from "../../core/route-helpers.js";
+import { ErrorCodes } from "../../core/error-responses.js";
+export async function handleCreateProject(c, projectManager) {
+    try {
+        const body = await c.req.json();
+        const { gitUrl, commitMethod } = body;
+        // Validate gitUrl is provided
+        if (!gitUrl || typeof gitUrl !== "string") {
+            return errorResponse(c, ErrorCodes.INVALID_REQUEST, "gitUrl is required and must be a string", 400);
+        }
+        // Validate commitMethod if provided (default to PullRequest)
+        const method = isValidCommitMethod(commitMethod) ? commitMethod : CommitMethods.PullRequest;
+        // Stream the project creation events
+        return streamAsyncGenerator(c, projectManager.createProject(gitUrl, method));
+    }
+    catch (error) {
+        return errorResponse(c, ErrorCodes.REQUEST_PARSE_ERROR, "Failed to parse request body", 400, error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=projects-create.route.js.map

package/dist/features/projects/projects-delete.route.d.ts

@@ -0,0 +1,24 @@
+/**
+ * DELETE /api/projects/:id
+ * Delete a project and all its threads
+ *
+ * Response:
+ * {
+ *   "success": true,
+ *   "message": "Project deleted successfully"
+ * }
+ *
+ * Requirements:
+ * - 6.2 - THE CLI SHALL expose REST API endpoints for Project operations
+ */
+import { Context } from "hono";
+import { ProjectManager } from "../projects/projects.manager.js";
+export declare function handleDeleteProject(c: Context, projectManager: ProjectManager): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details?: import("hono/utils/types").JSONValue | undefined;
+        timestamp: string;
+    };
+}, any, "json">) | (Response & import("hono").TypedResponse<import("hono/utils/types").JSONValue, any, "json">)>;
+//# sourceMappingURL=projects-delete.route.d.ts.map

package/dist/features/projects/projects-delete.route.js

@@ -0,0 +1,34 @@
+/**
+ * DELETE /api/projects/:id
+ * Delete a project and all its threads
+ *
+ * Response:
+ * {
+ *   "success": true,
+ *   "message": "Project deleted successfully"
+ * }
+ *
+ * Requirements:
+ * - 6.2 - THE CLI SHALL expose REST API endpoints for Project operations
+ */
+import { errorResponse, successResponse } from "../../core/route-helpers.js";
+import { ErrorCodes } from "../../core/error-responses.js";
+export async function handleDeleteProject(c, projectManager) {
+    try {
+        const projectId = c.req.param("id");
+        if (!projectId) {
+            return errorResponse(c, ErrorCodes.INVALID_REQUEST, "Project ID is required", 400);
+        }
+        await projectManager.deleteProject(projectId);
+        return successResponse(c, { success: true, message: "Project deleted successfully" });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Check if it's a "not found" error
+        if (errorMessage.includes("not found")) {
+            return errorResponse(c, ErrorCodes.PROJECT_NOT_FOUND, errorMessage, 404);
+        }
+        return errorResponse(c, ErrorCodes.DELETE_PROJECT_ERROR, "Failed to delete project", 500, errorMessage);
+    }
+}
+//# sourceMappingURL=projects-delete.route.js.map

package/dist/features/projects/projects-get.route.d.ts

@@ -0,0 +1,47 @@
+/**
+ * GET /api/projects/:id
+ * Get project details by ID
+ *
+ * Response:
+ * {
+ *   "id": "uuid",
+ *   "name": "project-name",
+ *   "gitUrl": "https://github.com/user/repo.git",
+ *   "path": "/path/to/project",
+ *   "createdAt": "2024-01-01T00:00:00Z",
+ *   "threads": ["thread-id-1", "thread-id-2"]
+ * }
+ *
+ * Requirements:
+ * - 6.2 - THE CLI SHALL expose REST API endpoints for Project operations
+ */
+import { Context } from "hono";
+import { ProjectManager } from "../projects/projects.manager.js";
+export declare function handleGetProject(c: Context, projectManager: ProjectManager): Promise<(Response & import("hono").TypedResponse<{
+    error: {
+        code: string;
+        message: string;
+        details?: import("hono/utils/types").JSONValue | undefined;
+        timestamp: string;
+    };
+}, any, "json">) | (Response & import("hono").TypedResponse<{
+    id: string;
+    name: string;
+    gitUrl: string;
+    path: string;
+    createdAt: string;
+    threads: string[];
+    openWith?: string | undefined;
+    commands?: {
+        id: string;
+        name: string;
+        icon: string;
+        commandLine: string;
+        relativeFolder?: string | undefined;
+    }[] | undefined;
+    setupScript?: string | undefined;
+    pendingSetupScripts?: string[] | undefined;
+    runCommand?: string | undefined;
+    commitMethod?: import("@tarsk/shared").CommitMethods | undefined;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+//# sourceMappingURL=projects-get.route.d.ts.map