@locusai/sdk 0.2.1

package/src/core/prompt-builder.ts

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync } from "node:fs";
+import { Task } from "@locusai/shared";
+import { getLocusPath } from "./config";
+import { CodebaseIndex } from "./indexer";
+
+export class PromptBuilder {
+  constructor(private projectPath: string) {}
+
+  async build(task: Task): Promise<string> {
+    let prompt = `# Task: ${task.title}\n\n`;
+
+    if (task.assigneeRole) {
+      prompt += `## Role\nYou are acting as a ${task.assigneeRole} engineer.\n\n`;
+    }
+
+    prompt += `## Description\n${task.description || "No description provided."}\n\n`;
+
+    // 1. Add CLAUDE.md context
+    const contextPath = getLocusPath(this.projectPath, "contextFile");
+    if (existsSync(contextPath)) {
+      try {
+        const context = readFileSync(contextPath, "utf-8");
+        prompt += `## Project Context (from CLAUDE.md)\n${context}\n\n`;
+      } catch (err) {
+        console.warn(`Warning: Could not read context file: ${err}`);
+      }
+    }
+
+    // 2. Add Codebase Index context
+    const indexPath = getLocusPath(this.projectPath, "indexFile");
+    if (existsSync(indexPath)) {
+      try {
+        const indexContent = readFileSync(indexPath, "utf-8");
+        const index = JSON.parse(indexContent) as CodebaseIndex;
+        prompt += this.formatIndex(index, task);
+      } catch (err) {
+        console.warn(`Warning: Could not read codebase index: ${err}`);
+      }
+    }
+
+    // 3. Add Documents
+    if (task.docs && task.docs.length > 0) {
+      prompt += `## Attached Documents\n`;
+      for (const doc of task.docs) {
+        prompt += `### ${doc.title}\n${doc.content || "(No content)"}\n\n`;
+      }
+    }
+
+    // 4. Add Checklist
+    if (task.acceptanceChecklist && task.acceptanceChecklist.length > 0) {
+      prompt += `## Acceptance Criteria\n`;
+      for (const item of task.acceptanceChecklist) {
+        prompt += `- ${item.done ? "[x]" : "[ ]"} ${item.text}\n`;
+      }
+      prompt += "\n";
+    }
+
+    // 5. Add Comments & Feedback
+    if (task.comments && task.comments.length > 0) {
+      prompt += `## Task History & Feedback\n`;
+      prompt += `Review the following comments for context or rejection feedback:\n\n`;
+      for (const comment of task.comments) {
+        const date = new Date(comment.createdAt).toLocaleString();
+        prompt += `### ${comment.author} (${date})\n${comment.text}\n\n`;
+      }
+    }
+
+    prompt += `## Instructions
+1. Complete this task. 
+2. **Artifact Management**: If you create any high-level documentation (PRDs, technical drafts, architecture docs), you MUST save them in \`.locus/artifacts/\`. Do NOT create them in the root directory.
+3. **Paths**: Use relative paths from the project root at all times. Do NOT use absolute local paths (e.g., /Users/...).
+4. When finished successfully, output: <promise>COMPLETE</promise>\n`;
+    return prompt;
+  }
+
+  private formatIndex(index: CodebaseIndex, task: Task): string {
+    let section = `## Codebase Overview\nThis codebase has been indexed to help you navigate.\n\n`;
+
+    // Structural directories
+    const structuralDirs = Object.entries(index.responsibilities || {})
+      .filter(([path]) => !path.includes(".") || path.split("/").length <= 2)
+      .slice(0, 15);
+
+    if (structuralDirs.length > 0) {
+      section += `### Project Structure\n${structuralDirs.map(([p, d]) => `- \`${p}\`: ${d}`).join("\n")}\n\n`;
+    }
+
+    // Relevant symbols
+    const keywords = `${task.title} ${task.description}`.toLowerCase();
+    const symbols = Object.entries(index.symbols || {})
+      .filter(([symbol]) => keywords.includes(symbol.toLowerCase()))
+      .slice(0, 10);
+
+    if (symbols.length > 0) {
+      section += `### Potentially Relevant Symbols\n${symbols.map(([s, f]) => `- \`${s}\` is defined in: ${Array.isArray(f) ? f.join(", ") : f}`).join("\n")}\n\n`;
+    }
+
+    return section;
+  }
+}

package/src/events.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from "events";
+
+export enum LocusEvent {
+  TOKEN_EXPIRED = "TOKEN_EXPIRED",
+  AUTH_ERROR = "AUTH_ERROR",
+  REQUEST_ERROR = "REQUEST_ERROR",
+}
+
+export interface LocusConfig {
+  baseUrl: string;
+  token?: string | null;
+  timeout?: number;
+}
+
+export class LocusEmitter extends EventEmitter {
+  on(event: LocusEvent.TOKEN_EXPIRED, listener: () => void): this;
+  on(event: LocusEvent.AUTH_ERROR, listener: (error: Error) => void): this;
+  on(event: LocusEvent.REQUEST_ERROR, listener: (error: Error) => void): this;
+  on(
+    event: LocusEvent | string,
+    listener: ((...args: unknown[]) => void) | (() => void)
+  ): this {
+    return super.on(event, listener);
+  }
+
+  emit(event: LocusEvent.TOKEN_EXPIRED): boolean;
+  emit(event: LocusEvent.AUTH_ERROR, error: Error): boolean;
+  emit(event: LocusEvent.REQUEST_ERROR, error: Error): boolean;
+  emit(event: LocusEvent | string, ...args: unknown[]): boolean {
+    return super.emit(event, ...args);
+  }
+}

package/src/index-node.ts

@@ -0,0 +1,20 @@
+/**
+ * Node.js-only exports
+ * This is a separate entry point for Node.js/CLI only
+ * It should NOT be imported by browser applications
+ *
+ * These modules use Node.js APIs (fs, child_process, etc.)
+ * and will break in browser environments
+ */
+
+// Node.js-only: Agent system
+export * from "./agent";
+// Node.js-only: AI clients
+export * from "./ai";
+// Node.js-only: Core utilities (uses fs)
+export * from "./core";
+// Re-export everything from main index (browser-safe)
+export * from "./index";
+
+// Node.js-only: Orchestrator
+export { AgentOrchestrator, type OrchestratorConfig } from "./orchestrator";

package/src/index.ts

@@ -0,0 +1,119 @@
+import axios, { AxiosInstance } from "axios";
+import { LocusConfig, LocusEmitter, LocusEvent } from "./events";
+import { AuthModule } from "./modules/auth";
+import { CiModule } from "./modules/ci";
+import { DocsModule } from "./modules/docs";
+import { InvitationsModule } from "./modules/invitations";
+import { OrganizationsModule } from "./modules/organizations";
+import { SprintsModule } from "./modules/sprints";
+import { TasksModule } from "./modules/tasks";
+import { WorkspacesModule } from "./modules/workspaces";
+
+// Browser-safe exports only
+export * from "./events";
+export * from "./modules/auth";
+export * from "./modules/ci";
+export * from "./modules/docs";
+export * from "./modules/invitations";
+export * from "./modules/organizations";
+export * from "./modules/sprints";
+export * from "./modules/tasks";
+export * from "./modules/workspaces";
+
+export class LocusClient {
+  private readonly api: AxiosInstance;
+  public readonly emitter: LocusEmitter;
+
+  public readonly auth: AuthModule;
+  public readonly tasks: TasksModule;
+  public readonly sprints: SprintsModule;
+  public readonly workspaces: WorkspacesModule;
+  public readonly organizations: OrganizationsModule;
+  public readonly invitations: InvitationsModule;
+  public readonly docs: DocsModule;
+  public readonly ci: CiModule;
+
+  constructor(config: LocusConfig) {
+    this.emitter = new LocusEmitter();
+
+    this.api = axios.create({
+      baseURL: config.baseUrl,
+      timeout: config.timeout || 10000,
+      headers: {
+        "Content-Type": "application/json",
+        ...(config.token ? { Authorization: `Bearer ${config.token}` } : {}),
+      },
+    });
+
+    this.setupInterceptors();
+
+    // Initialize modules
+    this.auth = new AuthModule(this.api, this.emitter);
+    this.tasks = new TasksModule(this.api, this.emitter);
+    this.sprints = new SprintsModule(this.api, this.emitter);
+    this.workspaces = new WorkspacesModule(this.api, this.emitter);
+    this.organizations = new OrganizationsModule(this.api, this.emitter);
+    this.invitations = new InvitationsModule(this.api, this.emitter);
+    this.docs = new DocsModule(this.api, this.emitter);
+    this.ci = new CiModule(this.api, this.emitter);
+  }
+
+  private setupInterceptors() {
+    this.api.interceptors.response.use(
+      (response) => {
+        if (
+          response.data &&
+          typeof response.data === "object" &&
+          "data" in response.data
+        ) {
+          response.data = response.data.data;
+        }
+        return response;
+      },
+      (error) => {
+        const status = error.response?.status;
+
+        // Extract error message from API response format: { error: { message: "..." } }
+        let message: string;
+
+        // Try to get message from API error response
+        if (
+          error.response?.data?.error?.message &&
+          typeof error.response.data.error.message === "string"
+        ) {
+          message = error.response.data.error.message;
+        } else if (
+          error.response?.data?.message &&
+          typeof error.response.data.message === "string"
+        ) {
+          message = error.response.data.message;
+        } else if (error.message && typeof error.message === "string") {
+          message = error.message;
+        } else {
+          message = "An error occurred";
+        }
+
+        // Create a new error with a meaningful message
+        const enhancedError = new Error(message);
+        enhancedError.name = `HTTP${status || "Error"}`;
+
+        if (status === 401) {
+          this.emitter.emit(LocusEvent.TOKEN_EXPIRED);
+          this.emitter.emit(LocusEvent.AUTH_ERROR, enhancedError);
+        } else {
+          this.emitter.emit(LocusEvent.REQUEST_ERROR, enhancedError);
+        }
+
+        return Promise.reject(enhancedError);
+      }
+    );
+  }
+
+  public setToken(token: string | null) {
+    if (token) {
+      this.api.defaults.headers.common.Authorization = `Bearer ${token}`;
+    } else {
+      delete this.api.defaults.headers.common.Authorization;
+    }
+  }
+}

package/src/modules/auth.ts

@@ -0,0 +1,48 @@
+import {
+  CompleteRegistration,
+  LoginResponse,
+  User,
+  VerifyOtp,
+} from "@locusai/shared";
+import { BaseModule } from "./base";
+
+export class AuthModule extends BaseModule {
+  async getMe(): Promise<User> {
+    const { data } = await this.api.get<User>("/auth/me");
+    return data;
+  }
+
+  async requestRegisterOtp(email: string): Promise<{ success: boolean }> {
+    const { data } = await this.api.post<{ success: boolean }>(
+      "/auth/register-otp",
+      { email }
+    );
+    return data;
+  }
+
+  async requestLoginOtp(email: string): Promise<{ success: boolean }> {
+    const { data } = await this.api.post<{ success: boolean }>(
+      "/auth/login-otp",
+      { email }
+    );
+    return data;
+  }
+
+  async verifyLogin(body: VerifyOtp): Promise<LoginResponse> {
+    const { data } = await this.api.post<LoginResponse>(
+      "/auth/verify-login",
+      body
+    );
+    return data;
+  }
+
+  async completeRegistration(
+    body: CompleteRegistration
+  ): Promise<LoginResponse> {
+    const { data } = await this.api.post<LoginResponse>(
+      "/auth/complete-registration",
+      body
+    );
+    return data;
+  }
+}

package/src/modules/base.ts

@@ -0,0 +1,9 @@
+import { AxiosInstance } from "axios";
+import { LocusEmitter } from "../events";
+
+export abstract class BaseModule {
+  constructor(
+    protected readonly api: AxiosInstance,
+    protected readonly emitter: LocusEmitter
+  ) {}
+}

package/src/modules/ci.ts

@@ -0,0 +1,12 @@
+import { ReportCiResult } from "@locusai/shared";
+import { BaseModule } from "./base";
+
+export class CiModule extends BaseModule {
+  async report(body: ReportCiResult): Promise<{ success: boolean }> {
+    const { data } = await this.api.post<{ success: boolean }>(
+      "/ci/report",
+      body
+    );
+    return data;
+  }
+}

package/src/modules/docs.ts

@@ -0,0 +1,84 @@
+import {
+  CreateDoc,
+  CreateDocGroup,
+  Doc,
+  DocGroup,
+  DocGroupResponse,
+  DocGroupsResponse,
+  DocResponse,
+  DocsResponse,
+  UpdateDoc,
+  UpdateDocGroup,
+} from "@locusai/shared";
+import { BaseModule } from "./base";
+
+export class DocsModule extends BaseModule {
+  async create(workspaceId: string, body: CreateDoc): Promise<Doc> {
+    const { data } = await this.api.post<DocResponse>(
+      `/workspaces/${workspaceId}/docs`,
+      body
+    );
+    return data.doc;
+  }
+
+  async list(workspaceId: string): Promise<Doc[]> {
+    const { data } = await this.api.get<DocsResponse>(
+      `/workspaces/${workspaceId}/docs`
+    );
+    return data.docs;
+  }
+
+  async getById(id: string, workspaceId: string): Promise<Doc> {
+    const { data } = await this.api.get<DocResponse>(
+      `/workspaces/${workspaceId}/docs/${id}`
+    );
+    return data.doc;
+  }
+
+  async update(id: string, workspaceId: string, body: UpdateDoc): Promise<Doc> {
+    const { data } = await this.api.put<DocResponse>(
+      `/workspaces/${workspaceId}/docs/${id}`,
+      body
+    );
+    return data.doc;
+  }
+
+  async delete(id: string, workspaceId: string): Promise<void> {
+    await this.api.delete(`/workspaces/${workspaceId}/docs/${id}`);
+  }
+
+  // Group Management
+  async listGroups(workspaceId: string): Promise<DocGroup[]> {
+    const { data } = await this.api.get<DocGroupsResponse>(
+      `/workspaces/${workspaceId}/doc-groups`
+    );
+    return data.groups;
+  }
+
+  async createGroup(
+    workspaceId: string,
+    body: CreateDocGroup
+  ): Promise<DocGroup> {
+    const { data } = await this.api.post<DocGroupResponse>(
+      `/workspaces/${workspaceId}/doc-groups`,
+      body
+    );
+    return data.group;
+  }
+
+  async updateGroup(
+    id: string,
+    workspaceId: string,
+    body: UpdateDocGroup
+  ): Promise<DocGroup> {
+    const { data } = await this.api.patch<DocGroupResponse>(
+      `/workspaces/${workspaceId}/doc-groups/${id}`,
+      body
+    );
+    return data.group;
+  }
+
+  async deleteGroup(id: string, workspaceId: string): Promise<void> {
+    await this.api.delete(`/workspaces/${workspaceId}/doc-groups/${id}`);
+  }
+}

package/src/modules/invitations.ts

@@ -0,0 +1,45 @@
+import {
+  AcceptInvitation,
+  AcceptInvitationResponse,
+  CreateInvitation,
+  Invitation,
+  InvitationResponse,
+  InvitationsResponse,
+} from "@locusai/shared";
+import { BaseModule } from "./base";
+
+export class InvitationsModule extends BaseModule {
+  async create(orgId: string, body: CreateInvitation): Promise<Invitation> {
+    const { data } = await this.api.post<InvitationResponse>(
+      `/org/${orgId}/invitations`,
+      body
+    );
+    return data.invitation;
+  }
+
+  async list(orgId: string): Promise<Invitation[]> {
+    const { data } = await this.api.get<InvitationsResponse>(
+      `/org/${orgId}/invitations`
+    );
+    return data.invitations;
+  }
+
+  async verify(token: string): Promise<InvitationResponse> {
+    const { data } = await this.api.get<InvitationResponse>(
+      `/invitations/verify/${token}`
+    );
+    return data;
+  }
+
+  async accept(body: AcceptInvitation): Promise<AcceptInvitationResponse> {
+    const { data } = await this.api.post<AcceptInvitationResponse>(
+      "/invitations/accept",
+      body
+    );
+    return data;
+  }
+
+  async revoke(orgId: string, id: string): Promise<void> {
+    await this.api.delete(`/org/${orgId}/invitations/${id}`);
+  }
+}

package/src/modules/organizations.ts

@@ -0,0 +1,90 @@
+import {
+  AddMember,
+  MembershipResponse,
+  MembershipWithUser,
+  MembersResponse,
+  Organization,
+  OrganizationResponse,
+  OrganizationsResponse,
+} from "@locusai/shared";
+import { BaseModule } from "./base";
+
+export interface ApiKey {
+  id: string;
+  organizationId: string;
+  name: string;
+  key: string;
+  active: boolean;
+  lastUsedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ApiKeysResponse {
+  apiKeys: ApiKey[];
+}
+
+interface ApiKeyResponse {
+  apiKey: ApiKey;
+}
+
+export class OrganizationsModule extends BaseModule {
+  async list(): Promise<Organization[]> {
+    const { data } =
+      await this.api.get<OrganizationsResponse>("/organizations");
+    return data.organizations;
+  }
+
+  async getById(id: string): Promise<Organization> {
+    const { data } = await this.api.get<OrganizationResponse>(
+      `/organizations/${id}`
+    );
+    return data.organization;
+  }
+
+  async listMembers(id: string): Promise<MembershipWithUser[]> {
+    const { data } = await this.api.get<MembersResponse>(
+      `/organizations/${id}/members`
+    );
+    return data.members;
+  }
+
+  async addMember(id: string, body: AddMember): Promise<MembershipWithUser> {
+    const { data } = await this.api.post<MembershipResponse>(
+      `/organizations/${id}/members`,
+      body
+    );
+    return data.membership;
+  }
+
+  async removeMember(orgId: string, userId: string): Promise<void> {
+    await this.api.delete(`/organizations/${orgId}/members/${userId}`);
+  }
+
+  async delete(orgId: string): Promise<void> {
+    await this.api.delete(`/organizations/${orgId}`);
+  }
+
+  // ============================================================================
+  // API Key Management
+  // ============================================================================
+
+  async listApiKeys(orgId: string): Promise<ApiKey[]> {
+    const { data } = await this.api.get<ApiKeysResponse>(
+      `/organizations/${orgId}/api-keys`
+    );
+    return data.apiKeys;
+  }
+
+  async createApiKey(orgId: string, name: string): Promise<ApiKey> {
+    const { data } = await this.api.post<ApiKeyResponse>(
+      `/organizations/${orgId}/api-keys`,
+      { name }
+    );
+    return data.apiKey;
+  }
+
+  async deleteApiKey(orgId: string, keyId: string): Promise<void> {
+    await this.api.delete(`/organizations/${orgId}/api-keys/${keyId}`);
+  }
+}

package/src/modules/sprints.ts

@@ -0,0 +1,69 @@
+import {
+  CreateSprint,
+  Sprint,
+  SprintResponse,
+  SprintsResponse,
+  UpdateSprint,
+} from "@locusai/shared";
+import { BaseModule } from "./base";
+
+export class SprintsModule extends BaseModule {
+  async list(workspaceId: string): Promise<Sprint[]> {
+    const { data } = await this.api.get<SprintsResponse>(
+      `/workspaces/${workspaceId}/sprints`
+    );
+    return data.sprints;
+  }
+
+  async getActive(workspaceId: string): Promise<Sprint> {
+    const { data } = await this.api.get<SprintResponse>(
+      `/workspaces/${workspaceId}/sprints/active`
+    );
+    return data.sprint;
+  }
+
+  async getById(id: string, workspaceId: string): Promise<Sprint> {
+    const { data } = await this.api.get<SprintResponse>(
+      `/workspaces/${workspaceId}/sprints/${id}`
+    );
+    return data.sprint;
+  }
+
+  async create(workspaceId: string, body: CreateSprint): Promise<Sprint> {
+    const { data } = await this.api.post<SprintResponse>(
+      `/workspaces/${workspaceId}/sprints`,
+      body
+    );
+    return data.sprint;
+  }
+
+  async update(
+    id: string,
+    workspaceId: string,
+    body: UpdateSprint
+  ): Promise<Sprint> {
+    const { data } = await this.api.patch<SprintResponse>(
+      `/workspaces/${workspaceId}/sprints/${id}`,
+      body
+    );
+    return data.sprint;
+  }
+
+  async delete(id: string, workspaceId: string): Promise<void> {
+    await this.api.delete(`/workspaces/${workspaceId}/sprints/${id}`);
+  }
+
+  async start(id: string, workspaceId: string): Promise<Sprint> {
+    const { data } = await this.api.post<SprintResponse>(
+      `/workspaces/${workspaceId}/sprints/${id}/start`
+    );
+    return data.sprint;
+  }
+
+  async complete(id: string, workspaceId: string): Promise<Sprint> {
+    const { data } = await this.api.post<SprintResponse>(
+      `/workspaces/${workspaceId}/sprints/${id}/complete`
+    );
+    return data.sprint;
+  }
+}