@chrisai/base 2.3.0

package/src/hooks/satellite-detection.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Hook: satellite-detection.py
+Purpose: Session-start hook that scans the workspace recursively for .paul/paul.json
+         files, cross-references registered satellites in workspace.json, and
+         auto-registers any unregistered projects it finds.
+Triggers: UserPromptSubmit (session context)
+Output: <base-satellites> block if new satellites registered, silent otherwise.
+"""
+
+import sys
+import json
+from datetime import datetime
+from pathlib import Path
+
+# Workspace root — find .base/ relative to this hook's location
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent  # hooks/ -> .base/ -> workspace
+BASE_DIR = WORKSPACE_ROOT / ".base"
+MANIFEST_FILE = BASE_DIR / "workspace.json"
+
+
+def has_hidden_component(path: Path, workspace_root: Path) -> bool:
+    """
+    Return True if any component of path (relative to workspace_root) starts with '.',
+    excluding '.paul' itself (which is the expected target directory).
+    """
+    try:
+        rel = path.relative_to(workspace_root)
+    except ValueError:
+        return True  # Can't relativize — skip it
+    return any(part.startswith(".") and part != ".paul" for part in rel.parts)
+
+
+def find_paul_json_files(workspace_root: Path) -> list[Path]:
+    """
+    Recursively scan workspace_root for .paul/paul.json files.
+    Skips any path that has a hidden directory component (starts with '.').
+    """
+    results = []
+    try:
+        for paul_json in workspace_root.rglob(".paul/paul.json"):
+            if not has_hidden_component(paul_json, workspace_root):
+                results.append(paul_json)
+    except (OSError, PermissionError):
+        pass
+    return results
+
+
+def main():
+    # Skip if BASE is not installed
+    if not BASE_DIR.exists() or not MANIFEST_FILE.exists():
+        sys.exit(0)
+
+    try:
+        with open(MANIFEST_FILE, "r") as f:
+            manifest = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    satellites = manifest.get("satellites", {})
+    new_registrations = []
+    activity_refreshed = []
+
+    paul_files = find_paul_json_files(WORKSPACE_ROOT)
+
+    for paul_json_path in paul_files:
+        try:
+            with open(paul_json_path, "r") as f:
+                paul_data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            continue  # Malformed or unreadable — skip silently
+
+        name = paul_data.get("name")
+        if not name:
+            continue  # No name field — skip
+
+        # Read last_activity from paul.json timestamps (if present)
+        last_activity = paul_data.get("timestamps", {}).get("updated_at")
+
+        if name in satellites:
+            # Already registered — refresh last_activity if available
+            if last_activity and satellites[name].get("last_activity") != last_activity:
+                satellites[name]["last_activity"] = last_activity
+                activity_refreshed.append(name)
+            continue
+
+        # New satellite — derive relative path
+        project_dir = paul_json_path.parent.parent
+        try:
+            rel_path = str(project_dir.relative_to(WORKSPACE_ROOT))
+        except ValueError:
+            continue  # Can't relativize — skip
+
+        # Build registration entry
+        entry = {
+            "path": rel_path,
+            "engine": "paul",
+            "state": f"{rel_path}/.paul/STATE.md",
+            "registered": datetime.now().strftime("%Y-%m-%d"),
+            "groom_check": True,
+        }
+        if last_activity:
+            entry["last_activity"] = last_activity
+
+        satellites[name] = entry
+        new_registrations.append(name)
+
+    if new_registrations or activity_refreshed:
+        # Write updated manifest
+        try:
+            manifest["satellites"] = satellites
+            with open(MANIFEST_FILE, "w") as f:
+                json.dump(manifest, f, indent=2)
+                f.write("\n")
+        except OSError:
+            sys.exit(0)  # Write failed — silent exit
+
+    if new_registrations:
+        names_str = ", ".join(new_registrations)
+        n = len(new_registrations)
+        print(f"<base-satellites>\nAuto-registered {n} new satellite(s): {names_str}\n</base-satellites>")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        sys.exit(0)

package/src/packages/base-mcp/index.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * BASE MCP — Surface CRUD Server
+ * Builder's Automated State Engine
+ *
+ * Generic CRUD operations for any registered data surface.
+ * Surfaces are registered in workspace.json and stored as JSON in .base/data/.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Tool group imports
+import { TOOLS as surfaceTools, handleTool as handleSurface } from './tools/surfaces.js';
+
+// ============================================================
+// CONFIGURATION
+// ============================================================
+
+// Resolve workspace from this file's location: base-mcp/ → .base/ → workspace root
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_PATH = path.resolve(__dirname, '../..');
+
+function debugLog(...args) {
+    console.error('[BASE]', new Date().toISOString(), ...args);
+}
+
+// ============================================================
+// TOOL REGISTRY
+// ============================================================
+
+const ALL_TOOLS = [...surfaceTools];
+
+// Build handler lookup: tool name → handler function
+const TOOL_HANDLERS = {};
+for (const tool of surfaceTools) TOOL_HANDLERS[tool.name] = handleSurface;
+
+// ============================================================
+// MCP SERVER
+// ============================================================
+
+const server = new Server({
+    name: "base-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+
+debugLog('BASE MCP Server initialized');
+debugLog('Workspace:', WORKSPACE_PATH);
+debugLog('Surface tools:', surfaceTools.length);
+debugLog('Total tools:', ALL_TOOLS.length);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    debugLog('List tools request');
+    return { tools: ALL_TOOLS };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    debugLog('Call tool:', name);
+
+    try {
+        const handler = TOOL_HANDLERS[name];
+        if (!handler) {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+
+        const result = await handler(name, args || {}, WORKSPACE_PATH);
+
+        if (result === null) {
+            throw new Error(`Tool ${name} returned null — handler mismatch`);
+        }
+
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: false,
+        };
+    } catch (error) {
+        debugLog('Error:', error.message);
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+
+// ============================================================
+// RUN
+// ============================================================
+
+async function runServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("BASE MCP Server running on stdio");
+}
+
+try {
+    await runServer();
+} catch (error) {
+    console.error("Fatal error:", error);
+    process.exit(1);
+}

package/src/packages/base-mcp/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "base-mcp",
+  "version": "1.0.0",
+  "description": "BASE Surface CRUD Server - Generic operations for registered data surfaces",
+  "type": "module",
+  "main": "index.js",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/src/packages/base-mcp/tools/surfaces.js

@@ -0,0 +1,404 @@
+/**
+ * BASE Surfaces — Generic CRUD tools for registered data surfaces
+ * Operates on any surface registered in workspace.json
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+function debugLog(...args) {
+    console.error('[BASE:surfaces]', new Date().toISOString(), ...args);
+}
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+function getWorkspaceJson(workspacePath) {
+    const filepath = join(workspacePath, '.base', 'workspace.json');
+    if (!existsSync(filepath)) {
+        throw new Error('workspace.json not found at ' + filepath);
+    }
+    try {
+        return JSON.parse(readFileSync(filepath, 'utf-8'));
+    } catch (error) {
+        throw new Error('Failed to parse workspace.json: ' + error.message);
+    }
+}
+
+function getSurfaceConfig(workspacePath, surface) {
+    const ws = getWorkspaceJson(workspacePath);
+    const surfaces = ws.surfaces || {};
+    const config = surfaces[surface];
+    if (!config) {
+        throw new Error(`Surface "${surface}" is not registered in workspace.json. Registered surfaces: ${Object.keys(surfaces).join(', ') || 'none'}`);
+    }
+    return config;
+}
+
+function getSurfacePath(workspacePath, config) {
+    return join(workspacePath, '.base', config.file);
+}
+
+function readSurface(workspacePath, surface) {
+    const config = getSurfaceConfig(workspacePath, surface);
+    const filepath = getSurfacePath(workspacePath, config);
+    if (!existsSync(filepath)) {
+        return { surface, version: 1, last_modified: null, items: [], archived: [] };
+    }
+    try {
+        return JSON.parse(readFileSync(filepath, 'utf-8'));
+    } catch (error) {
+        debugLog(`Error reading ${surface} data:`, error.message);
+        return { surface, version: 1, last_modified: null, items: [], archived: [] };
+    }
+}
+
+function writeSurface(workspacePath, surface, data) {
+    const config = getSurfaceConfig(workspacePath, surface);
+    const filepath = getSurfacePath(workspacePath, config);
+    data.last_modified = formatTimestamp();
+    writeFileSync(filepath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+function generateId(prefix, items) {
+    let max = 0;
+    for (const item of items) {
+        const id = item.id || '';
+        const match = id.match(new RegExp(`^${prefix}-(\\d+)$`));
+        if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > max) max = num;
+        }
+    }
+    return `${prefix}-${String(max + 1).padStart(3, '0')}`;
+}
+
+function formatTimestamp() {
+    return new Date().toISOString();
+}
+
+// ============================================================
+// TOOL DEFINITIONS
+// ============================================================
+
+export const TOOLS = [
+    {
+        name: "base_list_surfaces",
+        description: "List all registered data surfaces from workspace.json with item counts. Returns surface names, descriptions, and current item counts.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: "base_get_surface",
+        description: "Read all items from a registered data surface. Returns the full surface object including metadata, items array, and archived array.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                surface: {
+                    type: "string",
+                    description: "Surface name (e.g., 'active', 'backlog')"
+                }
+            },
+            required: ["surface"]
+        }
+    },
+    {
+        name: "base_get_item",
+        description: "Get a specific item by ID from a data surface.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                surface: {
+                    type: "string",
+                    description: "Surface name (e.g., 'active', 'backlog')"
+                },
+                id: {
+                    type: "string",
+                    description: "Item ID (e.g., 'ACT-001', 'BL-003')"
+                }
+            },
+            required: ["surface", "id"]
+        }
+    },
+    {
+        name: "base_add_item",
+        description: "Add a new item to a data surface. Auto-generates ID from surface schema's id_prefix. Validates required fields if schema defines them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                surface: {
+                    type: "string",
+                    description: "Surface name (e.g., 'active', 'backlog')"
+                },
+                data: {
+                    type: "object",
+                    description: "Item data object with fields matching the surface schema"
+                }
+            },
+            required: ["surface", "data"]
+        }
+    },
+    {
+        name: "base_update_item",
+        description: "Update an existing item's fields by ID. Performs shallow merge — only specified fields are updated, others preserved.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                surface: {
+                    type: "string",
+                    description: "Surface name (e.g., 'active', 'backlog')"
+                },
+                id: {
+                    type: "string",
+                    description: "Item ID to update"
+                },
+                data: {
+                    type: "object",
+                    description: "Fields to update (shallow merge onto existing item)"
+                }
+            },
+            required: ["surface", "id", "data"]
+        }
+    },
+    {
+        name: "base_archive_item",
+        description: "Archive an item by ID — removes from items array and moves to archived array with timestamp.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                surface: {
+                    type: "string",
+                    description: "Surface name (e.g., 'active', 'backlog')"
+                },
+                id: {
+                    type: "string",
+                    description: "Item ID to archive"
+                }
+            },
+            required: ["surface", "id"]
+        }
+    },
+    {
+        name: "base_search",
+        description: "Search across one or all registered surfaces by keyword. Case-insensitive substring match across all string fields in each item.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query (case-insensitive substring match)"
+                },
+                surface: {
+                    type: "string",
+                    description: "Optional: limit search to one surface. Omit to search all."
+                }
+            },
+            required: ["query"]
+        }
+    }
+];
+
+// ============================================================
+// TOOL HANDLERS
+// ============================================================
+
+function handleListSurfaces(workspacePath) {
+    const ws = getWorkspaceJson(workspacePath);
+    const surfaces = ws.surfaces || {};
+    const result = [];
+
+    for (const [name, config] of Object.entries(surfaces)) {
+        const filepath = join(workspacePath, '.base', config.file);
+        let itemsCount = 0;
+        if (existsSync(filepath)) {
+            try {
+                const data = JSON.parse(readFileSync(filepath, 'utf-8'));
+                itemsCount = (data.items || []).length;
+            } catch { /* ignore parse errors */ }
+        }
+        result.push({
+            name,
+            description: config.description || '',
+            file: config.file,
+            items_count: itemsCount,
+            hook: config.hook || false
+        });
+    }
+
+    return { surfaces: result, count: result.length };
+}
+
+function handleGetSurface(args, workspacePath) {
+    const { surface } = args;
+    if (!surface) throw new Error('Missing required parameter: surface');
+    return readSurface(workspacePath, surface);
+}
+
+function handleGetItem(args, workspacePath) {
+    const { surface, id } = args;
+    if (!surface) throw new Error('Missing required parameter: surface');
+    if (!id) throw new Error('Missing required parameter: id');
+
+    const data = readSurface(workspacePath, surface);
+    const item = data.items.find(i => i.id === id);
+    if (!item) {
+        throw new Error(`Item "${id}" not found in surface "${surface}". Available IDs: ${data.items.map(i => i.id).join(', ') || 'none'}`);
+    }
+    return item;
+}
+
+function handleAddItem(args, workspacePath) {
+    const { surface, data: itemData } = args;
+    if (!surface) throw new Error('Missing required parameter: surface');
+    if (!itemData) throw new Error('Missing required parameter: data');
+
+    const config = getSurfaceConfig(workspacePath, surface);
+    const schema = config.schema || {};
+
+    // Validate required fields
+    if (schema.required_fields) {
+        for (const field of schema.required_fields) {
+            if (itemData[field] === undefined || itemData[field] === null || itemData[field] === '') {
+                throw new Error(`Missing required field "${field}" for surface "${surface}". Required: ${schema.required_fields.join(', ')}`);
+            }
+        }
+    }
+
+    const surfaceData = readSurface(workspacePath, surface);
+
+    // Generate ID
+    const prefix = schema.id_prefix || surface.toUpperCase().slice(0, 3);
+    const newId = generateId(prefix, surfaceData.items);
+
+    const newItem = {
+        id: newId,
+        ...itemData,
+        added: formatTimestamp()
+    };
+
+    surfaceData.items.push(newItem);
+    writeSurface(workspacePath, surface, surfaceData);
+
+    debugLog(`Added item ${newId} to ${surface}`);
+    return newItem;
+}
+
+function handleUpdateItem(args, workspacePath) {
+    const { surface, id, data: updateData } = args;
+    if (!surface) throw new Error('Missing required parameter: surface');
+    if (!id) throw new Error('Missing required parameter: id');
+    if (!updateData) throw new Error('Missing required parameter: data');
+
+    const surfaceData = readSurface(workspacePath, surface);
+    const index = surfaceData.items.findIndex(i => i.id === id);
+    if (index === -1) {
+        throw new Error(`Item "${id}" not found in surface "${surface}"`);
+    }
+
+    // Shallow merge — preserve existing fields, update specified ones
+    surfaceData.items[index] = {
+        ...surfaceData.items[index],
+        ...updateData,
+        id, // Prevent ID overwrite
+        updated: formatTimestamp()
+    };
+
+    writeSurface(workspacePath, surface, surfaceData);
+
+    debugLog(`Updated item ${id} in ${surface}`);
+    return surfaceData.items[index];
+}
+
+function handleArchiveItem(args, workspacePath) {
+    const { surface, id } = args;
+    if (!surface) throw new Error('Missing required parameter: surface');
+    if (!id) throw new Error('Missing required parameter: id');
+
+    const surfaceData = readSurface(workspacePath, surface);
+    const index = surfaceData.items.findIndex(i => i.id === id);
+    if (index === -1) {
+        throw new Error(`Item "${id}" not found in surface "${surface}"`);
+    }
+
+    // Remove from items
+    const [item] = surfaceData.items.splice(index, 1);
+    item.archived = formatTimestamp();
+
+    // Add to archived array
+    if (!surfaceData.archived) surfaceData.archived = [];
+    surfaceData.archived.push(item);
+
+    writeSurface(workspacePath, surface, surfaceData);
+
+    debugLog(`Archived item ${id} from ${surface}`);
+    return item;
+}
+
+function handleSearch(args, workspacePath) {
+    const { query, surface: targetSurface } = args;
+    if (!query) throw new Error('Missing required parameter: query');
+
+    const ws = getWorkspaceJson(workspacePath);
+    const surfaces = ws.surfaces || {};
+    const queryLower = query.toLowerCase();
+    const results = [];
+
+    const surfacesToSearch = targetSurface
+        ? { [targetSurface]: getSurfaceConfig(workspacePath, targetSurface) }
+        : surfaces;
+
+    for (const [name, config] of Object.entries(surfacesToSearch)) {
+        const filepath = join(workspacePath, '.base', config.file);
+        if (!existsSync(filepath)) continue;
+
+        let data;
+        try {
+            data = JSON.parse(readFileSync(filepath, 'utf-8'));
+        } catch { continue; }
+
+        for (const item of (data.items || [])) {
+            for (const [field, value] of Object.entries(item)) {
+                if (typeof value === 'string' && value.toLowerCase().includes(queryLower)) {
+                    results.push({
+                        surface: name,
+                        id: item.id,
+                        title: item.title || item.id,
+                        match_field: field
+                    });
+                    break; // One match per item is enough
+                }
+            }
+        }
+    }
+
+    return { results, count: results.length, query };
+}
+
+// ============================================================
+// HANDLER DISPATCH
+// ============================================================
+
+export function handleTool(name, args, workspacePath) {
+    switch (name) {
+        case 'base_list_surfaces':
+            return handleListSurfaces(workspacePath);
+        case 'base_get_surface':
+            return handleGetSurface(args, workspacePath);
+        case 'base_get_item':
+            return handleGetItem(args, workspacePath);
+        case 'base_add_item':
+            return handleAddItem(args, workspacePath);
+        case 'base_update_item':
+            return handleUpdateItem(args, workspacePath);
+        case 'base_archive_item':
+            return handleArchiveItem(args, workspacePath);
+        case 'base_search':
+            return handleSearch(args, workspacePath);
+        default:
+            return null;
+    }
+}