@celilo/cli 0.1.5 → 0.1.6

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

@@ -0,0 +1,234 @@
+/**
+ * Module publish command — build and publish a module to the registry.
+ *
+ * Usage: celilo module publish <module-dir> --token <token>
+ *                              [--registry <url>] [--revision <n>]
+ *                              [--message "release note"] [--allow-dirty]
+ *
+ * The --token flag (or CELILO_PUBLISH_TOKEN env var) must contain a valid
+ * publish token configured on the registry server.
+ *
+ * Per CELILO_UPDATE D4 (strict-publish) the manifest's capability
+ * versions are validated against `CAPABILITY_CONTRACT_VERSIONS` from
+ * `@celilo/capabilities` before any build work; a mismatch refuses
+ * the publish so a stale manifest can't ship code that doesn't match
+ * its claimed contract.
+ *
+ * Per CELILO_UPDATE D5, every published .netapp carries a
+ * `release.json` with git SHA / branch / dirty flag / publish
+ * timestamp / CLI version / optional --message.
+ */
+
+import { rm } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  CAPABILITY_CONTRACT_VERSIONS,
+  type KnownCapabilityName,
+  compareProviderToRuntime,
+} from '@celilo/capabilities';
+import { parse as parseYaml } from 'yaml';
+import { buildModule } from '../../module/packaging/build';
+import {
+  buildReleaseMetadata,
+  collectGitInfo,
+  makeRealGitRunner,
+  readInstalledCliVersion,
+} from '../../module/packaging/release-metadata';
+import { RegistryClient } from '../../registry/client';
+import { getArg, getFlag, hasFlag } from '../parser';
+import type { CommandResult } from '../types';
+
+interface ManifestCapabilityClaim {
+  name: string;
+  version: string;
+}
+
+interface ManifestForPublish {
+  id: string;
+  version: string;
+  provides?: { capabilities?: ManifestCapabilityClaim[] };
+  requires?: { capabilities?: ManifestCapabilityClaim[] };
+}
+
+function isKnownCapability(name: string): name is KnownCapabilityName {
+  return name in CAPABILITY_CONTRACT_VERSIONS;
+}
+
+/**
+ * Strict-publish: every `provides[X].version` must match the framework's
+ * runtime registry; every `requires[X].version` must be at most the
+ * framework's runtime version (consumers can require older minors of
+ * still-supported majors).
+ *
+ * Exported for testing.
+ */
+export function validateCapabilityVersions(manifest: ManifestForPublish): string[] {
+  const errors: string[] = [];
+
+  for (const p of manifest.provides?.capabilities ?? []) {
+    if (!isKnownCapability(p.name)) continue;
+    const runtime = CAPABILITY_CONTRACT_VERSIONS[p.name];
+    const r = compareProviderToRuntime(p.version, runtime);
+    if (!r.compatible) {
+      errors.push(
+        `provides[${p.name}].version is ${p.version} but framework registry is ${runtime} ` +
+          `(${r.reason}). Update the manifest, then retry.`,
+      );
+    }
+  }
+
+  for (const need of manifest.requires?.capabilities ?? []) {
+    if (!isKnownCapability(need.name)) continue;
+    const runtime = CAPABILITY_CONTRACT_VERSIONS[need.name];
+    // Treat the runtime as the de-facto provider for publish-time validation:
+    // if a consumer's manifest claims it requires a contract newer than the
+    // framework even has registered, no in-tree provider can satisfy it.
+    const r = compareProviderToRuntime(need.version, runtime);
+    if (!r.compatible && r.reason === 'major_mismatch_higher') {
+      errors.push(
+        `requires[${need.name}].version is ${need.version} but framework registry is ${runtime}. Bump the framework before publishing, or lower the manifest version.`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+export async function handleModulePublish(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const moduleDir = getArg(args, 0);
+  if (!moduleDir) {
+    return {
+      success: false,
+      error:
+        'Module directory required\n\nUsage: celilo module publish <module-dir> --token <token>',
+    };
+  }
+
+  const token = getFlag(flags, 'token', '') || process.env.CELILO_PUBLISH_TOKEN || '';
+  if (!token) {
+    return {
+      success: false,
+      error: 'Publish token required — pass --token <token> or set CELILO_PUBLISH_TOKEN',
+    };
+  }
+
+  const registryUrl = getFlag(flags, 'registry', '');
+  const revisionOverride = getFlag(flags, 'revision', '');
+  const message = getFlag(flags, 'message', '') || null;
+  const allowDirty = hasFlag(flags, 'allow-dirty');
+
+  if (revisionOverride) {
+    const parsed = Number(revisionOverride);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      return { success: false, error: '--revision must be a positive integer' };
+    }
+  }
+
+  const resolvedDir = resolve(moduleDir);
+
+  // Read manifest
+  let manifest: ManifestForPublish;
+  try {
+    const manifestRaw = await readFile(join(resolvedDir, 'manifest.yml'), 'utf-8');
+    manifest = parseYaml(manifestRaw) as ManifestForPublish;
+    if (!manifest.id || !manifest.version) {
+      return { success: false, error: 'manifest.yml missing id or version' };
+    }
+  } catch {
+    return { success: false, error: `Could not read manifest.yml in ${resolvedDir}` };
+  }
+  const name = manifest.id;
+  const baseVersion = manifest.version;
+
+  // Strict-publish: refuse on capability version mismatch (D4).
+  const capErrors = validateCapabilityVersions(manifest);
+  if (capErrors.length > 0) {
+    return {
+      success: false,
+      error: [
+        `Capability version validation failed for ${name}@${baseVersion}:`,
+        ...capErrors.map((e) => `  • ${e}`),
+      ].join('\n'),
+    };
+  }
+
+  // Collect git state. Refuse a dirty tree unless --allow-dirty.
+  const gitInfo = collectGitInfo(resolvedDir, makeRealGitRunner());
+  if (gitInfo.dirty && !allowDirty) {
+    return {
+      success: false,
+      error: [
+        `Working tree at ${resolvedDir} has uncommitted changes.`,
+        'Refusing to publish — commit (or stash) your changes, or pass --allow-dirty to override.',
+      ].join('\n'),
+    };
+  }
+
+  // Determine package revision: --revision flag, or query the registry for next rev
+  let revision: number;
+  if (revisionOverride) {
+    revision = Number(revisionOverride);
+  } else {
+    const client = new RegistryClient(registryUrl || undefined);
+    try {
+      const entries = await client.getIndex(name);
+      const existingRevs = entries
+        .filter((e) => e.vers.startsWith(`${baseVersion}+`))
+        .map((e) => Number(e.vers.split('+')[1]))
+        .filter((n) => Number.isInteger(n));
+      revision = existingRevs.length > 0 ? Math.max(...existingRevs) + 1 : 1;
+    } catch {
+      // Registry unreachable — start at +1
+      revision = 1;
+    }
+  }
+
+  const version = `${baseVersion}+${revision}`;
+
+  // Assemble release metadata for the .netapp.
+  const releaseMetadata = buildReleaseMetadata({
+    moduleId: name,
+    version,
+    git: gitInfo,
+    cliVersion: readInstalledCliVersion(),
+    message,
+  });
+
+  // Build the .netapp into a temp dir
+  const tmpPath = join(tmpdir(), `${name}-${version}-${Date.now()}.netapp`);
+  console.log(`Building ${name}@${version}...`);
+
+  const buildResult = await buildModule({
+    sourceDir: resolvedDir,
+    outputPath: tmpPath,
+    releaseMetadata,
+  });
+  if (!buildResult.success || !buildResult.packagePath) {
+    return { success: false, error: buildResult.error ?? 'Build failed' };
+  }
+
+  // Publish
+  const client = new RegistryClient(registryUrl || undefined);
+  try {
+    console.log(`Publishing ${name}@${version} to ${client.baseUrl}...`);
+    await client.publish({ name, version, netappPath: buildResult.packagePath, token });
+  } catch (err) {
+    return {
+      success: false,
+      error: `Publish failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  } finally {
+    await rm(tmpPath, { force: true });
+  }
+
+  return {
+    success: true,
+    message: `Published ${name}@${version}${message ? ` — "${message}"` : ''}`,
+    data: { name, version, releaseMetadata },
+  };
+}

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

@@ -7,10 +7,14 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { eq } from 'drizzle-orm';
+import { eq, ne } from 'drizzle-orm';
+import { FuelGauge } from '../../cli/fuel-gauge';
 import { getDb } from '../../db/client';
-import { moduleInfrastructure, modules } from '../../db/schema';
+import { capabilities as capabilitiesTable, moduleInfrastructure, modules } from '../../db/schema';
+import { createGaugeLogger } from '../../hooks/logger';
+import { runNamedHook } from '../../hooks/run-named-hook';
 import { deallocateForModule } from '../../ipam/auto-allocator';
+import { ModuleManifestSchema } from '../../manifest/schema';
 import { executeBuildWithProgress } from '../../services/build-stream';
 import { getContainerService, getServiceCredentials } from '../../services/container-service';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
@@ -61,6 +65,82 @@ export async function handleModuleRemove(
     };
   }
 
+  // Check if any other installed module requires a capability this module provides
+  const providedCapabilities = db
+    .select()
+    .from(capabilitiesTable)
+    .where(eq(capabilitiesTable.moduleId, moduleId))
+    .all();
+
+  if (providedCapabilities.length > 0) {
+    const providedNames = new Set(providedCapabilities.map((c) => c.capabilityName));
+    const otherModules = db.select().from(modules).where(ne(modules.id, moduleId)).all();
+
+    const dependents = otherModules
+      .filter((m) => {
+        const parsed = ModuleManifestSchema.safeParse(m.manifestData);
+        if (!parsed.success) return false;
+        return (parsed.data.requires?.capabilities ?? []).some((req) =>
+          providedNames.has(req.name),
+        );
+      })
+      .map((m) => m.id);
+
+    if (dependents.length > 0) {
+      return {
+        success: false,
+        error: `Cannot remove '${moduleId}': the following installed modules depend on its capabilities: ${dependents.join(', ')}`,
+      };
+    }
+  }
+
+  // Run on_uninstall hook (if defined) BEFORE terraform destroy. Hooks
+  // typically need the module's runtime to still be up so they can talk
+  // to remote services — e.g. caddy's teardown SSHes the caddy host to
+  // unexpose its ports + clear the Caddyfile, which can't happen after
+  // terraform has destroyed the LXC. Failures here are best-effort: we
+  // log the error and continue with removal so an operator can still
+  // unstick a half-broken module. Use --force to skip the confirmation
+  // prompt on hook failure.
+  const manifestForHook = module.manifestData as { hooks?: { on_uninstall?: unknown } } | undefined;
+  if (manifestForHook?.hooks?.on_uninstall) {
+    // Match build-stream's TTY detection: in non-TTY contexts (tests,
+    // pipes, --no-interactive flow) skipAnimation prevents the gauge's
+    // setInterval/raw-stdin handlers from blocking process exit.
+    const isInteractive = process.stdout.isTTY && process.stdin.isTTY;
+    const gauge = new FuelGauge(`${moduleId}: on_uninstall`, {
+      skipAnimation: !isInteractive,
+    });
+    gauge.start();
+    const logger = createGaugeLogger(gauge, moduleId, 'on_uninstall');
+    const hookResult = await runNamedHook(moduleId, 'on_uninstall', db, logger, {});
+    if (hookResult.success) {
+      gauge.stop(true);
+    } else {
+      gauge.stop(false);
+      log.warn(`on_uninstall failed: ${hookResult.error ?? 'unknown error'}`);
+      if (force) {
+        log.info('--force set, continuing removal despite hook failure');
+      } else if (!isInteractive) {
+        // Non-TTY (tests, scripts, piped input). Don't try to prompt —
+        // @clack/prompts hangs on stdin in that context. Default
+        // behaviour: continue with removal so a hook crash doesn't
+        // wedge automation. Operators who want strict failure can
+        // re-run `celilo module run-hook <id> on_uninstall` manually.
+        log.warn('Non-interactive context detected; continuing removal despite hook failure');
+      } else {
+        const proceed = await promptConfirm({
+          message:
+            'on_uninstall hook failed. Continue removing the module anyway? ' +
+            '(some external state may not be cleaned up)',
+        });
+        if (!proceed) {
+          return { success: false, error: 'Removal cancelled after on_uninstall failure' };
+        }
+      }
+    }
+  }
+
   // Check if module has infrastructure that needs to be destroyed
   const infra = db
     .select()

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

@@ -0,0 +1,57 @@
+/**
+ * Module search command — search the registry for modules
+ *
+ * Usage: celilo module search [<query>] [--registry <url>] [--limit <n>]
+ */
+
+import { RegistryClient } from '../../registry/client';
+import { getArg, getFlag } from '../parser';
+import type { CommandResult } from '../types';
+
+export async function handleModuleSearch(
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  const query = getArg(args, 0) ?? '';
+  const limit = Number(getFlag(flags, 'limit', '25'));
+  const registryUrl = getFlag(flags, 'registry', '');
+  const client = new RegistryClient(registryUrl || undefined);
+
+  let result: Awaited<ReturnType<typeof client.search>>;
+  try {
+    result = await client.search(query, limit);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Registry unreachable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (result.modules.length === 0) {
+    return {
+      success: true,
+      message: query ? `No modules found matching "${query}"` : 'Registry is empty',
+    };
+  }
+
+  const nameWidth = Math.max(4, ...result.modules.map((m) => m.name.length));
+  const versionWidth = Math.max(7, ...result.modules.map((m) => m.max_version.length));
+
+  const header = `${'NAME'.padEnd(nameWidth)}  ${'VERSION'.padEnd(versionWidth)}  DESCRIPTION`;
+  const divider = '-'.repeat(header.length);
+  const rows = result.modules.map(
+    (m) =>
+      `${m.name.padEnd(nameWidth)}  ${m.max_version.padEnd(versionWidth)}  ${m.description || ''}`,
+  );
+
+  const footer =
+    result.total > result.modules.length
+      ? `\n(showing ${result.modules.length} of ${result.total} — use --limit to see more)`
+      : '';
+
+  return {
+    success: true,
+    message: [header, divider, ...rows].join('\n') + footer,
+    data: result,
+  };
+}

package/src/cli/commands/module-secret-get.ts

@@ -0,0 +1,59 @@
+/**
+ * Module secret get command
+ * Retrieves and decrypts a module-level secret
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { secrets } from '../../db/schema';
+import { decryptSecret } from '../../secrets/encryption';
+import { getOrCreateMasterKey } from '../../secrets/master-key';
+import { getArg } from '../parser';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle module secret get command
+ *
+ * Usage: celilo module secret get <module-id> <key>
+ *
+ * @param args - Command arguments
+ * @returns Command result with decrypted secret value
+ */
+export async function handleModuleSecretGet(args: string[]): Promise<CommandResult> {
+  const moduleId = getArg(args, 0);
+  const key = getArg(args, 1);
+
+  if (!moduleId || !key) {
+    return {
+      success: false,
+      error: 'Usage: celilo module secret get <module-id> <key>',
+    };
+  }
+
+  const db = getDb();
+  const secret = db
+    .select()
+    .from(secrets)
+    .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, key)))
+    .get();
+
+  if (!secret) {
+    return {
+      success: false,
+      error: `Secret not found: ${moduleId}/${key}`,
+    };
+  }
+
+  const masterKey = await getOrCreateMasterKey();
+  const decrypted = decryptSecret(
+    { encryptedValue: secret.encryptedValue, iv: secret.iv, authTag: secret.authTag },
+    masterKey,
+  );
+
+  return {
+    success: true,
+    message: decrypted,
+    rawOutput: true,
+    data: { moduleId, key, value: decrypted },
+  };
+}

package/src/cli/commands/module-terraform-unlock.ts

@@ -0,0 +1,57 @@
+/**
+ * module terraform-unlock command
+ *
+ * Removes a stale Terraform state lock for a module.
+ * Only use this if you are certain no other deploy is running.
+ */
+
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import { validateRequiredArgs } from '../parser';
+import { log } from '../prompts';
+import type { CommandResult } from '../types';
+
+export async function handleModuleTerraformUnlock(args: string[]): Promise<CommandResult> {
+  const error = validateRequiredArgs(args, 1);
+  if (error) {
+    return {
+      success: false,
+      error: 'Usage: celilo module terraform-unlock <module-id>',
+    };
+  }
+
+  const moduleId = args[0];
+  const db = getDb();
+  const module = await db.select().from(modules).where(eq(modules.id, moduleId)).get();
+
+  if (!module) {
+    return { success: false, error: `Module not found: ${moduleId}` };
+  }
+
+  const lockFile = join(
+    module.sourcePath,
+    'generated',
+    'terraform',
+    '.terraform.tfstate.lock.info',
+  );
+
+  if (!existsSync(lockFile)) {
+    log.success(`No state lock found for ${moduleId}`);
+    return { success: true, message: `No state lock found for ${moduleId}` };
+  }
+
+  try {
+    rmSync(lockFile);
+    log.success(`State lock removed for ${moduleId}`);
+    log.message('You can now retry the deploy.');
+    return { success: true, message: `State lock removed for ${moduleId}` };
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to remove lock file: ${err instanceof Error ? err.message : String(err)}\n\nTry manually: rm ${lockFile}`,
+    };
+  }
+}

package/src/cli/commands/module-verify.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { moduleAudit } from './module-audit';
+import { moduleVerify } from './module-verify';
+
+describe('moduleVerify', () => {
+  test('returns error when module ID is missing', async () => {
+    const result = await moduleVerify([]);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain('Module ID is required');
+      expect(result.error).toContain('module verify');
+    }
+  });
+});
+
+describe('moduleAudit (deprecation alias)', () => {
+  let dataDir: string;
+  const originalDataDir = process.env.CELILO_DATA_DIR;
+  const originalDbPath = process.env.CELILO_DB_PATH;
+
+  beforeEach(() => {
+    dataDir = mkdtempSync(join(tmpdir(), 'celilo-audit-alias-'));
+    process.env.CELILO_DATA_DIR = dataDir;
+    process.env.CELILO_DB_PATH = join(dataDir, 'celilo.db');
+  });
+
+  afterEach(() => {
+    rmSync(dataDir, { recursive: true, force: true });
+    if (originalDataDir === undefined) process.env.CELILO_DATA_DIR = undefined;
+    else process.env.CELILO_DATA_DIR = originalDataDir;
+    if (originalDbPath === undefined) process.env.CELILO_DB_PATH = undefined;
+    else process.env.CELILO_DB_PATH = originalDbPath;
+  });
+
+  test('writes a deprecation warning to stderr and delegates to verify', async () => {
+    const writes: Buffer[] = [];
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    // Narrower override is fine for the duration of the test; cast to
+    // bypass the overload set on Process['stderr']['write'].
+    process.stderr.write = ((chunk: string | Buffer) => {
+      writes.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      const result = await moduleAudit([]); // no args triggers the same arg-error
+      expect(result.success).toBe(false);
+    } finally {
+      process.stderr.write = originalWrite;
+    }
+
+    const stderr = Buffer.concat(writes).toString('utf-8');
+    expect(stderr).toContain('deprecated');
+    expect(stderr).toContain('module verify');
+  });
+});

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

@@ -0,0 +1,53 @@
+import { auditModule } from '../../module/packaging/audit';
+import type { CommandResult } from '../types';
+
+/**
+ * Verify module integrity (signature + checksums).
+ *
+ * Usage: celilo module verify <module-id>
+ *
+ * Renamed from `module audit` per CELILO_UPDATE D11 — `audit` is now
+ * reserved for system-level drift detection (`celilo system audit`).
+ * The legacy `module audit` continues to work via a deprecation alias
+ * (see `module-audit.ts`).
+ *
+ * Returns a CommandResult so the dispatcher controls process exit
+ * behavior.
+ */
+export async function moduleVerify(args: string[]): Promise<CommandResult> {
+  if (args.length === 0) {
+    return {
+      success: false,
+      error: 'Module ID is required\n\nUsage: celilo module verify <module-id>',
+    };
+  }
+
+  const moduleId = args[0];
+
+  const result = await auditModule(moduleId);
+
+  if (result.error) {
+    return { success: false, error: result.error };
+  }
+
+  if (result.success) {
+    return {
+      success: true,
+      message: `Module '${moduleId}' passed integrity check\n  No violations found.`,
+    };
+  }
+
+  const violationLines = result.violations.map((v) => {
+    const icon = v.type === 'missing' ? '⚠' : v.type === 'modified' ? '✗' : '!';
+    return `  ${icon} [${v.type.toUpperCase()}] ${v.message}`;
+  });
+
+  return {
+    success: false,
+    error: [
+      `Module '${moduleId}' failed integrity check`,
+      `  Found ${result.violations.length} violation(s):`,
+      ...violationLines,
+    ].join('\n'),
+  };
+}