@celilo/cli 0.9.0 → 0.10.0

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>;