@serfab/cadre-host 0.10.0 → 0.12.0

package/src/strands/types.ts

@@ -1,102 +1,102 @@
-/**
- * Strand-management types for cadre-host.
- *
- * A *strand* is a shared data network this party participates in. Membership is
- * canonical in the cadre control network's `Strand` table, reached over the owner
- * node's loopback admin channel (`GET /admin/strands`,
- * `DELETE /admin/strands/:id?confirm=1`).
- *
- * Unlike the trust circle — which layers host-local labels and pending invites on
- * top of the node's state — this layer holds **no host-local state at all**. There
- * is no `strands.json`. It exists for id validation, for translating the admin
- * channel's error codes into a stable vocabulary the management API can map to HTTP
- * statuses, and for nothing else. Keep it small.
- */
-
-/** One strand this party belongs to, as projected by the admin channel. */
-export interface StrandSummary {
-  /** The `Strand` row id — what a removal takes. */
-  id: string;
-  /** `'o'` = open, `'c'` = closed (the row carries this party's membership key). */
-  type: 'o' | 'c';
-  /** Whether the owner node currently has a running instance for the id. */
-  running: boolean;
-  /**
-   * The instance's status when running, else `null`. Deliberately `string` rather
-   * than cadre-core's `StrandStatus`: this is a wire projection the manager only
-   * forwards, and widening it keeps cadre-host from tracking a cadre-core union it
-   * never inspects.
-   */
-  status: string | null;
-}
-
-/** The result of listing this party's strands. */
-export interface StrandListSnapshot {
-  strands: StrandSummary[];
-  /**
-   * Open control-network connections on the owner node; 0 ⇒ writes commit
-   * local-only. A snapshot at read time, not a subscription — treat it as advisory.
-   */
-  controlConnections: number;
-}
-
-/** The result of removing this party's participation in one strand. */
-export interface StrandRemovalResult {
-  /** The trimmed id the call was about. */
-  strandId: string;
-  /** Whether a row existed before the write. */
-  published: boolean;
-  /** The found row's type; `null` when no row was found. */
-  type: 'o' | 'c' | null;
-  /**
-   * Whether THIS call issued the delete — not that the row was observed to vanish.
-   * The node's read and write are not atomic, so a concurrent removal landing in
-   * between makes this a no-op that still reports `true`.
-   */
-  removed: boolean;
-  /**
-   * The node saw 0 control connections at the end of the call. Sampled on EVERY
-   * call, including one that found no row and wrote nothing — read it as "this
-   * machine currently sees no siblings", and only as "your delete may not have
-   * travelled" when `removed` is also true.
-   */
-  alone: boolean;
-}
-
-/** Error codes thrown by StrandService. */
-export type StrandErrorCode =
-  /** The id was blank or whitespace-only, here or at the node. */
-  | 'invalid_id'
-  /** The node refused a closed-strand removal that carried no confirmation. */
-  | 'confirmation_required'
-  /** The owner node's admin channel is unreachable / not ready. */
-  | 'node_unavailable'
-  /** The node answered with a code this layer has no better word for. */
-  | 'internal';
-
-/** Typed error carrying a stable `code` for HTTP mapping. */
-export class StrandError extends Error {
-  readonly code: StrandErrorCode;
-
-  constructor(code: StrandErrorCode, message: string) {
-    super(message);
-    this.name = 'StrandError';
-    this.code = code;
-  }
-}
-
-/**
- * Typed handlers exposed to the local UI server for Fastify wiring.
- *
- * Handlers either return typed results or throw a `StrandError` whose `.code`
- * `server/error-handler.ts` maps to an HTTP status:
- *
- *   - `invalid_id`            → 400
- *   - `confirmation_required` → 428
- *   - `node_unavailable`      → 503
- *   - `internal`              → 500
- */
-export interface StrandHandlers {
-  listStrands(): Promise<StrandListSnapshot>;
-  removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult>;
-}
+/**
+ * Strand-management types for cadre-host.
+ *
+ * A *strand* is a shared data network this party participates in. Membership is
+ * canonical in the cadre control network's `Strand` table, reached over the owner
+ * node's loopback admin channel (`GET /admin/strands`,
+ * `DELETE /admin/strands/:id?confirm=1`).
+ *
+ * Unlike the trust circle — which layers host-local labels and pending invites on
+ * top of the node's state — this layer holds **no host-local state at all**. There
+ * is no `strands.json`. It exists for id validation, for translating the admin
+ * channel's error codes into a stable vocabulary the management API can map to HTTP
+ * statuses, and for nothing else. Keep it small.
+ */
+
+/** One strand this party belongs to, as projected by the admin channel. */
+export interface StrandSummary {
+  /** The `Strand` row id — what a removal takes. */
+  id: string;
+  /** `'o'` = open, `'c'` = closed (the row carries this party's membership key). */
+  type: 'o' | 'c';
+  /** Whether the owner node currently has a running instance for the id. */
+  running: boolean;
+  /**
+   * The instance's status when running, else `null`. Deliberately `string` rather
+   * than cadre-core's `StrandStatus`: this is a wire projection the manager only
+   * forwards, and widening it keeps cadre-host from tracking a cadre-core union it
+   * never inspects.
+   */
+  status: string | null;
+}
+
+/** The result of listing this party's strands. */
+export interface StrandListSnapshot {
+  strands: StrandSummary[];
+  /**
+   * Open control-network connections on the owner node; 0 ⇒ writes commit
+   * local-only. A snapshot at read time, not a subscription — treat it as advisory.
+   */
+  controlConnections: number;
+}
+
+/** The result of removing this party's participation in one strand. */
+export interface StrandRemovalResult {
+  /** The trimmed id the call was about. */
+  strandId: string;
+  /** Whether a row existed before the write. */
+  published: boolean;
+  /** The found row's type; `null` when no row was found. */
+  type: 'o' | 'c' | null;
+  /**
+   * Whether THIS call issued the delete — not that the row was observed to vanish.
+   * The node's read and write are not atomic, so a concurrent removal landing in
+   * between makes this a no-op that still reports `true`.
+   */
+  removed: boolean;
+  /**
+   * The node saw 0 control connections at the end of the call. Sampled on EVERY
+   * call, including one that found no row and wrote nothing — read it as "this
+   * machine currently sees no siblings", and only as "your delete may not have
+   * travelled" when `removed` is also true.
+   */
+  alone: boolean;
+}
+
+/** Error codes thrown by StrandService. */
+export type StrandErrorCode =
+  /** The id was blank or whitespace-only, here or at the node. */
+  | 'invalid_id'
+  /** The node refused a closed-strand removal that carried no confirmation. */
+  | 'confirmation_required'
+  /** The owner node's admin channel is unreachable / not ready. */
+  | 'node_unavailable'
+  /** The node answered with a code this layer has no better word for. */
+  | 'internal';
+
+/** Typed error carrying a stable `code` for HTTP mapping. */
+export class StrandError extends Error {
+  readonly code: StrandErrorCode;
+
+  constructor(code: StrandErrorCode, message: string) {
+    super(message);
+    this.name = 'StrandError';
+    this.code = code;
+  }
+}
+
+/**
+ * Typed handlers exposed to the local UI server for Fastify wiring.
+ *
+ * Handlers either return typed results or throw a `StrandError` whose `.code`
+ * `server/error-handler.ts` maps to an HTTP status:
+ *
+ *   - `invalid_id`            → 400
+ *   - `confirmation_required` → 428
+ *   - `node_unavailable`      → 503
+ *   - `internal`              → 500
+ */
+export interface StrandHandlers {
+  listStrands(): Promise<StrandListSnapshot>;
+  removeStrand(strandId: string, opts: { confirm: boolean }): Promise<StrandRemovalResult>;
+}

package/src/update/__tests__/apply.test.ts

@@ -1,158 +1,158 @@
-import { describe, expect, it } from 'vitest';
-
-import { applyUpdate, buildNpmSpawnSpec, quoteWindowsArg, type NpmExecutor, type NpmResult } from '../apply.js';
-import { UpdateErrorException } from '../types.js';
-
-function recordingExecutor(responses: NpmResult[]): { exec: NpmExecutor; calls: string[][] } {
-  const calls: string[][] = [];
-  let i = 0;
-  return {
-    calls,
-    async exec(args) {
-      calls.push(args);
-      const res = responses[i++] ?? { exitCode: 0, stdout: '', stderr: '' };
-      return res;
-    },
-  };
-}
-
-describe('applyUpdate', () => {
-  it('happy path: install succeeds, restart called', async () => {
-    const { exec, calls } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
-    let restartCount = 0;
-    const result = await applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-      restart: async () => { restartCount++; return undefined; },
-    });
-    expect(calls).toEqual([['install', '-g', '@serfab/cadre-host@0.7.0']]);
-    expect(restartCount).toBe(1);
-    expect(result).toMatchObject({ fromVersion: '0.6.0', toVersion: '0.7.0', restarted: true });
-  });
-
-  it('install succeeds but restart fails: result reports restartError, no throw', async () => {
-    const { exec } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
-    const result = await applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-      restart: async () => 'systemctl returned 1',
-    });
-    expect(result.restarted).toBe(false);
-    expect(result.restartError).toBe('systemctl returned 1');
-  });
-
-  it('install fails: rollback invoked, restart NOT called, throws apply_failed', async () => {
-    const { exec, calls } = recordingExecutor([
-      { exitCode: 1, stdout: '', stderr: 'EACCES' },
-      { exitCode: 0, stdout: 'rolled back', stderr: '' },
-    ]);
-    let restartCount = 0;
-    await expect(applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-      restart: async () => { restartCount++; return undefined; },
-    })).rejects.toBeInstanceOf(UpdateErrorException);
-    expect(calls).toEqual([
-      ['install', '-g', '@serfab/cadre-host@0.7.0'],
-      ['install', '-g', '@serfab/cadre-host@0.6.0'],
-    ]);
-    expect(restartCount).toBe(0);
-  });
-
-  it('install fails and rollback also fails: throws rollback_failed', async () => {
-    const { exec } = recordingExecutor([
-      { exitCode: 1, stdout: '', stderr: 'EACCES' },
-      { exitCode: 1, stdout: '', stderr: 'EACCES on rollback' },
-    ]);
-    await expect(applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-    })).rejects.toMatchObject({ code: 'rollback_failed' });
-  });
-
-  it('install throws (spawn error): rollback still attempted', async () => {
-    let i = 0;
-    const calls: string[][] = [];
-    const exec: NpmExecutor = async (args) => {
-      calls.push(args);
-      i++;
-      if (i === 1) throw new Error('ENOENT npm');
-      return { exitCode: 0, stdout: '', stderr: '' };
-    };
-    await expect(applyUpdate({
-      npmPackage: '@serfab/cadre-host',
-      fromVersion: '0.6.0',
-      toVersion: '0.7.0',
-      npmExecutor: exec,
-    })).rejects.toMatchObject({ code: 'apply_failed' });
-    expect(calls).toEqual([
-      ['install', '-g', '@serfab/cadre-host@0.7.0'],
-      ['install', '-g', '@serfab/cadre-host@0.6.0'],
-    ]);
-  });
-});
-
-describe('quoteWindowsArg', () => {
-  it('leaves safe args untouched', () => {
-    expect(quoteWindowsArg('install')).toBe('install');
-    expect(quoteWindowsArg('-g')).toBe('-g');
-    expect(quoteWindowsArg('@serfab/cadre-host@0.7.0')).toBe('@serfab/cadre-host@0.7.0');
-  });
-
-  it('quotes args containing whitespace or shell metachars', () => {
-    expect(quoteWindowsArg('has space')).toBe('"has space"');
-    expect(quoteWindowsArg('with&amp')).toBe('"with&amp"');
-    expect(quoteWindowsArg('pipe|me')).toBe('"pipe|me"');
-  });
-
-  it('escapes embedded quotes and trailing backslashes', () => {
-    expect(quoteWindowsArg('with"quote')).toBe('"with\\"quote"');
-    expect(quoteWindowsArg('trailing\\')).toBe('trailing\\');
-    expect(quoteWindowsArg('trail ing\\')).toBe('"trail ing\\\\"');
-  });
-
-  it('rejects control characters', () => {
-    expect(() => quoteWindowsArg('bad\nnewline')).toThrow(/control character/);
-    expect(() => quoteWindowsArg('bad\x00null')).toThrow(/control character/);
-  });
-});
-
-describe('buildNpmSpawnSpec', () => {
-  it('builds a single-string command with empty args on Windows', () => {
-    const original = process.platform;
-    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
-    try {
-      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
-      expect(spec).toEqual({
-        command: 'npm install -g @serfab/cadre-host@0.7.0',
-        args: [],
-        shell: true,
-      });
-    } finally {
-      Object.defineProperty(process, 'platform', { value: original, configurable: true });
-    }
-  });
-
-  it('passes args through verbatim on posix (no shell)', () => {
-    const original = process.platform;
-    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
-    try {
-      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
-      expect(spec).toEqual({
-        command: 'npm',
-        args: ['install', '-g', '@serfab/cadre-host@0.7.0'],
-        shell: false,
-      });
-    } finally {
-      Object.defineProperty(process, 'platform', { value: original, configurable: true });
-    }
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { applyUpdate, buildNpmSpawnSpec, quoteWindowsArg, type NpmExecutor, type NpmResult } from '../apply.js';
+import { UpdateErrorException } from '../types.js';
+
+function recordingExecutor(responses: NpmResult[]): { exec: NpmExecutor; calls: string[][] } {
+  const calls: string[][] = [];
+  let i = 0;
+  return {
+    calls,
+    async exec(args) {
+      calls.push(args);
+      const res = responses[i++] ?? { exitCode: 0, stdout: '', stderr: '' };
+      return res;
+    },
+  };
+}
+
+describe('applyUpdate', () => {
+  it('happy path: install succeeds, restart called', async () => {
+    const { exec, calls } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
+    let restartCount = 0;
+    const result = await applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => { restartCount++; return undefined; },
+    });
+    expect(calls).toEqual([['install', '-g', '@serfab/cadre-host@0.7.0']]);
+    expect(restartCount).toBe(1);
+    expect(result).toMatchObject({ fromVersion: '0.6.0', toVersion: '0.7.0', restarted: true });
+  });
+
+  it('install succeeds but restart fails: result reports restartError, no throw', async () => {
+    const { exec } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
+    const result = await applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => 'systemctl returned 1',
+    });
+    expect(result.restarted).toBe(false);
+    expect(result.restartError).toBe('systemctl returned 1');
+  });
+
+  it('install fails: rollback invoked, restart NOT called, throws apply_failed', async () => {
+    const { exec, calls } = recordingExecutor([
+      { exitCode: 1, stdout: '', stderr: 'EACCES' },
+      { exitCode: 0, stdout: 'rolled back', stderr: '' },
+    ]);
+    let restartCount = 0;
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => { restartCount++; return undefined; },
+    })).rejects.toBeInstanceOf(UpdateErrorException);
+    expect(calls).toEqual([
+      ['install', '-g', '@serfab/cadre-host@0.7.0'],
+      ['install', '-g', '@serfab/cadre-host@0.6.0'],
+    ]);
+    expect(restartCount).toBe(0);
+  });
+
+  it('install fails and rollback also fails: throws rollback_failed', async () => {
+    const { exec } = recordingExecutor([
+      { exitCode: 1, stdout: '', stderr: 'EACCES' },
+      { exitCode: 1, stdout: '', stderr: 'EACCES on rollback' },
+    ]);
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+    })).rejects.toMatchObject({ code: 'rollback_failed' });
+  });
+
+  it('install throws (spawn error): rollback still attempted', async () => {
+    let i = 0;
+    const calls: string[][] = [];
+    const exec: NpmExecutor = async (args) => {
+      calls.push(args);
+      i++;
+      if (i === 1) throw new Error('ENOENT npm');
+      return { exitCode: 0, stdout: '', stderr: '' };
+    };
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+    })).rejects.toMatchObject({ code: 'apply_failed' });
+    expect(calls).toEqual([
+      ['install', '-g', '@serfab/cadre-host@0.7.0'],
+      ['install', '-g', '@serfab/cadre-host@0.6.0'],
+    ]);
+  });
+});
+
+describe('quoteWindowsArg', () => {
+  it('leaves safe args untouched', () => {
+    expect(quoteWindowsArg('install')).toBe('install');
+    expect(quoteWindowsArg('-g')).toBe('-g');
+    expect(quoteWindowsArg('@serfab/cadre-host@0.7.0')).toBe('@serfab/cadre-host@0.7.0');
+  });
+
+  it('quotes args containing whitespace or shell metachars', () => {
+    expect(quoteWindowsArg('has space')).toBe('"has space"');
+    expect(quoteWindowsArg('with&amp')).toBe('"with&amp"');
+    expect(quoteWindowsArg('pipe|me')).toBe('"pipe|me"');
+  });
+
+  it('escapes embedded quotes and trailing backslashes', () => {
+    expect(quoteWindowsArg('with"quote')).toBe('"with\\"quote"');
+    expect(quoteWindowsArg('trailing\\')).toBe('trailing\\');
+    expect(quoteWindowsArg('trail ing\\')).toBe('"trail ing\\\\"');
+  });
+
+  it('rejects control characters', () => {
+    expect(() => quoteWindowsArg('bad\nnewline')).toThrow(/control character/);
+    expect(() => quoteWindowsArg('bad\x00null')).toThrow(/control character/);
+  });
+});
+
+describe('buildNpmSpawnSpec', () => {
+  it('builds a single-string command with empty args on Windows', () => {
+    const original = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+    try {
+      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
+      expect(spec).toEqual({
+        command: 'npm install -g @serfab/cadre-host@0.7.0',
+        args: [],
+        shell: true,
+      });
+    } finally {
+      Object.defineProperty(process, 'platform', { value: original, configurable: true });
+    }
+  });
+
+  it('passes args through verbatim on posix (no shell)', () => {
+    const original = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+    try {
+      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
+      expect(spec).toEqual({
+        command: 'npm',
+        args: ['install', '-g', '@serfab/cadre-host@0.7.0'],
+        shell: false,
+      });
+    } finally {
+      Object.defineProperty(process, 'platform', { value: original, configurable: true });
+    }
+  });
+});