borgmcp-server 0.1.1 → 0.1.5

package/src/migrations.ts

@@ -7,6 +7,13 @@ export interface Migration {
   readonly sql: string;
 }
 
+export class MigrationCompatibilityError extends Error {
+  constructor() {
+    super("Database migrations do not exactly match this server version.");
+    this.name = "MigrationCompatibilityError";
+  }
+}
+
 export const STORE_MIGRATIONS: readonly Migration[] = Object.freeze([
   {
     version: 1,
@@ -303,6 +310,74 @@ export const STORE_MIGRATIONS: readonly Migration[] = Object.freeze([
         ON seat_attach_bindings (drone_id, client_id, cube_id);
     `,
   },
+  {
+    version: 7,
+    name: "role_management_foundation",
+    sql: `
+      ALTER TABLE roles ADD COLUMN is_mandatory INTEGER NOT NULL DEFAULT 0
+        CHECK (is_mandatory IN (0, 1));
+      ALTER TABLE roles ADD COLUMN can_broadcast INTEGER NOT NULL DEFAULT 0
+        CHECK (can_broadcast IN (0, 1));
+      ALTER TABLE roles ADD COLUMN receives_all_direct INTEGER NOT NULL DEFAULT 0
+        CHECK (receives_all_direct IN (0, 1));
+
+      CREATE UNIQUE INDEX roles_one_default_per_cube_idx
+        ON roles (cube_id) WHERE is_default = 1;
+    `,
+  },
+  {
+    version: 8,
+    name: "cube_scoped_invitations",
+    sql: `
+      ALTER TABLE enrollment_invitations ADD COLUMN cube_id TEXT;
+      ALTER TABLE enrollment_invitations ADD COLUMN access TEXT
+        CHECK (access IS NULL OR access IN ('read', 'write', 'manage'));
+
+      CREATE TRIGGER enrollment_invitations_scope_insert
+      BEFORE INSERT ON enrollment_invitations
+      WHEN (NEW.cube_id IS NULL) <> (NEW.access IS NULL)
+        OR (NEW.cube_id IS NOT NULL AND NEW.purpose <> 'client')
+      BEGIN
+        SELECT RAISE(ABORT, 'invalid invitation cube scope');
+      END;
+
+      CREATE TRIGGER enrollment_invitations_scope_update
+      BEFORE UPDATE OF cube_id, access, purpose ON enrollment_invitations
+      WHEN (NEW.cube_id IS NULL) <> (NEW.access IS NULL)
+        OR (NEW.cube_id IS NOT NULL AND NEW.purpose <> 'client')
+      BEGIN
+        SELECT RAISE(ABORT, 'invalid invitation cube scope');
+      END;
+    `,
+  },
+  {
+    version: 9,
+    name: "digest_correlated_seat_attach",
+    sql: `
+      DROP TABLE seat_attach_bindings;
+      DROP INDEX drones_client_retry_key_idx;
+      ALTER TABLE drones DROP COLUMN retry_key;
+      ALTER TABLE drones DROP COLUMN attach_generation;
+    `,
+  },
+  {
+    version: 10,
+    name: "cube_message_taxonomy",
+    sql: "ALTER TABLE cubes ADD COLUMN message_taxonomy TEXT;",
+  },
+  {
+    version: 11,
+    name: "fleet_liveness",
+    sql: `
+      CREATE INDEX activity_log_drone_post_idx
+        ON activity_log (cube_id, drone_id, created_at, id) WHERE drone_id IS NOT NULL;
+      CREATE TABLE silent_seat_ping_state (
+        drone_id TEXT PRIMARY KEY REFERENCES drones(id) ON DELETE CASCADE,
+        attempts INTEGER NOT NULL CHECK (attempts BETWEEN 1 AND 3),
+        last_ping_at TEXT NOT NULL
+      ) STRICT;
+    `,
+  },
 ]);
 
 interface AppliedMigrationRow {
@@ -366,6 +441,33 @@ export function applyMigrations(
   }
 }
 
+export function assertMigrationsCurrent(
+  database: DatabaseSync,
+  migrations: readonly Migration[] = STORE_MIGRATIONS,
+): void {
+  validateMigrationOrder(migrations);
+  let rows: Record<string, unknown>[];
+  try {
+    rows = database.prepare(
+      "SELECT version, name, checksum FROM schema_migrations ORDER BY version",
+    ).all();
+  } catch {
+    throw new MigrationCompatibilityError();
+  }
+  if (rows.length !== migrations.length) throw new MigrationCompatibilityError();
+  for (let index = 0; index < migrations.length; index += 1) {
+    let applied: AppliedMigrationRow;
+    try {
+      applied = appliedMigrationRow(rows[index]!);
+    } catch {
+      throw new MigrationCompatibilityError();
+    }
+    const expected = migrations[index]!;
+    if (applied.version !== expected.version || applied.name !== expected.name ||
+        applied.checksum !== checksum(expected)) throw new MigrationCompatibilityError();
+  }
+}
+
 function validateMigrationOrder(migrations: readonly Migration[]): void {
   migrations.forEach((migration, index) => {
     if (migration.version !== index + 1 || migration.name.length === 0 || migration.sql.length === 0) {

package/src/operator-error.ts

@@ -5,6 +5,9 @@ export type OperatorErrorCode =
   | "START_HOST_MISSING"
   | "START_PORT_MISSING"
   | "START_PORT_INVALID"
+  | "START_LOG_LEVEL_DUPLICATE"
+  | "START_LOG_LEVEL_MISSING"
+  | "START_LOG_LEVEL_INVALID"
   | "START_OPTION_UNKNOWN"
   | "BIND_PORT_INVALID"
   | "BIND_HOST_INVALID"
@@ -13,6 +16,7 @@ export type OperatorErrorCode =
   | "BIND_LAN_CONSENT"
   | "SERVER_FILES_MISSING"
   | "DATA_PATH_SYMLINK"
+  | "INSTALLATION_EXISTS"
   | "LAN_CA_KEY_ONLINE"
   | "RUNTIME_ACTIVE"
   | "RUNTIME_LOCK_UNSAFE"
@@ -23,7 +27,13 @@ export type OperatorErrorCode =
   | "DISK_RESERVE_INVALID"
   | "CLIENT_NOT_FOUND"
   | "GRANT_NOT_FOUND"
-  | "RECOVERY_INVALID";
+  | "RECOVERY_INVALID"
+  | "INVITATION_BUSY"
+  | "INVITATION_CONTENTION"
+  | "INVITATION_SCHEMA_MISMATCH"
+  | "INVITATION_CUBE_NOT_FOUND"
+  | "INVITATION_CUBE_SELECTOR_INVALID"
+  | "INVITATION_CUBE_AMBIGUOUS";
 
 const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freeze({
   START_LAN_DUPLICATE: "Provide --lan only once.",
@@ -32,6 +42,9 @@ const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freez
   START_HOST_MISSING: "Provide an IP address after --host.",
   START_PORT_MISSING: "Provide a port number after --port.",
   START_PORT_INVALID: "Provide --port as an integer from 0 to 65535.",
+  START_LOG_LEVEL_DUPLICATE: "Provide --log-level only once.",
+  START_LOG_LEVEL_MISSING: "Provide debug after --log-level.",
+  START_LOG_LEVEL_INVALID: "Use --log-level debug or omit the option.",
   START_OPTION_UNKNOWN: "Use only documented start options; run borg-mcp-server help.",
   BIND_PORT_INVALID: "Configure the listen port as an integer from 0 to 65535.",
   BIND_HOST_INVALID: "Configure --host as an explicit IP address.",
@@ -40,8 +53,9 @@ const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freez
   BIND_LAN_CONSENT: "Add --lan to consent to this private-LAN start.",
   SERVER_FILES_MISSING: "Configure BORG_SERVER_DATA_DIR or the required TLS file variables.",
   DATA_PATH_SYMLINK: "Choose a BORG_SERVER_DATA_DIR path that contains no symbolic links.",
+  INSTALLATION_EXISTS: "An installation already exists in BORG_SERVER_DATA_DIR. To destroy and recreate it, stop the server and run borg-mcp-server setup --reinitialize.",
   LAN_CA_KEY_ONLINE: "Move ca.key out of the runtime data directory before private-LAN startup.",
-  RUNTIME_ACTIVE: "Stop the server before running offline client administration.",
+  RUNTIME_ACTIVE: "Stop the server before running setup or offline administration.",
   RUNTIME_LOCK_UNSAFE: "Ensure runtime.lock is a private regular file before retrying.",
   RUNTIME_LOCK_INVALID: "Confirm the server is stopped, then remove the invalid runtime.lock.",
   RUNTIME_LOCK_STALE: "Confirm the recorded server process is stopped, then remove runtime.lock.",
@@ -51,22 +65,30 @@ const publicMessages: Readonly<Record<OperatorErrorCode, string>> = Object.freez
   CLIENT_NOT_FOUND: "Provide an existing active client ID.",
   GRANT_NOT_FOUND: "Provide an existing client cube grant.",
   RECOVERY_INVALID: "Provide the active recovery credential through the private prompt.",
+  INVITATION_BUSY: "Confirm no invitation or offline administration command is running, then remove invitation-mint.lock.",
+  INVITATION_CONTENTION: "Retry invitation minting after the current server database write completes.",
+  INVITATION_SCHEMA_MISMATCH: "Invitation minting is unavailable while a server with an incompatible schema is running. Stop the server and rerun this command, or use the CLI version that matches the running server.",
+  INVITATION_CUBE_NOT_FOUND: "Provide an existing cube name or full cube ID.",
+  INVITATION_CUBE_SELECTOR_INVALID: "Provide a full canonical cube UUID or an exact case-sensitive cube name.",
+  INVITATION_CUBE_AMBIGUOUS: "Cube name is ambiguous. Rerun with the full cube ID.",
 });
 
 const operatorErrorCodes = new WeakMap<object, OperatorErrorCode>();
+const operatorErrorMessages = new WeakMap<object, string>();
 const operatorErrorCapability = Object.freeze({});
 
 class OperatorError extends Error {
   readonly #operatorCode: OperatorErrorCode;
 
-  constructor(capability: object, code: OperatorErrorCode) {
-    super(Object.hasOwn(publicMessages, code) ? publicMessages[code] : "Operator error rejected.");
+  constructor(capability: object, code: OperatorErrorCode, publicMessage?: string) {
+    super(publicMessage ?? (Object.hasOwn(publicMessages, code) ? publicMessages[code] : "Operator error rejected."));
     if (capability !== operatorErrorCapability || !Object.hasOwn(publicMessages, code)) {
       throw new Error("Operator error construction is unavailable.");
     }
     this.name = "OperatorError";
     this.#operatorCode = code;
     operatorErrorCodes.set(this, code);
+    operatorErrorMessages.set(this, this.message);
     Object.freeze(this);
   }
 
@@ -75,7 +97,7 @@ class OperatorError extends Error {
   }
 
   get publicMessage(): string {
-    return publicMessages[this.#operatorCode];
+    return operatorErrorMessages.get(this) ?? publicMessages[this.#operatorCode];
   }
 }
 
@@ -93,5 +115,17 @@ export function operatorPublicMessage(error: unknown): string | null {
   const code = operatorErrorCodes.get(error);
   if (code === undefined) return null;
   if (Object.getPrototypeOf(error) !== OperatorError.prototype || !Object.isFrozen(error)) return null;
-  return publicMessages[code];
+  return operatorErrorMessages.get(error) ?? publicMessages[code];
+}
+
+export function invitationCubeAmbiguousError(candidateIds: readonly string[]): Error {
+  if (candidateIds.length < 2 || candidateIds.some((id) =>
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(id))) {
+    throw new Error("Ambiguous cube candidates must contain canonical cube IDs.");
+  }
+  return new OperatorError(
+    operatorErrorCapability,
+    "INVITATION_CUBE_AMBIGUOUS",
+    `Cube name is ambiguous. Rerun with the full cube ID. Candidate cube IDs: ${candidateIds.join(", ")}`,
+  );
 }

package/src/role-section.ts

@@ -0,0 +1,108 @@
+export type RoleSectionPatchOp =
+  | { readonly action: "replace"; readonly heading: string; readonly body: string }
+  | {
+    readonly action: "insert";
+    readonly heading: string;
+    readonly body: string;
+    readonly after?: string | null;
+  }
+  | { readonly action: "delete"; readonly heading: string };
+
+interface RoleSection {
+  readonly heading: string | null;
+  readonly body: string;
+}
+
+export function patchRoleSectionText(text: string, operation: RoleSectionPatchOp): string {
+  validateHeading(operation.heading);
+  const sections = parseSections(text);
+  const target = normalizedHeading(operation.heading);
+  const index = sections.findIndex((section) =>
+    section.heading !== null && normalizedHeading(section.heading) === target
+  );
+
+  if (operation.action === "replace") {
+    if (index === -1) throw new Error("Role section not found.");
+    sections[index] = renderedSection(operation.heading, operation.body);
+    return serializeSections(sections);
+  }
+  if (operation.action === "delete") {
+    if (index === -1) throw new Error("Role section not found.");
+    sections.splice(index, 1);
+    return serializeSections(sections);
+  }
+  if (index !== -1) throw new Error("Role section already exists.");
+
+  const section = renderedSection(operation.heading, operation.body);
+  if (operation.after == null) {
+    ensureTrailingNewline(sections, sections.length - 1);
+    sections.push(section);
+    return serializeSections(sections);
+  }
+  validateHeading(operation.after);
+  const after = normalizedHeading(operation.after);
+  const afterIndex = sections.findIndex((candidate) =>
+    candidate.heading !== null && normalizedHeading(candidate.heading) === after
+  );
+  if (afterIndex === -1) throw new Error("Role section insertion point does not exist.");
+  ensureTrailingNewline(sections, afterIndex);
+  sections.splice(afterIndex + 1, 0, section);
+  return serializeSections(sections);
+}
+
+function parseSections(text: string): RoleSection[] {
+  const sections: RoleSection[] = [];
+  const lines = text.split("\n");
+  let heading: string | null = null;
+  let body = "";
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    const sourceLine = index < lines.length - 1 ? `${line}\n` : line;
+    if (isLabelLine(line)) {
+      sections.push({ heading, body });
+      heading = line.slice(0, -1).trim();
+      body = sourceLine;
+    } else {
+      body += sourceLine;
+    }
+  }
+  sections.push({ heading, body });
+  return sections;
+}
+
+function isLabelLine(line: string): boolean {
+  if (/^\s/u.test(line) || !line.endsWith(":")) return false;
+  const label = line.slice(0, -1);
+  return label.length > 0 && label.length <= 60 && !label.includes(":") &&
+    !/^[*\-#>`]/u.test(label);
+}
+
+function renderedSection(heading: string, body: string): RoleSection {
+  const normalizedBody = body === "" || body.endsWith("\n") ? body : `${body}\n`;
+  return {
+    heading: heading.trim(),
+    body: `${heading.trim()}:\n${normalizedBody}`,
+  };
+}
+
+function ensureTrailingNewline(sections: RoleSection[], index: number): void {
+  const section = sections[index];
+  if (section !== undefined && section.body !== "" && !section.body.endsWith("\n")) {
+    sections[index] = { ...section, body: `${section.body}\n` };
+  }
+}
+
+function serializeSections(sections: readonly RoleSection[]): string {
+  return sections.map((section) => section.body).join("");
+}
+
+function normalizedHeading(heading: string): string {
+  return heading.trim().toLowerCase();
+}
+
+function validateHeading(heading: string): void {
+  if (typeof heading !== "string" || /[\r\n]/u.test(heading) ||
+      !isLabelLine(`${heading.trim()}:`)) {
+    throw new TypeError("Role section heading is invalid.");
+  }
+}