hammoc 1.4.0 → 1.5.0

package/packages/server/dist/controllers/snippetController.js

@@ -0,0 +1,294 @@
+/**
+ * Story 29.2: Snippet management controller.
+ *
+ * Mounts at `/api/snippets/*` (NOT `/api/harness/*`) — the snippet system is
+ * Hammoc-native (`%name%` chat-input expansion via `snippetResolver`), not a
+ * Claude Code harness primitive, so its API namespace is intentionally
+ * separate from `/api/harness/snippets` to keep intent boundaries crisp.
+ *
+ * Error envelope mirrors `claudeMdController` and `harnessController` so the
+ * client can route both response shapes through the same error-display logic:
+ *   `{ error: { code, message, details? } }`
+ *
+ * Origin-socket broadcast (AC1.e): mutation endpoints (POST/PUT/DELETE/copy)
+ * read `X-Hammoc-Socket-Id` and `X-Hammoc-Working-Directory` headers and
+ * forward them to `broadcastSnippetList()` so the originating client's
+ * autocomplete surfaces (`SnippetPalette` via `useSnippets`) re-receive a
+ * fresh `snippets:list` payload without an explicit `refresh()` call.
+ * Phase-1 fan-out is single-socket; multi-tab sync is deferred (story AC1.e).
+ */
+import { z } from 'zod';
+import { HARNESS_ERRORS } from '@hammoc/shared';
+import { snippetService } from '../services/snippetService.js';
+import { broadcastSnippetList } from '../handlers/websocket.js';
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+const SCOPE_SCHEMA = z.enum(['project', 'user', 'bundled']);
+const MUTABLE_SCOPE_SCHEMA = z.enum(['project', 'user']);
+const refParamsSchema = z
+    .object({
+    scope: SCOPE_SCHEMA,
+    name: z.string().min(1),
+});
+const refQuerySchema = z.object({
+    projectSlug: z.string().optional(),
+});
+const listQuerySchema = z.object({
+    projectSlug: z.string().optional(),
+});
+const writeBodySchema = z.object({
+    content: z.string(),
+    expectedMtime: z.string().optional(),
+    projectSlug: z.string().optional(),
+});
+const deleteBodySchema = z.object({
+    expectedMtime: z.string().optional(),
+    projectSlug: z.string().optional(),
+});
+const copyBodySchema = z.object({
+    sourceScope: SCOPE_SCHEMA,
+    sourceName: z.string().min(1),
+    sourceProjectSlug: z.string().optional(),
+    targetScope: MUTABLE_SCOPE_SCHEMA,
+    targetName: z.string().min(1).optional(),
+    targetProjectSlug: z.string().optional(),
+    onConflict: z.enum(['abort', 'overwrite', 'rename']).optional(),
+});
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+const MAPPED_CODES = [
+    'HARNESS_PATH_DENIED',
+    'HARNESS_FORBIDDEN',
+    'HARNESS_FILE_NOT_FOUND',
+    'HARNESS_ROOT_MISSING',
+    'HARNESS_STALE_WRITE',
+    'HARNESS_FILE_EXISTS',
+    'HARNESS_BUNDLED_READONLY',
+    'HARNESS_PARSE_ERROR',
+];
+const MESSAGE_KEY = {
+    HARNESS_PATH_DENIED: 'harness.error.pathDenied',
+    HARNESS_FORBIDDEN: 'harness.error.forbidden',
+    HARNESS_FILE_NOT_FOUND: 'harness.error.fileNotFound',
+    HARNESS_ROOT_MISSING: 'harness.error.rootMissing',
+    HARNESS_STALE_WRITE: 'harness.error.staleWrite',
+    HARNESS_FILE_EXISTS: 'harness.snippets.error.fileExists',
+    HARNESS_BUNDLED_READONLY: 'harness.snippets.error.bundledReadOnly',
+    HARNESS_PARSE_ERROR: 'harness.error.parseError',
+};
+function handleError(req, res, error) {
+    const nodeError = error;
+    for (const key of MAPPED_CODES) {
+        const entry = HARNESS_ERRORS[key];
+        if (nodeError.code === entry.code) {
+            const body = {
+                code: entry.code,
+                message: req.t(MESSAGE_KEY[key]),
+            };
+            if (key === 'HARNESS_STALE_WRITE') {
+                body.details = { currentMtime: nodeError.currentMtime ?? '' };
+            }
+            if (key === 'HARNESS_FILE_NOT_FOUND' && nodeError.absolutePath) {
+                body.details = { absolutePath: nodeError.absolutePath };
+            }
+            res.status(entry.httpStatus).json({ error: body });
+            return;
+        }
+    }
+    res.status(HARNESS_ERRORS.HARNESS_WRITE_ERROR.httpStatus).json({
+        error: {
+            code: HARNESS_ERRORS.HARNESS_WRITE_ERROR.code,
+            message: req.t('harness.error.writeError'),
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseRefParams(req, res, projectSlug) {
+    const parsed = refParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+        res.status(400).json({
+            error: {
+                code: 'INVALID_REQUEST',
+                message: parsed.error.issues[0]?.message ?? 'invalid params',
+            },
+        });
+        return null;
+    }
+    if (parsed.data.scope === 'project' && !projectSlug) {
+        res.status(400).json({
+            error: {
+                code: 'INVALID_REQUEST',
+                message: 'projectSlug is required for project scope',
+            },
+        });
+        return null;
+    }
+    return {
+        scope: parsed.data.scope,
+        projectSlug: parsed.data.scope === 'project' ? projectSlug : undefined,
+        name: parsed.data.name,
+    };
+}
+function readBroadcastHeaders(req) {
+    const socketId = stringHeader(req.header('x-hammoc-socket-id'));
+    const workingDirectory = stringHeader(req.header('x-hammoc-working-directory'));
+    return { socketId, workingDirectory };
+}
+function stringHeader(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+async function emitOriginRefresh(req) {
+    const { socketId, workingDirectory } = readBroadcastHeaders(req);
+    if (!socketId || !workingDirectory)
+        return;
+    await broadcastSnippetList(workingDirectory, socketId);
+}
+// ---------------------------------------------------------------------------
+// Controller
+// ---------------------------------------------------------------------------
+export const snippetController = {
+    /** GET /api/snippets?projectSlug=<slug> */
+    async list(req, res) {
+        const parsed = listQuerySchema.safeParse(req.query);
+        if (!parsed.success) {
+            res.status(400).json({
+                error: {
+                    code: 'INVALID_REQUEST',
+                    message: parsed.error.issues[0]?.message ?? 'invalid query',
+                },
+            });
+            return;
+        }
+        try {
+            const result = await snippetService.list({ projectSlug: parsed.data.projectSlug });
+            res.json(result);
+        }
+        catch (error) {
+            handleError(req, res, error);
+        }
+    },
+    /** GET /api/snippets/:scope/:name?projectSlug=<slug> */
+    async read(req, res) {
+        const query = refQuerySchema.safeParse(req.query);
+        if (!query.success) {
+            res.status(400).json({ error: { code: 'INVALID_REQUEST', message: 'invalid query' } });
+            return;
+        }
+        const ref = parseRefParams(req, res, query.data.projectSlug);
+        if (!ref)
+            return;
+        try {
+            const result = await snippetService.read(ref);
+            res.json(result);
+        }
+        catch (error) {
+            handleError(req, res, error);
+        }
+    },
+    /** POST /api/snippets/:scope/:name  body: { content, projectSlug? } */
+    async create(req, res) {
+        const body = writeBodySchema.safeParse(req.body ?? {});
+        if (!body.success) {
+            res.status(400).json({
+                error: {
+                    code: 'INVALID_REQUEST',
+                    message: body.error.issues[0]?.message ?? 'invalid body',
+                },
+            });
+            return;
+        }
+        const ref = parseRefParams(req, res, body.data.projectSlug);
+        if (!ref)
+            return;
+        try {
+            const result = await snippetService.create(ref, { content: body.data.content });
+            await emitOriginRefresh(req);
+            res.status(201).json(result);
+        }
+        catch (error) {
+            handleError(req, res, error);
+        }
+    },
+    /** PUT /api/snippets/:scope/:name  body: { content, expectedMtime?, projectSlug? } */
+    async update(req, res) {
+        const body = writeBodySchema.safeParse(req.body ?? {});
+        if (!body.success) {
+            res.status(400).json({
+                error: {
+                    code: 'INVALID_REQUEST',
+                    message: body.error.issues[0]?.message ?? 'invalid body',
+                },
+            });
+            return;
+        }
+        const ref = parseRefParams(req, res, body.data.projectSlug);
+        if (!ref)
+            return;
+        try {
+            const result = await snippetService.update(ref, {
+                content: body.data.content,
+                expectedMtime: body.data.expectedMtime,
+            });
+            await emitOriginRefresh(req);
+            res.json(result);
+        }
+        catch (error) {
+            handleError(req, res, error);
+        }
+    },
+    /** DELETE /api/snippets/:scope/:name  body: { expectedMtime?, projectSlug? } */
+    async delete(req, res) {
+        const body = deleteBodySchema.safeParse(req.body ?? {});
+        if (!body.success) {
+            res.status(400).json({
+                error: {
+                    code: 'INVALID_REQUEST',
+                    message: body.error.issues[0]?.message ?? 'invalid body',
+                },
+            });
+            return;
+        }
+        const ref = parseRefParams(req, res, body.data.projectSlug);
+        if (!ref)
+            return;
+        try {
+            const result = await snippetService.delete(ref, {
+                expectedMtime: body.data.expectedMtime,
+            });
+            await emitOriginRefresh(req);
+            res.json(result);
+        }
+        catch (error) {
+            handleError(req, res, error);
+        }
+    },
+    /** POST /api/snippets/copy  body: SnippetCopyRequest */
+    async copy(req, res) {
+        const parsed = copyBodySchema.safeParse(req.body ?? {});
+        if (!parsed.success) {
+            res.status(400).json({
+                error: {
+                    code: 'INVALID_REQUEST',
+                    message: parsed.error.issues[0]?.message ?? 'invalid body',
+                },
+            });
+            return;
+        }
+        try {
+            const result = await snippetService.copy(parsed.data);
+            await emitOriginRefresh(req);
+            res.json(result);
+        }
+        catch (error) {
+            handleError(req, res, error);
+        }
+    },
+};
+//# sourceMappingURL=snippetController.js.map

package/packages/server/dist/controllers/snippetController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippetController.js","sourceRoot":"","sources":["../../src/controllers/snippetController.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/handlers/websocket.d.ts

@@ -82,6 +82,21 @@ export declare function initializeWebSocket(httpServer: HttpServer): Promise<Soc
  * @returns Socket.io server instance
  */
 export declare function getIO(): SocketIOServer<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>;
+/**
+ * Story 29.2 (AC1.e Phase 1): emit a fresh `snippets:list` payload to the
+ * single socket that triggered a mutation, so the originating client's
+ * SnippetPalette / useSnippets cache picks up the new state without an
+ * explicit refresh round-trip.
+ *
+ * Phase-1 limitation: only the origin socket is notified. Other tabs / browsers
+ * connected to the same project see stale data until their next user action
+ * (panel open, page reload). The Phase-2 `project:${slug}` room fan-out is
+ * deferred until ≥ 3 user reports of multi-tab divergence.
+ *
+ * Failures are swallowed — broadcast is best-effort and must not affect the
+ * REST mutation's success/failure semantics.
+ */
+export declare function broadcastSnippetList(workingDirectory: string | undefined, originSocketId: string | undefined): Promise<void>;
 /**
  * Get the current number of connected clients
  * @returns Number of connected clients

package/packages/server/dist/handlers/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/handlers/websocket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/handlers/websocket.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/handlers/websocket.js

@@ -95,6 +95,10 @@ const socketToSession = new Map();
 const socketSessionRoom = new Map();
 // Track which project room each socket joined (for leave on session switch)
 const socketProjectRoom = new Map();
+// Story 28.0.5: Track harness rooms each socket has subscribed to, so we can
+// release watcher ref counts on disconnect without leaking chokidar instances.
+// Key: socket.id → Set of "harness:user" | "harness:project:<slug>" room strings.
+const socketHarnessRooms = new Map();
 const chainState = new Map();
 // Per-session drain generation counter for race guard
 const chainDrainGeneration = new Map();
@@ -1790,6 +1794,10 @@ export async function initializeWebSocket(httpServer) {
                 socket.emit('snippets:list', { snippets: [] });
             }
         });
+        // Story 29.2: re-emit `snippets:list` after a snippet CRUD so the
+        // originating client's autocomplete surfaces stay in sync without an
+        // explicit refresh round-trip. This is the same channel the existing
+        // listener above answers, so consumers don't need a new event handler.
         // Handle project:join/leave — room for queue event delivery (Story 15.2)
         socket.on('project:join', (projectSlug) => {
             socket.join(`project:${projectSlug}`);
@@ -1802,6 +1810,37 @@ export async function initializeWebSocket(httpServer) {
                 socketProjectRoom.delete(socket.id);
             }
         });
+        // Story 28.0.5: Harness workbench subscription — one room per scope.
+        socket.on('harness:subscribe', async ({ scope, projectSlug }) => {
+            const room = scope === 'user' ? 'harness:user' : `harness:project:${projectSlug ?? ''}`;
+            await socket.join(room);
+            let rooms = socketHarnessRooms.get(socket.id);
+            if (!rooms) {
+                rooms = new Set();
+                socketHarnessRooms.set(socket.id, rooms);
+            }
+            // Idempotent subscribe: increment the watcher ref count only on the
+            // first join so disconnect cleanup matches exactly.
+            if (!rooms.has(room)) {
+                rooms.add(room);
+                try {
+                    await fileWatcherService.ensureHarnessWatcher({ scope, projectSlug });
+                }
+                catch (err) {
+                    log.warn(`harness:subscribe watcher failed for ${room}: ${String(err)}`);
+                }
+            }
+        });
+        socket.on('harness:unsubscribe', async ({ scope, projectSlug }) => {
+            const room = scope === 'user' ? 'harness:user' : `harness:project:${projectSlug ?? ''}`;
+            await socket.leave(room);
+            const rooms = socketHarnessRooms.get(socket.id);
+            if (rooms && rooms.delete(room)) {
+                fileWatcherService.releaseHarnessWatcher({ scope, projectSlug });
+                if (rooms.size === 0)
+                    socketHarnessRooms.delete(socket.id);
+            }
+        });
         // Handle queue events via WebSocket (Story 15.2)
         socket.on('queue:start', async (data) => {
             const { items, sessionId, projectSlug, permissionMode } = data;
@@ -2069,6 +2108,21 @@ export async function initializeWebSocket(httpServer) {
                 }
             }
             socketProjectRoom.delete(socket.id);
+            // Story 28.0.5: Release any harness watcher refs held by this socket so
+            // chokidar instances don't leak when a client drops without unsubscribing.
+            const harnessRooms = socketHarnessRooms.get(socket.id);
+            if (harnessRooms) {
+                for (const room of harnessRooms) {
+                    if (room === 'harness:user') {
+                        fileWatcherService.releaseHarnessWatcher({ scope: 'user' });
+                    }
+                    else if (room.startsWith('harness:project:')) {
+                        const slug = room.slice('harness:project:'.length);
+                        fileWatcherService.releaseHarnessWatcher({ scope: 'project', projectSlug: slug });
+                    }
+                }
+                socketHarnessRooms.delete(socket.id);
+            }
             // Story 25.9: Cleanup summarizing state on disconnect
             const sumState = socketSummarizing.get(socket.id);
             if (sumState?.abortController) {
@@ -2104,6 +2158,31 @@ export function getIO() {
     }
     return io;
 }
+/**
+ * Story 29.2 (AC1.e Phase 1): emit a fresh `snippets:list` payload to the
+ * single socket that triggered a mutation, so the originating client's
+ * SnippetPalette / useSnippets cache picks up the new state without an
+ * explicit refresh round-trip.
+ *
+ * Phase-1 limitation: only the origin socket is notified. Other tabs / browsers
+ * connected to the same project see stale data until their next user action
+ * (panel open, page reload). The Phase-2 `project:${slug}` room fan-out is
+ * deferred until ≥ 3 user reports of multi-tab divergence.
+ *
+ * Failures are swallowed — broadcast is best-effort and must not affect the
+ * REST mutation's success/failure semantics.
+ */
+export async function broadcastSnippetList(workingDirectory, originSocketId) {
+    if (!workingDirectory || !originSocketId || !io)
+        return;
+    try {
+        const snippets = await listSnippets(workingDirectory);
+        io.to(originSocketId).emit('snippets:list', { snippets });
+    }
+    catch (err) {
+        log.warn(`broadcastSnippetList failed for socket ${originSocketId}: ${String(err)}`);
+    }
+}
 /**
  * Get the current number of connected clients
  * @returns Number of connected clients