@homeflare/alchemy 0.1.0

package/src/talos/kubeconfig.ts

@@ -0,0 +1,170 @@
+/**
+ * `Talos.Kubeconfig` — fetch admin kubeconfig so `Kubernetes.*` workloads can connect.
+ *
+ * ★ REASONED FROM talosctl kubeconfig (Talos v1.13 CLI reference): writes a kubeconfig file;
+ *   `--merge=false` keeps it isolated; `-f/--force` overwrites an existing file.
+ *
+ * ⛔ THE KUBECONFIG FILE CONTAINS A CLIENT CERTIFICATE — IT MUST NOT BE AN ATTRIBUTE. Alchemy
+ *   persists attributes unencrypted. This resource:
+ *     - writes the file to `runtimePath` at reconcile time (re-minted each deploy),
+ *     - persists ONLY public metadata + fingerprints,
+ *     - exposes a `connection` field referencing the runtime path for `Kubernetes.ClusterAdapter`.
+ *
+ * ⚠️ `runtimePath` IS PERSISTED AS A STRING, NOT AS FILE CONTENTS. The path is a contract between
+ *   this resource and the host filesystem — same pattern as pointing Kubernetes.KubeConfig at
+ *   `/opt/homeflare/...` rendered outside Postgres.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { Connection } from 'alchemy/Kubernetes/Connection';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTalosconfig } from './credentials.ts';
+import type { TalosRequirements, WithTarget } from './resource.ts';
+import { talosctl } from './talosctl.ts';
+import { kubeconfigMetadata, sha256 } from './values.ts';
+
+export interface KubeconfigProps extends WithTarget {
+  /** Node that serves `talosctl kubeconfig`. */
+  node: string;
+  /** Context name inside the generated kubeconfig — not secret. */
+  context: string;
+  /**
+   * Host path where talosctl writes the kubeconfig each reconcile.
+   *
+   * ⛔ Must be outside Alchemy state and rotated by redeploy, never copied into attributes.
+   */
+  runtimePath: string;
+  after?: readonly unknown[];
+}
+
+export interface KubeconfigAttributes {
+  context: string;
+  endpoint: string;
+  certificateAuthorityFingerprint: string;
+  clientCertificateFingerprint: string;
+  /** Digest of endpoint+context+fingerprints — detects credential rotation without storing PEM. */
+  credentialGeneration: string;
+  /**
+   * Serializable `Kubernetes.Connection` for downstream workloads.
+   *
+   * ★ auth.kind `kubeconfig` is the stock ClusterAdapter — provider-roadmap.md names this seam.
+   *   Only `path` and `context` appear here; the adapter reads credentials from disk at call time.
+   */
+  connection: Connection;
+}
+
+export interface TalosKubeconfig extends Resource<
+  'Talos.Kubeconfig',
+  KubeconfigProps,
+  KubeconfigAttributes,
+  never,
+  TalosRequirements
+> {}
+
+export const TalosKubeconfig = Resource<TalosKubeconfig>('Talos.Kubeconfig');
+
+const generation = (meta: {
+  endpoint: string;
+  caFingerprint: string;
+  clientFingerprint: string;
+  context: string;
+}) => sha256(`${meta.context}\n${meta.endpoint}\n${meta.caFingerprint}\n${meta.clientFingerprint}`);
+
+const toConnection = (props: KubeconfigProps): Connection => ({
+  auth: { context: props.context, kind: 'kubeconfig', path: props.runtimePath },
+});
+
+const readFileMeta = (props: KubeconfigProps) =>
+  Effect.gen(function* () {
+    const text = yield* Effect.tryPromise({
+      try: () => Bun.file(props.runtimePath).text(),
+      catch: (cause) => new Error(String(cause)),
+    }).pipe(Effect.orElseSucceed(() => undefined as string | undefined));
+    if (text === undefined) return undefined;
+    const meta = kubeconfigMetadata(text, 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,
+    };
+  });
+
+const read = (props: KubeconfigProps) =>
+  readFileMeta(props).pipe(
+    Effect.map((meta) =>
+      meta === undefined
+        ? {
+            certificateAuthorityFingerprint: '',
+            clientCertificateFingerprint: '',
+            connection: toConnection(props),
+            context: props.context,
+            credentialGeneration: '',
+            endpoint: '',
+          }
+        : meta,
+    ),
+  );
+
+const diff = (news: Input<KubeconfigProps>, output: KubeconfigAttributes | undefined) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* read(news);
+    if (
+      live.credentialGeneration !== '' &&
+      output.credentialGeneration === live.credentialGeneration &&
+      output.context === live.context &&
+      output.endpoint === live.endpoint
+    ) {
+      return { action: 'noop' } as const;
+    }
+    return { action: 'update' } as const;
+  });
+
+const reconcile = (props: KubeconfigProps) =>
+  Effect.gen(function* () {
+    const credential = yield* mintTalosconfig(props.target);
+    yield* talosctl(
+      [
+        'kubeconfig',
+        props.runtimePath,
+        '--merge=false',
+        '--force',
+        '--force-context-name',
+        props.context,
+      ],
+      { nodes: [props.node], talosconfigPath: credential.talosconfigPath },
+    );
+    const meta = yield* readFileMeta(props);
+    if (meta === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `${props.runtimePath}: talosctl kubeconfig returned no error but the file is missing ` +
+            'or unparsable. Read back rather than trusting the exit code alone.',
+        ),
+      );
+    }
+    return meta;
+  });
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<KubeconfigProps>;
+    output: KubeconfigAttributes | undefined;
+  }) => diff(news, output),
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: KubeconfigProps }) => read(olds),
+  reconcile: ({ news }: { news: KubeconfigProps }) => reconcile(news),
+};
+
+export const TalosKubeconfigProvider = () =>
+  Provider.effect(TalosKubeconfig, Effect.succeed(TalosKubeconfig.Provider.of(handlers)));

package/src/talos/resource.ts

@@ -0,0 +1,31 @@
+/**
+ * Talos has no REST CRUD factory — and pretending otherwise would lie in every plan.
+ *
+ * ⛔ THE FORGEJO/PVE FACTORY IS create / read / update / delete OVER ONE JSON OBJECT AT ONE PATH.
+ *   Talos machine configuration is `talosctl apply-config`; bootstrap is a one-shot
+ *   `talosctl bootstrap`; health is `talosctl health`; kubeconfig is `talosctl kubeconfig`. None
+ *   of those are the same four operations with a different path — bootstrap cannot be deleted,
+ *   health is a gate not an object, and kubeconfig must not round-trip credential bytes through
+ *   Postgres. Copying forgejoOperations here would force `matches` to compare a declaration to
+ *   itself and answer `noop` forever, exactly the failure mode documented on Proxmox.NetworkApply.
+ *
+ * ★ SO EACH FAMILY BELOW HAND-WRITES THE FIVE PROVIDER HANDLERS, LIKE network-apply.ts and
+ *   sdn-apply.ts. Shared pieces are credentials.ts (mint) and talosctl.ts (spawn).
+ *
+ * ⚠️ EVERY CLAIM ABOUT talosctl FLAGS IN THIS PACKAGE IS REASONED FROM THE PUBLISHED CLI REFERENCE
+ *   (Talos v1.13 docs, fetched 2026-09-13 in this session). Nothing was measured on a live cluster.
+ */
+import type * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+import type { TalosTarget } from './credentials.ts';
+
+/**
+ * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME — ChildProcessSpawner only.
+ *
+ *   Talos credentials are minted by shelling out to `bao` and then shelling out to `talosctl`.
+ *   There is no HttpClient call in this package on purpose: the published operator surface is the
+ *   CLI, and a parallel gRPC client would be a second SDK the repo rules forbid.
+ */
+export type TalosRequirements = ChildProcessSpawner.ChildProcessSpawner;
+
+/** Every resource names which cluster's OpenBao mount it uses. */
+export type WithTarget = { target: TalosTarget };

package/src/talos/talos-bootstrap.ts

@@ -0,0 +1,109 @@
+/**
+ * `Talos.Bootstrap` — initialize etcd once on ONE control-plane node.
+ *
+ * ★ REASONED FROM talosctl bootstrap (Talos v1.13 CLI reference): one node aborts the etcd join
+ *   loop and forms the initial cluster; other control-plane nodes join after Kubernetes starts on
+ *   the bootstrap node. This command must run exactly once per cluster.
+ *
+ * ⛔ NOT A FACTORY RESOURCE — bootstrap cannot be deleted or updated in place; `delete` is a no-op.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTalosconfig } from './credentials.ts';
+import type { TalosRequirements, WithTarget } from './resource.ts';
+import { talosctl, talosctlOrAlready } from './talosctl.ts';
+
+export interface BootstrapProps extends WithTarget {
+  /** The ONE control-plane node that receives `talosctl bootstrap`. */
+  node: string;
+  /** Machine configs for this node (and peers) must be applied first. */
+  after?: readonly unknown[];
+}
+
+export interface BootstrapAttributes {
+  node: string;
+  bootstrapped: boolean;
+}
+
+export interface TalosBootstrap extends Resource<
+  'Talos.Bootstrap',
+  BootstrapProps,
+  BootstrapAttributes,
+  never,
+  TalosRequirements
+> {}
+
+export const TalosBootstrap = Resource<TalosBootstrap>('Talos.Bootstrap', {
+  /** etcd data is irreplaceable — opt into destroy explicitly if Talos ever adds an undo. */
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * REASONED: `talosctl get etcdmembers -o json` should list members after bootstrap.
+ * ⚠️ NOT MEASURED — first live deploy confirms the resource type name.
+ */
+const isBootstrapped = (props: BootstrapProps, talosconfigPath: string) =>
+  talosctl(['get', 'etcdmembers', '-o', 'json'], {
+    nodes: [props.node],
+    talosconfigPath,
+  }).pipe(
+    Effect.map((text) => text.includes('"id"') || text.includes('"member"')),
+    Effect.orElseSucceed(() => false),
+  );
+
+const read = (props: BootstrapProps) =>
+  Effect.gen(function* () {
+    const credential = yield* mintTalosconfig(props.target);
+    const bootstrapped = yield* isBootstrapped(props, credential.talosconfigPath);
+    return { bootstrapped, node: props.node };
+  });
+
+const diff = (news: Input<BootstrapProps>, output: BootstrapAttributes | undefined) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* read(news);
+    if (live.bootstrapped) return { action: 'noop' } as const;
+    return { action: 'update' } as const;
+  });
+
+const reconcile = (props: BootstrapProps) =>
+  Effect.gen(function* () {
+    const credential = yield* mintTalosconfig(props.target);
+    const before = yield* isBootstrapped(props, credential.talosconfigPath);
+    if (!before) {
+      yield* talosctlOrAlready(['bootstrap'], {
+        nodes: [props.node],
+        talosconfigPath: credential.talosconfigPath,
+      });
+    }
+    const after = yield* isBootstrapped(props, credential.talosconfigPath);
+    if (!after) {
+      return yield* Effect.die(
+        new Error(
+          `${props.node}: bootstrap returned no error but etcd members are still absent. ` +
+            'Read back rather than trusting the exit code alone.',
+        ),
+      );
+    }
+    return { bootstrapped: true, node: props.node };
+  });
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<BootstrapProps>;
+    output: BootstrapAttributes | undefined;
+  }) => diff(news, output),
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: BootstrapProps }) => read(olds),
+  reconcile: ({ news }: { news: BootstrapProps }) => reconcile(news),
+};
+
+export const TalosBootstrapProvider = () =>
+  Provider.effect(TalosBootstrap, Effect.succeed(TalosBootstrap.Provider.of(handlers)));

package/src/talos/talos-cluster-health.ts

@@ -0,0 +1,119 @@
+/**
+ * `Talos.ClusterHealth` — readiness gate other resources can depend on via `after`.
+ *
+ * ★ REASONED FROM talosctl health (Talos v1.13 CLI reference): checks Talos services, etcd, and
+ *   Kubernetes component health; `--wait-timeout` defaults to 20m0s.
+ *
+ * ⚠️ PLAN READS USE A SHORT TIMEOUT SO `plan` DOES NOT BLOCK TWENTY MINUTES. Reconcile uses the
+ *   declared timeout — that is the deploy gate, not the plan gate.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTalosconfig } from './credentials.ts';
+import type { TalosRequirements, WithTarget } from './resource.ts';
+import { talosctl } from './talosctl.ts';
+
+export interface ClusterHealthProps extends WithTarget {
+  /** Control-plane node IPs passed to `--control-plane-nodes`. */
+  controlPlaneNodes: readonly string[];
+  /** Worker node IPs passed to `--worker-nodes`. */
+  workerNodes?: readonly string[];
+  /**
+   * Reconcile wait (`--wait-timeout`), e.g. `20m0s`. Default from published CLI.
+   *
+   * ⚠️ REASONED default — not measured here.
+   */
+  waitTimeout?: string;
+  /** Bootstrap and kubeconfig should complete before health is enforced. */
+  after?: readonly unknown[];
+}
+
+export interface ClusterHealthAttributes {
+  healthy: boolean;
+  controlPlaneNodes: string;
+  workerNodes: string;
+}
+
+export interface TalosClusterHealth extends Resource<
+  'Talos.ClusterHealth',
+  ClusterHealthProps,
+  ClusterHealthAttributes,
+  never,
+  TalosRequirements
+> {}
+
+export const TalosClusterHealth = Resource<TalosClusterHealth>('Talos.ClusterHealth');
+
+const nodeCsv = (nodes: readonly string[] | undefined) =>
+  nodes === undefined || nodes.length === 0 ? '' : nodes.join(',');
+
+const healthArgs = (props: ClusterHealthProps, waitTimeout: string) => {
+  const args = ['health', '--wait-timeout', waitTimeout];
+  const cp = nodeCsv(props.controlPlaneNodes);
+  const workers = nodeCsv(props.workerNodes);
+  if (cp !== '') args.push('--control-plane-nodes', cp);
+  if (workers !== '') args.push('--worker-nodes', workers);
+  return args;
+};
+
+const check = (props: ClusterHealthProps, waitTimeout: string) =>
+  Effect.gen(function* () {
+    const credential = yield* mintTalosconfig(props.target);
+    yield* talosctl(healthArgs(props, waitTimeout), {
+      nodes: [...props.controlPlaneNodes],
+      talosconfigPath: credential.talosconfigPath,
+    });
+    return {
+      controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
+      healthy: true,
+      workerNodes: nodeCsv(props.workerNodes),
+    };
+  });
+
+const read = (props: ClusterHealthProps) =>
+  check(props, '5s').pipe(
+    Effect.orElseSucceed(() => ({
+      controlPlaneNodes: nodeCsv(props.controlPlaneNodes),
+      healthy: false,
+      workerNodes: nodeCsv(props.workerNodes),
+    })),
+  );
+
+const diff = (news: Input<ClusterHealthProps>, output: ClusterHealthAttributes | undefined) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* read(news);
+    if (live.healthy) return { action: 'noop' } as const;
+    return { action: 'update' } as const;
+  });
+
+const reconcile = (props: ClusterHealthProps) =>
+  check(props, props.waitTimeout ?? '20m0s').pipe(
+    Effect.mapError(
+      (cause) =>
+        new Error(
+          `Talos.ClusterHealth ${props.target.cluster}: cluster not healthy within ` +
+            `${props.waitTimeout ?? '20m0s'} — ${String(cause)}`,
+        ),
+    ),
+  );
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<ClusterHealthProps>;
+    output: ClusterHealthAttributes | undefined;
+  }) => diff(news, output),
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: ClusterHealthProps }) => read(olds),
+  reconcile: ({ news }: { news: ClusterHealthProps }) => reconcile(news),
+};
+
+export const TalosClusterHealthProvider = () =>
+  Provider.effect(TalosClusterHealth, Effect.succeed(TalosClusterHealth.Provider.of(handlers)));

package/src/talos/talos-machine-config.ts

@@ -0,0 +1,146 @@
+/**
+ * `Talos.MachineConfig` — apply one machine configuration document to one node.
+ *
+ * ★ REASONED FROM talosctl apply-config (Talos v1.13 CLI reference): `-f/--file`, `-n/--nodes`,
+ *   `-m/--mode`, `-i/--insecure` for maintenance mode, `--dry-run` for planning without a write.
+ *
+ * ⛔ THE CONFIG BODY IS NEVER AN ATTRIBUTE. Machine configs can embed cluster tokens; only a digest
+ *   of the repo file is persisted. Read `configFile` from disk at reconcile time.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTalosconfig } from './credentials.ts';
+import type { TalosRequirements, WithTarget } from './resource.ts';
+import { talosctl } from './talosctl.ts';
+import { configDigest, resolveConfigPath } from './values.ts';
+
+const STACK_DIR = new URL('..', import.meta.url).pathname;
+
+export type ApplyMode = 'auto' | 'no-reboot' | 'reboot' | 'staged' | 'try';
+
+export interface MachineConfigProps extends WithTarget {
+  /** Node IP or hostname — the `-n` target. */
+  node: string;
+  /** Repo-relative or absolute path to the YAML file passed to `-f`. */
+  configFile: string;
+  /** talosctl `-m` mode. Default `auto` per published CLI. */
+  mode?: ApplyMode;
+  /**
+   * Maintenance-mode apply only (`-i`). Default false — post-bootstrap applies use talosconfig auth.
+   *
+   * ⚠️ REASONED: docs describe `--insecure` for the first apply before talosconfig exists.
+   */
+  insecure?: boolean;
+  /** Ordering edge — e.g. wait for Proxmox.Vm. */
+  after?: readonly unknown[];
+}
+
+export interface MachineConfigAttributes {
+  node: string;
+  configDigest: string;
+  mode: ApplyMode;
+  /** True when the node's reported config digest matches the declared file. */
+  converged: boolean;
+}
+
+export interface TalosMachineConfig extends Resource<
+  'Talos.MachineConfig',
+  MachineConfigProps,
+  MachineConfigAttributes,
+  never,
+  TalosRequirements
+> {}
+
+export const TalosMachineConfig = Resource<TalosMachineConfig>('Talos.MachineConfig');
+
+const loadDigest = (props: MachineConfigProps) =>
+  Effect.gen(function* () {
+    const path = resolveConfigPath(STACK_DIR, props.configFile);
+    const text = yield* Effect.tryPromise({
+      try: () => Bun.file(path).text(),
+      catch: (cause) => new Error(`reading ${props.configFile}: ${String(cause)}`),
+    });
+    return configDigest(text);
+  });
+
+/** REASONED: `talosctl get machineconfig -o yaml` returns the live document. */
+const liveDigest = (props: MachineConfigProps, talosconfigPath: string) =>
+  talosctl(['get', 'machineconfig', '-o', 'yaml'], {
+    nodes: [props.node],
+    talosconfigPath,
+  }).pipe(
+    Effect.map((yaml) => configDigest(yaml)),
+    Effect.orElseSucceed(() => undefined),
+  );
+
+const read = (props: MachineConfigProps) =>
+  Effect.gen(function* () {
+    const wanted = yield* loadDigest(props);
+    const credential = yield* mintTalosconfig(props.target);
+    const live = yield* liveDigest(props, credential.talosconfigPath);
+    return {
+      configDigest: wanted,
+      converged: live === wanted,
+      mode: props.mode ?? 'auto',
+      node: props.node,
+    };
+  });
+
+const diff = (news: Input<MachineConfigProps>, output: MachineConfigAttributes | undefined) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    const live = yield* read(news);
+    if (live.converged) return { action: 'noop' } as const;
+    return { action: 'update' } as const;
+  });
+
+const reconcile = (props: MachineConfigProps) =>
+  Effect.gen(function* () {
+    const path = resolveConfigPath(STACK_DIR, props.configFile);
+    const wanted = yield* loadDigest(props);
+    const credential = yield* mintTalosconfig(props.target);
+    const args = [
+      'apply-config',
+      '--file',
+      path,
+      '--mode',
+      props.mode ?? 'auto',
+      ...(props.insecure === true ? ['--insecure'] : []),
+    ];
+    yield* talosctl(args, { nodes: [props.node], talosconfigPath: credential.talosconfigPath });
+    const live = yield* liveDigest(props, credential.talosconfigPath);
+    if (live !== wanted) {
+      return yield* Effect.die(
+        new Error(
+          `${props.node}: apply-config returned no error but machineconfig digest still differs. ` +
+            'Read back rather than trusting the exit code alone.',
+        ),
+      );
+    }
+    return {
+      configDigest: wanted,
+      converged: true,
+      mode: props.mode ?? 'auto',
+      node: props.node,
+    };
+  });
+
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<MachineConfigProps>;
+    output: MachineConfigAttributes | undefined;
+  }) => diff(news, output),
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: MachineConfigProps }) => read(olds),
+  reconcile: ({ news }: { news: MachineConfigProps }) => reconcile(news),
+};
+
+export const TalosMachineConfigProvider = () =>
+  Provider.effect(TalosMachineConfig, Effect.succeed(TalosMachineConfig.Provider.of(handlers)));

package/src/talos/talosctl.ts

@@ -0,0 +1,94 @@
+/**
+ * One `talosctl` invocation — stdout/stderr captured, secrets never echoed.
+ *
+ * ★ SHELL OUT LIKE ALCHEMY'S DOCKER PROVIDER (ChildProcessSpawner), NOT A SECOND SDK. Talos speaks
+ *   gRPC; the published, stable surface for operators is `talosctl`. No Talos npm package is added.
+ *
+ * ⚠️ REASONED FROM docs.siderolabs.com/talos/v1.13/reference/cli — nothing here was measured on a
+ *   live cluster in this session.
+ *
+ * ⛔ DO NOT LOG STDOUT ON FAILURE. `talosctl kubeconfig` and error paths have been observed in the
+ *   wild to include credential material; stderr is the safe diagnostic channel.
+ */
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+import * as ChildProcess from 'effect/unstable/process/ChildProcess';
+import * as ChildProcessSpawner from 'effect/unstable/process/ChildProcessSpawner';
+
+export class TalosError extends Error {
+  constructor(
+    readonly command: string,
+    readonly exitCode: number,
+    detail: string,
+  ) {
+    super(`talosctl ${command} -> ${String(exitCode)}: ${detail}`);
+    this.name = 'TalosError';
+  }
+}
+
+export type TalosRunOptions = {
+  readonly talosconfigPath: string;
+  readonly nodes?: readonly string[];
+  readonly endpoints?: readonly string[];
+};
+
+/** Run `talosctl <args…>`. Returns trimmed stdout, or '' when empty. */
+export const talosctl = (args: readonly string[], options: TalosRunOptions) =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const argv = [
+      ...args,
+      '--talosconfig',
+      options.talosconfigPath,
+      ...(options.nodes === undefined ? [] : ['--nodes', options.nodes.join(',')]),
+      ...(options.endpoints === undefined ? [] : ['--endpoints', options.endpoints.join(',')]),
+    ];
+    const result = yield* ChildProcess.make('talosctl', argv, {
+      detached: false,
+      extendEnv: true,
+      stderr: 'pipe',
+      stdin: 'ignore',
+      stdout: 'pipe',
+    }).pipe(
+      spawner.spawn,
+      Effect.flatMap((child) =>
+        Effect.all(
+          {
+            exitCode: child.exitCode,
+            stderr: child.stderr.pipe(
+              Stream.decodeText,
+              Stream.mkString,
+              Effect.map((text) => text.trim()),
+            ),
+            stdout: child.stdout.pipe(
+              Stream.decodeText,
+              Stream.mkString,
+              Effect.map((text) => text.trim()),
+            ),
+          },
+          { concurrency: 'unbounded' },
+        ),
+      ),
+      Effect.scoped,
+    );
+
+    const command = args.join(' ');
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(
+        new TalosError(command, result.exitCode, result.stderr.slice(0, 300)),
+      );
+    }
+    return result.stdout;
+  });
+
+/** Like `talosctl`, but exit code 1 with "already" in stderr is treated as success. */
+export const talosctlOrAlready = (args: readonly string[], options: TalosRunOptions) =>
+  talosctl(args, options).pipe(
+    Effect.catchIf(
+      (cause): cause is TalosError =>
+        cause instanceof TalosError &&
+        cause.exitCode !== 0 &&
+        /already|exists|bootstrapped/i.test(cause.message),
+      () => Effect.succeed(''),
+    ),
+  );