@celilo/cli 0.22.0 → 0.24.0

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

@@ -14,7 +14,9 @@ import { modules } from '../../db/schema';
 import { resolveDeployPosture } from '../../services/deploy-posture';
 import {
   FRAMEWORK_CONFIG_KEYS,
+  handleModuleConfigGet,
   handleModuleConfigSet,
+  handleModuleConfigUnset,
   validateFrameworkConfigValue,
 } from './module-config';
 import { pickUpgradePolicy } from './module-upgrade';
@@ -112,6 +114,30 @@ describe('handleModuleConfigSet — infra-key contract (ISS-0069)', () => {
     expect(result.success).toBe(false);
   });
 
+  test('a per-module policy key is settable on a module whose manifest never mentions it', async () => {
+    expect((await handleModuleConfigSet(['testmod', 'backup_schedule', '6h'])).success).toBe(true);
+    const read = await handleModuleConfigGet(['testmod', 'backup_schedule']);
+    expect(read.success).toBe(true);
+    if (read.success) expect(read.message).toContain('6h');
+  });
+
+  test('unset removes the override so the module follows its manifest again', async () => {
+    await handleModuleConfigSet(['testmod', 'backup_schedule', 'weekly']);
+
+    const unset = await handleModuleConfigUnset(['testmod', 'backup_schedule']);
+    expect(unset.success).toBe(true);
+
+    expect((await handleModuleConfigGet(['testmod', 'backup_schedule'])).success).toBe(false);
+  });
+
+  test('unsetting a key that was never set reports it and still succeeds', async () => {
+    // `unset` states a desired end state. Failing on an already-clean one makes
+    // it unusable from any script that cannot check first.
+    const result = await handleModuleConfigUnset(['testmod', 'backup_schedule']);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.message).toContain('No override set');
+  });
+
   test('the valid-keys hint advertises the celilo-managed keys', async () => {
     const result = await handleModuleConfigSet(['testmod', 'nope', 'x']);
     expect(result.success).toBe(false);
@@ -127,8 +153,19 @@ describe('validateFrameworkConfigValue (pure)', () => {
     expect(validateFrameworkConfigValue('app_port', 'anything')).toBeNull();
   });
 
-  test('accepts every documented value', () => {
-    for (const [key, values] of Object.entries(FRAMEWORK_CONFIG_KEYS)) {
+  test('every framework key accepts at least its documented values', () => {
+    const documented: Record<string, string[]> = {
+      auto_upgrade: ['true', 'false'],
+      upgrade_policy: ['by-semver', 'always-safe', 'always-fast'],
+      backup_schedule: ['hourly', 'daily', 'weekly', 'monthly', 'manual', '6h'],
+      health_check_interval: ['15m', '1h', 'daily', 'manual'],
+      backup_retention_count: ['1', '3', '30'],
+      backup_retention_max_age_days: ['1', '30', '365'],
+    };
+    // Every key must be covered, so adding one without deciding what it accepts
+    // fails here rather than shipping unvalidated.
+    expect(Object.keys(documented).sort()).toEqual(Object.keys(FRAMEWORK_CONFIG_KEYS).sort());
+    for (const [key, values] of Object.entries(documented)) {
       for (const v of values) expect(validateFrameworkConfigValue(key, v)).toBeNull();
     }
   });
@@ -136,6 +173,31 @@ describe('validateFrameworkConfigValue (pure)', () => {
   test('rejects an unlisted value', () => {
     expect(validateFrameworkConfigValue('upgrade_policy', 'always_safe')).toContain('Allowed');
   });
+
+  test('rejects a cadence the sweep that would serve it cannot run', () => {
+    // The backup sweep rides an hourly tick; accepting `5m` would leave the
+    // operator believing they configured something that can never happen.
+    expect(validateFrameworkConfigValue('backup_schedule', '5m')).toContain('hourly');
+    // The alerting sweep ticks every five minutes, so the same value is fine there.
+    expect(validateFrameworkConfigValue('health_check_interval', '5m')).toBeNull();
+    expect(validateFrameworkConfigValue('health_check_interval', '1m')).toContain('Allowed');
+  });
+
+  test('a retention of zero or below is refused rather than read as "keep nothing"', () => {
+    // A `0` read as a bound would delete every backup the module has.
+    for (const bad of ['0', '-1', '2.5', 'lots']) {
+      expect(validateFrameworkConfigValue('backup_retention_count', bad)).toContain('1 or greater');
+      expect(validateFrameworkConfigValue('backup_retention_max_age_days', bad)).toContain(
+        '1 or greater',
+      );
+    }
+  });
+
+  test('a misspelled cadence is refused, and says it was not coerced', () => {
+    const error = validateFrameworkConfigValue('backup_schedule', 'dailyy');
+    expect(error).toContain('named period');
+    expect(error).toContain('Rejected rather than coerced');
+  });
 });
 
 // The point of the whole control: with always-safe set, a PATCH upgrade — which

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

@@ -3,9 +3,25 @@
  */
 
 import { eq } from 'drizzle-orm';
+import { z } from 'zod';
 import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import {
+  HEALTH_CHECK_INTERVAL_CONFIG_KEY,
+  reconcileModuleWatchState,
+} from '../../services/alerting/health-cadence';
+import {
+  BACKUP_RETENTION_COUNT_CONFIG_KEY,
+  BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY,
+} from '../../services/backup-retention';
+import { BACKUP_SCHEDULE_CONFIG_KEY } from '../../services/backup-schedule';
+import {
+  BACKUP_CADENCE_FLOOR_MINUTES,
+  MONITOR_INTERVAL_FLOOR_MINUTES,
+  cadenceSchema,
+} from '../../services/cadence';
+import {
+  deleteModuleConfig,
   formatConfigValue,
   getAllModuleConfigValues,
   getModuleConfigValue,
@@ -18,6 +34,12 @@ import type { CommandResult } from '../types';
  * Operator keys that EVERY module accepts, whether or not its manifest declares
  * them, with their permitted values.
  *
+ * This is also where a module's per-module POLICY lives: how often to back it
+ * up, how often to health-check it. A manifest states those as the author's
+ * suggestion about a fleet they have never seen; the row an operator writes
+ * here wins, and every reader resolves the two at read time so a corrected
+ * manifest still reaches installs that have not overridden it.
+ *
  * These describe how celilo TREATS a module (its CD policy), not how the module
  * configures itself, so gating them on `variables.owns` had it backwards: it
  * required each module author to opt into being manageable. The failure was
@@ -34,9 +56,69 @@ import type { CommandResult } from '../types';
  * floor while nothing changed. A safety control that fails open on a typo is
  * worse than no control.
  */
-export const FRAMEWORK_CONFIG_KEYS: Record<string, readonly string[]> = {
-  auto_upgrade: ['true', 'false'],
-  upgrade_policy: ['by-semver', 'always-safe', 'always-fast'],
+export interface FrameworkConfigKey {
+  /** Accepts the value the operator typed, or explains what it should be. */
+  schema: z.ZodTypeAny;
+  /**
+   * Why this key is refused rather than coerced. Carried per key rather than
+   * derived from the schema's error: the substance is what a WRONG value would
+   * silently do, and no validator knows that.
+   */
+  why: string;
+}
+
+const REFUSED_NOT_COERCED_UPGRADE =
+  'Rejected rather than coerced: an unrecognized value silently falls back to the PERMISSIVE default (upgrade_policy → by-semver, which skips the pre-deploy backup on a patch), so a typo would look like it took effect.';
+
+const REFUSED_NOT_COERCED_CADENCE =
+  'Rejected rather than coerced: an unrecognized cadence falls back to the manifest\'s suggestion, so a typo would leave the module on the cadence you meant to change — visibly "set", and doing nothing.';
+
+const REFUSED_NOT_COERCED_RETENTION =
+  'Rejected rather than coerced: an unrecognized retention value falls back to the manifest, so a typo would leave the module keeping a different number of backups than you asked for — and the direction that goes wrong deletes data.';
+
+/** An enum whose rejection message reads as an operator instruction, not a type error. */
+function oneOf(values: readonly [string, ...string[]]): z.ZodTypeAny {
+  return z.enum(values, { errorMap: () => ({ message: `Allowed: ${values.join(', ')}` }) });
+}
+
+/**
+ * A whole number of things, at least one. Zero is refused rather than read as
+ * "keep nothing": a retention of 0 would delete every backup the module has.
+ */
+function positiveInteger(what: string): z.ZodTypeAny {
+  return z.string().superRefine((value, ctx) => {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Allowed: a whole number of ${what}, 1 or greater. Unset the key to keep everything.`,
+      });
+    }
+  });
+}
+
+export const FRAMEWORK_CONFIG_KEYS: Record<string, FrameworkConfigKey> = {
+  auto_upgrade: { schema: oneOf(['true', 'false']), why: REFUSED_NOT_COERCED_UPGRADE },
+  upgrade_policy: {
+    schema: oneOf(['by-semver', 'always-safe', 'always-fast']),
+    why: REFUSED_NOT_COERCED_UPGRADE,
+  },
+  [BACKUP_SCHEDULE_CONFIG_KEY]: {
+    schema: cadenceSchema({ floorMinutes: BACKUP_CADENCE_FLOOR_MINUTES }),
+    why: REFUSED_NOT_COERCED_CADENCE,
+  },
+  [HEALTH_CHECK_INTERVAL_CONFIG_KEY]: {
+    schema: cadenceSchema({ floorMinutes: MONITOR_INTERVAL_FLOOR_MINUTES }),
+    why: REFUSED_NOT_COERCED_CADENCE,
+  },
+  [BACKUP_RETENTION_COUNT_CONFIG_KEY]: {
+    schema: positiveInteger('copies to keep'),
+    why: REFUSED_NOT_COERCED_RETENTION,
+  },
+  [BACKUP_RETENTION_MAX_AGE_DAYS_CONFIG_KEY]: {
+    schema: positiveInteger('days to keep a backup'),
+    why: REFUSED_NOT_COERCED_RETENTION,
+  },
 };
 
 /**
@@ -44,10 +126,12 @@ export const FRAMEWORK_CONFIG_KEYS: Record<string, readonly string[]> = {
  * or null when the key is not a framework key or the value is permitted.
  */
 export function validateFrameworkConfigValue(key: string, value: string): string | null {
-  const allowed = FRAMEWORK_CONFIG_KEYS[key];
-  if (!allowed) return null;
-  if (allowed.includes(value)) return null;
-  return `Invalid value '${value}' for '${key}'.\n\nAllowed: ${allowed.join(', ')}\n\nRejected rather than coerced: an unrecognized value silently falls back to the PERMISSIVE default (upgrade_policy → by-semver, which skips the pre-deploy backup on a patch), so a typo would look like it took effect.`;
+  const framework = FRAMEWORK_CONFIG_KEYS[key];
+  if (!framework) return null;
+  const result = framework.schema.safeParse(value);
+  if (result.success) return null;
+  const explanation = result.error.issues.map((issue) => issue.message).join('\n');
+  return `Invalid value '${value}' for '${key}'.\n\n${explanation}\n\n${framework.why}`;
 }
 
 /**
@@ -131,10 +215,14 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
   // Set config value using service (handles primitive and complex types)
   try {
     await setModuleConfigValue(moduleId, key, value);
+    const resolved = settlingWatchState(db, moduleId, key);
 
     return {
       success: true,
-      message: `Set config for ${moduleId}: ${key}`,
+      message:
+        resolved > 0
+          ? `Set config for ${moduleId}: ${key} (resolved ${resolved} alert(s) — nothing will report on this module again until it is watched)`
+          : `Set config for ${moduleId}: ${key}`,
     };
   } catch (error) {
     return {
@@ -144,6 +232,69 @@ export async function handleModuleConfigSet(args: string[]): Promise<CommandResu
   }
 }
 
+/**
+ * Handle module config unset command
+ *
+ * Usage: celilo module config unset <module-id> <key>
+ *
+ * Removing an override is what returns a module to following its manifest.
+ * Without it, an operator who once set a cadence could never go back to the
+ * author's suggestion, and every later correction would stop reaching them —
+ * the exact failure read-time resolution exists to prevent, aimed at the
+ * operators who engaged with the feature.
+ *
+ * @param args - Command arguments
+ * @returns Command result
+ */
+export async function handleModuleConfigUnset(args: string[]): Promise<CommandResult> {
+  const error = validateRequiredArgs(args, 2);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo module config unset <module-id> <key>`,
+    };
+  }
+
+  const moduleId = getArg(args, 0);
+  const key = getArg(args, 1);
+
+  if (!moduleId || !key) {
+    return { success: false, error: 'Module ID and key are required' };
+  }
+
+  const db = getDb();
+
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) {
+    return { success: false, error: `Module not found: ${moduleId}` };
+  }
+
+  // Unsetting a key that was never set SUCCEEDS. `unset` states a desired end
+  // state, and failing on an already-clean one makes it unusable from any
+  // script that cannot check first.
+  if (!getModuleConfigValue(moduleId, key, db)) {
+    return { success: true, message: `No override set for ${moduleId}: ${key}` };
+  }
+
+  deleteModuleConfig(db, moduleId, key);
+  settlingWatchState(db, moduleId, key);
+  return {
+    success: true,
+    message: `Unset config for ${moduleId}: ${key} (now follows the module's manifest)`,
+  };
+}
+
+/**
+ * A module that has just stopped being watched may still own live alerts from
+ * its last scheduled runs, and nothing will ever report on them again. Resolve
+ * them here rather than leaving them firing with no action able to clear them.
+ * No-op for every other key.
+ */
+function settlingWatchState(db: ReturnType<typeof getDb>, moduleId: string, key: string): number {
+  if (key !== HEALTH_CHECK_INTERVAL_CONFIG_KEY) return 0;
+  return reconcileModuleWatchState(db, moduleId, new Date());
+}
+
 /**
  * Handle module config get command
  *

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

@@ -71,8 +71,8 @@ export async function handleModuleDeploy(
   }
 
   // Success message is emitted by deployModule via the active ProgressDisplay,
-  // so we return an empty message to avoid the top-level clack outro printing
-  // a duplicate line in a different style.
+  // so we return an empty message — index.ts exits without writing anything
+  // more, rather than printing a duplicate line in a different style.
   return {
     success: true,
     message: '',

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

@@ -79,6 +79,7 @@ export async function handleModuleHealth(
     return {
       success: true,
       message: JSON.stringify({ modules: results }, null, 2),
+      rawOutput: true,
     };
   }
 

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

@@ -143,9 +143,9 @@ export async function handleAspectApprovalAfterImport(args: {
     `celilo will run the '${aspect.ansible_role}' Ansible role on every non-api_only system`,
     'in those zones.',
   ].join('\n');
-  // Use process.stderr.write rather than the prompt UI so the
-  // multi-line scope block is preserved verbatim — @clack/prompts
-  // mangles multi-line message arguments.
+  // Written straight to stderr rather than through the prompt UI so the
+  // multi-line scope block is preserved verbatim — a prompt renderer owns
+  // its frame and reflows a multi-line message argument.
   process.stderr.write(`\n${scopeMsg}\n\n`);
 
   const accepted = await withInterviewSession(() =>

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

@@ -3,6 +3,7 @@ import { type DbClient, getDb } from '../../db/client';
 import { modules, modules as modulesTable, monitors } from '../../db/schema';
 import { moduleHealthCell } from '../../services/alerting/format';
 import { loadAllLiveAlerts, summariseByModule } from '../../services/alerting/store';
+import { formatPausedDuration } from '../../services/module-pause';
 import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
@@ -50,7 +51,17 @@ export async function handleModuleList(
   for (const module of moduleRows) {
     const observed = health.get(module.id);
     const healthNote = observed ? `  [${observed}]` : '';
-    lines.push(`${module.id} (v${module.version}) - ${module.state}${healthNote}`);
+    // A pause suppresses the alerting that would otherwise report this module
+    // as down, so the state alone is not enough — the AGE is what separates a
+    // maintenance window from an outage nobody remembers taking (design D7).
+    const stateCell =
+      module.state === 'PAUSED'
+        ? `PAUSED (${formatPausedDuration(module.pausedAt)})`
+        : module.state;
+    lines.push(`${module.id} (v${module.version}) - ${stateCell}${healthNote}`);
+    if (module.state === 'PAUSED' && module.pauseReason) {
+      lines.push(`  Paused: ${module.pauseReason}`);
+    }
     if (module.description) {
       lines.push(`  ${module.description}`);
     }