@junejuly-lockstep/reconciler 0.1.0

package/templates/lockstep-reconcile.yml

@@ -0,0 +1,219 @@
+# Lockstep client contract, item 6. Commit this file as .github/workflows/lockstep-reconcile.yml
+# and add the project API key to the repo secrets as LOCKSTEP_API_KEY.
+#
+# Runs:
+#   push (default branch) -> model sync: `lockstep sync-models` loads the journey files and
+#                         scenarios and posts the parsed models to the platform. The platform
+#                         never executes client code, so this job is how the canvas learns about
+#                         a model change (its webhook only sees that a newer commit exists).
+#   pull_request       -> report-only run (kind pr, env preview). Verdicts never fail the check.
+#   deployment_status  -> deploy run on a successful deployment. Exit 3 (verdicts need judgment)
+#                         fails the workflow so a red deploy is visible in GitHub and on the board.
+#   workflow_dispatch  -> manual run of the checked-out commit (Actions -> Lockstep reconcile ->
+#                         Run workflow): the deploy-run path for repos whose hosting never emits
+#                         deployment_status, and a way to re-run a deploy run by hand. Inputs: kind
+#                         (deploy|pr), env (staging|prod|preview), deploy_label (default d<run
+#                         number>), pr (only for kind pr). Uses --fail-on-verdicts auto: a deploy
+#                         run fails on verdicts, a pr run is report-only.
+#   repository_dispatch (lockstep-build) -> placeholder for the client's coding agent.
+name: Lockstep reconcile
+
+on:
+  push:
+  pull_request:
+  deployment_status:
+  workflow_dispatch:
+    inputs:
+      kind:
+        description: Run kind
+        type: choice
+        options: [deploy, pr]
+        default: deploy
+      env:
+        description: Environment the run is recorded against
+        type: choice
+        options: [staging, prod, preview]
+        default: staging
+      deploy_label:
+        description: Deploy label, e.g. d14 (empty = d<run number>)
+        type: string
+        default: ''
+      pr:
+        description: Pull request number (only for kind pr)
+        type: string
+        default: ''
+  repository_dispatch:
+    types: [lockstep-build]
+
+concurrency:
+  group: lockstep-${{ github.workflow }}-${{ github.event.pull_request.number || github.event.deployment.sha || github.run_id }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  # Fast path, no browser and no build: a push to the default branch mirrors the journey models
+  # to the platform within a minute so the canvas updates on its next 10 s poll.
+  sync-models:
+    if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      LOCKSTEP_API_KEY: ${{ secrets.LOCKSTEP_API_KEY }}
+      # The reconciler never needs browsers for a model sync.
+      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Sync journey models to Lockstep
+        run: >-
+          npx lockstep sync-models
+          --ref "$GITHUB_SHA"
+          --branch "$GITHUB_REF_NAME"
+          --pushed-at "${{ github.event.head_commit.timestamp }}"
+
+  reconcile:
+    if: >-
+      github.event_name == 'pull_request' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      LOCKSTEP_API_KEY: ${{ secrets.LOCKSTEP_API_KEY }}
+      # deployment_status: the deployed commit; pull_request: the head commit; workflow_dispatch: the
+      # commit of the branch or tag the run was started from (GITHUB_SHA).
+      SHA: ${{ github.event_name == 'deployment_status' && github.event.deployment.sha || github.event.pull_request.head.sha || github.sha }}
+      TZ: UTC
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.SHA }}
+          # The contract diff compares the SDL against the previous commit.
+          fetch-depth: 2
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Install Chromium for Playwright
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Build the app
+        run: pnpm build
+
+      - name: Validate the Lockstep contract
+        run: npx lockstep validate
+
+      - name: Reconcile (pull request, report-only)
+        if: github.event_name == 'pull_request'
+        run: >-
+          npx lockstep reconcile
+          --ref "$SHA"
+          --kind pr
+          --pr ${{ github.event.pull_request.number }}
+          --env preview
+          --fail-on-verdicts never
+
+      - name: Reconcile (deploy, fails on verdicts)
+        if: github.event_name == 'deployment_status'
+        run: >-
+          npx lockstep reconcile
+          --ref "$SHA"
+          --kind deploy
+          --env ${{ github.event.deployment.environment == 'production' && 'prod' || 'staging' }}
+          --deploy-label "d${{ github.run_number }}"
+          --fail-on-verdicts always
+
+      # Manual deploy-run path (no deployment_status needed). `auto` = fail on verdicts for kind
+      # deploy, report-only for kind pr; --pr and --deploy-label are only passed when they apply.
+      - name: Reconcile (manual run)
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          KIND: ${{ inputs.kind }}
+          ENV_NAME: ${{ inputs.env }}
+          DEPLOY_LABEL: ${{ inputs.deploy_label != '' && inputs.deploy_label || format('d{0}', github.run_number) }}
+          PR: ${{ inputs.pr }}
+        run: |
+          set -- --ref "$GITHUB_SHA" --kind "$KIND" --env "$ENV_NAME" --fail-on-verdicts auto
+          if [ "$KIND" = "deploy" ]; then set -- "$@" --deploy-label "$DEPLOY_LABEL"; fi
+          if [ -n "$PR" ]; then set -- "$@" --pr "$PR"; fi
+          echo "npx lockstep reconcile $*"
+          npx lockstep reconcile "$@"
+
+      - name: Upload local reconcile output
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lockstep-${{ github.run_id }}
+          path: .lockstep
+          retention-days: 14
+          if-no-files-found: ignore
+
+  # ------------------------------------------------------------------------------------------
+  # Agent build placeholder. The platform dispatches `lockstep-build` from POST /api/cards/:id/dispatch
+  # with client_payload { cardId, cardRef, branch, workOrder }. The agent runner itself is out of
+  # Lockstep's scope: wire your coding agent in the step marked below.
+  #
+  # The only contract back to the platform: the PR this job opens must contain the card ref
+  # (for example "FERN-12") in its body. The Lockstep GitHub App webhook links the PR to the card
+  # on open; merge plus a clean reconcile walks the card to In lockstep.
+  # ------------------------------------------------------------------------------------------
+  agent-build:
+    if: github.event_name == 'repository_dispatch' && github.event.action == 'lockstep-build'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      CARD_ID: ${{ github.event.client_payload.cardId }}
+      CARD_REF: ${{ github.event.client_payload.cardRef }}
+      BRANCH: ${{ github.event.client_payload.branch }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Show the work order
+        run: |
+          echo "Card: $CARD_REF ($CARD_ID)"
+          echo "Branch: $BRANCH"
+          echo '${{ toJson(github.event.client_payload.workOrder) }}' > work-order.json
+          cat work-order.json
+
+      # ----------------------------------------------------------------------------------------
+      # WIRE YOUR CODING AGENT HERE.
+      # Input: work-order.json (brief, machine delta, scenario fixtures, acceptance paths, bindings).
+      # Output: commits on $BRANCH that implement the journey and keep the contract green.
+      # Example: run your agent CLI against work-order.json, then `git push origin HEAD:$BRANCH`.
+      # ----------------------------------------------------------------------------------------
+      - name: Run coding agent (placeholder)
+        run: |
+          echo "No agent configured. Replace this step with your agent runner."
+          exit 0
+
+      # The PR body MUST include the card ref so the platform can link it. Keep the first line.
+      - name: Open the pull request
+        if: false # set to true once the agent step above produces commits on $BRANCH
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh pr create \
+            --head "$BRANCH" \
+            --title "$CARD_REF: $(jq -r '.brief | split("\n")[0]' work-order.json)" \
+            --body "$(printf 'Lockstep card %s\n\n%s\n\nGenerated from work order %s.' "$CARD_REF" "$(jq -r .brief work-order.json)" "$CARD_ID")"

package/templates/lockstep.config.example.ts

@@ -0,0 +1,46 @@
+import { defineConfig } from '@junejuly-lockstep/reconciler';
+
+/**
+ * Lockstep client contract, item 1. Lives at the repo root as `lockstep.config.ts`.
+ * Every relative path resolves from this file's directory.
+ */
+export default defineConfig({
+  /** Project key on the platform; cards render as FERN-12. Uppercase, 2-8 chars. */
+  projectKey: 'FERN',
+
+  /** Platform API origin the reconciler posts runs to. */
+  apiBaseUrl: 'https://api.lockstep.example.com',
+
+  /** One file per journey, each exporting `machine` (XState v5 createMachine) and `meta`. */
+  journeysGlob: 'src/journeys/*.journey.ts',
+
+  /** Named personas: seed plus mock overrides. */
+  scenariosPath: 'src/journeys/scenarios.ts',
+
+  /** Ordered seam strip, 6 to 8 names. Backend changes tag the seams they touch. */
+  seams: ['Client app', 'API layer', 'Scheduling', 'Patient records', 'Notifications', 'Identity'],
+
+  /** Fraction of differing pixels above which a screenshot is `changed`. */
+  visualDiffThreshold: 0.001,
+
+  /**
+   * How the reconciler boots the app under test. The command receives PORT, LOCKSTEP_SCENARIO
+   * and LOCKSTEP_SEED in its environment; the walker also appends `?lockstep_scenario=` to the
+   * first navigation so the MSW layer can seed itself in the browser.
+   */
+  bootCommand: 'pnpm exec next start --port 3100',
+  port: 3100,
+
+  /**
+   * Security rule: walks only ever hit mocks. `appApiBase` is the origin the app talks to and
+   * must match `mockApiPattern`, otherwise the reconciler refuses to run.
+   */
+  appApiBase: 'msw://patient-api',
+  mockApiPattern: '^(mock|msw):|localhost|127\\.0\\.0\\.1',
+
+  /** GraphQL contract: the SDL and the graphql-codegen TypeScript output. */
+  schema: {
+    sdlPath: 'schema.graphql',
+    codegenOutput: 'src/gql/graphql.ts',
+  },
+});

package/templates/msw-handlers.example.ts

@@ -0,0 +1,113 @@
+import { graphql, HttpResponse } from 'msw';
+import { scenarios } from '../journeys/scenarios';
+
+/**
+ * Lockstep client contract, item 4: MSW handlers that are deterministic under a fixed seed.
+ *
+ * Rules that keep screenshots byte-identical run to run:
+ *  - No faker, no Math.random, no Date.now(). Every value derives from the seed below or from
+ *    the frozen epoch the walker installs (FROZEN_EPOCH_MS in @junejuly-lockstep/reconciler).
+ *  - The scenario comes from `?lockstep_scenario=` in the browser or LOCKSTEP_SCENARIO on the
+ *    server; both are set by the reconciler. Default to the first scenario in dev.
+ *  - Shapes follow the generated types from graphql-codegen so a schema change shows up here
+ *    as a type error before it shows up as a contract verdict.
+ */
+
+/** mulberry32: tiny, fast, fully deterministic PRNG. */
+export function seeded(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const CLINICIANS = ['Dr. Amara Okafor', 'Dr. Ben Liu', 'Dr. Carla Mendes', 'Dr. Dev Patel'];
+const LOCATIONS = ['Downtown clinic', 'Riverside clinic', 'Telehealth'];
+
+/** The walker freezes the page clock here; derive every date from it, never from Date.now(). */
+export const FROZEN_EPOCH_MS = Date.UTC(2026, 0, 15, 9, 30, 0);
+
+export function currentScenario(): (typeof scenarios)[number] {
+  let name: string | undefined;
+  if (typeof window !== 'undefined') {
+    name = new URLSearchParams(window.location.search).get('lockstep_scenario') ?? undefined;
+    if (name) window.sessionStorage.setItem('lockstep_scenario', name);
+    name ??= window.sessionStorage.getItem('lockstep_scenario') ?? undefined;
+  } else if (typeof process !== 'undefined') {
+    name = process.env['LOCKSTEP_SCENARIO'];
+  }
+  return scenarios.find((s) => s.name === name) ?? scenarios[0]!;
+}
+
+function pick<T>(rand: () => number, list: readonly T[]): T {
+  return list[Math.floor(rand() * list.length)]!;
+}
+
+function slotsFor(scenario: (typeof scenarios)[number]) {
+  const rand = seeded(scenario.seed);
+  const count =
+    typeof scenario.overrides['availableSlots'] === 'number'
+      ? (scenario.overrides['availableSlots'] as number)
+      : 6;
+  const slots = [];
+  for (let i = 0; i < count; i++) {
+    const dayOffset = 1 + Math.floor(rand() * 7);
+    const hour = 9 + Math.floor(rand() * 8);
+    slots.push({
+      id: `slot-${scenario.seed}-${i}`,
+      startsAt: new Date(FROZEN_EPOCH_MS + dayOffset * 86_400_000 + hour * 3_600_000).toISOString(),
+      clinician: pick(rand, CLINICIANS),
+      location: pick(rand, LOCATIONS),
+      available: true,
+    });
+  }
+  return slots.sort((a, b) => a.startsAt.localeCompare(b.startsAt));
+}
+
+export const handlers = [
+  graphql.query('Viewer', () => {
+    const scenario = currentScenario();
+    const rand = seeded(scenario.seed);
+    return HttpResponse.json({
+      data: {
+        viewer: {
+          id: `patient-${scenario.seed}`,
+          firstName: scenario.name.split('-')[0]!.replace(/^./, (c) => c.toUpperCase()),
+          eligible: true,
+          upcomingVisits: Array.from(
+            { length: Number(scenario.overrides['upcomingVisits'] ?? 0) },
+            (_, i) => ({
+              id: `visit-${scenario.seed}-${i}`,
+              startsAt: new Date(FROZEN_EPOCH_MS + (i + 2) * 86_400_000).toISOString(),
+              clinician: pick(rand, CLINICIANS),
+            }),
+          ),
+        },
+      },
+    });
+  }),
+
+  graphql.query('Slots', () => {
+    return HttpResponse.json({ data: { slots: slotsFor(currentScenario()) } });
+  }),
+
+  graphql.mutation('BookVisit', ({ variables }) => {
+    const scenario = currentScenario();
+    const slot =
+      slotsFor(scenario).find((s) => s.id === (variables as { slotId?: string }).slotId) ??
+      slotsFor(scenario)[0];
+    return HttpResponse.json({
+      data: {
+        bookVisit: {
+          id: `booking-${scenario.seed}`,
+          reference: `FERN-${String(scenario.seed).padStart(4, '0')}`,
+          slot,
+        },
+      },
+    });
+  }),
+];

package/templates/scenarios.example.ts

@@ -0,0 +1,32 @@
+import type { Scenario } from '@junejuly-lockstep/reconciler';
+
+/**
+ * Lockstep client contract, item 3: named personas. Each scenario is a seed plus overrides for
+ * the schema-generated mock handlers. The reconciler boots the app once per scenario with
+ * LOCKSTEP_SCENARIO=<name> and LOCKSTEP_SEED=<seed>, and opens the first route with
+ * `?lockstep_scenario=<name>&lockstep_seed=<seed>`.
+ *
+ * Keep seeds stable: changing a seed changes every screenshot and forces a baseline review.
+ */
+export const scenarios: Scenario[] = [
+  {
+    name: 'nora',
+    description: 'Nora, eligible, no visit history',
+    seed: 1,
+    overrides: {},
+  },
+  {
+    name: 'omar',
+    description: 'Omar, returning, one upcoming visit, two slots left this week',
+    seed: 2,
+    overrides: { upcomingVisits: 1, availableSlots: 2 },
+  },
+  {
+    name: 'priya-no-slots',
+    description: 'Priya, eligible, no slots available in the next seven days',
+    seed: 3,
+    overrides: { availableSlots: 0 },
+  },
+];
+
+export default scenarios;