@celilo/cli 0.1.0

package/src/capabilities/logging-wrapper.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Tests for `wrapWithLogging` (HOOK_API_V2 Phase 6 / D6).
+ *
+ * The wrapper is the framework's auto-logging layer for capability
+ * methods. The contract: log `→ <cap>.<method>` before, `✓` after,
+ * `✗` on failure (then re-throw). Method names ONLY — never any
+ * payload, never any result, because capability requests can carry
+ * secrets.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { wrapWithLogging } from '@celilo/capabilities';
+import { createCapturingLogger } from '../hooks/logger';
+
+describe('wrapWithLogging', () => {
+  test('wraps async methods and emits arrow markers in order', async () => {
+    const { logger, messages } = createCapturingLogger();
+
+    const wrapped = wrapWithLogging(
+      {
+        async greet(name: string): Promise<string> {
+          return `hello, ${name}`;
+        },
+      },
+      logger,
+      'public_web',
+    );
+
+    const result = await wrapped.greet('world');
+
+    expect(result).toBe('hello, world');
+    expect(messages).toEqual([
+      { level: 'info', message: '→ public_web.greet' },
+      { level: 'info', message: '✓ public_web.greet' },
+    ]);
+  });
+
+  test('captures errors, logs them at error level, then re-throws', async () => {
+    const { logger, messages } = createCapturingLogger();
+
+    const wrapped = wrapWithLogging(
+      {
+        async fail(): Promise<void> {
+          throw new Error('boom');
+        },
+      },
+      logger,
+      'idp',
+    );
+
+    await expect(wrapped.fail()).rejects.toThrow('boom');
+
+    expect(messages).toEqual([
+      { level: 'info', message: '→ idp.fail' },
+      { level: 'error', message: '✗ idp.fail: boom' },
+    ]);
+  });
+
+  test('does NOT log payload arguments — method name only', async () => {
+    const { logger, messages } = createCapturingLogger();
+
+    const wrapped = wrapWithLogging(
+      {
+        async create_user(req: { username: string; password: string }): Promise<void> {
+          // Method body — payload should never appear in any log line.
+          void req;
+        },
+      },
+      logger,
+      'idp',
+    );
+
+    await wrapped.create_user({ username: 'alice', password: 'super-secret-token' });
+
+    // Confirm the secret password never appears in any log message.
+    for (const m of messages) {
+      expect(m.message).not.toContain('alice');
+      expect(m.message).not.toContain('super-secret-token');
+    }
+    // And the only log lines are the arrow markers.
+    expect(messages.map((m) => m.message)).toEqual(['→ idp.create_user', '✓ idp.create_user']);
+  });
+
+  test('does NOT log result values', async () => {
+    const { logger, messages } = createCapturingLogger();
+
+    const wrapped = wrapWithLogging(
+      {
+        async create_oidc_client(): Promise<{ client_id: string; client_secret: string }> {
+          return { client_id: 'abc', client_secret: 'this-is-a-secret-do-not-log' };
+        },
+      },
+      logger,
+      'idp',
+    );
+
+    const result = await wrapped.create_oidc_client();
+
+    expect(result.client_secret).toBe('this-is-a-secret-do-not-log');
+    for (const m of messages) {
+      expect(m.message).not.toContain('this-is-a-secret-do-not-log');
+      expect(m.message).not.toContain('client_id');
+    }
+  });
+
+  test('preserves non-function properties unchanged', () => {
+    const { logger } = createCapturingLogger();
+
+    const original = {
+      version: '1.0.0',
+      capability: 'idp' as const,
+      async noop() {},
+    };
+
+    const wrapped = wrapWithLogging(original, logger, 'idp');
+
+    expect(wrapped.version).toBe('1.0.0');
+    expect(wrapped.capability).toBe('idp');
+    expect(typeof wrapped.noop).toBe('function');
+  });
+
+  test('does not mutate the original methods object', async () => {
+    const { logger } = createCapturingLogger();
+
+    let originalCalls = 0;
+    const original = {
+      async tick() {
+        originalCalls++;
+      },
+    };
+
+    const wrapped = wrapWithLogging(original, logger, 'cap');
+
+    // Calling the original should NOT trip the wrapper logger.
+    await original.tick();
+    expect(originalCalls).toBe(1);
+
+    // The wrapped reference must be a different function.
+    expect(wrapped.tick).not.toBe(original.tick);
+  });
+
+  test('multiple methods on the same object are each wrapped independently', async () => {
+    const { logger, messages } = createCapturingLogger();
+
+    const wrapped = wrapWithLogging(
+      {
+        async a(): Promise<void> {},
+        async b(): Promise<void> {},
+        async c(): Promise<void> {},
+      },
+      logger,
+      'cap',
+    );
+
+    await wrapped.a();
+    await wrapped.b();
+    await wrapped.c();
+
+    const messageTexts = messages.map((m) => m.message);
+    expect(messageTexts).toEqual([
+      '→ cap.a',
+      '✓ cap.a',
+      '→ cap.b',
+      '✓ cap.b',
+      '→ cap.c',
+      '✓ cap.c',
+    ]);
+  });
+
+  test('handles non-Error throws (string, plain object) by stringifying them', async () => {
+    const { logger, messages } = createCapturingLogger();
+
+    const wrapped = wrapWithLogging(
+      {
+        async throwString(): Promise<void> {
+          throw 'literal string';
+        },
+      },
+      logger,
+      'cap',
+    );
+
+    await expect(wrapped.throwString()).rejects.toBe('literal string');
+
+    expect(messages).toContainEqual({
+      level: 'error',
+      message: '✗ cap.throwString: literal string',
+    });
+  });
+
+  test('preserves `this` binding inside wrapped methods', async () => {
+    // The wrapper always returns an async function regardless of whether
+    // the original method was sync or async. This is fine in practice
+    // because every real capability interface declares its methods as
+    // async (`Promise<T>` return types) — see PublicWebCapability,
+    // IdpCapability, etc. Sync capability methods would be a type-system
+    // lie that the existing interfaces don't allow.
+    const { logger } = createCapturingLogger();
+
+    const original = {
+      _state: 'initial',
+      async setState(this: { _state: string }, next: string): Promise<void> {
+        this._state = next;
+      },
+      async getState(this: { _state: string }): Promise<string> {
+        return this._state;
+      },
+    };
+
+    const wrapped = wrapWithLogging(original, logger, 'cap');
+
+    await wrapped.setState('updated');
+    // The wrapped object shares state with the original via `this`
+    // because both methods operate on the same wrapped instance.
+    expect(await wrapped.getState()).toBe('updated');
+  });
+});

package/src/capabilities/lookup.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Tests for zone-scoped capability lookup
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { DbClient } from '../db/client';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import { findAllCapabilityProviders, findCapabilityProvider } from './lookup';
+
+describe('Zone-Scoped Capability Lookup', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+
+    // Insert test modules
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('greenwave', 'GreenWave', '1.0.0', '/path', '{}')`,
+    );
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('iptables', 'iptables', '1.0.0', '/path', '{}')`,
+    );
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('gmail', 'Gmail', '1.0.0', '/path', '{}')`,
+    );
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  describe('findCapabilityProvider', () => {
+    test('returns null when no providers exist', () => {
+      const result = findCapabilityProvider('firewall', db);
+      expect(result).toBeNull();
+    });
+
+    test('returns zone-agnostic provider without zone filter', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('gmail', 'email_reader', '1.0.0', '{}', NULL)`,
+      );
+
+      const result = findCapabilityProvider('email_reader', db);
+      expect(result).not.toBeNull();
+      expect(result?.moduleId).toBe('gmail');
+    });
+
+    test('returns zone-agnostic provider when zone is specified but no zone-scoped match', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('gmail', 'email_reader', '1.0.0', '{}', NULL)`,
+      );
+
+      const result = findCapabilityProvider('email_reader', db, 'dmz');
+      expect(result).not.toBeNull();
+      expect(result?.moduleId).toBe('gmail');
+    });
+
+    test('returns zone-scoped provider when zone matches', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{}', '["dmz","app","secure"]')`,
+      );
+
+      const result = findCapabilityProvider('firewall', db, 'dmz');
+      expect(result).not.toBeNull();
+      expect(result?.moduleId).toBe('iptables');
+    });
+
+    test('returns null when zone does not match any provider', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{}', '["dmz"]')`,
+      );
+
+      const result = findCapabilityProvider('firewall', db, 'external');
+      expect(result).toBeNull();
+    });
+
+    test('selects correct provider from multiple zone-scoped providers', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('greenwave', 'firewall', '1.0.0', '{"has_external":true}', '["internal"]')`,
+      );
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{}', '["dmz","app","secure"]')`,
+      );
+
+      const dmzResult = findCapabilityProvider('firewall', db, 'dmz');
+      expect(dmzResult?.moduleId).toBe('iptables');
+
+      const internalResult = findCapabilityProvider('firewall', db, 'internal');
+      expect(internalResult?.moduleId).toBe('greenwave');
+    });
+
+    test('returns first provider when no zone specified and multiple exist', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('greenwave', 'firewall', '1.0.0', '{}', '["internal"]')`,
+      );
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{}', '["dmz"]')`,
+      );
+
+      const result = findCapabilityProvider('firewall', db);
+      expect(result).not.toBeNull();
+      // Returns first one found (order depends on DB insert order)
+    });
+
+    test('includes zones in returned info', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{"nat_ip":"192.168.0.253"}', '["dmz","app"]')`,
+      );
+
+      const result = findCapabilityProvider('firewall', db, 'dmz');
+      expect(result?.zones).toEqual(['dmz', 'app']);
+      expect(result?.data).toEqual({ nat_ip: '192.168.0.253' });
+    });
+  });
+
+  describe('findAllCapabilityProviders', () => {
+    test('returns empty array when no providers exist', () => {
+      const results = findAllCapabilityProviders('firewall', db);
+      expect(results).toEqual([]);
+    });
+
+    test('returns all providers of a capability', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('greenwave', 'firewall', '1.0.0', '{}', '["internal"]')`,
+      );
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('iptables', 'firewall', '1.0.0', '{}', '["dmz"]')`,
+      );
+
+      const results = findAllCapabilityProviders('firewall', db);
+      expect(results).toHaveLength(2);
+      const moduleIds = results.map((r) => r.moduleId).sort();
+      expect(moduleIds).toEqual(['greenwave', 'iptables']);
+    });
+
+    test('does not return providers of different capabilities', () => {
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('greenwave', 'firewall', '1.0.0', '{}', '["internal"]')`,
+      );
+      db.$client.run(
+        `INSERT INTO capabilities (module_id, capability_name, version, data, zones) VALUES ('gmail', 'email_reader', '1.0.0', '{}', NULL)`,
+      );
+
+      const firewalls = findAllCapabilityProviders('firewall', db);
+      expect(firewalls).toHaveLength(1);
+      expect(firewalls[0].moduleId).toBe('greenwave');
+    });
+  });
+});

package/src/capabilities/lookup.ts

@@ -0,0 +1,89 @@
+/**
+ * Capability Lookup
+ *
+ * Zone-aware capability provider lookup. Supports both zone-scoped
+ * capabilities (like firewall) and zone-agnostic ones (like dns_registrar).
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities } from '../db/schema';
+
+export interface CapabilityProviderInfo {
+  id: number;
+  moduleId: string;
+  capabilityName: string;
+  version: string;
+  data: Record<string, unknown>;
+  zones: string[] | null;
+}
+
+/**
+ * Find a capability provider, optionally filtered by zone.
+ *
+ * - If zone is provided: prefer providers whose zones include that zone.
+ *   Falls back to zone-agnostic providers (zones is null).
+ * - If zone is not provided: return the first matching provider.
+ *
+ * @param name - Capability name (e.g., "firewall", "dns_registrar")
+ * @param zone - Optional zone filter (e.g., "dmz", "internal")
+ * @param db - Database client
+ */
+export function findCapabilityProvider(
+  name: string,
+  db: DbClient,
+  zone?: string,
+): CapabilityProviderInfo | null {
+  const all = db.select().from(capabilities).where(eq(capabilities.capabilityName, name)).all();
+
+  if (all.length === 0) return null;
+
+  if (zone) {
+    // First: try to find a provider that explicitly covers this zone
+    const zoneMatch = all.find((c) => {
+      const zones = c.zones as string[] | null;
+      return zones?.includes(zone);
+    });
+    if (zoneMatch) return toInfo(zoneMatch);
+
+    // Second: fall back to zone-agnostic provider (zones is null)
+    const agnostic = all.find((c) => c.zones === null || c.zones === undefined);
+    if (agnostic) return toInfo(agnostic);
+
+    // No match for this zone
+    return null;
+  }
+
+  // No zone specified: return first provider
+  return toInfo(all[0]);
+}
+
+/**
+ * Find all providers of a capability (across all zones)
+ */
+export function findAllCapabilityProviders(name: string, db: DbClient): CapabilityProviderInfo[] {
+  return db
+    .select()
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, name))
+    .all()
+    .map(toInfo);
+}
+
+function toInfo(row: {
+  id: number;
+  moduleId: string;
+  capabilityName: string;
+  version: string;
+  data: Record<string, unknown>;
+  zones: string[] | null;
+}): CapabilityProviderInfo {
+  return {
+    id: row.id,
+    moduleId: row.moduleId,
+    capabilityName: row.capabilityName,
+    version: row.version,
+    data: row.data as Record<string, unknown>,
+    zones: row.zones as string[] | null,
+  };
+}

package/src/capabilities/public-web-helpers.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Tests for the pure helpers exported alongside the public_web
+ * capability factory: client-config rendering and request validation
+ * for the higher-level operations introduced in HOOK_API_V2 Phase 4
+ * (D4).
+ *
+ * The factory itself opens SSH connections and shells out to tar, so
+ * it's not unit-testable in isolation. These helpers are the seam
+ * where the interesting logic lives.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  type PublishStaticSiteRequest,
+  type RegisterReverseProxyRequest,
+  generateClientConfigJs,
+  validatePublishStaticSiteRequest,
+  validateRegisterReverseProxyRequest,
+} from '@celilo/capabilities';
+
+describe('generateClientConfigJs', () => {
+  test('renders an empty object as a literal {}', () => {
+    const out = generateClientConfigJs({});
+    expect(out).toContain('window.__MODULE_CONFIG__ = {};');
+  });
+
+  test('emits the do-not-edit banner', () => {
+    const out = generateClientConfigJs({});
+    expect(out.split('\n')[0]).toContain('Generated by Celilo');
+    expect(out.split('\n')[0]).toContain('do not edit');
+  });
+
+  test('renders a single string field', () => {
+    const out = generateClientConfigJs({ CLIENT_ID: 'lunacycle-web' });
+    expect(out).toContain('"CLIENT_ID":"lunacycle-web"');
+  });
+
+  test('renders multiple fields in one object', () => {
+    const out = generateClientConfigJs({
+      AUTHENTIK_URL: 'https://auth.example.com',
+      CLIENT_ID: 'lunacycle-web',
+    });
+    expect(out).toContain('"AUTHENTIK_URL":"https://auth.example.com"');
+    expect(out).toContain('"CLIENT_ID":"lunacycle-web"');
+  });
+
+  test('round-trips numbers as JSON numbers (not strings)', () => {
+    const out = generateClientConfigJs({ TIMEOUT_MS: 5000, RETRIES: 3 });
+    expect(out).toContain('"TIMEOUT_MS":5000');
+    expect(out).toContain('"RETRIES":3');
+    expect(out).not.toContain('"5000"');
+  });
+
+  test('round-trips booleans as JSON booleans', () => {
+    const out = generateClientConfigJs({ DEBUG: true, PROD: false });
+    expect(out).toContain('"DEBUG":true');
+    expect(out).toContain('"PROD":false');
+  });
+
+  test('escapes double quotes inside string values', () => {
+    const out = generateClientConfigJs({ MOTD: 'hello "world"' });
+    expect(out).toContain('"MOTD":"hello \\"world\\""');
+  });
+
+  test('escapes backslashes inside string values', () => {
+    const out = generateClientConfigJs({ PATH: 'C:\\Users\\test' });
+    // JSON escapes each backslash, so the output has 2x doubled backslashes.
+    expect(out).toContain('"PATH":"C:\\\\Users\\\\test"');
+  });
+
+  test('escapes newlines and other control characters', () => {
+    const out = generateClientConfigJs({ MULTI: 'a\nb\tc' });
+    expect(out).toContain('"MULTI":"a\\nb\\tc"');
+  });
+
+  test('output is parseable as JavaScript (banner + assignment)', () => {
+    const out = generateClientConfigJs({ FOO: 'bar', N: 42 });
+    // The trailing newline keeps the file POSIX-clean.
+    expect(out.endsWith('\n')).toBe(true);
+    // Two non-empty lines: banner + assignment.
+    const lines = out.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(lines[1]).toMatch(/^window\.__MODULE_CONFIG__ = \{.*\};$/);
+  });
+});
+
+function basePublishRequest(
+  overrides: Partial<PublishStaticSiteRequest> = {},
+): PublishStaticSiteRequest {
+  return {
+    path: '/lunacycle',
+    sourceDir: '/tmp/build/dist',
+    ...overrides,
+  };
+}
+
+describe('validatePublishStaticSiteRequest', () => {
+  test('accepts a complete valid request', () => {
+    const result = validatePublishStaticSiteRequest(basePublishRequest());
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  test('accepts a request with optional clientConfig and subdomain', () => {
+    const result = validatePublishStaticSiteRequest(
+      basePublishRequest({
+        clientConfig: { FOO: 'bar' },
+        subdomain: 'app',
+      }),
+    );
+    expect(result.valid).toBe(true);
+  });
+
+  test('rejects empty path', () => {
+    const result = validatePublishStaticSiteRequest(basePublishRequest({ path: '' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Path is required');
+  });
+
+  test('rejects path that does not start with /', () => {
+    const result = validatePublishStaticSiteRequest(basePublishRequest({ path: 'lunacycle' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes('must start with /'))).toBe(true);
+  });
+
+  test('rejects path with trailing slash', () => {
+    const result = validatePublishStaticSiteRequest(basePublishRequest({ path: '/lunacycle/' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes('trailing slash'))).toBe(true);
+  });
+
+  test('accepts root path "/"', () => {
+    const result = validatePublishStaticSiteRequest(basePublishRequest({ path: '/' }));
+    expect(result.valid).toBe(true);
+  });
+
+  test('rejects empty sourceDir', () => {
+    const result = validatePublishStaticSiteRequest(basePublishRequest({ sourceDir: '' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('sourceDir is required');
+  });
+
+  test('reports multiple errors at once', () => {
+    const result = validatePublishStaticSiteRequest({
+      path: '',
+      sourceDir: '',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+function baseProxyRequest(
+  overrides: Partial<RegisterReverseProxyRequest> = {},
+): RegisterReverseProxyRequest {
+  return {
+    path: '/lunacycle/api',
+    targetHost: '10.0.20.42',
+    targetPort: 8080,
+    ...overrides,
+  };
+}
+
+describe('validateRegisterReverseProxyRequest', () => {
+  test('accepts a complete valid request', () => {
+    const result = validateRegisterReverseProxyRequest(baseProxyRequest());
+    expect(result.valid).toBe(true);
+  });
+
+  test('accepts websocket flag', () => {
+    const result = validateRegisterReverseProxyRequest(baseProxyRequest({ websocket: true }));
+    expect(result.valid).toBe(true);
+  });
+
+  test('rejects missing targetHost', () => {
+    const result = validateRegisterReverseProxyRequest(baseProxyRequest({ targetHost: '' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('targetHost is required');
+  });
+
+  test('rejects port 0', () => {
+    const result = validateRegisterReverseProxyRequest(baseProxyRequest({ targetPort: 0 }));
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes('between 1 and 65535'))).toBe(true);
+  });
+
+  test('rejects port above 65535', () => {
+    const result = validateRegisterReverseProxyRequest(baseProxyRequest({ targetPort: 70000 }));
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.includes('between 1 and 65535'))).toBe(true);
+  });
+
+  test('rejects missing path', () => {
+    const result = validateRegisterReverseProxyRequest(baseProxyRequest({ path: '' }));
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Path is required');
+  });
+});