@locusai/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Locus AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@locusai/server",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "lint": "bun lint"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "better-sqlite3": "^11.5.0",
+    "zod": "^3.23.8",
+    "@locusai/shared": "workspace:*",
+    "cors": "^2.8.5",
+    "dockerode": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/cors": "^2.8.19",
+    "@types/dockerode": "^3.3.33",
+    "@types/express": "^5.0.6"
+  }
+}

package/src/controllers/artifact.controller.ts

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { NextFunction, Request, Response } from "express";
+import type { ArtifactRepository } from "../repositories/artifact.repository.js";
+
+export class ArtifactController {
+  constructor(
+    private artifactRepo: ArtifactRepository,
+    private workspaceDir: string
+  ) {}
+
+  getArtifactFile = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { taskId, type, filename } = req.params;
+      const filePath = join(
+        this.workspaceDir,
+        "artifacts",
+        taskId as string,
+        type as string,
+        filename as string
+      );
+
+      if (!existsSync(filePath)) {
+        return res
+          .status(404)
+          .json({ error: { message: "Artifact not found" } });
+      }
+
+      res.sendFile(filePath);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  getByTaskId = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const artifacts = this.artifactRepo.findByTaskId(
+        req.params.taskId as string
+      );
+      res.json(artifacts);
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/controllers/ci.controller.ts

@@ -0,0 +1,16 @@
+import type { NextFunction, Request, Response } from "express";
+import type { CiService } from "../services/ci.service.js";
+
+export class CiController {
+  constructor(private ciService: CiService) {}
+
+  run = async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { taskId, preset } = req.body;
+      const result = await this.ciService.runCi(taskId, preset);
+      res.json(result);
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/controllers/doc.controller.ts

@@ -0,0 +1,116 @@
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { NextFunction, Request, Response } from "express";
+
+export interface DocNode {
+  type: "file" | "directory";
+  name: string;
+  path: string;
+  children?: DocNode[];
+}
+
+export class DocController {
+  constructor(private config: { repoPath: string; docsPath: string }) {}
+
+  getAll = (_req: Request, res: Response, next: NextFunction) => {
+    try {
+      const locusDir = join(this.config.repoPath, ".locus");
+      const docsFile = join(locusDir, "docs.json");
+
+      if (!existsSync(docsFile)) {
+        return res.json([]);
+      }
+
+      const docs = JSON.parse(readFileSync(docsFile, "utf-8"));
+      res.json(docs);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  getTree = (_req: Request, res: Response, next: NextFunction) => {
+    try {
+      if (!existsSync(this.config.docsPath)) {
+        return res.json([]);
+      }
+      const tree = this.buildTree(this.config.docsPath);
+      res.json(tree);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  read = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const filePath = req.query.path as string;
+      if (!filePath) {
+        return res.status(400).json({ error: { message: "Path is required" } });
+      }
+
+      const fullPath = join(this.config.docsPath, filePath);
+      if (!fullPath.startsWith(this.config.docsPath)) {
+        return res.status(403).json({ error: { message: "Invalid path" } });
+      }
+
+      const content = readFileSync(fullPath, "utf-8");
+      res.json({ content });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  write = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { path: filePath, content } = req.body;
+      if (!filePath) {
+        return res.status(400).json({ error: { message: "Path is required" } });
+      }
+
+      const fullPath = join(this.config.docsPath, filePath);
+      if (!fullPath.startsWith(this.config.docsPath)) {
+        return res.status(403).json({ error: { message: "Invalid path" } });
+      }
+
+      writeFileSync(fullPath, content, "utf-8");
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  private buildTree(dir: string, basePath: string = ""): DocNode[] {
+    const entries = readdirSync(dir);
+    const nodes: DocNode[] = [];
+
+    for (const entry of entries) {
+      if (entry.startsWith(".")) continue;
+
+      const fullPath = join(dir, entry);
+      const relativePath = join(basePath, entry);
+      const stats = statSync(fullPath);
+
+      if (stats.isDirectory()) {
+        nodes.push({
+          type: "directory",
+          name: entry,
+          path: relativePath,
+          children: this.buildTree(fullPath, relativePath),
+        });
+      } else {
+        nodes.push({
+          type: "file",
+          name: entry,
+          path: relativePath,
+        });
+      }
+    }
+
+    return nodes;
+  }
+}

package/src/controllers/event.controller.ts

@@ -0,0 +1,20 @@
+import type { NextFunction, Request, Response } from "express";
+import type { EventRepository } from "../repositories/event.repository.js";
+
+export class EventController {
+  constructor(private eventRepo: EventRepository) {}
+
+  getByTaskId = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const taskId = req.query.taskId as string;
+      const events = this.eventRepo.findByTaskId(taskId);
+      const formattedEvents = events.map((e) => ({
+        ...e,
+        payload: JSON.parse(e.payload || "{}"),
+      }));
+      res.json(formattedEvents);
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/controllers/sprint.controller.ts

@@ -0,0 +1,34 @@
+import type { NextFunction, Request, Response } from "express";
+import type { SprintService } from "../services/sprint.service.js";
+
+export class SprintController {
+  constructor(private sprintService: SprintService) {}
+
+  getAll = (_req: Request, res: Response, next: NextFunction) => {
+    try {
+      const sprints = this.sprintService.getAllSprints();
+      res.json(sprints);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  create = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { name } = req.body;
+      const id = this.sprintService.createSprint(name);
+      res.json({ id });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  updateStatus = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      this.sprintService.updateSprint(req.params.id as string, req.body);
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/controllers/task.controller.ts

@@ -0,0 +1,98 @@
+import { TaskSchema } from "@locusai/shared";
+import type { NextFunction, Request, Response } from "express";
+import type { TaskService } from "../services/task.service.js";
+
+export class TaskController {
+  constructor(private taskService: TaskService) {}
+
+  getAll = (_req: Request, res: Response, next: NextFunction) => {
+    try {
+      const tasks = this.taskService.getAllTasks();
+      res.json(tasks);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  getById = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const task = this.taskService.getTaskById(req.params.id as string);
+      res.json(task);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  create = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const data = TaskSchema.parse(req.body);
+      const id = this.taskService.createTask(data);
+      res.json({ id });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  update = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      this.taskService.updateTask(req.params.id as string, req.body);
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  delete = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      this.taskService.deleteTask(req.params.id as string);
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  addComment = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { author, text } = req.body;
+      this.taskService.addComment(req.params.id as string, author, text);
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  dispatch = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { workerId, sprintId } = req.body;
+      if (!sprintId) {
+        return res
+          .status(400)
+          .json({ error: { message: "sprintId is required" } });
+      }
+      const task = this.taskService.dispatchTask(workerId, Number(sprintId));
+      res.json(task);
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  lock = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { agentId, ttlSeconds } = req.body;
+      this.taskService.lockTask(req.params.id as string, agentId, ttlSeconds);
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+
+  unlock = (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const { agentId } = req.body;
+      this.taskService.unlockTask(req.params.id as string, agentId);
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/src/db.ts

@@ -0,0 +1,107 @@
+import { Database } from "bun:sqlite";
+import { join } from "node:path";
+
+export function initDb(workspaceDir: string) {
+  const db = new Database(join(workspaceDir, "db.sqlite"));
+
+  // Create tables if they don't exist
+  db.run(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      description TEXT,
+      status TEXT NOT NULL,
+      priority TEXT NOT NULL DEFAULT 'MEDIUM',
+      labels TEXT,
+      assigneeRole TEXT,
+      parentId INTEGER,
+      lockedBy TEXT,
+      lockExpiresAt INTEGER,
+      acceptanceChecklist TEXT,
+      createdAt INTEGER NOT NULL,
+      updatedAt INTEGER NOT NULL,
+      FOREIGN KEY(parentId) REFERENCES tasks(id)
+    );`);
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS comments (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      taskId INTEGER NOT NULL,
+      author TEXT NOT NULL,
+      text TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      FOREIGN KEY(taskId) REFERENCES tasks(id)
+    );`);
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS artifacts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      taskId INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      contentText TEXT,
+      filePath TEXT,
+      createdBy TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      FOREIGN KEY(taskId) REFERENCES tasks(id)
+    );`);
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      taskId INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      payload TEXT,
+      createdAt INTEGER NOT NULL,
+      FOREIGN KEY(taskId) REFERENCES tasks(id)
+    );`);
+
+  // Run migrations for existing tasks table columns
+  try {
+    const tableInfo = db.prepare("PRAGMA table_info(tasks)").all() as {
+      name: string;
+    }[];
+    const columns = tableInfo.map((col) => col.name);
+
+    if (!columns.includes("priority")) {
+      db.run(
+        "ALTER TABLE tasks ADD COLUMN priority TEXT NOT NULL DEFAULT 'MEDIUM'"
+      );
+      console.log("Migration: Added priority column to tasks table");
+    }
+
+    if (!columns.includes("parentId")) {
+      db.run("ALTER TABLE tasks ADD COLUMN parentId INTEGER");
+      console.log("Migration: Added parentId column to tasks table");
+    }
+
+    if (!columns.includes("lockedBy")) {
+      db.run("ALTER TABLE tasks ADD COLUMN lockedBy TEXT");
+      console.log("Migration: Added lockedBy column to tasks table");
+    }
+
+    if (!columns.includes("lockExpiresAt")) {
+      db.run("ALTER TABLE tasks ADD COLUMN lockExpiresAt INTEGER");
+      console.log("Migration: Added lockExpiresAt column to tasks table");
+    }
+
+    if (!columns.includes("sprintId")) {
+      db.run("ALTER TABLE tasks ADD COLUMN sprintId INTEGER");
+      console.log("Migration: Added sprintId column to tasks table");
+    }
+  } catch (err) {
+    console.error("Migration error:", err);
+  }
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS sprints (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'PLANNED',
+      startDate INTEGER,
+      endDate INTEGER,
+      createdAt INTEGER NOT NULL
+    );`);
+
+  return db;
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { parseArgs } from "node:util";
+import cors from "cors";
+import express from "express";
+import { ArtifactController } from "./controllers/artifact.controller.js";
+import { CiController } from "./controllers/ci.controller.js";
+import { DocController } from "./controllers/doc.controller.js";
+import { EventController } from "./controllers/event.controller.js";
+import { SprintController } from "./controllers/sprint.controller.js";
+// Controllers
+import { TaskController } from "./controllers/task.controller.js";
+import { initDb } from "./db.js";
+// Middleware
+import { errorHandler } from "./middleware/error.middleware.js";
+import { ArtifactRepository } from "./repositories/artifact.repository.js";
+import { CommentRepository } from "./repositories/comment.repository.js";
+import { EventRepository } from "./repositories/event.repository.js";
+import { SprintRepository } from "./repositories/sprint.repository.js";
+// Repositories
+import { TaskRepository } from "./repositories/task.repository.js";
+import { createArtifactsRouter } from "./routes/artifacts.routes.js";
+import { createCiRouter } from "./routes/ci.routes.js";
+import { createDocsRouter } from "./routes/docs.routes.js";
+import { createEventsRouter } from "./routes/events.routes.js";
+import { createSprintsRouter } from "./routes/sprints.routes.js";
+// Routes
+import { createTaskRouter } from "./routes/tasks.routes.js";
+import { CiService } from "./services/ci.service.js";
+import { SprintService } from "./services/sprint.service.js";
+// Services
+import { TaskService } from "./services/task.service.js";
+import { TaskProcessor } from "./task-processor.js";
+
+const { values } = parseArgs({
+  args: Bun.argv,
+  options: {
+    project: { type: "string" },
+  },
+  strict: true,
+  allowPositionals: true,
+});
+
+if (!values.project) {
+  console.error("Usage: bun run dev -- --project <workspaceDir>");
+  process.exit(1);
+}
+
+const workspaceDir = isAbsolute(values.project)
+  ? values.project
+  : join(process.cwd(), values.project);
+const configPath = join(workspaceDir, "workspace.config.json");
+const config = JSON.parse(readFileSync(configPath, "utf-8"));
+
+const db = initDb(workspaceDir);
+
+// Initialize Repositories
+const taskRepo = new TaskRepository(db);
+const eventRepo = new EventRepository(db);
+const commentRepo = new CommentRepository(db);
+const artifactRepo = new ArtifactRepository(db);
+const sprintRepo = new SprintRepository(db);
+
+const processor = new TaskProcessor(db, {
+  ciPresetsPath: config.ciPresetsPath,
+  repoPath: workspaceDir,
+});
+
+// Initialize Services
+const taskService = new TaskService(
+  taskRepo,
+  eventRepo,
+  commentRepo,
+  artifactRepo,
+  processor
+);
+const sprintService = new SprintService(sprintRepo);
+const ciService = new CiService(artifactRepo, eventRepo, {
+  ciPresetsPath: config.ciPresetsPath,
+  repoPath: workspaceDir,
+});
+
+// Initialize Controllers
+const taskController = new TaskController(taskService);
+const sprintController = new SprintController(sprintService);
+const ciController = new CiController(ciService);
+const artifactController = new ArtifactController(artifactRepo, workspaceDir);
+const docController = new DocController({
+  repoPath: config.repoPath,
+  docsPath: config.docsPath,
+});
+const eventController = new EventController(eventRepo);
+
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: "12mb" }));
+
+// Routes Implementation
+app.use("/api/tasks", createTaskRouter(taskController));
+app.use("/api/docs", createDocsRouter(docController));
+app.use("/api/sprints", createSprintsRouter(sprintController));
+app.use("/api/ci", createCiRouter(ciController));
+app.use("/api/events", createEventsRouter(eventController));
+app.use("/api", createArtifactsRouter(artifactController));
+
+// Health Check
+app.get("/health", (_req, res) => res.json({ status: "ok" }));
+
+// Error Handling
+app.use(errorHandler);
+
+const PORT = 3080;
+
+// Serve Dashboard UI if it exists
+const dashboardPaths = [
+  join(import.meta.dir, "../public/dashboard"), // Production (bundled)
+  join(process.cwd(), "packages/cli/public/dashboard"), // Dev (root)
+];
+
+const dashboardPath = dashboardPaths.find((p) => existsSync(p));
+
+if (dashboardPath) {
+  console.log(`Serving dashboard from ${dashboardPath}`);
+  app.use(express.static(dashboardPath));
+  // Client-side routing fallback
+  app.get("/[^api]*", (_req, res) => {
+    res.sendFile(join(dashboardPath, "index.html"));
+  });
+}
+
+app.listen(PORT, () =>
+  console.log(`Server running on http://localhost:${PORT}`)
+);

package/src/middleware/error.middleware.ts

@@ -0,0 +1,21 @@
+import type { NextFunction, Request, Response } from "express";
+import { ServiceError } from "../services/task.service.js";
+
+export function errorHandler(
+  err: Error,
+  _req: Request,
+  res: Response,
+  _next: NextFunction
+) {
+  console.error("Server Error:", err);
+
+  const statusCode = err instanceof ServiceError ? err.statusCode : 500;
+  const message = err.message || "Internal Server Error";
+
+  res.status(statusCode).json({
+    error: {
+      message,
+      stack: process.env.NODE_ENV === "development" ? err.stack : undefined,
+    },
+  });
+}

package/src/repositories/artifact.repository.ts

@@ -0,0 +1,44 @@
+import { BaseRepository } from "./base.repository.js";
+
+export interface DBArtifact {
+  id: number;
+  taskId: number;
+  type: string;
+  title: string;
+  contentText?: string;
+  filePath?: string;
+  createdBy: string;
+  createdAt: number;
+}
+
+export class ArtifactRepository extends BaseRepository {
+  findByTaskId(taskId: number | string): DBArtifact[] {
+    return this.db
+      .prepare(
+        "SELECT * FROM artifacts WHERE taskId = ? ORDER BY createdAt DESC"
+      )
+      .all(taskId) as DBArtifact[];
+  }
+
+  create(data: Omit<DBArtifact, "id" | "createdAt">): void {
+    const now = Date.now();
+    this.db
+      .prepare(`
+        INSERT INTO artifacts (taskId, type, title, contentText, filePath, createdBy, createdAt)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `)
+      .run(
+        data.taskId,
+        data.type,
+        data.title,
+        data.contentText ?? null,
+        data.filePath ?? null,
+        data.createdBy,
+        now
+      );
+  }
+
+  deleteByTaskId(taskId: number | string): void {
+    this.db.prepare("DELETE FROM artifacts WHERE taskId = ?").run(taskId);
+  }
+}

package/src/repositories/base.repository.ts

@@ -0,0 +1,5 @@
+import type { Database } from "bun:sqlite";
+
+export abstract class BaseRepository {
+  constructor(protected db: Database) {}
+}