@celilo/cli 0.9.0 → 0.9.1

package/drizzle/meta/_journal.json

@@ -101,4 +101,4 @@
       "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -16,13 +16,7 @@
     "CELILO_SUBSYSTEMS.md",
     "CELILO_CORE_MODULES.md"
   ],
-  "keywords": [
-    "celilo",
-    "homelab",
-    "orchestration",
-    "ansible",
-    "terraform"
-  ],
+  "keywords": ["celilo", "homelab", "orchestration", "ansible", "terraform"],
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/capabilities/well-known.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 import {
   WELL_KNOWN_CAPABILITIES,
-  getCapabilityDataSchema,
   getSupportedCapabilities,
   getWellKnownCapability,
   isWellKnown,
@@ -166,64 +165,6 @@ describe('Well-Known Capabilities Registry', () => {
     });
   });
 
-  describe('getCapabilityDataSchema', () => {
-    test('should return data schema for public_web', () => {
-      const schema = getCapabilityDataSchema('public_web');
-
-      expect(schema).toEqual({
-        server: {
-          ip: {
-            primary: '$self:target_ip',
-          },
-          port: 443,
-        },
-      });
-    });
-
-    test('should return data schema for dns_registrar', () => {
-      const schema = getCapabilityDataSchema('dns_registrar');
-
-      expect(schema).toEqual({
-        provider: 'namecheap',
-        domains: '$self:domains',
-        supports: ['dynamic_dns_a_record'],
-      });
-    });
-
-    test('should return data schema for auth', () => {
-      const schema = getCapabilityDataSchema('auth');
-
-      // Note: oidc.issuer_url was removed in MANIFEST_V2 D9 — auth providers
-      // (e.g. authentik) now derive their issuer URL in their own manifest
-      // and expose it through provides.capabilities[].data.
-      expect(schema).toEqual({
-        server: {
-          ip: {
-            primary: '$self:target_ip',
-          },
-          port: 9000,
-        },
-      });
-    });
-
-    test('should return cloned schema (not reference)', () => {
-      const schema1 = getCapabilityDataSchema('public_web');
-      const schema2 = getCapabilityDataSchema('public_web');
-
-      // Modify one schema to test cloning
-      // biome-ignore lint/suspicious/noExplicitAny: intentionally mutating to verify independent copies
-      (schema1 as any).server.port = 8080;
-
-      // Other schema should be unchanged
-      // biome-ignore lint/suspicious/noExplicitAny: accessing mutated property for comparison
-      expect((schema2 as any).server.port).toBe(443);
-    });
-
-    test('should throw error for unknown capability', () => {
-      expect(() => getCapabilityDataSchema('unknown')).toThrow('Unknown capability: unknown');
-    });
-  });
-
   describe('Security zone requirements', () => {
     test('home lab public-facing services must be in DMZ', () => {
       expect(WELL_KNOWN_CAPABILITIES.public_web.required_zone).toBe('dmz');

package/src/capabilities/well-known.ts

@@ -227,12 +227,3 @@ export function validateZoneRequirement(
 
   return { valid: true };
 }
-
-/**
- * Get capability data schema with variables resolved
- * Note: This returns the template schema - actual variable resolution happens during generation
- */
-export function getCapabilityDataSchema(capabilityName: string): Record<string, unknown> {
-  const capability = getWellKnownCapability(capabilityName);
-  return structuredClone(capability.data_schema);
-}

package/src/cli/completion.ts

@@ -533,40 +533,6 @@ complete -F _celilo_completion celilo
 `;
 }
 
-/**
- * Generate zsh completion script
- */
-export function generateZshCompletion(): string {
-  return `#compdef celilo
-
-_celilo() {
-    local -a completions
-    local -a words_array
-    local current_word
-
-    # Get current word index (CURRENT is 1-based)
-    current_word=\${CURRENT}
-
-    # Get words from command line
-    words_array=("\${words[@]}")
-
-    # Call celilo to get completions (returns newline-separated list)
-    local result
-    result=$(celilo --get-completions "\${words_array[@]}" "$current_word" 2>/dev/null)
-
-    # Split result into array by newlines
-    completions=("\${(@f)result}")
-
-    # Provide completions
-    if (( \${#completions} > 0 )); then
-        compadd -a completions
-    fi
-}
-
-compdef _celilo celilo
-`;
-}
-
 /**
  * Generate fish completion script.
  *

package/src/cli/validators.test.ts

@@ -3,149 +3,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import {
-  validateDomain,
-  validateEmail,
-  validateIpAddress,
-  validateIpAddressList,
-  validateProxmoxUrl,
-  validateRequired,
-  validateRequiredNoDefault,
-  validateSubnet,
-} from './validators';
-
-describe('validateProxmoxUrl', () => {
-  test('accepts valid HTTPS URL with port', () => {
-    expect(validateProxmoxUrl('https://proxmox.example.com:8006')).toBeUndefined();
-    expect(validateProxmoxUrl('https://192.168.1.100:8006')).toBeUndefined();
-  });
-
-  test('rejects non-HTTPS URLs', () => {
-    expect(validateProxmoxUrl('http://proxmox.example.com:8006')).toBe(
-      'URL must start with https://',
-    );
-  });
-
-  test('rejects URLs without port', () => {
-    expect(validateProxmoxUrl('https://proxmox.example.com')).toBe(
-      'URL must include port (e.g., :8006)',
-    );
-  });
-
-  test('allows undefined (for default values)', () => {
-    expect(validateProxmoxUrl(undefined)).toBeUndefined();
-  });
-
-  test('rejects empty input', () => {
-    expect(validateProxmoxUrl('')).toBe('URL is required');
-    expect(validateProxmoxUrl('   ')).toBe('URL is required');
-  });
-
-  test('rejects invalid URLs', () => {
-    expect(validateProxmoxUrl('https://:8006')).toBe('Invalid URL format');
-    expect(validateProxmoxUrl('not-a-url')).toBe('URL must start with https://');
-  });
-});
-
-describe('validateSubnet', () => {
-  test('accepts valid CIDR notation', () => {
-    expect(validateSubnet('10.0.10.0/24')).toBeUndefined();
-    expect(validateSubnet('192.168.1.0/16')).toBeUndefined();
-    expect(validateSubnet('172.16.0.0/12')).toBeUndefined();
-  });
-
-  test('rejects invalid CIDR format', () => {
-    expect(validateSubnet('10.0.10.0')).toBe('Subnet must be in CIDR format (e.g., 10.0.10.0/24)');
-    expect(validateSubnet('10.0.10/24')).toBe('Subnet must be in CIDR format (e.g., 10.0.10.0/24)');
-  });
-
-  test('rejects invalid IP octets', () => {
-    expect(validateSubnet('256.0.10.0/24')).toBe('Invalid IP address (octets must be 0-255)');
-    expect(validateSubnet('10.300.10.0/24')).toBe('Invalid IP address (octets must be 0-255)');
-  });
-
-  test('rejects invalid prefix', () => {
-    expect(validateSubnet('10.0.10.0/33')).toBe('Invalid prefix length (must be 0-32)');
-    expect(validateSubnet('10.0.10.0/-1')).toBe('Invalid prefix length (must be 0-32)');
-  });
-
-  test('allows undefined (for default values)', () => {
-    expect(validateSubnet(undefined)).toBeUndefined();
-  });
-
-  test('rejects empty input', () => {
-    expect(validateSubnet('')).toBe('Subnet is required');
-  });
-});
-
-describe('validateDomain', () => {
-  test('accepts valid domains', () => {
-    expect(validateDomain('homelab.local')).toBeUndefined();
-    expect(validateDomain('example.com')).toBeUndefined();
-    expect(validateDomain('sub.domain.co.uk')).toBeUndefined();
-  });
-
-  test('rejects invalid domain format', () => {
-    expect(validateDomain('not-a-domain')).toBe('Invalid domain format (e.g., homelab.local)');
-    expect(validateDomain('.example.com')).toBe('Invalid domain format (e.g., homelab.local)');
-    expect(validateDomain('example..com')).toBe('Invalid domain format (e.g., homelab.local)');
-  });
-
-  test('allows undefined (for default values)', () => {
-    expect(validateDomain(undefined)).toBeUndefined();
-  });
-
-  test('rejects empty input', () => {
-    expect(validateDomain('')).toBe('Domain is required');
-  });
-});
-
-describe('validateEmail', () => {
-  test('accepts valid emails', () => {
-    expect(validateEmail('admin@example.com')).toBeUndefined();
-    expect(validateEmail('user.name@domain.co.uk')).toBeUndefined();
-  });
-
-  test('rejects invalid email format', () => {
-    expect(validateEmail('not-an-email')).toBe('Invalid email format');
-    expect(validateEmail('@example.com')).toBe('Invalid email format');
-    expect(validateEmail('user@')).toBe('Invalid email format');
-  });
-
-  test('allows undefined (for default values)', () => {
-    expect(validateEmail(undefined)).toBeUndefined();
-  });
-
-  test('rejects empty input', () => {
-    expect(validateEmail('')).toBe('Email is required');
-  });
-});
-
-describe('validateIpAddress', () => {
-  test('accepts valid IP addresses', () => {
-    expect(validateIpAddress('1.1.1.1')).toBeUndefined();
-    expect(validateIpAddress('192.168.1.100')).toBeUndefined();
-    expect(validateIpAddress('10.0.0.1')).toBeUndefined();
-  });
-
-  test('rejects invalid IP format', () => {
-    expect(validateIpAddress('not-an-ip')).toBe('Invalid IP format (e.g., 1.1.1.1)');
-    expect(validateIpAddress('192.168.1')).toBe('Invalid IP format (e.g., 1.1.1.1)');
-  });
-
-  test('rejects invalid octets', () => {
-    expect(validateIpAddress('256.1.1.1')).toBe('Invalid IP address (octets must be 0-255)');
-    expect(validateIpAddress('192.168.1.300')).toBe('Invalid IP address (octets must be 0-255)');
-  });
-
-  test('allows undefined (for default values)', () => {
-    expect(validateIpAddress(undefined)).toBeUndefined();
-  });
-
-  test('rejects empty input', () => {
-    expect(validateIpAddress('')).toBe('IP address is required');
-  });
-});
+import { validateRequired } from './validators';
 
 describe('validateRequired', () => {
   test('accepts non-empty strings', () => {
@@ -170,66 +28,3 @@ describe('validateRequired', () => {
     expect(validator('')).toBe('Custom field is required');
   });
 });
-
-describe('validateRequiredNoDefault', () => {
-  test('accepts non-empty strings', () => {
-    const validator = validateRequiredNoDefault('Password');
-    expect(validator('value')).toBeUndefined();
-    expect(validator('  text  ')).toBeUndefined();
-  });
-
-  test('rejects undefined (no default values)', () => {
-    const validator = validateRequiredNoDefault('Password');
-    expect(validator(undefined)).toBe('Password is required');
-  });
-
-  test('rejects empty strings', () => {
-    const validator = validateRequiredNoDefault('Password');
-    expect(validator('')).toBe('Password is required');
-    expect(validator('   ')).toBe('Password is required');
-  });
-
-  test('uses custom field name in error message', () => {
-    const validator = validateRequiredNoDefault('Custom password');
-    expect(validator('')).toBe('Custom password is required');
-  });
-});
-
-describe('validateIpAddressList', () => {
-  test('accepts single IP address', () => {
-    expect(validateIpAddressList('1.1.1.1')).toBeUndefined();
-    expect(validateIpAddressList('192.168.1.100')).toBeUndefined();
-  });
-
-  test('accepts space-separated IP addresses', () => {
-    expect(validateIpAddressList('8.8.8.8 1.1.1.1')).toBeUndefined();
-    expect(validateIpAddressList('192.168.0.1 10.0.0.1 1.1.1.1')).toBeUndefined();
-  });
-
-  test('accepts multiple spaces between IPs', () => {
-    expect(validateIpAddressList('8.8.8.8  1.1.1.1')).toBeUndefined();
-    expect(validateIpAddressList('1.1.1.1   8.8.8.8   1.0.0.1')).toBeUndefined();
-  });
-
-  test('rejects comma-separated IPs', () => {
-    expect(validateIpAddressList('1.1.1.1,8.8.8.8')).toContain('Invalid IP address');
-  });
-
-  test('rejects invalid IP in list', () => {
-    expect(validateIpAddressList('8.8.8.8 999.999.999.999')).toContain(
-      "Invalid IP address '999.999.999.999'",
-    );
-    expect(validateIpAddressList('192.168.0.1 not-an-ip')).toContain(
-      "Invalid IP address 'not-an-ip'",
-    );
-  });
-
-  test('allows undefined (for default values)', () => {
-    expect(validateIpAddressList(undefined)).toBeUndefined();
-  });
-
-  test('rejects empty input', () => {
-    expect(validateIpAddressList('')).toBe('At least one IP address is required');
-    expect(validateIpAddressList('   ')).toBe('At least one IP address is required');
-  });
-});

package/src/cli/validators.ts

@@ -3,137 +3,6 @@
  * Validation functions for interactive prompts
  */
 
-/**
- * Validate URL format (must start with https:// and include port)
- */
-export function validateProxmoxUrl(value: string | undefined): string | Error | undefined {
-  // Allow undefined (default will be used)
-  if (value === undefined) {
-    return;
-  }
-
-  if (!value.trim()) {
-    return 'URL is required';
-  }
-
-  if (!value.startsWith('https://')) {
-    return 'URL must start with https://';
-  }
-
-  if (!value.includes(':') || !value.match(/:\d+/)) {
-    return 'URL must include port (e.g., :8006)';
-  }
-
-  // Basic URL validation
-  try {
-    new URL(value);
-  } catch {
-    return 'Invalid URL format';
-  }
-}
-
-/**
- * Validate subnet CIDR notation (e.g., 10.0.10.0/24)
- */
-export function validateSubnet(value: string | undefined): string | Error | undefined {
-  // Allow undefined (default will be used)
-  if (value === undefined) {
-    return;
-  }
-
-  if (!value.trim()) {
-    return 'Subnet is required';
-  }
-
-  // Check CIDR format: IP/prefix
-  const cidrPattern = /^(\d{1,3}\.){3}\d{1,3}\/(.+)$/;
-  if (!cidrPattern.test(value)) {
-    return 'Subnet must be in CIDR format (e.g., 10.0.10.0/24)';
-  }
-
-  // Validate IP octets (0-255)
-  const [ip, prefix] = value.split('/');
-  const octets = ip.split('.').map(Number);
-
-  for (const octet of octets) {
-    if (octet < 0 || octet > 255) {
-      return 'Invalid IP address (octets must be 0-255)';
-    }
-  }
-
-  // Validate prefix (0-32)
-  const prefixNum = Number(prefix);
-  if (prefixNum < 0 || prefixNum > 32) {
-    return 'Invalid prefix length (must be 0-32)';
-  }
-}
-
-/**
- * Validate domain name format
- */
-export function validateDomain(value: string | undefined): string | Error | undefined {
-  // Allow undefined (default will be used)
-  if (value === undefined) {
-    return;
-  }
-
-  if (!value.trim()) {
-    return 'Domain is required';
-  }
-
-  // Basic domain format: lowercase, alphanumeric, hyphens, dots
-  const domainPattern = /^[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,}$/i;
-  if (!domainPattern.test(value)) {
-    return 'Invalid domain format (e.g., homelab.local)';
-  }
-}
-
-/**
- * Validate email format
- */
-export function validateEmail(value: string | undefined): string | Error | undefined {
-  // Allow undefined (default will be used)
-  if (value === undefined) {
-    return;
-  }
-
-  if (!value.trim()) {
-    return 'Email is required';
-  }
-
-  const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-  if (!emailPattern.test(value)) {
-    return 'Invalid email format';
-  }
-}
-
-/**
- * Validate IP address format
- */
-export function validateIpAddress(value: string | undefined): string | Error | undefined {
-  // Allow undefined (default will be used)
-  if (value === undefined) {
-    return;
-  }
-
-  if (!value.trim()) {
-    return 'IP address is required';
-  }
-
-  const ipPattern = /^(\d{1,3}\.){3}\d{1,3}$/;
-  if (!ipPattern.test(value)) {
-    return 'Invalid IP format (e.g., 1.1.1.1)';
-  }
-
-  // Validate octets (0-255)
-  const octets = value.split('.').map(Number);
-  for (const octet of octets) {
-    if (octet < 0 || octet > 255) {
-      return 'Invalid IP address (octets must be 0-255)';
-    }
-  }
-}
-
 /**
  * Validate non-empty string (allows undefined for prompts with default values)
  */
@@ -149,40 +18,3 @@ export function validateRequired(fieldName: string) {
     }
   };
 }
-
-/**
- * Validate required field with no defaults (for password fields)
- */
-export function validateRequiredNoDefault(fieldName: string) {
-  return (value: string | undefined): string | Error | undefined => {
-    // Reject undefined - no default value for this field
-    if (value === undefined || !value.trim()) {
-      return `${fieldName} is required`;
-    }
-  };
-}
-
-/**
- * Validate space-separated list of IP addresses
- */
-export function validateIpAddressList(value: string | undefined): string | Error | undefined {
-  // Allow undefined (default will be used)
-  if (value === undefined) {
-    return;
-  }
-
-  if (!value.trim()) {
-    return 'At least one IP address is required';
-  }
-
-  // Split by spaces (any amount of whitespace)
-  const ips = value.trim().split(/\s+/);
-
-  // Validate each IP
-  for (const ip of ips) {
-    const error = validateIpAddress(ip);
-    if (error) {
-      return `Invalid IP address '${ip}': ${error}`;
-    }
-  }
-}

package/src/services/aspect-approvals.test.ts

@@ -247,5 +247,57 @@ describe('aspect-approvals', () => {
       const status = checkAspectApproval('knot-unbound-internal', '1.0.0', newAspect, db);
       expect(status).toBe('scope_changed');
     });
+
+    // #262 — scope-keyed carry-forward across versions. The ISS-0156 cutover
+    // hung because consent was recorded at the imported version, then a
+    // `module update` bumped the version and the deploy re-prompted (no row for
+    // the new version) — and nothing answered the prompt. Per D7, only a SCOPE
+    // change requires re-consent; a pure version bump must not.
+    it('carries approval forward to a bumped version with the SAME scope (#262 — no re-prompt)', () => {
+      insertModule('technitium', '1.0.2+4');
+      const db = getDb();
+      recordAspectApproval({
+        moduleId: 'technitium',
+        version: '1.0.2+4',
+        scopeHash: computeAspectScopeHash(baseAspect),
+        approver: null,
+        db,
+      });
+      // `module update` bumped +4 → +6; aspect scope unchanged.
+      expect(checkAspectApproval('technitium', '1.0.2+6', baseAspect, db)).toBe('approved');
+    });
+
+    it('carries a DENIAL forward to a bumped version with the same scope', () => {
+      insertModule('technitium', '1.0.2+4');
+      const db = getDb();
+      recordAspectConsent({
+        moduleId: 'technitium',
+        version: '1.0.2+4',
+        scopeHash: computeAspectScopeHash(baseAspect),
+        approver: null,
+        consented: false,
+        db,
+      });
+      expect(checkAspectApproval('technitium', '1.0.2+6', baseAspect, db)).toBe('denied');
+    });
+
+    it('does NOT carry forward to a bumped version when the scope changed', () => {
+      insertModule('technitium', '1.0.2+4');
+      const db = getDb();
+      recordAspectApproval({
+        moduleId: 'technitium',
+        version: '1.0.2+4',
+        scopeHash: computeAspectScopeHash(baseAspect),
+        approver: null,
+        db,
+      });
+      const narrowed: BaseModuleAspect = {
+        ansible_role: 'dns-client-config',
+        applicable_zones: ['dmz'],
+        triggers: ['on_install'],
+      };
+      // Bumped version AND narrowed scope → no exact row, no scope match → re-prompt.
+      expect(checkAspectApproval('technitium', '1.0.2+6', narrowed, db)).toBe('no_approval');
+    });
   });
 });

package/src/services/aspect-approvals.ts

@@ -21,7 +21,7 @@
  */
 
 import { createHash, randomUUID } from 'node:crypto';
-import { and, eq, sql } from 'drizzle-orm';
+import { and, desc, eq, sql } from 'drizzle-orm';
 import type { getDb } from '../db/client';
 import { aspectApprovals } from '../db/schema';
 import type { BaseModuleAspect } from '../manifest/schema';
@@ -65,6 +65,26 @@ export function findAspectApproval(
     .get();
 }
 
+/**
+ * Find the most recent consent row for a (moduleId, scopeHash) pair across ALL
+ * versions. Used to carry an operator's decision forward when a module version
+ * bump leaves the aspect scope (applicable_zones + triggers) unchanged — so a
+ * `module update` auto-revision doesn't force re-consent (#262). The latest
+ * decision (by approvedAt) for that scope wins.
+ */
+export function findAspectApprovalByScope(
+  moduleId: string,
+  scopeHash: string,
+  db: DbClient,
+): typeof aspectApprovals.$inferSelect | undefined {
+  return db
+    .select()
+    .from(aspectApprovals)
+    .where(and(eq(aspectApprovals.moduleId, moduleId), eq(aspectApprovals.scopeHash, scopeHash)))
+    .orderBy(desc(aspectApprovals.approvedAt))
+    .get();
+}
+
 /**
  * Record the operator's consent DECISION for a module version's
  * base-module aspect — `consented: true` (approve) or `false`
@@ -132,9 +152,17 @@ export function recordAspectApproval(args: {
  *   - 'approved': a matching-scope row with `consented: true` — run.
  *   - 'denied': a matching-scope row with `consented: false` — the
  *     operator explicitly refused (ISS-0027). Skip; do NOT re-prompt.
- *   - 'scope_changed': a row exists but the manifest's scope differs
- *     (D7 — the prior decision was about a different scope; re-prompt).
- *   - 'no_approval': no row for this version — undecided; prompt.
+ *   - 'scope_changed': a row exists for THIS version but the manifest's scope
+ *     differs (D7 — the prior decision was about a different scope; re-prompt).
+ *   - 'no_approval': no row for this version AND no prior decision for this
+ *     scope at any version — undecided; prompt.
+ *
+ * #262: when there's no row for the exact version, the operator's decision is
+ * carried forward by SCOPE. A pure version bump (e.g. a `module update`
+ * auto-revision) that leaves applicable_zones + triggers unchanged must NOT
+ * re-prompt — that re-prompt, unanswerable headlessly, is what hung the
+ * ISS-0156 cutover. A genuine scope change has a different scopeHash, so it
+ * finds no match and correctly falls through to 'no_approval'.
  */
 export function checkAspectApproval(
   moduleId: string,
@@ -142,9 +170,14 @@ export function checkAspectApproval(
   aspect: BaseModuleAspect,
   db: DbClient,
 ): 'approved' | 'denied' | 'scope_changed' | 'no_approval' {
-  const existing = findAspectApproval(moduleId, version, db);
-  if (!existing) return 'no_approval';
   const currentHash = computeAspectScopeHash(aspect);
-  if (existing.scopeHash !== currentHash) return 'scope_changed';
-  return existing.consented ? 'approved' : 'denied';
+  const exact = findAspectApproval(moduleId, version, db);
+  if (exact) {
+    if (exact.scopeHash !== currentHash) return 'scope_changed';
+    return exact.consented ? 'approved' : 'denied';
+  }
+  // No row for this exact version — carry the decision forward by scope (#262).
+  const byScope = findAspectApprovalByScope(moduleId, currentHash, db);
+  if (byScope) return byScope.consented ? 'approved' : 'denied';
+  return 'no_approval';
 }

package/src/services/programmatic-responder.aspect.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Regression: the programmatic responder (`celilo events respond`) must handle
+ * `aspect.required.*` so a HEADLESS deploy of a module with a base_module_aspect
+ * can be approved without a TTY.
+ *
+ * Before the fix it watched only config/secret/ensure/interview — never aspect —
+ * so a headless deploy whose aspect consent wasn't pre-recorded emitted
+ * `aspect.required.<m>.<role>` and hung forever (busInterview uses timeoutMs:0;
+ * no responder ever replied). This reproduced the ISS-0156 cutover hang and is
+ * the core of #262.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { type AspectRequiredPayload, EVENT_TYPES } from './bus-interview';
+import { startProgrammaticResponder } from './programmatic-responder';
+
+const NO_SCHEMAS = defineEvents({});
+
+const ASPECT_PAYLOAD: AspectRequiredPayload = {
+  module: 'technitium',
+  role: 'dns-client-config',
+  zones: ['dmz', 'app', 'secure', 'internal'],
+  triggers: ['on_install'],
+  trigger: 'on_install',
+  reason: 'no_approval',
+};
+
+/** Emit the aspect-consent query and return the responder's decision, or null. */
+async function askAspectConsent(
+  busPath: string,
+  module: string,
+  role: string,
+  payload: AspectRequiredPayload,
+): Promise<boolean | null> {
+  const bus = openBus({ dbPath: busPath, events: NO_SCHEMAS });
+  try {
+    const replies = await bus.query(
+      EVENT_TYPES.aspectRequired(module, role) as never,
+      payload as never,
+      {
+        timeoutMs: 3000,
+        pollIntervalMs: 100,
+        expect: 'first',
+      },
+    );
+    if (replies.length === 0) return null;
+    return (replies[0].payload as { consented?: boolean }).consented ?? null;
+  } finally {
+    bus.close();
+  }
+}
+
+describe('programmatic responder — aspect.required consent (#262)', () => {
+  let dir: string;
+  let busPath: string;
+  let db: ReturnType<typeof getDb>;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-resp-aspect-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    busPath = join(dir, 'bus.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+    db = getDb();
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(dir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+  });
+
+  it('approves (consented=true) when the policy approves the module', async () => {
+    const handle = startProgrammaticResponder({
+      busDbPath: busPath,
+      db,
+      onMissing: 'skip',
+      values: { aspects: { technitium: true } },
+    });
+    try {
+      const decision = await askAspectConsent(
+        busPath,
+        'technitium',
+        'dns-client-config',
+        ASPECT_PAYLOAD,
+      );
+      expect(decision).toBe(true);
+    } finally {
+      handle.close();
+    }
+  });
+
+  it("approves via the '*' wildcard policy", async () => {
+    const handle = startProgrammaticResponder({
+      busDbPath: busPath,
+      db,
+      onMissing: 'skip',
+      values: { aspects: { '*': true } },
+    });
+    try {
+      const decision = await askAspectConsent(
+        busPath,
+        'technitium',
+        'dns-client-config',
+        ASPECT_PAYLOAD,
+      );
+      expect(decision).toBe(true);
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('refuses (consented=false) when the policy denies the module', async () => {
+    const handle = startProgrammaticResponder({
+      busDbPath: busPath,
+      db,
+      onMissing: 'skip',
+      values: { aspects: { technitium: false } },
+    });
+    try {
+      const decision = await askAspectConsent(
+        busPath,
+        'technitium',
+        'dns-client-config',
+        ASPECT_PAYLOAD,
+      );
+      expect(decision).toBe(false);
+    } finally {
+      handle.close();
+    }
+  });
+
+  it('does not reply when no aspect policy is provided (onMissing: skip)', async () => {
+    const handle = startProgrammaticResponder({
+      busDbPath: busPath,
+      db,
+      onMissing: 'skip',
+      values: {},
+    });
+    try {
+      const decision = await askAspectConsent(
+        busPath,
+        'technitium',
+        'dns-client-config',
+        ASPECT_PAYLOAD,
+      );
+      expect(decision).toBeNull();
+    } finally {
+      handle.close();
+    }
+  });
+});

package/src/services/programmatic-responder.ts

@@ -21,6 +21,7 @@ import type { DbClient } from '../db/client';
 import { generateSecret } from '../secrets/generators';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import type {
+  AspectRequiredPayload,
   ConfigRequiredPayload,
   EnsureRequiredPayload,
   InterviewRequiredPayload,
@@ -66,6 +67,17 @@ export interface ResponderValues {
    * (string for text/select, string[] for multiselect, boolean for confirm).
    */
   interview?: Record<string, unknown>;
+  /**
+   * Aspect-consent decisions for a module's `base_module_aspect`
+   * (ISS-0027 / #262). When a HEADLESS deploy emits
+   * `aspect.required.<module>.<role>`, the responder replies
+   * `{ consented }` so the fan-out is approved/denied without a TTY —
+   * the gap that hung the ISS-0156 cutover. Lookup precedence:
+   * `<module>.<role>`, then `<module>`, then the `'*'` wildcard.
+   * Absent → the responder skips (onMissing), exactly like an unmapped
+   * config value — it never silently approves an un-policied aspect.
+   */
+  aspects?: Record<string, boolean>;
 }
 
 export interface ProgrammaticResponderOptions {
@@ -117,6 +129,7 @@ export interface ProgrammaticResponderHandle {
   seenSecretPayloads(): SecretRequiredPayload[];
   seenEnsurePayloads(): EnsureRequiredPayload[];
   seenInterviewPayloads(): InterviewRequiredPayload[];
+  seenAspectPayloads(): AspectRequiredPayload[];
   /** Stop watching. Caller still owns the db client. */
   close(): void;
 }
@@ -136,6 +149,7 @@ export function startProgrammaticResponder(
   const seenSecret: SecretRequiredPayload[] = [];
   const seenEnsure: EnsureRequiredPayload[] = [];
   const seenInterview: InterviewRequiredPayload[] = [];
+  const seenAspect: AspectRequiredPayload[] = [];
   let lastActivityAt = Date.now();
 
   const me = opts.emittedBy ?? 'programmatic';
@@ -308,6 +322,41 @@ export function startProgrammaticResponder(
     answered.push({ type: event.type, key: lookupKey });
   });
 
+  // Aspect consent (ISS-0027 / #262): a headless deploy about to fan out a
+  // module's base_module_aspect emits `aspect.required.<module>.<role>` and
+  // waits (busInterview, timeoutMs:0). Without this watch the responder never
+  // replied → the deploy hung forever (the ISS-0156 cutover failure). We reply
+  // per the `aspects` policy; an un-policied aspect is skipped, never approved.
+  const aspectWatch = bus.watch('aspect.required.*.*', async (event) => {
+    if (event.replyFor !== null) return;
+    lastActivityAt = Date.now();
+
+    const payload = event.payload as AspectRequiredPayload;
+    if (!payload || typeof payload.module !== 'string' || typeof payload.role !== 'string') {
+      missed.push({ type: event.type, key: '?', reason: 'malformed payload' });
+      return;
+    }
+    seenAspect.push(payload);
+
+    // Precedence: exact "<module>.<role>", then "<module>", then "*" wildcard.
+    const lookupKey = `${payload.module}.${payload.role}`;
+    const decision =
+      opts.values.aspects?.[lookupKey] ??
+      opts.values.aspects?.[payload.module] ??
+      opts.values.aspects?.['*'];
+    if (decision === undefined) {
+      handleMissing(event.type, lookupKey, `no aspect decision for "${lookupKey}"`);
+      return;
+    }
+
+    bus.emitRaw(
+      `${event.type}.reply`,
+      { consented: decision },
+      { replyFor: event.id, emittedBy: me },
+    );
+    answered.push({ type: event.type, key: lookupKey });
+  });
+
   // Liveness probe: a non-interactive caller (e.g. `module generate`
   // with no TTY) emits `responder.probe` to detect whether any
   // responder is listening before calling busInterview (which waits
@@ -331,11 +380,13 @@ export function startProgrammaticResponder(
     seenSecretPayloads: () => [...seenSecret],
     seenEnsurePayloads: () => [...seenEnsure],
     seenInterviewPayloads: () => [...seenInterview],
+    seenAspectPayloads: () => [...seenAspect],
     close: () => {
       configWatch.close();
       secretWatch.close();
       ensureWatch.close();
       interviewWatch.close();
+      aspectWatch.close();
       probeWatch.close();
       bus.close();
     },

package/src/utils/shell.test.ts

@@ -1,11 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import {
-  needsEscaping,
-  safeShellEscape,
-  shellEscape,
-  shellEscapeArray,
-  validatePath,
-} from './shell';
+import { shellEscape } from './shell';
 
 describe('shellEscape', () => {
   describe('simple paths', () => {
@@ -176,162 +170,6 @@ describe('shellEscape', () => {
   });
 });
 
-describe('shellEscapeArray', () => {
-  test('escapes array of simple paths', () => {
-    const paths = ['/tmp/test1', '/tmp/test2', '/tmp/test3'];
-    expect(shellEscapeArray(paths)).toEqual(["'/tmp/test1'", "'/tmp/test2'", "'/tmp/test3'"]);
-  });
-
-  test('escapes array of paths with spaces', () => {
-    const paths = ['/tmp/test one', '/tmp/test two'];
-    expect(shellEscapeArray(paths)).toEqual(["'/tmp/test one'", "'/tmp/test two'"]);
-  });
-
-  test('escapes empty array', () => {
-    expect(shellEscapeArray([])).toEqual([]);
-  });
-
-  test('escapes array with mixed path types', () => {
-    const paths = ['/tmp/simple', '/tmp/with spaces', "/tmp/with'quote", '/tmp/$special'];
-    expect(shellEscapeArray(paths)).toEqual([
-      "'/tmp/simple'",
-      "'/tmp/with spaces'",
-      "'/tmp/with'\\''quote'",
-      "'/tmp/$special'",
-    ]);
-  });
-});
-
-describe('needsEscaping', () => {
-  test('returns false for simple path', () => {
-    expect(needsEscaping('/tmp/test')).toBe(false);
-  });
-
-  test('returns false for path with only alphanumeric and slashes', () => {
-    expect(needsEscaping('/usr/local/bin/test123')).toBe(false);
-  });
-
-  test('returns false for path with hyphens and underscores', () => {
-    expect(needsEscaping('/tmp/test-module_v1')).toBe(false);
-  });
-
-  test('returns false for path with dots', () => {
-    expect(needsEscaping('./relative/path.txt')).toBe(false);
-  });
-
-  test('returns true for path with space', () => {
-    expect(needsEscaping('/tmp/test module')).toBe(true);
-  });
-
-  test('returns true for path with single quote', () => {
-    expect(needsEscaping("/tmp/Bob's Files")).toBe(true);
-  });
-
-  test('returns true for path with double quote', () => {
-    expect(needsEscaping('/tmp/"test"')).toBe(true);
-  });
-
-  test('returns true for path with dollar sign', () => {
-    expect(needsEscaping('/tmp/$VAR')).toBe(true);
-  });
-
-  test('returns true for path with backtick', () => {
-    expect(needsEscaping('/tmp/`cmd`')).toBe(true);
-  });
-
-  test('returns true for path with special shell characters', () => {
-    const specialChars = [
-      '!',
-      '&',
-      '|',
-      ';',
-      '<',
-      '>',
-      '(',
-      ')',
-      '[',
-      ']',
-      '{',
-      '}',
-      '*',
-      '?',
-      '~',
-      '#',
-      '\\',
-    ];
-    for (const char of specialChars) {
-      expect(needsEscaping(`/tmp/test${char}`)).toBe(true);
-    }
-  });
-});
-
-describe('validatePath', () => {
-  test('accepts valid simple path', () => {
-    expect(() => validatePath('/tmp/test')).not.toThrow();
-  });
-
-  test('accepts path with spaces', () => {
-    expect(() => validatePath('/tmp/test module')).not.toThrow();
-  });
-
-  test('accepts path with special characters', () => {
-    expect(() => validatePath('/tmp/$VAR/test')).not.toThrow();
-  });
-
-  test('accepts relative path', () => {
-    expect(() => validatePath('./modules/homebridge')).not.toThrow();
-  });
-
-  test('accepts path traversal (..)', () => {
-    expect(() => validatePath('../../etc/passwd')).not.toThrow();
-  });
-
-  test('throws on empty string', () => {
-    expect(() => validatePath('')).toThrow('Path cannot be empty');
-  });
-
-  test('throws on whitespace-only string', () => {
-    expect(() => validatePath('   ')).toThrow('Path cannot be empty');
-  });
-
-  test('throws on null byte', () => {
-    expect(() => validatePath('/tmp/test\0file')).toThrow('Path cannot contain null bytes');
-  });
-
-  test('throws on extremely long path', () => {
-    const longPath = `/tmp/${'a'.repeat(5000)}`;
-    expect(() => validatePath(longPath)).toThrow('Path exceeds maximum length');
-  });
-
-  test('accepts path at maximum length', () => {
-    const maxPath = `/tmp/${'a'.repeat(4090)}`; // Total ~4096
-    expect(() => validatePath(maxPath)).not.toThrow();
-  });
-});
-
-describe('safeShellEscape', () => {
-  test('validates and escapes valid path', () => {
-    expect(safeShellEscape('/tmp/test')).toBe("'/tmp/test'");
-  });
-
-  test('validates and escapes path with spaces', () => {
-    expect(safeShellEscape('/tmp/test module')).toBe("'/tmp/test module'");
-  });
-
-  test('throws on empty path', () => {
-    expect(() => safeShellEscape('')).toThrow('Path cannot be empty');
-  });
-
-  test('throws on null byte', () => {
-    expect(() => safeShellEscape('/tmp/test\0')).toThrow('Path cannot contain null bytes');
-  });
-
-  test('throws on extremely long path', () => {
-    const longPath = `/tmp/${'a'.repeat(5000)}`;
-    expect(() => safeShellEscape(longPath)).toThrow('Path exceeds maximum length');
-  });
-});
-
 describe('usage examples', () => {
   test('example: cd command with spaces', () => {
     const modulePath = '/Users/user/Library/Application Support/celilo';

package/src/utils/shell.ts

@@ -57,103 +57,3 @@ export function shellEscape(path: string): string {
 
   return `'${escaped}'`;
 }
-
-/**
- * Escapes an array of paths for shell usage.
- *
- * @param paths - Array of paths to escape
- * @returns Array of shell-escaped strings
- *
- * @example
- * ```typescript
- * const paths = ['/tmp/test', '/Users/user/My Files'];
- * const escaped = shellEscapeArray(paths);
- * // Returns: ["'/tmp/test'", "'/Users/user/My Files'"]
- *
- * // Use in command
- * execSync(`cp ${escaped.join(' ')} /dest/`);
- * ```
- */
-export function shellEscapeArray(paths: string[]): string[] {
-  return paths.map((p) => shellEscape(p));
-}
-
-/**
- * Checks if a path contains characters that require escaping.
- *
- * This is primarily for logging/debugging - you should ALWAYS escape paths
- * regardless of this check for security and reliability.
- *
- * @param path - Path to check
- * @returns True if path contains special characters
- *
- * @example
- * ```typescript
- * needsEscaping('/tmp/test')              // false
- * needsEscaping('/tmp/test module')       // true (space)
- * needsEscaping('/tmp/Bob\'s Files')      // true (quote)
- * needsEscaping('/tmp/test$var')          // true (special char)
- * ```
- */
-export function needsEscaping(path: string): boolean {
-  // Characters that require escaping in shell:
-  // - Spaces
-  // - Quotes (single and double)
-  // - Shell special characters: $ ` ! & | ; < > ( ) [ ] { } * ? ~ #
-  // - Backslash
-  const specialChars = /[ '"$`!&|;<>()[\]{}*?~#\\]/;
-
-  return specialChars.test(path);
-}
-
-/**
- * Validates a path before escaping (throws on clearly invalid inputs).
- *
- * Note: This does NOT validate that the path exists or is accessible,
- * only that it's not obviously malicious or invalid.
- *
- * @param path - Path to validate
- * @throws {Error} If path is clearly invalid or suspicious
- *
- * @example
- * ```typescript
- * validatePath('/tmp/test')           // OK
- * validatePath('')                    // throws: empty path
- * validatePath('../../../etc/passwd') // OK (relative paths allowed)
- * ```
- */
-export function validatePath(path: string): void {
-  if (!path || path.trim().length === 0) {
-    throw new Error('Path cannot be empty or whitespace-only');
-  }
-
-  // Check for null bytes (security risk)
-  if (path.includes('\0')) {
-    throw new Error('Path cannot contain null bytes');
-  }
-
-  // Check for extremely long paths (likely an error)
-  if (path.length > 4096) {
-    throw new Error('Path exceeds maximum length (4096 characters)');
-  }
-}
-
-/**
- * Safe shell escape with validation.
- *
- * Convenience function that validates then escapes a path.
- *
- * @param path - Path to validate and escape
- * @returns Shell-escaped string
- * @throws {Error} If path is invalid
- *
- * @example
- * ```typescript
- * safeShellEscape('/tmp/My Files')  // Returns: '/tmp/My Files'
- * safeShellEscape('')               // Throws: Path cannot be empty
- * ```
- */
-export function safeShellEscape(path: string): string {
-  validatePath(path);
-  return shellEscape(path);
-}

package/src/validation/schemas.ts

@@ -126,11 +126,6 @@ export const CLIServerResponseSchema = z.object({
 
 export type CLIServerResponse = z.infer<typeof CLIServerResponseSchema>;
 
-/**
- * Array of strings (for inventory groups, etc.)
- */
-export const StringArraySchema = z.array(z.string());
-
 /**
  * Helper: Parse JSON with Zod validation
  * Wraps JSON.parse() with schema validation and user-friendly error messages

package/src/config/env.ts

@@ -1,41 +0,0 @@
-/**
- * Environment Configuration
- *
- * Validates and exports typed environment variables using Zod.
- * Fails fast on startup if required environment variables are missing or invalid.
- */
-
-import { z } from 'zod';
-
-/**
- * Environment variable schema
- */
-const envSchema = z.object({
-  // Database configuration
-  CELILO_DB_PATH: z.string().default('./celilo.db'),
-
-  // Security
-  CELILO_MASTER_KEY_PATH: z.string().default('./master.key'),
-
-  // Data directory
-  CELILO_DATA_DIR: z.string().default('./data'),
-
-  // Environment
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-
-  // Optional: Server port (for future API server)
-  PORT: z.string().regex(/^\d+$/).transform(Number).default('3000'),
-});
-
-/**
- * Validated environment variables
- *
- * This will throw a detailed error on startup if validation fails,
- * preventing the app from running with invalid configuration.
- */
-export const env = envSchema.parse(process.env);
-
-/**
- * Type-safe environment variable access
- */
-export type Env = z.infer<typeof envSchema>;