profclaw 0.0.1-beta.1

package/dist/tickets/types.js

@@ -0,0 +1,310 @@
+/**
+ * profClaw AI-Native Ticket System Types
+ *
+ * Universal schema designed for bi-directional sync with:
+ * - GitHub Issues
+ * - Linear
+ * - Jira
+ * - Plane
+ */
+import { z } from "zod";
+// === Enums ===
+export const TicketType = z.enum([
+    "task",
+    "bug",
+    "feature",
+    "epic",
+    "story",
+    "subtask",
+]);
+export const TicketPriority = z.enum([
+    "critical",
+    "high",
+    "medium",
+    "low",
+    "none",
+]);
+export const TicketStatus = z.enum([
+    "backlog",
+    "todo",
+    "in_progress",
+    "in_review",
+    "done",
+    "cancelled",
+]);
+// State groups for custom workflow states (maps custom states to core groups)
+export const StateGroup = z.enum([
+    "backlog",
+    "unstarted",
+    "started",
+    "completed",
+    "cancelled",
+]);
+export const ExternalPlatform = z.enum([
+    "github",
+    "linear",
+    "jira",
+    "plane",
+    "monday",
+]);
+export const SyncDirection = z.enum(["push", "pull", "bidirectional"]);
+export const AuthorType = z.enum(["human", "ai"]);
+// === External Link (1 ticket -> N platforms) ===
+export const ExternalLinkSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    platform: ExternalPlatform,
+    externalId: z.string(), // PROJ-123, LIN-456, #789
+    externalUrl: z.string().url().optional(),
+    syncEnabled: z.boolean().default(true),
+    syncDirection: SyncDirection.default("bidirectional"),
+    lastSyncedAt: z.string().datetime().optional(),
+    syncError: z.string().optional(),
+    createdAt: z.string().datetime(),
+});
+// === Ticket Relations (issue links) ===
+export const TicketRelationType = z.enum([
+    "blocks",
+    "blocked_by",
+    "relates_to",
+    "duplicates",
+    "start_before",
+    "finish_before",
+]);
+export const TicketRelationSchema = z.object({
+    id: z.string(),
+    sourceTicketId: z.string(),
+    targetTicketId: z.string(),
+    relationType: TicketRelationType,
+    createdAt: z.string().datetime(),
+});
+// === Ticket Watchers ===
+export const TicketWatcherSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    userId: z.string(),
+    createdAt: z.string().datetime(),
+});
+// === Ticket Assignees ===
+export const TicketAssigneeSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    userId: z.string(),
+    createdAt: z.string().datetime(),
+});
+// === Ticket Mentions ===
+export const TicketMentionSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    userId: z.string(),
+    source: z.enum(["description", "comment", "history"]),
+    sourceId: z.string().optional(),
+    createdAt: z.string().datetime(),
+});
+// === Ticket Attachments ===
+export const TicketAttachmentSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    fileName: z.string(),
+    fileType: z.string().optional(),
+    fileSize: z.number().optional(),
+    url: z.string().url(),
+    storagePath: z.string().optional(),
+    uploadedBy: z.string().optional(),
+    createdAt: z.string().datetime(),
+});
+// === Ticket Reactions ===
+export const TicketReactionSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    userId: z.string(),
+    emoji: z.string(),
+    createdAt: z.string().datetime(),
+});
+// === Unified Comment (aggregated from all platforms) ===
+export const CommentAuthorSchema = z.object({
+    type: AuthorType,
+    name: z.string(),
+    platform: z.string(), // Where comment originated
+    avatarUrl: z.string().url().optional(),
+});
+export const TicketCommentSchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    content: z.string(),
+    contentHtml: z.string().optional(),
+    author: CommentAuthorSchema,
+    source: z.enum(["profclaw", "github", "linear", "jira", "plane"]),
+    externalId: z.string().optional(), // ID in source system
+    isAiResponse: z.boolean().default(false),
+    respondingTo: z.string().optional(), // Comment ID it's replying to
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime().optional(),
+});
+// === History Entry (audit trail) ===
+export const HistoryEntrySchema = z.object({
+    id: z.string(),
+    ticketId: z.string(),
+    field: z.string(), // "status", "assignee", "title"
+    oldValue: z.string().optional(),
+    newValue: z.string().optional(),
+    changedBy: CommentAuthorSchema,
+    timestamp: z.string().datetime(),
+});
+// === Core Ticket ===
+export const TicketSchema = z.object({
+    // === Core Identity ===
+    id: z.string(),
+    sequence: z.number(), // Human-readable: PC-123
+    workspaceId: z.string().optional(),
+    projectId: z.string().optional(), // Multi-project support
+    // === Content ===
+    title: z.string().min(1),
+    description: z.string().default(""),
+    descriptionHtml: z.string().optional(),
+    // === Classification ===
+    type: TicketType.default("task"),
+    priority: TicketPriority.default("medium"),
+    status: TicketStatus.default("backlog"),
+    labels: z.array(z.string()).default([]),
+    // === Assignment ===
+    assignee: z.string().optional(), // User ID
+    assigneeAgent: z.string().optional(), // AI agent ID (claude, openclaw, ollama)
+    // === Relationships ===
+    parentId: z.string().optional(), // Epic/parent ticket
+    linkedPRs: z.array(z.string()).default([]), // GitHub PR URLs
+    linkedCommits: z.array(z.string()).default([]), // Commit SHAs
+    linkedBranch: z.string().optional(), // Working branch
+    // === Timestamps ===
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    startedAt: z.string().datetime().optional(),
+    completedAt: z.string().datetime().optional(),
+    startDate: z.string().datetime().optional(),
+    dueDate: z.string().datetime().optional(),
+    // === AI Metadata ===
+    createdBy: AuthorType.default("human"),
+    aiAgent: z.string().optional(), // Which agent created it
+    aiSessionId: z.string().optional(), // Link to Claude session
+    aiTaskId: z.string().optional(), // Link to profClaw task
+    // === Estimation ===
+    estimate: z.number().optional(), // Story points or hours
+    estimateUnit: z.enum(["points", "hours", "days"]).optional(),
+});
+// === Create/Update Schemas ===
+export const CreateTicketSchema = z.object({
+    title: z.string().min(1, "Title is required"),
+    description: z.string().optional(),
+    type: TicketType.optional(),
+    priority: TicketPriority.optional(),
+    status: TicketStatus.optional(),
+    labels: z.array(z.string()).optional(),
+    assignee: z.string().optional(),
+    assigneeAgent: z.string().optional(),
+    parentId: z.string().optional(),
+    projectId: z.string().optional(), // Multi-project support
+    startDate: z.string().datetime().optional(),
+    dueDate: z.string().datetime().optional(),
+    estimate: z.number().optional(),
+    estimateUnit: z.enum(["points", "hours", "days"]).optional(),
+    // AI metadata
+    createdBy: AuthorType.optional(),
+    aiAgent: z.string().optional(),
+    aiSessionId: z.string().optional(),
+    aiTaskId: z.string().optional(),
+    // External link on creation
+    externalLink: z
+        .object({
+        platform: ExternalPlatform,
+        externalId: z.string(),
+        externalUrl: z.string().url().optional(),
+    })
+        .optional(),
+});
+export const UpdateTicketSchema = CreateTicketSchema.partial();
+// === Bulk Schemas ===
+export const BulkUpdateTicketsSchema = z.object({
+    ids: z.array(z.string()).min(1, "At least one ticket ID is required"),
+    updates: UpdateTicketSchema,
+});
+export const BulkDeleteTicketsSchema = z.object({
+    ids: z.array(z.string()).min(1, "At least one ticket ID is required"),
+});
+// === Query Schemas ===
+export const TicketQuerySchema = z.object({
+    // Project/Sprint filtering
+    projectId: z.string().optional(),
+    sprintId: z.string().optional(),
+    inBacklog: z.boolean().optional(), // Tickets not assigned to any sprint
+    // Status filtering
+    status: z.union([TicketStatus, z.array(TicketStatus)]).optional(),
+    type: z.union([TicketType, z.array(TicketType)]).optional(),
+    priority: z.union([TicketPriority, z.array(TicketPriority)]).optional(),
+    assignee: z.string().optional(),
+    assigneeAgent: z.string().optional(),
+    labels: z.array(z.string()).optional(),
+    label: z.string().optional(), // Single label filter (for simple UI)
+    parentId: z.string().optional(),
+    search: z.string().optional(),
+    createdBy: z.enum(["human", "ai"]).optional(), // Filter by author type
+    createdAfter: z.string().datetime().optional(),
+    createdBefore: z.string().datetime().optional(),
+    startDateAfter: z.string().datetime().optional(),
+    startDateBefore: z.string().datetime().optional(),
+    sortBy: z
+        .enum([
+        "createdAt",
+        "updatedAt",
+        "priority",
+        "sequence",
+        "dueDate",
+        "startDate",
+    ])
+        .optional(),
+    sortOrder: z.enum(["asc", "desc"]).optional(),
+    limit: z.number().min(1).max(200).optional(), // Increased for board views
+    offset: z.number().min(0).optional(),
+    includeArchived: z.boolean().optional(),
+    // Cursor-based pagination (Phase 17)
+    cursorCreatedAt: z.date().optional(),
+    cursorId: z.string().optional(),
+});
+// === Status Mapping (Cross-Platform) ===
+export const STATUS_MAP = {
+    backlog: { jira: "To Do", linear: "Backlog", github: "open" },
+    todo: { jira: "To Do", linear: "Todo", github: "open" },
+    in_progress: { jira: "In Progress", linear: "In Progress", github: "open" },
+    in_review: { jira: "In Review", linear: "In Review", github: "open" },
+    done: { jira: "Done", linear: "Done", github: "closed" },
+    cancelled: { jira: "Cancelled", linear: "Cancelled", github: "closed" },
+};
+export const REVERSE_STATUS_MAP = {
+    jira: {
+        "To Do": "todo",
+        "In Progress": "in_progress",
+        "In Review": "in_review",
+        Done: "done",
+        Cancelled: "cancelled",
+    },
+    linear: {
+        Backlog: "backlog",
+        Todo: "todo",
+        "In Progress": "in_progress",
+        "In Review": "in_review",
+        Done: "done",
+        Cancelled: "cancelled",
+    },
+    github: {
+        open: "todo",
+        closed: "done",
+    },
+};
+// === Priority Mapping ===
+export const PRIORITY_MAP = {
+    critical: { jira: "Highest", linear: "Urgent", github: "P0" },
+    high: { jira: "High", linear: "High", github: "P1" },
+    medium: { jira: "Medium", linear: "Medium", github: "P2" },
+    low: { jira: "Low", linear: "Low", github: "P3" },
+    none: { jira: "Lowest", linear: "None", github: "" },
+};
+//# sourceMappingURL=types.js.map

package/dist/tools/adapters.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Tool Adapters
+ *
+ * Convert universal tool definitions to specific formats:
+ * - MCP (Model Context Protocol) for external AI agents
+ * - Chat Execution for internal chat API
+ * - AI SDK for native function calling
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolDefinition as ChatToolDefinition } from '../chat/execution/types.js';
+import type { ToolDefinition, ToolResult, MCPToolSchema, AIToolSchema, ToolCategory } from './types.js';
+/**
+ * Convert tool definition to MCP schema
+ */
+export declare function toMCPSchema(tool: ToolDefinition, prefix?: string): MCPToolSchema;
+/**
+ * Convert tool result to MCP CallToolResult
+ */
+export declare function toMCPResult(result: ToolResult): CallToolResult;
+/**
+ * Create MCP handler for a set of tools
+ */
+export declare function createMCPHandler(tools: ToolDefinition[], prefix?: string): (name: string, args: unknown) => Promise<CallToolResult | null>;
+/**
+ * Convert universal tool to chat execution format
+ */
+export declare function toChatTool(tool: ToolDefinition): ChatToolDefinition;
+/**
+ * Convert multiple tools to chat execution format
+ */
+export declare function toChatTools(tools: ToolDefinition[]): ChatToolDefinition[];
+/**
+ * Convert tool definition to AI SDK schema
+ */
+export declare function toAISchema(tool: ToolDefinition): AIToolSchema;
+/**
+ * Convert multiple tools to AI SDK format
+ */
+export declare function toAISchemas(tools: ToolDefinition[]): AIToolSchema[];
+/**
+ * Filter tools by security level
+ */
+export declare function filterSafeTools(tools: ToolDefinition[]): ToolDefinition[];
+/**
+ * Filter tools by category
+ */
+export declare function filterByCategory(tools: ToolDefinition[], category: ToolCategory): ToolDefinition[];
+/**
+ * Get tool names
+ */
+export declare function getToolNames(tools: ToolDefinition[]): string[];
+/**
+ * Find tool by name
+ */
+export declare function findTool(tools: ToolDefinition[], name: string): ToolDefinition | undefined;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/tools/adapters.js

@@ -0,0 +1,183 @@
+/**
+ * Tool Adapters
+ *
+ * Convert universal tool definitions to specific formats:
+ * - MCP (Model Context Protocol) for external AI agents
+ * - Chat Execution for internal chat API
+ * - AI SDK for native function calling
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+// MCP Adapter
+const MCP_PREFIX = 'profclaw__';
+/**
+ * Convert tool definition to MCP schema
+ */
+export function toMCPSchema(tool, prefix = MCP_PREFIX) {
+    const jsonSchema = zodToJsonSchema(tool.parameters, {
+        $refStrategy: 'none',
+        target: 'openAi',
+    });
+    return {
+        name: `${prefix}${tool.name}`,
+        description: tool.description,
+        inputSchema: jsonSchema,
+    };
+}
+/**
+ * Convert tool result to MCP CallToolResult
+ */
+export function toMCPResult(result) {
+    if (!result.success) {
+        return {
+            content: [{ type: 'text', text: result.output }],
+            isError: true,
+        };
+    }
+    // Handle image data specially
+    const data = result.data;
+    if (data && typeof data === 'object' && 'base64' in data && 'mimeType' in data) {
+        return {
+            content: [
+                {
+                    type: 'image',
+                    data: data.base64,
+                    mimeType: data.mimeType,
+                },
+            ],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: result.output }],
+    };
+}
+/**
+ * Create MCP handler for a set of tools
+ */
+export function createMCPHandler(tools, prefix = MCP_PREFIX) {
+    return async (name, args) => {
+        if (!name.startsWith(prefix)) {
+            return null;
+        }
+        const toolName = name.slice(prefix.length);
+        const tool = tools.find((t) => t.name === toolName);
+        if (!tool) {
+            return null;
+        }
+        // Parse and validate args
+        const parsed = tool.parameters.safeParse(args);
+        if (!parsed.success) {
+            return {
+                content: [{ type: 'text', text: `Invalid parameters: ${parsed.error.message}` }],
+                isError: true,
+            };
+        }
+        // Execute tool
+        const result = await tool.execute(parsed.data);
+        return toMCPResult(result);
+    };
+}
+// Chat Execution Adapter
+/**
+ * Convert universal tool to chat execution format
+ */
+export function toChatTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        category: tool.category,
+        securityLevel: tool.securityLevel,
+        allowedHosts: ['sandbox', 'gateway', 'local'],
+        isAvailable: tool.isAvailable,
+        parameters: tool.parameters,
+        examples: tool.examples?.map((e) => ({
+            description: e.description,
+            params: e.params,
+        })),
+        async execute(_context, params) {
+            const result = await tool.execute(params);
+            return {
+                success: result.success,
+                data: result.data,
+                output: result.output,
+                error: result.error,
+            };
+        },
+    };
+}
+/**
+ * Convert multiple tools to chat execution format
+ */
+export function toChatTools(tools) {
+    return tools.map(toChatTool);
+}
+// AI SDK Adapter (OpenAI/Anthropic native format)
+/**
+ * Convert tool definition to AI SDK schema
+ */
+export function toAISchema(tool) {
+    const jsonSchema = zodToJsonSchema(tool.parameters, {
+        $refStrategy: 'none',
+        target: 'openAi',
+    });
+    const schemaObj = jsonSchema;
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: buildAIDescription(tool),
+            parameters: {
+                type: 'object',
+                properties: schemaObj.properties ?? {},
+                required: schemaObj.required,
+            },
+        },
+    };
+}
+function buildAIDescription(tool) {
+    let desc = tool.description;
+    if (tool.securityLevel === 'dangerous') {
+        desc += '\n\n⚠️ This tool requires approval before execution.';
+    }
+    else if (tool.securityLevel === 'moderate') {
+        desc += '\n\nNote: This tool may require approval depending on the operation.';
+    }
+    if (tool.examples?.length) {
+        desc += '\n\nExamples:';
+        for (const example of tool.examples.slice(0, 2)) {
+            desc += `\n- ${example.description}`;
+        }
+    }
+    return desc;
+}
+/**
+ * Convert multiple tools to AI SDK format
+ */
+export function toAISchemas(tools) {
+    return tools.map(toAISchema);
+}
+// Utility Functions
+/**
+ * Filter tools by security level
+ */
+export function filterSafeTools(tools) {
+    return tools.filter((t) => t.securityLevel === 'safe');
+}
+/**
+ * Filter tools by category
+ */
+export function filterByCategory(tools, category) {
+    return tools.filter((t) => t.category === category);
+}
+/**
+ * Get tool names
+ */
+export function getToolNames(tools) {
+    return tools.map((t) => t.name);
+}
+/**
+ * Find tool by name
+ */
+export function findTool(tools, name) {
+    return tools.find((t) => t.name === name);
+}
+//# sourceMappingURL=adapters.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Unified Tool System
+ *
+ * Single source of truth for all profClaw tools.
+ *
+ * Usage:
+ * ```typescript
+ * import { getAllTools, getMCPTools, getChatTools } from './tools/index.js';
+ *
+ * // Get all tools
+ * const tools = getAllTools();
+ *
+ * // Get MCP schemas (with profclaw__ prefix)
+ * const mcpTools = getMCPTools();
+ *
+ * // Get chat execution tools
+ * const chatTools = getChatTools();
+ *
+ * // Handle MCP tool call
+ * const result = await handleMCPToolCall('profclaw__browser_navigate', { url: '...' });
+ * ```
+ */
+export type { ToolDefinition, ToolResult, ToolExample, ToolCategory, SecurityLevel, ToolCollection, MCPToolSchema, AIToolSchema, } from './types.js';
+export { createToolCollection } from './types.js';
+export { toMCPSchema, toMCPResult, createMCPHandler, toChatTool, toChatTools, toAISchema, toAISchemas, filterSafeTools, filterByCategory, getToolNames, findTool, } from './adapters.js';
+import type { ToolDefinition, MCPToolSchema } from './types.js';
+import type { ToolDefinition as ChatToolDefinition } from '../chat/execution/types.js';
+/**
+ * Get all registered tools
+ */
+export declare function getAllTools(): ToolDefinition[];
+/**
+ * Get safe tools only (for default chat)
+ */
+export declare function getSafeTools(): ToolDefinition[];
+/**
+ * Get all tool names
+ */
+export declare function getAllToolNames(): string[];
+/**
+ * Get safe tool names
+ */
+export declare function getSafeToolNames(): string[];
+/**
+ * Get MCP tool schemas (with profclaw__ prefix)
+ */
+export declare function getMCPTools(): MCPToolSchema[];
+/**
+ * Handle MCP tool call
+ */
+export declare const handleMCPToolCall: (name: string, args: unknown) => Promise<import("@modelcontextprotocol/sdk/types.js").CallToolResult | null>;
+/**
+ * Check if a name is an MCP tool
+ */
+export declare function isMCPTool(name: string): boolean;
+/**
+ * Get chat execution tools
+ */
+export declare function getChatTools(): ChatToolDefinition[];
+/**
+ * Get safe chat tools (for default mode)
+ */
+export declare function getSafeChatTools(): ChatToolDefinition[];
+export { BROWSER_TOOLS } from '../browser/tools.js';
+export { BROWSER_TOOL_NAMES, SAFE_BROWSER_TOOL_NAMES, } from '../browser/tools.js';
+//# sourceMappingURL=index.d.ts.map