@mycadet/assistant 0.12.11 → 0.13.0

package/src/runtime/migrations/migration-transport.ts

@@ -1,612 +0,0 @@
-/**
- * Shared transport methods for managed and runtime migration APIs.
- *
- * Provides typed functions for each migration endpoint, usable by
- * client web views (macOS/iOS WKWebView), the gateway, or any
- * TypeScript consumer that needs to call migration APIs.
- *
- * Two target APIs:
- *
- *   Runtime (local daemon):
- *     POST /v1/migrations/validate
- *     POST /v1/migrations/export
- *     POST /v1/migrations/import-preflight
- *     POST /v1/migrations/import
- *
- *   Managed (platform/Django):
- *     POST /v1/migrations/validate/
- *     POST /v1/migrations/export/
- *     POST /v1/migrations/import-preflight/
- *     POST /v1/migrations/import/
- *     GET  /v1/migrations/export/{job_id}/status/
- *     GET  /v1/migrations/import/{job_id}/status/
- *
- * All methods accept a `fetchFn` parameter for testability (defaults to
- * the global `fetch`). Auth headers are passed via `TransportConfig`.
- */
-
-import { z } from "zod";
-
-export type MigrationTarget = "runtime" | "managed";
-
-export interface TransportConfig {
-  /** Base URL of the target API (e.g. "https://cloud.mycadet.ai"). */
-  baseURL: string;
-  /** Which API surface to target. Managed endpoints use trailing slashes. */
-  target: MigrationTarget;
-  /** Authorization header value (e.g. "Bearer <jwt>" or session token). */
-  authHeader?: string;
-  /** Header name for auth. Defaults to "Authorization" for runtime, "X-Session-Token" for managed. */
-  authHeaderName?: string;
-  /**
-   * Additional headers to include with every request.
-   * Merged after Content-Type but before auth-header injection,
-   * so an explicit auth header from the transport always wins
-   * over a same-named entry in defaultHeaders.
-   */
-  defaultHeaders?: Record<string, string>;
-  /** Custom fetch implementation for testing or environments without global fetch. */
-  fetchFn?: typeof fetch;
-}
-
-export interface ValidationError {
-  code: string;
-  message: string;
-  path?: string;
-}
-
-interface ManifestFileEntry {
-  path: string;
-  sha256: string;
-  size_bytes: number;
-}
-
-interface ManifestAssistantInfo {
-  id: string;
-  name: string;
-  runtime_version: string;
-}
-
-interface ManifestOrigin {
-  mode: "managed" | "self-hosted-remote" | "self-hosted-local";
-  platform_version?: string;
-  hostname?: string;
-}
-
-interface ManifestCompatibility {
-  min_runtime_version: string;
-  max_runtime_version: string | null;
-}
-
-interface ManifestExportOptions {
-  include_logs: boolean;
-  include_browser_state: boolean;
-  include_memory_vectors: boolean;
-}
-
-export interface Manifest {
-  schema_version: number;
-  bundle_id: string;
-  created_at: string;
-  assistant: ManifestAssistantInfo;
-  origin: ManifestOrigin;
-  compatibility: ManifestCompatibility;
-  contents: ManifestFileEntry[];
-  checksum: string;
-  secrets_redacted: boolean;
-  export_options: ManifestExportOptions;
-}
-
-export interface ValidateSuccessResponse {
-  is_valid: true;
-  errors: ValidationError[];
-  manifest: Manifest;
-}
-
-export interface ValidateFailureResponse {
-  is_valid: false;
-  errors: ValidationError[];
-}
-
-export type ValidateResponse =
-  | ValidateSuccessResponse
-  | ValidateFailureResponse;
-
-/** Runtime export returns the binary archive directly. */
-export interface ExportRuntimeResult {
-  ok: true;
-  archive: ArrayBuffer;
-  filename: string;
-  schemaVersion: number;
-  checksum: string;
-}
-
-/** Managed export initiates an async job and returns a job ID. */
-export interface ExportManagedResult {
-  ok: true;
-  jobId: string;
-  status: string;
-}
-
-type ExportResult = ExportRuntimeResult | ExportManagedResult;
-
-export interface ImportPreflightFileReport {
-  path: string;
-  action: "create" | "overwrite" | "unchanged" | "skip";
-  bundle_size: number;
-  current_size: number | null;
-  bundle_sha256: string;
-  current_sha256: string | null;
-}
-
-export interface ImportPreflightConflict {
-  code: string;
-  message: string;
-  path?: string;
-}
-
-export interface ImportPreflightSuccessResponse {
-  can_import: true;
-  summary: {
-    total_files: number;
-    files_to_create: number;
-    files_to_overwrite: number;
-    files_unchanged: number;
-    files_to_skip: number;
-  };
-  files: ImportPreflightFileReport[];
-  conflicts: ImportPreflightConflict[];
-  manifest: Manifest;
-}
-
-export interface ImportPreflightValidationFailedResponse {
-  can_import: false;
-  validation: {
-    is_valid: false;
-    errors: ValidationError[];
-  };
-}
-
-export interface ImportPreflightConflictResponse {
-  can_import: false;
-  summary: {
-    total_files: number;
-    files_to_create: number;
-    files_to_overwrite: number;
-    files_unchanged: number;
-    files_to_skip: number;
-  };
-  files: ImportPreflightFileReport[];
-  conflicts: ImportPreflightConflict[];
-  manifest: Manifest;
-}
-
-export type ImportPreflightResponse =
-  | ImportPreflightSuccessResponse
-  | ImportPreflightValidationFailedResponse
-  | ImportPreflightConflictResponse;
-
-export interface ImportedFileReport {
-  path: string;
-  disk_path: string;
-  action: "created" | "overwritten" | "skipped";
-  size: number;
-  sha256: string;
-  backup_path: string | null;
-}
-
-export interface ImportCommitSuccessResponse {
-  success: true;
-  summary: {
-    total_files: number;
-    files_created: number;
-    files_overwritten: number;
-    files_skipped: number;
-    backups_created: number;
-  };
-  files: ImportedFileReport[];
-  manifest: Manifest;
-  warnings: string[];
-  credentialsImported?: {
-    total: number;
-    succeeded: number;
-    failed: number;
-    failedAccounts: string[];
-    skippedPlatform?: number;
-  };
-}
-
-export interface ImportCommitFailureResponse {
-  success: false;
-  reason: "validation_failed" | "extraction_failed" | "write_failed";
-  errors?: ValidationError[];
-  message?: string;
-  partial_report?: unknown;
-}
-
-export type ImportCommitResponse =
-  | ImportCommitSuccessResponse
-  | ImportCommitFailureResponse;
-
-export interface JobStatusPending {
-  status: "pending" | "processing";
-  jobId: string;
-  progress?: number;
-}
-
-export interface JobStatusComplete {
-  status: "complete";
-  jobId: string;
-  downloadUrl?: string;
-  result?: unknown;
-}
-
-export interface JobStatusFailed {
-  status: "failed";
-  jobId: string;
-  error: string;
-}
-
-export type JobStatusResponse =
-  | JobStatusPending
-  | JobStatusComplete
-  | JobStatusFailed;
-
-export class MigrationTransportError extends Error {
-  readonly statusCode: number;
-  readonly responseBody: string;
-
-  constructor(message: string, statusCode: number, responseBody: string) {
-    super(message);
-    this.name = "MigrationTransportError";
-    this.statusCode = statusCode;
-    this.responseBody = responseBody;
-  }
-}
-
-function resolveFetch(config: TransportConfig): typeof fetch {
-  return config.fetchFn ?? globalThis.fetch;
-}
-
-function buildURL(config: TransportConfig, path: string): string {
-  const base = config.baseURL.replace(/\/+$/, "");
-  const trailingSlash = config.target === "managed" ? "/" : "";
-  return `${base}/v1/migrations/${path}${trailingSlash}`;
-}
-
-function buildHeaders(
-  config: TransportConfig,
-  contentType?: string,
-): Record<string, string> {
-  const headers: Record<string, string> = {};
-  const headerKeysByLowerName = new Map<string, string>();
-
-  const setHeader = (headerName: string, headerValue: string): void => {
-    const lowerName = headerName.toLowerCase();
-    const existingHeaderName = headerKeysByLowerName.get(lowerName);
-    if (existingHeaderName && existingHeaderName !== headerName) {
-      delete headers[existingHeaderName];
-    }
-    headerKeysByLowerName.set(lowerName, headerName);
-    headers[headerName] = headerValue;
-  };
-
-  if (contentType) {
-    setHeader("Content-Type", contentType);
-  }
-
-  // Merge defaultHeaders after Content-Type but before auth injection
-  if (config.defaultHeaders) {
-    for (const [headerName, headerValue] of Object.entries(
-      config.defaultHeaders,
-    )) {
-      setHeader(headerName, headerValue);
-    }
-  }
-
-  // Auth header is applied last so it always wins over defaultHeaders
-  if (config.authHeader) {
-    const headerName =
-      config.authHeaderName ??
-      (config.target === "managed" ? "X-Session-Token" : "Authorization");
-    setHeader(headerName, config.authHeader);
-  }
-
-  return headers;
-}
-
-async function assertOk(response: Response, context: string): Promise<void> {
-  if (!response.ok) {
-    const body = await response.text().catch(() => "<unreadable>");
-    throw new MigrationTransportError(
-      `${context}: HTTP ${response.status}`,
-      response.status,
-      body,
-    );
-  }
-}
-
-/**
- * Validate a .vbundle archive.
- *
- * Sends the archive as binary body and returns structured validation results.
- */
-export async function validateBundle(
-  config: TransportConfig,
-  fileData: ArrayBuffer,
-): Promise<ValidateResponse> {
-  const doFetch = resolveFetch(config);
-  const url = buildURL(config, "validate");
-
-  const response = await doFetch(url, {
-    method: "POST",
-    headers: buildHeaders(config, "application/octet-stream"),
-    body: fileData,
-  });
-
-  await assertOk(response, "validate");
-  return (await response.json()) as ValidateResponse;
-}
-
-/**
- * Export assistant data as a .vbundle archive.
- *
- * Runtime target: returns the binary archive directly.
- * Managed target: initiates an async export job and returns the job ID.
- */
-export async function exportBundle(
-  config: TransportConfig,
-  options?: { description?: string },
-): Promise<ExportResult> {
-  const doFetch = resolveFetch(config);
-  const url = buildURL(config, "export");
-
-  const body = options?.description
-    ? JSON.stringify({ description: options.description })
-    : undefined;
-
-  const contentType = body ? "application/json" : undefined;
-
-  const response = await doFetch(url, {
-    method: "POST",
-    headers: buildHeaders(config, contentType),
-    ...(body ? { body } : {}),
-  });
-
-  await assertOk(response, "export");
-
-  if (config.target === "managed") {
-    const json = (await response.json()) as {
-      job_id: string;
-      status: string;
-    };
-    return {
-      ok: true,
-      jobId: json.job_id,
-      status: json.status,
-    } as ExportManagedResult;
-  }
-
-  // Runtime returns the binary archive. The legacy
-  // `X-Vbundle-Manifest-Sha256` response header name is preserved for
-  // cross-version client compat — its value is now sourced from the
-  // renamed manifest `checksum` field.
-  const archive = await response.arrayBuffer();
-  const schemaVersionHeader =
-    response.headers.get("X-Vbundle-Schema-Version") ?? "";
-  const parsedSchemaVersion = Number.parseInt(schemaVersionHeader, 10);
-  return {
-    ok: true,
-    archive,
-    filename:
-      response.headers
-        .get("Content-Disposition")
-        ?.match(/filename="?(.+?)"?$/)?.[1] ?? "export.vbundle",
-    schemaVersion: Number.isFinite(parsedSchemaVersion)
-      ? parsedSchemaVersion
-      : 0,
-    checksum: response.headers.get("X-Vbundle-Manifest-Sha256") ?? "",
-  } as ExportRuntimeResult;
-}
-
-/**
- * Dry-run import analysis of a .vbundle archive.
- *
- * Returns a detailed report of what would change if the bundle were imported,
- * without modifying any data on disk.
- */
-export async function importPreflight(
-  config: TransportConfig,
-  fileData: ArrayBuffer,
-): Promise<ImportPreflightResponse> {
-  const doFetch = resolveFetch(config);
-  const url = buildURL(config, "import-preflight");
-
-  const response = await doFetch(url, {
-    method: "POST",
-    headers: buildHeaders(config, "application/octet-stream"),
-    body: fileData,
-  });
-
-  await assertOk(response, "import-preflight");
-  return (await response.json()) as ImportPreflightResponse;
-}
-
-/**
- * Commit a .vbundle archive import.
- *
- * This is a destructive operation that writes bundle files to their
- * target locations. For managed targets, this may initiate an async
- * import job.
- */
-export async function importCommit(
-  config: TransportConfig,
-  fileData: ArrayBuffer,
-): Promise<ImportCommitResponse> {
-  const doFetch = resolveFetch(config);
-  const url = buildURL(config, "import");
-
-  const response = await doFetch(url, {
-    method: "POST",
-    headers: buildHeaders(config, "application/octet-stream"),
-    body: fileData,
-  });
-
-  // The import endpoint can return non-2xx for server errors but
-  // also returns 200 with success: false for validation/write failures.
-  // We only throw on non-2xx status codes.
-  if (response.status >= 500) {
-    const body = await response.text().catch(() => "<unreadable>");
-    throw new MigrationTransportError(
-      `import: HTTP ${response.status}`,
-      response.status,
-      body,
-    );
-  }
-
-  // 400-level errors are also transport failures
-  if (response.status >= 400 && response.status < 500) {
-    const body = await response.text().catch(() => "<unreadable>");
-    throw new MigrationTransportError(
-      `import: HTTP ${response.status}`,
-      response.status,
-      body,
-    );
-  }
-
-  return (await response.json()) as ImportCommitResponse;
-}
-
-/**
- * Poll the status of a cloud export job.
- *
- * Only applicable to managed targets. Runtime exports are synchronous
- * and do not require status polling.
- */
-export async function pollExportStatus(
-  config: TransportConfig,
-  jobId: string,
-): Promise<JobStatusResponse> {
-  return fetchJobStatus(config, "export", jobId);
-}
-
-/**
- * Poll the status of a cloud import job.
- *
- * Only applicable to managed targets. Runtime imports are synchronous
- * and do not require status polling.
- */
-export async function pollImportStatus(
-  config: TransportConfig,
-  jobId: string,
-): Promise<JobStatusResponse> {
-  return fetchJobStatus(config, "import", jobId);
-}
-
-const jobStatusWireSchema = z.object({
-  status: z.enum(["pending", "processing", "complete", "failed"]),
-  job_id: z.string().optional(),
-  download_url: z.string().optional(),
-  progress: z.number().optional(),
-  error: z.string().optional(),
-  result: z.unknown().optional(),
-});
-
-function jobStatusFromWire(
-  wire: z.infer<typeof jobStatusWireSchema>,
-  fallbackJobId: string,
-): JobStatusResponse {
-  const jobId = wire.job_id ?? fallbackJobId;
-  if (wire.status === "complete") {
-    return {
-      status: "complete",
-      jobId,
-      downloadUrl: wire.download_url,
-      result: wire.result,
-    };
-  }
-  if (wire.status === "failed") {
-    return {
-      status: "failed",
-      jobId,
-      error: wire.error ?? "unknown export error",
-    };
-  }
-  return { status: wire.status, jobId, progress: wire.progress };
-}
-
-async function fetchJobStatus(
-  config: TransportConfig,
-  kind: "export" | "import",
-  jobId: string,
-): Promise<JobStatusResponse> {
-  if (config.target !== "managed") {
-    throw new Error(
-      `poll${kind === "export" ? "Export" : "Import"}Status is only supported for managed targets`,
-    );
-  }
-
-  const doFetch = resolveFetch(config);
-  const base = config.baseURL.replace(/\/+$/, "");
-  const url = `${base}/v1/migrations/${kind}/${encodeURIComponent(
-    jobId,
-  )}/status/`;
-
-  const response = await doFetch(url, {
-    method: "GET",
-    headers: buildHeaders(config),
-  });
-
-  await assertOk(response, `${kind} status (job ${jobId})`);
-  const parsed = jobStatusWireSchema.safeParse(await response.json());
-  if (!parsed.success) {
-    throw new MigrationTransportError(
-      `${kind} status (job ${jobId}): malformed response`,
-      response.status,
-      "",
-    );
-  }
-  return jobStatusFromWire(parsed.data, jobId);
-}
-
-interface PollOptions {
-  /** Polling interval in milliseconds. Defaults to 2000. */
-  intervalMs?: number;
-  /** Maximum number of polls before giving up. Defaults to 60. */
-  maxAttempts?: number;
-  /** Callback invoked on each poll with the latest status. */
-  onProgress?: (status: JobStatusResponse) => void;
-}
-
-/**
- * Poll a cloud job until it reaches a terminal state (complete or failed).
- *
- * Returns the final status response. Throws if maxAttempts is exceeded.
- */
-export async function pollUntilComplete(
-  config: TransportConfig,
-  jobType: "export" | "import",
-  jobId: string,
-  options?: PollOptions,
-): Promise<JobStatusComplete | JobStatusFailed> {
-  const intervalMs = options?.intervalMs ?? 2000;
-  const maxAttempts = options?.maxAttempts ?? 60;
-  const pollFn = jobType === "export" ? pollExportStatus : pollImportStatus;
-
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const status = await pollFn(config, jobId);
-    options?.onProgress?.(status);
-
-    if (status.status === "complete" || status.status === "failed") {
-      return status;
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, intervalMs));
-  }
-
-  throw new MigrationTransportError(
-    `${jobType} job ${jobId} did not complete within ${maxAttempts} polls`,
-    0,
-    "",
-  );
-}