@accelerationguy/accel 1.0.0

package/modules/momentum/src/packages/momentum-mcp/tools/state.js

@@ -0,0 +1,199 @@
+/**
+ * Mission Control State — Read/update tools for state.json
+ * Workspace health, drift tracking, groom scheduling
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+function debugLog(...args) {
+    console.error('[Momentum:state]', new Date().toISOString(), ...args);
+}
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+function getStatePath(workspacePath) {
+    return join(workspacePath, '.accel/momentum', 'data', 'state.json');
+}
+
+function readState(workspacePath) {
+    const filepath = getStatePath(workspacePath);
+    if (!existsSync(filepath)) {
+        return { version: 1, workspace: '', last_modified: null, groom: {}, drift: { score: 0, indicators: {} }, areas: {}, satellites: {} };
+    }
+    try {
+        return JSON.parse(readFileSync(filepath, 'utf-8'));
+    } catch (error) {
+        debugLog('Error reading state.json:', error.message);
+        return { version: 1, workspace: '', last_modified: null, groom: {}, drift: { score: 0, indicators: {} }, areas: {}, satellites: {} };
+    }
+}
+
+function writeState(workspacePath, data) {
+    const filepath = getStatePath(workspacePath);
+    data.last_modified = new Date().toISOString();
+    writeFileSync(filepath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+function addDays(dateStr, days) {
+    const d = new Date(dateStr);
+    d.setDate(d.getDate() + days);
+    return d.toISOString().split('T')[0];
+}
+
+function todayStr() {
+    return new Date().toISOString().split('T')[0];
+}
+
+// ============================================================
+// TOOL DEFINITIONS
+// ============================================================
+
+export const TOOLS = [
+    {
+        name: "momentum_get_state",
+        description: "Read full workspace state (groom, drift, areas, satellites, vector_hygiene). Returns entire state.json.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: "momentum_update_drift",
+        description: "Update drift indicators and recalculate composite score. Pass indicator key-value pairs to merge.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                indicators: {
+                    type: "object",
+                    description: "Drift indicator updates (e.g., { active_age_days: 2, backlog_past_review: 3 })"
+                }
+            },
+            required: ["indicators"]
+        }
+    },
+    {
+        name: "momentum_record_groom",
+        description: "Record a groom event. Sets last_groom to today and advances next_groom_due based on cadence.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: []
+        }
+    },
+    {
+        name: "momentum_update_area",
+        description: "Update a specific workspace area's fields (status, last_touched, groom_due, etc.).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                area: { type: "string", description: "Area slug (key in state.json areas object)" },
+                data: { type: "object", description: "Fields to merge into the area object" }
+            },
+            required: ["area", "data"]
+        }
+    }
+];
+
+// ============================================================
+// TOOL HANDLERS
+// ============================================================
+
+function handleGetState(workspacePath) {
+    debugLog('Reading state');
+    return readState(workspacePath);
+}
+
+function handleUpdateDrift(args, workspacePath) {
+    const { indicators } = args;
+    if (!indicators) throw new Error('Missing required parameter: indicators');
+
+    debugLog('Updating drift indicators');
+    const data = readState(workspacePath);
+
+    if (!data.drift) data.drift = { score: 0, indicators: {} };
+    if (!data.drift.indicators) data.drift.indicators = {};
+
+    // Merge indicators
+    data.drift.indicators = { ...data.drift.indicators, ...indicators };
+
+    // Recalculate score as sum of all indicator values
+    data.drift.score = Object.values(data.drift.indicators)
+        .reduce((sum, val) => sum + (typeof val === 'number' ? val : 0), 0);
+
+    writeState(workspacePath, data);
+
+    return {
+        score: data.drift.score,
+        indicators: data.drift.indicators
+    };
+}
+
+function handleRecordGroom(workspacePath) {
+    debugLog('Recording groom event');
+    const data = readState(workspacePath);
+
+    if (!data.groom) data.groom = { cadence: 'weekly', day: 'friday' };
+
+    const today = todayStr();
+    data.groom.last_groom = today;
+
+    // Calculate next due based on cadence
+    const cadenceDays = {
+        daily: 1,
+        weekly: 7,
+        'bi-weekly': 14,
+        monthly: 30
+    };
+    const days = cadenceDays[data.groom.cadence] || 7;
+    data.groom.next_groom_due = addDays(today, days);
+
+    writeState(workspacePath, data);
+
+    return {
+        last_groom: data.groom.last_groom,
+        next_groom_due: data.groom.next_groom_due,
+        cadence: data.groom.cadence
+    };
+}
+
+function handleUpdateArea(args, workspacePath) {
+    const { area, data: updateData } = args;
+    if (!area) throw new Error('Missing required parameter: area');
+    if (!updateData) throw new Error('Missing required parameter: data');
+
+    debugLog('Updating area:', area);
+    const data = readState(workspacePath);
+
+    if (!data.areas) data.areas = {};
+    if (!data.areas[area]) {
+        throw new Error(`Area "${area}" not found. Available: ${Object.keys(data.areas).join(', ') || 'none'}`);
+    }
+
+    data.areas[area] = { ...data.areas[area], ...updateData };
+    writeState(workspacePath, data);
+
+    return data.areas[area];
+}
+
+// ============================================================
+// HANDLER DISPATCH
+// ============================================================
+
+export function handleTool(name, args, workspacePath) {
+    switch (name) {
+        case 'momentum_get_state':
+            return handleGetState(workspacePath);
+        case 'momentum_update_drift':
+            return handleUpdateDrift(args, workspacePath);
+        case 'momentum_record_groom':
+            return handleRecordGroom(workspacePath);
+        case 'momentum_update_area':
+            return handleUpdateArea(args, workspacePath);
+        default:
+            return null;
+    }
+}

package/modules/momentum/src/packages/momentum-mcp/tools/surfaces.js

@@ -0,0 +1,404 @@
+/**
+ * Momentum 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('[Momentum:surfaces]', new Date().toISOString(), ...args);
+}
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+function getWorkspaceJson(workspacePath) {
+    const filepath = join(workspacePath, '.accel/momentum', '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, '.accel/momentum', 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: "momentum_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: "momentum_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: "momentum_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: "momentum_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: "momentum_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: "momentum_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: "momentum_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, '.accel/momentum', 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, '.accel/momentum', 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 'momentum_list_surfaces':
+            return handleListSurfaces(workspacePath);
+        case 'momentum_get_surface':
+            return handleGetSurface(args, workspacePath);
+        case 'momentum_get_item':
+            return handleGetItem(args, workspacePath);
+        case 'momentum_add_item':
+            return handleAddItem(args, workspacePath);
+        case 'momentum_update_item':
+            return handleUpdateItem(args, workspacePath);
+        case 'momentum_archive_item':
+            return handleArchiveItem(args, workspacePath);
+        case 'momentum_search':
+            return handleSearch(args, workspacePath);
+        default:
+            return null;
+    }
+}