sailfork / t3code-github / apps/ web/ src/ onboarding/ firstRun.logic.test.ts

import { describe, expect, it } from "vite-plus/test";

import {
  isFirstRunWorkspaceProvenanceAuthoritative,
  isFreshFirstRunWorkspace,
  resolveFirstRunDecision,
  transitionFirstRunGateState,
} from "./firstRun.logic";

const freshWorkspace = {
  enabled: true,
  hydrated: true,
  completed: false,
  bootstrapped: true,
  authoritative: true,
  workspaceAuthoritative: true,
  workspaceProvenanceAuthoritative: true,
  catalogReady: true,
  serverConfigAvailable: true,
  workspaceFresh: true,
  projectCount: 1,
  threadCount: 1,
} as const;

describe("resolveFirstRunDecision", () => {
  it("opens the wizard for an authoritative fresh workspace", () => {
    expect(resolveFirstRunDecision(freshWorkspace)).toEqual({
      decision: "wizard",
      persistCompletion: false,
    });
  });

  it("does not permanently complete onboarding from cached project counts", () => {
    expect(
      resolveFirstRunDecision({
        ...freshWorkspace,
        authoritative: false,
        projectCount: 3,
        workspaceFresh: false,
      }),
    ).toEqual({
      decision: "app",
      persistCompletion: false,
    });
  });

  it("backfills completion once existing projects are confirmed by the server", () => {
    expect(
      resolveFirstRunDecision({
        ...freshWorkspace,
        projectCount: 3,
        workspaceFresh: false,
      }),
    ).toEqual({
      decision: "app",
      persistCompletion: true,
    });
  });

  it("waits when the initial welcome is pending and opens the wizard after completion", () => {
    const pendingProvenance = isFirstRunWorkspaceProvenanceAuthoritative({
      welcomeReceived: true,
      bootstrapStatus: "pending",
    });
    expect(
      resolveFirstRunDecision({
        ...freshWorkspace,
        workspaceProvenanceAuthoritative: pendingProvenance,
      }),
    ).toEqual({ decision: "pending", persistCompletion: false });

    const completedProvenance = isFirstRunWorkspaceProvenanceAuthoritative({
      welcomeReceived: true,
      bootstrapStatus: "complete",
    });
    expect(
      resolveFirstRunDecision({
        ...freshWorkspace,
        workspaceProvenanceAuthoritative: completedProvenance,
      }),
    ).toEqual({ decision: "wizard", persistCompletion: false });
  });

  it("does not wait for server data after onboarding is already complete", () => {
    expect(
      resolveFirstRunDecision({
        ...freshWorkspace,
        authoritative: false,
        bootstrapped: false,
        completed: true,
        serverConfigAvailable: false,
      }),
    ).toEqual({
      decision: "app",
      persistCompletion: false,
    });
  });
});

describe("isFirstRunWorkspaceProvenanceAuthoritative", () => {
  it("accepts a legacy welcome without bootstrap status", () => {
    expect(
      isFirstRunWorkspaceProvenanceAuthoritative({
        welcomeReceived: true,
        bootstrapStatus: null,
      }),
    ).toBe(true);
  });
});

describe("transitionFirstRunGateState", () => {
  it("shows recovery without mounting the app when evidence stalls", () => {
    expect(
      transitionFirstRunGateState({ decision: "pending", stalled: false }, { type: "timeout" }),
    ).toEqual({ decision: "pending", stalled: true });
  });

  it.each([
    { previous: "app", workspaceFresh: true, decision: "wizard" },
    { previous: "wizard", workspaceFresh: false, decision: "app" },
  ] as const)(
    "updates $previous to $decision when authoritative workspace evidence changes",
    ({ previous, workspaceFresh, decision }) => {
      const evidence = resolveFirstRunDecision({ ...freshWorkspace, workspaceFresh });
      expect(
        transitionFirstRunGateState(
          { decision: previous, stalled: false },
          { type: "evidence", decision: evidence.decision },
        ),
      ).toEqual({ decision, stalled: false });
    },
  );

  // regression: #19680 unchanged gate evidence must not produce a new state
  it.each(["pending", "app", "wizard"] as const)(
    "preserves state identity for unchanged %s evidence",
    (decision) => {
      const state = { decision, stalled: false };
      expect(transitionFirstRunGateState(state, { type: "evidence", decision })).toBe(state);
    },
  );
});

const primaryEnvironmentId = "primary-environment";
const bootstrapProject = {
  id: "bootstrap-project",
  environmentId: primaryEnvironmentId,
  workspaceRoot: "/projects/current",
};
const bootstrapThread = {
  id: "bootstrap-thread",
  projectId: bootstrapProject.id,
  environmentId: primaryEnvironmentId,
  latestRun: null,
  latestUserMessageAt: null,
  runtime: null,
};

const freshBootstrap = {
  primaryEnvironmentId,
  serverCwd: "/projects/current",
  bootstrapProjectId: bootstrapProject.id,
  bootstrapThreadId: bootstrapThread.id,
  bootstrapProjectCreated: true,
  bootstrapThreadCreated: true,
  projects: [bootstrapProject],
  threads: [bootstrapThread],
};

describe("isFreshFirstRunWorkspace", () => {
  it("accepts only the unused project and thread created from the server cwd", () => {
    expect(
      isFreshFirstRunWorkspace({
        primaryEnvironmentId,
        serverCwd: "/projects/current/",
        bootstrapProjectId: bootstrapProject.id,
        bootstrapThreadId: bootstrapThread.id,
        bootstrapProjectCreated: true,
        bootstrapThreadCreated: true,
        projects: [bootstrapProject],
        threads: [bootstrapThread],
      }),
    ).toBe(true);
  });

  it("rejects an existing unused cwd project and thread reused by startup", () => {
    expect(
      isFreshFirstRunWorkspace({
        primaryEnvironmentId,
        serverCwd: "/projects/current",
        bootstrapProjectId: bootstrapProject.id,
        bootstrapThreadId: bootstrapThread.id,
        bootstrapProjectCreated: false,
        bootstrapThreadCreated: false,
        projects: [bootstrapProject],
        threads: [bootstrapThread],
      }),
    ).toBe(false);
  });

  it("rejects a nonempty workspace when an older server omits creation provenance", () => {
    expect(
      isFreshFirstRunWorkspace({
        primaryEnvironmentId,
        serverCwd: "/projects/current",
        bootstrapProjectId: bootstrapProject.id,
        bootstrapThreadId: bootstrapThread.id,
        projects: [bootstrapProject],
        threads: [bootstrapThread],
      }),
    ).toBe(false);
  });

  it("normalizes Windows project paths before checking the bootstrap workspace", () => {
    expect(
      isFreshFirstRunWorkspace({
        primaryEnvironmentId,
        serverCwd: "C:\\Projects\\Current\\",
        bootstrapProjectId: bootstrapProject.id,
        bootstrapThreadId: bootstrapThread.id,
        bootstrapProjectCreated: true,
        bootstrapThreadCreated: true,
        projects: [{ ...bootstrapProject, workspaceRoot: "c:/projects/current" }],
        threads: [bootstrapThread],
      }),
    ).toBe(true);
  });

  it("rejects a bootstrap thread that already has a user message", () => {
    expect(
      isFreshFirstRunWorkspace({
        ...freshBootstrap,
        projects: [bootstrapProject],
        threads: [
          {
            ...bootstrapThread,
            latestUserMessageAt: "2026-08-23T12:00:00.000Z",
          },
        ],
      }),
    ).toBe(false);
  });
});