@vellumai/assistant 0.4.56 → 0.4.57

package/src/__tests__/migration-cross-version-compatibility.test.ts

@@ -53,13 +53,14 @@ function toArrayBuffer(data: Uint8Array): ArrayBuffer {
 const testDir = realpathSync(
   mkdtempSync(join(tmpdir(), "migration-cross-version-test-")),
 );
-const testDbDir = join(testDir, "db");
+const testDbDir = join(testDir, "data", "db");
 const testDbPath = join(testDbDir, "assistant.db");
 const testConfigPath = join(testDir, "config.json");
 
 mock.module("../util/platform.js", () => ({
   getRootDir: () => testDir,
-  getDataDir: () => testDir,
+  getDataDir: () => join(testDir, "data"),
+  getWorkspaceDir: () => testDir,
   getWorkspaceConfigPath: () => testConfigPath,
   isMacOS: () => process.platform === "darwin",
   isLinux: () => process.platform === "linux",
@@ -83,9 +84,8 @@ mock.module("../config/loader.js", () => ({
     model: "test",
     provider: "test",
     memory: { enabled: false },
-    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    rateLimit: { maxRequestsPerMinute: 0 },
     secretDetection: { enabled: false },
-    sandbox: { enabled: false },
   }),
 }));
 
@@ -445,7 +445,7 @@ describe("schema version compatibility", () => {
       { schema_version: "3.0" },
     );
 
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -463,7 +463,7 @@ describe("schema version compatibility", () => {
       schema_version: "5.0-beta",
     });
 
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const validationResult = validateVBundle(vbundle);
     expect(validationResult.manifest).toBeDefined();
 
@@ -774,9 +774,10 @@ describe("round-trip: export -> validate -> preflight -> import", () => {
     expect(preflightBody.files).toBeDefined();
     expect(preflightBody.manifest).toBeDefined();
 
-    // The files should show "unchanged" since we exported from the same disk
+    // The files should show "unchanged" since we exported from the same disk.
+    // New format uses workspace/ prefix for archive paths.
     const dbFile = preflightBody.files!.find(
-      (f) => f.path === "data/db/assistant.db",
+      (f) => f.path === "workspace/data/db/assistant.db",
     );
     expect(dbFile).toBeDefined();
     expect(dbFile!.action).toBe("unchanged");
@@ -829,7 +830,7 @@ describe("round-trip: export -> validate -> preflight -> import", () => {
     );
 
     // Step 3: Analyze (preflight)
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const report = analyzeImport({
       manifest: validationResult.manifest!,
       pathResolver: resolver,
@@ -888,13 +889,14 @@ describe("partial failure scenarios", () => {
       { path: "data/db/assistant.db", data: newDbData },
     ]);
 
-    // Point to a path that cannot be written (a non-existent deeply nested
-    // directory whose parent is a regular file, not a directory)
-    const blockerPath = join(testDir, "blocker-file");
-    writeFileSync(blockerPath, "I am a file, not a directory");
-    const impossibleDbPath = join(blockerPath, "nested", "deep", "db.db");
+    // Point to a workspace path where data/db cannot be created
+    // (a regular file blocks directory creation)
+    const blockerWorkspace = join(testDir, "blocker-workspace");
+    mkdirSync(blockerWorkspace, { recursive: true });
+    // Create "data" as a regular file — mkdirSync("data/db") will fail
+    writeFileSync(join(blockerWorkspace, "data"), "I am a file, not a directory");
 
-    const resolver = new DefaultPathResolver(impossibleDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, blockerWorkspace);
     const result = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -908,11 +910,11 @@ describe("partial failure scenarios", () => {
     }
 
     // Clean up
-    rmSync(blockerPath, { force: true });
+    rmSync(blockerWorkspace, { recursive: true, force: true });
   });
 
   test("commitImport with invalid archive returns validation_failed", () => {
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: new Uint8Array([0xba, 0xad, 0xf0, 0x0d]),
       pathResolver: resolver,
@@ -1000,7 +1002,7 @@ describe("partial failure scenarios", () => {
     ]);
     const corruptVBundle = gzipSync(tar);
 
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: corruptVBundle,
       pathResolver: resolver,
@@ -1032,7 +1034,7 @@ describe("edge cases", () => {
     expect(result.manifest?.files[0].size).toBe(0);
 
     // Import should also succeed
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const importResult = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -1186,7 +1188,10 @@ describe("edge cases", () => {
     expect(missingError!.message).toContain("data/extra/ghost.bin");
   });
 
-  test("bundle with only manifest (no required db) fails validation", () => {
+  test("bundle with only manifest (no data files) is valid", () => {
+    // After the workspace walk refactor, only manifest.json is required.
+    // A bundle with no data files is structurally valid — it just won't
+    // restore anything meaningful.
     const manifestWithoutChecksum = {
       schema_version: "1.0",
       created_at: new Date().toISOString(),
@@ -1205,12 +1210,7 @@ describe("edge cases", () => {
     const vbundle = gzipSync(tar);
     const result = validateVBundle(vbundle);
 
-    expect(result.is_valid).toBe(false);
-    expect(
-      result.errors.some(
-        (e) => e.code === "MISSING_ENTRY" && e.path === "data/db/assistant.db",
-      ),
-    ).toBe(true);
+    expect(result.is_valid).toBe(true);
   });
 
   test("completely empty gzip content (no tar entries) fails gracefully", () => {
@@ -1424,7 +1424,7 @@ describe("diagnostic quality", () => {
   });
 
   test("import commit validation_failed response includes error codes and messages", () => {
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: new Uint8Array([0x00]),
       pathResolver: resolver,
@@ -1633,7 +1633,7 @@ describe("builder -> validator consistency", () => {
 
 describe("import analyzer edge cases", () => {
   test("all-unchanged files produce correct summary", () => {
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const existingConfig = new Uint8Array(readFileSync(testConfigPath));
 
     const report = analyzeImport({
@@ -1666,8 +1666,8 @@ describe("import analyzer edge cases", () => {
 
   test("all-create scenario (fresh install) produces correct summary", () => {
     const resolver = new DefaultPathResolver(
-      join(testDir, "nonexistent-dir", "db.db"),
-      join(testDir, "nonexistent-dir", "config.json"),
+      undefined,
+      join(testDir, "nonexistent-workspace"),
     );
 
     const report = analyzeImport({
@@ -1698,7 +1698,7 @@ describe("import analyzer edge cases", () => {
   });
 
   test("mixed create/overwrite/unchanged produces accurate counts", () => {
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
 
     // db: different from disk -> overwrite
     // config: same as disk -> unchanged
@@ -1731,7 +1731,7 @@ describe("import analyzer edge cases", () => {
   });
 
   test("unknown archive path produces UNKNOWN_ARCHIVE_PATH conflict", () => {
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
 
     const report = analyzeImport({
       manifest: {

package/src/__tests__/migration-export-http.test.ts

@@ -27,13 +27,14 @@ import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test";
 const testDir = realpathSync(
   mkdtempSync(join(tmpdir(), "migration-export-http-test-")),
 );
-const testDbDir = join(testDir, "db");
+const testDbDir = join(testDir, "data", "db");
 const testDbPath = join(testDbDir, "assistant.db");
 const testConfigPath = join(testDir, "config.json");
 
 mock.module("../util/platform.js", () => ({
   getRootDir: () => testDir,
-  getDataDir: () => testDir,
+  getDataDir: () => join(testDir, "data"),
+  getWorkspaceDir: () => testDir,
   getWorkspaceConfigPath: () => testConfigPath,
   isMacOS: () => process.platform === "darwin",
   isLinux: () => process.platform === "linux",
@@ -57,9 +58,8 @@ mock.module("../config/loader.js", () => ({
     model: "test",
     provider: "test",
     memory: { enabled: false },
-    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    rateLimit: { maxRequestsPerMinute: 0 },
     secretDetection: { enabled: false },
-    sandbox: { enabled: false },
   }),
 }));
 
@@ -206,10 +206,10 @@ describe("handleMigrationExport", () => {
     expect(manifest.created_at).toBeDefined();
     expect(manifest.manifest_sha256).toBeDefined();
 
-    // Verify file entries
+    // Verify file entries — workspace walk uses workspace/ prefix
     const filePaths = manifest.files.map((f) => f.path);
-    expect(filePaths).toContain("data/db/assistant.db");
-    expect(filePaths).toContain("config/settings.json");
+    expect(filePaths).toContain("workspace/data/db/assistant.db");
+    expect(filePaths).toContain("workspace/config.json");
 
     // Verify each file entry has proper sha256 and size
     for (const file of manifest.files) {
@@ -299,7 +299,7 @@ describe("export data population", () => {
     const archiveData = new Uint8Array(await res.arrayBuffer());
     const entries = parseTarEntries(archiveData);
 
-    const dbEntry = entries.find((e) => e.name === "data/db/assistant.db");
+    const dbEntry = entries.find((e) => e.name === "workspace/data/db/assistant.db");
     expect(dbEntry).toBeDefined();
     expect(dbEntry!.data.length).toBe(SQLITE_HEADER.length);
     // Verify the exported data matches the test fixture exactly
@@ -315,7 +315,7 @@ describe("export data population", () => {
     const archiveData = new Uint8Array(await res.arrayBuffer());
     const entries = parseTarEntries(archiveData);
 
-    const configEntry = entries.find((e) => e.name === "config/settings.json");
+    const configEntry = entries.find((e) => e.name === "workspace/config.json");
     expect(configEntry).toBeDefined();
 
     const configContent = new TextDecoder().decode(configEntry!.data);
@@ -336,13 +336,13 @@ describe("export data population", () => {
     const manifest = validationResult.manifest!;
 
     const dbFile = manifest.files.find(
-      (f) => f.path === "data/db/assistant.db",
+      (f) => f.path === "workspace/data/db/assistant.db",
     );
     expect(dbFile).toBeDefined();
     expect(dbFile!.size).toBe(SQLITE_HEADER.length);
 
     const configFile = manifest.files.find(
-      (f) => f.path === "config/settings.json",
+      (f) => f.path === "workspace/config.json",
     );
     expect(configFile).toBeDefined();
     const expectedConfigSize = Buffer.byteLength(
@@ -382,7 +382,7 @@ describe("export data population", () => {
     const manifest = validationResult.manifest!;
 
     const dbFile = manifest.files.find(
-      (f) => f.path === "data/db/assistant.db",
+      (f) => f.path === "workspace/data/db/assistant.db",
     );
     expect(dbFile).toBeDefined();
     // The skeleton used size 0 — real export should have actual content
@@ -398,7 +398,7 @@ describe("export data population", () => {
     const archiveData = new Uint8Array(await res.arrayBuffer());
     const entries = parseTarEntries(archiveData);
 
-    const configEntry = entries.find((e) => e.name === "config/settings.json");
+    const configEntry = entries.find((e) => e.name === "workspace/config.json");
     expect(configEntry).toBeDefined();
 
     const configContent = new TextDecoder().decode(configEntry!.data);
@@ -413,42 +413,41 @@ describe("export data population", () => {
 // ---------------------------------------------------------------------------
 
 describe("export graceful fallback", () => {
-  test("missing database produces valid archive with empty db entry", async () => {
+  test("nonexistent workspace produces valid archive with no files", async () => {
     const { buildExportVBundle } =
       await import("../runtime/migrations/vbundle-builder.js");
 
     const result = buildExportVBundle({
-      dbPath: join(testDir, "nonexistent.db"),
-      configPath: testConfigPath,
+      workspaceDir: join(testDir, "nonexistent-workspace"),
     });
 
     const validationResult = validateVBundle(result.archive);
     expect(validationResult.is_valid).toBe(true);
-
-    const dbFile = result.manifest.files.find(
-      (f) => f.path === "data/db/assistant.db",
-    );
-    expect(dbFile).toBeDefined();
-    expect(dbFile!.size).toBe(0);
+    expect(result.manifest.files).toHaveLength(0);
   });
 
-  test("missing config produces valid archive with empty JSON config", async () => {
+  test("workspace walk includes db and config under workspace/ prefix", async () => {
     const { buildExportVBundle } =
       await import("../runtime/migrations/vbundle-builder.js");
 
     const result = buildExportVBundle({
-      dbPath: testDbPath,
-      configPath: join(testDir, "nonexistent-config.json"),
+      workspaceDir: testDir,
     });
 
     const validationResult = validateVBundle(result.archive);
     expect(validationResult.is_valid).toBe(true);
 
+    const dbFile = result.manifest.files.find(
+      (f) => f.path === "workspace/data/db/assistant.db",
+    );
+    expect(dbFile).toBeDefined();
+    expect(dbFile!.size).toBeGreaterThan(0);
+
     const configFile = result.manifest.files.find(
-      (f) => f.path === "config/settings.json",
+      (f) => f.path === "workspace/config.json",
     );
     expect(configFile).toBeDefined();
-    expect(configFile!.size).toBe(2); // "{}" is 2 bytes
+    expect(configFile!.size).toBeGreaterThan(0);
   });
 });
 

package/src/__tests__/migration-import-commit-http.test.ts

@@ -48,13 +48,14 @@ function toArrayBuffer(data: Uint8Array): ArrayBuffer {
 const testDir = realpathSync(
   mkdtempSync(join(tmpdir(), "migration-import-commit-http-test-")),
 );
-const testDbDir = join(testDir, "db");
+const testDbDir = join(testDir, "data", "db");
 const testDbPath = join(testDbDir, "assistant.db");
 const testConfigPath = join(testDir, "config.json");
 
 mock.module("../util/platform.js", () => ({
   getRootDir: () => testDir,
-  getDataDir: () => testDir,
+  getDataDir: () => join(testDir, "data"),
+  getWorkspaceDir: () => testDir,
   getWorkspaceConfigPath: () => testConfigPath,
   isMacOS: () => process.platform === "darwin",
   isLinux: () => process.platform === "linux",
@@ -78,9 +79,8 @@ mock.module("../config/loader.js", () => ({
     model: "test",
     provider: "test",
     memory: { enabled: false },
-    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    rateLimit: { maxRequestsPerMinute: 0 },
     secretDetection: { enabled: false },
-    sandbox: { enabled: false },
   }),
 }));
 
@@ -377,10 +377,13 @@ describe("handleMigrationImport", () => {
     expect(writtenData).toEqual(newDbData);
   });
 
-  test("creates backup of existing files before overwriting", async () => {
+  test("workspace is cleared before restore — files are created fresh", async () => {
+    // Only new-format bundles (workspace/ prefix) trigger workspace clearing.
+    // With clearing, existing files are removed before writing, so all files
+    // in the bundle are "created" (not "overwritten") and no backups are made.
     const newDbData = new Uint8Array([0x01, 0x02, 0x03]);
     const vbundle = createValidVBundle([
-      { path: "data/db/assistant.db", data: newDbData },
+      { path: "workspace/data/db/assistant.db", data: newDbData },
     ]);
     const req = new Request("http://localhost/v1/migrations/import", {
       method: "POST",
@@ -392,29 +395,22 @@ describe("handleMigrationImport", () => {
     const body = (await res.json()) as ImportCommitResponse;
 
     expect(body.success).toBe(true);
-    expect(body.summary.backups_created).toBeGreaterThan(0);
+    expect(body.summary.backups_created).toBe(0);
 
-    // Verify backup was created
-    const dbFile = body.files.find((f) => f.path === "data/db/assistant.db");
+    const dbFile = body.files.find(
+      (f) => f.path === "workspace/data/db/assistant.db",
+    );
     expect(dbFile).toBeDefined();
-    expect(dbFile!.action).toBe("overwritten");
-    expect(dbFile!.backup_path).not.toBeNull();
-    expect(existsSync(dbFile!.backup_path!)).toBe(true);
-
-    // Verify backup contains the original data
-    const backupData = new Uint8Array(readFileSync(dbFile!.backup_path!));
-    expect(backupData).toEqual(EXISTING_DB_DATA);
+    expect(dbFile!.action).toBe("created");
   });
 
-  test("reports correct actions for created and overwritten files", async () => {
-    // Remove the config file so it will be "created" instead of "overwritten"
-    rmSync(testConfigPath, { force: true });
-
+  test("reports all files as created after workspace clear", async () => {
+    // New-format workspace/ paths trigger clearing — both files are fresh.
     const newDbData = new Uint8Array([0xaa, 0xbb]);
     const newConfigData = new TextEncoder().encode('{"provider":"openai"}');
     const vbundle = createValidVBundle([
-      { path: "data/db/assistant.db", data: newDbData },
-      { path: "config/settings.json", data: newConfigData },
+      { path: "workspace/data/db/assistant.db", data: newDbData },
+      { path: "workspace/config.json", data: newConfigData },
     ]);
     const req = new Request("http://localhost/v1/migrations/import", {
       method: "POST",
@@ -427,14 +423,16 @@ describe("handleMigrationImport", () => {
 
     expect(body.success).toBe(true);
 
-    const dbFile = body.files.find((f) => f.path === "data/db/assistant.db");
+    const dbFile = body.files.find(
+      (f) => f.path === "workspace/data/db/assistant.db",
+    );
     const configFile = body.files.find(
-      (f) => f.path === "config/settings.json",
+      (f) => f.path === "workspace/config.json",
     );
 
-    expect(dbFile!.action).toBe("overwritten");
+    // Both are "created" because workspace was cleared before writing
+    expect(dbFile!.action).toBe("created");
     expect(configFile!.action).toBe("created");
-    expect(configFile!.backup_path).toBeNull();
   });
 
   test("summary counts match file details", async () => {
@@ -641,7 +639,7 @@ describe("commitImport", () => {
       { path: "data/db/assistant.db", data: newDbData },
     ]);
 
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -655,7 +653,7 @@ describe("commitImport", () => {
   });
 
   test("returns validation_failed for invalid bundles", () => {
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: new Uint8Array([0xba, 0xad]),
       pathResolver: resolver,
@@ -671,17 +669,16 @@ describe("commitImport", () => {
   });
 
   test("creates parent directories if they do not exist", () => {
-    // Use a path that does not exist yet
-    const nonexistentDir = join(testDir, "new-subdir");
-    const newDbPath = join(nonexistentDir, "assistant.db");
-    const newConfigPath = join(testDir, "new-config.json");
+    // Use a workspace that does not exist yet
+    const nonexistentWorkspace = join(testDir, "new-workspace");
+    const expectedDbPath = join(nonexistentWorkspace, "data", "db", "assistant.db");
 
     const dbData = new Uint8Array([0x01, 0x02, 0x03]);
     const vbundle = createValidVBundle([
       { path: "data/db/assistant.db", data: dbData },
     ]);
 
-    const resolver = new DefaultPathResolver(newDbPath, newConfigPath);
+    const resolver = new DefaultPathResolver(undefined, nonexistentWorkspace);
     const result = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -690,11 +687,11 @@ describe("commitImport", () => {
     expect(result.ok).toBe(true);
     if (result.ok) {
       expect(result.report.files[0].action).toBe("created");
-      expect(existsSync(newDbPath)).toBe(true);
+      expect(existsSync(expectedDbPath)).toBe(true);
     }
 
     // Clean up
-    rmSync(nonexistentDir, { recursive: true, force: true });
+    rmSync(nonexistentWorkspace, { recursive: true, force: true });
   });
 
   test("post-write integrity: written file SHA-256 matches expected", () => {
@@ -705,7 +702,7 @@ describe("commitImport", () => {
       { path: "data/db/assistant.db", data: newDbData },
     ]);
 
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -735,7 +732,7 @@ describe("commitImport", () => {
       { path: "config/settings.json", data: newConfigData },
     ]);
 
-    const resolver = new DefaultPathResolver(testDbPath, testConfigPath);
+    const resolver = new DefaultPathResolver(undefined, testDir);
     const result = commitImport({
       archiveData: vbundle,
       pathResolver: resolver,
@@ -755,6 +752,137 @@ describe("commitImport", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Workspace clearing tests
+// ---------------------------------------------------------------------------
+
+describe("commitImport — workspace clearing", () => {
+  const skillsDir = join(testDir, "skills");
+  const hooksDir = join(testDir, "hooks");
+
+  afterEach(() => {
+    // Restore test fixture files for subsequent tests
+    mkdirSync(testDbDir, { recursive: true });
+    writeFileSync(testDbPath, EXISTING_DB_DATA);
+    writeFileSync(testConfigPath, JSON.stringify(EXISTING_CONFIG, null, 2));
+    // Clean up skills/hooks dirs
+    for (const dir of [skillsDir, hooksDir]) {
+      if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("clears stale files via workspace clearing (new-format workspace/ entries)", () => {
+    mkdirSync(join(skillsDir, "stale-skill"), { recursive: true });
+    writeFileSync(join(skillsDir, "stale-skill", "SKILL.md"), "stale");
+
+    const skillData = new TextEncoder().encode("# New Skill");
+    const vbundle = createValidVBundle([
+      { path: "workspace/skills/new-skill/SKILL.md", data: skillData },
+    ]);
+
+    const resolver = new DefaultPathResolver(undefined, testDir);
+    const result = commitImport({
+      archiveData: vbundle,
+      pathResolver: resolver,
+      workspaceDir: testDir,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // New skill written
+    expect(existsSync(join(skillsDir, "new-skill", "SKILL.md"))).toBe(true);
+    expect(readFileSync(join(skillsDir, "new-skill", "SKILL.md"), "utf8")).toBe(
+      "# New Skill",
+    );
+
+    // Stale skill removed by workspace clearing
+    expect(existsSync(join(skillsDir, "stale-skill"))).toBe(false);
+  });
+
+  test("old-format skills/ entries do not trigger workspace clearing", () => {
+    mkdirSync(join(skillsDir, "stale-skill"), { recursive: true });
+    writeFileSync(join(skillsDir, "stale-skill", "SKILL.md"), "stale");
+
+    const skillData = new TextEncoder().encode("# New Skill");
+    const vbundle = createValidVBundle([
+      { path: "skills/new-skill/SKILL.md", data: skillData },
+    ]);
+
+    const resolver = new DefaultPathResolver(undefined, testDir);
+    const result = commitImport({
+      archiveData: vbundle,
+      pathResolver: resolver,
+      workspaceDir: testDir,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // New skill written
+    expect(existsSync(join(skillsDir, "new-skill", "SKILL.md"))).toBe(true);
+
+    // Stale skill survives — old-format bundles don't trigger workspace clearing
+    expect(existsSync(join(skillsDir, "stale-skill", "SKILL.md"))).toBe(true);
+  });
+
+  test("hooks/ entries import to hooksDir (not workspace/hooks/)", () => {
+    // Use a separate hooks dir outside the workspace, like production layout
+    const externalHooksDir = join(testDir, ".hooks-external");
+    mkdirSync(externalHooksDir, { recursive: true });
+
+    const hookData = new TextEncoder().encode("#!/bin/sh\necho new");
+    const vbundle = createValidVBundle([
+      { path: "hooks/new-hook/hook.sh", data: hookData },
+    ]);
+
+    const resolver = new DefaultPathResolver(undefined, testDir, externalHooksDir);
+    const result = commitImport({
+      archiveData: vbundle,
+      pathResolver: resolver,
+      workspaceDir: testDir,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Hook written to the external hooks dir, not workspace/hooks/
+    expect(existsSync(join(externalHooksDir, "new-hook", "hook.sh"))).toBe(true);
+    expect(
+      readFileSync(join(externalHooksDir, "new-hook", "hook.sh"), "utf8"),
+    ).toBe("#!/bin/sh\necho new");
+
+    // Cleanup
+    rmSync(externalHooksDir, { recursive: true, force: true });
+  });
+
+  test("without workspaceDir, no clearing happens", () => {
+    mkdirSync(join(skillsDir, "existing-skill"), { recursive: true });
+    writeFileSync(
+      join(skillsDir, "existing-skill", "SKILL.md"),
+      "should survive",
+    );
+
+    const vbundle = createValidVBundle([
+      { path: "skills/new-skill/SKILL.md", data: new TextEncoder().encode("new") },
+    ]);
+
+    const resolver = new DefaultPathResolver(undefined, testDir);
+    // No workspaceDir — no clearing
+    const result = commitImport({
+      archiveData: vbundle,
+      pathResolver: resolver,
+    });
+
+    expect(result.ok).toBe(true);
+
+    // Existing skill survives (no workspace clearing without workspaceDir)
+    expect(existsSync(join(skillsDir, "existing-skill", "SKILL.md"))).toBe(
+      true,
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Auth policy registration tests
 // ---------------------------------------------------------------------------