@celilo/cli 0.3.30-alpha.0 → 0.4.0-alpha.0

package/src/services/cross-module-read.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Tests for cross-module-read materialization + atomic write-back.
+ *
+ * Read side: verify that materializeCrossModuleRoot mirrors every
+ * OTHER deployed module's terraform/ dir + writes an index.json.
+ * Write side: verify applyCrossModuleWriteRoot atomically rotates
+ * staged dirs into live storage, and rolls back on mid-loop failure.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { modules } from '../db/schema';
+import type { ModuleManifest } from '../manifest/schema';
+import {
+  type CrossModuleIndex,
+  applyCrossModuleWriteRoot,
+  materializeCrossModuleRoot,
+  moduleHasCrossModuleRead,
+} from './cross-module-read';
+
+function buildManifest(caps: Array<{ name: string; version: string }>): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'm',
+    name: 'm',
+    version: '0.0.1',
+    requires: { capabilities: caps },
+  } as ModuleManifest;
+}
+
+describe('moduleHasCrossModuleRead', () => {
+  it('returns false for manifests with no capabilities', () => {
+    expect(moduleHasCrossModuleRead(buildManifest([]))).toBe(false);
+  });
+
+  it('returns false for manifests with other capabilities', () => {
+    expect(moduleHasCrossModuleRead(buildManifest([{ name: 'public_web', version: '^3.0' }]))).toBe(
+      false,
+    );
+  });
+
+  it('returns true when cross_module_read is declared in requires', () => {
+    expect(
+      moduleHasCrossModuleRead(buildManifest([{ name: 'cross_module_read', version: '^1.0' }])),
+    ).toBe(true);
+  });
+
+  it('returns true when cross_module_read is declared in optional', () => {
+    const manifest = {
+      ...buildManifest([]),
+      optional: { capabilities: [{ name: 'cross_module_read', version: '^1.0' }] },
+    } as ModuleManifest;
+    expect(moduleHasCrossModuleRead(manifest)).toBe(true);
+  });
+});
+
+describe('materializeCrossModuleRoot', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-xmr-test-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    process.env.CELILO_DATA_DIR = dir;
+    await runMigrations(process.env.CELILO_DB_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_DATA_DIR = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function plantDeployedModule(id: string, version: string, tfstateContent: string): void {
+    const db = getDb();
+    db.insert(modules)
+      .values({
+        id,
+        name: id,
+        version,
+        sourcePath: join(dir, 'sources', id),
+        manifestData: { id, name: id, version, celilo_contract: '1.0', requires: {} } as Record<
+          string,
+          unknown
+        >,
+      })
+      .run();
+    const tfDir = join(dir, 'modules', id, 'generated', 'terraform');
+    mkdirSync(tfDir, { recursive: true });
+    writeFileSync(join(tfDir, 'terraform.tfstate'), tfstateContent);
+  }
+
+  it("mirrors every other deployed module's terraform/ + writes index.json", () => {
+    plantDeployedModule('homebridge', '0.1.0', '{"state":"homebridge"}');
+    plantDeployedModule('caddy', '0.2.0', '{"state":"caddy"}');
+    plantDeployedModule('celilo-mgmt', '0.3.0', '{"state":"mgmt"}');
+
+    const root = join(dir, 'cross-module-root');
+    materializeCrossModuleRoot(root, 'celilo-mgmt');
+
+    // index.json lists the OTHER modules, not celilo-mgmt
+    const index: CrossModuleIndex = JSON.parse(readFileSync(join(root, 'index.json'), 'utf-8'));
+    expect(index.schemaVersion).toBe('1.0');
+    expect(index.modules.map((m) => m.id).sort()).toEqual(['caddy', 'homebridge']);
+
+    // Mirrored TF state is reachable + matches the live content.
+    const mirroredHomebridge = readFileSync(
+      join(root, 'modules', 'homebridge', 'terraform', 'terraform.tfstate'),
+      'utf-8',
+    );
+    expect(mirroredHomebridge).toBe('{"state":"homebridge"}');
+    expect(existsSync(join(root, 'modules', 'celilo-mgmt'))).toBe(false);
+  });
+
+  it('mirrors state + lock file but EXCLUDES the .terraform provider cache (ISS-0015)', () => {
+    plantDeployedModule('caddy', '0.2.0', '{"state":"caddy"}');
+    // Plant a realistic terraform dir: state + lock file (must travel) plus a
+    // .terraform/providers/ binary (must NOT — re-fetchable, ~19 MB each).
+    const tfDir = join(dir, 'modules', 'caddy', 'generated', 'terraform');
+    writeFileSync(join(tfDir, '.terraform.lock.hcl'), 'provider "telmate/proxmox" {}');
+    const providerDir = join(tfDir, '.terraform', 'providers', 'registry.terraform.io', 'telmate');
+    mkdirSync(providerDir, { recursive: true });
+    writeFileSync(join(providerDir, 'terraform-provider-proxmox'), 'BINARY'.repeat(1000));
+
+    const root = join(dir, 'cross-module-root');
+    materializeCrossModuleRoot(root, 'celilo-mgmt');
+
+    const mirrored = join(root, 'modules', 'caddy', 'terraform');
+    expect(existsSync(join(mirrored, 'terraform.tfstate'))).toBe(true);
+    expect(existsSync(join(mirrored, '.terraform.lock.hcl'))).toBe(true);
+    // The provider cache must not be in the envelope.
+    expect(existsSync(join(mirrored, '.terraform'))).toBe(false);
+  });
+
+  it('skips modules with no terraform.tfstate (not deployed)', () => {
+    plantDeployedModule('caddy', '0.2.0', '{"state":"caddy"}');
+    // imported-but-not-deployed: row exists but no tf state on disk
+    const db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'half-installed',
+        name: 'half-installed',
+        version: '0.0.1',
+        sourcePath: join(dir, 'sources', 'half-installed'),
+        manifestData: {} as Record<string, unknown>,
+      })
+      .run();
+
+    const root = join(dir, 'cross-module-root');
+    materializeCrossModuleRoot(root, 'celilo-mgmt');
+
+    const index: CrossModuleIndex = JSON.parse(readFileSync(join(root, 'index.json'), 'utf-8'));
+    expect(index.modules.map((m) => m.id)).toEqual(['caddy']);
+  });
+
+  it('produces an empty index when no other modules are deployed', () => {
+    plantDeployedModule('celilo-mgmt', '0.3.0', '{}');
+    const root = join(dir, 'cross-module-root');
+    materializeCrossModuleRoot(root, 'celilo-mgmt');
+    const index: CrossModuleIndex = JSON.parse(readFileSync(join(root, 'index.json'), 'utf-8'));
+    expect(index.modules).toHaveLength(0);
+  });
+});
+
+describe('applyCrossModuleWriteRoot', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-xmw-test-'));
+    process.env.CELILO_DATA_DIR = dir;
+  });
+
+  afterEach(() => {
+    process.env.CELILO_DATA_DIR = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function stage(stagingRoot: string, moduleId: string, fileName: string, content: string): void {
+    const tfDir = join(stagingRoot, 'modules', moduleId, 'terraform');
+    mkdirSync(tfDir, { recursive: true });
+    writeFileSync(join(tfDir, fileName), content);
+  }
+
+  function plantLive(moduleId: string, fileName: string, content: string): void {
+    const tfDir = join(dir, 'modules', moduleId, 'generated', 'terraform');
+    mkdirSync(tfDir, { recursive: true });
+    writeFileSync(join(tfDir, fileName), content);
+  }
+
+  function readLive(moduleId: string, fileName: string): string | null {
+    const p = join(dir, 'modules', moduleId, 'generated', 'terraform', fileName);
+    if (!existsSync(p)) return null;
+    return readFileSync(p, 'utf-8');
+  }
+
+  it('replaces live tf state with staged content', () => {
+    plantLive('caddy', 'terraform.tfstate', 'old-state');
+    const stagingRoot = join(dir, 'staging');
+    mkdirSync(stagingRoot, { recursive: true });
+    stage(stagingRoot, 'caddy', 'terraform.tfstate', 'new-state');
+
+    const result = applyCrossModuleWriteRoot(stagingRoot);
+    expect(result.applied).toEqual(['caddy']);
+    expect(result.skipped).toEqual([]);
+    expect(readLive('caddy', 'terraform.tfstate')).toBe('new-state');
+
+    // The .cross-module-restore-old sibling should be cleaned up.
+    expect(
+      existsSync(join(dir, 'modules', 'caddy', 'generated', 'terraform.cross-module-restore-old')),
+    ).toBe(false);
+  });
+
+  it('creates a fresh live dir when none existed before', () => {
+    const stagingRoot = join(dir, 'staging');
+    mkdirSync(stagingRoot, { recursive: true });
+    stage(stagingRoot, 'new-module', 'terraform.tfstate', 'fresh');
+
+    const result = applyCrossModuleWriteRoot(stagingRoot);
+    expect(result.applied).toEqual(['new-module']);
+    expect(readLive('new-module', 'terraform.tfstate')).toBe('fresh');
+  });
+
+  it('reports skipped modules whose staged subtree has no terraform/ dir', () => {
+    const stagingRoot = join(dir, 'staging');
+    mkdirSync(join(stagingRoot, 'modules', 'orphan'), { recursive: true });
+    const result = applyCrossModuleWriteRoot(stagingRoot);
+    expect(result.skipped).toEqual(['orphan']);
+    expect(result.applied).toEqual([]);
+  });
+
+  it('is a no-op when staging root has no modules/ dir', () => {
+    const stagingRoot = join(dir, 'empty-staging');
+    mkdirSync(stagingRoot, { recursive: true });
+    const result = applyCrossModuleWriteRoot(stagingRoot);
+    expect(result.applied).toEqual([]);
+    expect(result.skipped).toEqual([]);
+  });
+});

package/src/services/cross-module-read.ts

@@ -0,0 +1,232 @@
+/**
+ * Materialization helpers for the `cross_module_read` privilege.
+ *
+ * Phase 2 of v2/SYSTEM_BACKUP_TERRAFORM_STATE.md. When an allow-listed
+ * module (today: only celilo-mgmt) declares `cross_module_read` in its
+ * `requires.capabilities`, its on_backup hook receives a
+ * `cross_module_root` input pointing at a directory mirroring OTHER
+ * modules' generated/terraform/ trees plus an index.json enumerating
+ * deployed modules. On restore, the symmetric `cross_module_write_root`
+ * input gives the hook a staging dir that the framework atomically
+ * applies back onto live storage.
+ *
+ * The privilege is enforced in two places:
+ *   1. validatePrivilegedCapabilities (manifest/validate.ts) — refuses
+ *      modules outside the allow-list at import time.
+ *   2. moduleHasCrossModuleRead (here) — returns true only for manifests
+ *      that actually declared the requirement. Belt-and-suspenders so a
+ *      bug in import-time validation can't silently grant the privilege
+ *      to a module that didn't ask.
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { getModuleStoragePath } from '../config/paths';
+import { getDb } from '../db/client';
+import { modules } from '../db/schema';
+import type { ModuleManifest } from '../manifest/schema';
+
+const CROSS_MODULE_READ_NAME = 'cross_module_read';
+
+/**
+ * True if the manifest declares cross_module_read (in requires or optional).
+ * Note: this DOES NOT enforce the allow-list — that's the validator's job
+ * at import time. By the time we're calling this at backup/restore time,
+ * the module is in the DB, which means it passed validation.
+ */
+export function moduleHasCrossModuleRead(manifest: ModuleManifest): boolean {
+  const declaresIn = (caps: { name: string }[] | undefined): boolean =>
+    (caps ?? []).some((c) => c.name === CROSS_MODULE_READ_NAME);
+  return declaresIn(manifest.requires?.capabilities) || declaresIn(manifest.optional?.capabilities);
+}
+
+export interface CrossModuleIndexEntry {
+  id: string;
+  version: string;
+  terraformStateDir: string; // relative path inside cross_module_root
+}
+
+export interface CrossModuleIndex {
+  /** Schema version of the index.json shape — bumps independently of the envelope schema. */
+  schemaVersion: '1.0';
+  generatedAt: string; // ISO 8601
+  modules: CrossModuleIndexEntry[];
+}
+
+/**
+ * Populate a read-only mirror of every deployed module's
+ * generated/terraform/ tree under `<rootDir>/modules/<id>/terraform/`,
+ * plus an index.json describing them. Excludes the calling module
+ * itself (the hook reads ITS OWN data via the normal backup_dir
+ * mechanism, not via this mirror).
+ *
+ * Returns the path to the root directory — callers pass this to the
+ * hook as the `cross_module_root` input.
+ */
+export function materializeCrossModuleRoot(rootDir: string, excludeModuleId: string): string {
+  mkdirSync(rootDir, { recursive: true });
+  const modulesDir = join(rootDir, 'modules');
+  mkdirSync(modulesDir, { recursive: true });
+
+  const db = getDb();
+  const allModules = db.select().from(modules).all();
+  const storageRoot = getModuleStoragePath();
+
+  const entries: CrossModuleIndexEntry[] = [];
+  for (const mod of allModules) {
+    if (mod.id === excludeModuleId) continue;
+
+    const liveTfDir = join(storageRoot, mod.id, 'generated', 'terraform');
+    if (!existsSync(liveTfDir)) continue; // not deployed (no TF state to mirror)
+
+    const mirroredTfDir = join(modulesDir, mod.id, 'terraform');
+    mkdirSync(mirroredTfDir, { recursive: true });
+    copyDirShallow(liveTfDir, mirroredTfDir);
+
+    entries.push({
+      id: mod.id,
+      version: mod.version,
+      terraformStateDir: `modules/${mod.id}/terraform`,
+    });
+  }
+
+  const index: CrossModuleIndex = {
+    schemaVersion: '1.0',
+    generatedAt: new Date().toISOString(),
+    modules: entries,
+  };
+  writeFileSync(join(rootDir, 'index.json'), JSON.stringify(index, null, 2));
+
+  return rootDir;
+}
+
+/**
+ * After on_restore returns successfully, atomically apply each module's
+ * staged terraform/ subtree back to its live storage path.
+ *
+ * Atomicity strategy:
+ *   - Each module's restore happens as a rename(live → live.old) + rename(staged → live).
+ *   - On any error mid-loop, rename(live.old → live) for the modules already touched.
+ *   - At the end of a successful sweep, rm -rf the live.old siblings.
+ *
+ * If the staging dir is empty or doesn't exist, this is a no-op.
+ */
+export interface ApplyResult {
+  applied: string[]; // module IDs whose state was replaced
+  skipped: string[]; // module IDs whose staged dir was empty/missing
+}
+
+export function applyCrossModuleWriteRoot(stagingRootDir: string): ApplyResult {
+  const stagingModulesDir = join(stagingRootDir, 'modules');
+  if (!existsSync(stagingModulesDir)) {
+    return { applied: [], skipped: [] };
+  }
+
+  const storageRoot = getModuleStoragePath();
+  const applied: string[] = [];
+  const skipped: string[] = [];
+  const rollback: Array<{ liveDir: string; backupDir: string }> = [];
+
+  try {
+    for (const moduleIdEntry of readdirSync(stagingModulesDir, { withFileTypes: true })) {
+      if (!moduleIdEntry.isDirectory()) continue;
+      const moduleId = moduleIdEntry.name;
+      const stagedTfDir = join(stagingModulesDir, moduleId, 'terraform');
+
+      if (!existsSync(stagedTfDir)) {
+        skipped.push(moduleId);
+        continue;
+      }
+
+      const liveGeneratedDir = join(storageRoot, moduleId, 'generated');
+      mkdirSync(liveGeneratedDir, { recursive: true });
+      const liveTfDir = join(liveGeneratedDir, 'terraform');
+      const backupTfDir = `${liveTfDir}.cross-module-restore-old`;
+
+      // Move the current live dir aside (if any) so we can roll back on
+      // failure. The two renames + the staged-to-live rename together are
+      // as close to atomic as POSIX gives us.
+      if (existsSync(liveTfDir)) {
+        renameSync(liveTfDir, backupTfDir);
+      }
+      try {
+        renameSync(stagedTfDir, liveTfDir);
+      } catch (err) {
+        // staged → live failed; restore the old dir if we moved it aside.
+        if (existsSync(backupTfDir)) {
+          renameSync(backupTfDir, liveTfDir);
+        }
+        throw err;
+      }
+      rollback.push({ liveDir: liveTfDir, backupDir: backupTfDir });
+      applied.push(moduleId);
+    }
+  } catch (err) {
+    // Roll back every successful module first, then rethrow.
+    for (const entry of rollback) {
+      try {
+        // Remove the freshly-restored live dir
+        rmSync(entry.liveDir, { recursive: true, force: true });
+        if (existsSync(entry.backupDir)) {
+          renameSync(entry.backupDir, entry.liveDir);
+        }
+      } catch {
+        // Best-effort rollback; the underlying error matters more.
+      }
+    }
+    throw err;
+  }
+
+  // Success — clean up the backup dirs.
+  for (const entry of rollback) {
+    try {
+      if (existsSync(entry.backupDir)) {
+        rmSync(entry.backupDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Stale .cross-module-restore-old dir is harmless; will be cleaned
+      // on next restore.
+    }
+  }
+
+  return { applied, skipped };
+}
+
+/**
+ * Recursive copy of every file in `srcDir` into `destDir`, EXCEPT the
+ * `.terraform/` cache directory. Mirrors the exact tree shape (no flattening).
+ *
+ * What travels: the state itself — terraform.tfstate, terraform.tfstate.backup,
+ * and the provider lock file `.terraform.lock.hcl` (a top-level FILE, not inside
+ * `.terraform/`). What does NOT: `.terraform/` — the provider binary cache
+ * (~19 MB per proxmox provider) and the module cache, both reconstructible with
+ * `terraform init` on restore. Including it bloated the backup envelope by ~95 MB
+ * across the fleet and dragged the S3 upload past 12 minutes (ISS-0015). Restore
+ * re-fetches providers via `terraform init`.
+ */
+function copyDirShallow(srcDir: string, destDir: string): void {
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    // Skip the terraform provider/module cache — re-fetchable, not state.
+    if (entry.isDirectory() && entry.name === '.terraform') continue;
+
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      mkdirSync(destPath, { recursive: true });
+      copyDirShallow(srcPath, destPath);
+    } else if (entry.isFile()) {
+      copyFileSync(srcPath, destPath);
+    }
+    // Symlinks/sockets/etc are skipped intentionally — TF state should
+    // never contain them, and silently following symlinks across a
+    // privilege boundary is a footgun.
+  }
+}

package/src/services/deploy-validation.ts

@@ -11,6 +11,7 @@ import { and, eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { capabilities, moduleConfigs, modules } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
+import { isPrivilegedCapability } from '../manifest/validate';
 import { generateTemplates } from '../templates/generator';
 import { findMissingSecrets } from './config-interview';
 import { buildModuleFromSource, getModuleBuildStatus, verifyArtifactsExist } from './module-build';
@@ -184,6 +185,12 @@ async function findMissingCapabilities(
   const missing: string[] = [];
 
   for (const cap of required) {
+    // Framework-granted privileges (e.g. cross_module_read) aren't
+    // provider-backed — they're gated by the allow-list at import time,
+    // not satisfied by deploying another module. Skip them here.
+    if (isPrivilegedCapability(cap.name)) {
+      continue;
+    }
     const isProvided = await isCapabilityProvided(cap.name, db);
     if (!isProvided) {
       missing.push(cap.name);