@celilo/cli 0.14.0 → 0.14.1

package/CELILO_CORE_MODULES.md

@@ -39,7 +39,7 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **celilo-mgmt** — the celilo management server itself, deployed as a module (replaces install.sh + `system init`; ships daemon, runs migrations, self-registers). **provides:** `celilo_event_bus`, `celilo_module_deploy_worker`. **requires:** `cross_module_read`. See `openspec/specs/management-as-module/spec.md`.
 - **celilo-registry** — module registry server (Cargo sparse protocol); stores `.netapp` files, serves index + search/download API. On install it provisions a confidential introspection OIDC client via `idp.create_oidc_client` (SECURE_MODULE_PUBLISH.md §5[D-A]) and converges its issuer + introspection endpoint + creds onto the box for RFC 7662 token verification. **provides:** `registry_publish`. **requires:** `public_web`, `dns_registrar`, `idp`.
 - **celilo-apt-repo** — Debian apt repository (reprepro + Bun HTTP server) serving the celilo `.deb` at apt.celilo.computer. **provides:** `apt_publish`. **requires:** `public_web`, `dns_registrar`.
-- **signal** — bidirectional Signal transport for alerts and deploy-interview questions; runs signal-cli in daemon mode with its JSON-RPC socket bound to the host's own address (never public). Enrolled as a SECONDARY DEVICE of an existing Signal account rather than registering its own number — Signal blocks most VOIP ranges and bans bot-ish registrations. Recipient addresses live on celilo routes, not in module config, so adding a person never requires a redeploy. Runs on x86_64 and aarch64. `libsignal-client` ships no linux-aarch64 native, so celilo builds one (`modules/signal/build/`) and installs it as a `libsignal-jni` .deb on ARM hosts; x86_64 uses the JAR's bundled native. **provides:** `notification` (`send`, `receive`). **requires:** nothing — a transport that depended on the proxy, registrar or firewall could not tell you those were broken. See `openspec/changes/add-alerting/`.
+- **signal** — bidirectional Signal transport for alerts and deploy-interview questions; runs signal-cli in daemon mode with its JSON-RPC socket bound to the host's own address (never public). Enrolled as a SECONDARY DEVICE of an existing Signal account rather than registering its own number — Signal blocks most VOIP ranges and bans bot-ish registrations. Recipient addresses live on celilo routes, not in module config, so adding a person never requires a redeploy. Runs on x86_64 and aarch64. `libsignal-client` ships no linux-aarch64 native, so celilo builds one (`modules/signal/build/`) and installs it as a `libsignal-jni` .deb on ARM hosts; x86_64 uses the JAR's bundled native. **provides:** `notification` (`send`, `receive`). **requires:** no capabilities — a transport that depended on the proxy, registrar or firewall could not tell you those were broken — and a system in the **`secure-mgmt`** zone: it holds a linked Signal account (the operator's own messaging identity and keys), and its job is to observe every tier while depending on none, which is what the control-plane zone is for. See `openspec/changes/add-alerting/`.
 - **celilo-website** — public docs site (static Astro) served via Caddy on celilo.computer. **requires:** `public_web`, `dns_registrar`.
 
 ## Git forge & CI pipeline

package/package.json

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

package/src/capabilities/well-known.ts

@@ -19,10 +19,20 @@
  *   instead. Modules placed here inherit that reach, so placement is a privilege
  *   decision. celilo-mgmt may equally run in `internal`.
  *
+ * Semi-trusted LAN:
+ * - internal: Behind the firewall (NAT outbound, port-forward inbound), shielded
+ *   from the uncontrolled outside internet. Not firewall-segmented.
+ *
  * External Zone (Cloud/VPS):
  * - external: Services hosted outside home network (no VLAN, e.g., VPS on internet)
+ *
+ * Re-exported from db/schema rather than redeclared: this file used to carry its
+ * own hand-written copy of the union, and a second hand-maintained copy is what
+ * let `secure-mgmt` go missing in other places (see NETWORK_ZONES' comment).
  */
-export type NetworkZone = 'internal' | 'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'external';
+import type { NetworkZone } from '../db/schema';
+
+export type { NetworkZone };
 
 export interface WellKnownCapability {
   canonical_hostname: string;

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

@@ -5,7 +5,7 @@
 
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { type NetworkZone, modules } from '../../db/schema';
 import { type ModuleManifest, getSingularSystemSpec } from '../../manifest/schema';
 import { buildResolutionContext } from '../../variables/context';
 import { getArg, validateRequiredArgs } from '../parser';
@@ -161,14 +161,22 @@ export async function handleModuleShowZone(args: string[]): Promise<CommandResul
       };
     }
 
-    const zoneDescriptions: Record<string, string> = {
+    // Keyed by NetworkZone, not string: a new zone added to NETWORK_ZONES becomes a
+    // compile error here rather than silently rendering as "Unknown zone". Both
+    // `internal` and `secure-mgmt` were missing from the previous string-keyed map.
+    const zoneDescriptions: Record<NetworkZone, string> = {
+      internal: 'Internal (Semi-trusted network behind the firewall)',
       dmz: 'DMZ (Public-facing services)',
       app: 'Application (Internal services)',
       secure: 'Secure (Authentication/Database)',
+      'secure-mgmt': "Secure-Mgmt (celilo's own control plane)",
       external: 'External (VPS/Cloud)',
     };
 
-    const description = zoneDescriptions[zone] || 'Unknown zone';
+    // Cast at the lookup, not the declaration: `zone` comes from config and may be
+    // any string, so the runtime fallback stays — but the map above still has to
+    // cover every NetworkZone.
+    const description = zoneDescriptions[zone as NetworkZone] ?? 'Unknown zone';
 
     const lines = [`Module: ${moduleId}`, `Zone: ${zone} - ${description}`, ''];
 

package/src/db/schema.ts

@@ -198,7 +198,7 @@ export const ipAllocations = sqliteTable('ip_allocations', {
     .references(() => modules.id, { onDelete: 'cascade' }),
   vmid: integer('vmid').notNull().unique(),
   containerIp: text('container_ip').notNull().unique(), // CIDR format (e.g., "10.0.10.10/24")
-  zone: text('zone').$type<'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'internal'>().notNull(),
+  zone: text('zone').$type<AllocatableZone>().notNull(),
   allocatedAt: integer('allocated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
 
@@ -211,7 +211,7 @@ export const ipReservations = sqliteTable('ip_reservations', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   ipStart: text('ip_start').notNull(), // Single IP or range start
   ipEnd: text('ip_end'), // NULL for single IP, end IP for range
-  zone: text('zone').$type<'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'internal'>().notNull(),
+  zone: text('zone').$type<AllocatableZone>().notNull(),
   reason: text('reason').notNull(),
   reservedAt: integer('reserved_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
@@ -275,6 +275,17 @@ export const NETWORK_ZONES = [
  */
 export type NetworkZone = (typeof NETWORK_ZONES)[number];
 
+/**
+ * Zones an IP allocation or reservation can name: every NetworkZone except
+ * `external`, whose systems are addressed by the provider, not by our IPAM.
+ *
+ * Derived rather than hand-written for the same reason as NetworkZone above —
+ * the previous hand-written union was copied into two column definitions and a
+ * cast in machine-pool.ts, and the cast had already drifted (it was missing
+ * `secure-mgmt`, and its comment claimed the only difference was `external`).
+ */
+export type AllocatableZone = Exclude<NetworkZone, 'external'>;
+
 /**
  * Container services table
  * Stores container service providers (Proxmox, Digital Ocean, etc.)

package/src/manifest/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { NETWORK_ZONES } from '../db/schema';
 import { SUPPORTED_CONTRACT_VERSIONS } from './contracts';
 
 /**
@@ -309,9 +310,19 @@ export function parseIntervalMinutes(value: string): number | null {
  * operator creates a monitor by hand.
  */
 export const HealthCheckHookSchema = LifecycleHookSchema.extend({
+  // `.regex` duplicates the well-formedness half of the `superRefine` below on
+  // purpose: only `.regex` survives the export to JSON Schema, and that export is
+  // what validates `modules/*/manifest.yml` in the editor. The 5-minute floor
+  // cannot be expressed in JSON Schema at all, so it stays a refinement — which
+  // is why both exist rather than one. Keeping them in sync is the point of
+  // sharing DURATION_PATTERN.
   interval: z
     .string()
+    .regex(DURATION_PATTERN)
     .optional()
+    .describe(
+      'Suggested monitoring cadence, e.g. "15m", "1h", "1d". Must be 5m or longer — the monitor sweep runs on a 5-minute grid.',
+    )
     .superRefine((value, ctx) => {
       if (value === undefined) return;
       const minutes = parseIntervalMinutes(value);
@@ -379,9 +390,10 @@ export const SystemResourceSchema = z.object({
       'Proxmox provisioning type: lxc (default) or vm (qemu, for Docker / kernel-module workloads). ' +
         'Modules declare this explicitly; celilo never infers it. Moot for machine-pool / external infra.',
     ),
-  zone: z
-    .enum(['internal', 'dmz', 'app', 'secure', 'secure-mgmt', 'external'])
-    .describe('Required security zone for this module'),
+  // Derived from NETWORK_ZONES, not re-listed: a hand-written copy here would be
+  // a fourth place a new zone has to be remembered, and the copies in
+  // module-show and machine-pool had both already drifted.
+  zone: z.enum(NETWORK_ZONES).describe('Required security zone for this module'),
 });
 
 /**
@@ -594,7 +606,9 @@ export const ModuleManifestSchema = z
         container_created: LifecycleHookSchema.optional(),
         on_install: LifecycleHookSchema.optional(),
         on_uninstall: LifecycleHookSchema.optional(),
-        health_check: HealthCheckHookSchema.optional(),
+        health_check: HealthCheckHookSchema.optional().describe(
+          "Health check hook. `interval` is the module's SUGGESTED monitoring cadence; the operator's monitor row is the effective schedule and always wins.",
+        ),
         validate_config: LifecycleHookSchema.optional(),
         on_backup: LifecycleHookSchema.optional(),
         on_backup_analyze: LifecycleHookSchema.optional(),

package/src/services/machine-pool.ts

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { and, eq, inArray } from 'drizzle-orm';
 import { getDb } from '../db/client';
 import {
+  type AllocatableZone,
   type NetworkZone,
   containerServices,
   ipAllocations,
@@ -355,7 +356,7 @@ export async function getContainerSystemsByZone(
         eq(moduleInfrastructure.infrastructureType, 'container_service'),
         // ip_allocations.zone is narrower than NetworkZone (no 'external');
         // safe to cast — any 'external' input would just match zero rows.
-        inArray(ipAllocations.zone, zones as Array<'dmz' | 'app' | 'secure' | 'internal'>),
+        inArray(ipAllocations.zone, zones as AllocatableZone[]),
       ),
     );