@celilo/cli 0.1.0

package/src/services/module-types-drift.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Drift check: every active module's committed `celilo/types.d.ts`
+ * must match what `generateModuleTypes()` would produce from its
+ * current `manifest.yml`.
+ *
+ * This is the CI-level backstop for `celilo module types check`.
+ * If a manifest changes `variables.owns`/`variables.imports` but the
+ * committed types file is not regenerated, this test fails.
+ *
+ * Scope: `modules/<id>/manifest.yml` at the repo root. Archived
+ * modules (`modules/archive/**`) and scratch extract dirs
+ * (`modules/.tmp-*`) are excluded — they are not active modules.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Glob } from 'bun';
+import { validateManifest } from '../manifest/validate';
+import { generateModuleTypes } from './module-types-generator';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const MODULES_DIR = join(REPO_ROOT, 'modules');
+
+function findActiveManifests(): string[] {
+  const glob = new Glob('*/manifest.yml');
+  const results: string[] = [];
+  for (const match of glob.scanSync({ cwd: MODULES_DIR, onlyFiles: true })) {
+    results.push(join(MODULES_DIR, match));
+  }
+  return results.sort();
+}
+
+describe('module types drift check', () => {
+  const manifests = findActiveManifests();
+
+  test('discovers at least one active module', () => {
+    expect(manifests.length).toBeGreaterThan(0);
+  });
+
+  for (const manifestPath of manifests) {
+    const moduleDir = dirname(manifestPath);
+    const moduleId = moduleDir.split('/').pop() ?? moduleDir;
+
+    test(`${moduleId}: committed types.d.ts matches generated output`, () => {
+      const yaml = readFileSync(manifestPath, 'utf-8');
+      const result = validateManifest(yaml);
+      if (!result.success) {
+        const errorMessages = result.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+        throw new Error(`Manifest validation failed for ${moduleId}:\n${errorMessages}`);
+      }
+
+      const expected = generateModuleTypes(result.data);
+      const typesPath = join(moduleDir, 'celilo', 'types.d.ts');
+
+      let actual: string;
+      try {
+        actual = readFileSync(typesPath, 'utf-8');
+      } catch {
+        throw new Error(
+          `Missing committed types file: ${typesPath}\nRun: celilo module types generate ${moduleDir}`,
+        );
+      }
+
+      if (actual !== expected) {
+        throw new Error(
+          `Types file is stale: ${typesPath}\nIt does not match what would be generated from the current manifest.yml.\nRun: celilo module types generate ${moduleDir}`,
+        );
+      }
+    });
+  }
+});

package/src/services/module-types-generator.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Tests for the module types generator.
+ *
+ * These exercise pure codegen — no filesystem I/O. Each test builds a
+ * ModuleManifest object in-memory and asserts on the generated string.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../manifest/schema';
+import {
+  generateModuleTypes,
+  moduleIdToPascalCase,
+  variableTypeToTs,
+} from './module-types-generator';
+
+function baseManifest(overrides: Partial<ModuleManifest> = {}): ModuleManifest {
+  return {
+    celilo_contract: '1.0',
+    id: 'test-module',
+    name: 'Test Module',
+    version: '1.0.0',
+    requires: { capabilities: [] },
+    provides: { capabilities: [] },
+    variables: { owns: [], imports: [] },
+    ...overrides,
+  };
+}
+
+describe('moduleIdToPascalCase', () => {
+  test('converts single-word IDs', () => {
+    expect(moduleIdToPascalCase('lunacycle')).toBe('Lunacycle');
+  });
+
+  test('converts kebab-case IDs', () => {
+    expect(moduleIdToPascalCase('dns-external')).toBe('DnsExternal');
+    expect(moduleIdToPascalCase('my-fancy-app')).toBe('MyFancyApp');
+  });
+
+  test('handles empty segments defensively', () => {
+    expect(moduleIdToPascalCase('a--b')).toBe('AB');
+  });
+
+  test('preserves numeric characters', () => {
+    expect(moduleIdToPascalCase('caddy-v2')).toBe('CaddyV2');
+  });
+});
+
+describe('variableTypeToTs', () => {
+  test('maps primitives', () => {
+    expect(variableTypeToTs('string')).toBe('string');
+    expect(variableTypeToTs('boolean')).toBe('boolean');
+    expect(variableTypeToTs('integer')).toBe('number');
+    expect(variableTypeToTs('number')).toBe('number');
+  });
+
+  test('maps array to unknown[]', () => {
+    expect(variableTypeToTs('array')).toBe('unknown[]');
+  });
+
+  test('maps object to Record<string, unknown>', () => {
+    expect(variableTypeToTs('object')).toBe('Record<string, unknown>');
+  });
+});
+
+describe('generateModuleTypes', () => {
+  test('emits a file header and empty interface for a manifest with no variables', () => {
+    const out = generateModuleTypes(baseManifest({ id: 'empty', name: 'Empty Module' }));
+    expect(out).toContain('// Generated from manifest.yml');
+    expect(out).toContain('Do not edit by hand');
+    expect(out).toContain('export interface EmptyConfig {');
+    expect(out).toContain('(No variables declared — module has no typed config surface)');
+  });
+
+  test('produces the right interface name from a kebab-case module ID', () => {
+    const out = generateModuleTypes(baseManifest({ id: 'dns-external', name: 'DNS External' }));
+    expect(out).toContain('export interface DnsExternalConfig {');
+  });
+
+  test('renders required fields as non-optional', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [
+            {
+              name: 'hostname',
+              type: 'string',
+              required: true,
+              source: 'user',
+            },
+          ],
+          imports: [],
+        },
+      }),
+    );
+    expect(out).toContain('hostname: string;');
+    expect(out).not.toContain('hostname?: string;');
+  });
+
+  test('renders optional fields as optional when not required and no default', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [
+            {
+              name: 'hostname',
+              type: 'string',
+              required: false,
+              source: 'user',
+            },
+          ],
+          imports: [],
+        },
+      }),
+    );
+    expect(out).toContain('hostname?: string;');
+  });
+
+  test('treats not-required + default as guaranteed (non-optional)', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [
+            {
+              name: 'app_port',
+              type: 'integer',
+              required: false,
+              default: 3000,
+              source: 'user',
+            },
+          ],
+          imports: [],
+        },
+      }),
+    );
+    expect(out).toContain('app_port: number;');
+    expect(out).not.toContain('app_port?: number;');
+  });
+
+  test('maps every primitive type correctly', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [
+            { name: 'str', type: 'string', required: true, source: 'user' },
+            { name: 'num', type: 'number', required: true, source: 'user' },
+            { name: 'int', type: 'integer', required: true, source: 'user' },
+            { name: 'bool', type: 'boolean', required: true, source: 'user' },
+            { name: 'arr', type: 'array', required: true, source: 'user' },
+            { name: 'obj', type: 'object', required: true, source: 'user' },
+          ],
+          imports: [],
+        },
+      }),
+    );
+    expect(out).toContain('str: string;');
+    expect(out).toContain('num: number;');
+    expect(out).toContain('int: number;');
+    expect(out).toContain('bool: boolean;');
+    expect(out).toContain('arr: unknown[];');
+    expect(out).toContain('obj: Record<string, unknown>;');
+  });
+
+  test('emits JSDoc comments from variable descriptions', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [
+            {
+              name: 'hostname',
+              type: 'string',
+              required: true,
+              source: 'user',
+              description: 'Container hostname for DNS resolution',
+            },
+          ],
+          imports: [],
+        },
+      }),
+    );
+    expect(out).toContain('/** Container hostname for DNS resolution */');
+  });
+
+  test('renders imported capability variables as unknown with source-annotated JSDoc', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [],
+          imports: [
+            {
+              name: 'dns_nameserver',
+              source: 'capability',
+              from: 'dns_external.nameserver',
+            },
+          ],
+        },
+      }),
+    );
+    expect(out).toContain('Imported capability variables');
+    expect(out).toContain('dns_nameserver: unknown;');
+    expect(out).toContain('Imported from capability: dns_external.nameserver');
+  });
+
+  test('separates owns and imports sections with a blank line', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [{ name: 'hostname', type: 'string', required: true, source: 'user' }],
+          imports: [{ name: 'dns_ns', source: 'capability', from: 'dns_external.nameserver' }],
+        },
+      }),
+    );
+    expect(out).toContain('Module-owned variables');
+    expect(out).toContain('Imported capability variables');
+  });
+
+  test('includes the module name and description in the interface JSDoc', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'lunacycle',
+        name: 'LunaCycle',
+        description: 'Family task management',
+      }),
+    );
+    expect(out).toContain('Configuration shape for the LunaCycle module');
+    expect(out).toContain('Family task management');
+  });
+
+  test('escapes */ sequences in descriptions to avoid breaking the JSDoc', () => {
+    const out = generateModuleTypes(
+      baseManifest({
+        id: 'test',
+        name: 'Test',
+        variables: {
+          owns: [
+            {
+              name: 'weird',
+              type: 'string',
+              required: true,
+              source: 'user',
+              description: 'A field with */ in the description',
+            },
+          ],
+          imports: [],
+        },
+      }),
+    );
+    expect(out).not.toContain('*/ in the description');
+    expect(out).toContain('* / in the description');
+  });
+
+  test('output is deterministic across multiple runs', () => {
+    const manifest = baseManifest({
+      id: 'lunacycle',
+      name: 'LunaCycle',
+      variables: {
+        owns: [
+          { name: 'hostname', type: 'string', required: true, source: 'user' },
+          { name: 'app_port', type: 'integer', required: false, default: 3000, source: 'user' },
+        ],
+        imports: [],
+      },
+    });
+    const first = generateModuleTypes(manifest);
+    const second = generateModuleTypes(manifest);
+    const third = generateModuleTypes(manifest);
+    expect(first).toBe(second);
+    expect(second).toBe(third);
+  });
+
+  test('output ends with a trailing newline', () => {
+    const out = generateModuleTypes(baseManifest());
+    expect(out.endsWith('\n')).toBe(true);
+  });
+});

package/src/services/module-types-generator.ts

@@ -0,0 +1,189 @@
+/**
+ * Module Types Generator
+ *
+ * Pure codegen: given a validated ModuleManifest, produces the content of
+ * `<module>/celilo/types.d.ts` — a TypeScript declaration file exposing
+ * a typed `<ModuleName>Config` interface derived from the manifest's
+ * `variables.owns` and `variables.imports` arrays.
+ *
+ * This file is intentionally I/O-free. The CLI command in
+ * `cli/commands/module-types.ts` handles reading manifests and writing
+ * output files; this module is responsible for the translation only, so
+ * unit tests can exercise every branch without touching the filesystem.
+ *
+ * See `design/TECHNICAL_DESIGN_HOOK_API_V2.md` D2 for the design rationale.
+ */
+
+import type { ModuleManifest, VariableDeclare, VariableImport } from '../manifest/schema';
+
+/**
+ * Convert a kebab-case module ID to a PascalCase type name.
+ *
+ *   "lunacycle"      → "Lunacycle"
+ *   "dns-external"   → "DnsExternal"
+ *   "my-fancy-app"   → "MyFancyApp"
+ */
+export function moduleIdToPascalCase(id: string): string {
+  return id
+    .split('-')
+    .map((part) => (part.length === 0 ? '' : part[0].toUpperCase() + part.slice(1)))
+    .join('');
+}
+
+/**
+ * Translate a variable's declared `type:` field into a TypeScript type
+ * expression. Per HOOK_API_V2 D2, arrays and objects get generic
+ * unknown-element types for now; richer item-level typing can be added
+ * later without breaking any committed `types.d.ts`.
+ */
+export function variableTypeToTs(type: VariableDeclare['type']): string {
+  switch (type) {
+    case 'string':
+      return 'string';
+    case 'integer':
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      return 'unknown[]';
+    case 'object':
+      return 'Record<string, unknown>';
+  }
+}
+
+/**
+ * Determine whether a declared variable is guaranteed to have a value at
+ * hook execution time. A variable is guaranteed if:
+ *   - It's marked `required: true`, OR
+ *   - It has a `default:` value (the default guarantees presence).
+ *
+ * `infrastructure` sources are treated as guaranteed when the variable is
+ * marked required; Celilo's infrastructure-variable-resolver populates
+ * them before hooks run and fails fast if it can't.
+ */
+function isVariableGuaranteed(variable: VariableDeclare): boolean {
+  if (variable.required) return true;
+  if (variable.default !== undefined) return true;
+  return false;
+}
+
+function isImportGuaranteed(_variable: VariableImport): boolean {
+  // Imports are sourced from another module's capability. The capability
+  // must be declared in requires.capabilities (enforced by
+  // validateVariableSources), and at hook invocation time Celilo's
+  // resolver populates the value. We treat imports as guaranteed —
+  // Phase 3 will add an explicit runtime pre-flight check.
+  return true;
+}
+
+/**
+ * Escape a string so it can appear safely inside a JSDoc block comment.
+ * Converts sequences that would terminate the comment.
+ */
+function escapeJsDoc(text: string): string {
+  return text.replace(/\*\//g, '* /');
+}
+
+function formatJsDocLine(description: string | undefined): string[] {
+  if (!description) return [];
+  return [`  /** ${escapeJsDoc(description)} */`];
+}
+
+/**
+ * Render a single interface field: optional JSDoc + name + optionality + type.
+ */
+function renderField(
+  name: string,
+  type: string,
+  optional: boolean,
+  description: string | undefined,
+): string[] {
+  const doc = formatJsDocLine(description);
+  const optionalMark = optional ? '?' : '';
+  return [...doc, `  ${name}${optionalMark}: ${type};`];
+}
+
+/**
+ * Sort variables deterministically so regenerating against the same
+ * manifest always produces byte-identical output. Manifest author order
+ * is the canonical order — stable across runs, meaningful to readers.
+ * `variables.owns` is already ordered by the YAML parser; we just
+ * preserve it.
+ */
+
+/**
+ * Generate the full `<module>/celilo/types.d.ts` content for a manifest.
+ *
+ * Deterministic: calling this twice with the same input produces
+ * byte-identical output, so the drift check can compare against the
+ * committed file.
+ */
+export function generateModuleTypes(manifest: ModuleManifest): string {
+  const typeName = `${moduleIdToPascalCase(manifest.id)}Config`;
+  const lines: string[] = [];
+
+  lines.push('// Generated from manifest.yml by `celilo module types generate`.');
+  lines.push('// Do not edit by hand. Run the command again after changing `variables.owns`.');
+  lines.push('// CI enforces this file stays in sync via `celilo module types check`.');
+  lines.push('');
+  lines.push('/**');
+  lines.push(` * Configuration shape for the ${manifest.name} module.`);
+  if (manifest.description) {
+    lines.push(' *');
+    for (const descLine of manifest.description.split('\n')) {
+      lines.push(` * ${descLine}`);
+    }
+  }
+  lines.push(' *');
+  lines.push(' * Fields are derived from `variables.owns` and `variables.imports` in the');
+  lines.push(' * module manifest. Optional fields (marked with `?`) correspond to variables');
+  lines.push(' * that are neither `required: true` nor have a `default:` value.');
+  lines.push(' */');
+  lines.push(`export interface ${typeName} {`);
+
+  const ownsFields: string[] = [];
+  const importsFields: string[] = [];
+
+  for (const variable of manifest.variables.owns) {
+    const tsType = variableTypeToTs(variable.type);
+    const optional = !isVariableGuaranteed(variable);
+    const rendered = renderField(variable.name, tsType, optional, variable.description);
+    ownsFields.push(...rendered);
+  }
+
+  for (const imp of manifest.variables.imports) {
+    // Imports don't carry type info in the manifest schema — they're
+    // raw references to capability data. Treat as `unknown` so consumers
+    // cast as needed. A future enhancement could look up the capability's
+    // `data_schema` to infer a more precise type.
+    const optional = !isImportGuaranteed(imp);
+    const rendered = renderField(
+      imp.name,
+      'unknown',
+      optional,
+      `Imported from ${imp.source}: ${imp.from}`,
+    );
+    importsFields.push(...rendered);
+  }
+
+  if (ownsFields.length > 0) {
+    lines.push('  // Module-owned variables (from variables.owns)');
+    lines.push(...ownsFields);
+  }
+
+  if (importsFields.length > 0) {
+    if (ownsFields.length > 0) lines.push('');
+    lines.push('  // Imported capability variables (from variables.imports)');
+    lines.push(...importsFields);
+  }
+
+  if (ownsFields.length === 0 && importsFields.length === 0) {
+    lines.push('  // (No variables declared — module has no typed config surface)');
+  }
+
+  lines.push('}');
+  lines.push('');
+
+  return lines.join('\n');
+}

package/src/services/proxmox-state-recovery.ts

@@ -0,0 +1,140 @@
+/**
+ * Proxmox State Recovery Service
+ *
+ * Handles state drift scenarios where Terraform state and module_configs are out of sync.
+ * This typically occurs when containers are deleted outside Terraform and then recreated.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { and, eq } from 'drizzle-orm';
+import { log } from '../cli/prompts';
+import type { DbClient } from '../db/client';
+import { moduleConfigs } from '../db/schema';
+
+/**
+ * Terraform state file structure (subset we care about)
+ */
+interface TerraformState {
+  resources?: Array<{
+    type: string;
+    name: string;
+    instances?: Array<{
+      attributes?: {
+        vmid?: number;
+        network?: Array<{
+          ip?: string;
+        }>;
+      };
+    }>;
+  }>;
+}
+
+/**
+ * Ensure module_configs has vmid and container_ip from Terraform state
+ * This recovers from state drift scenarios where container was deleted/recreated
+ *
+ * @param moduleId - Module identifier
+ * @param terraformDir - Terraform working directory
+ * @param db - Database connection
+ */
+export async function ensureProxmoxConfigFromState(
+  moduleId: string,
+  terraformDir: string,
+  db: DbClient,
+): Promise<void> {
+  // Check if vmid and container_ip already exist
+  const existingVmid = await db
+    .select()
+    .from(moduleConfigs)
+    .where(and(eq(moduleConfigs.moduleId, moduleId), eq(moduleConfigs.key, 'vmid')))
+    .get();
+
+  const existingContainerIp = await db
+    .select()
+    .from(moduleConfigs)
+    .where(and(eq(moduleConfigs.moduleId, moduleId), eq(moduleConfigs.key, 'container_ip')))
+    .get();
+
+  // If both exist, no recovery needed
+  if (existingVmid && existingContainerIp) {
+    return;
+  }
+
+  // Read Terraform state file
+  const statePath = join(terraformDir, 'terraform.tfstate');
+  let stateContent: string;
+  try {
+    stateContent = await readFile(statePath, 'utf-8');
+  } catch (error) {
+    throw new Error(
+      `Failed to read Terraform state for recovery: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    );
+  }
+
+  let state: TerraformState;
+  try {
+    state = JSON.parse(stateContent) as TerraformState;
+  } catch (error) {
+    throw new Error(
+      `Failed to parse Terraform state: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    );
+  }
+
+  // Find proxmox_lxc resource
+  const lxcResource = state.resources?.find((r) => r.type === 'proxmox_lxc');
+  if (!lxcResource || !lxcResource.instances || lxcResource.instances.length === 0) {
+    throw new Error('No proxmox_lxc resource found in Terraform state');
+  }
+
+  const attributes = lxcResource.instances[0].attributes;
+  if (!attributes) {
+    throw new Error('No attributes found in proxmox_lxc resource');
+  }
+
+  const vmid = attributes.vmid;
+  const containerIp = attributes.network?.[0]?.ip;
+
+  if (!vmid) {
+    throw new Error('vmid not found in Terraform state');
+  }
+
+  if (!containerIp) {
+    throw new Error('container IP not found in Terraform state');
+  }
+
+  // Store in module_configs (recovery)
+  log.warn('  Recovering vmid and container_ip from Terraform state...');
+
+  if (!existingVmid) {
+    await db
+      .insert(moduleConfigs)
+      .values({
+        moduleId,
+        key: 'vmid',
+        value: vmid.toString(),
+      })
+      .onConflictDoUpdate({
+        target: [moduleConfigs.moduleId, moduleConfigs.key],
+        set: { value: vmid.toString() },
+      })
+      .run();
+  }
+
+  if (!existingContainerIp) {
+    await db
+      .insert(moduleConfigs)
+      .values({
+        moduleId,
+        key: 'container_ip',
+        value: containerIp,
+      })
+      .onConflictDoUpdate({
+        target: [moduleConfigs.moduleId, moduleConfigs.key],
+        set: { value: containerIp },
+      })
+      .run();
+  }
+
+  log.success(`  Recovered: vmid=${vmid}, container_ip=${containerIp}`);
+}