@locusai/locus-gateway 0.22.13

package/dist/index.cjs

@@ -0,0 +1,592 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  truncate: () => truncate,
+  splitMessage: () => splitMessage,
+  getCommandDefinition: () => getCommandDefinition,
+  bestFormat: () => bestFormat,
+  STREAMING_COMMANDS: () => STREAMING_COMMANDS,
+  Gateway: () => Gateway,
+  CommandTracker: () => CommandTracker,
+  CommandRouter: () => CommandRouter,
+  CommandExecutor: () => CommandExecutor,
+  COMMAND_REGISTRY: () => COMMAND_REGISTRY
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/commands.ts
+var COMMAND_REGISTRY = {
+  run: { cliArgs: ["run"], streaming: true },
+  status: { cliArgs: ["status"], streaming: false },
+  issues: { cliArgs: ["issue", "list"], streaming: false },
+  issue: { cliArgs: ["issue", "show"], streaming: false },
+  sprint: { cliArgs: ["sprint"], streaming: false },
+  plan: { cliArgs: ["plan"], streaming: true },
+  review: { cliArgs: ["review"], streaming: true },
+  iterate: { cliArgs: ["iterate"], streaming: true },
+  discuss: {
+    cliArgs: ["discuss"],
+    streaming: true,
+    requiresArgs: `Please provide a discussion topic.
+
+Example: /discuss Should we use Redis or in-memory caching?`
+  },
+  exec: {
+    cliArgs: ["exec"],
+    streaming: true,
+    requiresArgs: `Please provide a prompt.
+
+Example: /exec Add error handling to the API`
+  },
+  logs: { cliArgs: ["logs"], streaming: false },
+  config: { cliArgs: ["config"], streaming: false },
+  artifacts: { cliArgs: ["artifacts"], streaming: false }
+};
+var STREAMING_COMMANDS = new Set(Object.entries(COMMAND_REGISTRY).filter(([, def]) => def.streaming).map(([name]) => name));
+function getCommandDefinition(command) {
+  return COMMAND_REGISTRY[command] ?? null;
+}
+// src/executor.ts
+var import_node_child_process2 = require("node:child_process");
+var import_node_util = require("node:util");
+
+// ../sdk/dist/index.js
+var import_node_child_process = require("node:child_process");
+function invokeLocusStream(args, cwd) {
+  return import_node_child_process.spawn("locus", args, {
+    cwd: cwd ?? process.cwd(),
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+    shell: false
+  });
+}
+var colorEnabled = () => process.stderr.isTTY === true && process.env.NO_COLOR === undefined;
+var wrap = (open, close) => (text) => colorEnabled() ? `${open}${text}${close}` : text;
+var bold = wrap("\x1B[1m", "\x1B[22m");
+var dim = wrap("\x1B[2m", "\x1B[22m");
+var red = wrap("\x1B[31m", "\x1B[39m");
+var yellow = wrap("\x1B[33m", "\x1B[39m");
+var cyan = wrap("\x1B[36m", "\x1B[39m");
+var gray = wrap("\x1B[90m", "\x1B[39m");
+function formatData(data) {
+  if (!data || Object.keys(data).length === 0)
+    return "";
+  return ` ${dim(JSON.stringify(data))}`;
+}
+function createLogger(name) {
+  const prefix = dim(`[${name}]`);
+  return {
+    info(msg, data) {
+      process.stderr.write(`${bold(cyan("●"))} ${prefix} ${msg}${formatData(data)}
+`);
+    },
+    warn(msg, data) {
+      process.stderr.write(`${bold(yellow("⚠"))}  ${prefix} ${yellow(msg)}${formatData(data)}
+`);
+    },
+    error(msg, data) {
+      process.stderr.write(`${bold(red("✗"))} ${prefix} ${red(msg)}${formatData(data)}
+`);
+    },
+    debug(msg, data) {
+      if (!process.env.LOCUS_DEBUG)
+        return;
+      process.stderr.write(`${gray("⋯")} ${prefix} ${gray(msg)}${formatData(data)}
+`);
+    }
+  };
+}
+
+// src/executor.ts
+var exec = import_node_util.promisify(import_node_child_process2.exec);
+var STREAM_UPDATE_INTERVAL = 2000;
+
+class CommandExecutor {
+  tracker;
+  constructor(tracker) {
+    this.tracker = tracker;
+  }
+  getTracker() {
+    return this.tracker;
+  }
+  async executeLocusCommand(sessionId, command, args, callbacks) {
+    const definition = getCommandDefinition(command);
+    if (!definition) {
+      return {
+        text: `Unknown command: /${command}`,
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    if (definition.requiresArgs && args.length === 0) {
+      return {
+        text: definition.requiresArgs,
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    const conflict = this.tracker.checkExclusiveConflict(sessionId, command);
+    if (conflict) {
+      return {
+        text: formatConflictText(command, conflict),
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    const fullArgs = [...definition.cliArgs, ...args];
+    if (definition.streaming && callbacks) {
+      return this.executeStreaming(sessionId, command, args, fullArgs, callbacks);
+    }
+    return this.executeBuffered(sessionId, command, args, fullArgs);
+  }
+  async executeGit(sessionId, command, args, gitArgs) {
+    const conflict = this.tracker.checkExclusiveConflict(sessionId, command);
+    if (conflict) {
+      return {
+        text: formatConflictText(command, conflict),
+        format: "plain",
+        exitCode: 1
+      };
+    }
+    const trackingId = this.tracker.track(sessionId, command, args);
+    try {
+      const { stdout } = await exec(`git ${gitArgs}`, { cwd: process.cwd() });
+      return {
+        text: stdout,
+        format: "plain",
+        exitCode: 0
+      };
+    } catch (error) {
+      const errStr = String(error);
+      return {
+        text: errStr,
+        format: "plain",
+        exitCode: 1
+      };
+    } finally {
+      this.tracker.untrack(sessionId, trackingId);
+    }
+  }
+  async executeStreaming(sessionId, command, args, fullArgs, callbacks) {
+    const child = invokeLocusStream(fullArgs);
+    const trackingId = this.tracker.track(sessionId, command, args, child);
+    let output = "";
+    let lastUpdateTime = 0;
+    let updateTimer = null;
+    let messageId = "";
+    const displayCmd = `locus ${fullArgs.join(" ")}`;
+    const startResult = await callbacks.onStart(formatStreamingText(displayCmd, "", false));
+    if (startResult)
+      messageId = startResult;
+    const pushUpdate = async () => {
+      const now = Date.now();
+      if (now - lastUpdateTime < STREAM_UPDATE_INTERVAL)
+        return;
+      lastUpdateTime = now;
+      try {
+        await callbacks.onUpdate(messageId, formatStreamingText(displayCmd, output, false));
+      } catch {}
+    };
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+      if (updateTimer)
+        clearTimeout(updateTimer);
+      updateTimer = setTimeout(pushUpdate, STREAM_UPDATE_INTERVAL);
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    return new Promise((resolve) => {
+      child.on("close", async (exitCode) => {
+        this.tracker.untrack(sessionId, trackingId);
+        if (updateTimer)
+          clearTimeout(updateTimer);
+        const code = exitCode ?? 0;
+        await callbacks.onComplete(messageId, formatStreamingText(displayCmd, output, true), code);
+        resolve({
+          text: output,
+          format: "plain",
+          streaming: true,
+          exitCode: code
+        });
+      });
+    });
+  }
+  async executeBuffered(sessionId, command, args, fullArgs) {
+    const child = invokeLocusStream(fullArgs);
+    const trackingId = this.tracker.track(sessionId, command, args, child);
+    let output = "";
+    child.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    return new Promise((resolve) => {
+      child.on("close", (exitCode) => {
+        this.tracker.untrack(sessionId, trackingId);
+        const code = exitCode ?? 0;
+        resolve({
+          text: output,
+          format: "plain",
+          exitCode: code
+        });
+      });
+    });
+  }
+}
+function formatConflictText(blockedCommand, conflict) {
+  const running = conflict.runningCommand;
+  const runningLabel = `/${running.command}${running.args.length ? ` ${running.args.join(" ")}` : ""}`;
+  return `/${blockedCommand} cannot start — ${runningLabel} is already running.
+
+Send /cancel to abort it, or wait for it to finish.`;
+}
+function formatStreamingText(command, output, isComplete) {
+  const status = isComplete ? "[DONE]" : "[RUNNING]";
+  const header = `${status} ${command}`;
+  if (!output.trim()) {
+    return isComplete ? `${header}
+
+Completed.` : `${header}
+
+Running...
+
+Send /cancel to abort`;
+  }
+  const lines = output.trim().split(`
+`);
+  const lastLines = lines.slice(-30).join(`
+`);
+  const hint = isComplete ? "" : `
+
+Send /cancel to abort`;
+  return `${header}
+
+${lastLines}${hint}`;
+}
+// src/formatter.ts
+function bestFormat(capabilities) {
+  if (capabilities.supportsHTML)
+    return "html";
+  if (capabilities.supportsMarkdown)
+    return "markdown";
+  return "plain";
+}
+function splitMessage(text, maxLength) {
+  if (text.length <= maxLength)
+    return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+    let splitIdx = remaining.lastIndexOf(`
+`, maxLength);
+    if (splitIdx === -1 || splitIdx < maxLength / 2) {
+      splitIdx = maxLength;
+    }
+    chunks.push(remaining.slice(0, splitIdx));
+    remaining = remaining.slice(splitIdx);
+  }
+  return chunks;
+}
+function truncate(text, maxLength) {
+  if (text.length <= maxLength)
+    return text;
+  return `${text.slice(0, maxLength - 20)}
+
+... (truncated)`;
+}
+// src/router.ts
+class CommandRouter {
+  prefix;
+  constructor(prefix = "/") {
+    this.prefix = prefix;
+  }
+  parse(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith(this.prefix)) {
+      return { type: "freetext", text: trimmed };
+    }
+    const withoutPrefix = trimmed.slice(this.prefix.length);
+    const parts = withoutPrefix.split(/\s+/);
+    const rawCommand = parts[0] ?? "";
+    const command = rawCommand.replace(/@\S+$/, "").toLowerCase();
+    if (!command) {
+      return { type: "freetext", text: trimmed };
+    }
+    const args = parts.slice(1);
+    return {
+      type: "command",
+      command,
+      args,
+      raw: trimmed
+    };
+  }
+}
+
+// src/tracker.ts
+var WORKSPACE_EXCLUSIVE = new Set(["run", "plan", "iterate", "exec"]);
+var GIT_EXCLUSIVE = new Set(["stage", "commit", "checkout", "stash", "pr"]);
+function getExclusivityGroup(command) {
+  if (WORKSPACE_EXCLUSIVE.has(command))
+    return "workspace";
+  if (GIT_EXCLUSIVE.has(command))
+    return "git";
+  return null;
+}
+var nextId = 1;
+
+class CommandTracker {
+  active = new Map;
+  track(sessionId, command, args, childProcess = null) {
+    const id = String(nextId++);
+    const entry = {
+      id,
+      command,
+      args,
+      childProcess,
+      startedAt: new Date
+    };
+    const list = this.active.get(sessionId);
+    if (list) {
+      list.push(entry);
+    } else {
+      this.active.set(sessionId, [entry]);
+    }
+    return id;
+  }
+  untrack(sessionId, id) {
+    const list = this.active.get(sessionId);
+    if (!list)
+      return;
+    const idx = list.findIndex((c) => c.id === id);
+    if (idx !== -1)
+      list.splice(idx, 1);
+    if (list.length === 0)
+      this.active.delete(sessionId);
+  }
+  getActive(sessionId) {
+    return this.active.get(sessionId) ?? [];
+  }
+  checkExclusiveConflict(sessionId, command) {
+    const group = getExclusivityGroup(command);
+    if (!group)
+      return null;
+    const list = this.active.get(sessionId);
+    if (!list)
+      return null;
+    for (const entry of list) {
+      if (getExclusivityGroup(entry.command) === group) {
+        return { blocked: true, runningCommand: entry, group };
+      }
+    }
+    return null;
+  }
+  kill(sessionId, id) {
+    const list = this.active.get(sessionId);
+    if (!list)
+      return false;
+    const entry = list.find((c) => c.id === id);
+    if (!entry)
+      return false;
+    if (entry.childProcess && !entry.childProcess.killed) {
+      entry.childProcess.kill("SIGTERM");
+    }
+    this.untrack(sessionId, id);
+    return true;
+  }
+  killAll(sessionId) {
+    const list = this.active.get(sessionId);
+    if (!list)
+      return 0;
+    let killed = 0;
+    for (const entry of list) {
+      if (entry.childProcess && !entry.childProcess.killed) {
+        entry.childProcess.kill("SIGTERM");
+      }
+      killed++;
+    }
+    this.active.delete(sessionId);
+    return killed;
+  }
+}
+
+// src/gateway.ts
+var logger = createLogger("gateway");
+
+class Gateway {
+  adapters = new Map;
+  router;
+  executor;
+  tracker;
+  onEvent;
+  constructor(options = {}) {
+    this.router = new CommandRouter;
+    this.tracker = new CommandTracker;
+    this.executor = new CommandExecutor(this.tracker);
+    this.onEvent = options.onEvent;
+  }
+  register(adapter) {
+    if (this.adapters.has(adapter.platform)) {
+      throw new Error(`Adapter already registered for platform: ${adapter.platform}`);
+    }
+    this.adapters.set(adapter.platform, adapter);
+    logger.info(`Registered adapter: ${adapter.platform}`);
+  }
+  getAdapter(platform) {
+    return this.adapters.get(platform);
+  }
+  getRouter() {
+    return this.router;
+  }
+  getExecutor() {
+    return this.executor;
+  }
+  getTracker() {
+    return this.tracker;
+  }
+  async handleMessage(message) {
+    this.emit({ type: "message_received", message });
+    const adapter = this.adapters.get(message.platform);
+    if (!adapter) {
+      logger.warn(`No adapter registered for platform: ${message.platform}`);
+      return;
+    }
+    const parsed = this.router.parse(message.text);
+    if (parsed.type === "freetext") {
+      await this.executeCommand(adapter, message.sessionId, "exec", [parsed.text], message);
+      return;
+    }
+    await this.executeCommand(adapter, message.sessionId, parsed.command, parsed.args, message);
+  }
+  async start() {
+    const platforms = Array.from(this.adapters.keys());
+    logger.info(`Starting gateway with adapters: ${platforms.join(", ")}`);
+    for (const [platform, adapter] of this.adapters) {
+      try {
+        await adapter.start();
+        logger.info(`Started adapter: ${platform}`);
+      } catch (error) {
+        logger.error(`Failed to start adapter: ${platform}`, {
+          error: String(error)
+        });
+        throw error;
+      }
+    }
+  }
+  async stop() {
+    for (const [platform, adapter] of this.adapters) {
+      try {
+        await adapter.stop();
+        logger.info(`Stopped adapter: ${platform}`);
+      } catch (error) {
+        logger.warn(`Error stopping adapter: ${platform}`, {
+          error: String(error)
+        });
+      }
+    }
+  }
+  async executeCommand(adapter, sessionId, command, args, _originalMessage) {
+    this.emit({
+      type: "command_started",
+      sessionId,
+      command,
+      args
+    });
+    let streamCallbacks;
+    if (adapter.capabilities.supportsStreaming && adapter.edit) {
+      const adapterRef = adapter;
+      const sentMessageId = "";
+      streamCallbacks = {
+        async onStart(text) {
+          await adapterRef.send(sessionId, {
+            text,
+            format: "plain"
+          });
+          return sentMessageId;
+        },
+        async onUpdate(messageId, text) {
+          if (adapterRef.edit) {
+            await adapterRef.edit(sessionId, messageId, {
+              text,
+              format: "plain"
+            });
+          }
+        },
+        async onComplete(messageId, text, _exitCode) {
+          if (adapterRef.edit) {
+            await adapterRef.edit(sessionId, messageId, {
+              text,
+              format: "plain"
+            });
+          }
+        }
+      };
+    }
+    const result = await this.executor.executeLocusCommand(sessionId, command, args, streamCallbacks);
+    this.emit({
+      type: "command_completed",
+      sessionId,
+      command,
+      exitCode: result.exitCode
+    });
+    if (!result.streaming) {
+      await adapter.send(sessionId, {
+        text: result.text,
+        format: result.format,
+        actions: result.actions
+      });
+    }
+  }
+  emit(event) {
+    if (this.onEvent) {
+      try {
+        this.onEvent(event);
+      } catch (error) {
+        logger.warn("Event handler error", { error: String(error) });
+      }
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @locusai/locus-gateway — Channel-agnostic message gateway for Locus.
+ *
+ * Provides the core abstractions for building platform adapters
+ * (Telegram, Discord, WhatsApp, etc.) that connect to the Locus CLI.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   Gateway,
+ *   CommandRouter,
+ *   CommandExecutor,
+ *   CommandTracker,
+ * } from "@locusai/locus-gateway";
+ * import type {
+ *   PlatformAdapter,
+ *   PlatformCapabilities,
+ *   InboundMessage,
+ *   OutboundMessage,
+ * } from "@locusai/locus-gateway";
+ * ```
+ */
+export { COMMAND_REGISTRY, getCommandDefinition, STREAMING_COMMANDS, } from "./commands.js";
+export type { StreamCallbacks } from "./executor.js";
+export { CommandExecutor } from "./executor.js";
+export { bestFormat, splitMessage, truncate } from "./formatter.js";
+export type { GatewayEventHandler, GatewayOptions } from "./gateway.js";
+export { Gateway } from "./gateway.js";
+export { CommandRouter } from "./router.js";
+export { CommandTracker } from "./tracker.js";
+export type { Action, ActiveCommand, Attachment, CommandDefinition, CommandResult, ConflictResult, ExclusivityGroup, FreeText, GatewayEvent, InboundMessage, OutboundMessage, ParsedCommand, PlatformAdapter, PlatformCapabilities, RouteContext, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAExE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EACV,MAAM,EACN,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,eAAe,EACf,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,YAAY,GACb,MAAM,YAAY,CAAC"}