borgmcp 1.1.15 → 2.0.1

package/src/self-path.ts

@@ -0,0 +1,51 @@
+/**
+ * Resolve absolute paths to sibling bin executables from the running entrypoint.
+ *
+ * When borg-mcp is installed globally or repo-locally, MCP config registrations
+ * and orientation commands must use the exact binary from THIS installation, not
+ * a bare name resolved via PATH (which may point to a different version).
+ *
+ * `fileURLToPath(import.meta.url)` gives the realpath of the compiled JS file
+ * under `dist/`. All bin targets are siblings in the same `dist/` directory.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to a sibling bin file in dist/.
+ * Returns the path even if the file does not yet exist (caller decides whether
+ * to fail) so callers that write config can store the path before build.
+ */
+export function resolveSelfBinPath(binName: string): string {
+  const binPath = path.join(DIST_DIR, binName);
+  return binPath;
+}
+
+/** Absolute path to the borg-mcp stdio server entrypoint (dist/index.js). */
+export function resolveMcpBinaryPath(): string {
+  return resolveSelfBinPath('index.js');
+}
+
+/** Absolute path to borg-regen (dist/regen.js). */
+export function resolveRegenPath(): string {
+  return resolveSelfBinPath('regen.js');
+}
+
+/** Absolute path to borg-inbox-monitor (dist/inbox-monitor.js). */
+export function resolveInboxMonitorPath(): string {
+  return resolveSelfBinPath('inbox-monitor.js');
+}
+
+/** Absolute path to borg-clear-rewake (dist/clear-rewake.js). */
+export function resolveClearRewakePath(): string {
+  return resolveSelfBinPath('clear-rewake.js');
+}
+
+/** Absolute path to borg-log-audit (dist/log-audit.js). */
+export function resolveLogAuditPath(): string {
+  return resolveSelfBinPath('log-audit.js');
+}

package/src/server-endpoint.ts

@@ -0,0 +1,38 @@
+/**
+ * Normalize the endpoint accepted by `borg assimilate --host <host>`.
+ *
+ * Bare hosts default to HTTPS, including loopback: the ratified v1 server
+ * architecture requires TLS for every authority. Plaintext endpoints are
+ * rejected even on loopback so enrollment credentials never cross HTTP.
+ */
+export function normalizeServerEndpoint(input: string): string {
+  const raw = input.trim();
+  if (!raw) throw new Error('--host requires a host or URL');
+
+  const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw);
+  let url: URL;
+  try {
+    url = new URL(hasScheme ? raw : `https://${raw}`);
+  } catch {
+    // Never echo the raw input: malformed URLs may contain pasted credentials.
+    throw new Error('invalid Borg server endpoint');
+  }
+
+  if (url.protocol !== 'https:') {
+    throw new Error('Borg server endpoints must use https://');
+  }
+  if (url.username || url.password) {
+    throw new Error('Borg server endpoints must not contain credentials');
+  }
+  if (url.search || url.hash) {
+    throw new Error('Borg server endpoints must not contain a query string or fragment');
+  }
+  if (url.pathname !== '/' && url.pathname !== '') {
+    throw new Error('Borg server endpoints must not contain a path');
+  }
+  if (url.hostname === '0.0.0.0' || url.hostname === '[::]') {
+    throw new Error('Borg server endpoints must not use a wildcard address');
+  }
+
+  return url.origin;
+}

package/src/server-errors.ts

@@ -0,0 +1,93 @@
+export type BorgServerErrorCode =
+  | 'NOT_ENROLLED'
+  | 'CREDENTIAL_REJECTED'
+  | 'INVITATION_REJECTED'
+  | 'CREATE_CUBE_DENIED'
+  | 'ATTACH_CONFLICT'
+  | 'SESSION_REJECTED';
+
+/** Safe, non-secret state code for deterministic authority recovery copy. */
+export class BorgServerError extends Error {
+  constructor(
+    public readonly code: BorgServerErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'BorgServerError';
+  }
+}
+
+/**
+ * CR5: a STABLE TYPED non-ok HTTP verdict from a verified server. Carries the raw
+ * status so the seat probe classifies endpoint/protocol-mismatch (404) vs
+ * server-failure (5xx) from the actual code — never a mutable error-text regex.
+ * The message is kept identical to the pre-typed string for call-site parity.
+ */
+export class BorgServerHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code?: ErrorCode,
+  ) {
+    super(message);
+    this.name = 'BorgServerHttpError';
+  }
+}
+
+export class LocalManageRequiredError extends Error {
+  constructor(
+    public readonly operation: string,
+    public readonly cubeName: string,
+    public readonly noMutation: string,
+  ) {
+    super(
+      `[LOCAL-MANAGE-REQUIRED] This session cannot ${operation} because ` +
+      'the selected local client does not have cube management access.\n\n' +
+      'Coordinator and Queen are workflow roles; they do not grant server permissions. ' +
+      `${noMutation} Do not retry this request from this session.\n\n` +
+      'Use a session whose local client already has management access to this cube.',
+    );
+    this.name = 'LocalManageRequiredError';
+  }
+}
+
+export class LocalManageCredentialUnavailableError extends Error {
+  constructor(
+    public readonly operation: string,
+    public readonly cubeName: string,
+    public readonly noMutation: string,
+  ) {
+    super(
+      `The selected local client credential for cube "${cubeName}" is missing or unreadable. ` +
+      `This session cannot ${operation}. ${noMutation} Restore or re-enroll the selected local ` +
+      'client before retrying.',
+    );
+    this.name = 'LocalManageCredentialUnavailableError';
+  }
+}
+
+/**
+ * CR5: a STABLE TYPED terminal trust verdict — the pinned server identity no longer
+ * matches. This is a security boundary: it must be classified from the error TYPE,
+ * never from an error-text regex ("regex classification is not an authority
+ * boundary"). trust-mismatch is terminal (never launch-anyway, never credential-send).
+ */
+export class BorgServerTrustError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BorgServerTrustError';
+  }
+}
+
+/**
+ * CR5: a STABLE TYPED transport-failure verdict — the server was unreachable
+ * (connection refused/reset, DNS failure) or the request timed out. Distinct from
+ * an HTTP status; genuinely transient.
+ */
+export class BorgServerUnreachableError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'BorgServerUnreachableError';
+  }
+}
+import type { ErrorCode } from 'borgmcp-shared/protocol';