@homeflare/alchemy 0.39.0 → 0.40.0

package/src/talos/fake-process.ts

@@ -0,0 +1,94 @@
+/**
+ * A fake `ChildProcessSpawner` for offline Talos tests — no real `bao` or `talosctl` process ever
+ * starts. Shared by credentials.test.ts and talos-machine-config.test.ts (2026-09-26, K-A3);
+ * this package had NO process-level test fake before this file — every Talos resource file spawns
+ * a real binary in production and none of that was previously exercised offline.
+ *
+ * ★ A FULL FAKE SERVICE, NOT A REAL SPAWN WITH A FIXTURE EXECUTABLE ON `PATH`. The alternative —
+ *   a tiny fake `bao`/`talosctl` script and a mutated `process.env.PATH` — spawns a REAL OS
+ *   process and mutates process-global state for the test's duration, which is exactly the kind
+ *   of cross-test interference the house rules ask tests to avoid. `ChildProcessSpawner.make`
+ *   takes just a `spawn` function and derives everything else, so a fake `spawn` is the whole cost.
+ */
+import * as Effect from 'effect/Effect';
+import * as Sink from 'effect/Sink';
+import * as Stream from 'effect/Stream';
+import type { Command } from 'effect/unstable/process/ChildProcess';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+
+export type FakeResult = {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode?: number;
+};
+export type FakeCall = {
+  readonly command: string;
+  readonly args: readonly string[];
+  /**
+   * Decoded stdin text, present only when the real caller piped a `Stream` in (K-talos-first-boot,
+   * `credentials-write.ts`'s `writeKvValue`) — the whole reason this fake exists is to prove a
+   * value went in via stdin and never via argv, so a test needs to see it.
+   */
+  readonly stdin?: string;
+};
+export type FakeHandler = (call: FakeCall) => FakeResult;
+
+const encode = (text: string) => new TextEncoder().encode(text);
+
+const fakeHandle = (result: FakeResult): ChildProcessSpawner.ChildProcessHandle =>
+  ChildProcessSpawner.makeHandle({
+    all: Stream.fromIterable([encode((result.stdout ?? '') + (result.stderr ?? ''))]),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result.exitCode ?? 0)),
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    pid: ChildProcessSpawner.ProcessId(1),
+    stderr: Stream.fromIterable([encode(result.stderr ?? '')]),
+    stdin: Sink.drain,
+    stdout: Stream.fromIterable([encode(result.stdout ?? '')]),
+    unref: Effect.succeed(Effect.void),
+  });
+
+/**
+ * Decode a `StandardCommand`'s `options.stdin` into text, or `undefined` when there was none to
+ * decode. Only `"pipe" | "inherit" | "ignore" | "overlapped"` (no bytes) and a raw `Stream` (the
+ * only two shapes anything in this package ever passes — `credentials-write.ts`'s `writeKvValue`
+ * uses `Stream.fromIterable`, matching `alchemy`'s own `Cloudflare/Workers/ViteChild.ts` usage) are
+ * handled; a `StdinConfig` wrapper is unwrapped to its own `.stream` field first.
+ */
+const stdinText = (stdin: unknown) =>
+  Effect.gen(function* () {
+    if (stdin === undefined || typeof stdin === 'string') return undefined;
+    const stream =
+      typeof stdin === 'object' && stdin !== null && 'stream' in stdin
+        ? (stdin as { stream: unknown }).stream
+        : stdin;
+    if (stream === undefined || typeof stream === 'string') return undefined;
+    const chunks = yield* Stream.runCollect(stream as Stream.Stream<Uint8Array>);
+    return chunks.map((chunk) => new TextDecoder().decode(chunk)).join('');
+  }).pipe(Effect.orDie);
+
+/**
+ * Build a fake `ChildProcessSpawner.Service` from `handler`, which sees every command's
+ * executable + argv (+ decoded stdin, when piped) and returns canned stdout/stderr/exitCode.
+ * `credentials.ts` and `talosctl.ts` only ever build `StandardCommand`s (never a piped command),
+ * so that is the only shape this fake accepts — a `PipedCommand` is a test-authoring mistake, not
+ * something to fake.
+ */
+export const fakeSpawner = (handler: FakeHandler, calls: FakeCall[] = []) =>
+  ChildProcessSpawner.make((command: Command) =>
+    Effect.gen(function* () {
+      if (command._tag !== 'StandardCommand') {
+        return yield* Effect.die(new Error('fake-process: only StandardCommand is supported'));
+      }
+      const stdin = yield* stdinText(command.options.stdin);
+      const call: FakeCall = {
+        args: command.args,
+        command: command.command,
+        ...(stdin === undefined ? {} : { stdin }),
+      };
+      calls.push(call);
+      return fakeHandle(handler(call));
+    }),
+  );

package/src/talos/index.ts

@@ -5,10 +5,45 @@
  *   These are the symbols a real stack consumes; the rest of the files are internals a
  *   provider needs but a consumer should not depend on. An `export *` here would publish
  *   every helper as API and make the next refactor a breaking change.
+ * ★ `Talos.MachineConfig`'S RESOURCE CLASS JOINED ITS PROVIDER 2026-09-26 (K-A3) — until now this
+ *   barrel exported only `Talos*Provider`, which builds the provider but gives a consuming stack
+ *   nothing to `new` or call to actually DECLARE a row (the same gap proxmox/index.ts's own header
+ *   calls out for `ProxmoxVm`). MachineConfig is safe to declare today: it fails closed on a digest
+ *   mismatch before touching a node, and its cold-start read never silently adopts (PR 307 fix-first
+ *   #1, machine-config-read.ts's own header).
+ * ★ BOOTSTRAP, CLUSTERHEALTH AND KUBECONFIG JOIN THEM (K-talos-first-boot, 2026-09-26) — PR 307's
+ *   red team (fix-first #3) held these back because `Talos.Bootstrap` could re-run `talosctl
+ *   bootstrap` against an already-bootstrapped cluster and `Talos.Kubeconfig` wrote a cluster-admin
+ *   kubeconfig to un-vaulted host disk. Both are fixed now: bootstrap's "once means once" invariant
+ *   (talos-bootstrap.ts's own header) and kubeconfig landing in OpenBao, written once at bring-up
+ *   (kubeconfig.ts's own header) — plus `Talos.ClusterHealth`'s error handling no longer conflates a
+ *   vault/transport failure with "cluster not healthy yet" (talos-cluster-health.ts's own header).
  * ★ Anything unlisted is still reachable by path if you genuinely need it — that is a
  *   deliberate, visible act rather than an accident of barrelling.
  */
-export { TalosKubeconfigProvider } from './kubeconfig.ts';
-export { TalosBootstrapProvider } from './talos-bootstrap.ts';
-export { TalosClusterHealthProvider } from './talos-cluster-health.ts';
-export { TalosMachineConfigProvider } from './talos-machine-config.ts';
+export type { TalosCredential, TalosTarget } from './credentials.ts';
+export {
+  type KubeconfigAttributes,
+  type KubeconfigProps,
+  TalosKubeconfig,
+  TalosKubeconfigProvider,
+} from './kubeconfig.ts';
+export type { ApplyMode, WithTarget } from './resource.ts';
+export {
+  type BootstrapAttributes,
+  type BootstrapProps,
+  TalosBootstrap,
+  TalosBootstrapProvider,
+} from './talos-bootstrap.ts';
+export {
+  type ClusterHealthAttributes,
+  type ClusterHealthProps,
+  TalosClusterHealth,
+  TalosClusterHealthProvider,
+} from './talos-cluster-health.ts';
+export {
+  type MachineConfigAttributes,
+  type MachineConfigProps,
+  TalosMachineConfig,
+  TalosMachineConfigProvider,
+} from './talos-machine-config.ts';

package/src/talos/kubeconfig-attrs.ts

@@ -0,0 +1,55 @@
+/**
+ * `Talos.Kubeconfig`'s attribute builder and its `Kubernetes.Connection` — split out of
+ * kubeconfig.ts (LAND, 2026-09-26, C1/I2 fixes) once fixing those findings pushed the file over the
+ * 250-line cap, the same reason machine-config-read.ts/machine-config-poll.ts/talos-errors.ts were
+ * split out of talos-machine-config.ts before it. Only `import type` comes back from kubeconfig.ts,
+ * so there is no runtime cycle between the two files.
+ */
+import type { Connection } from 'alchemy/Kubernetes/Connection';
+import type { KubeconfigAttributes, KubeconfigProps } from './kubeconfig.ts';
+import { kubeconfigMetadata, sha256 } from './values.ts';
+
+const generation = (meta: {
+  endpoint: string;
+  caFingerprint: string;
+  clientFingerprint: string;
+  context: string;
+}) => sha256(`${meta.context}\n${meta.endpoint}\n${meta.caFingerprint}\n${meta.clientFingerprint}`);
+
+/**
+ * ⛔ I2 FIX (LAND red team, 2026-09-26) — NEVER LEAVE `path` UNDEFINED. An undefined `path` here
+ *   made the stock `Kubernetes.KubeConfigAdapter` fall back to `$KUBECONFIG`/`~/.kube/config`
+ *   (alchemy `Kubernetes/internal/kubeconfig.ts`'s `resolveKubeConfigPath`, wired in
+ *   `BuiltinAdapters.ts`) — exactly the un-vaulted, possibly-stale-context exposure this whole
+ *   family exists to remove. A consumer wiring `Kubernetes.*` to `kube.connection` (this
+ *   attribute's own doc invites exactly that) would silently connect through whatever
+ *   `admin@<cluster>` context happens to be on the operator's machine. `Kubernetes.ClusterAdapter`
+ *   is not yet wired to `mintKubeconfig` (kubeconfig.ts's own header) — no real path exists for
+ *   this connection to use — so it must fail LOUDLY instead of silently succeeding against a
+ *   stranger's cluster. A path that can never resolve does that: `resolveKubeContext` fails at
+ *   `fs.readFileString` naming this exact sentinel, instead of reading whatever real file happens
+ *   to be on `$KUBECONFIG`.
+ */
+const UNWIRED_KUBECONFIG_PATH =
+  '/talos-first-boot-unwired/wire-Kubernetes.ClusterAdapter-to-mintKubeconfig';
+
+const toConnection = (props: KubeconfigProps): Connection => ({
+  auth: { context: props.context, kind: 'kubeconfig', path: UNWIRED_KUBECONFIG_PATH },
+});
+
+/** Parse `raw` kubeconfig YAML into public, persistable attributes, or `undefined` if it fails to. */
+export const buildAttrs = (
+  raw: string,
+  props: KubeconfigProps,
+): KubeconfigAttributes | undefined => {
+  const meta = kubeconfigMetadata(raw, props.context);
+  if (meta === undefined) return undefined;
+  return {
+    certificateAuthorityFingerprint: meta.caFingerprint,
+    clientCertificateFingerprint: meta.clientFingerprint,
+    connection: toConnection(props),
+    context: props.context,
+    credentialGeneration: generation({ ...meta, context: props.context }),
+    endpoint: meta.endpoint,
+  };
+};

package/src/talos/kubeconfig.test.ts

@@ -0,0 +1,256 @@
+/**
+ * `Talos.Kubeconfig` landing in OpenBao, written once at bring-up (K-talos-first-boot). Fully
+ * offline: fake-process.ts fakes `bao`/`talosctl`; the fake `talosctl kubeconfig` handler writes a
+ * fixture file to the temp path it was given, standing in for what the real binary would do.
+ *
+ * ⚠️ FIXTURES ONLY — see values.test.ts's own header for why the base64 fields are built from
+ *   plain words at run time rather than written out literally.
+ */
+import assert from 'node:assert/strict';
+import { existsSync, writeFileSync } from 'node:fs';
+import { describe, it } from 'node:test';
+import * as Effect from 'effect/Effect';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import { type FakeCall, fakeSpawner } from './fake-process.ts';
+import {
+  type KubeconfigAttributes,
+  type KubeconfigProps,
+  diffKubeconfig as diff,
+  readKubeconfig as read,
+  reconcileKubeconfig as reconcile,
+} from './kubeconfig.ts';
+
+const b64 = (words: string) => Buffer.from(words).toString('base64');
+
+const fixtureKubeconfig = (marker: string) => `
+apiVersion: v1
+kind: Config
+clusters:
+  - name: hf-c1
+    cluster:
+      server: https://192.0.2.50:6443
+      certificate-authority-data: ${b64(`not a ca ${marker}`)}
+contexts:
+  - name: admin@hf-c1
+    context: { cluster: hf-c1, user: admin@hf-c1 }
+users:
+  - name: admin@hf-c1
+    user:
+      client-certificate-data: ${b64(`not a certificate ${marker}`)}
+      client-key-data: ${b64(`not a key ${marker}`)}
+current-context: admin@hf-c1
+`;
+
+const TARGET = { cluster: 'c1', mount: 'talos-c1' };
+const props = (): KubeconfigProps => ({
+  context: 'admin@hf-c1',
+  node: '198.51.100.10',
+  target: TARGET,
+});
+
+const run = <A, E>(
+  effect: Effect.Effect<A, E, ChildProcessSpawner.ChildProcessSpawner>,
+  handler: (c: FakeCall) => { stdout?: string; stderr?: string; exitCode?: number },
+  calls: FakeCall[] = [],
+) =>
+  Effect.runPromise(
+    Effect.provideService(
+      effect,
+      ChildProcessSpawner.ChildProcessSpawner,
+      fakeSpawner(handler, calls),
+    ),
+  );
+
+describe('reconcile — CREATE writes talosctl kubeconfig output into the vault, never a host path', () => {
+  it('mints the temp file, writes its content to vault via stdin, cleans up the temp file', async () => {
+    const calls: FakeCall[] = [];
+    let outPath = '';
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'fake-talosconfig' } } }) };
+      }
+      if (call.command === 'bao' && call.args[1] === 'put') return {};
+      if (call.command === 'talosctl' && call.args[0] === 'kubeconfig') {
+        outPath = call.args[1] ?? '';
+        writeFileSync(outPath, fixtureKubeconfig('create'));
+        return {};
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = (await run(
+      reconcile(props(), undefined),
+      handler,
+      calls,
+    )) as KubeconfigAttributes;
+
+    assert.equal(result.endpoint, 'https://192.0.2.50:6443');
+    assert.equal(result.context, 'admin@hf-c1');
+    assert.equal(result.connection.auth.kind, 'kubeconfig');
+    // ⛔ I2 (LAND red team): NEVER undefined — an undefined `path` here would let the stock
+    // KubeConfigAdapter fall back to $KUBECONFIG/~/.kube/config. It must be a path that can never
+    // resolve, so a consumer that isn't yet wired to mintKubeconfig fails loudly instead of quietly
+    // reaching the operator's own cluster.
+    const authPath = (result.connection.auth as { path?: string }).path;
+    assert.ok(typeof authPath === 'string' && authPath.length > 0);
+
+    const put = calls.find((c) => c.command === 'bao' && c.args[1] === 'put');
+    assert.ok(put);
+    // ⛔ C2 (LAND red team): `=-`, never `=@-` — see credentials-write.ts's own header.
+    assert.deepEqual(put.args, ['kv', 'put', 'talos-c1/kubeconfig', 'kubeconfig=-']);
+    assert.equal(put.stdin, fixtureKubeconfig('create'));
+    assert.ok(!put.args.some((a) => a.includes('not a key')), 'never in argv');
+
+    assert.equal(existsSync(outPath), false, 'the captured temp file must be gone after reconcile');
+  });
+});
+
+describe('reconcile — write-once: a second reconcile never re-runs talosctl kubeconfig', () => {
+  it('confirms from the vault copy instead of minting a new admin cert', async () => {
+    const calls: FakeCall[] = [];
+    const priorOutput: KubeconfigAttributes = {
+      certificateAuthorityFingerprint: 'x',
+      clientCertificateFingerprint: 'x',
+      connection: { auth: { context: 'admin@hf-c1', kind: 'kubeconfig' } },
+      context: 'admin@hf-c1',
+      credentialGeneration: 'x',
+      endpoint: 'https://192.0.2.50:6443',
+    };
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        return {
+          stdout: JSON.stringify({ data: { data: { config: fixtureKubeconfig('confirm') } } }),
+        };
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = (await run(
+      reconcile(props(), priorOutput),
+      handler,
+      calls,
+    )) as KubeconfigAttributes;
+
+    assert.equal(result.endpoint, 'https://192.0.2.50:6443');
+    assert.ok(
+      calls.every(
+        (c) => !(c.command === 'talosctl') && !(c.command === 'bao' && c.args[1] === 'put'),
+      ),
+      'a confirm-only reconcile never spawns talosctl or writes the vault again',
+    );
+  });
+});
+
+describe('read — C1 fix: undefined means genuinely absent, never "some read failed"', () => {
+  it('returns undefined (never a defined empty object) when the vault key was never written', async () => {
+    // ⛔ MEASURED against OpenBao v2.6.2: this exit code + stderr text is exactly what `bao kv get`
+    // prints for a genuinely unwritten KV-v2 key — see kubeconfig.ts's `isVaultKeyAbsent` header.
+    const result = await run(read(props()), () => ({
+      exitCode: 2,
+      stderr: 'No value found at talos-c1/data/kubeconfig',
+    }));
+    assert.equal(result, undefined);
+  });
+
+  it('propagates a genuine vault/transport failure instead of reading it as absence', async () => {
+    await assert.rejects(
+      run(read(props()), () => ({ exitCode: 2, stderr: 'permission denied' })),
+      (error: unknown) => error instanceof Error && error.message.includes('permission denied'),
+    );
+  });
+});
+
+describe('read → reconcile chained the way the Alchemy engine drives a cold start (C1 regression)', () => {
+  it('a cold-start read (undefined) followed by reconcile(undefined) actually creates', async () => {
+    // ⛔ Alchemy beta.79 Plan.ts:1303-1352 always calls `read` first when there is no state row; a
+    // DEFINED result there is adopted and forces `update`, so this is the exact sequence that made
+    // Talos.Kubeconfig un-creatable before the C1 fix — see kubeconfig.ts's own `readKubeconfig`
+    // header.
+    const calls: FakeCall[] = [];
+    const coldHandler = () => ({
+      exitCode: 2,
+      stderr: 'No value found at talos-c1/data/kubeconfig',
+    });
+    const readResult = await run(read(props()), coldHandler, calls);
+    assert.equal(
+      readResult,
+      undefined,
+      "the engine's adoption probe must see a genuine cold start",
+    );
+
+    const createHandler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        // ★ mintTalosconfig reads the `talosconfig` key first — only the `kubeconfig` key itself
+        // is genuinely absent at a cold start.
+        return call.args[3]?.endsWith('/kubeconfig')
+          ? coldHandler()
+          : { stdout: JSON.stringify({ data: { data: { talosconfig: 'fake-talosconfig' } } }) };
+      }
+      if (call.command === 'bao' && call.args[1] === 'put') return {};
+      if (call.command === 'talosctl' && call.args[0] === 'kubeconfig') {
+        writeFileSync(call.args[1] ?? '', fixtureKubeconfig('engine-order'));
+        return {};
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const created = (await run(
+      reconcile(props(), readResult),
+      createHandler,
+    )) as KubeconfigAttributes;
+    assert.equal(created.endpoint, 'https://192.0.2.50:6443');
+    assert.notEqual(created.credentialGeneration, '');
+  });
+});
+
+describe('reconcile — belt-and-suspenders: a defined-but-empty output is treated as absent (C1)', () => {
+  it('a pre-fix-shaped empty output still runs CREATE instead of failing to confirm', async () => {
+    const staleEmptyOutput: KubeconfigAttributes = {
+      certificateAuthorityFingerprint: '',
+      clientCertificateFingerprint: '',
+      connection: { auth: { context: 'admin@hf-c1', kind: 'kubeconfig' } },
+      context: 'admin@hf-c1',
+      credentialGeneration: '',
+      endpoint: '',
+    };
+    const handler = (call: FakeCall) => {
+      if (call.command === 'bao' && call.args[1] === 'get') {
+        return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+      }
+      if (call.command === 'bao' && call.args[1] === 'put') return {};
+      if (call.command === 'talosctl' && call.args[0] === 'kubeconfig') {
+        writeFileSync(call.args[1] ?? '', fixtureKubeconfig('stale-empty'));
+        return {};
+      }
+      throw new Error(`unexpected call ${JSON.stringify(call)}`);
+    };
+    const result = (await run(
+      reconcile(props(), staleEmptyOutput),
+      handler,
+    )) as KubeconfigAttributes;
+    assert.notEqual(result.credentialGeneration, '');
+  });
+});
+
+describe('diff', () => {
+  it('plans noop when the vault copy matches state', async () => {
+    const output: KubeconfigAttributes = (await run(
+      reconcile(props(), undefined),
+      (call: FakeCall) => {
+        if (call.command === 'bao' && call.args[1] === 'get') {
+          return { stdout: JSON.stringify({ data: { data: { talosconfig: 'x' } } }) };
+        }
+        if (call.command === 'bao' && call.args[1] === 'put') return {};
+        if (call.command === 'talosctl') {
+          writeFileSync(call.args[1] ?? '', fixtureKubeconfig('diff'));
+          return {};
+        }
+        throw new Error('unexpected');
+      },
+    )) as KubeconfigAttributes;
+
+    const result = await run(diff(props(), output), (call: FakeCall) =>
+      call.args[1] === 'get'
+        ? { stdout: JSON.stringify({ data: { data: { config: fixtureKubeconfig('diff') } } }) }
+        : {},
+    );
+    assert.equal(result?.action, 'noop');
+  });
+});