@celilo/cli 0.1.0

package/src/ipam/auto-allocator.ts

@@ -0,0 +1,270 @@
+/**
+ * IPAM Auto-Allocator
+ * Automatic VMID and IP allocation for container-based modules
+ *
+ * - Modules declare zone, Celilo auto-allocates vmid/IP
+ * - Sequential allocation with reservation support
+ * - Persistent storage in ip_allocations table
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { ipAllocations } from '../db/schema';
+
+export interface IpamAllocation {
+  moduleId: string;
+  vmid: number;
+  containerIp: string;
+  zone: string;
+}
+
+/**
+ * Get existing allocation for module
+ *
+ * @param moduleId - Module identifier
+ * @param db - Drizzle database instance
+ * @returns Existing allocation or null
+ */
+export function getAllocation(moduleId: string, db: DbClient): IpamAllocation | null {
+  const allocation = db
+    .select()
+    .from(ipAllocations)
+    .where(eq(ipAllocations.moduleId, moduleId))
+    .get();
+
+  if (!allocation) {
+    return null;
+  }
+
+  return {
+    moduleId: allocation.moduleId,
+    vmid: allocation.vmid,
+    containerIp: allocation.containerIp,
+    zone: allocation.zone,
+  };
+}
+
+/**
+ * Allocate VMID from available pool
+ *
+ * Algorithm:
+ * - Start from 200 (100-199 reserved for infrastructure)
+ * - Skip already allocated VMIDs
+ * - Skip reserved VMID ranges
+ * - Return first available VMID
+ *
+ * @param db - SQLite database instance (for raw queries)
+ * @returns Next available VMID
+ * @throws Error if no VMIDs available
+ */
+function allocateVMID(db: DbClient['$client']): number {
+  // Get all allocated VMIDs
+  const allocatedRows = db.prepare('SELECT vmid FROM ip_allocations').all() as Array<{
+    vmid: number;
+  }>;
+
+  // Get all reserved VMIDs (including ranges)
+  const reservedRows = db.prepare('SELECT vmid FROM vmid_reservations').all() as Array<{
+    vmid: number;
+  }>;
+
+  const used = new Set<number>();
+
+  // Add allocated VMIDs
+  for (const row of allocatedRows) {
+    used.add(row.vmid);
+  }
+
+  // Add reserved VMIDs
+  for (const row of reservedRows) {
+    used.add(row.vmid);
+  }
+
+  // Find first available VMID starting from 200
+  const START_VMID = 200;
+  const MAX_VMID = 999999999;
+
+  for (let candidate = START_VMID; candidate <= MAX_VMID; candidate++) {
+    if (!used.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error('No available VMIDs in pool (200-999999999)');
+}
+
+/**
+ * Parse CIDR subnet to get network address and prefix
+ *
+ * @param subnet - CIDR subnet (e.g., "10.0.10.0/24")
+ * @returns Parsed subnet components
+ */
+function parseSubnet(subnet: string): {
+  octets: number[];
+  prefix: number;
+} {
+  const [network, prefixStr] = subnet.split('/');
+  const octets = network.split('.').map(Number);
+  const prefix = Number.parseInt(prefixStr, 10);
+
+  return { octets, prefix };
+}
+
+/**
+ * Allocate IP address from zone subnet
+ *
+ * Algorithm:
+ * - Get zone subnet from system config
+ * - Parse CIDR to get network range
+ * - Skip .0 (network), .1 (gateway), .255 (broadcast)
+ * - Start allocation from .10 (reserve .2-.9 for infrastructure)
+ * - Skip already allocated IPs
+ * - Skip reserved IP ranges
+ * - Return first available IP
+ *
+ * @param zone - Network zone (dmz, app, secure)
+ * @param db - SQLite database instance
+ * @returns Next available IP address
+ * @throws Error if no IPs available or subnet not configured
+ */
+function allocateIP(zone: string, db: DbClient['$client']): string {
+  // Get zone subnet from system config
+  const subnetRow = db
+    .prepare('SELECT value FROM system_config WHERE key = ?')
+    .get(`network.${zone}.subnet`) as { value: string } | undefined;
+
+  if (!subnetRow) {
+    throw new Error(
+      `Zone subnet not configured: network.${zone}.subnet\n` +
+        `Run: celilo system config set network.${zone}.subnet <cidr>`,
+    );
+  }
+
+  const subnet = subnetRow.value;
+  const { octets, prefix } = parseSubnet(subnet);
+  const [a, b, c] = octets;
+
+  // IP allocation range: .10 to .254
+  // .0 = network address
+  // .1 = gateway (reserved)
+  // .2-.9 = infrastructure (reserved for manual use)
+  // .10-.254 = auto-allocation pool
+  // .255 = broadcast address
+  const START_OCTET = 10;
+  const END_OCTET = 254;
+
+  // Get all allocated IPs in this zone
+  const allocatedRows = db
+    .prepare('SELECT container_ip FROM ip_allocations WHERE zone = ?')
+    .all(zone) as Array<{ container_ip: string }>;
+
+  // Get all reserved IPs in this zone
+  const reservedRows = db
+    .prepare('SELECT ip_start, ip_end FROM ip_reservations WHERE zone = ?')
+    .all(zone) as Array<{ ip_start: string; ip_end: string | null }>;
+
+  const used = new Set<string>();
+
+  // Add allocated IPs (strip CIDR suffix for comparison)
+  for (const row of allocatedRows) {
+    const ipOnly = row.container_ip.split('/')[0];
+    used.add(ipOnly);
+  }
+
+  // Add reserved IPs (including ranges)
+  for (const row of reservedRows) {
+    if (row.ip_end) {
+      // Handle IP range: "10.0.10.1-10.0.10.9"
+      const startOctet = Number.parseInt(row.ip_start.split('.')[3], 10);
+      const endOctet = Number.parseInt(row.ip_end.split('.')[3], 10);
+
+      for (let i = startOctet; i <= endOctet; i++) {
+        used.add(`${a}.${b}.${c}.${i}`);
+      }
+    } else {
+      // Single IP reservation
+      used.add(row.ip_start);
+    }
+  }
+
+  // Find first available IP
+  for (let octet = START_OCTET; octet <= END_OCTET; octet++) {
+    const candidate = `${a}.${b}.${c}.${octet}`;
+    if (!used.has(candidate)) {
+      return `${candidate}/${prefix}`;
+    }
+  }
+
+  throw new Error(
+    `No available IPs in zone ${zone} subnet ${subnet}\n` +
+      `Allocated: ${allocatedRows.length}, Reserved: ${reservedRows.length}`,
+  );
+}
+
+/**
+ * Allocate VMID and IP for module
+ *
+ * Main allocation function - coordinates VMID and IP allocation
+ * and stores result in database.
+ *
+ * @param moduleId - Module identifier
+ * @param zone - Network zone (dmz, app, secure)
+ * @param drizzleDb - Drizzle database instance (for inserts)
+ * @param sqliteDb - SQLite database instance (for raw queries)
+ * @returns Allocated VMID and IP
+ */
+export async function allocateForModule(
+  moduleId: string,
+  zone: string,
+  drizzleDb: DbClient,
+  sqliteDb: DbClient['$client'],
+): Promise<IpamAllocation> {
+  // Check if already allocated
+  const existing = getAllocation(moduleId, drizzleDb);
+  if (existing) {
+    return existing;
+  }
+
+  // Allocate VMID
+  const vmid = allocateVMID(sqliteDb);
+
+  // Allocate IP from zone subnet
+  const containerIp = allocateIP(zone, sqliteDb);
+
+  // Store allocation
+  await drizzleDb.insert(ipAllocations).values({
+    moduleId,
+    vmid,
+    containerIp,
+    zone: zone as 'dmz' | 'app' | 'secure' | 'internal',
+  });
+
+  return {
+    moduleId,
+    vmid,
+    containerIp,
+    zone,
+  };
+}
+
+/**
+ * Deallocate VMID and IP for module
+ *
+ * Removes allocation from database, making VMID and IP available
+ * for future allocations.
+ *
+ * @param moduleId - Module identifier
+ * @param db - Drizzle database instance
+ * @returns True if allocation was removed, false if none existed
+ */
+export async function deallocateForModule(moduleId: string, db: DbClient): Promise<boolean> {
+  // Check if allocation exists before deleting
+  const existing = getAllocation(moduleId, db);
+  if (!existing) {
+    return false;
+  }
+
+  await db.delete(ipAllocations).where(eq(ipAllocations.moduleId, moduleId));
+
+  return true;
+}

package/src/ipam/subnet-parser.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  addCIDR,
+  generateIPsInSubnet,
+  isIPInRange,
+  isInSubnet,
+  parseSubnet,
+  stripCIDR,
+} from './subnet-parser';
+
+describe('Subnet Parser', () => {
+  describe('parseSubnet', () => {
+    test('should parse valid /24 subnet', () => {
+      const result = parseSubnet('10.0.10.0/24');
+
+      expect(result.network).toBe('10.0.10.0');
+      expect(result.maskBits).toBe(24);
+      expect(result.octets).toEqual([10, 0, 10, 0]);
+      expect(result.firstUsableIp).toBe('10.0.10.10');
+      expect(result.lastUsableIp).toBe('10.0.10.254');
+    });
+
+    test('should reject invalid subnet format', () => {
+      expect(() => parseSubnet('invalid')).toThrow('Invalid subnet format');
+      expect(() => parseSubnet('10.0.10.0')).toThrow('Invalid subnet format');
+      expect(() => parseSubnet('10.0.10.0/abc')).toThrow('Invalid subnet format');
+    });
+
+    test('should reject invalid IP address', () => {
+      expect(() => parseSubnet('256.0.10.0/24')).toThrow('Invalid IP address');
+      expect(() => parseSubnet('10.0.10/24')).toThrow('Invalid IP address');
+    });
+
+    test('should reject subnets smaller than /24', () => {
+      expect(() => parseSubnet('10.0.10.0/25')).toThrow('Subnet too small');
+      expect(() => parseSubnet('10.0.10.0/30')).toThrow('Subnet too small');
+    });
+  });
+
+  describe('stripCIDR', () => {
+    test('should strip CIDR mask', () => {
+      expect(stripCIDR('10.0.10.10/24')).toBe('10.0.10.10');
+      expect(stripCIDR('192.168.1.1/16')).toBe('192.168.1.1');
+    });
+
+    test('should return IP unchanged if no mask', () => {
+      expect(stripCIDR('10.0.10.10')).toBe('10.0.10.10');
+    });
+  });
+
+  describe('addCIDR', () => {
+    test('should add CIDR mask', () => {
+      expect(addCIDR('10.0.10.10', 24)).toBe('10.0.10.10/24');
+      expect(addCIDR('192.168.1.1', 16)).toBe('192.168.1.1/16');
+    });
+  });
+
+  describe('isInSubnet', () => {
+    test('should return true for IP in subnet', () => {
+      expect(isInSubnet('10.0.10.50/24', '10.0.10.0/24')).toBe(true);
+      expect(isInSubnet('10.0.10.10/24', '10.0.10.0/24')).toBe(true);
+      expect(isInSubnet('10.0.10.254/24', '10.0.10.0/24')).toBe(true);
+    });
+
+    test('should return false for IP outside subnet', () => {
+      expect(isInSubnet('10.0.11.50/24', '10.0.10.0/24')).toBe(false);
+      expect(isInSubnet('10.0.20.10/24', '10.0.10.0/24')).toBe(false);
+      expect(isInSubnet('192.168.1.1/24', '10.0.10.0/24')).toBe(false);
+    });
+  });
+
+  describe('generateIPsInSubnet', () => {
+    test('should generate IPs from .10 to .254', () => {
+      const ips = Array.from(generateIPsInSubnet('10.0.10.0/24'));
+
+      expect(ips[0]).toBe('10.0.10.10/24'); // First usable (reserve .1-.9)
+      expect(ips[ips.length - 1]).toBe('10.0.10.254/24'); // Last usable
+      expect(ips.length).toBe(245); // 254 - 10 + 1 = 245 IPs
+    });
+
+    test('should generate correct IPs for different subnet', () => {
+      const ips = Array.from(generateIPsInSubnet('192.168.1.0/24'));
+
+      expect(ips[0]).toBe('192.168.1.10/24');
+      expect(ips[ips.length - 1]).toBe('192.168.1.254/24');
+    });
+  });
+
+  describe('isIPInRange', () => {
+    test('should match single IP reservation', () => {
+      expect(isIPInRange('10.0.10.50', '10.0.10.50', null)).toBe(true);
+      expect(isIPInRange('10.0.10.51', '10.0.10.50', null)).toBe(false);
+    });
+
+    test('should match IP range reservation', () => {
+      expect(isIPInRange('10.0.10.50', '10.0.10.50', '10.0.10.60')).toBe(true);
+      expect(isIPInRange('10.0.10.55', '10.0.10.50', '10.0.10.60')).toBe(true);
+      expect(isIPInRange('10.0.10.60', '10.0.10.50', '10.0.10.60')).toBe(true);
+      expect(isIPInRange('10.0.10.49', '10.0.10.50', '10.0.10.60')).toBe(false);
+      expect(isIPInRange('10.0.10.61', '10.0.10.50', '10.0.10.60')).toBe(false);
+    });
+
+    test('should handle IPs with CIDR notation', () => {
+      expect(isIPInRange('10.0.10.50/24', '10.0.10.50', '10.0.10.60')).toBe(true);
+    });
+  });
+});

package/src/ipam/subnet-parser.ts

@@ -0,0 +1,136 @@
+/**
+ * Subnet parsing utilities for IPAM system
+ * Handles CIDR notation and IP address operations
+ */
+
+export interface SubnetInfo {
+  network: string;
+  maskBits: number;
+  octets: [number, number, number, number];
+  firstUsableIp: string;
+  lastUsableIp: string;
+  totalHosts: number;
+}
+
+/**
+ * Parse subnet CIDR notation (e.g., "10.0.10.0/24")
+ * Returns network information needed for IP allocation
+ */
+export function parseSubnet(subnet: string): SubnetInfo {
+  const [network, maskBitsStr] = subnet.split('/');
+  const maskBits = Number.parseInt(maskBitsStr, 10);
+
+  if (!network || Number.isNaN(maskBits) || maskBits < 0 || maskBits > 32) {
+    throw new Error(`Invalid subnet format: ${subnet}`);
+  }
+
+  const octets = network.split('.').map((o) => {
+    const octet = Number.parseInt(o, 10);
+    if (Number.isNaN(octet) || octet < 0 || octet > 255) {
+      throw new Error(`Invalid IP address: ${network}`);
+    }
+    return octet;
+  }) as [number, number, number, number];
+
+  if (octets.length !== 4) {
+    throw new Error(`Invalid IP address: ${network}`);
+  }
+
+  // Calculate total hosts (2^(32-maskBits) - 2 for network and broadcast)
+  const totalHosts = 2 ** (32 - maskBits) - 2;
+
+  // For simplicity, we only support /24 and larger subnets
+  if (maskBits > 24) {
+    throw new Error(`Subnet too small: ${subnet}. Celilo requires /24 or larger subnets.`);
+  }
+
+  // Calculate first and last usable IPs
+  // We reserve .1-.9 for infrastructure, so first usable is .10
+  const firstUsableIp = `${octets[0]}.${octets[1]}.${octets[2]}.10`;
+  const lastUsableIp = `${octets[0]}.${octets[1]}.${octets[2]}.254`;
+
+  return {
+    network,
+    maskBits,
+    octets,
+    firstUsableIp,
+    lastUsableIp,
+    totalHosts,
+  };
+}
+
+/**
+ * Strip CIDR mask from IP address
+ * Example: "10.0.10.10/24" → "10.0.10.10"
+ */
+export function stripCIDR(ipWithMask: string): string {
+  return ipWithMask.split('/')[0];
+}
+
+/**
+ * Add CIDR mask to IP address
+ * Example: "10.0.10.10", 24 → "10.0.10.10/24"
+ */
+export function addCIDR(ip: string, maskBits: number): string {
+  return `${ip}/${maskBits}`;
+}
+
+/**
+ * Check if an IP address belongs to a subnet
+ * Example: isInSubnet("10.0.10.50/24", "10.0.10.0/24") → true
+ */
+export function isInSubnet(ipWithMask: string, subnet: string): boolean {
+  const ip = stripCIDR(ipWithMask);
+  const subnetInfo = parseSubnet(subnet);
+
+  const ipOctets = ip.split('.').map((o) => Number.parseInt(o, 10));
+
+  // For /24 subnet, just check first 3 octets
+  return (
+    ipOctets[0] === subnetInfo.octets[0] &&
+    ipOctets[1] === subnetInfo.octets[1] &&
+    ipOctets[2] === subnetInfo.octets[2]
+  );
+}
+
+/**
+ * Generate all possible IPs in a subnet range
+ * For /24 subnet, returns IPs from .10 to .254 (reserved .1-.9 for infrastructure)
+ */
+export function* generateIPsInSubnet(subnet: string): Generator<string> {
+  const subnetInfo = parseSubnet(subnet);
+  const [a, b, c] = subnetInfo.octets;
+
+  // Start from .10 (reserve .1-.9 for infrastructure)
+  // End at .254 (reserve .255 for broadcast)
+  for (let lastOctet = 10; lastOctet <= 254; lastOctet++) {
+    yield addCIDR(`${a}.${b}.${c}.${lastOctet}`, subnetInfo.maskBits);
+  }
+}
+
+/**
+ * Check if IP is within a reserved range
+ */
+export function isIPInRange(ip: string, rangeStart: string, rangeEnd: string | null): boolean {
+  const ipNum = ipToNumber(ip);
+  const startNum = ipToNumber(rangeStart);
+
+  if (!rangeEnd) {
+    // Single IP reservation
+    return ipNum === startNum;
+  }
+
+  const endNum = ipToNumber(rangeEnd);
+  return ipNum >= startNum && ipNum <= endNum;
+}
+
+/**
+ * Convert IP address to number for comparison
+ * Example: "10.0.10.50" → 167773234
+ */
+function ipToNumber(ip: string): number {
+  const octets = stripCIDR(ip)
+    .split('.')
+    .map((o) => Number.parseInt(o, 10));
+  return (octets[0] << 24) + (octets[1] << 16) + (octets[2] << 8) + octets[3];
+}

package/src/manifest/contracts/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Celilo Module Contract Registry
+ *
+ * Maps contract version strings to their canonical hook signatures. The
+ * manifest's `celilo_contract` field selects which contract applies; the
+ * registry is the single source of truth for what each version promises.
+ *
+ * To mint a new contract version: add a new file (e.g. `./v2.ts`), import its
+ * contract object here, and register it in `CONTRACTS`. Old contracts stay
+ * registered indefinitely so legacy modules continue to validate.
+ */
+
+import { V1_CONTRACT } from './v1';
+import type { ContractHookSignature, ContractHooks } from './v1';
+
+export type { ContractHooks, ContractHookSignature };
+
+/**
+ * The shape of a registered contract.
+ */
+export interface Contract {
+  /** Semver-style version string (e.g. "1.0"). */
+  version: string;
+  /** Canonical hook signatures for this version. */
+  hooks: ContractHooks;
+}
+
+/**
+ * Registry of every contract version Celilo knows about.
+ * The keys are the strings users write in `celilo_contract`.
+ *
+ * When minting a new version, also add its string literal to
+ * `SUPPORTED_CONTRACT_VERSIONS` below so Zod's enum picks it up.
+ */
+export const CONTRACTS: Record<string, Contract> = {
+  '1.0': V1_CONTRACT,
+};
+
+/**
+ * Const tuple of supported contract version strings, used to drive the Zod
+ * enum that validates the manifest's `celilo_contract` field.
+ */
+export const SUPPORTED_CONTRACT_VERSIONS = ['1.0'] as const;
+export type SupportedContractVersion = (typeof SUPPORTED_CONTRACT_VERSIONS)[number];
+
+/**
+ * Look up a contract by version string.
+ *
+ * @returns The contract, or `undefined` if the version is not registered.
+ */
+export function resolveContract(version: string): Contract | undefined {
+  return CONTRACTS[version];
+}
+
+/**
+ * List of all registered contract version strings, used for error messages
+ * and for validating the `celilo_contract` field's enum.
+ */
+export function supportedContractVersions(): string[] {
+  return Object.keys(CONTRACTS);
+}

package/src/manifest/contracts/v1.ts

@@ -0,0 +1,118 @@
+/**
+ * Celilo Module Contract — v1.0
+ *
+ * Defines the canonical signature of every lifecycle hook in contract version
+ * "1.0". A module that declares `celilo_contract: "1.0"` in its manifest
+ * promises to implement these hooks with these exact inputs and outputs.
+ *
+ * Why this exists:
+ * Before contract versioning, every module redeclared inputs/outputs arrays
+ * for every hook in its manifest. That meant if Celilo changed the
+ * canonical signature of a hook (say, added a required input to on_backup),
+ * we had to hand-edit every manifest to match. This file is now the single
+ * source of truth.
+ *
+ * The contract is enforced by `validateHookInputs` and `validateHookOutputs`
+ * in `apps/celilo/src/hooks/executor.ts` — at execution time the executor
+ * looks up the canonical inputs/outputs from the contract registered for the
+ * manifest's declared version.
+ *
+ * Adding a new optional input or output is a v1.x additive change.
+ * Adding a new required input or removing a required output is a breaking
+ * change and requires a v2.0 contract.
+ */
+
+/**
+ * Per-input/output metadata.
+ *
+ * `required: true` — the executor enforces presence at runtime.
+ * `required: false` — the value is allowed but not mandatory; modules may
+ *   produce or accept it without violating the contract.
+ */
+export interface ContractField {
+  required: boolean;
+}
+
+/**
+ * Signature for a single lifecycle hook within a contract version.
+ */
+export interface ContractHookSignature {
+  /** Inputs the executor must supply when calling the hook. */
+  inputs: Record<string, ContractField>;
+  /** Outputs the executor enforces against the hook's return value. */
+  outputs: Record<string, ContractField>;
+}
+
+/**
+ * Full contract for a version: a map of canonical hook name → signature.
+ * Only hook names listed here are valid; declaring a hook not in this map is
+ * a manifest validation error.
+ */
+export type ContractHooks = Record<string, ContractHookSignature>;
+
+/**
+ * Contract v1.0 — current canonical hook signatures.
+ *
+ * These mirror the inputs/outputs that pre-Phase-2 manifests declared
+ * inline. The values were derived from a survey of every active manifest in
+ * the repo at the time the contract was minted.
+ */
+export const V1_HOOKS: ContractHooks = {
+  container_created: {
+    inputs: {},
+    outputs: {},
+  },
+  on_install: {
+    inputs: {},
+    outputs: {},
+  },
+  on_uninstall: {
+    inputs: {},
+    outputs: {},
+  },
+  health_check: {
+    inputs: {},
+    outputs: {},
+  },
+  validate_config: {
+    inputs: {},
+    outputs: {},
+  },
+  on_backup: {
+    inputs: {
+      backup_dir: { required: true },
+    },
+    outputs: {
+      artifact_count: { required: true },
+      size_bytes: { required: true },
+      schema_version: { required: true },
+    },
+  },
+  on_backup_analyze: {
+    inputs: {
+      artifact_path: { required: true },
+    },
+    outputs: {
+      artifact_count: { required: true },
+      size_bytes: { required: true },
+      schema_version: { required: true },
+    },
+  },
+  on_restore: {
+    inputs: {
+      restore_dir: { required: true },
+      schema_version: { required: true },
+    },
+    outputs: {
+      restored_items: { required: true },
+    },
+  },
+};
+
+/**
+ * Contract v1.0 metadata.
+ */
+export const V1_CONTRACT = {
+  version: '1.0' as const,
+  hooks: V1_HOOKS,
+};