@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/api-project-identity.ts

@@ -0,0 +1,74 @@
+/**
+ * `/__editor/compatibility` — WHICH Node process is serving this editor, and
+ * whether its source is still the source it started with.
+ *
+ * Every other call in `api/` assumes the answer is stable for the page's
+ * lifetime; `requireEditorCompatibility` is what turns "the server moved
+ * underneath us" into a loud error instead of a confusing one later.
+ */
+
+import {
+  assertEditorCompatibility,
+  type EditorServerCompatibility,
+  editorServerUnavailableError,
+  missingCompatibilityError,
+} from '@volter/sdk/session/editor-compatibility';
+import { assertEditorServerResponse } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+
+function parseEditorCompatibility(value: unknown): EditorServerCompatibility | null {
+  if (!value || typeof value !== 'object') return null;
+  const candidate = value as Partial<EditorServerCompatibility>;
+  if (
+    candidate.apiVersion !== 1 ||
+    (typeof candidate.engineVersion !== 'string' && candidate.engineVersion !== null) ||
+    typeof candidate.manifestVersion !== 'number' ||
+    typeof candidate.startedAt !== 'string' ||
+    !candidate.source ||
+    (candidate.source.state !== 'current' && candidate.source.state !== 'restart-required')
+  ) {
+    return null;
+  }
+  if (
+    candidate.source.state === 'restart-required' &&
+    (typeof candidate.source.changedPath !== 'string' ||
+      typeof candidate.source.changedAt !== 'string')
+  ) {
+    return null;
+  }
+  return candidate as EditorServerCompatibility;
+}
+
+/** Read the immutable identity of the local Node process serving this editor. */
+export async function getEditorCompatibility(): Promise<EditorServerCompatibility | null> {
+  let res: Response;
+  try {
+    res = await fetch(`${BASE}/compatibility`, { cache: 'no-store' });
+  } catch (error) {
+    throw editorServerUnavailableError(error instanceof Error ? error.message : String(error));
+  }
+  if (res.status >= 500) throw editorServerUnavailableError(`HTTP ${res.status}`);
+  try {
+    // This route's own copy of the page-fallback discrimination predates
+    // `editor-server-response.ts`; the reader now owns it. `null` (not a throw)
+    // stays the answer for "no editor server here" — that is the whole question
+    // this probe exists to ask, and `requireEditorCompatibility` turns it into
+    // the named `missingCompatibilityError()`.
+    assertEditorServerResponse(res, `GET ${BASE}/compatibility`);
+  } catch {
+    return null;
+  }
+  try {
+    return parseEditorCompatibility(await res.json());
+  } catch {
+    return null;
+  }
+}
+
+/** Require a current handshake before any operation that activates a project. */
+export async function requireEditorCompatibility(): Promise<EditorServerCompatibility> {
+  const identity = await getEditorCompatibility();
+  if (!identity) throw missingCompatibilityError();
+  assertEditorCompatibility(identity);
+  return identity;
+}

package/src/kit/api-settings.ts

@@ -0,0 +1,36 @@
+/**
+ * The two shared settings layers over the wire (`server/routes/settings.ts`):
+ * `~/.volter/settings.json` (user) and `<project>/.volter/settings.json`
+ * (project), both files the editor server owns.
+ */
+import type { EditorSettings } from '@volter/project/settings/schema';
+import { assertEditorServerResponse, editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+
+export type SettingsLayer = 'user' | 'project';
+
+export interface SettingsLayerRead {
+  readonly settings: EditorSettings;
+  /** Problems with the stored document, spelled for the person who owns it. */
+  readonly issues: readonly string[];
+  /** Where the layer lives, for the issue report. */
+  readonly path: string | null;
+}
+
+export async function loadSettingsLayer(layer: SettingsLayer): Promise<SettingsLayerRead> {
+  const res = await fetch(`${BASE}/settings/${layer}`);
+  return editorServerJson<SettingsLayerRead>(res, `Could not read ${layer} settings`);
+}
+
+export async function saveSettingsLayer(
+  layer: SettingsLayer,
+  settings: EditorSettings,
+): Promise<void> {
+  const body = JSON.stringify(settings, null, 2);
+  const res = await fetch(`${BASE}/settings/${layer}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+  assertEditorServerResponse(res, `Could not save ${layer} settings`);
+}

package/src/kit/api-worktrees.ts

@@ -0,0 +1,205 @@
+/**
+ * The worktree board: which checkouts this repository has, which of them an
+ * editor is serving, and the create / open / delegate / archive / stop verbs.
+ */
+
+import { assertEditorServerAnswered } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+export interface EditorRepositoryParticipant {
+  participantId: string;
+  displayName: string;
+  kind: 'human' | 'agent';
+  color: string;
+  status: 'active' | 'idle' | 'needs-input' | 'done';
+  lastSeenAt: string;
+  agent: { harness: string; conversationId: string } | null;
+  changeCount: number;
+}
+
+export interface EditorRepositoryPresenceSession {
+  sessionId: string;
+  worktreeId: string;
+  branch: string | null;
+  updatedAt: string;
+  participants: Array<
+    Omit<EditorRepositoryParticipant, 'agent'> & { agent: { harness: string } | null }
+  >;
+}
+
+export interface EditorRepositoryPresence {
+  currentWorktreeId: string | null;
+  sessions: EditorRepositoryPresenceSession[];
+}
+
+/** Browser-safe repository directory. Unlike worktree management, this is
+ * available through a shared session and contains no host filesystem data. */
+export async function getEditorRepositoryPresence(): Promise<EditorRepositoryPresence> {
+  const response = await fetch(`${BASE}/repository-presence`, { cache: 'no-store' });
+  // An empty presence is a MEASUREMENT ("nobody else is here"), so it may only
+  // be returned when the editor server said so — never when a page fallback did.
+  assertEditorServerAnswered(response, 'Could not read repository presence');
+  if (!response.ok) return { currentWorktreeId: null, sessions: [] };
+  const payload = (await response
+    .json()
+    .catch(() => null)) as Partial<EditorRepositoryPresence> | null;
+  return {
+    currentWorktreeId:
+      typeof payload?.currentWorktreeId === 'string' ? payload.currentWorktreeId : null,
+    sessions: Array.isArray(payload?.sessions) ? payload.sessions : [],
+  };
+}
+
+export interface EditorWorktreeSession {
+  sessionId: string | null;
+  port: number;
+  pid: number | null;
+  presence?: {
+    updatedAt: string;
+    participants: EditorRepositoryParticipant[];
+  };
+}
+
+export interface EditorWorktree {
+  root: string;
+  branch: string | null;
+  headCommit: string | null;
+  worktreeId: string;
+  current: boolean;
+  project: string | null;
+  dirty: boolean;
+  ahead: number | null;
+  behind: number | null;
+  locked: string | null;
+  prunable: string | null;
+  sessions: EditorWorktreeSession[];
+}
+
+export interface EditorBranch {
+  name: string;
+  headCommit: string;
+  updatedAt: number;
+  worktreeId: string | null;
+  current: boolean;
+}
+
+export interface EditorWorktreeState {
+  worktrees: EditorWorktree[];
+  branches: EditorBranch[];
+}
+
+export interface EditorSessionWorktreeIdentity {
+  branch: string | null;
+  worktreeId: string | null;
+}
+
+/** The cheap, already-owned session identity used by persistent header chrome.
+ * Repository-wide worktree inspection is intentionally a separate, on-demand
+ * operation: asking Git for every checkout's status can take seconds in a
+ * repository with many agent worktrees and must never sit on viewport boot. */
+export async function getEditorSessionWorktreeIdentity(): Promise<EditorSessionWorktreeIdentity> {
+  const response = await fetch(`${BASE}/project`, { cache: 'no-store' });
+  assertEditorServerAnswered(response, 'Could not read this session’s worktree identity');
+  if (!response.ok) return { branch: null, worktreeId: null };
+  const payload = (await response.json().catch(() => null)) as {
+    session?: { branch?: unknown; worktreeId?: unknown };
+  } | null;
+  return {
+    branch: typeof payload?.session?.branch === 'string' ? payload.session.branch : null,
+    worktreeId:
+      typeof payload?.session?.worktreeId === 'string' ? payload.session.worktreeId : null,
+  };
+}
+
+async function worktreeRequest(path: string, init?: RequestInit): Promise<Record<string, unknown>> {
+  const response = await fetch(`${BASE}/worktrees${path}`, init);
+  // Every verb below reports by returning, and `.json().catch(() => null)`
+  // turned a page fallback into `{}` — an archive/stop/delegate that touched
+  // nothing, answered with an empty worktree board.
+  assertEditorServerAnswered(response, `Worktree operation ${path || '(list)'} failed`);
+  const payload = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+  if (!response.ok) {
+    throw new Error(
+      typeof payload?.['error'] === 'string'
+        ? payload['error']
+        : `Worktree operation failed (${response.status}).`,
+    );
+  }
+  return payload ?? {};
+}
+
+function parseEditorWorktreeState(payload: Record<string, unknown>): EditorWorktreeState {
+  return {
+    worktrees: Array.isArray(payload['worktrees'])
+      ? (payload['worktrees'] as EditorWorktree[])
+      : [],
+    branches: Array.isArray(payload['branches']) ? (payload['branches'] as EditorBranch[]) : [],
+  };
+}
+
+/** The harnesses supercode reports able to start a delegated task here. */
+export async function listDelegateHarnesses(): Promise<Array<{ id: string; label: string }>> {
+  const payload = await worktreeRequest('/harnesses');
+  return Array.isArray(payload['harnesses'])
+    ? (payload['harnesses'] as Array<{ id: string; label: string }>)
+    : [];
+}
+
+export async function listEditorWorktrees(): Promise<EditorWorktreeState> {
+  const payload = await worktreeRequest('');
+  return parseEditorWorktreeState(payload);
+}
+
+export async function openEditorWorktree(
+  worktreeId: string,
+): Promise<{ url: string; status: string }> {
+  return (await worktreeRequest('/open', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ worktreeId }),
+  })) as { url: string; status: string };
+}
+
+export async function createEditorWorktree(
+  branch: string,
+  from = 'HEAD',
+): Promise<{ url: string; status: string }> {
+  return (await worktreeRequest('/create', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ branch, from }),
+  })) as { url: string; status: string };
+}
+
+export async function delegateEditorTask(input: {
+  task: string;
+  harness: string;
+  isolation: 'worktree' | 'current';
+  branch?: string;
+  from?: string;
+}): Promise<Record<string, unknown>> {
+  return worktreeRequest('/delegate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+}
+
+export async function archiveEditorWorktree(worktreeId: string): Promise<EditorWorktree[]> {
+  const payload = await worktreeRequest('/archive', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ worktreeId }),
+  });
+  return parseEditorWorktreeState(payload).worktrees;
+}
+
+export async function stopEditorWorktreeSession(
+  worktreeId: string,
+  sessionId: string,
+): Promise<void> {
+  await worktreeRequest('/stop', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ worktreeId, sessionId }),
+  });
+}

package/src/kit/asset-capabilities.ts

@@ -0,0 +1,344 @@
+export type AssetFormat =
+  | 'glb'
+  | 'gltf'
+  | 'fbx'
+  | 'obj'
+  | 'dae'
+  | 'stl'
+  | 'ply'
+  | 'spz'
+  | '3ds'
+  | 'bvh'
+  | 'blend'
+  | 'usd'
+  | 'usda'
+  | 'usdc'
+  | 'png'
+  | 'jpg'
+  | 'jpeg'
+  | 'webp'
+  | 'gif'
+  | 'svg'
+  | 'hdr'
+  | 'exr'
+  | 'mp4'
+  | 'webm'
+  | 'mp3'
+  | 'ogg'
+  | 'wav'
+  | 'flac'
+  | 'cube'
+  | 'glsl'
+  | 'vert'
+  | 'frag'
+  | 'ts'
+  | 'tsx'
+  | 'js'
+  | 'jsx'
+  | 'css'
+  | 'html'
+  | 'md'
+  | 'txt'
+  | 'mtl'
+  | 'csv'
+  | 'xml'
+  | 'yaml'
+  | 'yml'
+  | 'inputmap.json'
+  | 'data.json'
+  | 'json'
+  | 'unknown';
+
+export type AssetImportStrategy =
+  | 'copy-runtime'
+  | 'convert-model'
+  | 'animation-source'
+  | 'copy-project'
+  | 'unsupported';
+
+export type AssetCapabilityKind =
+  | 'model'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'json'
+  | 'prefab'
+  | 'source'
+  | 'unknown';
+
+export interface AssetCapabilities {
+  readonly format: AssetFormat;
+  readonly kind: AssetCapabilityKind;
+  readonly previewable: boolean;
+  readonly importable: boolean;
+  readonly runtimeReady: boolean;
+  readonly placeable: boolean;
+  readonly animated: boolean;
+  readonly importStrategy: AssetImportStrategy;
+  readonly editor:
+    | 'model'
+    | 'image'
+    | 'environment'
+    | 'video'
+    | 'audio'
+    | 'data'
+    | 'source'
+    | 'none';
+}
+
+const MODEL_PREVIEW_FORMATS = ['glb', 'gltf', 'fbx', 'obj', 'dae', 'stl', 'ply', '3ds'] as const;
+const SOURCE_MODEL_FORMATS = ['blend', 'usd', 'usda', 'usdc'] as const;
+const IMAGE_FORMATS = ['png', 'jpg', 'jpeg', 'webp', 'gif', 'svg'] as const;
+const HIGH_DYNAMIC_RANGE_FORMATS = ['hdr', 'exr'] as const;
+const AUDIO_FORMATS = ['mp3', 'ogg', 'wav', 'flac'] as const;
+/** Clip formats a browser plays natively. Reference material (a generated
+ *  motion study, a captured plate) is the common case, and a video is NOT a
+ *  runtime-ready game asset: nothing in a scene places one, so `placeable`
+ *  and `runtimeReady` stay false and the row's whole job is to be seen. */
+const VIDEO_FORMATS = ['mp4', 'webm'] as const;
+const COLOR_GRADE_FORMATS = ['cube'] as const;
+const SHADER_SOURCE_FORMATS = ['glsl', 'vert', 'frag'] as const;
+const TEXT_SOURCE_FORMATS = [
+  'txt',
+  'md',
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'css',
+  'html',
+  'mtl',
+  'csv',
+  'xml',
+  'yaml',
+  'yml',
+] as const;
+
+function row(
+  format: AssetFormat,
+  values: Omit<AssetCapabilities, 'format'>,
+): readonly [AssetFormat, AssetCapabilities] {
+  return [format, { format, ...values }];
+}
+
+const MODEL_SOURCE_BASE = {
+  kind: 'source',
+  previewable: true,
+  importable: true,
+  runtimeReady: false,
+  placeable: false,
+  animated: false,
+  importStrategy: 'convert-model',
+  editor: 'model',
+} as const;
+
+export const ASSET_CAPABILITY_REGISTRY: ReadonlyMap<AssetFormat, AssetCapabilities> = new Map([
+  ...MODEL_PREVIEW_FORMATS.map((format) =>
+    row(format, {
+      ...MODEL_SOURCE_BASE,
+      kind: format === 'glb' || format === 'gltf' ? 'model' : 'source',
+      runtimeReady: format === 'glb' || format === 'gltf',
+      placeable: format === 'glb' || format === 'gltf',
+      importStrategy: format === 'glb' || format === 'gltf' ? 'copy-runtime' : 'convert-model',
+    }),
+  ),
+  row('spz', {
+    kind: 'model',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: true,
+    animated: false,
+    importStrategy: 'copy-runtime',
+    editor: 'model',
+  }),
+  row('bvh', {
+    kind: 'source',
+    previewable: true,
+    importable: true,
+    runtimeReady: false,
+    placeable: false,
+    animated: true,
+    importStrategy: 'animation-source',
+    editor: 'model',
+  }),
+  ...SOURCE_MODEL_FORMATS.map((format) =>
+    row(format, { ...MODEL_SOURCE_BASE, previewable: false, editor: 'source' }),
+  ),
+  ...IMAGE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'image',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: format === 'gif',
+      importStrategy: 'copy-project',
+      editor: 'image',
+    }),
+  ),
+  ...HIGH_DYNAMIC_RANGE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'image',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'environment',
+    }),
+  ),
+  ...AUDIO_FORMATS.map((format) =>
+    row(format, {
+      kind: 'audio',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'audio',
+    }),
+  ),
+  ...VIDEO_FORMATS.map((format) =>
+    row(format, {
+      kind: 'video',
+      previewable: true,
+      importable: true,
+      runtimeReady: false,
+      placeable: false,
+      animated: true,
+      importStrategy: 'copy-project',
+      editor: 'video',
+    }),
+  ),
+  ...COLOR_GRADE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'source',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'source',
+    }),
+  ),
+  ...SHADER_SOURCE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'source',
+      previewable: true,
+      importable: true,
+      runtimeReady: true,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'source',
+    }),
+  ),
+  ...TEXT_SOURCE_FORMATS.map((format) =>
+    row(format, {
+      kind: 'source',
+      previewable: true,
+      importable: true,
+      runtimeReady: false,
+      placeable: false,
+      animated: false,
+      importStrategy: 'copy-project',
+      editor: 'source',
+    }),
+  ),
+  row('inputmap.json', {
+    kind: 'json',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'data',
+  }),
+  row('data.json', {
+    kind: 'json',
+    previewable: true,
+    importable: true,
+    runtimeReady: true,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'data',
+  }),
+  row('json', {
+    kind: 'json',
+    previewable: true,
+    importable: true,
+    runtimeReady: false,
+    placeable: false,
+    animated: false,
+    importStrategy: 'copy-project',
+    editor: 'data',
+  }),
+]);
+
+const UNKNOWN_CAPABILITIES: AssetCapabilities = {
+  format: 'unknown',
+  kind: 'unknown',
+  previewable: false,
+  importable: false,
+  runtimeReady: false,
+  placeable: false,
+  animated: false,
+  importStrategy: 'unsupported',
+  editor: 'none',
+};
+
+export function assetFormatFromPath(path: string): AssetFormat {
+  const clean = path.split(/[?#]/, 1)[0]!.toLowerCase();
+  for (const compound of ['inputmap.json', 'data.json'] as const) {
+    if (clean.endsWith(`.${compound}`)) return compound;
+  }
+  const dot = clean.lastIndexOf('.');
+  const extension = dot >= 0 ? clean.slice(dot + 1) : '';
+  return ASSET_CAPABILITY_REGISTRY.has(extension as AssetFormat)
+    ? (extension as AssetFormat)
+    : extension === 'json'
+      ? 'json'
+      : 'unknown';
+}
+
+export function assetCapabilities(pathOrFormat: string): AssetCapabilities {
+  const direct = ASSET_CAPABILITY_REGISTRY.get(pathOrFormat.toLowerCase() as AssetFormat);
+  if (direct) return direct;
+  return ASSET_CAPABILITY_REGISTRY.get(assetFormatFromPath(pathOrFormat)) ?? UNKNOWN_CAPABILITIES;
+}
+
+export function supportedAssetFormats(): readonly AssetFormat[] {
+  return [...ASSET_CAPABILITY_REGISTRY.keys()];
+}
+
+/** Editor document kind for a capability row; null means no honest editor exists. */
+export function assetDocumentKind(
+  capability: AssetCapabilities,
+): 'model' | 'image' | 'video' | 'audio' | 'json' | 'source' | null {
+  switch (capability.editor) {
+    case 'model':
+      return 'model';
+    case 'image':
+      return 'image';
+    case 'environment':
+      // Workspace persistence needs only the broad asset kind. The path and
+      // capability registry recover the native HDR/EXR viewer on restore.
+      return 'image';
+    case 'video':
+      return 'video';
+    case 'audio':
+      return 'audio';
+    case 'data':
+      return 'json';
+    case 'source':
+      return 'source';
+    default:
+      return null;
+  }
+}