borgmcp 4.6.1 → 4.7.0

package/src/repository-identity.ts

@@ -37,39 +37,132 @@ interface RepositoryIdentityState {
 }
 
 export interface RepositoryIdentityDeps {
-  runGit?: (cwd: string, args: string[]) => { status: number | null; stdout?: string | null };
+  runGit?: (cwd: string, args: string[]) => GitCommandResult;
   canonicalPath?: (path: string) => Promise<string>;
   root?: string;
 }
 
+interface GitCommandResult {
+  status: number | null;
+  stdout?: string | null;
+  stderr?: string | null;
+  error?: Error;
+}
+
+export class RepositoryDiscoveryError extends Error {
+  readonly name = 'RepositoryDiscoveryError';
+
+  constructor(
+    readonly kind: 'git-execution' | 'git-query' | 'canonical-path',
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+export function repositoryDiscoveryFailureMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/[\x00-\x1F\x7F]/g, '').trim() || 'Unknown repository discovery failure';
+}
+
 function defaultRunGit(cwd: string, args: string[]) {
-  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
-  return { status: result.status, stdout: result.stdout };
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, LC_ALL: 'C' },
+  });
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr, error: result.error };
 }
 
-function output(result: { status: number | null; stdout?: string | null }): string | null {
+function output(result: GitCommandResult): string | null {
   const value = result.status === 0 ? result.stdout?.trim() : null;
   return value || null;
 }
 
+function runGitForDiscovery(
+  runGit: NonNullable<RepositoryIdentityDeps['runGit']>,
+  cwd: string,
+  args: string[],
+): GitCommandResult {
+  let result: GitCommandResult;
+  try {
+    result = runGit(cwd, args);
+  } catch (cause) {
+    throw new RepositoryDiscoveryError(
+      'git-execution',
+      `Git repository discovery could not run: ${repositoryDiscoveryFailureMessage(cause)}`,
+      { cause },
+    );
+  }
+  if (result.error) {
+    throw new RepositoryDiscoveryError(
+      'git-execution',
+      `Git repository discovery could not run: ${repositoryDiscoveryFailureMessage(result.error)}`,
+      { cause: result.error },
+    );
+  }
+  return result;
+}
+
+function gitQueryFailure(label: string, result: GitCommandResult): RepositoryDiscoveryError {
+  const detail = (result.stderr ?? '').replace(/[\x00-\x1F\x7F]/g, '').trim();
+  const suffix = detail ? `: ${detail}` : ` (Git exited with status ${result.status ?? 'unknown'})`;
+  return new RepositoryDiscoveryError(
+    'git-query',
+    `Git repository discovery failed while querying ${label}${suffix}`,
+  );
+}
+
+async function canonicalizeRepositoryPath(
+  canonicalPath: NonNullable<RepositoryIdentityDeps['canonicalPath']>,
+  path: string,
+  label: string,
+): Promise<string> {
+  try {
+    return await canonicalPath(path);
+  } catch (cause) {
+    throw new RepositoryDiscoveryError(
+      'canonical-path',
+      `Could not resolve the ${label}: ${repositoryDiscoveryFailureMessage(cause)}`,
+      { cause },
+    );
+  }
+}
+
 export async function resolveGitRepositoryContext(
   cwd: string,
   deps: RepositoryIdentityDeps = {},
 ): Promise<GitRepositoryContext | null> {
   const runGit = deps.runGit ?? defaultRunGit;
   const canonicalPath = deps.canonicalPath ?? realpath;
-  const rootRaw = output(runGit(cwd, ['rev-parse', '--show-toplevel']));
-  if (!rootRaw || !isAbsolute(rootRaw)) return null;
-  const bare = output(runGit(cwd, ['rev-parse', '--is-bare-repository']));
+  const bareResult = runGitForDiscovery(runGit, cwd, ['rev-parse', '--is-bare-repository']);
+  if (bareResult.status !== 0) {
+    if (/not a git repository/i.test(bareResult.stderr ?? '')) return null;
+    throw gitQueryFailure('whether the repository is bare', bareResult);
+  }
+  const bare = output(bareResult);
   if (bare === 'true') throw new Error('BARE_REPOSITORY');
-  const commonRaw = output(runGit(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
-  if (!commonRaw || !isAbsolute(commonRaw)) return null;
-  const root = await canonicalPath(rootRaw);
-  const commonDir = await canonicalPath(commonRaw);
+  if (bare !== 'false') throw gitQueryFailure('whether the repository is bare', bareResult);
+
+  const rootResult = runGitForDiscovery(runGit, cwd, ['rev-parse', '--show-toplevel']);
+  const rootRaw = output(rootResult);
+  if (!rootRaw || !isAbsolute(rootRaw)) throw gitQueryFailure('the repository root', rootResult);
+
+  const commonResult = runGitForDiscovery(runGit, cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const commonRaw = output(commonResult);
+  if (!commonRaw || !isAbsolute(commonRaw)) throw gitQueryFailure('the Git common directory', commonResult);
+
+  const root = await canonicalizeRepositoryPath(canonicalPath, rootRaw, 'repository root path');
+  const commonDir = await canonicalizeRepositoryPath(canonicalPath, commonRaw, 'Git common directory path');
   const derivedName = normalizeCubeName(basename(root));
   if (!derivedName) return null;
 
-  const originRaw = output(runGit(root, ['config', '--get', 'remote.origin.url']));
+  const originResult = runGitForDiscovery(runGit, root, ['config', '--get', 'remote.origin.url']);
+  if (originResult.status !== 0 && (originResult.status !== 1 || originResult.stderr?.trim())) {
+    throw gitQueryFailure('the origin remote', originResult);
+  }
+  const originRaw = output(originResult);
   const canonical = originRaw ? canonicalizeWorkingRepoIdentity(originRaw) : null;
   return {
     root,
@@ -94,8 +187,8 @@ function emptyState(): RepositoryIdentityState {
   return { version: STORE_VERSION, localIdentities: {}, associations: {} };
 }
 
-function parseState(raw: string | null): RepositoryIdentityState {
-  if (raw === null) return emptyState();
+function parseState(raw: string | null): { state: RepositoryIdentityState; migrated: boolean } {
+  if (raw === null) return { state: emptyState(), migrated: false };
   const parsed = JSON.parse(raw) as Partial<RepositoryIdentityState>;
   if (
     parsed.version !== STORE_VERSION ||
@@ -109,7 +202,9 @@ function parseState(raw: string | null): RepositoryIdentityState {
       throw new Error('Borg repository identity store is malformed or unsupported');
     }
   }
-  for (const [key, value] of Object.entries(parsed.associations)) {
+  let migrated = false;
+  for (const [key, rawAssociation] of Object.entries(parsed.associations)) {
+    const value = rawAssociation as Omit<Partial<RepositoryAssociation>, 'template'> & { template?: unknown };
     if (
       !/^[a-f0-9]{64}$/.test(key) ||
       !value || typeof value !== 'object' || Array.isArray(value) ||
@@ -117,13 +212,22 @@ function parseState(raw: string | null): RepositoryIdentityState {
       typeof value.name !== 'string' || Buffer.byteLength(value.name, 'utf8') > 120 ||
       !DISPLAY_NAME_RE.test(value.name) ||
       typeof value.workingRepoName !== 'string' || Buffer.byteLength(value.workingRepoName, 'utf8') > 120 ||
-      !DISPLAY_NAME_RE.test(value.workingRepoName) ||
-      !CUBE_TEMPLATES.some((template) => template === value.template)
+      !DISPLAY_NAME_RE.test(value.workingRepoName)
     ) {
       throw new Error('Borg repository identity store is malformed or unsupported');
     }
+    // Tag 12 persisted the removed legacy seed. Dropping only this valid
+    // association makes the caller re-resolve authoritative state from tag 13.
+    if (value.template === 'default') {
+      delete parsed.associations[key];
+      migrated = true;
+      continue;
+    }
+    if (!CUBE_TEMPLATES.some((template) => template === value.template)) {
+      throw new Error('Borg repository identity store is malformed or unsupported');
+    }
   }
-  return parsed as RepositoryIdentityState;
+  return { state: parsed as RepositoryIdentityState, migrated };
 }
 
 function digest(secret: Buffer, purpose: string, value: string): string {
@@ -145,9 +249,10 @@ async function withIdentityState<T>(
       await atomicWrite0600(secretPath, `${secret.toString('hex')}\n`, options);
     }
     const statePath = join(root, STATE_FILE);
-    const state = parseState(await readStoreFile(statePath, options));
+    const parsed = parseState(await readStoreFile(statePath, options));
+    const state = parsed.state;
     const outcome = await operation(secret, state);
-    if (outcome.changed) {
+    if (parsed.migrated || outcome.changed) {
       await atomicWrite0600(statePath, `${JSON.stringify(state, null, 2)}\n`, options);
     }
     return outcome.result;

package/src/self-path.ts

@@ -9,7 +9,6 @@
  * under `dist/`. All bin targets are siblings in the same `dist/` directory.
  */
 
-import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 

package/src/server-handshake.ts

@@ -89,7 +89,6 @@ import type { EnrollmentArtifactBinding } from './enrollment-types.js';
 const HANDSHAKE_BODY_LIMIT = 64 * 1024;
 const HANDSHAKE_TIMEOUT_MS = 5_000;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const CLIENT_ATTACH_PATH = '/api/client/attach';
 export const DEFAULT_LOCAL_SERVER_ORIGIN = 'https://127.0.0.1:7091' as const;
 
 type FetchLike = typeof fetch;
@@ -215,7 +214,7 @@ export interface ServerAttachResult {
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v12.
+ * Attach an enrolled client principal to one granted cube/role over protocol v13.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * local 0600 credential store (keyed by the stable per-seat identity) BEFORE
  * this request, so an interrupted/lost response is recovered by re-sending the

package/src/tool-manifest.ts

@@ -452,8 +452,8 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_create-cube',
           description:
-            'Create a new cube bound to an explicit repository. The server homes ONE cube per repository: if the given repository already has a cube, this reports that existing cube and leaves its directive unchanged (it never overwrites it). The server seeds a default "Drone" role atomically so a newly-created cube is assimilatable immediately. ' +
-            'Pass an optional `template` name to apply a richer role set instead (see borg_list-templates / borg_apply-template).',
+            'Create a new cube bound to an explicit repository. The server homes ONE cube per repository: if the given repository already has a cube, this reports that existing cube and leaves its directive unchanged (it never overwrites it). The server seeds the selected named template atomically; `software-dev` is selected by default. ' +
+            'Pass an optional `template` name to select another role set (see borg_list-templates / borg_apply-template).',
           inputSchema: {
             type: 'object',
             properties: {
@@ -476,7 +476,7 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
               },
               template: {
                 type: 'string',
-                description: 'Optional template name to apply after cube creation (e.g. "software-dev"). Roles are merged by name; the default Drone role gets overwritten by the template if a same-named role is in the template. Only applied when a cube is newly created — never to an already-existing repository cube.',
+                description: 'Optional named template (default: "software-dev"). The server seeds its roles atomically when a cube is newly created; it is never applied to an already-existing repository cube.',
               },
             },
             required: ['name', 'cube_directive', 'repository'],

package/src/unknown-subcommand.ts

@@ -15,6 +15,7 @@
 export const KNOWN_SUBCOMMANDS = [
   'setup',
   'update',
+  'upgrade',
   'doctor',
   'clone',
   'quickstart',

package/src/update-cmd.ts

@@ -1370,7 +1370,7 @@ export async function runEarlyUpdate(
   argv: readonly string[],
   deps?: UpdateDeps,
 ): Promise<number | null> {
-  if (argv[2] !== 'update') return null;
+  if (argv[2] !== 'update' && argv[2] !== 'upgrade') return null;
   const parsed = parseUpdateArgs(argv.slice(3), process.env[REENTRY_ENV] === '1');
   const resolvedDeps = deps ?? buildDefaultUpdateDeps(parsed.ok ? parsed.registry : undefined);
   if (!parsed.ok) {

package/dist/postinstall-banner.d.ts

@@ -1,2 +0,0 @@
-export declare function composeInstallBanner(hasAgentCli: boolean): string;
-//# sourceMappingURL=postinstall-banner.d.ts.map

package/dist/postinstall-banner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"postinstall-banner.d.ts","sourceRoot":"","sources":["../src/postinstall-banner.ts"],"names":[],"mappings":"AAWA,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAyBjE"}

package/dist/postinstall-banner.js

@@ -1,27 +0,0 @@
-// Pure builder for the post-install banner text. Kept separate from
-// postinstall.ts (which is a side-effectful entry script that runs detection
-// + console output + process.exit on import) so the message content is unit-
-// testable without triggering those side effects.
-//
-// gh#653 B1: a non-expert who installs borgmcp WITHOUT an agent CLI (Claude
-// Code / Codex) present would otherwise be sent straight to "Next step: borg
-// setup", which dead-ends at "No supported agent CLI found". When no agent CLI
-// is detected, surface the install-an-agent-CLI step FIRST so the banner never
-// points the user into a wall.
-export function composeInstallBanner(hasAgentCli) {
-    const lines = [
-        '',
-        '╔════════════════════════════════════╗',
-        '║       ◼ Borg MCP Installed ◼       ║',
-        '╚════════════════════════════════════╝',
-        '',
-    ];
-    if (!hasAgentCli) {
-        lines.push('⚠ No agent CLI detected. Borg runs on top of Claude Code or Codex —', '  install one first:', '    Claude Code: https://claude.ai/download', '    Codex:       https://developers.openai.com/codex', '', 'Then run:', '  borg setup', '');
-    }
-    else {
-        lines.push('Next step:', '  borg setup', '');
-    }
-    return lines.join('\n');
-}
-//# sourceMappingURL=postinstall-banner.js.map

package/dist/postinstall-banner.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"postinstall-banner.js","sourceRoot":"","sources":["../src/postinstall-banner.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,6EAA6E;AAC7E,6EAA6E;AAC7E,kDAAkD;AAClD,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,+EAA+E;AAC/E,+EAA+E;AAC/E,+BAA+B;AAE/B,MAAM,UAAU,oBAAoB,CAAC,WAAoB;IACvD,MAAM,KAAK,GAAG;QACZ,EAAE;QACF,wCAAwC;QACxC,wCAAwC;QACxC,wCAAwC;QACxC,EAAE;KACH,CAAC;IAEF,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CACR,qEAAqE,EACrE,sBAAsB,EACtB,6CAA6C,EAC7C,sDAAsD,EACtD,EAAE,EACF,WAAW,EACX,cAAc,EACd,EAAE,CACH,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/postinstall.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-/**
- * Post-install script
- *
- * Detects local vs global installation and rejects local installs.
- * gh#653 B1: also detects whether an agent CLI (Claude Code / Codex) is present
- * and adjusts the "next step" banner so a user with no agent CLI is told to
- * install one FIRST rather than being sent into `borg setup`'s dead-end.
- */
-export {};
-//# sourceMappingURL=postinstall.d.ts.map

package/dist/postinstall.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"postinstall.d.ts","sourceRoot":"","sources":["../src/postinstall.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}

package/dist/postinstall.js

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-/**
- * Post-install script
- *
- * Detects local vs global installation and rejects local installs.
- * gh#653 B1: also detects whether an agent CLI (Claude Code / Codex) is present
- * and adjusts the "next step" banner so a user with no agent CLI is told to
- * install one FIRST rather than being sent into `borg setup`'s dead-end.
- */
-import { detectCliAvailability, installedCliNames } from './cli-platform.js';
-import { composeInstallBanner } from './postinstall-banner.js';
-// Check if this is a local install (npm_config_global is not set)
-const isGlobal = process.env.npm_config_global === 'true';
-if (!isGlobal) {
-    console.error('\n◼ Error: borg must be installed globally\n');
-    console.error('Please install with:');
-    console.error('  npm install -g borgmcp\n');
-    console.error('Local installation is not supported.\n');
-    process.exit(1);
-}
-// Global install — show instructions. Detect agent-CLI presence so the banner
-// never points a user with no Claude Code / Codex at `borg setup` (which would
-// dead-end). On any detection error, default to assuming an agent CLI is
-// present so we never emit a false "install an agent CLI" warning.
-let hasAgentCli = true;
-try {
-    hasAgentCli = installedCliNames(detectCliAvailability()).length > 0;
-}
-catch {
-    hasAgentCli = true;
-}
-console.log(composeInstallBanner(hasAgentCli));
-//# sourceMappingURL=postinstall.js.map

package/dist/postinstall.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"postinstall.js","sourceRoot":"","sources":["../src/postinstall.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,kEAAkE;AAClE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,MAAM,CAAC;AAE1D,IAAI,CAAC,QAAQ,EAAE,CAAC;IACd,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC9D,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACtC,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC5C,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,8EAA8E;AAC9E,+EAA+E;AAC/E,yEAAyE;AACzE,mEAAmE;AACnE,IAAI,WAAW,GAAG,IAAI,CAAC;AACvB,IAAI,CAAC;IACH,WAAW,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACtE,CAAC;AAAC,MAAM,CAAC;IACP,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -1,5 +0,0 @@
-/**
- * Type definitions for Borg MCP Client
- */
-export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC"}

package/dist/types.js

@@ -1,5 +0,0 @@
-/**
- * Type definitions for Borg MCP Client
- */
-export {};
-//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/src/postinstall-banner.ts

@@ -1,37 +0,0 @@
-// Pure builder for the post-install banner text. Kept separate from
-// postinstall.ts (which is a side-effectful entry script that runs detection
-// + console output + process.exit on import) so the message content is unit-
-// testable without triggering those side effects.
-//
-// gh#653 B1: a non-expert who installs borgmcp WITHOUT an agent CLI (Claude
-// Code / Codex) present would otherwise be sent straight to "Next step: borg
-// setup", which dead-ends at "No supported agent CLI found". When no agent CLI
-// is detected, surface the install-an-agent-CLI step FIRST so the banner never
-// points the user into a wall.
-
-export function composeInstallBanner(hasAgentCli: boolean): string {
-  const lines = [
-    '',
-    '╔════════════════════════════════════╗',
-    '║       ◼ Borg MCP Installed ◼       ║',
-    '╚════════════════════════════════════╝',
-    '',
-  ];
-
-  if (!hasAgentCli) {
-    lines.push(
-      '⚠ No agent CLI detected. Borg runs on top of Claude Code or Codex —',
-      '  install one first:',
-      '    Claude Code: https://claude.ai/download',
-      '    Codex:       https://developers.openai.com/codex',
-      '',
-      'Then run:',
-      '  borg setup',
-      '',
-    );
-  } else {
-    lines.push('Next step:', '  borg setup', '');
-  }
-
-  return lines.join('\n');
-}

package/src/postinstall.ts

@@ -1,36 +0,0 @@
-#!/usr/bin/env node
-/**
- * Post-install script
- *
- * Detects local vs global installation and rejects local installs.
- * gh#653 B1: also detects whether an agent CLI (Claude Code / Codex) is present
- * and adjusts the "next step" banner so a user with no agent CLI is told to
- * install one FIRST rather than being sent into `borg setup`'s dead-end.
- */
-
-import { detectCliAvailability, installedCliNames } from './cli-platform.js';
-import { composeInstallBanner } from './postinstall-banner.js';
-
-// Check if this is a local install (npm_config_global is not set)
-const isGlobal = process.env.npm_config_global === 'true';
-
-if (!isGlobal) {
-  console.error('\n◼ Error: borg must be installed globally\n');
-  console.error('Please install with:');
-  console.error('  npm install -g borgmcp\n');
-  console.error('Local installation is not supported.\n');
-  process.exit(1);
-}
-
-// Global install — show instructions. Detect agent-CLI presence so the banner
-// never points a user with no Claude Code / Codex at `borg setup` (which would
-// dead-end). On any detection error, default to assuming an agent CLI is
-// present so we never emit a false "install an agent CLI" warning.
-let hasAgentCli = true;
-try {
-  hasAgentCli = installedCliNames(detectCliAvailability()).length > 0;
-} catch {
-  hasAgentCli = true;
-}
-
-console.log(composeInstallBanner(hasAgentCli));

package/src/types.ts

@@ -1,5 +0,0 @@
-/**
- * Type definitions for Borg MCP Client
- */
-
-export {};