atabey 0.0.11 → 0.0.13

package/framework-mcp/dist/tools/definitions.js

@@ -1,322 +1,154 @@
+import * as schemas from "./schemas.js";
+import { zodToMcpSchema } from "../utils/zod-to-mcp.js";
+/**
+ * ─── SUPREME TOOL REGISTRY ─────────────────────────────────────────
+ * Every tool is dynamically generated from its Zod schema.
+ * ZERO manual JSON schema maintenance permitted.
+ */
 export const TOOLS = [
+    // File System
     {
         name: "read_file",
         description: "Read the content of a file within the project. Supports optional line range reading to prevent stream overload.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file relative to project root" },
-                startLine: { type: "number", description: "Optional starting line number (1-indexed)" },
-                endLine: { type: "number", description: "Optional ending line number (inclusive)" },
-            },
-            required: ["path"],
-        },
+        inputSchema: zodToMcpSchema(schemas.ReadFileSchema),
     },
     {
-        name: "list_dir",
-        description: "List the contents of a directory. Essential for codebase exploration.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the directory relative to project root (default: '.')" },
-            },
-        },
-    },
-    {
-        name: "grep_search",
-        description: "Perform a recursive regex search across the codebase to find functions, variables, or patterns.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                pattern: { type: "string", description: "The regex pattern to search for" },
-                includePattern: { type: "string", description: "Optional: Filter files by extension (e.g., '.ts')" },
-                excludePattern: { type: "string", description: "Optional: Directory pattern to exclude (default: 'node_modules')" },
-            },
-            required: ["pattern"],
-        },
+        name: "view_file",
+        description: "Alias for read_file. Reads the content of a file within the project.",
+        inputSchema: zodToMcpSchema(schemas.ReadFileSchema),
     },
     {
         name: "write_file",
         description: "Write content to a file. Creates directories if missing.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file relative to project root" },
-                content: { type: "string", description: "Complete content of the file" },
-            },
-            required: ["path", "content"],
-        },
+        inputSchema: zodToMcpSchema(schemas.WriteFileSchema),
     },
     {
         name: "replace_text",
         description: "Surgically replace a string in a file with another string.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file" },
-                oldText: { type: "string", description: "The exact text to find" },
-                newText: { type: "string", description: "The text to replace it with" },
-                allowMultiple: { type: "boolean", description: "Allow multiple replacements if oldText is not unique." }
-            },
-            required: ["path", "oldText", "newText"],
-        },
+        inputSchema: zodToMcpSchema(schemas.ReplaceTextSchema),
     },
     {
         name: "batch_surgical_edit",
-        description: "Perform multiple surgical text replacements across multiple files in a single batch request. More efficient for cross-cutting changes.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                edits: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            path: { type: "string", description: "Path to the file" },
-                            oldText: { type: "string", description: "The exact text to find" },
-                            newText: { type: "string", description: "The text to replace it with" },
-                            allowMultiple: { type: "boolean", description: "Allow multiple replacements in this file." }
-                        },
-                        required: ["path", "oldText", "newText"]
-                    }
-                }
-            },
-            required: ["edits"],
-        },
+        description: "Perform multiple surgical text replacements across multiple files in a single batch request.",
+        inputSchema: zodToMcpSchema(schemas.BatchSurgicalEditSchema),
     },
     {
         name: "patch_file",
         description: "Safely update a file by replacing a specific line range with new content.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file" },
-                startLine: { type: "number", description: "Starting line number (1-indexed)" },
-                endLine: { type: "number", description: "Ending line number (inclusive)" },
-                newContent: { type: "string", description: "The new lines to insert" },
-            },
-            required: ["path", "startLine", "endLine", "newContent"],
-        },
+        inputSchema: zodToMcpSchema(schemas.PatchFileSchema),
+    },
+    // Search & Exploration
+    {
+        name: "list_dir",
+        description: "List the contents of a directory. Essential for codebase exploration.",
+        inputSchema: zodToMcpSchema(schemas.ListDirSchema),
+    },
+    {
+        name: "grep_search",
+        description: "Perform a recursive regex search across the codebase.",
+        inputSchema: zodToMcpSchema(schemas.GrepSearchSchema),
     },
     {
         name: "get_project_map",
-        description: "Generate a tree-view map of the project structure to visualize the layout. Useful for onboarding and architectural analysis.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                maxDepth: { type: "number", description: "Maximum directory depth to scan (default: 3)" },
-                includeFiles: { type: "boolean", description: "Whether to include files in the map (default: true)" }
-            }
-        }
+        description: "Generate a tree-view map of the project structure.",
+        inputSchema: zodToMcpSchema(schemas.GetProjectMapSchema),
     },
     {
         name: "get_project_gaps",
-        description: "Scans the codebase for TODOs, FIXMEs, and empty function bodies. Helps identify what is left and where the agent might have skipped logic.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the source directory (default: 'src')" },
-            },
-        },
+        description: "Scans the codebase for TODOs, FIXMEs, and empty function bodies.",
+        inputSchema: zodToMcpSchema(schemas.GetProjectGapsSchema),
     },
+    // Framework & System
     {
-        name: "audit_dependencies",
-        description: "Audits package.json for unused, redundant, or duplicate-like packages to ensure a clean dependency tree.",
-        inputSchema: { type: "object", properties: {} },
+        name: "run_shell_command",
+        description: "Execute a shell command. Restricted for security.",
+        inputSchema: zodToMcpSchema(schemas.RunShellCommandSchema),
     },
     {
         name: "run_tests",
-        description: "Execute project test suites (Vitest, Playwright, etc.) and capture detailed pass/fail reports for analysis.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                command: { type: "string", description: "The test command to run (default: project's standard test command)" }
-            }
-        }
+        description: "Execute project test suites and capture pass/fail reports.",
+        inputSchema: zodToMcpSchema(schemas.RunTestsSchema),
     },
     {
         name: "get_system_health",
-        description: "Retrieve real-time system metrics like CPU load, RAM usage, and uptime.",
-        inputSchema: { type: "object", properties: {} }
+        description: "Retrieve real-time system metrics (CPU, RAM).",
+        inputSchema: zodToMcpSchema(schemas.GetSystemHealthSchema),
     },
     {
         name: "check_active_ports",
-        description: "Identify which network ports are currently active and listening. Helps verify if the dev server or API is running.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                filter: { type: "string", description: "Optional: Filter results by port number or service name (e.g., ':3000')" }
-            }
-        }
+        description: "Identify which network ports are currently active.",
+        inputSchema: zodToMcpSchema(schemas.CheckPortsSchema),
     },
     {
         name: "get_framework_status",
         description: "Get the current project phase, active traces, and agent states.",
-        inputSchema: { type: "object", properties: {} },
+        inputSchema: zodToMcpSchema(schemas.GetFrameworkStatusSchema),
     },
     {
         name: "read_project_memory",
-        description: "Read the full project central memory (PROJECT_MEMORY.md). Use this at the start of a session to gain context.",
-        inputSchema: { type: "object", properties: {} },
+        description: "Read the full project central memory (PROJECT_MEMORY.md).",
+        inputSchema: zodToMcpSchema(schemas.ReadProjectMemorySchema),
     },
     {
         name: "get_memory_insights",
-        description: "Retrieve a summarized version of the project memory (active phase, trace, and last 5 actions) to save tokens.",
-        inputSchema: { type: "object", properties: {} },
+        description: "Retrieve a summarized version of the project memory.",
+        inputSchema: zodToMcpSchema(schemas.GetMemoryInsightsSchema),
     },
     {
         name: "update_project_memory",
         description: "Update a specific section in PROJECT_MEMORY.md.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                section: { type: "string", description: "Section name (e.g., HISTORY, ACTIVE TASKS)" },
-                content: { type: "string", description: "Markdown content to append or set" },
-            },
-            required: ["section", "content"],
-        },
+        inputSchema: zodToMcpSchema(schemas.UpdateProjectMemorySchema),
     },
     {
         name: "orchestrate_loop",
-        description: "Process the pending Hermes messages and trigger dynamic state transitions.",
-        inputSchema: { type: "object", properties: {} },
+        description: "Process pending Hermes messages and trigger transitions.",
+        inputSchema: zodToMcpSchema(schemas.OrchestrateLoopSchema),
     },
     {
-        name: "send_agent_message",
-        description: "Send a Hermes protocol message to another agent for collaboration or sub-tasking.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                from: { type: "string", description: "Sender agent (e.g., @manager, @backend)." },
-                to: { type: "string", description: "Target agent (e.g., @backend, @quality)." },
-                category: { type: "string", enum: ["ACTION", "DELEGATION", "SUBTASK", "REPLY", "ALERT"], description: "Message type." },
-                content: { type: "string", description: "Task description or message content." },
-                traceId: { type: "string", description: "Active Trace ID." },
-                parentId: { type: "string", description: "Optional parent task trace ID for hierarchical tracking." },
-                priority: { type: "string", enum: ["HIGH", "NORMAL", "LOW"], description: "Optional priority level (HIGH, NORMAL, LOW). Defaults to HIGH for ALERT/ACTION." },
-                requiresApproval: { type: "boolean", description: "If true, this message will require manager approval before being processed." },
-            },
-            required: ["from", "to", "category", "content", "traceId"],
-        },
+        name: "submit_plan",
+        description: "Submit a structured DAG plan of tasks for the project.",
+        inputSchema: zodToMcpSchema(schemas.SubmitPlanSchema),
     },
     {
-        name: "acquire_lock",
-        description: "Acquire a stateful lock on a shared resource (like PROJECT_MEMORY.md) to prevent concurrent write conflicts.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                resource: { type: "string", description: "The resource name or path to lock (e.g., 'memory')." },
-                agent: { type: "string", description: "The agent requesting the lock (e.g., '@backend')." },
-                ttl: { type: "number", description: "Time-to-live in seconds before the lock auto-expires (default: 60)." }
-            },
-            required: ["resource", "agent"]
-        }
+        name: "update_contract_hash",
+        description: "Re-generate and synchronize the backend contract SHA-256 hash.",
+        inputSchema: zodToMcpSchema(schemas.UpdateContractHashSchema),
     },
     {
-        name: "release_lock",
-        description: "Release a previously acquired lock on a resource.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                resource: { type: "string", description: "The resource name or path." },
-                agent: { type: "string", description: "The agent releasing the lock." }
-            },
-            required: ["resource", "agent"]
-        }
+        name: "audit_dependencies",
+        description: "Audits package.json for unused or redundant packages.",
+        inputSchema: zodToMcpSchema(schemas.AuditDependenciesSchema),
     },
     {
-        name: "register_agent",
-        description: "Register an agent instance with the Control Plane and validate its permissions.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                agent: { type: "string", description: "The agent name (e.g., '@backend')." },
-                role: { type: "string", description: "The role of the agent." },
-                capability: { type: "number", description: "The capability score (1-10)." },
-                specialties: {
-                    type: "object",
-                    additionalProperties: { type: "number" },
-                    description: "Sub-specialty weights mapping (e.g. {\"postgres\": 10, \"redis\": 8})"
-                }
-            },
-            required: ["agent", "role"]
-        }
+        name: "check_lint",
+        description: "Run the project's linter (e.g., ESLint).",
+        inputSchema: zodToMcpSchema(schemas.CheckLintSchema),
     },
+    // Control Plane
     {
-        name: "log_agent_action",
-        description: "Log an agent action to the framework logs.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                agent: { type: "string", description: "The agent name (e.g., @manager, @backend)" },
-                action: { type: "string", description: "Action type or name" },
-                traceId: { type: "string", description: "The active Trace ID" },
-                status: { type: "string", enum: ["SUCCESS", "FAILURE"], description: "The status of the action" },
-                summary: { type: "string", description: "Brief description of the action taken" },
-                findings: { type: "string", description: "Optional comma-separated findings or details" }
-            },
-            required: ["agent", "action", "traceId", "status", "summary"]
-        }
+        name: "acquire_lock",
+        description: "Acquire a stateful lock on a shared resource.",
+        inputSchema: zodToMcpSchema(schemas.AcquireLockSchema),
     },
     {
-        name: "update_contract_hash",
-        description: "Re-generate and synchronize the backend contract SHA-256 hash.",
-        inputSchema: { type: "object", properties: {} }
+        name: "release_lock",
+        description: "Release a previously acquired lock.",
+        inputSchema: zodToMcpSchema(schemas.ReleaseLockSchema),
     },
     {
-        name: "run_shell_command",
-        description: "Execute a shell command. For security, only a limited set of commands are allowed.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                command: { type: "string", description: "The shell command to execute." },
-            },
-            required: ["command"],
-        },
+        name: "register_agent",
+        description: "Register an agent instance with the Control Plane.",
+        inputSchema: zodToMcpSchema(schemas.RegisterAgentSchema),
     },
+    // Messaging (Hermes)
     {
-        name: "check_lint",
-        description: "Run the project's linter (e.g., ESLint) to check for code quality and style issues.",
-        inputSchema: { type: "object", properties: {} },
+        name: "send_agent_message",
+        description: "Send a Hermes protocol message to another agent.",
+        inputSchema: zodToMcpSchema(schemas.SendAgentMessageSchema),
     },
     {
-        name: "submit_plan",
-        description: "Submit a structured DAG plan of tasks for the project. This will be decomposed and queued for execution.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                tasks: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            id: { type: "string", description: "Unique task ID (e.g. TASK_01)" },
-                            agent: { type: "string", description: "The agent responsible for the task (e.g. @backend)" },
-                            task: { type: "string", description: "The task description" },
-                            dependencies: {
-                                type: "array",
-                                items: { type: "string" },
-                                description: "List of task IDs that must be completed before this task."
-                            }
-                        },
-                        required: ["id", "agent", "task"]
-                    }
-                }
-            },
-            required: ["tasks"],
-        },
+        name: "log_agent_action",
+        description: "Log an agent action to the framework logs.",
+        inputSchema: zodToMcpSchema(schemas.LogAgentActionSchema),
     },
-    {
-        name: "view_file",
-        description: "Alias for read_file. Reads the content of a file within the project.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file relative to project root" },
-                startLine: { type: "number", description: "Optional starting line number (1-indexed)" },
-                endLine: { type: "number", description: "Optional ending line number (inclusive)" },
-            },
-            required: ["path"],
-        },
-    }
 ];

package/framework-mcp/dist/tools/index.js

@@ -25,6 +25,7 @@ import { handleAcquireLock, handleReleaseLock } from "./control_plane/locking.js
 import { handleRegisterAgent } from "./control_plane/registry.js";
 import { handleRunCommand } from "./shell/run_command.js";
 import { handleCheckLint } from "./quality/check_lint.js";
+import * as schemas from "./schemas.js";
 // Map of tool names to their handler functions
 const bind = (fn) => {
     return (root, args) => fn(root, args);
@@ -59,4 +60,40 @@ export const toolHandlers = {
     run_shell_command: bind(handleRunCommand),
     check_lint: bind(handleCheckLint),
 };
+// Map of tool names to their Zod validation schemas
+export const toolSchemas = {
+    // File System
+    read_file: schemas.ReadFileSchema,
+    view_file: schemas.ReadFileSchema,
+    write_file: schemas.WriteFileSchema,
+    replace_text: schemas.ReplaceTextSchema,
+    batch_surgical_edit: schemas.BatchSurgicalEditSchema,
+    patch_file: schemas.PatchFileSchema,
+    // Search & Exploration
+    list_dir: schemas.ListDirSchema,
+    grep_search: schemas.GrepSearchSchema,
+    get_project_map: schemas.GetProjectMapSchema,
+    get_project_gaps: schemas.GetProjectGapsSchema,
+    // Framework & System
+    run_shell_command: schemas.RunShellCommandSchema,
+    run_tests: schemas.RunTestsSchema,
+    get_system_health: schemas.GetSystemHealthSchema,
+    check_active_ports: schemas.CheckPortsSchema,
+    get_framework_status: schemas.GetFrameworkStatusSchema,
+    read_project_memory: schemas.ReadProjectMemorySchema,
+    get_memory_insights: schemas.GetMemoryInsightsSchema,
+    update_project_memory: schemas.UpdateProjectMemorySchema,
+    orchestrate_loop: schemas.OrchestrateLoopSchema,
+    submit_plan: schemas.SubmitPlanSchema,
+    update_contract_hash: schemas.UpdateContractHashSchema,
+    audit_dependencies: schemas.AuditDependenciesSchema,
+    check_lint: schemas.CheckLintSchema,
+    // Control Plane
+    acquire_lock: schemas.AcquireLockSchema,
+    release_lock: schemas.ReleaseLockSchema,
+    register_agent: schemas.RegisterAgentSchema,
+    // Messaging (Hermes)
+    send_agent_message: schemas.SendAgentMessageSchema,
+    log_agent_action: schemas.LogAgentActionSchema,
+};
 export { TOOLS };

package/framework-mcp/dist/tools/schemas.js

@@ -0,0 +1,133 @@
+import { z } from "zod";
+/**
+ * ─── ATABEY BRANDED TYPES ─────────────────────────────────────────
+ * Using Zod's .brand() to ensure compile-time and runtime safety.
+ * These types represent the "System DNA".
+ */
+export const AgentIDSchema = z.string()
+    .regex(/^@[a-zA-Z0-9_-]+$/, "AgentID must start with '@' followed by alphanumeric characters/underscores.")
+    .brand();
+export const TraceIDSchema = z.string()
+    .min(1, "TraceID cannot be empty")
+    .brand();
+export const TaskIDSchema = z.string()
+    .regex(/^TASK-[0-9]+$/, "TaskID must follow the format 'TASK-001'.")
+    .brand();
+export const PhaseIDSchema = z.enum(["PHASE_0", "PHASE_1", "PHASE_2", "PHASE_3", "PHASE_4"])
+    .brand();
+/**
+ * ─── TOOL CONTRACTS ────────────────────────────────────────────────
+ * Every tool must have a strict schema defining its boundary.
+ * No unknown properties are allowed (.strict()).
+ */
+// ─── File System
+export const ReadFileSchema = z.object({
+    path: z.string().min(1, "Path is required"),
+    startLine: z.number().int().positive().optional(),
+    endLine: z.number().int().positive().optional(),
+}).strict();
+export const WriteFileSchema = z.object({
+    path: z.string().min(1, "Path is required"),
+    content: z.string(),
+}).strict();
+export const ReplaceTextSchema = z.object({
+    path: z.string().min(1, "Path is required"),
+    oldText: z.string().min(1, "oldText is required"),
+    newText: z.string(),
+    allowMultiple: z.boolean().default(false),
+}).strict();
+// ─── Search & Exploration
+export const ListDirSchema = z.object({
+    path: z.string().default("."),
+}).strict();
+export const GrepSearchSchema = z.object({
+    pattern: z.string().min(1, "Pattern is required"),
+    includePattern: z.string().optional(),
+    excludePattern: z.string().optional(),
+}).strict();
+export const GetProjectMapSchema = z.object({
+    maxDepth: z.number().int().positive().default(3),
+    includeFiles: z.boolean().default(true),
+}).strict();
+export const GetProjectGapsSchema = z.object({
+    path: z.string().default("src"),
+}).strict();
+// ─── Batch & Patch
+export const BatchSurgicalEditSchema = z.object({
+    edits: z.array(z.object({
+        path: z.string().min(1),
+        oldText: z.string().min(1),
+        newText: z.string(),
+        allowMultiple: z.boolean().default(false),
+    })),
+}).strict();
+export const PatchFileSchema = z.object({
+    path: z.string().min(1),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    newContent: z.string(),
+}).strict();
+// ─── Framework & System
+export const RunShellCommandSchema = z.object({
+    command: z.string().min(1),
+}).strict();
+export const RunTestsSchema = z.object({
+    command: z.string().optional(),
+}).strict();
+export const GetSystemHealthSchema = z.object({}).strict();
+export const CheckPortsSchema = z.object({
+    filter: z.string().optional(),
+}).strict();
+export const GetFrameworkStatusSchema = z.object({}).strict();
+export const ReadProjectMemorySchema = z.object({}).strict();
+export const GetMemoryInsightsSchema = z.object({}).strict();
+export const UpdateProjectMemorySchema = z.object({
+    section: z.string().min(1),
+    content: z.string().min(1),
+}).strict();
+export const OrchestrateLoopSchema = z.object({}).strict();
+export const SubmitPlanSchema = z.object({
+    tasks: z.array(z.object({
+        id: TaskIDSchema,
+        agent: AgentIDSchema,
+        task: z.string().min(1),
+        dependencies: z.array(TaskIDSchema).optional(),
+    })),
+}).strict();
+export const AcquireLockSchema = z.object({
+    resource: z.string().min(1),
+    agent: AgentIDSchema,
+    ttl: z.number().int().positive().default(60),
+}).strict();
+export const ReleaseLockSchema = z.object({
+    resource: z.string().min(1),
+    agent: AgentIDSchema,
+}).strict();
+export const RegisterAgentSchema = z.object({
+    agent: AgentIDSchema,
+    role: z.string().min(1),
+    capability: z.number().int().min(1).max(10).default(5),
+    specialties: z.record(z.number()).optional(),
+}).strict();
+export const UpdateContractHashSchema = z.object({}).strict();
+export const AuditDependenciesSchema = z.object({}).strict();
+export const CheckLintSchema = z.object({}).strict();
+// ─── Messaging (Hermes)
+export const SendAgentMessageSchema = z.object({
+    from: AgentIDSchema,
+    to: AgentIDSchema,
+    category: z.enum(["ACTION", "DELEGATION", "SUBTASK", "REPLY", "ALERT"]),
+    content: z.string().min(1, "Content cannot be empty"),
+    traceId: TraceIDSchema,
+    parentId: TaskIDSchema.optional(),
+    priority: z.enum(["HIGH", "NORMAL", "LOW"]).default("NORMAL"),
+    requiresApproval: z.boolean().default(false),
+}).strict();
+export const LogAgentActionSchema = z.object({
+    agent: AgentIDSchema,
+    action: z.string().min(1),
+    traceId: TraceIDSchema,
+    status: z.enum(["SUCCESS", "FAILURE"]),
+    summary: z.string().min(1),
+    findings: z.string().optional(),
+}).strict();

package/framework-mcp/dist/utils/types.js

@@ -10,3 +10,7 @@ export function asTraceID(val) { return val; }
 export function asAgentID(val) { return val; }
 export function asPhaseID(val) { return val; }
 export function asProjectPath(val) { return val; }
+export function asMessageID(val) { return val; }
+export function asTaskID(val) { return val; }
+export function asLogID(val) { return val; }
+export function asPlanID(val) { return val; }