@vellumai/assistant 0.6.6 → 0.7.1

package/src/runtime/migrations/__tests__/v1-test-helpers.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared test helpers for vbundle v1 manifest fixture builders.
+ *
+ * Most tests don't care about the specific values of the assistant identity,
+ * origin, compatibility, or export-options blocks — they just need the
+ * builder/validator to accept their fixtures. Centralizing the defaults
+ * keeps every test from re-spelling the same six required option fields.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type {
+  BuildVBundleOptions,
+  VBundleAssistantInfo,
+  VBundleCompatibility,
+  VBundleExportOptions,
+  VBundleOriginInfo,
+} from "../vbundle-builder.js";
+import {
+  computeManifestChecksum,
+  type ManifestFileEntryType,
+  type ManifestType,
+} from "../vbundle-validator.js";
+
+export interface DefaultV1Options {
+  assistant: VBundleAssistantInfo;
+  origin: VBundleOriginInfo;
+  compatibility: VBundleCompatibility;
+  exportOptions: VBundleExportOptions;
+  secretsRedacted: boolean;
+}
+
+/**
+ * Sensible defaults for the six caller-required v1 manifest options.
+ *
+ * `secretsRedacted` defaults to false to match the runtime's typical
+ * "credentials included by design" path; tests that exercise the managed
+ * cross-field refine override `origin.mode` and `secretsRedacted` directly.
+ */
+export function defaultV1Options(): DefaultV1Options {
+  return {
+    assistant: {
+      id: "self",
+      name: "Test",
+      runtime_version: "0.0.0-test",
+    },
+    origin: {
+      mode: "self-hosted-local",
+    },
+    compatibility: {
+      min_runtime_version: "0.0.0-test",
+      max_runtime_version: null,
+    },
+    exportOptions: {
+      include_logs: false,
+      include_browser_state: false,
+      include_memory_vectors: false,
+    },
+    secretsRedacted: false,
+  };
+}
+
+/**
+ * Convenience: spread `defaultV1Options()` into a `BuildVBundleOptions`
+ * with the supplied `files`. Saves repeating the spread at every call site.
+ */
+export function buildVBundleTestOptions(
+  files: BuildVBundleOptions["files"],
+  overrides: Partial<DefaultV1Options> = {},
+): BuildVBundleOptions {
+  return {
+    files,
+    ...defaultV1Options(),
+    ...overrides,
+  };
+}
+
+/**
+ * Build a v1 ManifestType for tests, mirroring buildManifestObject() in
+ * vbundle-builder.ts. Use this in test fixtures that need a synthetic
+ * manifest rather than calling buildVBundle (e.g. cross-version compat
+ * tests that need to mutate fields between emit and validate).
+ *
+ * Pass `overrides` to override any field after the defaults are applied —
+ * useful for negative-path tests that exercise specific schema rejections.
+ * `schema_version` is widened to `number` so negative tests can write 0/2/etc.
+ * The checksum is computed on the merged shape so overrides take effect.
+ */
+export type BuildTestManifestOverrides = Partial<
+  Omit<ManifestType, "schema_version">
+> & { schema_version?: number };
+
+export function buildTestManifest(input: {
+  contents: ManifestFileEntryType[];
+  overrides?: BuildTestManifestOverrides;
+}): ManifestType {
+  const base = defaultV1Options();
+  const merged = {
+    schema_version: 1,
+    bundle_id: randomUUID(),
+    created_at: new Date().toISOString(),
+    assistant: base.assistant,
+    origin: base.origin,
+    compatibility: base.compatibility,
+    contents: input.contents,
+    checksum: "",
+    secrets_redacted: base.secretsRedacted,
+    export_options: base.exportOptions,
+    ...(input.overrides ?? {}),
+  } as ManifestType;
+  return { ...merged, checksum: computeManifestChecksum(merged) };
+}

package/src/runtime/migrations/__tests__/vbundle-builder-credentials.test.ts

@@ -16,6 +16,7 @@ import { gunzipSync } from "node:zlib";
 import { describe, expect, test } from "bun:test";
 
 import { buildExportVBundle, streamExportVBundle } from "../vbundle-builder.js";
+import { defaultV1Options } from "./v1-test-helpers.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -111,6 +112,7 @@ describe("buildExportVBundle with credentials", () => {
       ];
 
       const result = buildExportVBundle({
+        ...defaultV1Options(),
         workspaceDir: workspace.dir,
         credentials,
       });
@@ -141,6 +143,7 @@ describe("buildExportVBundle with credentials", () => {
       ];
 
       const result = buildExportVBundle({
+        ...defaultV1Options(),
         workspaceDir: workspace.dir,
         credentials,
       });
@@ -149,12 +152,12 @@ describe("buildExportVBundle with credentials", () => {
         new TextEncoder().encode("secret-value-abc"),
       );
 
-      const credEntry = result.manifest.files.find(
+      const credEntry = result.manifest.contents.find(
         (f) => f.path === "credentials/my-api-key",
       );
       expect(credEntry).toBeDefined();
       expect(credEntry!.sha256).toBe(expectedHash);
-      expect(credEntry!.size).toBe(
+      expect(credEntry!.size_bytes).toBe(
         new TextEncoder().encode("secret-value-abc").length,
       );
     } finally {
@@ -166,6 +169,7 @@ describe("buildExportVBundle with credentials", () => {
     const workspace = createTestWorkspace();
     try {
       const result = buildExportVBundle({
+        ...defaultV1Options(),
         workspaceDir: workspace.dir,
       });
 
@@ -178,7 +182,7 @@ describe("buildExportVBundle with credentials", () => {
       expect(credentialEntries).toHaveLength(0);
 
       // Manifest should have no credential entries
-      const credManifestEntries = result.manifest.files.filter((f) =>
+      const credManifestEntries = result.manifest.contents.filter((f) =>
         f.path.startsWith("credentials/"),
       );
       expect(credManifestEntries).toHaveLength(0);
@@ -191,6 +195,7 @@ describe("buildExportVBundle with credentials", () => {
     const workspace = createTestWorkspace();
     try {
       const result = buildExportVBundle({
+        ...defaultV1Options(),
         workspaceDir: workspace.dir,
         credentials: [],
       });
@@ -218,6 +223,7 @@ describe("streamExportVBundle with credentials", () => {
       ];
 
       result = await streamExportVBundle({
+        ...defaultV1Options(),
         workspaceDir: workspace.dir,
         credentials,
       });
@@ -237,7 +243,7 @@ describe("streamExportVBundle with credentials", () => {
       );
 
       // Verify manifest entry
-      const credEntry = result.manifest.files.find(
+      const credEntry = result.manifest.contents.find(
         (f) => f.path === "credentials/stream-key",
       );
       expect(credEntry).toBeDefined();
@@ -255,6 +261,7 @@ describe("streamExportVBundle with credentials", () => {
     let result: Awaited<ReturnType<typeof streamExportVBundle>> | undefined;
     try {
       result = await streamExportVBundle({
+        ...defaultV1Options(),
         workspaceDir: workspace.dir,
       });
 

package/src/runtime/migrations/__tests__/vbundle-builder-v1-shape.test.ts

@@ -0,0 +1,253 @@
+/**
+ * Verifies that the buffered (`buildVBundle` / `buildExportVBundle`) and
+ * streaming (`streamExportVBundle`) emit paths both produce manifests
+ * conforming to the canonical v1 ten-field shape.
+ *
+ * Drift between the two emit paths is exactly how the prior schema
+ * mismatch went unnoticed — these tests pin both paths to the same shape
+ * and run a round-trip through `validateVBundle` so any future
+ * canonicalization drift fails loudly.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildExportVBundle,
+  buildVBundle,
+  streamExportVBundle,
+} from "../vbundle-builder.js";
+import { canonicalizeJson, validateVBundle } from "../vbundle-validator.js";
+import { defaultV1Options } from "./v1-test-helpers.js";
+
+function sha256Hex(data: Uint8Array | string): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+function createTestWorkspace(): { dir: string; cleanup: () => void } {
+  const dir = join(
+    tmpdir(),
+    `vbundle-v1-shape-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "config.json"), JSON.stringify({ test: true }));
+  const dbDir = join(dir, "data", "db");
+  mkdirSync(dbDir, { recursive: true });
+  writeFileSync(join(dbDir, "assistant.db"), "fake-db-content");
+  return {
+    dir,
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+const UUID_V4_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const ISO_8601_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+describe("buildVBundle — v1 ten-field manifest shape", () => {
+  test("emits all ten required top-level fields with correct types", () => {
+    const { manifest } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    expect(manifest.schema_version).toBe(1);
+    expect(typeof manifest.bundle_id).toBe("string");
+    expect(manifest.bundle_id).toMatch(UUID_V4_RE);
+    expect(manifest.created_at).toMatch(ISO_8601_RE);
+    expect(manifest.assistant.id).toBe("self");
+    expect(manifest.assistant.name).toBe("Test");
+    expect(manifest.assistant.runtime_version).toBe("0.0.0-test");
+    expect(manifest.origin.mode).toBe("self-hosted-local");
+    expect(manifest.compatibility.min_runtime_version).toBe("0.0.0-test");
+    expect(manifest.compatibility.max_runtime_version).toBeNull();
+    expect(Array.isArray(manifest.contents)).toBe(true);
+    expect(manifest.contents.length).toBeGreaterThan(0);
+    expect(manifest.checksum).toMatch(SHA256_HEX_RE);
+    expect(typeof manifest.secrets_redacted).toBe("boolean");
+    expect(typeof manifest.export_options.include_logs).toBe("boolean");
+  });
+
+  test("contents always declares data/db/assistant.db when the input includes it", () => {
+    const { manifest } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+        {
+          path: "config/settings.json",
+          data: new TextEncoder().encode("{}"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const dbEntry = manifest.contents.find(
+      (f) => f.path === "data/db/assistant.db",
+    );
+    expect(dbEntry).toBeDefined();
+    expect(dbEntry!.size_bytes).toBe(
+      new TextEncoder().encode("db-bytes").length,
+    );
+  });
+
+  test("checksum is the sha256 of the canonicalized manifest with checksum=''", () => {
+    const { manifest } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const expected = sha256Hex(canonicalizeJson({ ...manifest, checksum: "" }));
+    expect(manifest.checksum).toBe(expected);
+  });
+
+  test("secrets_redacted reflects the input flag", () => {
+    const truthy = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+      ],
+      ...defaultV1Options(),
+      secretsRedacted: true,
+    });
+    expect(truthy.manifest.secrets_redacted).toBe(true);
+
+    const falsey = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+      ],
+      ...defaultV1Options(),
+      secretsRedacted: false,
+    });
+    expect(falsey.manifest.secrets_redacted).toBe(false);
+  });
+
+  test("bundle_id is a fresh UUID per export", () => {
+    const a = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+    const b = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new TextEncoder().encode("db-bytes"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+    expect(a.manifest.bundle_id).not.toBe(b.manifest.bundle_id);
+  });
+});
+
+describe("streamExportVBundle — v1 ten-field manifest shape", () => {
+  test("matches buildExportVBundle's manifest shape (modulo bundle_id and created_at)", async () => {
+    const workspace = createTestWorkspace();
+    let streamResult:
+      | Awaited<ReturnType<typeof streamExportVBundle>>
+      | undefined;
+    try {
+      const sync = buildExportVBundle({
+        workspaceDir: workspace.dir,
+        ...defaultV1Options(),
+      });
+      streamResult = await streamExportVBundle({
+        workspaceDir: workspace.dir,
+        ...defaultV1Options(),
+      });
+
+      expect(streamResult.manifest.schema_version).toBe(
+        sync.manifest.schema_version,
+      );
+      expect(streamResult.manifest.assistant).toEqual(sync.manifest.assistant);
+      expect(streamResult.manifest.origin).toEqual(sync.manifest.origin);
+      expect(streamResult.manifest.compatibility).toEqual(
+        sync.manifest.compatibility,
+      );
+      expect(streamResult.manifest.export_options).toEqual(
+        sync.manifest.export_options,
+      );
+      expect(streamResult.manifest.secrets_redacted).toBe(
+        sync.manifest.secrets_redacted,
+      );
+
+      // Same set of files (paths + sha + size).
+      const sortByPath = (a: { path: string }, b: { path: string }) =>
+        a.path.localeCompare(b.path);
+      expect(streamResult.manifest.contents.slice().sort(sortByPath)).toEqual(
+        sync.manifest.contents.slice().sort(sortByPath),
+      );
+    } finally {
+      await streamResult?.cleanup();
+      workspace.cleanup();
+    }
+  });
+});
+
+describe("buildExportVBundle round-trip", () => {
+  test("validateVBundle accepts the buffered emit", () => {
+    const workspace = createTestWorkspace();
+    try {
+      const result = buildExportVBundle({
+        workspaceDir: workspace.dir,
+        ...defaultV1Options(),
+      });
+      const validation = validateVBundle(result.archive);
+      expect(validation.is_valid).toBe(true);
+      expect(validation.errors).toHaveLength(0);
+      expect(validation.manifest?.checksum).toBe(result.manifest.checksum);
+    } finally {
+      workspace.cleanup();
+    }
+  });
+
+  test("validateVBundle accepts the streaming emit", async () => {
+    const workspace = createTestWorkspace();
+    let result: Awaited<ReturnType<typeof streamExportVBundle>> | undefined;
+    try {
+      result = await streamExportVBundle({
+        workspaceDir: workspace.dir,
+        ...defaultV1Options(),
+      });
+      const archive = new Uint8Array(
+        await Bun.file(result.tempPath).arrayBuffer(),
+      );
+      // Sanity: archive is valid gzip of a tar.
+      expect(gunzipSync(archive).length).toBeGreaterThan(0);
+      const validation = validateVBundle(archive);
+      expect(validation.is_valid).toBe(true);
+      expect(validation.errors).toHaveLength(0);
+      expect(validation.manifest?.checksum).toBe(result.manifest.checksum);
+    } finally {
+      await result?.cleanup();
+      workspace.cleanup();
+    }
+  });
+});

package/src/runtime/migrations/__tests__/vbundle-import-credentials.test.ts

@@ -24,16 +24,29 @@ function makeTarEntry(data: string): VBundleTarEntry {
 
 function makeManifest(paths: string[]): ManifestType {
   return {
-    schema_version: "1.0.0",
+    schema_version: 1,
+    bundle_id: "00000000-0000-4000-8000-000000000000",
     created_at: new Date().toISOString(),
-    source: "test",
-    manifest_sha256: "test",
-    files: paths.map((path) => ({
+    assistant: { id: "self", name: "Test", runtime_version: "0.0.0-test" },
+    origin: { mode: "self-hosted-local" },
+    compatibility: {
+      min_runtime_version: "0.0.0-test",
+      max_runtime_version: null,
+    },
+    contents: paths.map((path) => ({
       path,
-      size: 0,
+      size_bytes: 0,
       sha256: "test",
     })),
-  } as ManifestType;
+    checksum:
+      "0000000000000000000000000000000000000000000000000000000000000000",
+    secrets_redacted: false,
+    export_options: {
+      include_logs: false,
+      include_browser_state: false,
+      include_memory_vectors: false,
+    },
+  } as unknown as ManifestType;
 }
 
 // ---------------------------------------------------------------------------