borgmcp 4.2.3 → 4.3.0

package/src/remote-client.ts

@@ -51,11 +51,15 @@ import {
   type EvictDroneResult,
   type ReassignDroneResult,
   type RoleRationaleResult,
+  decodeCreateCubeResponse,
   type PutDocumentResult,
   type GetDocumentResult,
   type ListDocumentsResult,
   type RemoveDocumentResult,
+  type CreateCubeRepository,
 } from 'borgmcp-shared/protocol';
+import { Buffer } from 'node:buffer';
+import { canonicalizeWorkingRepoIdentity } from './working-repo.js';
 import { consolePrefix } from './console-prefix.js';
 import { debugLog } from './debug.js';
 import { assertUuidShape } from './evict-drone.js';
@@ -1526,31 +1530,116 @@ export async function listCubes(connection?: RemoteConnection): Promise<{ cubes:
  * orchestrator pick a default role without a follow-up `getCube` call.
  * Existing callers that read `body.cube` keep working (forward-compat).
  */
+const REPOSITORY_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// The wire's working_repo_name rule (borgmcp-shared decodeWorkingRepositoryName,
+// which the package does not export): 1-120 UTF-8 bytes, must start with a
+// letter or digit, then letters/digits/spaces/dots/underscores/hyphens.
+const WORKING_REPO_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+
+function assertValidWorkingRepoName(name: string): string {
+  const bytes = Buffer.byteLength(name, 'utf8');
+  if (bytes < 1 || bytes > 120 || !WORKING_REPO_NAME_RE.test(name)) {
+    throw new Error(
+      'working_repo_name must start with a letter or digit and contain only letters, digits, spaces, dots, underscores, or hyphens (1-120 UTF-8 bytes).',
+    );
+  }
+  return name;
+}
+
+export interface NormalizedCreateCubeRepository {
+  repository: CreateCubeRepository;
+  workingRepoName: string;
+}
+
+/**
+ * client#499: normalize the EXPLICIT repository argument into the wire's
+ * `{ repository, working_repo_name }` pair — no cwd inference. A canonical git
+ * remote URL becomes an `origin` identity (reusing the shared canonicalizer,
+ * the same encoding the CLI create path uses); a UUID becomes a `local`
+ * identity (the server requires a UUID for local repositories). The optional
+ * working-repo display name defaults to the origin's repository segment.
+ */
+export function normalizeExplicitRepository(
+  repositoryArg: unknown,
+  workingRepoNameArg?: unknown,
+): NormalizedCreateCubeRepository {
+  if (typeof repositoryArg !== 'string' || repositoryArg.trim().length === 0) {
+    throw new Error(
+      'repository is required: pass a canonical git remote URL (e.g. https://github.com/owner/repo) or a UUID identifying a local repository.',
+    );
+  }
+  // client#499 CR: a PRESENT working_repo_name must be a string; reject a
+  // present non-string rather than silently coercing it to the derived name.
+  if (workingRepoNameArg !== undefined && workingRepoNameArg !== null && typeof workingRepoNameArg !== 'string') {
+    throw new Error('working_repo_name must be a string when provided.');
+  }
+  const repoInput = repositoryArg.trim();
+  const nameArg = typeof workingRepoNameArg === 'string' ? workingRepoNameArg.trim() : '';
+
+  const canonical = canonicalizeWorkingRepoIdentity(repoInput);
+  if (canonical?.origin && canonical.name) {
+    const derivedName = canonical.name.split('/').pop() || canonical.name;
+    // Validate the FINAL name (explicit or derived) against the wire rule
+    // before any network use, for both repository kinds — fail closed.
+    return {
+      repository: { kind: 'origin', value: canonical.origin },
+      workingRepoName: assertValidWorkingRepoName(nameArg || derivedName),
+    };
+  }
+  if (REPOSITORY_UUID_RE.test(repoInput)) {
+    if (!nameArg) {
+      throw new Error(
+        'working_repo_name is required when repository is a local UUID — there is no origin URL to derive a name from.',
+      );
+    }
+    return { repository: { kind: 'local', value: repoInput }, workingRepoName: assertValidWorkingRepoName(nameArg) };
+  }
+  throw new Error(
+    'repository must be a canonical git remote URL (e.g. https://github.com/owner/repo) or a UUID identifying a local repository.',
+  );
+}
+
 export async function createCube(
   name: string | undefined,
   cubeDirective: string,
-  opts?: { template?: string; message_taxonomy?: MessageTaxonomy | null },
+  opts?: {
+    template?: string;
+    message_taxonomy?: MessageTaxonomy | null;
+    // client#499: the explicit repository binding (no cwd inference). Required.
+    repository?: CreateCubeRepository;
+    workingRepoName?: string;
+  },
   connection?: RemoteConnection,
-): Promise<{ id: string; name: string; cube_directive?: string; roles: any[]; drones?: any[]; [k: string]: any }> {
+): Promise<{ result: 'created' | 'resolved'; cube: { id: string; name: string; cube_directive?: string; roles: any[]; drones?: any[]; [k: string]: any } }> {
   if (!name?.trim()) throw new Error('Local Borg server cube creation requires a cube name');
   if (opts?.template !== undefined && opts.template !== 'default') {
     throw new Error('Local Borg server supports only the default cube seed');
   }
+  if (!opts?.repository || !opts?.workingRepoName) {
+    throw new Error('Local Borg server cube creation requires an explicit repository identity');
+  }
   const resolved = await localOwnerConnection(connection);
-  const created = await localConnectionMutation<{
-    cube_id: string;
-    human_seat_role_id: string;
-    default_worker_role_id: string;
-  }>(resolved, '/api/cubes', 'POST', {
+  // client#499 CR: strictly decode the response against the shared
+  // CreateCubeResponse contract — `result` MUST be 'created' or 'resolved'. A
+  // missing/unknown result FAILS CLOSED (throws) rather than falling through to
+  // 'created' and PATCHing an existing cube's directive.
+  const created = decodeCreateCubeResponse(await localConnectionMutation<unknown>(resolved, '/api/cubes', 'POST', {
     retry_key: randomUUID(),
     name: name.trim(),
+    working_repo_name: opts.workingRepoName,
+    repository: opts.repository,
     template: 'default',
-  });
-  if (!created?.cube_id) throw new Error('Local Borg server returned an invalid cube creation response');
+  }));
+  // client#499: the server homes one cube per repository. A 'resolved' result
+  // means this repository already has a cube — report it honestly and DO NOT
+  // PATCH its directive over the existing settings (the round-1 stomp defect).
+  if (created.result === 'resolved') {
+    return { result: 'resolved', cube: await getCube(created.cube_id, resolved) };
+  }
   const patch: Record<string, unknown> = { cube_directive: cubeDirective };
   if (opts?.message_taxonomy !== undefined) patch.message_taxonomy = opts.message_taxonomy;
   await localConnectionMutation(resolved, `/api/cubes/${created.cube_id}`, 'PATCH', patch);
-  return getCube(created.cube_id, resolved);
+  return { result: 'created', cube: await getCube(created.cube_id, resolved) };
 }
 
 /**

package/src/tool-manifest.ts

@@ -452,7 +452,7 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_create-cube',
           description:
-            'Create a new cube. The server seeds a default "Drone" role atomically so the cube is assimilatable immediately. ' +
+            '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).',
           inputSchema: {
             type: 'object',
@@ -464,12 +464,22 @@ const BASE_TOOL_MANIFEST: ToolManifestEntry[] = [
                 maxLength: 120,
               },
               cube_directive: { type: 'string', description: 'Project-specific Markdown shown to every drone when it refreshes cube context.' },
+              repository: {
+                type: 'string',
+                description: 'The repository this cube binds to (explicit — not inferred from the working directory). Pass a canonical git remote URL (e.g. https://github.com/owner/repo) for a hosted repository, or a UUID identifying a local (no-remote) repository. The cube is homed to this repository; if it already has one, that existing cube is reported and its directive is left unchanged.',
+              },
+              working_repo_name: {
+                type: 'string',
+                description: 'Optional short display name for the repository (starts with a letter or digit; letters, digits, spaces, dots, underscores, or hyphens; max 120 bytes). Defaults to the repository segment of the URL; required when `repository` is a local UUID.',
+                pattern: '^[A-Za-z0-9][A-Za-z0-9 ._-]*$',
+                maxLength: 120,
+              },
               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.',
+                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.',
               },
             },
-            required: ['name', 'cube_directive'],
+            required: ['name', 'cube_directive', 'repository'],
           },
         },
         {
@@ -1063,11 +1073,14 @@ export const TOOL_OUTPUT_SCHEMAS: Record<string, OutputSchema> = {
     type: 'object',
     properties: {
       cube: CUBE_OUTPUT,
+      // client#499: 'created' = a new cube; 'resolved' = the repository already
+      // had a cube (reported, directive left unchanged).
+      result: { type: 'string', enum: ['created', 'resolved'] },
       template: { type: ['string', 'null'] },
       roles_created: { type: ['number', 'null'] },
       roles_updated: { type: ['number', 'null'] },
     },
-    required: ['cube', 'template'],
+    required: ['cube', 'result', 'template'],
   },
   'borg_update-cube': {
     type: 'object',