@celilo/cli 0.1.0

package/src/cli/commands/module-types.ts

@@ -0,0 +1,189 @@
+/**
+ * Module types command
+ *
+ * Generates TypeScript `<module>/celilo/types.d.ts` files from a
+ * module's `variables.owns` / `variables.imports` declarations in
+ * manifest.yml. The generated file exposes a `<ModuleName>Config`
+ * interface that hook scripts import via `defineHook<ConfigT, ...>`.
+ *
+ * See `design/TECHNICAL_DESIGN_HOOK_API_V2.md` D2 for the design rationale.
+ *
+ * Subcommands:
+ *   celilo module types generate <module-dir>  — write types.d.ts
+ *   celilo module types check <module-dir>     — CI drift check
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import type { ModuleManifest } from '../../manifest/schema';
+import { validateManifest } from '../../manifest/validate';
+import { generateModuleTypes } from '../../services/module-types-generator';
+import { getArg, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+const TYPES_FILE_RELATIVE_PATH = join('celilo', 'types.d.ts');
+
+type LoadManifestResult =
+  | { ok: true; manifest: ModuleManifest }
+  | { ok: false; failure: CommandResult };
+
+/**
+ * Load and validate a module's manifest.yml from a directory path.
+ *
+ * Returns a discriminated result: either the parsed manifest on success,
+ * or a CommandResult describing the failure that callers can return
+ * directly.
+ */
+async function loadManifest(modulePath: string): Promise<LoadManifestResult> {
+  const absolute = resolve(modulePath);
+  if (!existsSync(absolute)) {
+    return {
+      ok: false,
+      failure: {
+        success: false,
+        error: `Module directory does not exist: ${modulePath}`,
+      },
+    };
+  }
+
+  const manifestPath = join(absolute, 'manifest.yml');
+  if (!existsSync(manifestPath)) {
+    return {
+      ok: false,
+      failure: {
+        success: false,
+        error: `No manifest.yml found in ${modulePath}`,
+      },
+    };
+  }
+
+  const yamlContent = await readFile(manifestPath, 'utf-8');
+  const result = validateManifest(yamlContent);
+  if (!result.success) {
+    const errorMessages = result.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+    return {
+      ok: false,
+      failure: {
+        success: false,
+        error: `Manifest validation failed:\n${errorMessages}`,
+      },
+    };
+  }
+
+  return { ok: true, manifest: result.data };
+}
+
+/**
+ * Handle `celilo module types generate <module-dir>`.
+ *
+ * Reads the manifest, generates the types file content, writes it to
+ * `<module-dir>/celilo/types.d.ts`, creating the `celilo/`
+ * subdirectory if needed.
+ */
+export async function handleModuleTypesGenerate(args: string[]): Promise<CommandResult> {
+  const err = validateRequiredArgs(args, 1);
+  if (err) {
+    return {
+      success: false,
+      error: `${err}\n\nUsage: celilo module types generate <module-dir>`,
+    };
+  }
+
+  const modulePath = getArg(args, 0);
+  if (!modulePath) {
+    return {
+      success: false,
+      error: 'Module directory is required\n\nUsage: celilo module types generate <module-dir>',
+    };
+  }
+
+  const loaded = await loadManifest(modulePath);
+  if (!loaded.ok) return loaded.failure;
+
+  const content = generateModuleTypes(loaded.manifest);
+  const outputPath = resolve(modulePath, TYPES_FILE_RELATIVE_PATH);
+
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, content, 'utf-8');
+
+  return {
+    success: true,
+    message: `Generated ${outputPath}`,
+  };
+}
+
+/**
+ * Handle `celilo module types check <module-dir>`.
+ *
+ * Regenerates the expected types file content in-memory and compares it
+ * byte-for-byte to the committed file. Fails if they differ or if the
+ * committed file is missing. Used as a CI drift check.
+ */
+export async function handleModuleTypesCheck(args: string[]): Promise<CommandResult> {
+  const err = validateRequiredArgs(args, 1);
+  if (err) {
+    return {
+      success: false,
+      error: `${err}\n\nUsage: celilo module types check <module-dir>`,
+    };
+  }
+
+  const modulePath = getArg(args, 0);
+  if (!modulePath) {
+    return {
+      success: false,
+      error: 'Module directory is required\n\nUsage: celilo module types check <module-dir>',
+    };
+  }
+
+  const loaded = await loadManifest(modulePath);
+  if (!loaded.ok) return loaded.failure;
+
+  const expected = generateModuleTypes(loaded.manifest);
+  const outputPath = resolve(modulePath, TYPES_FILE_RELATIVE_PATH);
+
+  if (!existsSync(outputPath)) {
+    return {
+      success: false,
+      error: `Types file missing: ${outputPath}\n\nRun 'celilo module types generate ${modulePath}' to create it.`,
+    };
+  }
+
+  const actual = await readFile(outputPath, 'utf-8');
+  if (actual !== expected) {
+    return {
+      success: false,
+      error: `Types file is stale: ${outputPath}\n\nIt does not match what would be generated from the current manifest.yml.\nRun 'celilo module types generate ${modulePath}' to regenerate.`,
+    };
+  }
+
+  return {
+    success: true,
+    message: `Types file is in sync: ${outputPath}`,
+  };
+}
+
+/**
+ * Silent generator used as the belt-and-suspenders step in
+ * `celilo module import`. Writes types to the imported module's
+ * directory and swallows errors with a warning — failing to regenerate
+ * types should not abort an import.
+ *
+ * Returns a string describing what was done (for logging), or `null` if
+ * the operation was skipped or failed silently.
+ */
+export async function generateTypesForImportedModule(modulePath: string): Promise<string | null> {
+  try {
+    const loaded = await loadManifest(modulePath);
+    if (!loaded.ok) return null;
+
+    const content = generateModuleTypes(loaded.manifest);
+    const outputPath = resolve(modulePath, TYPES_FILE_RELATIVE_PATH);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, content, 'utf-8');
+    return outputPath;
+  } catch {
+    return null;
+  }
+}

package/src/cli/commands/module-upgrade.ts

@@ -0,0 +1,192 @@
+/**
+ * Module update command
+ *
+ * Updates module code (manifest, scripts, templates) while preserving state
+ * (configs, secrets, infrastructure, capabilities).
+ *
+ * Usage: celilo module update <path>
+ *
+ * The module ID is read from the manifest at the given path.
+ */
+
+import { cpSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { parse as parseYaml } from 'yaml';
+import { registerModuleCapabilities } from '../../capabilities/registration';
+import { getDb } from '../../db/client';
+import { capabilities, modules } from '../../db/schema';
+import { ModuleManifestSchema } from '../../manifest/schema';
+import type { ModuleManifest } from '../../manifest/schema';
+import { cleanupTempDir, extractPackage } from '../../module/packaging/extract';
+import { log } from '../prompts';
+import type { CommandResult } from '../types';
+
+/**
+ * Upgrade a single module from a source path
+ */
+async function upgradeOne(
+  sourcePath: string,
+  db: ReturnType<typeof getDb>,
+  flags: Record<string, string | boolean> = {},
+): Promise<{ moduleId: string; success: boolean; error?: string }> {
+  const originalCwd = process.env.CELILO_ORIGINAL_CWD || process.cwd();
+  const importPath = resolve(originalCwd, sourcePath);
+  if (!existsSync(importPath)) {
+    return { moduleId: sourcePath, success: false, error: `Source path not found: ${importPath}` };
+  }
+
+  // Handle .netapp packages: extract to temp dir
+  let actualPath = importPath;
+  let tempDir: string | null = null;
+
+  if (importPath.endsWith('.netapp')) {
+    const extractResult = await extractPackage(importPath);
+    if (!extractResult.success || !extractResult.tempDir) {
+      return {
+        moduleId: sourcePath,
+        success: false,
+        error: extractResult.error || 'Failed to extract package',
+      };
+    }
+    tempDir = extractResult.tempDir;
+    actualPath = tempDir;
+
+    // Skip signature verification if --skip-verify
+    if (flags['skip-verify'] !== true) {
+      const { verifyPackageIntegrity } = await import('../../module/packaging/extract');
+      const verifyResult = await verifyPackageIntegrity(tempDir);
+      if (!verifyResult.success) {
+        await cleanupTempDir(tempDir);
+        return {
+          moduleId: sourcePath,
+          success: false,
+          error: verifyResult.error || 'Package verification failed',
+        };
+      }
+    } else {
+      log.warn('Skipping package signature verification (--skip-verify)');
+    }
+  }
+
+  const manifestPath = join(actualPath, 'manifest.yml');
+  if (!existsSync(manifestPath)) {
+    if (tempDir) await cleanupTempDir(tempDir);
+    return {
+      moduleId: sourcePath,
+      success: false,
+      error: `No manifest.yml found at ${actualPath}`,
+    };
+  }
+
+  let newManifest: ModuleManifest;
+  try {
+    const raw = readFileSync(manifestPath, 'utf-8');
+    const parsed = parseYaml(raw);
+    newManifest = ModuleManifestSchema.parse(parsed);
+  } catch (err) {
+    if (tempDir) await cleanupTempDir(tempDir);
+    const msg = err instanceof Error ? err.message : String(err);
+    return { moduleId: sourcePath, success: false, error: `Invalid manifest: ${msg}` };
+  }
+
+  const moduleId = newManifest.id;
+
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    return {
+      moduleId,
+      success: false,
+      error: `Module '${moduleId}' is not installed. Use 'celilo module import ${sourcePath}' first.`,
+    };
+  }
+
+  const oldManifest = module.manifestData as ModuleManifest;
+  log.info(`Upgrading ${moduleId}: v${oldManifest.version} → v${newManifest.version}`);
+
+  // Copy new module files, preserving generated output and state
+  const installedPath = module.sourcePath;
+  const preserveDirs = new Set(['generated', 'screenshots', 'cookies.json']);
+
+  const skipDirs = new Set(['.git', 'node_modules', '.next', '.cache']);
+  const entries = readdirSync(actualPath);
+  for (const entry of entries) {
+    if (preserveDirs.has(entry) || skipDirs.has(entry)) continue;
+    const src = join(actualPath, entry);
+    const dest = join(installedPath, entry);
+    cpSync(src, dest, { recursive: true, force: true });
+  }
+
+  // Clean up temp dir if we extracted a .netapp
+  if (tempDir) await cleanupTempDir(tempDir);
+
+  // Update manifest in database
+  db.update(modules)
+    .set({
+      manifestData: newManifest as unknown as Record<string, unknown>,
+      version: newManifest.version,
+      name: newManifest.name,
+    })
+    .where(eq(modules.id, moduleId))
+    .run();
+
+  // Re-register capabilities
+  db.delete(capabilities).where(eq(capabilities.moduleId, moduleId)).run();
+
+  if (newManifest.provides?.capabilities && newManifest.provides.capabilities.length > 0) {
+    const regResult = await registerModuleCapabilities(moduleId, newManifest, db.$client);
+    if (!regResult.success) {
+      log.warn(`  ${moduleId}: capability re-registration warning: ${regResult.error}`);
+    }
+  }
+
+  log.success(`Upgraded ${moduleId} (v${oldManifest.version} → v${newManifest.version})`);
+  return { moduleId, success: true };
+}
+
+/**
+ * Handle module upgrade command
+ *
+ * @param args - Command arguments: [path, path, ...]
+ * @returns Command result
+ */
+export async function handleModuleUpgrade(
+  args: string[],
+  flags: Record<string, string | boolean> = {},
+): Promise<CommandResult> {
+  if (args.length === 0) {
+    return {
+      success: false,
+      error: 'At least one module path is required\n\nUsage: celilo module update <path> [path...]',
+    };
+  }
+
+  const db = getDb();
+  const results: Array<{ moduleId: string; success: boolean; error?: string }> = [];
+
+  for (const path of args) {
+    const result = await upgradeOne(path, db, flags);
+    results.push(result);
+  }
+
+  const succeeded = results.filter((r) => r.success);
+  const failed = results.filter((r) => !r.success);
+
+  if (failed.length > 0) {
+    const errors = failed.map((r) => `  ${r.moduleId}: ${r.error}`).join('\n');
+    if (succeeded.length > 0) {
+      const names = succeeded.map((r) => r.moduleId).join(', ');
+      return {
+        success: false,
+        error: `Upgraded ${succeeded.length} module(s): ${names}\n\nFailed ${failed.length}:\n${errors}`,
+      };
+    }
+    return { success: false, error: `Upgrade failed:\n${errors}` };
+  }
+
+  const names = succeeded.map((r) => r.moduleId).join(', ');
+  return {
+    success: true,
+    message: `Successfully updated ${succeeded.length} module(s): ${names}`,
+  };
+}

package/src/cli/commands/package.ts

@@ -0,0 +1,68 @@
+/**
+ * Package command
+ *
+ * Creates distributable .netapp packages from module source directories
+ */
+
+import { resolve } from 'node:path';
+import { buildModule } from '../../module/packaging/build';
+import { getArg, getFlag, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle package command
+ *
+ * Usage:
+ *   celilo package <source-directory> [--output <path>]
+ *
+ * @param args - Command arguments
+ * @param flags - Command flags
+ * @returns Command result
+ */
+export async function handlePackage(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  // Validate arguments
+  const error = validateRequiredArgs(args, 1);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage:\n  celilo package <source-directory> [--output <path>]`,
+    };
+  }
+
+  const sourceDir = getArg(args, 0);
+  if (!sourceDir) {
+    return {
+      success: false,
+      error: 'Source directory is required',
+    };
+  }
+
+  // Resolve paths relative to the user's original cwd, not the backend directory
+  const originalCwd = process.env.CELILO_ORIGINAL_CWD || process.cwd();
+  const resolvedSourceDir = resolve(originalCwd, sourceDir);
+  const outputPath = getFlag(flags, 'output');
+  const resolvedOutputPath = outputPath ? resolve(originalCwd, outputPath as string) : undefined;
+
+  const result = await buildModule({
+    sourceDir: resolvedSourceDir,
+    outputPath: resolvedOutputPath,
+  });
+
+  if (!result.success) {
+    return {
+      success: false,
+      error: result.error || 'Package creation failed',
+    };
+  }
+
+  return {
+    success: true,
+    message: `Successfully created module package: ${result.packagePath}`,
+    data: {
+      packagePath: result.packagePath,
+    },
+  };
+}

package/src/cli/commands/secret-list.ts

@@ -0,0 +1,99 @@
+/**
+ * Secret list command
+ */
+
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { modules, secrets } from '../../db/schema';
+import { getArg, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle secret list command
+ *
+ * Usage: celilo secret list <module-id>
+ *
+ * Lists all secrets declared in the module manifest and shows which ones are configured.
+ *
+ * @param args - Command arguments
+ * @returns Command result
+ */
+export async function handleSecretList(args: string[]): Promise<CommandResult> {
+  // Validate arguments
+  const error = validateRequiredArgs(args, 1);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo secret list <module-id>`,
+    };
+  }
+
+  const moduleId = getArg(args, 0);
+  if (!moduleId) {
+    return {
+      success: false,
+      error: 'Module ID is required',
+    };
+  }
+
+  const db = getDb();
+
+  // Check if module exists
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    return {
+      success: false,
+      error: `Module not found: ${moduleId}`,
+    };
+  }
+
+  // Get declared secrets from manifest
+  const manifest = module.manifestData as Record<string, unknown>;
+  const secretsSection = manifest.secrets as
+    | {
+        declares?: Array<{ name: string; type?: string; required?: boolean; description?: string }>;
+      }
+    | undefined;
+  const declaredSecrets = secretsSection?.declares || [];
+
+  if (declaredSecrets.length === 0) {
+    return {
+      success: true,
+      message: `Module '${moduleId}' declares no secrets`,
+    };
+  }
+
+  // Get configured secrets from database
+  const configuredSecrets = db
+    .select({ name: secrets.name })
+    .from(secrets)
+    .where(eq(secrets.moduleId, moduleId))
+    .all();
+
+  const configuredNames = new Set(configuredSecrets.map((s) => s.name));
+
+  // Build output
+  const lines: string[] = [`\nSecrets for module '${moduleId}':\n`];
+
+  for (const secret of declaredSecrets) {
+    const isConfigured = configuredNames.has(secret.name);
+    const status = isConfigured ? '✓' : '✗';
+    const statusText = isConfigured ? 'configured' : 'not configured';
+    const requiredText = secret.required ? ' (required)' : '';
+
+    lines.push(`  ${status} ${secret.name} - ${statusText}${requiredText}`);
+    if (secret.description) {
+      lines.push(`    ${secret.description}`);
+    }
+  }
+
+  // Summary
+  const configuredCount = declaredSecrets.filter((s) => configuredNames.has(s.name)).length;
+  const totalCount = declaredSecrets.length;
+  lines.push(`\nConfigured: ${configuredCount}/${totalCount}`);
+
+  return {
+    success: true,
+    message: lines.join('\n'),
+  };
+}

package/src/cli/commands/secret-set.ts

@@ -0,0 +1,134 @@
+/**
+ * Secret set command
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { modules, secrets } from '../../db/schema';
+import { encryptSecret } from '../../secrets/encryption';
+import { getOrCreateMasterKey } from '../../secrets/master-key';
+import { getArg, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle secret set command
+ *
+ * Usage: celilo secret set <module-id> <name> <value>
+ *
+ * @param args - Command arguments
+ * @returns Command result
+ */
+export async function handleSecretSet(args: string[]): Promise<CommandResult> {
+  // Validate arguments
+  const error = validateRequiredArgs(args, 3);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo secret set <module-id> <name> <value>`,
+    };
+  }
+
+  const moduleId = getArg(args, 0);
+  const name = getArg(args, 1);
+  const value = getArg(args, 2);
+
+  if (!moduleId || !name || !value) {
+    return {
+      success: false,
+      error: 'Module ID, secret name, and value are required',
+    };
+  }
+
+  const db = getDb();
+
+  // Check if module exists
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    return {
+      success: false,
+      error: `Module not found: ${moduleId}`,
+    };
+  }
+
+  // Validate secret name against manifest
+  const manifest = module.manifestData as Record<string, unknown>;
+  const secretsSection = manifest.secrets as
+    | { declares?: Array<{ name: string; type?: string; required?: boolean }> }
+    | undefined;
+  const declaredSecrets = secretsSection?.declares || [];
+
+  // Check if secret is declared in manifest
+  const declaredSecret = declaredSecrets.find((s) => s.name === name);
+  if (!declaredSecret) {
+    const validSecrets = declaredSecrets.map((s) => s.name).join(', ');
+    return {
+      success: false,
+      error: `Invalid secret '${name}' for module ${moduleId}.\n\nValid secrets: ${validSecrets || '(none declared)'}`,
+    };
+  }
+
+  // Get or create master key
+  let masterKey: Buffer;
+  try {
+    masterKey = await getOrCreateMasterKey();
+  } catch (err) {
+    return {
+      success: false,
+      error: 'Failed to access master key',
+      details: err,
+    };
+  }
+
+  // Encrypt secret
+  let encrypted: { encryptedValue: string; iv: string; authTag: string };
+  try {
+    encrypted = encryptSecret(value, masterKey);
+  } catch (err) {
+    return {
+      success: false,
+      error: 'Failed to encrypt secret',
+      details: err,
+    };
+  }
+
+  // Check if secret already exists
+  const existingSecret = db
+    .select()
+    .from(secrets)
+    .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, name)))
+    .get();
+
+  if (existingSecret) {
+    // Update existing secret
+    db.update(secrets)
+      .set({
+        encryptedValue: encrypted.encryptedValue,
+        iv: encrypted.iv,
+        authTag: encrypted.authTag,
+        updatedAt: new Date(),
+      })
+      .where(eq(secrets.id, existingSecret.id))
+      .run();
+
+    return {
+      success: true,
+      message: `Updated secret for ${moduleId}: ${name}`,
+    };
+  }
+
+  // Insert new secret
+  db.insert(secrets)
+    .values({
+      moduleId,
+      name,
+      encryptedValue: encrypted.encryptedValue,
+      iv: encrypted.iv,
+      authTag: encrypted.authTag,
+    })
+    .run();
+
+  return {
+    success: true,
+    message: `Set secret for ${moduleId}: ${name}`,
+  };
+}