@celilo/cli 0.3.17 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/command-registry.ts

@@ -255,27 +255,21 @@ export const COMMANDS: CommandDef[] = [
     subcommands: [
       {
         name: 'import',
-        description: 'Import a module (file <path> | public-registry <name>)',
-        subcommands: [
-          {
-            name: 'file',
-            description: 'Import from local filesystem',
-            args: [{ name: 'path', description: 'Module path', completion: 'directories' }],
-          },
+        description:
+          'Import a module from the registry (bare name) or from a local path (./, /, ~, or *.netapp)',
+        args: [
           {
-            name: 'public-registry',
-            description: 'Import from celilo.computer registry',
-            args: [{ name: 'name', description: 'Module name' }],
-            flags: [
-              {
-                name: 'registry',
-                description: 'Registry URL (overrides default celilo.computer)',
-                takesValue: true,
-              },
-            ],
+            name: 'name-or-path',
+            description: 'Module name (registry) or filesystem path',
+            completion: 'directories',
           },
         ],
         flags: [
+          {
+            name: 'registry',
+            description: 'Registry URL (overrides default celilo.computer)',
+            takesValue: true,
+          },
           {
             name: 'target',
             description: 'Target directory',
@@ -477,12 +471,6 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
-      {
-        name: 'install',
-        description: 'Download and import a module from the registry',
-        args: [{ name: 'name', description: 'Module name' }],
-        flags: [{ name: 'registry', description: 'Registry URL', takesValue: true }],
-      },
       {
         name: 'search',
         description: 'Search the module registry',

package/src/cli/commands/module-import-routing.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Tests for the import-routing rule that disambiguates between
+ *   `celilo module import caddy`             → registry
+ *   `celilo module import ./modules/caddy`   → local path
+ *
+ * Pure function over the argument string; no network, no filesystem.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { classifyImportArg } from './module-import';
+
+describe('classifyImportArg', () => {
+  test('routes bare kebab names to the registry', () => {
+    expect(classifyImportArg('caddy')).toBe('name');
+    expect(classifyImportArg('homebridge')).toBe('name');
+    expect(classifyImportArg('dns-external')).toBe('name');
+    expect(classifyImportArg('a')).toBe('name');
+  });
+
+  test('routes leading-dot relative paths to the filesystem', () => {
+    expect(classifyImportArg('./modules/caddy')).toBe('path');
+    expect(classifyImportArg('../caddy')).toBe('path');
+    expect(classifyImportArg('./caddy')).toBe('path');
+  });
+
+  test('routes leading-slash absolute paths to the filesystem', () => {
+    expect(classifyImportArg('/tmp/caddy')).toBe('path');
+    expect(classifyImportArg('/abs/path/to/module')).toBe('path');
+  });
+
+  test('routes tilde-expanded paths to the filesystem', () => {
+    expect(classifyImportArg('~')).toBe('path');
+    expect(classifyImportArg('~/dev/caddy')).toBe('path');
+  });
+
+  test('routes any path containing / to the filesystem', () => {
+    expect(classifyImportArg('modules/caddy')).toBe('path');
+    expect(classifyImportArg('a/b/c')).toBe('path');
+  });
+
+  test('routes .netapp filenames to the filesystem (registry never serves them by name)', () => {
+    expect(classifyImportArg('caddy.netapp')).toBe('path');
+    expect(classifyImportArg('homebridge-1.0.0.netapp')).toBe('path');
+  });
+
+  test('does not confuse versioned names with paths (no slash, no .netapp)', () => {
+    // Future: registry may accept `name@version` syntax. Today this routes
+    // to "name" — KEBAB_NAME validation in handleModuleImport will reject
+    // until the syntax is implemented.
+    expect(classifyImportArg('caddy@1.0.0')).toBe('name');
+  });
+});

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

@@ -1,7 +1,23 @@
 /**
  * Module import command
+ *
+ * Single entry point for both registry and local-source imports. Routing
+ * is determined by the shape of the argument:
+ *
+ *   celilo module import caddy                 → registry  (kebab name)
+ *   celilo module import ./modules/caddy       → local dir  (relative path)
+ *   celilo module import /tmp/caddy.netapp     → local file (absolute path)
+ *   celilo module import ~/dev/caddy           → local dir  (tilde-expanded)
+ *   celilo module import caddy.netapp          → local file (.netapp extension)
+ *
+ * The previous CLI surface had three overlapping commands for this:
+ * `module install` (registry-only shorthand), `module import public-registry`
+ * (registry, verbose), and `module import file` (local, verbose). All have
+ * been collapsed into this one command — the routing rule below is the
+ * canonical disambiguator.
  */
 
+import { existsSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -14,47 +30,74 @@ import type { CommandResult } from '../types';
 import { generateTypesForImportedModule } from './module-types';
 
 const USAGE = `Usage:
-  celilo module import file <path>              Import from local filesystem
-  celilo module import public-registry <name>   Import from celilo.computer registry`;
+  celilo module import <name>      Import from celilo.computer registry
+  celilo module import <path>      Import from a local directory or .netapp file
+
+Examples:
+  celilo module import caddy
+  celilo module import ./modules/caddy
+  celilo module import /tmp/caddy.netapp`;
 
 /**
- * Handle module import command
+ * Decide whether the user's argument should route to local-filesystem
+ * import or registry import. Path-like arguments win — see header comment
+ * for the routing rules. Anything else is treated as a registry name
+ * (validated against the kebab-case rule before the network call).
  *
- * Usage: celilo module import file <path> [--target <path>]
- *        celilo module import public-registry <name>
- *        celilo module import <path>  (alias for "file", kept for compatibility)
+ * Exposed for tests; not exported from the package.
  */
+export function classifyImportArg(arg: string): 'path' | 'name' {
+  if (arg.startsWith('/') || arg.startsWith('./') || arg.startsWith('../')) return 'path';
+  if (arg.startsWith('~/') || arg === '~') return 'path';
+  if (arg.includes('/')) return 'path';
+  if (arg.endsWith('.netapp')) return 'path';
+  return 'name';
+}
+
+const KEBAB_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
 export async function handleModuleImport(
   args: string[],
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
-  const subcommand = getArg(args, 0);
+  const arg = getArg(args, 0);
 
-  if (!subcommand) {
-    return { success: false, error: `Subcommand required.\n\n${USAGE}` };
+  if (!arg) {
+    return { success: false, error: `Module name or path required.\n\n${USAGE}` };
   }
 
-  if (subcommand === 'public-registry') {
-    const moduleName = getArg(args, 1);
-    if (!moduleName) {
-      return { success: false, error: `Module name required.\n\n${USAGE}` };
+  if (classifyImportArg(arg) === 'name') {
+    if (!KEBAB_NAME.test(arg)) {
+      return {
+        success: false,
+        error: `Not a valid module name or path: '${arg}'.\n\n${USAGE}\n\nModule names are kebab-case (lowercase letters, digits, hyphens). For local paths, use ./, /, ~/, or include / in the argument.`,
+      };
     }
-    return handlePublicRegistryImport(moduleName, flags);
+    return handlePublicRegistryImport(arg, flags);
   }
 
-  // Resolve the source path: "file <path>" or bare "<path>" alias
-  const sourcePath = subcommand === 'file' ? getArg(args, 1) : subcommand;
-
-  if (!sourcePath) {
-    return { success: false, error: `Path required.\n\n${USAGE}` };
-  }
+  return handleFileImport(arg, flags);
+}
 
-  // Resolve paths
+async function handleFileImport(
+  sourcePath: string,
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
   const resolvedSourcePath = resolve(sourcePath);
   const targetBasePath = getFlag(flags, 'target', getModuleStoragePath());
   const resolvedTargetBasePath = resolve(targetBasePath);
 
-  // Import module
+  // Surface a more useful error than "module directory does not exist"
+  // when the user typed a registry name with a typo (e.g. `caddy/` or
+  // `./caddy`) but no such directory is present. Helps them realize
+  // they probably wanted the registry form.
+  if (!existsSync(resolvedSourcePath)) {
+    return {
+      success: false,
+      error: `Path does not exist: ${resolvedSourcePath}\n\nIf you meant the registry, use a bare module name (no leading ./ or /):\n  celilo module import <name>`,
+    };
+  }
+
   const db = getDb();
   const result = await importModule({
     sourcePath: resolvedSourcePath,

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

@@ -6,7 +6,7 @@
  *      surrounding workspace (if any).
  *
  * The canonical failures this catches:
- *   - "I just installed celilo on a fresh box but module install is
+ *   - "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.

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

@@ -123,7 +123,6 @@ export async function getCompletions(words: string[], current: number): Promise<
     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'];

package/src/cli/index.ts

@@ -49,7 +49,7 @@ import { handleModuleConfigGet, handleModuleConfigSet } from './commands/module-
 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';
@@ -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
@@ -384,14 +381,14 @@ Registry:
       --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
@@ -1165,17 +1162,6 @@ 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':

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/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 {

package/src/services/bus-secret-flow.test.ts

@@ -324,4 +324,98 @@ describe('bus-mediated interviewForMissingSecrets', () => {
 
     handle.close();
   });
+
+  // string-map secrets: the responder collects key/value pairs via an
+  // add-loop and JSON-stringifies the result before writing. The bus
+  // payload signals the type so the responder picks the right UX.
+  test('string-map: payload carries type=string-map + labels; stored value is JSON-stringified record', async () => {
+    const { seen, close } = startTestResponder(
+      bus,
+      'secret.required.testmod.ddns_passwords',
+      { value: JSON.stringify({ 'lunacycle.net': 'pw1', 'celilo.computer': 'pw2' }) },
+      testDb,
+    );
+
+    const result = await interviewForMissingSecrets(
+      'testmod',
+      [
+        {
+          name: 'ddns_passwords',
+          source: 'secret',
+          type: 'string-map',
+          description: 'Namecheap Dynamic DNS password per managed domain',
+          key_label: 'Domain',
+          value_label: 'Password',
+        },
+      ],
+      testDb,
+    );
+
+    expect(result.success).toBe(true);
+    expect(seen.length).toBe(1);
+    expect(seen[0].payload.type).toBe('string-map');
+    expect(seen[0].payload.key_label).toBe('Domain');
+    expect(seen[0].payload.value_label).toBe('Password');
+
+    // Bus must NOT carry the secret value, even for string-map.
+    expect(seen[0].payload).not.toHaveProperty('value');
+
+    const masterKey = await getOrCreateMasterKey();
+    const stored = await readModuleSecretKey('testmod', 'ddns_passwords', testDb, masterKey);
+    expect(stored).toBe(JSON.stringify({ 'lunacycle.net': 'pw1', 'celilo.computer': 'pw2' }));
+
+    close();
+  });
+
+  test('string-map: enrichment from manifest.yml makes its way to the bus payload', async () => {
+    // Drop a manifest.yml in tempDir (the module's sourcePath) declaring
+    // the secret as string-map with custom labels. validateModuleSecrets
+    // reads the manifest and threads the metadata through to the bus.
+    writeSecretsSchema(tempDir, {
+      ddns_passwords: { source: 'user_provided' },
+    });
+    writeFileSync(
+      join(tempDir, 'manifest.yml'),
+      `
+celilo_contract: "1.0"
+id: testmod
+name: Test Module
+version: 1.0.0
+secrets:
+  declares:
+    - name: ddns_passwords
+      type: string-map
+      required: true
+      description: Per-domain DDNS password
+      sensitive: true
+      key_label: Domain
+      value_label: Password
+`,
+    );
+
+    const { seen, close } = startTestResponder(
+      bus,
+      'secret.required.testmod.ddns_passwords',
+      { value: JSON.stringify({ 'a.test': 'pw' }) },
+      testDb,
+    );
+
+    const { interviewForMissingSecrets, validateModuleSecrets } = await import(
+      './config-interview'
+    );
+    const missing = await validateModuleSecrets('testmod', testDb);
+    expect(missing).toHaveLength(1);
+    expect(missing[0].name).toBe('ddns_passwords');
+    expect(missing[0].type).toBe('string-map');
+    expect(missing[0].key_label).toBe('Domain');
+    expect(missing[0].value_label).toBe('Password');
+
+    const result = await interviewForMissingSecrets('testmod', missing, testDb);
+    expect(result.success).toBe(true);
+    expect(seen[0].payload.type).toBe('string-map');
+    expect(seen[0].payload.key_label).toBe('Domain');
+    expect(seen[0].payload.value_label).toBe('Password');
+
+    close();
+  });
 });

package/src/services/config-interview.ts

@@ -19,11 +19,54 @@ import {
 } from './bus-interview';
 import { getSecretMetadata, loadSecretsSchema } from './secret-schema-loader';
 
+/**
+ * Pull the manifest's `secrets.declares[]` entries keyed by name. Best-
+ * effort — returns an empty Map on any read/parse failure so the caller
+ * can fall back to JSON-schema-only interview behavior.
+ */
+async function loadManifestSecretDeclares(
+  moduleId: string,
+  db: DbClient,
+): Promise<
+  Map<string, { type?: string; description?: string; key_label?: string; value_label?: string }>
+> {
+  const out = new Map<
+    string,
+    { type?: string; description?: string; key_label?: string; value_label?: string }
+  >();
+  const moduleRow = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!moduleRow?.sourcePath) return out;
+
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { parse: parseYaml } = await import('yaml');
+    const yamlContent = await readFile(join(moduleRow.sourcePath, 'manifest.yml'), 'utf-8');
+    const parsed = parseYaml(yamlContent) as { secrets?: { declares?: unknown[] } } | undefined;
+    const declares = parsed?.secrets?.declares;
+    if (!Array.isArray(declares)) return out;
+    for (const d of declares) {
+      if (typeof d !== 'object' || d === null) continue;
+      const decl = d as Record<string, unknown>;
+      if (typeof decl.name !== 'string') continue;
+      out.set(decl.name, {
+        type: typeof decl.type === 'string' ? decl.type : undefined,
+        description: typeof decl.description === 'string' ? decl.description : undefined,
+        key_label: typeof decl.key_label === 'string' ? decl.key_label : undefined,
+        value_label: typeof decl.value_label === 'string' ? decl.value_label : undefined,
+      });
+    }
+  } catch {
+    // Manifest unreadable / malformed — fall back to schema-only.
+  }
+  return out;
+}
+
 export interface MissingVariable {
   name: string;
   source: 'user' | 'secret' | 'capability' | 'system';
   description?: string;
-  /** Variable type from manifest (string, array, etc.) */
+  /** Variable type from manifest (string, array, string-map, etc.) */
   type?: string;
   /** Derivation source (e.g., "$machine:ipAddress") */
   derive_from?: string;
@@ -42,6 +85,9 @@ export interface MissingVariable {
     length: number;
     encoding: string;
   };
+  /** For `type: string-map` only — labels shown in the add-loop prompt. */
+  key_label?: string;
+  value_label?: string;
 }
 
 export interface InterviewResult {
@@ -445,6 +491,12 @@ export async function validateModuleSecrets(
     return [];
   }
 
+  // Best-effort: load manifest declarations so we can enrich each missing
+  // secret with `type` (e.g. 'string-map'), `key_label`, `value_label`.
+  // The JSON schema knows shape; the manifest knows interview UX. If the
+  // manifest can't be read, we degrade to plain prompts.
+  const manifestDeclares = await loadManifestSecretDeclares(moduleId, db);
+
   // Check each declared secret
   for (const [secretName, propertySchema] of Object.entries(schema.properties)) {
     // Check if secret exists in database
@@ -455,10 +507,14 @@ export async function validateModuleSecrets(
       .get();
 
     if (!existing) {
+      const declare = manifestDeclares.get(secretName);
       missingSecrets.push({
         name: secretName,
         source: 'secret',
-        description: propertySchema.description || propertySchema.title,
+        description: declare?.description || propertySchema.description || propertySchema.title,
+        type: declare?.type,
+        key_label: declare?.key_label,
+        value_label: declare?.value_label,
       });
     }
   }
@@ -614,13 +670,15 @@ export async function interviewForMissingSecrets(
         // value into the encrypted store out-of-band, then replies
         // with `{ acknowledged: true }`. The value never crosses the
         // bus. See INTERACTIVE_DEPLOYS_VIA_BUS.md.
+        // The bus payload accepts scalar types and `string-map`
+        // (Record<string, string>, gathered via add-loop, stored as JSON).
+        // Cross-module ensure flows write composite shapes via a separate
+        // path, but the interview-driven `string-map` lands here.
+        const declaredType = (variable.type as SecretRequiredPayload['type']) ?? 'string';
         const payload: SecretRequiredPayload = {
           module: moduleId,
           key: variable.name,
-          // The bus payload narrows to scalar types. Secrets in the
-          // wider system can be objects, but those are written via
-          // the cross-module ensure flow, not this interview.
-          type: 'string',
+          type: declaredType === 'string-map' ? 'string-map' : 'string',
           required: true,
           description: variable.description,
           style: source,
@@ -631,6 +689,8 @@ export async function interviewForMissingSecrets(
                   length: metadata?.length || 32,
                 }
               : undefined,
+          key_label: variable.key_label,
+          value_label: variable.value_label,
         };
         await busInterview<SecretAck>(EVENT_TYPES.secretRequired(moduleId, variable.name), payload);
         log.success(`Saved ${variable.name}`);

package/src/services/terminal-responder.ts

@@ -325,6 +325,13 @@ async function promptForSecret(payload: SecretRequiredPayload): Promise<string |
     : `${payload.module}.${payload.key}:`;
   const style = payload.style ?? 'user_provided';
 
+  // string-map: Record<string, string> gathered via add-loop, stored as
+  // JSON. Bypasses the style switch — string-map secrets are always
+  // collected key-by-key, never as a single masked input.
+  if (payload.type === 'string-map') {
+    return promptForStringMap(payload);
+  }
+
   if (style === 'user_password') {
     while (true) {
       const value = await promptPassword({
@@ -368,6 +375,74 @@ async function promptForSecret(payload: SecretRequiredPayload): Promise<string |
   return value;
 }
 
+/**
+ * Add-loop UX for `type: string-map` secrets. Collects key/value pairs
+ * one at a time (key via `promptText`, value via `promptPassword` since
+ * we're inside the secret responder), then JSON-stringifies the result
+ * for storage. The operator never has to type braces, quotes, or commas.
+ *
+ * Empty key terminates the loop. If `payload.required` and zero entries
+ * have been collected, we re-ask rather than ack-ing with an empty map —
+ * the alternative would be a successful "ack" that fails downstream
+ * validation, which is worse UX.
+ */
+async function promptForStringMap(payload: SecretRequiredPayload): Promise<string | undefined> {
+  const keyLabel = payload.key_label ?? 'key';
+  const valueLabel = payload.value_label ?? 'value';
+  const header = payload.description
+    ? `${payload.module}.${payload.key} — ${payload.description}`
+    : `${payload.module}.${payload.key}`;
+  log.message(header);
+  log.message(
+    `Add ${keyLabel.toLowerCase()} → ${valueLabel.toLowerCase()} entries one at a time. Press Enter on an empty ${keyLabel.toLowerCase()} when done.`,
+  );
+
+  const collected: Record<string, string> = {};
+
+  while (true) {
+    const count = Object.keys(collected).length;
+    const keyMessage = count === 0 ? `${keyLabel}:` : `${keyLabel} (or Enter to finish):`;
+
+    const key = await promptText({
+      message: keyMessage,
+      validate: () => undefined, // empty = finish
+    });
+    if (key === undefined) {
+      // User cancelled (Ctrl-C). Return undefined so the responder
+      // doesn't ack — the deploy stays paused.
+      return undefined;
+    }
+    const trimmedKey = key.trim();
+    if (trimmedKey === '') {
+      if (count === 0 && payload.required) {
+        log.error(
+          `At least one ${keyLabel.toLowerCase()} is required. Add an entry or Ctrl-C to cancel.`,
+        );
+        continue;
+      }
+      break;
+    }
+
+    if (collected[trimmedKey] !== undefined) {
+      log.warn(`${keyLabel} '${trimmedKey}' was already entered — overwriting previous value.`);
+    }
+
+    const value = await promptPassword({
+      message: `${valueLabel} for '${trimmedKey}':`,
+      validate: (val) => (!val || val.trim() === '' ? 'Required' : undefined),
+    });
+    if (value === undefined) {
+      // User cancelled mid-entry; abort the whole interview.
+      return undefined;
+    }
+
+    collected[trimmedKey] = value;
+    log.success(`Added ${trimmedKey}`);
+  }
+
+  return JSON.stringify(collected);
+}
+
 /**
  * Short hint shown in the prompt for non-string types so the operator
  * isn't guessing what shape we want. Returns null for plain strings —