@celilo/cli 0.3.16 → 0.3.18

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

@@ -4,21 +4,16 @@
  */
 
 import * as p from '@clack/prompts';
-import {
-  buildTemplateUrl,
-  checkTaskStatus,
-  downloadTemplate,
-  extractTemplateFilename,
-} from '../../api-clients/proxmox';
+import { extractTemplateFilename } from '../../api-clients/proxmox';
 import {
   type ProxmoxCredentials,
   getContainerServiceByServiceId,
   getServiceCredentials,
   verifyContainerService,
 } from '../../services/container-service';
-import { FuelGauge } from '../fuel-gauge';
 import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
+import { runApplianceDownload } from './proxmox-template-selection';
 
 /**
  * Handle service verify command
@@ -108,7 +103,6 @@ export async function handleServiceVerify(
 
       if (shouldDownload) {
         try {
-          // Get credentials and config
           const credentials = (await getServiceCredentials(service.id)) as ProxmoxCredentials;
           const providerConfig = service.providerConfig as {
             default_target_node: string;
@@ -116,86 +110,33 @@ export async function handleServiceVerify(
             storage: string;
           };
 
-          // Extract template info
           const templateFilename = extractTemplateFilename(providerConfig.lxc_template);
-          const templateParts = providerConfig.lxc_template.split(':');
-          const templateStorage = templateParts[0] || 'local';
-
-          // Detect Ubuntu version from template filename
-          const versionMatch = templateFilename.match(/ubuntu-(\d+\.\d+)-/);
-          if (!versionMatch) {
-            return {
-              success: false,
-              error: 'Cannot auto-download: unrecognized template format',
-            };
-          }
-          const ubuntuVersion = versionMatch[1];
-
-          const templateUrl = buildTemplateUrl(ubuntuVersion);
+          const templateStorage = providerConfig.lxc_template.split(':')[0] || 'local';
 
-          const downloadResult = await downloadTemplate(
+          // The saved volid was the canonical filename when the service was
+          // created; if Proxmox refreshed the revision since then, this download
+          // will fail with `started-failed` and the user can `service reconfigure`
+          // to pick a fresh filename from the catalog.
+          const outcome = await runApplianceDownload({
             credentials,
-            providerConfig.default_target_node,
+            targetNode: providerConfig.default_target_node,
             templateStorage,
-            templateUrl,
-          );
-
-          if (!downloadResult.success) {
-            return {
-              success: false,
-              error: `Failed to download template: ${downloadResult.message}`,
-            };
-          }
-
-          // Wait for download to complete with fuel-gauge progress
-          const upid = downloadResult.data;
-          const gauge = new FuelGauge(`Downloading ${templateFilename}`);
-          gauge.start();
-
-          let downloadComplete = false;
-          let attempts = 0;
-          const maxAttempts = 60; // 5 minutes
-
-          while (!downloadComplete && attempts < maxAttempts) {
-            await new Promise((resolve) => setTimeout(resolve, 5000));
-
-            const statusResult = await checkTaskStatus(
-              credentials,
-              providerConfig.default_target_node,
-              upid,
-            );
-
-            if (statusResult.success) {
-              if (statusResult.data.status === 'stopped') {
-                if (statusResult.data.exitstatus === 'OK') {
-                  downloadComplete = true;
-                  gauge.stop(true);
-                } else {
-                  gauge.stop(false);
-                  return {
-                    success: false,
-                    error: `Template download failed: ${statusResult.data.exitstatus}\n\nThis usually means the Proxmox host cannot reach download.proxmox.com.\n\nTroubleshooting:\n  1. SSH into your Proxmox host and test: curl -I https://download.proxmox.com\n  2. Try downloading manually: pveam download ${templateStorage} ${templateFilename}\n  3. Choose a different Ubuntu version: celilo service reconfigure ${service.serviceId}\n  4. Check DNS and firewall settings on the Proxmox host`,
-                  };
-                }
-              } else {
-                gauge.addOutput(`Status: ${statusResult.data.status} (${attempts * 5}s elapsed)`);
-              }
-            } else {
-              gauge.addOutput(`Waiting for status... (${attempts * 5}s elapsed)`);
-            }
-
-            attempts++;
-          }
-
-          if (!downloadComplete) {
-            gauge.stop(false);
+            templateFilename,
+          });
+
+          if (!outcome.ready) {
+            const detail =
+              outcome.reason === 'task-failed'
+                ? `pveam download exited with status: ${outcome.exitStatus ?? 'unknown'}\n\nThis usually means the saved template revision is no longer available on Proxmox's mirror.`
+                : outcome.reason === 'started-failed'
+                  ? `Proxmox rejected the download request: ${outcome.startError ?? 'unknown error'}\n\nThis usually means the saved template name does not match Proxmox's current catalog.`
+                  : 'Template download did not complete in time. The Proxmox host may have slow internet or connectivity issues.';
             return {
               success: false,
-              error: `Template download timed out after 5 minutes.\n\nThe Proxmox host may have slow internet or connectivity issues.\nTry downloading manually: ssh root@<proxmox-host> pveam download ${templateStorage} ${templateFilename}`,
+              error: `${detail}\n\nTroubleshooting:\n  1. Pick a fresh template version: celilo service reconfigure ${service.serviceId}\n  2. SSH into your Proxmox host and run: pveam update && pveam download ${templateStorage} ${templateFilename}\n  3. Check DNS and firewall settings on the Proxmox host`,
             };
           }
 
-          // Retry verification
           console.log('\nRetrying verification...');
           const retryResult = await verifyContainerService(service.id);
 

package/src/cli/commands/{doctor.test.ts → system-doctor.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { compareVersions } from './doctor';
+import { compareVersions } from './system-doctor';
 
 describe('compareVersions', () => {
   test('detects ascending major/minor/patch', () => {

package/src/cli/commands/{doctor.ts → system-doctor.ts}

@@ -1,19 +1,32 @@
 /**
- * `celilo doctor` — diagnose @celilo/* version drift between the running CLI
- * and the surrounding workspace (if any).
+ * `celilo system doctor` — diagnose system-level health for celilo:
+ *   1. System prerequisites (ansible, terraform, ssh, etc.) present
+ *      and at supported versions.
+ *   2. @celilo/* version drift between the running CLI and the
+ *      surrounding workspace (if any).
  *
- * Catches the canonical "I edited the workspace but my global celilo is
- * still running an older published version" failure mode.
+ * The canonical failures this catches:
+ *   - "I just installed celilo on a fresh box but module import is
+ *     erroring with a child-process exit 127." → prereq section.
+ *   - "I edited the workspace but my global celilo is still running
+ *     an older published version." → drift section.
  *
- * Resolution strategy:
- *   - The running CLI's package.json comes from a relative import — that
- *     anchors us to whatever copy of `@celilo/cli` is actually executing
- *     (workspace TS source or globally-installed node_modules tree).
+ * Renamed from top-level `celilo doctor` (Phase 0; no alias kept) to
+ * fit alongside `system init`, `system audit`, `system config`. See
+ * apps/celilo/designs/PREREQ_DETECTION.md.
+ *
+ * Drift resolution strategy:
+ *   - The running CLI's package.json comes from a relative import —
+ *     that anchors us to whatever copy of `@celilo/cli` is actually
+ *     executing (workspace TS source or globally-installed
+ *     node_modules tree).
  *   - For each `@celilo/*` dependency, we ask the runtime where it
- *     resolves the package's `package.json` and read the version there.
- *   - If we can find a workspace root by walking up from `process.cwd()`,
- *     we read each `packages/*\/package.json` and flag anything where the
- *     loaded version is older than the workspace.
+ *     resolves the package's `package.json` and read the version
+ *     there.
+ *   - If we can find a workspace root by walking up from
+ *     `process.cwd()`, we read each `packages/*\/package.json` and
+ *     flag anything where the loaded version is older than the
+ *     workspace.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -21,6 +34,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import cliPkg from '../../../package.json' with { type: 'json' };
+import { checkAllPrerequisites, failingPrerequisites } from '../../system/prereqs';
 import type { CommandResult } from '../types';
 
 interface CeliloPkgInfo {
@@ -247,7 +261,42 @@ function applyFix(drifted: DriftedDep[], cliRoot: string): string[] {
   return lines;
 }
 
-export async function handleDoctor(
+/**
+ * Render the system-prerequisites block: every tool from the
+ * PREREQUISITES table with its detection result, formatted into the
+ * doctor's output column-aligned style.
+ */
+function renderPrereqSection(): { lines: string[]; failingCount: number } {
+  const checks = checkAllPrerequisites();
+  const lines: string[] = [];
+
+  lines.push('System prerequisites');
+  // Right-pad column for alignment. Take the longest tool name +1
+  // for spacing.
+  const nameCol = Math.max(...checks.map((c) => c.name.length), 12);
+
+  for (const c of checks) {
+    if (c.present && c.meetsMinimum) {
+      const version = c.version ? c.version : `${ANSI.dim}(version unknown)${ANSI.reset}`;
+      lines.push(`  ${ANSI.green}✔${ANSI.reset} ${c.name.padEnd(nameCol)}  ${version}`);
+    } else if (c.present && !c.meetsMinimum) {
+      // Present but below minimum (or version-parse failed with a minimum).
+      const detail = c.version ? `${c.version} — below minimum required` : 'version unreadable';
+      lines.push(`  ${ANSI.yellow}⚠${ANSI.reset} ${c.name.padEnd(nameCol)}  ${detail}`);
+      lines.push(`    ${ANSI.dim}install: ${c.installHint}${ANSI.reset}`);
+    } else {
+      // Missing entirely.
+      lines.push(
+        `  ${ANSI.red}✗${ANSI.reset} ${c.name.padEnd(nameCol)}  ${ANSI.dim}not installed${ANSI.reset}`,
+      );
+      lines.push(`    ${ANSI.dim}install: ${c.installHint}${ANSI.reset}`);
+    }
+  }
+
+  return { lines, failingCount: failingPrerequisites(checks).length };
+}
+
+export async function handleSystemDoctor(
   _args: string[],
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
@@ -261,6 +310,12 @@ export async function handleDoctor(
   lines.push(`${ANSI.dim}running from ${cliRoot}${ANSI.reset}`);
   lines.push('');
 
+  // System prerequisites first — they're the most common reason a
+  // fresh management box can't run modules.
+  const prereqResult = renderPrereqSection();
+  lines.push(...prereqResult.lines);
+  lines.push('');
+
   const workspaceRoot = findWorkspaceRoot(process.cwd());
   const workspaceVersions = workspaceRoot ? collectWorkspaceVersions(workspaceRoot) : [];
   const workspaceMap = new Map(workspaceVersions.map((w) => [w.name, w]));
@@ -347,8 +402,17 @@ export async function handleDoctor(
     lines.push(...applyFix(drifted, cliRoot));
     lines.push('');
     lines.push(
-      `${ANSI.dim}Re-run \`celilo doctor\` to verify; \`bun unlink\` from each workspace dir reverses.${ANSI.reset}`,
+      `${ANSI.dim}Re-run \`celilo system doctor\` to verify; \`bun unlink\` from each workspace dir reverses.${ANSI.reset}`,
     );
+    // Note: --fix only addresses drift, not missing prereqs. If prereqs
+    // failed, surface that even on a successful --fix run.
+    if (prereqResult.failingCount > 0) {
+      return {
+        success: false,
+        error: `${prereqResult.failingCount} system prerequisite(s) missing or below minimum — install before running celilo`,
+        details: lines.join('\n'),
+      };
+    }
     return {
       success: true,
       message: lines.join('\n'),
@@ -360,23 +424,34 @@ export async function handleDoctor(
     lines.push(`${ANSI.dim}--fix: nothing to repair.${ANSI.reset}`);
   }
 
-  if (driftCount > 0 || unresolvedCount > 0) {
+  if (driftCount > 0 || unresolvedCount > 0 || prereqResult.failingCount > 0) {
     const summary: string[] = [];
+    if (prereqResult.failingCount > 0) {
+      summary.push(`${prereqResult.failingCount} prerequisite(s) missing/below-minimum`);
+    }
     if (driftCount > 0) summary.push(`${driftCount} package(s) behind workspace`);
     if (unresolvedCount > 0) summary.push(`${unresolvedCount} unresolved`);
     if (drifted.length > 0) {
       lines.push(
-        `${ANSI.dim}Run \`celilo doctor --fix\` to bun-link drifted packages from the workspace.${ANSI.reset}`,
+        `${ANSI.dim}Run \`celilo system doctor --fix\` to bun-link drifted packages from the workspace.${ANSI.reset}`,
       );
     }
+    // Distinguish prereq-only from drift-only from both — the
+    // operator's next move is different.
+    const errorPrefix =
+      driftCount === 0 && unresolvedCount === 0
+        ? 'System prerequisites missing'
+        : prereqResult.failingCount === 0
+          ? 'Drift detected'
+          : 'Issues detected';
     return {
       success: false,
-      error: `Drift detected: ${summary.join(', ')}`,
+      error: `${errorPrefix}: ${summary.join(', ')}`,
       details: lines.join('\n'),
     };
   }
 
-  lines.push(`${ANSI.green}OK${ANSI.reset} — no drift detected`);
+  lines.push(`${ANSI.green}OK${ANSI.reset} — no issues detected`);
   return {
     success: true,
     message: lines.join('\n'),

package/src/cli/commands/system-update.ts

@@ -142,7 +142,7 @@ async function buildSnapshots(
  * - `backup` calls `createModuleBackup`. Modules without an
  *   `on_backup` hook return ok (nothing to back up; not an error).
  * - `upgrade` is a no-op for now — the in-place upgrade path lives
- *   in `module install <name>` and needs a refactor before the
+ *   in `module import <name>` and needs a refactor before the
  *   orchestrator can drive it cleanly. Deploy will re-converge
  *   against whatever's installed, which is the right behavior for
  *   "redeploy what's there."

package/src/cli/completion.ts

@@ -32,7 +32,6 @@ export async function getCompletions(words: string[], current: number): Promise<
       'backup',
       'capability',
       'completion',
-      'doctor',
       'events',
       'help',
       'hook',
@@ -122,8 +121,8 @@ export async function getCompletions(words: string[], current: number): Promise<
   // Module subcommands
   if (command === 'module' && currentIndex === 1) {
     const subcommands = [
+      'check',
       'import',
-      'install',
       'list',
       'publish',
       'remove',
@@ -150,11 +149,6 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(subcommands, args[1] || '');
   }
 
-  // Module import subcommands (celilo module import file|public-registry)
-  if (command === 'module' && args[1] === 'import' && currentIndex === 2) {
-    return filterSuggestions(['file', 'public-registry'], args[2] || '');
-  }
-
   // Module config subcommands (celilo module config set/get)
   if (command === 'module' && args[1] === 'config' && currentIndex === 2) {
     const subcommands = ['set', 'get'];
@@ -437,7 +431,7 @@ export async function getCompletions(words: string[], current: number): Promise<
 
   // System subcommands
   if (command === 'system' && currentIndex === 1) {
-    const subcommands = ['init', 'config', 'secret', 'vault-password', 'audit', 'update'];
+    const subcommands = ['init', 'config', 'secret', 'vault-password', 'audit', 'update', 'doctor'];
     return filterSuggestions(subcommands, args[1] || '');
   }
 
@@ -518,3 +512,30 @@ _celilo() {
 compdef _celilo celilo
 `;
 }
+
+/**
+ * Generate fish completion script.
+ *
+ * Fish doesn't have an equivalent of bash's `compgen -W` or zsh's `compadd`,
+ * so we register a single dynamic completer that calls the CLI's
+ * --get-completions hook on each TAB. The CLI emits one completion per line;
+ * fish picks them up as candidates.
+ *
+ * The shell context fish exposes is `commandline -opc` (tokens before the
+ * in-progress word) plus `commandline -ct` (the in-progress word). We
+ * recombine them into the same words + cword shape the bash/zsh wrappers
+ * use, so the same TypeScript completion logic serves all three shells.
+ */
+export function generateFishCompletion(): string {
+  return `# Celilo fish completion
+function __celilo_complete
+    set -l tokens (commandline -opc)
+    set -l current (commandline -ct)
+    set -l words celilo $tokens[2..-1] $current
+    set -l cword (math (count $words) - 1)
+    celilo --get-completions $words $cword 2>/dev/null
+end
+
+complete -c celilo -f -a '(__celilo_complete)'
+`;
+}

package/src/cli/index.ts

@@ -10,7 +10,6 @@ import { COMMANDS, type CommandDef } from './command-registry';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
-import { handleDoctor } from './commands/doctor';
 import {
   handleEventsAck,
   handleEventsDrain,
@@ -45,11 +44,12 @@ import { handleMachineRemove } from './commands/machine-remove';
 import { handleMachineStatus } from './commands/machine-status';
 import { moduleAudit } from './commands/module-audit';
 import { handleModuleBuild } from './commands/module-build';
+import { handleModuleCheck } from './commands/module-check';
 import { handleModuleConfigGet, handleModuleConfigSet } from './commands/module-config';
 import { handleModuleDeploy } from './commands/module-deploy';
 import { handleModuleGenerate } from './commands/module-generate';
 import { handleModuleHealth } from './commands/module-health';
-import { handleModuleImport, handlePublicRegistryImport } from './commands/module-import';
+import { handleModuleImport } from './commands/module-import';
 import { handleModuleList } from './commands/module-list';
 import { handleModuleLogs } from './commands/module-logs';
 import { handleModulePublish } from './commands/module-publish';
@@ -75,6 +75,7 @@ import { handleServiceVerify } from './commands/service-verify';
 import { handleStatus } from './commands/status';
 import { handleSystemAudit } from './commands/system-audit';
 import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
+import { handleSystemDoctor } from './commands/system-doctor';
 import { handleSystemInit } from './commands/system-init';
 import { handleSystemSecretGet } from './commands/system-secret-get';
 import { handleSystemSecretSet } from './commands/system-secret-set';
@@ -148,7 +149,6 @@ Usage:
 
 Commands:
   status                   Show system and module status
-  doctor                   Diagnose @celilo/* version drift between the running CLI and the workspace
   audit                    Top-level alias for 'system audit'
   events                   SQLite event-bus operations (status, tail, run dispatcher, etc.)
   capability               View registered module capabilities
@@ -218,7 +218,7 @@ Examples:
   celilo package ../custom-module
 
 Related Commands:
-  celilo module import <package.netapp>    Import a packaged module
+  celilo module import <name-or-path>      Import a module (registry name or local path)
   celilo module verify <module-id>         Verify package integrity
 `;
 
@@ -313,8 +313,9 @@ Usage:
   celilo module <subcommand> [args...] [options]
 
 Subcommands:
-  import <path>                        Import a module from directory or .netapp file
+  import <name-or-path>                Import a module from the registry (bare name) or a local path
     Options:
+      --registry <url>                 Use a custom registry (default: https://celilo.computer/registry)
       --target <path>                  Target base directory (default: platform-specific)
       --auto-generate-secrets          Auto-generate all secrets without prompting
 
@@ -359,10 +360,6 @@ Subcommands:
   update <path> [path...]               Update module code while preserving state (configs, secrets, infra)
 
 Registry:
-  install <name>                       Download and import a module from the registry
-    Options:
-      --registry <url>                 Use a custom registry (default: https://celilo.computer/registry)
-
   search [query]                       Search the registry for modules
     Options:
       --registry <url>                 Use a custom registry
@@ -377,15 +374,21 @@ Registry:
       --allow-dirty                    Permit publishing from a dirty git tree
       --allow-stale                    Skip the manifest-vs-src stale-check. Use sparingly.
 
+  check [path]                         Check a module for drift against the framework (default: .)
+    Options:
+      --no-build                       Skip the TypeScript build check
+      --json                           Emit a structured Check[] payload (CI-friendly)
+      --strict                         Treat warnings as failures
+
 Examples:
-  celilo module install caddy
-  celilo module install namecheap --registry https://my-registry.example.com/registry
+  celilo module import caddy                       # registry (bare name)
+  celilo module import namecheap --registry https://my-registry.example.com/registry
+  celilo module import ./modules/homebridge        # local directory
+  celilo module import homebridge.netapp           # local .netapp file
+  celilo module import /abs/path/to/module --target /custom/location
   celilo module search dns
   celilo module publish ./modules/caddy --token mytoken
   celilo module publish ./modules/*                # publish every module in a dir
-  celilo module import ./modules/homebridge
-  celilo module import homebridge.netapp
-  celilo module import /abs/path/to/module --target /custom/location
   celilo module list
   celilo module remove homebridge
   celilo module verify homebridge
@@ -787,6 +790,8 @@ Subcommands:
   update [--module <id>] [--no-backup] [--allow-destructive] [--dry-run] [--json]
                                        Bring the system to the audit-determined READY state
 
+  doctor [--fix]                       Diagnose system prerequisites and @celilo/* version drift
+
 Runbook:
   https://celilo.computer/docs/system-update
   (offline summary in apps/celilo/docs/INDEX.md)
@@ -907,11 +912,6 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     return handleStatus();
   }
 
-  // Handle doctor command
-  if (parsed.command === 'doctor') {
-    return handleDoctor(parsed.args, parsed.flags);
-  }
-
   // Top-level alias: `celilo audit` → `celilo system audit`
   if (parsed.command === 'audit') {
     return handleSystemAudit(parsed.args, parsed.flags);
@@ -1162,19 +1162,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleShowZone(parsed.args);
       case 'search':
         return handleModuleSearch(parsed.args, parsed.flags);
-      case 'install': {
-        // `celilo module install <name>` — shorthand for `module import public-registry <name>`
-        const name = parsed.args[0] ?? parsed.subcommand;
-        if (!name) {
-          return {
-            success: false,
-            error: 'Module name required\n\nUsage: celilo module install <name> [--registry <url>]',
-          };
-        }
-        return handlePublicRegistryImport(name, parsed.flags);
-      }
       case 'publish':
         return handleModulePublish(parsed.args, parsed.flags);
+      case 'check':
+        return handleModuleCheck(parsed.args, parsed.flags);
       default:
         return {
           success: false,
@@ -1512,6 +1503,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleSystemUpdate(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'doctor') {
+      return handleSystemDoctor(parsed.args, parsed.flags);
+    }
+
     return {
       success: false,
       error: `Unknown system subcommand: ${parsed.subcommand}\n\nRun "celilo system --help" for usage`,

package/src/manifest/schema.ts

@@ -95,7 +95,10 @@ export const SecretGenerateSchema = z.object({
 
 export const SecretDeclareSchema = z.object({
   name: z.string().min(1),
-  type: z.enum(['string', 'integer', 'number']).default('string'),
+  // `string-map` is `Record<string, string>` (e.g. domain → password). It's
+  // stored as JSON.stringify'd text on disk, but the interview uses an
+  // add-loop UX so the operator never has to type JSON braces.
+  type: z.enum(['string', 'integer', 'number', 'string-map']).default('string'),
   required: z.boolean().default(false),
   description: z.string().optional(),
   sensitive: z.boolean().default(true), // Don't log in CLI output
@@ -104,6 +107,11 @@ export const SecretDeclareSchema = z.object({
   minimum: z.number().optional(),
   maximum: z.number().optional(),
   pattern: z.string().optional(),
+  // For `type: string-map` only: human-readable labels shown in the
+  // add-loop prompt. Defaults are 'key' / 'value' which are usually too
+  // generic; namecheap wants 'Domain' / 'Password'.
+  key_label: z.string().optional(),
+  value_label: z.string().optional(),
 });
 
 /**

package/src/module/import.ts

@@ -417,8 +417,10 @@ async function installScriptDependencies(
     return;
   }
 
-  // Run bun install in the scripts directory
-  log.info('Installing script dependencies...');
+  // Run bun install in the scripts directory. The bun-install can take a
+  // few seconds on a cold cache, so we surface a status line — silent
+  // pauses look like hangs.
+  log.info('Installing dependencies for module hook scripts...');
   execSync('bun install', {
     cwd: scriptsDir,
     timeout: 120_000,

package/src/registry/client.ts

@@ -115,11 +115,24 @@ export class RegistryClient {
     version: string;
     netappPath: string;
     token: string;
+    /**
+     * One-line description from the module's manifest.yml. Optional
+     * (server tolerates absence) but recommended — it's what shows
+     * up in the registry's browse UI per
+     * apps/celilo/designs/REGISTRY_BROWSE_UI.md (Phase 2 step 0).
+     */
+    description?: string;
   }): Promise<{ ok: boolean; name: string; vers: string }> {
     const fileData = await readFile(opts.netappPath);
     const cksum = `sha256:${createHash('sha256').update(fileData).digest('hex')}`;
 
-    const meta = JSON.stringify({ name: opts.name, vers: opts.version, deps: [], cksum });
+    const meta = JSON.stringify({
+      name: opts.name,
+      vers: opts.version,
+      deps: [],
+      cksum,
+      ...(opts.description ? { description: opts.description } : {}),
+    });
     const metaBuf = Buffer.from(meta, 'utf-8');
 
     const body = Buffer.allocUnsafe(4 + metaBuf.length + 4 + fileData.length);

package/src/services/bus-interview.ts

@@ -70,11 +70,23 @@ export interface ConfigReply {
 export interface SecretRequiredPayload {
   module: string;
   key: string;
-  type: 'string' | 'integer' | 'number';
+  /**
+   * `string-map` = Record<string, string>; the responder runs an
+   * add-loop and serializes to JSON before storing, so the operator
+   * never types braces or commas. See terminal-responder.ts for the UX.
+   */
+  type: 'string' | 'integer' | 'number' | 'string-map';
   required: boolean;
   description?: string;
   style?: 'user_provided' | 'user_password' | 'generated_optional';
   generate?: { format: string; length: number };
+  /**
+   * For `type: string-map` only — labels shown in the add-loop prompt.
+   * Defaults to 'key' / 'value' when absent. namecheap uses
+   * 'Domain' / 'Password'.
+   */
+  key_label?: string;
+  value_label?: string;
 }
 
 export interface SecretAck {