@femtomc/mu-server 26.2.19

package/README.md

@@ -0,0 +1,148 @@
+# @femtomc/mu-server
+
+HTTP JSON API server for mu issue and forum stores. Provides the backend for the mu web UI and can also be used standalone for programmatic access.
+
+## Installation
+
+```bash
+bun add @femtomc/mu-server
+```
+
+## Usage
+
+```typescript
+import { createServer } from "@femtomc/mu-server";
+
+// Create server with default options (uses current directory as repo root)
+const server = createServer();
+
+// Or specify custom repo root and port
+const server = createServer({
+  repoRoot: "/path/to/repo",
+  port: 8080
+});
+
+// Start the server
+Bun.serve(server);
+```
+
+## API Endpoints
+
+### Health Check
+
+- `GET /healthz` or `GET /health` - Returns 200 OK
+
+### Status
+
+- `GET /api/status` - Returns repository status
+  ```json
+  {
+    "repo_root": "/path/to/repo",
+    "open_count": 10,
+    "ready_count": 3
+  }
+  ```
+
+### Issues
+
+- `GET /api/issues` - List issues
+  - Query params: `?status=open&tag=bug`
+- `GET /api/issues/:id` - Get issue by ID
+- `POST /api/issues` - Create new issue
+  ```json
+  {
+    "title": "Issue title",
+    "body": "Issue description",
+    "tags": ["bug", "priority"],
+    "priority": 2,
+    "execution_spec": { ... }
+  }
+  ```
+- `PATCH /api/issues/:id` - Update issue
+- `POST /api/issues/:id/close` - Close issue
+  ```json
+  {
+    "outcome": "success"
+  }
+  ```
+- `POST /api/issues/:id/claim` - Claim issue (changes status to in_progress)
+- `GET /api/issues/ready` - Get ready issues
+  - Query param: `?root=issue-id`
+
+### Forum
+
+- `GET /api/forum/topics` - List forum topics
+  - Query param: `?prefix=issue:`
+- `GET /api/forum/read` - Read messages from topic
+  - Query params: `?topic=issue:123&limit=50`
+- `POST /api/forum/post` - Post message to topic
+  ```json
+  {
+    "topic": "issue:123",
+    "body": "Message content",
+    "author": "username"
+  }
+  ```
+
+## Running the Server
+
+### With Web UI (Recommended)
+
+The easiest way to run the server with the web interface:
+
+```bash
+# From any mu repository
+mu serve
+
+# Or with custom ports
+mu serve --port 8080 --api-port 3001
+```
+
+### Standalone Server
+
+```bash
+# Install globally
+bun install -g @femtomc/mu-server
+
+# Run server (looks for .mu/ in current directory or ancestors)
+mu-server
+
+# Or set custom port
+PORT=8080 mu-server
+```
+
+### Programmatic
+
+```bash
+# Run the example
+bun run example.js
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build
+bun run build
+
+# Start server (after building)
+bun run start
+```
+
+## Architecture
+
+The server uses:
+- Filesystem-backed JSONL stores (FsJsonlStore)
+- IssueStore and ForumStore from mu packages
+- Bun's built-in HTTP server
+- Simple REST-style JSON API
+
+All data is persisted to `.mu/` directory:
+- `.mu/issues.jsonl` - Issue data
+- `.mu/forum.jsonl` - Forum messages
+- `.mu/events.jsonl` - Event log

package/dist/api/forum.d.ts

@@ -0,0 +1,2 @@
+import type { ServerContext } from "../server.js";
+export declare function forumRoutes(request: Request, context: ServerContext): Promise<Response>;

package/dist/api/forum.js

@@ -0,0 +1,41 @@
+export async function forumRoutes(request, context) {
+    const url = new URL(request.url);
+    const path = url.pathname.replace("/api/forum", "") || "/";
+    const method = request.method;
+    try {
+        // List topics - GET /api/forum/topics
+        if (path === "/topics" && method === "GET") {
+            const prefix = url.searchParams.get("prefix");
+            const topics = await context.forumStore.topics(prefix);
+            return Response.json(topics);
+        }
+        // Read messages - GET /api/forum/read
+        if (path === "/read" && method === "GET") {
+            const topic = url.searchParams.get("topic");
+            const limit = url.searchParams.get("limit");
+            if (!topic) {
+                return new Response("Topic is required", { status: 400 });
+            }
+            const messages = await context.forumStore.read(topic, limit ? parseInt(limit, 10) : 50);
+            return Response.json(messages);
+        }
+        // Post message - POST /api/forum/post
+        if (path === "/post" && method === "POST") {
+            const body = await request.json();
+            const { topic, body: messageBody, author } = body;
+            if (!topic || !messageBody) {
+                return new Response("Topic and body are required", { status: 400 });
+            }
+            const message = await context.forumStore.post(topic, messageBody, author || "system");
+            return Response.json(message, { status: 201 });
+        }
+        return new Response("Not Found", { status: 404 });
+    }
+    catch (error) {
+        console.error("Forum API error:", error);
+        return new Response(JSON.stringify({ error: error instanceof Error ? error.message : "Internal server error" }), {
+            status: 500,
+            headers: { "Content-Type": "application/json" }
+        });
+    }
+}

package/dist/api/issues.d.ts

@@ -0,0 +1,2 @@
+import type { ServerContext } from "../server.js";
+export declare function issueRoutes(request: Request, context: ServerContext): Promise<Response>;

package/dist/api/issues.js

@@ -0,0 +1,87 @@
+export async function issueRoutes(request, context) {
+    const url = new URL(request.url);
+    const path = url.pathname.replace("/api/issues", "") || "/";
+    const method = request.method;
+    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
+            });
+            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);
+            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);
+            }
+        }
+        // Create issue - POST /api/issues
+        if (path === "/" && method === "POST") {
+            const body = await request.json();
+            const { title, body: issueBody, tags, priority, execution_spec } = body;
+            if (!title) {
+                return new Response("Title is required", { status: 400 });
+            }
+            const issue = await context.issueStore.create(title, {
+                body: issueBody,
+                tags,
+                priority,
+                execution_spec
+            });
+            return Response.json(issue, { status: 201 });
+        }
+        // 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);
+            }
+        }
+        // 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;
+            if (!outcome) {
+                return new Response("Outcome is required", { status: 400 });
+            }
+            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 success = await context.issueStore.claim(id);
+            if (!success) {
+                return new Response("Failed to claim issue", { status: 409 });
+            }
+            const issue = await context.issueStore.get(id);
+            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" }
+        });
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import { createServer } from "./server.js";
+import { findRepoRoot } from "@femtomc/mu-core/node";
+const port = parseInt(process.env.PORT || "3000", 10);
+let repoRoot;
+try {
+    repoRoot = findRepoRoot();
+}
+catch {
+    console.error("Error: Could not find .mu directory. Run 'mu init' first.");
+    process.exit(1);
+}
+console.log(`Starting mu-server on port ${port}...`);
+console.log(`Repository root: ${repoRoot}`);
+const server = createServer({ repoRoot, port });
+Bun.serve(server);
+console.log(`Server running at http://localhost:${port}`);
+console.log(`Health check: http://localhost:${port}/healthz`);
+console.log(`API Status: http://localhost:${port}/api/status`);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { ServerOptions, ServerContext } from "./server.js";
+export { createServer, createContext } from "./server.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { createServer, createContext } from "./server.js";

package/dist/server.d.ts

@@ -0,0 +1,19 @@
+import { EventLog } from "@femtomc/mu-core/node";
+import { IssueStore } from "@femtomc/mu-issue";
+import { ForumStore } from "@femtomc/mu-forum";
+export type ServerOptions = {
+    repoRoot?: string;
+    port?: number;
+};
+export type ServerContext = {
+    repoRoot: string;
+    issueStore: IssueStore;
+    forumStore: ForumStore;
+    eventLog: EventLog;
+};
+export declare function createContext(repoRoot: string): ServerContext;
+export declare function createServer(options?: ServerOptions): {
+    port: number;
+    fetch: (request: Request) => Promise<Response>;
+    hostname: string;
+};

package/dist/server.js

@@ -0,0 +1,66 @@
+import { fsEventLogFromRepoRoot, FsJsonlStore, getStorePaths } from "@femtomc/mu-core/node";
+import { IssueStore } from "@femtomc/mu-issue";
+import { ForumStore } from "@femtomc/mu-forum";
+import { issueRoutes } from "./api/issues.js";
+import { forumRoutes } from "./api/forum.js";
+export function createContext(repoRoot) {
+    const paths = getStorePaths(repoRoot);
+    const eventLog = fsEventLogFromRepoRoot(repoRoot);
+    const issueStore = new IssueStore(new FsJsonlStore(paths.issuesPath), { events: eventLog });
+    const forumStore = new ForumStore(new FsJsonlStore(paths.forumPath), { events: eventLog });
+    return { repoRoot, issueStore, forumStore, eventLog };
+}
+export function createServer(options = {}) {
+    const repoRoot = options.repoRoot || process.cwd();
+    const context = createContext(repoRoot);
+    const handleRequest = async (request) => {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        // CORS headers for development
+        const headers = new Headers({
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type",
+        });
+        // Handle preflight requests
+        if (request.method === "OPTIONS") {
+            return new Response(null, { status: 204, headers });
+        }
+        // Health check
+        if (path === "/healthz" || path === "/health") {
+            return new Response("ok", { status: 200, headers });
+        }
+        // Status endpoint
+        if (path === "/api/status") {
+            const issues = await context.issueStore.list();
+            const openIssues = issues.filter(i => i.status === "open");
+            const readyIssues = await context.issueStore.ready();
+            return Response.json({
+                repo_root: context.repoRoot,
+                open_count: openIssues.length,
+                ready_count: readyIssues.length
+            }, { headers });
+        }
+        // Issue routes
+        if (path.startsWith("/api/issues")) {
+            const response = await issueRoutes(request, context);
+            // Add CORS headers to the response
+            headers.forEach((value, key) => response.headers.set(key, value));
+            return response;
+        }
+        // Forum routes
+        if (path.startsWith("/api/forum")) {
+            const response = await forumRoutes(request, context);
+            // Add CORS headers to the response
+            headers.forEach((value, key) => response.headers.set(key, value));
+            return response;
+        }
+        return new Response("Not Found", { status: 404, headers });
+    };
+    const server = {
+        port: options.port || 3000,
+        fetch: handleRequest,
+        hostname: "0.0.0.0",
+    };
+    return server;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@femtomc/mu-server",
+  "version": "26.2.19",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mu-server": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "start": "bun run dist/cli.js"
+  },
+  "dependencies": {
+    "@femtomc/mu-core": "26.2.19",
+    "@femtomc/mu-issue": "26.2.19",
+    "@femtomc/mu-forum": "26.2.19"
+  }
+}