@cleocode/core 2026.4.12 → 2026.4.13

package/src/store/__tests__/backup-unpack.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Tests for backup-unpack.ts (T350).
+ *
+ * Covers: unpack of unencrypted and encrypted bundles, all verification
+ * layers, BundleError codes (70–75), staging dir management, and manifest
+ * field correctness.
+ *
+ * Uses real node:sqlite DatabaseSync to seed minimal test databases.
+ * All filesystem interactions occur in temp directories; the real user's
+ * project root is never touched.
+ *
+ * @task T350
+ * @epic T311
+ */
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { packBundle } from '../backup-pack.js';
+import { BundleError, cleanupStaging, unpackBundle } from '../backup-unpack.js';
+
+// ---------------------------------------------------------------------------
+// node:sqlite interop
+// ---------------------------------------------------------------------------
+
+const _require = createRequire(import.meta.url);
+type DatabaseSync = _DatabaseSyncType;
+const { DatabaseSync } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof _DatabaseSyncType>) => DatabaseSync;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed a project root with the minimal .cleo layout required by packBundle.
+ * Creates: tasks.db, brain.db, conduit.db, config.json, project-info.json,
+ * project-context.json.
+ */
+function seedProject(projectRoot: string): void {
+  const cleoDir = path.join(projectRoot, '.cleo');
+  fs.mkdirSync(cleoDir, { recursive: true });
+  for (const name of ['tasks', 'brain', 'conduit']) {
+    const db = new DatabaseSync(path.join(cleoDir, `${name}.db`));
+    db.exec('CREATE TABLE t(x INTEGER); INSERT INTO t VALUES (1);');
+    db.close();
+  }
+  fs.writeFileSync(path.join(cleoDir, 'config.json'), '{}');
+  fs.writeFileSync(path.join(cleoDir, 'project-info.json'), '{}');
+  fs.writeFileSync(path.join(cleoDir, 'project-context.json'), '{}');
+}
+
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
+
+describe('T350 backup-unpack', () => {
+  let tmpRoot: string;
+  let bundleDir: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t350-root-'));
+    bundleDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t350-bundle-'));
+    seedProject(tmpRoot);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+    fs.rmSync(bundleDir, { recursive: true, force: true });
+  });
+
+  async function createBundle(opts?: { encrypt?: boolean; passphrase?: string }): Promise<string> {
+    const bundlePath = path.join(
+      bundleDir,
+      'test' + (opts?.encrypt === true ? '.enc' : '') + '.cleobundle.tar.gz',
+    );
+    await packBundle({
+      scope: 'project',
+      projectRoot: tmpRoot,
+      outputPath: bundlePath,
+      encrypt: opts?.encrypt,
+      passphrase: opts?.passphrase,
+    });
+    return bundlePath;
+  }
+
+  // -------------------------------------------------------------------------
+  // Unencrypted bundle — happy path
+  // -------------------------------------------------------------------------
+
+  it('unpacks an unencrypted bundle successfully', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.verified.manifestSchema).toBe(true);
+    expect(result.verified.checksums).toBe(true);
+    expect(result.verified.sqliteIntegrity).toBe(true);
+    expect(result.manifest.backup.scope).toBe('project');
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('returns verified.encryptionAuth=true for unencrypted bundle (N/A = pass)', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.verified.encryptionAuth).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // Encrypted bundle — happy path
+  // -------------------------------------------------------------------------
+
+  it('unpacks an encrypted bundle with correct passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    const result = await unpackBundle({ bundlePath, passphrase: 'hunter2' });
+    expect(result.verified.encryptionAuth).toBe(true);
+    expect(result.verified.manifestSchema).toBe(true);
+    expect(result.verified.checksums).toBe(true);
+    expect(result.verified.sqliteIntegrity).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // Error: wrong passphrase → E_BUNDLE_DECRYPT (70)
+  // -------------------------------------------------------------------------
+
+  it('throws BundleError(70) on wrong passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    await expect(unpackBundle({ bundlePath, passphrase: 'wrong' })).rejects.toMatchObject({
+      code: 70,
+      codeName: 'E_BUNDLE_DECRYPT',
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error: encrypted bundle without passphrase → E_BUNDLE_DECRYPT (70)
+  // -------------------------------------------------------------------------
+
+  it('throws BundleError(70) on encrypted bundle without passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    await expect(unpackBundle({ bundlePath })).rejects.toMatchObject({ code: 70 });
+  });
+
+  it('throws BundleError(70) on encrypted bundle with empty passphrase', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'hunter2' });
+    await expect(unpackBundle({ bundlePath, passphrase: '' })).rejects.toMatchObject({ code: 70 });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error: tampered bundle → BundleError (72 or tar error)
+  // -------------------------------------------------------------------------
+
+  it('throws BundleError on checksum mismatch (tampered bytes)', async () => {
+    const bundlePath = await createBundle();
+    // Tamper by flipping bits near the end of the file (in the compressed data)
+    const buf = fs.readFileSync(bundlePath);
+    // Flip bytes well inside the compressed payload (not the gzip header)
+    const tamperOffset = Math.floor(buf.length / 2);
+    buf[tamperOffset] = buf[tamperOffset]! ^ 0xff;
+    buf[tamperOffset + 1] = (buf[tamperOffset + 1] ?? 0) ^ 0xff;
+    fs.writeFileSync(bundlePath, buf);
+    // tar may catch the corruption before we read checksums — accept any BundleError
+    await expect(unpackBundle({ bundlePath })).rejects.toBeInstanceOf(BundleError);
+  });
+
+  // -------------------------------------------------------------------------
+  // Staging directory structure
+  // -------------------------------------------------------------------------
+
+  it('returns a valid staging dir containing manifest.json, databases/, json/', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(fs.existsSync(path.join(result.stagingDir, 'manifest.json'))).toBe(true);
+    expect(fs.existsSync(path.join(result.stagingDir, 'databases'))).toBe(true);
+    expect(fs.existsSync(path.join(result.stagingDir, 'json'))).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('staging dir contains schemas/manifest-v1.json', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(fs.existsSync(path.join(result.stagingDir, 'schemas', 'manifest-v1.json'))).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // cleanupStaging
+  // -------------------------------------------------------------------------
+
+  it('cleanupStaging removes the staging dir', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    cleanupStaging(result.stagingDir);
+    expect(fs.existsSync(result.stagingDir)).toBe(false);
+  });
+
+  it('cleanupStaging is idempotent — does not throw if already removed', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    cleanupStaging(result.stagingDir);
+    // Second call must not throw
+    expect(() => cleanupStaging(result.stagingDir)).not.toThrow();
+  });
+
+  // -------------------------------------------------------------------------
+  // Manifest field correctness
+  // -------------------------------------------------------------------------
+
+  it('parses manifest fields correctly', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.manifest.manifestVersion).toBe('1.0.0');
+    expect(result.manifest.$schema).toBe('./schemas/manifest-v1.json');
+    expect(result.manifest.backup.scope).toBe('project');
+    expect(result.manifest.integrity.algorithm).toBe('sha256');
+    expect(result.manifest.databases.length).toBeGreaterThanOrEqual(3);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('manifest.backup.encrypted is false for unencrypted bundle', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    expect(result.manifest.backup.encrypted).toBe(false);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('manifest.backup.encrypted is true for encrypted bundle', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'p@ss' });
+    const result = await unpackBundle({ bundlePath, passphrase: 'p@ss' });
+    expect(result.manifest.backup.encrypted).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+
+  it('manifest.databases includes tasks, brain, conduit for project scope', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    const names = result.manifest.databases.map((d) => d.name);
+    expect(names).toContain('tasks');
+    expect(names).toContain('brain');
+    expect(names).toContain('conduit');
+    cleanupStaging(result.stagingDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // BundleError class shape
+  // -------------------------------------------------------------------------
+
+  it('BundleError extends Error with code and codeName properties', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'secret' });
+    let caught: unknown = null;
+    try {
+      await unpackBundle({ bundlePath });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(BundleError);
+    expect(caught).toBeInstanceOf(Error);
+    const be = caught as BundleError;
+    expect(typeof be.code).toBe('number');
+    expect(typeof be.codeName).toBe('string');
+    expect(be.name).toBe('BundleError');
+  });
+
+  // -------------------------------------------------------------------------
+  // Cleanup on error — staging dir is removed when unpack fails
+  // -------------------------------------------------------------------------
+
+  it('does not leave a staging dir behind when decryption fails', async () => {
+    const bundlePath = await createBundle({ encrypt: true, passphrase: 'secret' });
+    const preDirs = fs.readdirSync(os.tmpdir()).filter((n) => n.startsWith('cleo-unpack-'));
+
+    try {
+      await unpackBundle({ bundlePath, passphrase: 'wrong' });
+    } catch {
+      // expected
+    }
+
+    const postDirs = fs.readdirSync(os.tmpdir()).filter((n) => n.startsWith('cleo-unpack-'));
+    const newDirs = postDirs.filter((d) => !preDirs.includes(d));
+    expect(newDirs).toHaveLength(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Warnings are empty for a freshly-packed bundle
+  // -------------------------------------------------------------------------
+
+  it('returns no schema version warnings for a freshly packed bundle', async () => {
+    const bundlePath = await createBundle();
+    const result = await unpackBundle({ bundlePath });
+    // No warnings for a brand-new pack; schema versions may be 'unknown'
+    // so compareSchemaVersions returns null and warnings stays empty.
+    expect(Array.isArray(result.warnings)).toBe(true);
+    cleanupStaging(result.stagingDir);
+  });
+});

package/src/store/__tests__/regenerators.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Tests for T352 dry-run JSON file generators.
+ *
+ * Verifies:
+ *   1. All generators return the correct `filename` field.
+ *   2. No generator writes anything to disk.
+ *   3. Machine-local fields reflect the `projectRoot` argument.
+ *   4. Different `projectRoot` values produce distinguishable output.
+ *   5. `regenerateAllJson` returns all three files.
+ *
+ * @task T352
+ * @epic T311
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  regenerateAllJson,
+  regenerateConfigJson,
+  regenerateProjectContextJson,
+  regenerateProjectInfoJson,
+} from '../regenerators.js';
+
+describe('T352 regenerators (dry-run init JSON generators)', () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t352-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  // ── regenerateConfigJson ────────────────────────────────────────────
+
+  describe('regenerateConfigJson', () => {
+    it('returns filename="config.json"', () => {
+      const result = regenerateConfigJson(tmpRoot);
+      expect(result.filename).toBe('config.json');
+    });
+
+    it('returns a non-null object as content', () => {
+      const result = regenerateConfigJson(tmpRoot);
+      expect(result.content).toBeTypeOf('object');
+      expect(result.content).not.toBeNull();
+    });
+
+    it('does NOT write config.json to disk', () => {
+      regenerateConfigJson(tmpRoot);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo', 'config.json'))).toBe(false);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo'))).toBe(false);
+    });
+
+    it('content has expected top-level keys from createDefaultConfig', () => {
+      const result = regenerateConfigJson(tmpRoot);
+      const content = result.content as Record<string, unknown>;
+      // These keys mirror createDefaultConfig() in scaffold.ts
+      expect(content).toHaveProperty('version');
+      expect(content).toHaveProperty('output');
+      expect(content).toHaveProperty('backup');
+      expect(content).toHaveProperty('hierarchy');
+      expect(content).toHaveProperty('session');
+      expect(content).toHaveProperty('lifecycle');
+    });
+
+    it('is stable across two calls to the same projectRoot (modulo timestamps)', () => {
+      const a = regenerateConfigJson(tmpRoot);
+      const b = regenerateConfigJson(tmpRoot);
+      // All non-timestamp fields must be identical
+      expect(typeof a.content).toBe(typeof b.content);
+      expect((a.content as Record<string, unknown>)['version']).toBe(
+        (b.content as Record<string, unknown>)['version'],
+      );
+    });
+  });
+
+  // ── regenerateProjectInfoJson ───────────────────────────────────────
+
+  describe('regenerateProjectInfoJson', () => {
+    it('returns filename="project-info.json"', () => {
+      const result = regenerateProjectInfoJson(tmpRoot);
+      expect(result.filename).toBe('project-info.json');
+    });
+
+    it('returns a non-null object as content', () => {
+      const result = regenerateProjectInfoJson(tmpRoot);
+      expect(result.content).toBeTypeOf('object');
+      expect(result.content).not.toBeNull();
+    });
+
+    it('does NOT write project-info.json to disk', () => {
+      regenerateProjectInfoJson(tmpRoot);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo', 'project-info.json'))).toBe(false);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo'))).toBe(false);
+    });
+
+    it('content includes required machine-local fields', () => {
+      const result = regenerateProjectInfoJson(tmpRoot);
+      const content = result.content as Record<string, unknown>;
+      expect(content).toHaveProperty('projectHash');
+      expect(content).toHaveProperty('projectId');
+      expect(content).toHaveProperty('cleoVersion');
+      expect(content).toHaveProperty('lastUpdated');
+      expect(content).toHaveProperty('schemas');
+    });
+
+    it('projectHash reflects the resolved projectRoot path', () => {
+      const result = regenerateProjectInfoJson(tmpRoot);
+      const content = result.content as Record<string, unknown>;
+      // projectHash must be a non-empty string (SHA-256 prefix)
+      expect(typeof content['projectHash']).toBe('string');
+      expect((content['projectHash'] as string).length).toBeGreaterThan(0);
+    });
+
+    it('produces different projectHash for different projectRoots', () => {
+      const root2 = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t352-other-'));
+      try {
+        const a = regenerateProjectInfoJson(tmpRoot);
+        const b = regenerateProjectInfoJson(root2);
+        expect((a.content as Record<string, unknown>)['projectHash']).not.toBe(
+          (b.content as Record<string, unknown>)['projectHash'],
+        );
+      } finally {
+        fs.rmSync(root2, { recursive: true, force: true });
+      }
+    });
+
+    it('schemas block contains config, sqlite, and projectContext keys', () => {
+      const result = regenerateProjectInfoJson(tmpRoot);
+      const schemas = (result.content as Record<string, unknown>)['schemas'] as Record<
+        string,
+        unknown
+      >;
+      expect(schemas).toHaveProperty('config');
+      expect(schemas).toHaveProperty('sqlite');
+      expect(schemas).toHaveProperty('projectContext');
+    });
+  });
+
+  // ── regenerateProjectContextJson ───────────────────────────────────
+
+  describe('regenerateProjectContextJson', () => {
+    it('returns filename="project-context.json"', () => {
+      const result = regenerateProjectContextJson(tmpRoot);
+      expect(result.filename).toBe('project-context.json');
+    });
+
+    it('returns a non-null object as content', () => {
+      const result = regenerateProjectContextJson(tmpRoot);
+      expect(result.content).toBeTypeOf('object');
+      expect(result.content).not.toBeNull();
+    });
+
+    it('does NOT write project-context.json to disk', () => {
+      regenerateProjectContextJson(tmpRoot);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo', 'project-context.json'))).toBe(false);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo'))).toBe(false);
+    });
+
+    it('content has required schema fields from detectProjectType', () => {
+      const result = regenerateProjectContextJson(tmpRoot);
+      const content = result.content as Record<string, unknown>;
+      expect(content).toHaveProperty('schemaVersion');
+      expect(content).toHaveProperty('detectedAt');
+      expect(content).toHaveProperty('projectTypes');
+      expect(content).toHaveProperty('monorepo');
+    });
+
+    it('detectedAt is a valid ISO timestamp', () => {
+      const result = regenerateProjectContextJson(tmpRoot);
+      const content = result.content as Record<string, unknown>;
+      const detectedAt = content['detectedAt'] as string;
+      expect(typeof detectedAt).toBe('string');
+      const parsed = new Date(detectedAt);
+      expect(Number.isNaN(parsed.getTime())).toBe(false);
+    });
+  });
+
+  // ── regenerateAllJson ───────────────────────────────────────────────
+
+  describe('regenerateAllJson', () => {
+    it('returns all three files', () => {
+      const all = regenerateAllJson(tmpRoot);
+      expect(all.config.filename).toBe('config.json');
+      expect(all.projectInfo.filename).toBe('project-info.json');
+      expect(all.projectContext.filename).toBe('project-context.json');
+    });
+
+    it('does NOT write any files to disk', () => {
+      regenerateAllJson(tmpRoot);
+      expect(fs.existsSync(path.join(tmpRoot, '.cleo'))).toBe(false);
+    });
+
+    it('all three content values are non-null objects', () => {
+      const all = regenerateAllJson(tmpRoot);
+      for (const file of [all.config, all.projectInfo, all.projectContext]) {
+        expect(file.content).toBeTypeOf('object');
+        expect(file.content).not.toBeNull();
+      }
+    });
+  });
+
+  // ── Cross-projectRoot differentiation ──────────────────────────────
+
+  describe('cross-projectRoot differentiation', () => {
+    it('regenerated project-info differs across different projectRoots', () => {
+      const root2 = fs.mkdtempSync(path.join(os.tmpdir(), 'cleo-t352-other-'));
+      try {
+        const a = regenerateProjectInfoJson(tmpRoot);
+        const b = regenerateProjectInfoJson(root2);
+        // At minimum the projectHash must differ (different paths)
+        expect(JSON.stringify(a.content)).not.toBe(JSON.stringify(b.content));
+      } finally {
+        fs.rmSync(root2, { recursive: true, force: true });
+      }
+    });
+  });
+
+  // ── Stability / shape ───────────────────────────────────────────────
+
+  describe('stability', () => {
+    it('config content has the same type shape across two calls', () => {
+      const a = regenerateConfigJson(tmpRoot);
+      const b = regenerateConfigJson(tmpRoot);
+      expect(typeof a.content).toBe(typeof b.content);
+      expect(Object.keys(a.content as Record<string, unknown>).sort()).toEqual(
+        Object.keys(b.content as Record<string, unknown>).sort(),
+      );
+    });
+  });
+});