borgmcp-shared 0.6.2 → 0.6.3

package/src/protocol/contract.ts

@@ -1,6 +1,7 @@
 import { ErrorCode } from './errors.js';
 import { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
 import {
+  canonicalizeRepositoryIdentity,
   RuntimeMetadataValidationError,
   validateRuntimeMetadata,
   validateRuntimeMetadataPatch,
@@ -12,7 +13,7 @@ import type {
 } from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.6.2' as const;
+export const SHARED_PACKAGE_VERSION = '0.6.3' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
@@ -120,17 +121,28 @@ export type EnrollmentExchangeResponse =
   | ClientEnrollmentExchangeResponse
   | OwnerEnrollmentExchangeResponse;
 
-export const CUBE_TEMPLATES = ['default'] as const;
+export const CUBE_TEMPLATES = ['default', 'software-dev', 'starter'] as const;
 export type CubeTemplate = (typeof CUBE_TEMPLATES)[number];
 
+export type CreateCubeRepository =
+  | { kind: 'origin'; value: string }
+  | { kind: 'local'; value: string };
+
 export interface CreateCubeRequest {
   retry_key: string;
   name: string;
+  working_repo_name: string;
+  repository: CreateCubeRepository;
   template: CubeTemplate;
 }
 
 export interface CreateCubeResponse {
+  result: 'created' | 'resolved';
   cube_id: string;
+  name: string;
+  working_repo_name: string;
+  repository: CreateCubeRepository;
+  template: CubeTemplate;
   human_seat_role_id: string;
   default_worker_role_id: string;
   access: 'manage';
@@ -434,17 +446,27 @@ function decodeExactServerCapabilities(
 
 export function decodeCreateCubeRequest(value: unknown): CreateCubeRequest {
   const input = record(value);
-  exactKeys(input, ['retry_key', 'name', 'template'], ['retry_key', 'name', 'template']);
+  exactKeys(
+    input,
+    ['retry_key', 'name', 'working_repo_name', 'repository', 'template'],
+    ['retry_key', 'name', 'working_repo_name', 'repository', 'template'],
+  );
   const name = boundedString(input.name, 1, 120, ['name']);
   if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
     fail('Cube name contains unsupported characters.', ['name']);
   }
+  const workingRepoName = boundedString(input.working_repo_name, 1, 120, ['working_repo_name']);
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(workingRepoName)) {
+    fail('Cube name contains unsupported characters.', ['working_repo_name']);
+  }
   if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
     fail('Unsupported cube template.', ['template']);
   }
   return {
     retry_key: decodeUuid(input.retry_key, ['retry_key']),
     name,
+    working_repo_name: workingRepoName,
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
     template: input.template as CubeTemplate,
   };
 }
@@ -457,18 +479,82 @@ export function decodeCreateCubeResponse(value: unknown): CreateCubeResponse {
   const input = record(value);
   exactKeys(
     input,
-    ['cube_id', 'human_seat_role_id', 'default_worker_role_id', 'access'],
-    ['cube_id', 'human_seat_role_id', 'default_worker_role_id', 'access'],
+    [
+      'result',
+      'cube_id',
+      'name',
+      'working_repo_name',
+      'repository',
+      'template',
+      'human_seat_role_id',
+      'default_worker_role_id',
+      'access',
+    ],
+    [
+      'result',
+      'cube_id',
+      'name',
+      'working_repo_name',
+      'repository',
+      'template',
+      'human_seat_role_id',
+      'default_worker_role_id',
+      'access',
+    ],
   );
+  if (input.result !== 'created' && input.result !== 'resolved') {
+    fail('Invalid cube creation result.', ['result']);
+  }
+  const name = boundedString(input.name, 1, 120, ['name']);
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name)) {
+    fail('Cube name contains unsupported characters.', ['name']);
+  }
+  const workingRepoName = boundedString(input.working_repo_name, 1, 120, ['working_repo_name']);
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(workingRepoName)) {
+    fail('Cube name contains unsupported characters.', ['working_repo_name']);
+  }
+  if (!CUBE_TEMPLATES.includes(input.template as CubeTemplate)) {
+    fail('Unsupported cube template.', ['template']);
+  }
   if (input.access !== 'manage') fail('Created cube access must be manage.', ['access']);
   return {
+    result: input.result,
     cube_id: decodeUuid(input.cube_id, ['cube_id']),
+    name,
+    working_repo_name: workingRepoName,
+    repository: decodeCreateCubeRepository(input.repository, ['repository']),
+    template: input.template as CubeTemplate,
     human_seat_role_id: decodeUuid(input.human_seat_role_id, ['human_seat_role_id']),
     default_worker_role_id: decodeUuid(input.default_worker_role_id, ['default_worker_role_id']),
     access: 'manage',
   };
 }
 
+function decodeCreateCubeRepository(
+  value: unknown,
+  path: readonly (string | number)[],
+): CreateCubeRepository {
+  const input = record(value, path);
+  exactKeys(input, ['kind', 'value'], ['kind', 'value'], path);
+  if (input.kind === 'local') {
+    return { kind: 'local', value: decodeUuid(input.value, [...path, 'value']) };
+  }
+  if (input.kind !== 'origin') fail('Unsupported repository identity kind.', [...path, 'kind']);
+  const origin = boundedString(input.value, 1, 512, [...path, 'value']);
+  try {
+    if (canonicalizeRepositoryIdentity(origin).working_repo_origin !== origin) {
+      fail('Repository origin must be canonical.', [...path, 'value']);
+    }
+  } catch (error) {
+    if (error instanceof ProtocolContractError) throw error;
+    if (error instanceof RuntimeMetadataValidationError) {
+      fail('Repository origin must be canonical.', [...path, 'value']);
+    }
+    throw error;
+  }
+  return { kind: 'origin', value: origin };
+}
+
 export function decodeCreateCubeResponseEnvelope(value: unknown): ProtocolEnvelope<CreateCubeResponse> {
   return decodeProtocolEnvelope(value, decodeCreateCubeResponse);
 }
@@ -698,7 +784,7 @@ export function decodeUpdateDroneRuntimeMetadataResponseEnvelope(
   return decodeProtocolEnvelope(value, decodeUpdateDroneRuntimeMetadataResponse);
 }
 
-// ── v3 clean-slate wire types ──────────────────────────────────────────────
+// ── Clean-slate attach wire types (introduced in v3) ──────────────────────
 
 export interface AttachRequest {
   cube_id: string;
@@ -800,7 +886,7 @@ function decodeAttachSession(value: unknown, path: readonly (string | number)[])
 }
 
 /**
- * Decode a v3 attach request. Strict: exact keys, bounded sizes,
+ * Decode an attach request. Strict: exact keys, bounded sizes,
  * session_credential is token-safe and never echoed in errors.
  */
 export function decodeAttachRequest(value: unknown): AttachRequest {
@@ -825,7 +911,7 @@ export function decodeAttachRequest(value: unknown): AttachRequest {
 }
 
 /**
- * Create a v3 attach request envelope. Stamps the canonical protocol version.
+ * Create an attach request envelope. Stamps the canonical protocol version.
  */
 export function createAttachRequestEnvelope(
   requestId: string,
@@ -839,7 +925,7 @@ export function createAttachRequestEnvelope(
 }
 
 /**
- * Decode a v3 attach request envelope. Verifies protocol_version === PROTOCOL_VERSION
+ * Decode an attach request envelope. Verifies protocol_version === PROTOCOL_VERSION
  * BEFORE decoding the payload — a wrong tag never invokes the payload decoder
  * and never exposes or returns the supplied session_credential.
  * Uses a static token-safe diagnostic; does not interpolate attacker-controlled text.
@@ -869,7 +955,7 @@ export function decodeAttachRequestEnvelope(
 }
 
 /**
- * Decode a v3 attach response. Strict: exact keys and result discriminant.
+ * Decode an attach response. Strict: exact keys and result discriminant.
  */
 export function decodeAttachResponse(value: unknown): AttachResponse {
   const input = record(value);
@@ -893,7 +979,7 @@ export function decodeAttachResponse(value: unknown): AttachResponse {
 }
 
 /**
- * Decode a v3 attach response wrapped in a ProtocolEnvelope.
+ * Decode an attach response wrapped in a ProtocolEnvelope.
  * Verifies protocol_version === PROTOCOL_VERSION before decoding payload.
  */
 export function decodeAttachResponseEnvelope(value: unknown): ProtocolEnvelope<AttachResponse> {

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v3. */
-export const PROTOCOL_VERSION = '3' as const;
+/** Current Borg coordination protocol generation. Clean-slate v4. */
+export const PROTOCOL_VERSION = '4' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/templates.ts

@@ -30,12 +30,29 @@ export type MessageTaxonomy = MessageTaxonomyClass[];
 
 export interface Template {
   name: string;
+  label: string;
+  short_description: string;
   description: string;
   roles: TemplateRole[];
   cube_directive?: string;
   message_taxonomy?: MessageTaxonomy;
 }
 
+export const LEGACY_DEFAULT_TEMPLATE_LABEL = 'Default (legacy)';
+
+export const NEW_CUBE_TEMPLATE_PRESENTATIONS = [
+  {
+    name: 'software-dev',
+    label: 'Software Development',
+    short_description: 'Recommended for code repositories.',
+  },
+  {
+    name: 'starter',
+    label: 'Starter',
+    short_description: 'Minimal roles for general projects.',
+  },
+] as const;
+
 export const ESCALATION_DISCIPLINE = `
 
 Escalation:
@@ -318,7 +335,7 @@ const SECURITY_AUDITOR = `Perform only the routed security review of an exact so
 - Do not implement fixes, merge, deploy, publish, tag, or release.${SERIALIZED_REVIEW_ROUNDS_DISCIPLINE}${ESCALATION_DISCIPLINE}`;
 
 const SOFTWARE_DEV: Template = {
-  name: 'software-dev',
+  ...NEW_CUBE_TEMPLATE_PRESENTATIONS[0],
   description: 'Scope-first multi-agent software development with one human Coordinator, implementation, and proportionate review roles.',
   cube_directive: SOFTWARE_DEV_DIRECTIVE,
   message_taxonomy: SOFTWARE_DEV_TAXONOMY,
@@ -432,7 +449,7 @@ const STARTER_TAXONOMY: MessageTaxonomy = [
 ];
 
 const STARTER: Template = {
-  name: 'starter',
+  ...NEW_CUBE_TEMPLATE_PRESENTATIONS[1],
   description: 'Minimal scope-first template for general projects: a human Coordinator, a Worker, and a Reviewer.',
   cube_directive: `## Scope and coordination
 
@@ -487,8 +504,8 @@ const STARTER: Template = {
 };
 
 export const TEMPLATES: Record<string, Template> = {
-  starter: STARTER,
   'software-dev': SOFTWARE_DEV,
+  starter: STARTER,
 };
 
 export function getTemplate(name: string): Template | null {