@femtomc/mu-server 26.2.69 → 26.2.71

package/dist/api/heartbeats.d.ts

@@ -0,0 +1,2 @@
+import type { ServerRoutingDependencies } from "../server_routing.js";
+export declare function heartbeatRoutes(request: Request, url: URL, deps: ServerRoutingDependencies, headers: Headers): Promise<Response>;

package/dist/api/heartbeats.js

@@ -0,0 +1,211 @@
+import { normalizeWakeMode } from "../server_types.js";
+export async function heartbeatRoutes(request, url, deps, headers) {
+    const path = url.pathname;
+    if (path === "/api/heartbeats") {
+        if (request.method !== "GET") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        const enabledRaw = url.searchParams.get("enabled")?.trim().toLowerCase();
+        const enabled = enabledRaw === "true" ? true : enabledRaw === "false" ? false : undefined;
+        const targetKindRaw = url.searchParams.get("target_kind")?.trim().toLowerCase();
+        const targetKind = targetKindRaw === "run" || targetKindRaw === "activity" ? targetKindRaw : undefined;
+        const limitRaw = url.searchParams.get("limit");
+        const limit = limitRaw && /^\d+$/.test(limitRaw) ? Math.max(1, Math.min(500, Number.parseInt(limitRaw, 10))) : undefined;
+        const programs = await deps.heartbeatPrograms.list({ enabled, targetKind, limit });
+        return Response.json({ count: programs.length, programs }, { headers });
+    }
+    if (path === "/api/heartbeats/create") {
+        if (request.method !== "POST") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ error: "invalid json body" }, { status: 400, headers });
+        }
+        const title = typeof body.title === "string" ? body.title.trim() : "";
+        if (!title) {
+            return Response.json({ error: "title is required" }, { status: 400, headers });
+        }
+        const targetKind = typeof body.target_kind === "string" ? body.target_kind.trim().toLowerCase() : "";
+        let target = null;
+        if (targetKind === "run") {
+            const jobId = typeof body.run_job_id === "string" ? body.run_job_id.trim() : "";
+            const rootIssueId = typeof body.run_root_issue_id === "string" ? body.run_root_issue_id.trim() : "";
+            if (!jobId && !rootIssueId) {
+                return Response.json({ error: "run target requires run_job_id or run_root_issue_id" }, { status: 400, headers });
+            }
+            target = {
+                kind: "run",
+                job_id: jobId || null,
+                root_issue_id: rootIssueId || null,
+            };
+        }
+        else if (targetKind === "activity") {
+            const activityId = typeof body.activity_id === "string" ? body.activity_id.trim() : "";
+            if (!activityId) {
+                return Response.json({ error: "activity target requires activity_id" }, { status: 400, headers });
+            }
+            target = {
+                kind: "activity",
+                activity_id: activityId,
+            };
+        }
+        else {
+            return Response.json({ error: "target_kind must be run or activity" }, { status: 400, headers });
+        }
+        const everyMs = typeof body.every_ms === "number" && Number.isFinite(body.every_ms)
+            ? Math.max(0, Math.trunc(body.every_ms))
+            : undefined;
+        const reason = typeof body.reason === "string" ? body.reason.trim() : undefined;
+        const wakeMode = normalizeWakeMode(body.wake_mode);
+        const enabled = typeof body.enabled === "boolean" ? body.enabled : undefined;
+        try {
+            const program = await deps.heartbeatPrograms.create({
+                title,
+                target,
+                everyMs,
+                reason,
+                wakeMode,
+                enabled,
+                metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
+                    ? body.metadata
+                    : undefined,
+            });
+            return Response.json({ ok: true, program }, { status: 201, headers });
+        }
+        catch (err) {
+            return Response.json({ error: deps.describeError(err) }, { status: 400, headers });
+        }
+    }
+    if (path === "/api/heartbeats/update") {
+        if (request.method !== "POST") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ error: "invalid json body" }, { status: 400, headers });
+        }
+        const programId = typeof body.program_id === "string" ? body.program_id.trim() : "";
+        if (!programId) {
+            return Response.json({ error: "program_id is required" }, { status: 400, headers });
+        }
+        let target;
+        if (typeof body.target_kind === "string") {
+            const targetKind = body.target_kind.trim().toLowerCase();
+            if (targetKind === "run") {
+                const jobId = typeof body.run_job_id === "string" ? body.run_job_id.trim() : "";
+                const rootIssueId = typeof body.run_root_issue_id === "string" ? body.run_root_issue_id.trim() : "";
+                if (!jobId && !rootIssueId) {
+                    return Response.json({ error: "run target requires run_job_id or run_root_issue_id" }, { status: 400, headers });
+                }
+                target = {
+                    kind: "run",
+                    job_id: jobId || null,
+                    root_issue_id: rootIssueId || null,
+                };
+            }
+            else if (targetKind === "activity") {
+                const activityId = typeof body.activity_id === "string" ? body.activity_id.trim() : "";
+                if (!activityId) {
+                    return Response.json({ error: "activity target requires activity_id" }, { status: 400, headers });
+                }
+                target = {
+                    kind: "activity",
+                    activity_id: activityId,
+                };
+            }
+            else {
+                return Response.json({ error: "target_kind must be run or activity" }, { status: 400, headers });
+            }
+        }
+        const wakeMode = Object.hasOwn(body, "wake_mode") ? normalizeWakeMode(body.wake_mode) : undefined;
+        try {
+            const result = await deps.heartbeatPrograms.update({
+                programId,
+                title: typeof body.title === "string" ? body.title : undefined,
+                target,
+                everyMs: typeof body.every_ms === "number" && Number.isFinite(body.every_ms)
+                    ? Math.max(0, Math.trunc(body.every_ms))
+                    : undefined,
+                reason: typeof body.reason === "string" ? body.reason : undefined,
+                wakeMode,
+                enabled: typeof body.enabled === "boolean" ? body.enabled : undefined,
+                metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
+                    ? body.metadata
+                    : undefined,
+            });
+            if (result.ok) {
+                return Response.json(result, { headers });
+            }
+            return Response.json(result, { status: result.reason === "not_found" ? 404 : 400, headers });
+        }
+        catch (err) {
+            return Response.json({ error: deps.describeError(err) }, { status: 400, headers });
+        }
+    }
+    if (path === "/api/heartbeats/delete") {
+        if (request.method !== "POST") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ error: "invalid json body" }, { status: 400, headers });
+        }
+        const programId = typeof body.program_id === "string" ? body.program_id.trim() : "";
+        if (!programId) {
+            return Response.json({ error: "program_id is required" }, { status: 400, headers });
+        }
+        const result = await deps.heartbeatPrograms.remove(programId);
+        return Response.json(result, { status: result.ok ? 200 : result.reason === "not_found" ? 404 : 400, headers });
+    }
+    if (path === "/api/heartbeats/trigger") {
+        if (request.method !== "POST") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ error: "invalid json body" }, { status: 400, headers });
+        }
+        const result = await deps.heartbeatPrograms.trigger({
+            programId: typeof body.program_id === "string" ? body.program_id : null,
+            reason: typeof body.reason === "string" ? body.reason : null,
+        });
+        if (result.ok) {
+            return Response.json(result, { headers });
+        }
+        if (result.reason === "missing_target") {
+            return Response.json(result, { status: 400, headers });
+        }
+        if (result.reason === "not_found") {
+            return Response.json(result, { status: 404, headers });
+        }
+        return Response.json(result, { status: 409, headers });
+    }
+    if (path.startsWith("/api/heartbeats/")) {
+        if (request.method !== "GET") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        const id = decodeURIComponent(path.slice("/api/heartbeats/".length)).trim();
+        if (!id) {
+            return Response.json({ error: "missing program id" }, { status: 400, headers });
+        }
+        const program = await deps.heartbeatPrograms.get(id);
+        if (!program) {
+            return Response.json({ error: "program not found" }, { status: 404, headers });
+        }
+        return Response.json(program, { headers });
+    }
+    return Response.json({ error: "Not Found" }, { status: 404, headers });
+}

package/dist/api/identities.d.ts

@@ -0,0 +1,2 @@
+import type { ServerRoutingDependencies } from "../server_routing.js";
+export declare function identityRoutes(request: Request, url: URL, deps: ServerRoutingDependencies, headers: Headers): Promise<Response>;

package/dist/api/identities.js

@@ -0,0 +1,103 @@
+import { getControlPlanePaths, IdentityStore, ROLE_SCOPES, } from "@femtomc/mu-control-plane";
+export async function identityRoutes(request, url, deps, headers) {
+    const path = url.pathname;
+    const cpPaths = getControlPlanePaths(deps.context.repoRoot);
+    const identityStore = new IdentityStore(cpPaths.identitiesPath);
+    await identityStore.load();
+    if (path === "/api/identities") {
+        if (request.method !== "GET") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        const includeInactive = url.searchParams.get("include_inactive")?.trim().toLowerCase() === "true";
+        const bindings = identityStore.listBindings({ includeInactive });
+        return Response.json({ count: bindings.length, bindings }, { headers });
+    }
+    if (path === "/api/identities/link") {
+        if (request.method !== "POST") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ error: "invalid json body" }, { status: 400, headers });
+        }
+        const channel = typeof body.channel === "string" ? body.channel.trim() : "";
+        if (!channel || (channel !== "slack" && channel !== "discord" && channel !== "telegram")) {
+            return Response.json({ error: "channel is required (slack, discord, telegram)" }, { status: 400, headers });
+        }
+        const actorId = typeof body.actor_id === "string" ? body.actor_id.trim() : "";
+        if (!actorId) {
+            return Response.json({ error: "actor_id is required" }, { status: 400, headers });
+        }
+        const tenantId = typeof body.tenant_id === "string" ? body.tenant_id.trim() : "";
+        if (!tenantId) {
+            return Response.json({ error: "tenant_id is required" }, { status: 400, headers });
+        }
+        const roleKey = typeof body.role === "string" ? body.role.trim() : "operator";
+        const roleScopes = ROLE_SCOPES[roleKey];
+        if (!roleScopes) {
+            return Response.json({ error: `invalid role: ${roleKey} (operator, contributor, viewer)` }, { status: 400, headers });
+        }
+        const bindingId = typeof body.binding_id === "string" && body.binding_id.trim().length > 0
+            ? body.binding_id.trim()
+            : `bind-${crypto.randomUUID()}`;
+        const operatorId = typeof body.operator_id === "string" && body.operator_id.trim().length > 0
+            ? body.operator_id.trim()
+            : "default";
+        const decision = await identityStore.link({
+            bindingId,
+            operatorId,
+            channel: channel,
+            channelTenantId: tenantId,
+            channelActorId: actorId,
+            scopes: [...roleScopes],
+        });
+        switch (decision.kind) {
+            case "linked":
+                return Response.json({ ok: true, kind: "linked", binding: decision.binding }, { status: 201, headers });
+            case "binding_exists":
+                return Response.json({ ok: false, kind: "binding_exists", binding: decision.binding }, { status: 409, headers });
+            case "principal_already_linked":
+                return Response.json({ ok: false, kind: "principal_already_linked", binding: decision.binding }, { status: 409, headers });
+        }
+    }
+    if (path === "/api/identities/unlink") {
+        if (request.method !== "POST") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        let body;
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return Response.json({ error: "invalid json body" }, { status: 400, headers });
+        }
+        const bindingId = typeof body.binding_id === "string" ? body.binding_id.trim() : "";
+        if (!bindingId) {
+            return Response.json({ error: "binding_id is required" }, { status: 400, headers });
+        }
+        const actorBindingId = typeof body.actor_binding_id === "string" ? body.actor_binding_id.trim() : "";
+        if (!actorBindingId) {
+            return Response.json({ error: "actor_binding_id is required" }, { status: 400, headers });
+        }
+        const reason = typeof body.reason === "string" ? body.reason.trim() : null;
+        const decision = await identityStore.unlinkSelf({
+            bindingId,
+            actorBindingId,
+            reason: reason || null,
+        });
+        switch (decision.kind) {
+            case "unlinked":
+                return Response.json({ ok: true, kind: "unlinked", binding: decision.binding }, { headers });
+            case "not_found":
+                return Response.json({ ok: false, kind: "not_found" }, { status: 404, headers });
+            case "invalid_actor":
+                return Response.json({ ok: false, kind: "invalid_actor" }, { status: 403, headers });
+            case "already_inactive":
+                return Response.json({ ok: false, kind: "already_inactive", binding: decision.binding }, { status: 409, headers });
+        }
+    }
+    return Response.json({ error: "Not Found" }, { status: 404, headers });
+}

package/dist/api/issues.js

@@ -1,3 +1,58 @@
+import { DEFAULT_ISSUE_QUERY_LIMIT, ISSUE_STATUS_VALUES, IssueStoreNotFoundError, IssueStoreValidationError, normalizeIssueContainsFilter, normalizeIssueQueryLimit, } from "@femtomc/mu-issue";
+const ISSUE_STATUS_SET = new Set(ISSUE_STATUS_VALUES);
+function normalizeIssueId(value) {
+    try {
+        return decodeURIComponent(value).trim();
+    }
+    catch (cause) {
+        throw new IssueStoreValidationError("invalid issue id encoding", { cause });
+    }
+}
+function normalizeIssueStatusFilter(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    if (!ISSUE_STATUS_SET.has(normalized)) {
+        throw new IssueStoreValidationError(`invalid issue status filter: ${normalized}`);
+    }
+    return normalized;
+}
+async function readJsonBody(request) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        throw new IssueStoreValidationError("invalid json body");
+    }
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        throw new IssueStoreValidationError("json body must be an object");
+    }
+    return body;
+}
+function errorResponse(status, message) {
+    return new Response(JSON.stringify({ error: message }), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function mapIssueRouteError(error) {
+    if (error instanceof IssueStoreNotFoundError) {
+        return errorResponse(404, error.message);
+    }
+    if (error instanceof IssueStoreValidationError) {
+        return errorResponse(400, error.message);
+    }
+    if (error instanceof Error && error.name === "ZodError") {
+        return errorResponse(400, error.message);
+    }
+    console.error("Issue API error:", error);
+    return errorResponse(500, error instanceof Error ? error.message : "Internal server error");
+}
 export async function issueRoutes(request, context) {
     const url = new URL(request.url);
     const path = url.pathname.replace("/api/issues", "") || "/";
@@ -5,37 +60,63 @@ export async function issueRoutes(request, context) {
     try {
         // List issues - GET /api/issues
         if (path === "/" && method === "GET") {
-            const status = url.searchParams.get("status");
-            const tag = url.searchParams.get("tag");
-            const issues = await context.issueStore.list({
-                status: status,
-                tag: tag || undefined,
+            const status = normalizeIssueStatusFilter(url.searchParams.get("status"));
+            const tag = url.searchParams.get("tag")?.trim() || undefined;
+            const contains = normalizeIssueContainsFilter(url.searchParams.get("contains"));
+            const limit = normalizeIssueQueryLimit(url.searchParams.get("limit"), {
+                defaultLimit: DEFAULT_ISSUE_QUERY_LIMIT,
             });
+            const issues = await context.issueStore.list({ status, tag, contains, limit: limit ?? undefined });
             return Response.json(issues);
         }
         // Get ready issues - GET /api/issues/ready
         if (path === "/ready" && method === "GET") {
-            const root = url.searchParams.get("root");
-            const issues = await context.issueStore.ready(root || undefined);
+            const root = url.searchParams.get("root")?.trim() || undefined;
+            const contains = normalizeIssueContainsFilter(url.searchParams.get("contains"));
+            const limit = normalizeIssueQueryLimit(url.searchParams.get("limit"), {
+                defaultLimit: DEFAULT_ISSUE_QUERY_LIMIT,
+            });
+            const issues = await context.issueStore.ready(root, { contains, limit: limit ?? undefined });
             return Response.json(issues);
         }
         // Get single issue - GET /api/issues/:id
         if (path.startsWith("/") && method === "GET") {
-            const id = path.slice(1);
-            if (id) {
-                const issue = await context.issueStore.get(id);
-                if (!issue) {
-                    return new Response("Issue not found", { status: 404 });
-                }
-                return Response.json(issue);
+            const id = normalizeIssueId(path.slice(1));
+            if (id.length === 0) {
+                return errorResponse(400, "issue id is required");
             }
+            const issue = await context.issueStore.get(id);
+            if (!issue) {
+                return errorResponse(404, "issue not found");
+            }
+            return Response.json(issue);
         }
         // Create issue - POST /api/issues
         if (path === "/" && method === "POST") {
-            const body = (await request.json());
-            const { title, body: issueBody, tags, priority } = body;
+            const body = await readJsonBody(request);
+            const title = typeof body.title === "string" ? body.title.trim() : "";
             if (!title) {
-                return new Response("Title is required", { status: 400 });
+                return errorResponse(400, "title is required");
+            }
+            const issueBody = body.body == null ? undefined : typeof body.body === "string" ? body.body : undefined;
+            if (body.body != null && issueBody == null) {
+                return errorResponse(400, "body must be a string when provided");
+            }
+            let tags;
+            if (body.tags != null) {
+                if (!Array.isArray(body.tags) || !body.tags.every((tag) => typeof tag === "string")) {
+                    return errorResponse(400, "tags must be a string[] when provided");
+                }
+                tags = body.tags.map((tag) => tag.trim());
+            }
+            let priority;
+            if (body.priority != null) {
+                if (typeof body.priority !== "number" ||
+                    !Number.isFinite(body.priority) ||
+                    !Number.isInteger(body.priority)) {
+                    return errorResponse(400, "priority must be an integer when provided");
+                }
+                priority = body.priority;
             }
             const issue = await context.issueStore.create(title, {
                 body: issueBody,
@@ -46,41 +127,47 @@ export async function issueRoutes(request, context) {
         }
         // Update issue - PATCH /api/issues/:id
         if (path.startsWith("/") && method === "PATCH") {
-            const id = path.slice(1);
-            if (id) {
-                const body = (await request.json());
-                const issue = await context.issueStore.update(id, body);
-                return Response.json(issue);
+            const id = normalizeIssueId(path.slice(1));
+            if (id.length === 0) {
+                return errorResponse(400, "issue id is required");
             }
+            const body = await readJsonBody(request);
+            const issue = await context.issueStore.update(id, body);
+            return Response.json(issue);
         }
         // Close issue - POST /api/issues/:id/close
         if (path.endsWith("/close") && method === "POST") {
-            const id = path.slice(1, -6); // Remove leading / and trailing /close
-            const body = (await request.json());
-            const { outcome } = body;
+            const id = normalizeIssueId(path.slice(1, -"/close".length));
+            if (id.length === 0) {
+                return errorResponse(400, "issue id is required");
+            }
+            const body = await readJsonBody(request);
+            const outcome = typeof body.outcome === "string" ? body.outcome.trim() : "";
             if (!outcome) {
-                return new Response("Outcome is required", { status: 400 });
+                return errorResponse(400, "outcome is required");
             }
             const issue = await context.issueStore.close(id, outcome);
             return Response.json(issue);
         }
         // Claim issue - POST /api/issues/:id/claim
         if (path.endsWith("/claim") && method === "POST") {
-            const id = path.slice(1, -6); // Remove leading / and trailing /claim
+            const id = normalizeIssueId(path.slice(1, -"/claim".length));
+            if (id.length === 0) {
+                return errorResponse(400, "issue id is required");
+            }
             const success = await context.issueStore.claim(id);
             if (!success) {
-                return new Response("Failed to claim issue", { status: 409 });
+                return errorResponse(409, "failed to claim issue");
             }
             const issue = await context.issueStore.get(id);
+            if (!issue) {
+                return errorResponse(404, "issue not found");
+            }
             return Response.json(issue);
         }
         return new Response("Not Found", { status: 404 });
     }
     catch (error) {
-        console.error("Issue API error:", error);
-        return new Response(JSON.stringify({ error: error instanceof Error ? error.message : "Internal server error" }), {
-            status: 500,
-            headers: { "Content-Type": "application/json" },
-        });
+        return mapIssueRouteError(error);
     }
 }

package/dist/api/runs.d.ts

@@ -0,0 +1,2 @@
+import type { ServerRoutingDependencies } from "../server_routing.js";
+export declare function runRoutes(request: Request, url: URL, deps: ServerRoutingDependencies, headers: Headers): Promise<Response>;