Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
feat(switchdash): persisted, sequential host setup plan model + runner (CHOO-1809)
switch-worker-louis-remote8aae7f3e93fb
diff --git a/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.test.ts b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.test.tsnew file mode 100644index 000000000..7cf676398--- /dev/null+++ b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.test.ts@@ -0,0 +1,401 @@+import { describe, expect, it, vi } from 'vitest';+import type { HostSetupPlan, HostSetupStep } from '@shared/core/remote-hosts/setup';+import {+ HostSetupAbortedError,+ HostSetupRunner,+ type StepCheckResult,+ type StepInstallResult,+} from './host-setup-runner';++function step(id: string, patch: Partial<HostSetupStep> = {}): HostSetupStep {+ return {+ id,+ kind: 'core-dependency',+ name: id,+ state: 'pending',+ outcome: null,+ version: null,+ error: null,+ output: null,+ optional: false,+ dependsOn: [],+ updatedAt: '2026-01-01T00:00:00.000Z',+ ...patch,+ };+}++function plan(steps: HostSetupStep[]): HostSetupPlan {+ return {+ sshHost: 'dev-vm',+ status: 'idle',+ steps,+ currentStepId: null,+ createdAt: '2026-01-01T00:00:00.000Z',+ updatedAt: '2026-01-01T00:00:00.000Z',+ };+}++type Harness = {+ checks: Record<string, StepCheckResult[]>;+ installs: Record<string, StepInstallResult>;+ canInstall?: (id: string) => boolean;+ reachable?: boolean;+};++class Unreachable extends Error {}++function makeRunner(harness: Harness) {+ const saved: HostSetupPlan[] = [];+ const published: HostSetupPlan[] = [];+ const installOrder: string[] = [];+ const inFlight = { count: 0, max: 0 };++ const runner = new HostSetupRunner({+ sshHost: 'dev-vm',+ load: async () => null,+ save: async (p) => void saved.push(structuredClone(p)),+ publish: (p) => published.push(structuredClone(p)),+ check: async (s) => {+ const queue = harness.checks[s.id] ?? [{ outcome: 'satisfied' }];+ return queue.length > 1 ? queue.shift()! : queue[0]!;+ },+ install: async (s) => {+ installOrder.push(s.id);+ inFlight.count += 1;+ inFlight.max = Math.max(inFlight.max, inFlight.count);+ await Promise.resolve();+ inFlight.count -= 1;+ return harness.installs[s.id] ?? { ok: true };+ },+ canInstall: (s) => harness.canInstall?.(s.id) ?? true,+ requireReachable: () => {+ if (harness.reachable === false) throw new Unreachable('host down');+ },+ now: () => new Date('2026-02-02T00:00:00.000Z'),+ });++ return { runner, saved, published, installOrder, inFlight };+}++const stateOf = (p: HostSetupPlan, id: string) => p.steps.find((s) => s.id === id)!.state;++describe('HostSetupRunner', () => {+ it('marks already-satisfied steps satisfied without installing', async () => {+ const { runner, installOrder } = makeRunner({+ checks: { git: [{ outcome: 'satisfied', version: '2.43.0' }] },+ installs: {},+ });++ const result = await runner.run(plan([step('git')]));++ expect(result.status).toBe('complete');+ expect(stateOf(result, 'git')).toBe('satisfied');+ expect(installOrder).toEqual([]);+ });++ it('installs a missing dependency and verifies it afterwards', async () => {+ const { runner, installOrder } = makeRunner({+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied', version: '22.0.0' }] },+ installs: { node: { ok: true } },+ });++ const result = await runner.run(plan([step('node')]));++ expect(installOrder).toEqual(['node']);+ expect(stateOf(result, 'node')).toBe('satisfied');+ expect(result.steps[0]!.version).toBe('22.0.0');+ expect(result.status).toBe('complete');+ });++ it('fails the step when an install reports success but verification disagrees', async () => {+ // The installer's exit code is a claim; only the re-check is evidence.+ const { runner } = makeRunner({+ checks: { node: [{ outcome: 'missing' }, { outcome: 'missing' }] },+ installs: { node: { ok: true } },+ });++ const result = await runner.run(plan([step('node')]));++ expect(stateOf(result, 'node')).toBe('failed');+ expect(result.steps[0]!.error).toContain('still reports "missing" after installing');+ expect(result.status).toBe('halted');+ });++ it('installs strictly one at a time, in plan order', async () => {+ const { runner, installOrder, inFlight } = makeRunner({+ checks: {+ git: [{ outcome: 'missing' }, { outcome: 'satisfied' }],+ node: [{ outcome: 'missing' }, { outcome: 'satisfied' }],+ tmux: [{ outcome: 'missing' }, { outcome: 'satisfied' }],+ },+ installs: {},+ });++ await runner.run(plan([step('git'), step('node'), step('tmux')]));++ expect(installOrder).toEqual(['git', 'node', 'tmux']);+ expect(inFlight.max).toBe(1);+ });++ it('halts on failure, keeps earlier progress, and blocks later steps', async () => {+ const { runner, installOrder } = makeRunner({+ checks: {+ git: [{ outcome: 'satisfied' }],+ node: [{ outcome: 'missing' }],+ tmux: [{ outcome: 'missing' }],+ },+ installs: { node: { ok: false, error: 'apt-get failed', output: 'E: Unable to locate' } },+ });++ const result = await runner.run(plan([step('git'), step('node'), step('tmux')]));++ expect(result.status).toBe('halted');+ expect(stateOf(result, 'git')).toBe('satisfied'); // step 1 is not discarded+ expect(stateOf(result, 'node')).toBe('failed');+ expect(stateOf(result, 'tmux')).toBe('blocked'); // never attempted, and says so+ expect(installOrder).toEqual(['node']); // stopped; tmux was not installed+ expect(result.currentStepId).toBe('node');+ });++ it('preserves the failing step error and command output', async () => {+ const { runner } = makeRunner({+ checks: { node: [{ outcome: 'missing' }] },+ installs: { node: { ok: false, error: 'permission denied', output: 'sudo: no tty' } },+ });++ const result = await runner.run(plan([step('node')]));++ expect(result.steps[0]!.error).toBe('permission denied');+ expect(result.steps[0]!.output).toBe('sudo: no tty');+ });++ it('resumes from the failed step without redoing satisfied ones', async () => {+ // Each runner gets its own check queues — sharing them would let the first+ // run consume the second's answers and hide whether resume really re-probes.+ const first = makeRunner({+ checks: { git: [{ outcome: 'satisfied' }], node: [{ outcome: 'missing' }] },+ installs: { node: { ok: false, error: 'transient' } },+ });+ const halted = await first.runner.run(plan([step('git'), step('node')]));+ expect(halted.status).toBe('halted');++ // Resume with the persisted plan, exactly as a restart would. node is still+ // missing, so it must be re-attempted; git is satisfied and must not be.+ const second = makeRunner({+ checks: {+ git: [{ outcome: 'satisfied' }],+ node: [{ outcome: 'missing' }, { outcome: 'satisfied' }],+ },+ installs: { node: { ok: true } },+ });+ const resumed = await second.runner.run(halted);++ expect(resumed.status).toBe('complete');+ expect(second.installOrder).toEqual(['node']); // git was not re-installed+ });++ it('records unknown — never missing — when a probe throws', async () => {+ const runner = new HostSetupRunner({+ sshHost: 'dev-vm',+ load: async () => null,+ save: async () => {},+ publish: () => {},+ check: async () => {+ throw new Error('ssh channel closed');+ },+ install: async () => ({ ok: true }),+ canInstall: () => true,+ requireReachable: () => {},+ now: () => new Date('2026-02-02T00:00:00.000Z'),+ });++ const result = await runner.run(plan([step('docker')]));++ expect(result.steps[0]!.outcome).toBe('unknown');+ expect(result.steps[0]!.state).toBe('failed');+ expect(result.steps[0]!.error).toContain('ssh channel closed');+ });++ it('never reports an unverifiable step as satisfied', async () => {+ const { runner } = makeRunner({+ checks: { docker: [{ outcome: 'unknown', error: 'could not tell' }] },+ installs: {},+ });++ const result = await runner.run(plan([step('docker')]));++ expect(stateOf(result, 'docker')).not.toBe('satisfied');+ expect(result.status).toBe('halted');+ });++ it('does not try to install a dependency that is installed but not running', async () => {+ const { runner, installOrder } = makeRunner({+ checks: { docker: [{ outcome: 'not-running' }] },+ installs: {},+ });++ const result = await runner.run(plan([step('docker')]));++ expect(installOrder).toEqual([]);+ expect(result.steps[0]!.error).toContain('not running');+ });++ it('reports "no install command" rather than silently stalling', async () => {+ const { runner } = makeRunner({+ checks: { docker: [{ outcome: 'missing' }] },+ installs: {},+ canInstall: () => false,+ });++ const result = await runner.run(plan([step('docker')]));++ expect(result.steps[0]!.state).toBe('failed');+ expect(result.steps[0]!.error).toContain('no install command');+ });++ it('continues past a failed optional step', async () => {+ const { runner } = makeRunner({+ checks: { gh: [{ outcome: 'missing' }], node: [{ outcome: 'satisfied' }] },+ installs: { gh: { ok: false, error: 'nope' } },+ });++ const result = await runner.run(plan([step('gh', { optional: true }), step('node')]));++ expect(stateOf(result, 'gh')).toBe('failed');+ expect(stateOf(result, 'node')).toBe('satisfied');+ expect(result.status).toBe('complete'); // optional failure does not block the host+ });++ it('skipping unblocks the rest of the plan but is not satisfied', async () => {+ const { runner } = makeRunner({+ checks: { node: [{ outcome: 'missing' }], tmux: [{ outcome: 'satisfied' }] },+ installs: { node: { ok: false, error: 'nope' } },+ });++ const halted = await runner.run(plan([step('node'), step('tmux')]));+ expect(stateOf(halted, 'tmux')).toBe('blocked');++ const skipped = await runner.skip(halted, 'node');++ expect(stateOf(skipped, 'node')).toBe('skipped');+ expect(stateOf(skipped, 'tmux')).toBe('pending'); // unblocked+ expect(skipped.steps.find((s) => s.id === 'node')!.outcome).not.toBe('satisfied');+ });++ it('aborts as unreachable instead of blaming a dependency', async () => {+ const { runner, installOrder } = makeRunner({+ checks: { node: [{ outcome: 'missing' }] },+ installs: {},+ reachable: false,+ });++ await expect(runner.run(plan([step('node')]))).rejects.toBeInstanceOf(HostSetupAbortedError);+ expect(installOrder).toEqual([]);+ });++ it('persists and publishes every transition', async () => {+ const { runner, saved, published } = makeRunner({+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied' }] },+ installs: { node: { ok: true } },+ });++ await runner.run(plan([step('node')]));++ // running → checking → observed → installing → checking → satisfied → complete+ expect(saved.length).toBeGreaterThanOrEqual(6);+ expect(published.length).toBe(saved.length);+ expect(saved.at(-1)!.status).toBe('complete');+ });++ it('refuses a second concurrent run for the same host', async () => {+ const { runner } = makeRunner({+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied' }] },+ installs: { node: { ok: true } },+ });+ const p = plan([step('node')]);++ const first = runner.run(p);+ await expect(runner.run(p)).rejects.toThrow('already in progress');+ await first;+ });++ it('stops mid-run when the host drops', async () => {+ const harness: Harness = {+ checks: { git: [{ outcome: 'satisfied' }], node: [{ outcome: 'missing' }] },+ installs: {},+ };+ const reachable = { value: true };+ const runner = new HostSetupRunner({+ sshHost: 'dev-vm',+ load: async () => null,+ save: async () => {},+ publish: () => {},+ check: async (s) => harness.checks[s.id]![0]!,+ install: async () => ({ ok: true }),+ canInstall: () => true,+ requireReachable: () => {+ if (!reachable.value) throw new Unreachable('dropped');+ reachable.value = false; // drops after the first step+ },+ now: () => new Date('2026-02-02T00:00:00.000Z'),+ });++ await expect(runner.run(plan([step('git'), step('node')]))).rejects.toBeInstanceOf(+ HostSetupAbortedError+ );+ });++ it('clears a previous error when a step is retried', async () => {+ const { runner } = makeRunner({+ checks: { node: [{ outcome: 'missing' }, { outcome: 'satisfied' }] },+ installs: { node: { ok: true } },+ });+ const failed = plan([+ step('node', { state: 'failed', error: 'old failure', output: 'old output' }),+ ]);++ const result = await runner.run(failed);++ expect(stateOf(result, 'node')).toBe('satisfied');+ expect(result.steps[0]!.error).toBeNull();+ expect(result.steps[0]!.output).toBeNull();+ });+});++describe('plan helpers', () => {+ it('treats a skipped required step as outstanding, not done', async () => {+ const { isPlanComplete } = await import('@shared/core/remote-hosts/setup');+ expect(isPlanComplete(plan([step('node', { state: 'skipped' })]))).toBe(false);+ });++ it('ignores optional steps when deciding completeness', async () => {+ const { isPlanComplete } = await import('@shared/core/remote-hosts/setup');+ expect(+ isPlanComplete(+ plan([step('node', { state: 'satisfied' }), step('gh', { optional: true, state: 'failed' })])+ )+ ).toBe(true);+ });+});++describe('runner determinism', () => {+ it('does not mutate the plan it was given', async () => {+ const { runner } = makeRunner({ checks: { git: [{ outcome: 'satisfied' }] }, installs: {} });+ const original = plan([step('git')]);+ const snapshot = structuredClone(original);++ await runner.run(original);++ expect(original).toEqual(snapshot);+ });++ it('stamps updatedAt on every changed step', async () => {+ const { runner } = makeRunner({ checks: { git: [{ outcome: 'satisfied' }] }, installs: {} });+ vi.useFakeTimers();++ const result = await runner.run(plan([step('git')]));++ expect(result.steps[0]!.updatedAt).toBe('2026-02-02T00:00:00.000Z');+ vi.useRealTimers();+ });+});diff --git a/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.ts b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.tsnew file mode 100644index 000000000..a4eb95845--- /dev/null+++ b/dash/apps/switchdash-desktop/src/main/core/remote-hosts/setup/host-setup-runner.ts@@ -0,0 +1,288 @@+/**+ * Sequential, resumable setup runner for a remote host (CHOO-1809).+ *+ * Runs a host's setup plan one step at a time, persisting after every+ * transition so a run survives the app closing mid-install. Three rules drive+ * the design:+ *+ * 1. **One step in flight.** Dependencies install one after another, in order,+ * never concurrently — the old page fired every probe and install+ * independently and left the user to guess the sequence.+ * 2. **Halt on failure, hold position.** A failed required step stops the run.+ * Steps already satisfied stay satisfied, the failure keeps its error and+ * command output, and untried steps become `blocked` rather than being+ * discarded. Resuming re-attempts the failure; it does not start over.+ * 3. **Reachability is not a dependency verdict.** The reachability gate is+ * consulted before any probing, and an unreachable host aborts the run as+ * *unreachable* instead of reporting every prerequisite as missing.+ *+ * Verification is explicit: after an install we re-check rather than assuming+ * the installer worked. A step is only `satisfied` on the strength of a fresh+ * observation.+ */++import {+ isInstallableOutcome,+ isPlanComplete,+ type DependencyCheckOutcome,+ type HostSetupPlan,+ type HostSetupStep,+ type HostSetupStepState,+} from '@shared/core/remote-hosts/setup';++/** What a probe observed for one step. */+export type StepCheckResult = {+ outcome: DependencyCheckOutcome;+ version?: string | null;+ /** Set when the outcome is `unknown` — why we could not tell. */+ error?: string;+};++/** Outcome of installing one step. */+export type StepInstallResult =+ | { ok: true }+ | { ok: false; error: string; output?: string | null };++export type HostSetupRunnerDeps = {+ sshHost: string;+ /** Load the persisted plan. Null when the host has never been set up. */+ load: (sshHost: string) => Promise<HostSetupPlan | null>;+ save: (plan: HostSetupPlan) => Promise<void>;+ /** Push the plan to the renderer on every transition. */+ publish: (plan: HostSetupPlan) => void;+ check: (step: HostSetupStep) => Promise<StepCheckResult>;+ install: (step: HostSetupStep) => Promise<StepInstallResult>;+ /** Whether this step can be installed by switchdash at all on this host. */+ canInstall: (step: HostSetupStep) => boolean;+ /**+ * Throws when the host is not reachable. Wired to the central reachability+ * service (CHOO-1682/1780) — this runner never forms its own verdict.+ */+ requireReachable: (sshHost: string) => void;+ now?: () => Date;+};++/** Raised when a run is abandoned because the host itself is not reachable. */+export class HostSetupAbortedError extends Error {+ constructor(+ message: string,+ readonly cause: unknown+ ) {+ super(message);+ this.name = 'HostSetupAbortedError';+ }+}++export class HostSetupRunner {+ private running = false;++ constructor(private readonly deps: HostSetupRunnerDeps) {}++ private now(): string {+ return (this.deps.now?.() ?? new Date()).toISOString();+ }++ /**+ * Run (or resume) the plan. Returns as soon as the plan completes or halts.+ * Concurrent calls are rejected rather than interleaved — two runs against+ * one host would break the one-at-a-time guarantee.+ */+ async run(plan: HostSetupPlan): Promise<HostSetupPlan> {+ if (this.running) {+ throw new Error(`A setup run is already in progress for ${this.deps.sshHost}`);+ }+ this.running = true;+ try {+ return await this.drive(plan);+ } finally {+ this.running = false;+ }+ }++ private async drive(initial: HostSetupPlan): Promise<HostSetupPlan> {+ let plan = await this.transition(initial, { status: 'running' });++ for (const step of plan.steps) {+ if (step.state === 'satisfied' || step.state === 'skipped') continue;++ // Gate on reachability before every step, not just at the start: a host+ // can drop mid-run, and continuing would attribute the loss of the+ // transport to whichever dependency happened to be next in line.+ try {+ this.deps.requireReachable(this.deps.sshHost);+ } catch (error) {+ plan = await this.transition(plan, { status: 'halted' });+ throw new HostSetupAbortedError(+ `Setup for ${this.deps.sshHost} stopped: the host became unreachable.`,+ error+ );+ }++ plan = await this.runStep(plan, step.id);+ const current = findStep(plan, step.id);++ if (current.state === 'failed' && !current.optional) {+ return await this.haltAfter(plan, step.id);+ }+ }++ return await this.transition(plan, {+ status: isPlanComplete(plan) ? 'complete' : 'halted',+ currentStepId: null,+ });+ }++ /**+ * Check one step, install it if that is both needed and possible, then+ * re-check to verify. Never marks a step satisfied on the strength of an+ * installer's exit code alone.+ */+ async runStep(plan: HostSetupPlan, stepId: string): Promise<HostSetupPlan> {+ let next = await this.patchStep(plan, stepId, {+ state: 'checking',+ error: null,+ output: null,+ });+ next = await this.transition(next, { currentStepId: stepId });++ const checked = await this.observe(next, stepId);+ const step = findStep(checked, stepId);++ if (step.outcome === 'satisfied') return checked;++ // Nothing we can do automatically — surface the real outcome rather than+ // pretending an install would help. `not-running` and `unknown` land here.+ if (!isInstallableOutcome(step.outcome) || !this.deps.canInstall(step)) {+ return await this.patchStep(checked, stepId, {+ state: 'failed',+ error: describeUnactionable(step),+ });+ }++ const installing = await this.patchStep(checked, stepId, { state: 'installing' });+ const result = await this.deps.install(findStep(installing, stepId));++ if (!result.ok) {+ return await this.patchStep(installing, stepId, {+ state: 'failed',+ error: result.error,+ output: result.output ?? null,+ });+ }++ // Verify. An installer reporting success is a claim, not an observation.+ const verifying = await this.patchStep(installing, stepId, { state: 'checking' });+ const verified = await this.observe(verifying, stepId);+ const after = findStep(verified, stepId);++ if (after.outcome === 'satisfied') return verified;++ return await this.patchStep(verified, stepId, {+ state: 'failed',+ error:+ after.outcome === 'unknown'+ ? `${after.name} was installed but could not be verified afterwards.`+ : `${after.name} still reports "${after.outcome}" after installing.`,+ });+ }++ /** Probe one step and record what was actually observed. */+ private async observe(plan: HostSetupPlan, stepId: string): Promise<HostSetupPlan> {+ let result: StepCheckResult;+ try {+ result = await this.deps.check(findStep(plan, stepId));+ } catch (error) {+ // A probe that throws tells us nothing about the dependency — record+ // `unknown`, never `missing`.+ result = {+ outcome: 'unknown',+ error: error instanceof Error ? error.message : String(error),+ };+ }++ return await this.patchStep(plan, stepId, {+ outcome: result.outcome,+ version: result.version ?? null,+ state: result.outcome === 'satisfied' ? 'satisfied' : 'checking',+ error: result.error ?? null,+ });+ }++ /** Mark the plan halted and block everything downstream of the failure. */+ private async haltAfter(plan: HostSetupPlan, failedStepId: string): Promise<HostSetupPlan> {+ const failedIndex = plan.steps.findIndex((s) => s.id === failedStepId);+ const steps = plan.steps.map((step, index) =>+ index > failedIndex && (step.state === 'pending' || step.state === 'blocked')+ ? { ...step, state: 'blocked' as HostSetupStepState, updatedAt: this.now() }+ : step+ );+ return await this.commit({+ ...plan,+ steps,+ status: 'halted',+ currentStepId: failedStepId,+ });+ }++ /**+ * Move past a step the user has chosen not to fix. Unblocks the rest of the+ * plan so the run can continue, but is never reported as satisfied.+ */+ async skip(plan: HostSetupPlan, stepId: string): Promise<HostSetupPlan> {+ const skipped = await this.patchStep(plan, stepId, {+ state: 'skipped',+ error: null,+ output: null,+ });+ const steps = skipped.steps.map((step) =>+ step.state === 'blocked' ? { ...step, state: 'pending' as HostSetupStepState } : step+ );+ return await this.commit({ ...skipped, steps, status: 'idle' });+ }++ private async patchStep(+ plan: HostSetupPlan,+ stepId: string,+ patch: Partial<Omit<HostSetupStep, 'id'>>+ ): Promise<HostSetupPlan> {+ const steps = plan.steps.map((step) =>+ step.id === stepId ? { ...step, ...patch, updatedAt: this.now() } : step+ );+ return await this.commit({ ...plan, steps });+ }++ private async transition(+ plan: HostSetupPlan,+ patch: Partial<Pick<HostSetupPlan, 'status' | 'currentStepId'>>+ ): Promise<HostSetupPlan> {+ return await this.commit({ ...plan, ...patch });+ }++ /** Persist then publish. Every visible state change goes through here. */+ private async commit(plan: HostSetupPlan): Promise<HostSetupPlan> {+ const next = { ...plan, updatedAt: this.now() };+ await this.deps.save(next);+ this.deps.publish(next);+ return next;+ }+}++function findStep(plan: HostSetupPlan, stepId: string): HostSetupStep {+ const step = plan.steps.find((s) => s.id === stepId);+ if (!step) throw new Error(`Setup step ${stepId} is not part of the plan for ${plan.sshHost}`);+ return step;+}++/** Why a step cannot be advanced automatically — stated in terms of what we saw. */+function describeUnactionable(step: HostSetupStep): string {+ switch (step.outcome) {+ case 'not-running':+ return `${step.name} is installed but not running. Start it on the host, then retry.`;+ case 'unknown':+ return step.error ?? `Could not determine whether ${step.name} is available.`;+ case 'wrong-version':+ return `${step.name} is installed but too old, and switchdash has no upgrade command for this host.`;+ default:+ return `${step.name} is not installed, and switchdash has no install command for this host.`;+ }+}diff --git a/dash/apps/switchdash-desktop/src/shared/core/remote-hosts/setup.ts b/dash/apps/switchdash-desktop/src/shared/core/remote-hosts/setup.tsnew file mode 100644index 000000000..9edb8d1d4--- /dev/null+++ b/dash/apps/switchdash-desktop/src/shared/core/remote-hosts/setup.ts@@ -0,0 +1,151 @@+/**+ * Model of a remote host's setup run (CHOO-1809).+ *+ * Onboarding a host used to be a single boolean — a row existed, or it didn't —+ * with every prerequisite probed independently by whichever component happened+ * to render. There was no notion of *where a host got to*, so nothing could be+ * resumed, nothing could be ordered, and a failure halfway through left no+ * record beyond whatever the UI happened to be holding in memory.+ *+ * A setup plan is that missing object: an ordered list of steps, persisted per+ * host, advanced one at a time. It is the single answer to "what still needs to+ * happen on this host, and what went wrong last time we tried?".+ */++import { defineEvent } from '@shared/lib/ipc/events';++/**+ * What a check actually observed. Deliberately richer than a boolean, because+ * the interesting failures are not "missing" (CHOO-1803):+ *+ * - `satisfied` — present, correct version, and usable.+ * - `missing` — not installed.+ * - `not-running` — installed but the daemon/service is not up (Docker being+ * the motivating case: `docker` on PATH tells you nothing about dockerd).+ * - `wrong-version` — installed but below the minimum we require.+ * - `unknown` — **we could not determine this.** A first-class answer, never+ * collapsed into satisfied. Reporting "fine" for something we failed to+ * observe is the stale-green bug from CHOO-1780.+ */+export type DependencyCheckOutcome =+ | 'satisfied'+ | 'missing'+ | 'not-running'+ | 'wrong-version'+ | 'unknown';++/** Outcomes that mean the step's requirement is genuinely met. */+export function isSatisfiedOutcome(outcome: DependencyCheckOutcome | null): boolean {+ return outcome === 'satisfied';+}++/**+ * Whether an outcome is something installing could plausibly fix. `not-running`+ * is excluded on purpose — starting a daemon is not installing a package, and+ * silently running an installer over a stopped service would misreport the+ * cause.+ */+export function isInstallableOutcome(outcome: DependencyCheckOutcome | null): boolean {+ return outcome === 'missing' || outcome === 'wrong-version';+}++/**+ * Where a step sits in its own lifecycle. Each step owns its state — the whole+ * point of the rewrite is that step 3 failing says nothing about steps 1-2.+ *+ * - `pending` — not reached yet.+ * - `checking` — a probe is in flight.+ * - `installing` — an install is in flight.+ * - `satisfied` — verified present after the last observation.+ * - `failed` — the check or install failed; carries `error` (and `output` when+ * a command produced any). The run halts here.+ * - `skipped` — the user chose to move past it. Never rendered as satisfied.+ * - `blocked` — an earlier required step failed, so this one was never+ * attempted. Distinct from `pending`: pending means "not yet", blocked means+ * "not unless something upstream is fixed".+ */+export type HostSetupStepState =+ | 'pending'+ | 'checking'+ | 'installing'+ | 'satisfied'+ | 'failed'+ | 'skipped'+ | 'blocked';++/** What kind of thing a step manages, for rendering and for install routing. */+export type HostSetupStepKind = 'core-dependency' | 'agent-cli' | 'agent-plugin' | 'gh-auth';++export type HostSetupStep = {+ /** Stable within a plan. Dependency id for deps; `<agentId>:plugin` for plugins. */+ id: string;+ kind: HostSetupStepKind;+ /** Display name, resolved when the plan is built. */+ name: string;+ state: HostSetupStepState;+ /** The last thing we actually observed. Null until first checked. */+ outcome: DependencyCheckOutcome | null;+ /** Detected version, when the probe found one. */+ version: string | null;+ /** Why this step failed. Null unless `state === 'failed'`. */+ error: string | null;+ /** Raw command output from a failed install — the detail users need. */+ output: string | null;+ /**+ * An optional step does not block the run or the host's usability. `gh` is+ * the motivating case: it needs an interactive device-flow login that a user+ * may reasonably defer without the host being unusable.+ */+ optional: boolean;+ /** Steps that must be satisfied before this one is attempted. */+ dependsOn: string[];+ /** ISO timestamp of the last state change. */+ updatedAt: string;+};++/**+ * Plan-level status.+ *+ * - `idle` — built (or resumed) and waiting for the user to start.+ * - `running` — a step is in flight.+ * - `halted` — a required step failed. **Position is held**: satisfied steps+ * stay satisfied, the failure keeps its error, and untried steps are blocked.+ * Resuming re-attempts from the failure rather than starting over.+ * - `complete` — every required step is satisfied or skipped.+ */+export type HostSetupPlanStatus = 'idle' | 'running' | 'halted' | 'complete';++export type HostSetupPlan = {+ sshHost: string;+ status: HostSetupPlanStatus;+ steps: HostSetupStep[];+ /** The step currently in flight, or the one that halted the run. */+ currentStepId: string | null;+ createdAt: string;+ updatedAt: string;+};++/** The first step that still needs work, in plan order. Null when nothing is left. */+export function nextActionableStep(plan: HostSetupPlan): HostSetupStep | null {+ return (+ plan.steps.find(+ (step) => step.state === 'pending' || step.state === 'blocked' || step.state === 'failed'+ ) ?? null+ );+}++/** Required steps that are not yet satisfied — what stands between here and done. */+export function outstandingRequiredSteps(plan: HostSetupPlan): HostSetupStep[] {+ return plan.steps.filter((step) => !step.optional && step.state !== 'satisfied');+}++/**+ * Whether the host is usable for running agents. Optional steps and skipped+ * steps do not count against it; a step we could not verify does.+ */+export function isPlanComplete(plan: HostSetupPlan): boolean {+ return outstandingRequiredSteps(plan).length === 0;+}++/** Pushed to the renderer on every plan transition, so the UI never polls. */+export const hostSetupPlanEventChannel = defineEvent<HostSetupPlan>('remote-hosts:setup-changed');