@celilo/cli 1.1.0 → 1.3.0

package/src/hooks/executor.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test';
+import { existsSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ContractHookSignature } from '../manifest/contracts';
 import {
@@ -272,6 +273,85 @@ describe('Hook Executor', () => {
     });
   });
 
+  describe('invokeHook artifacts', () => {
+    test('collects EVERY file the hook wrote, not just the newest .png', async () => {
+      const { logger } = createCapturingLogger();
+      const result = await invokeHook(
+        __dirname,
+        'container_created',
+        '1.0',
+        { script: './test-fixtures/artifact-writing-hook.ts', timeout: 10000 },
+        { vps_ip: '10.0.0.5' },
+        {},
+        {},
+        logger,
+      );
+
+      expect(result.success).toBe(true);
+      const names = (result.artifactPaths ?? []).map((p) => p.split('/').pop());
+      // The old behaviour returned exactly one of these — the .png — and
+      // threw away the DOM and the request log, which is the least useful
+      // third of a post-mortem on its own.
+      expect(names).toEqual(['spa-failure.html', 'spa-failure.png', 'spa-failure.requests.txt']);
+
+      // Per-run, so a consumer writing FIXED filenames cannot overwrite its
+      // own previous run — which is what makes retention meaningful.
+      const dir = (result.artifactPaths ?? [])[0];
+      expect(dir).toContain('/screenshots/container_created-');
+
+      rmSync(join(__dirname, 'screenshots'), { recursive: true, force: true });
+    });
+
+    test('a hook that writes nothing leaves no directory behind', async () => {
+      // Every hook invocation creates a run directory. If empty ones were
+      // kept, a module would accrue one per run forever — ~96 a day for a
+      // 15-minute monitor — and nothing would ever reclaim them.
+      const { logger } = createCapturingLogger();
+      const result = await invokeHook(
+        __dirname,
+        'container_created',
+        '1.0',
+        { script: './test-fixtures/success-hook.ts', timeout: 10000 },
+        { vps_ip: '10.0.0.5' },
+        {},
+        {},
+        logger,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.artifactPaths).toBeUndefined();
+      expect(existsSync(join(__dirname, 'screenshots', 'container_created'))).toBe(false);
+      const runDirs = existsSync(join(__dirname, 'screenshots'))
+        ? readdirSync(join(__dirname, 'screenshots'))
+        : [];
+      expect(runDirs).toEqual([]);
+    });
+
+    test('an early return before execution leaks no directory', async () => {
+      // The capability pre-flight returns between "create the directory" and
+      // the try/finally that reclaims it. Creating the directory too early
+      // therefore leaked one on every such run, and nothing cleans them up.
+      const { logger } = createCapturingLogger();
+      const result = await invokeHook(
+        __dirname,
+        'container_created',
+        '1.0',
+        { script: './test-fixtures/success-hook.ts', timeout: 10000 },
+        { vps_ip: '10.0.0.5' },
+        {},
+        {},
+        logger,
+        { requiredCapabilities: ['dns_internal'], capabilities: {} },
+      );
+
+      expect(result.success).toBe(false);
+      const runDirs = existsSync(join(__dirname, 'screenshots'))
+        ? readdirSync(join(__dirname, 'screenshots'))
+        : [];
+      expect(runDirs).toEqual([]);
+    });
+  });
+
   describe('invokeHook', () => {
     test('full successful invocation', async () => {
       const { logger, messages } = createCapturingLogger();

package/src/hooks/executor.ts

@@ -19,12 +19,13 @@
  * Execution function (Rule 10.1) - performs side effects (script execution)
  */
 
-import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import {
   type DeployedSystem,
   isCompiledHook,
   isMissingProviderInputError,
+  moduleArtifactDir,
 } from '@celilo/capabilities';
 import {
   type ContractHookSignature,
@@ -33,6 +34,7 @@ import {
   supportedContractVersions,
 } from '../manifest/contracts';
 import { isPrivilegedCapability } from '../manifest/validate';
+import { pruneModuleArtifacts } from './artifact-retention';
 import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
 
 /** Default total timeout: 60 seconds */
@@ -373,22 +375,45 @@ export function checkRequiredCapabilities(
  * @param since - Only consider files created after this timestamp (ms)
  * @returns Path to screenshot, or undefined
  */
-function findRecentScreenshot(dir: string, since: number): string | undefined {
-  if (!existsSync(dir)) return undefined;
+/**
+ * Every file the hook wrote to this run's artifact directory.
+ *
+ * No mtime filter is needed and none is wanted: the directory is created
+ * fresh for this run, so everything in it was written by this run. The
+ * previous version returned only the newest `.png`, which discarded the
+ * page content and the observed-request log — the two things that make a
+ * screenshot diagnosable.
+ */
+function collectArtifacts(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .map((file) => join(dir, file))
+      .filter((path) => {
+        try {
+          return statSync(path).isFile();
+        } catch {
+          return false;
+        }
+      })
+      .sort();
+  } catch {
+    // Best effort — never mask the original error with a readdir failure.
+    return [];
+  }
+}
 
+/** `undefined` rather than `[]`, so an empty result carries no field at all. */
+function nonEmpty(paths: string[]): string[] | undefined {
+  return paths.length > 0 ? paths : undefined;
+}
+
+/** Remove a run's artifact directory when the hook wrote nothing into it. */
+function discardIfEmpty(dir: string): void {
   try {
-    const files = readdirSync(dir).filter((f) => f.endsWith('.png'));
-    for (const file of files) {
-      const fullPath = join(dir, file);
-      const stat = statSync(fullPath);
-      if (stat.mtimeMs >= since) {
-        return fullPath;
-      }
-    }
+    if (readdirSync(dir).length === 0) rmdirSync(dir);
   } catch {
-    // Best effort — don't mask the original error
+    // Best effort — a leftover directory is not worth failing a hook over.
   }
-  return undefined;
 }
 
 /**
@@ -470,9 +495,16 @@ export async function invokeHook(
     };
   }
 
-  // Prepare screenshot directory
-  const screenshotDir = join(modulePath, 'screenshots');
-  mkdirSync(screenshotDir, { recursive: true });
+  // Prepare this run's artifact directory. Per-run, because a hook writing
+  // fixed filenames — a reasonable thing to do — would otherwise overwrite
+  // its own previous artifacts and leave retention nothing to retain.
+  // `moduleArtifactDir` is the one definition of that layout; a bus
+  // subscriber, which gets no HookContext, calls it directly.
+  // Path now, directory later. Creating it here would leak an empty
+  // directory on every early return between this point and the try/finally
+  // below — the capability pre-flight is one — and nothing ever cleans
+  // those up, so a module accrues one per affected run forever.
+  const screenshotDir = moduleArtifactDir(modulePath, `${hookName}-${startTime}`);
 
   // Build context
   const loadedCapabilities = options.capabilities ?? {};
@@ -515,6 +547,13 @@ export async function invokeHook(
     debug,
   );
 
+  // Create the artifact directory only once every early return is behind
+  // us, so the `finally` below is guaranteed to run and reclaim it.
+  mkdirSync(screenshotDir, { recursive: true });
+  // Prune on write, so retention needs no scheduler of its own and cannot
+  // fall behind a module that runs often.
+  pruneModuleArtifacts(dirname(screenshotDir));
+
   // Execute
   try {
     logger.info(`Executing hook: ${hookName}`);
@@ -535,16 +574,17 @@ export async function invokeHook(
     return {
       success: true,
       outputs,
+      artifactPaths: nonEmpty(collectArtifacts(screenshotDir)),
       duration: Date.now() - startTime,
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     logger.error(`Hook ${hookName} failed: ${message}`);
 
-    // Check for screenshots captured by the hook
-    const screenshotPath = findRecentScreenshot(screenshotDir, startTime);
-    if (screenshotPath) {
-      logger.info(`Screenshot saved: ${screenshotPath}`);
+    // Artifacts the hook wrote before it failed — the post-mortem.
+    const artifactPaths = nonEmpty(collectArtifacts(screenshotDir));
+    if (artifactPaths) {
+      logger.info(`Artifacts saved:\n  ${artifactPaths.join('\n  ')}`);
     }
 
     // Recognise the cross-module structured error so the orchestrator can
@@ -557,7 +597,7 @@ export async function invokeHook(
         success: false,
         outputs: {},
         error: message,
-        screenshotPath,
+        artifactPaths,
         duration: Date.now() - startTime,
         missingProviderInput: {
           providerModuleId: error.providerModuleId,
@@ -572,8 +612,13 @@ export async function invokeHook(
       success: false,
       outputs: {},
       error: message,
-      screenshotPath,
+      artifactPaths,
       duration: Date.now() - startTime,
     };
+  } finally {
+    // Most hooks write nothing, and every hook invocation would otherwise
+    // leave an empty directory behind. Discard it; a run that produced
+    // artifacts keeps its directory.
+    discardIfEmpty(screenshotDir);
   }
 }

package/src/hooks/test-fixtures/artifact-writing-hook.ts

@@ -0,0 +1,25 @@
+/**
+ * Test fixture: a hook that writes a post-mortem set to its artifact
+ * directory, the way a browser-driven check does — a screenshot, the page
+ * content, and the observed requests.
+ *
+ * Three files with three different extensions on purpose: the executor
+ * used to report only the newest `.png`, which silently discarded the two
+ * that make the screenshot diagnosable.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    const dir = ctx.screenshotDir as string;
+    writeFileSync(join(dir, 'spa-failure.png'), 'not-really-a-png');
+    writeFileSync(join(dir, 'spa-failure.html'), '<html></html>');
+    writeFileSync(join(dir, 'spa-failure.requests.txt'), 'GET /api/getActiveMonth 200');
+    return { api_key: 'wrote-artifacts' };
+  },
+});

package/src/hooks/types.ts

@@ -91,8 +91,13 @@ export interface HookResult {
   success: boolean;
   outputs: Record<string, unknown>;
   error?: string;
-  /** Path to failure screenshot, if captured */
-  screenshotPath?: string;
+  /**
+   * Every file the hook wrote to its per-run artifact directory.
+   * All of them, not just the newest image: a screenshot without the
+   * DOM and the observed requests is the least useful third of a
+   * post-mortem.
+   */
+  artifactPaths?: string[];
   /** Duration in milliseconds */
   duration: number;
   /**
@@ -120,3 +125,16 @@ import type { HookName } from '@celilo/capabilities';
  * Hook manifest section - maps hook names to definitions
  */
 export type HookManifest = Partial<Record<HookName, HookDefinition>>;
+
+/**
+ * Render collected artifacts for an operator-facing error message.
+ *
+ * One definition, because three call sites rendered the single old
+ * `screenshotPath` three separate times and would have drifted the moment
+ * one of them learned about the others.
+ */
+export function describeArtifacts(artifactPaths: string[] | undefined): string {
+  if (!artifactPaths || artifactPaths.length === 0) return '';
+  const label = artifactPaths.length === 1 ? 'Artifact saved' : 'Artifacts saved';
+  return `\n\n${label}:\n  ${artifactPaths.join('\n  ')}`;
+}

package/src/ipam/allocator.test.ts

@@ -25,6 +25,7 @@ import {
   reserveVMID,
   unreserveIP,
   unreserveVMID,
+  updateReservationReason,
 } from './allocator';
 
 describe('IPAM Allocator', () => {
@@ -295,6 +296,43 @@ describe('IPAM Allocator', () => {
       const reservations = await listReservations(db);
       expect(reservations).toHaveLength(2);
     });
+
+    // Editing in place, rather than include-then-exclude: that dance drops the
+    // row for a moment and can race an allocation into the held address.
+    test('should edit a reservation reason in place', async () => {
+      await reserveIP('10.0.10.50', 'dmz', 'LB', null, db);
+
+      const updated = await updateReservationReason('10.0.10.50', 'dmz', 'Retired LB', db);
+
+      expect(updated).toBe(true);
+      const reservations = await db.select().from(ipReservations).all();
+      expect(reservations).toHaveLength(1);
+      expect(reservations[0].reason).toBe('Retired LB');
+    });
+
+    test('should leave the address held while editing', async () => {
+      await reserveIP('10.0.10.50', 'dmz', 'LB', null, db);
+
+      await updateReservationReason('10.0.10.50', 'dmz', 'Retired LB', db);
+
+      expect(await isIPAvailable('10.0.10.50', 'dmz', db)).toBe(false);
+    });
+
+    test('should edit only the addressed row', async () => {
+      await reserveIP('10.0.10.50', 'dmz', 'LB', null, db);
+      await reserveIP('10.0.10.51', 'dmz', 'LB', null, db);
+
+      await updateReservationReason('10.0.10.50', 'dmz', 'Retired LB', db);
+
+      const reasons = (await listReservations(db)).map((r) => r.reason);
+      expect(reasons.sort()).toEqual(['LB', 'Retired LB']);
+    });
+
+    test('should report when no reservation exists to edit', async () => {
+      const updated = await updateReservationReason('10.0.10.99', 'dmz', 'Nothing there', db);
+
+      expect(updated).toBe(false);
+    });
   });
 
   describe('getAllocatedIPsInSubnet', () => {

package/src/ipam/allocator.ts

@@ -4,7 +4,7 @@
  * Prevents conflicts and tracks allocations
  */
 
-import { and, eq } from 'drizzle-orm';
+import { and, eq, like, or } from 'drizzle-orm';
 import type { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
 import type { DbClient } from '../db/client';
 import { ipAllocations, ipReservations, systemConfig, vmidReservations } from '../db/schema';
@@ -246,6 +246,68 @@ export async function unreserveIP(
     .where(and(eq(ipReservations.ipStart, ip), eq(ipReservations.zone, zone)));
 }
 
+/**
+ * Release every ingress-IP reservation a module holds (celilo#892).
+ *
+ * `ensureIngressIps` reserves an `internal`-subnet address at generate time and
+ * nothing released it at removal, so each install/remove cycle permanently
+ * burned one address from the static range — with no error and no way to tell
+ * the dead row from the live one, since both carry the same reason string.
+ *
+ * TWO reason formats exist in live databases and both must go: the current
+ * `ingress:<module>:<variable>` (since celilo#879) and the pre-879
+ * `dns-ingress:<module>`, which celilo-mgr still holds. Matching only the
+ * current one would leave the installed base leaking.
+ *
+ * Deletion is by REASON, not by the stored config value: a module can hold an
+ * ingress reservation with no `ip_allocations` row (it deploys onto a machine
+ * rather than a container), and the config rows are about to be cascade-deleted
+ * anyway. The reason string is the only thing that names the owner.
+ *
+ * @returns The addresses released, for reporting.
+ */
+export async function releaseIngressReservations(
+  moduleId: string,
+  db: DbOrTransaction,
+): Promise<string[]> {
+  // Module IDs are validated kebab-case, so they carry no LIKE wildcards.
+  const ownedByModule = or(
+    like(ipReservations.reason, `ingress:${moduleId}:%`),
+    eq(ipReservations.reason, `dns-ingress:${moduleId}`),
+  );
+
+  const held = await db.select().from(ipReservations).where(ownedByModule).all();
+  if (held.length === 0) return [];
+
+  await db.delete(ipReservations).where(ownedByModule);
+
+  return held.map((r: typeof ipReservations.$inferSelect) => r.ipStart);
+}
+
+/**
+ * Change an existing reservation's reason in place.
+ *
+ * The alternative — include then re-exclude — drops the row for a moment and
+ * can race an allocation into the address it was holding.
+ *
+ * @returns False when no reservation exists for that IP in that zone.
+ */
+export async function updateReservationReason(
+  ipStart: string,
+  zone: IpamZone,
+  reason: string,
+  db: DbOrTransaction,
+): Promise<boolean> {
+  const ip = stripCIDR(ipStart);
+  const match = and(eq(ipReservations.ipStart, ip), eq(ipReservations.zone, zone));
+
+  const existing = await db.select().from(ipReservations).where(match).all();
+  if (existing.length === 0) return false;
+
+  await db.update(ipReservations).set({ reason }).where(match);
+  return true;
+}
+
 /**
  * List all IP reservations
  */

package/src/ipam/auto-allocator.ts

@@ -10,6 +10,7 @@
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { ipAllocations } from '../db/schema';
+import { releaseIngressReservations } from './allocator';
 
 export interface IpamAllocation {
   moduleId: string;
@@ -258,6 +259,12 @@ export async function allocateForModule(
  * @returns True if allocation was removed, false if none existed
  */
 export async function deallocateForModule(moduleId: string, db: DbClient): Promise<boolean> {
+  // Ingress reservations are released FIRST and unconditionally (celilo#892).
+  // A module can hold one with no `ip_allocations` row at all — it deploys onto
+  // a machine rather than a celilo-provisioned container — so releasing it
+  // after the early return below would skip exactly the modules that leak.
+  await releaseIngressReservations(moduleId, db);
+
   // Check if allocation exists before deleting
   const existing = getAllocation(moduleId, db);
   if (!existing) {