@cfasim-ui/server 0.0.0-stage → 0.9.3

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@cfasim-ui/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.3",
+  "type": "module",
+  "description": "Local task-server integration for cfasim-ui: run long jobs with streamed progress and saved runs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CDCgov/cfa-simulator.git",
+    "directory": "cfasim-ui/server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/*.test.ts",
+    "!src/testUtils.ts"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./vite": "./src/vitePlugin.js"
+  },
+  "dependencies": {
+    "@cfasim-ui/shared": "0.9.3"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "vitest": "4.1.10",
+    "vue": "3.5.40"
+  }
 }

package/src/api.ts

@@ -0,0 +1,110 @@
+import type { ModelOutput } from "@cfasim-ui/shared";
+import { decodeModelOutputs } from "@cfasim-ui/shared";
+import type { RunFile, RunSummary, TaskInfo } from "./types.js";
+
+const DEFAULT_BASE_URL = "/api";
+
+interface StartedRun {
+  run_id: string;
+  name: string | null;
+  inputs_hash: string;
+}
+
+export class ServerError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly url: string,
+  ) {
+    super(message);
+    this.name = "ServerError";
+  }
+}
+
+export const errorMessage = (e: unknown) =>
+  e instanceof Error ? e.message : String(e);
+
+async function request(url: string, init?: RequestInit): Promise<Response> {
+  const res = await fetch(url, init);
+  if (!res.ok) {
+    let detail = `${res.status} ${res.statusText}`;
+    try {
+      const body = (await res.json()) as { error?: string };
+      if (body?.error) detail = body.error;
+    } catch {
+      // not JSON: keep the status line
+    }
+    throw new ServerError(detail, res.status, url);
+  }
+  return res;
+}
+
+export function createApi(baseUrl: string = DEFAULT_BASE_URL) {
+  const base = baseUrl.replace(/\/$/, "");
+  const url = (path: string) => `${base}${path}`;
+  const runUrl = (runId: string, suffix = "") =>
+    url(`/runs/${encodeURIComponent(runId)}${suffix}`);
+  return {
+    baseUrl: base,
+    eventsUrl: (runId: string) => runUrl(runId, "/events"),
+    fileUrl: (runId: string, path: string) =>
+      runUrl(
+        runId,
+        `/files/${path.split("/").map(encodeURIComponent).join("/")}`,
+      ),
+    async listTasks(): Promise<TaskInfo[]> {
+      const res = await request(url("/tasks"));
+      return ((await res.json()) as { tasks: TaskInfo[] }).tasks;
+    },
+    async listRuns(task?: string, limit?: number): Promise<RunSummary[]> {
+      const params = new URLSearchParams();
+      if (task) params.set("task", task);
+      if (limit !== undefined) params.set("limit", String(limit));
+      const query = params.toString();
+      const res = await request(url(`/runs${query ? `?${query}` : ""}`));
+      return ((await res.json()) as { runs: RunSummary[] }).runs;
+    },
+    async getRun(runId: string): Promise<RunSummary> {
+      const res = await request(runUrl(runId));
+      return (await res.json()) as RunSummary;
+    },
+    async startRun(
+      task: string,
+      inputs: Record<string, unknown>,
+      name?: string,
+    ): Promise<StartedRun> {
+      const res = await request(url(`/tasks/${encodeURIComponent(task)}/run`), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(name ? { inputs, name } : { inputs }),
+      });
+      return (await res.json()) as StartedRun;
+    },
+    async cancelRun(runId: string): Promise<void> {
+      await request(runUrl(runId, "/cancel"), {
+        method: "POST",
+      });
+    },
+    async fetchInputs(runId: string): Promise<Record<string, unknown>> {
+      const res = await request(runUrl(runId, "/inputs"));
+      return (await res.json()) as Record<string, unknown>;
+    },
+    async fetchLog(runId: string): Promise<string> {
+      const res = await request(runUrl(runId, "/log"));
+      return res.text();
+    },
+    async fetchFiles(runId: string): Promise<RunFile[]> {
+      const res = await request(runUrl(runId, "/files"));
+      return ((await res.json()) as { files: RunFile[] }).files;
+    },
+    async fetchOutputs(
+      runId: string,
+      signal?: AbortSignal,
+    ): Promise<Record<string, ModelOutput>> {
+      const res = await request(runUrl(runId, "/outputs"), { signal });
+      return decodeModelOutputs(await res.arrayBuffer());
+    },
+  };
+}
+
+export type ServerApi = ReturnType<typeof createApi>;

package/src/index.ts

@@ -0,0 +1,18 @@
+export { useServerModel } from "./useServerModel.js";
+export type { ServerModel } from "./useServerModel.js";
+export { useRun } from "./useRun.js";
+export { createApi, ServerError } from "./api.js";
+export type { ServerApi } from "./api.js";
+export type {
+  LogLine,
+  RunError,
+  RunFile,
+  RunHandle,
+  RunProgress,
+  RunStatus,
+  RunSummary,
+  ServerOptions,
+  TaskInfo,
+  TaskParam,
+} from "./types.js";
+export { TERMINAL_STATUSES } from "./types.js";

package/src/types.ts

@@ -0,0 +1,85 @@
+import type { ModelOutput } from "@cfasim-ui/shared";
+import type { ComputedRef, Ref } from "vue";
+
+export type RunStatus = "queued" | "running" | "done" | "error" | "cancelled";
+
+export const TERMINAL_STATUSES: ReadonlySet<RunStatus> = new Set([
+  "done",
+  "error",
+  "cancelled",
+]);
+
+export interface RunProgress {
+  fraction: number;
+  message: string | null;
+}
+
+export interface RunError {
+  message: string;
+  traceback: string | null;
+}
+
+/** One run as listed by `GET /api/runs` (the run's `status.json`). */
+export interface RunSummary {
+  run_id: string;
+  /** Optional label given when the run was started; also prefixes `run_id`. */
+  name: string | null;
+  task: string;
+  inputs_hash: string;
+  status: RunStatus;
+  created_at: string;
+  started_at: string | null;
+  finished_at: string | null;
+  progress: RunProgress | null;
+  outputs: { revision: number; partial: boolean; names: string[] } | null;
+  error: RunError | null;
+}
+
+export interface TaskParam {
+  name: string;
+  required: boolean;
+  default: unknown;
+  annotation: string | null;
+}
+
+export interface TaskInfo {
+  name: string;
+  doc: string | null;
+  params: TaskParam[];
+  accepts_extra: boolean;
+}
+
+/** A file the task wrote into its run directory. */
+export interface RunFile {
+  path: string;
+  size: number;
+  modified: string;
+}
+
+export interface LogLine {
+  stream: "stdout" | "stderr" | "task";
+  line: string;
+}
+
+export interface ServerOptions {
+  /** Prefix of the server's REST routes (default `"/api"`, the Vite proxy path). */
+  baseUrl?: string;
+}
+
+export interface RunHandle {
+  id: Readonly<Ref<string | undefined>>;
+  status: Ref<RunStatus | undefined>;
+  progress: Ref<RunProgress | undefined>;
+  log: Ref<LogLine[]>;
+  outputs: Ref<Record<string, ModelOutput> | undefined>;
+  /** Revision of `outputs`; increments every time the task emits. */
+  revision: Ref<number>;
+  inputs: Ref<Record<string, unknown> | undefined>;
+  files: Ref<RunFile[]>;
+  error: Ref<string | undefined>;
+  /** `true` while the run is queued or running. */
+  active: ComputedRef<boolean>;
+  /** URL of a file the task wrote, for download links; `""` with no run. */
+  fileUrl: (path: string) => string;
+  refreshFiles: () => Promise<void>;
+}

package/src/useRun.ts

@@ -0,0 +1,298 @@
+import { computed, onScopeDispose, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter } from "vue";
+import type { ModelOutput } from "@cfasim-ui/shared";
+import { createApi, errorMessage } from "./api.js";
+import type { ServerApi } from "./api.js";
+import type {
+  LogLine,
+  RunFile,
+  RunHandle,
+  RunProgress,
+  RunStatus,
+  ServerOptions,
+} from "./types.js";
+import { TERMINAL_STATUSES } from "./types.js";
+
+const MAX_LOG_LINES = 5000;
+
+const CONNECTION_LOST = "Connection to the server lost, retrying";
+
+// log.txt prefixes every non-stdout line with its stream, e.g. "[stderr] ".
+function parseSavedLog(text: string): LogLine[] {
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.map((line) => {
+    const m = /^\[(stderr|task)\] (.*)$/s.exec(line);
+    return m
+      ? { stream: m[1] as LogLine["stream"], line: m[2] }
+      : { stream: "stdout", line };
+  });
+}
+
+interface LogEvent {
+  stream: LogLine["stream"];
+  line: string;
+  overwrite: boolean;
+}
+
+/**
+ * Follow one run: its status, progress, log, and outputs, live over
+ * Server-Sent Events. Pass a ref to switch runs; pass `undefined` to detach.
+ * Two handles on two run ids give side-by-side comparison.
+ */
+export function useRun(
+  runId: MaybeRefOrGetter<string | undefined>,
+  options: ServerOptions | { api: ServerApi } = {},
+): RunHandle {
+  const api = "api" in options ? options.api : createApi(options.baseUrl);
+
+  const id = ref<string>();
+  const status = ref<RunStatus>();
+  const progress = ref<RunProgress>();
+  const log = ref<LogLine[]>([]);
+  const outputs = shallowRef<Record<string, ModelOutput>>();
+  const revision = ref(0);
+  const inputs = ref<Record<string, unknown>>();
+  const files = ref<RunFile[]>([]);
+  const error = ref<string>();
+  const active = computed(
+    () => status.value === "queued" || status.value === "running",
+  );
+
+  let source: EventSource | undefined;
+  // The in-flight `/outputs` fetch; at most one at a time.
+  let controller: AbortController | undefined;
+  // Highest outputs revision announced by the server.
+  let wantedRevision = 0;
+  let fetchScheduled = false;
+  let outputsError: string | undefined;
+  // The stream ended before `seed` knew the status (an old, finished run).
+  let streamEnded = false;
+  // Index into `log` of the last overwrite line per stream, so progress-bar
+  // updates replace rather than append.
+  let overwriteIndex: Partial<Record<LogLine["stream"], number>> = {};
+
+  function reset() {
+    status.value = undefined;
+    progress.value = undefined;
+    log.value = [];
+    outputs.value = undefined;
+    revision.value = 0;
+    inputs.value = undefined;
+    files.value = [];
+    error.value = undefined;
+    wantedRevision = 0;
+    fetchScheduled = false;
+    outputsError = undefined;
+    streamEnded = false;
+    overwriteIndex = {};
+  }
+
+  function closeSource() {
+    source?.close();
+    source = undefined;
+  }
+
+  function teardown() {
+    closeSource();
+    controller?.abort();
+    controller = undefined;
+  }
+
+  function finish(next: RunStatus) {
+    status.value = next;
+    closeSource();
+    if (error.value === CONNECTION_LOST) error.value = undefined;
+    // Picks up a revision whose fetch failed or is still pending.
+    scheduleOutputs();
+    void refreshFiles();
+  }
+
+  // Loads the saved log when the event stream had none to replay.
+  async function loadSavedLog() {
+    const current = id.value;
+    if (!current || log.value.length) return;
+    try {
+      const text = await api.fetchLog(current);
+      if (id.value !== current || log.value.length) return;
+      log.value = parseSavedLog(text).slice(-MAX_LOG_LINES);
+    } catch {
+      // no log file yet; nothing to show
+    }
+  }
+
+  async function refreshFiles() {
+    const current = id.value;
+    if (!current) return;
+    try {
+      const list = await api.fetchFiles(current);
+      if (id.value === current) files.value = list;
+    } catch {
+      // the run may be gone; keep the previous list
+    }
+  }
+
+  function requestOutputs(nextRevision: number) {
+    if (nextRevision > wantedRevision) wantedRevision = nextRevision;
+    scheduleOutputs();
+  }
+
+  function scheduleOutputs() {
+    if (fetchScheduled || controller || wantedRevision <= revision.value) {
+      return;
+    }
+    fetchScheduled = true;
+    // Coalesce a burst of `outputs` events (history replay) into one fetch.
+    queueMicrotask(() => {
+      fetchScheduled = false;
+      const current = id.value;
+      const target = wantedRevision;
+      if (!current || controller || target <= revision.value) return;
+      const ctl = (controller = new AbortController());
+      api
+        .fetchOutputs(current, ctl.signal)
+        .then((decoded) => {
+          if (controller !== ctl) return;
+          outputs.value = decoded;
+          revision.value = target;
+          if (error.value === outputsError) error.value = undefined;
+          outputsError = undefined;
+          controller = undefined;
+          // Revisions that arrived meanwhile.
+          scheduleOutputs();
+        })
+        .catch((e: unknown) => {
+          if (controller !== ctl) return;
+          controller = undefined;
+          // The next `outputs` event, or the run finishing, retries.
+          outputsError = error.value = errorMessage(e);
+        });
+    });
+  }
+
+  function appendLog(event: LogEvent) {
+    const lines = log.value;
+    const entry: LogLine = { stream: event.stream, line: event.line };
+    const prev = overwriteIndex[event.stream];
+    if (event.overwrite && prev !== undefined && lines[prev]) {
+      lines[prev] = entry;
+      return;
+    }
+    lines.push(entry);
+    if (event.overwrite) {
+      overwriteIndex[event.stream] = lines.length - 1;
+    } else {
+      delete overwriteIndex[event.stream];
+    }
+    if (lines.length > MAX_LOG_LINES) {
+      lines.splice(0, lines.length - MAX_LOG_LINES);
+      overwriteIndex = {};
+    }
+  }
+
+  function subscribe(runId: string) {
+    const es = new EventSource(api.eventsUrl(runId));
+    source = es;
+    const on = <T>(type: string, handler: (data: T) => void) => {
+      es.addEventListener(type, (e) => {
+        // The browser also dispatches its own connection "error" Event here,
+        // which carries no data; `onerror` below handles that one.
+        const data = (e as MessageEvent).data as unknown;
+        if (source !== es || typeof data !== "string") return;
+        handler(JSON.parse(data) as T);
+      });
+    };
+    on<{ status: RunStatus }>("status", (d) => {
+      status.value = d.status;
+    });
+    on<RunProgress>("progress", (d) => {
+      progress.value = { fraction: d.fraction, message: d.message ?? null };
+    });
+    on<LogEvent>("log", appendLog);
+    on<{ revision: number }>("outputs", (d) => requestOutputs(d.revision));
+    on("done", () => finish("done"));
+    on<{ message: string }>("error", (d) => {
+      error.value = d.message;
+      finish("error");
+    });
+    on("cancelled", () => finish("cancelled"));
+    es.onerror = () => {
+      if (source !== es) return;
+      // Until `seed` has told us the status, a closed stream may simply be a
+      // finished run from an earlier server session; `seed` closes those.
+      if (!status.value) {
+        streamEnded = true;
+        return;
+      }
+      if (TERMINAL_STATUSES.has(status.value)) {
+        closeSource();
+        void loadSavedLog();
+        return;
+      }
+      // The browser reconnects on its own; say so until the next event.
+      if (!error.value) error.value = CONNECTION_LOST;
+    };
+    es.onopen = () => {
+      if (source !== es) return;
+      streamEnded = false;
+      if (error.value === CONNECTION_LOST) error.value = undefined;
+    };
+  }
+
+  async function seed(runId: string) {
+    try {
+      const [summary, runInputs] = await Promise.all([
+        api.getRun(runId),
+        api.fetchInputs(runId),
+      ]);
+      if (id.value !== runId) return;
+      // Events may have moved things along while we fetched.
+      if (!status.value) status.value = summary.status;
+      // A finished run's stream replays its history and then ends, which
+      // `onerror` handles; one that already ended had nothing to replay.
+      if (TERMINAL_STATUSES.has(status.value) && streamEnded) {
+        closeSource();
+        void loadSavedLog();
+      }
+      if (!progress.value && summary.progress)
+        progress.value = summary.progress;
+      inputs.value = runInputs;
+      if (summary.outputs) requestOutputs(summary.outputs.revision);
+      if (summary.error && !error.value) error.value = summary.error.message;
+    } catch (e: unknown) {
+      if (id.value !== runId) return;
+      error.value = errorMessage(e);
+    }
+    void refreshFiles();
+  }
+
+  watch(
+    () => toValue(runId),
+    (next) => {
+      teardown();
+      reset();
+      id.value = next;
+      if (!next) return;
+      subscribe(next);
+      void seed(next);
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(teardown);
+
+  return {
+    id,
+    status,
+    progress,
+    log,
+    outputs,
+    revision,
+    inputs,
+    files,
+    error,
+    active,
+    fileUrl: (path: string) => (id.value ? api.fileUrl(id.value, path) : ""),
+    refreshFiles,
+  };
+}

package/src/useServerModel.ts

@@ -0,0 +1,160 @@
+import { onScopeDispose, ref, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+import { ServerError, createApi, errorMessage } from "./api.js";
+import { useRun } from "./useRun.js";
+import type {
+  RunHandle,
+  RunSummary,
+  ServerOptions,
+  TaskInfo,
+} from "./types.js";
+import { TERMINAL_STATUSES } from "./types.js";
+
+const RECONNECT_INTERVAL_MS = 3000;
+
+const UNREACHABLE = (baseUrl: string) =>
+  `Could not reach the cfasim server at ${baseUrl}. Is it running? (In dev, \`pnpm dev\` starts it through the Vite plugin.)`;
+
+export interface ServerModel {
+  tasks: Ref<TaskInfo[]>;
+  runs: Ref<RunSummary[]>;
+  /**
+   * `false` while the server cannot be reached; it is retried every few
+   * seconds until it answers.
+   */
+  connected: Ref<boolean>;
+  error: Ref<string | undefined>;
+  refreshTasks: () => Promise<void>;
+  refreshRuns: () => Promise<void>;
+  /**
+   * Start `task` with `inputs`; the new run becomes `current`. Resolves to
+   * its id, or `undefined` when the server refused it (`error` says why). A
+   * `name` labels the run and prefixes its id and folder.
+   */
+  start: (
+    task: string,
+    inputs: Record<string, unknown>,
+    options?: { name?: string },
+  ) => Promise<string | undefined>;
+  cancel: (runId?: string) => Promise<void>;
+  /** Make an existing run `current` (its events replay from the server). */
+  load: (runId: string | undefined) => void;
+  current: RunHandle;
+  /** Follow any other run, e.g. to compare two side by side. */
+  useRun: (runId: MaybeRefOrGetter<string | undefined>) => RunHandle;
+}
+
+/**
+ * Talk to a cfasim task server: list its tasks and saved runs, start and
+ * cancel runs, and follow the current one.
+ */
+export function useServerModel(options: ServerOptions = {}): ServerModel {
+  const api = createApi(options.baseUrl);
+  const tasks = ref<TaskInfo[]>([]);
+  const runs = ref<RunSummary[]>([]);
+  const connected = ref(true);
+  const error = ref<string>();
+  const currentId = ref<string>();
+  const current = useRun(currentId, { api });
+
+  let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  let runsRequest = 0;
+
+  // A network error, or the dev proxy's 502/504 when nothing listens behind it.
+  const unreachable = (e: unknown) =>
+    e instanceof TypeError ||
+    (e instanceof ServerError && (e.status === 502 || e.status === 504));
+
+  function fail(e: unknown) {
+    if (unreachable(e)) {
+      connected.value = false;
+      error.value = UNREACHABLE(api.baseUrl);
+      reconnectTimer ??= setTimeout(() => {
+        reconnectTimer = undefined;
+        void refreshTasks().then(() => {
+          if (connected.value) void refreshRuns();
+        });
+      }, RECONNECT_INTERVAL_MS);
+    } else {
+      error.value = errorMessage(e);
+    }
+  }
+
+  async function load<T>(fetchIt: () => Promise<T>, apply: (value: T) => void) {
+    try {
+      const value = await fetchIt();
+      apply(value);
+      if (!connected.value) {
+        connected.value = true;
+        if (error.value === UNREACHABLE(api.baseUrl)) error.value = undefined;
+      }
+    } catch (e) {
+      fail(e);
+    }
+  }
+
+  const refreshTasks = () =>
+    load(api.listTasks, (value) => {
+      tasks.value = value;
+    });
+
+  function refreshRuns() {
+    // Responses can arrive out of order; only the newest request applies.
+    const request = ++runsRequest;
+    return load(api.listRuns, (value) => {
+      if (request === runsRequest) runs.value = value;
+    });
+  }
+
+  async function start(
+    task: string,
+    inputs: Record<string, unknown>,
+    options: { name?: string } = {},
+  ) {
+    error.value = undefined;
+    const name = options.name?.trim() || undefined;
+    try {
+      const { run_id } = await api.startRun(task, inputs, name);
+      currentId.value = run_id;
+      void refreshRuns();
+      return run_id;
+    } catch (e) {
+      fail(e);
+      return undefined;
+    }
+  }
+
+  async function cancel(runId: string | undefined = currentId.value) {
+    if (!runId) return;
+    try {
+      await api.cancelRun(runId);
+    } catch (e) {
+      fail(e);
+    }
+  }
+
+  watch(current.status, (next) => {
+    if (next && TERMINAL_STATUSES.has(next)) void refreshRuns();
+  });
+
+  onScopeDispose(() => clearTimeout(reconnectTimer));
+
+  void refreshTasks();
+  void refreshRuns();
+
+  return {
+    tasks,
+    runs,
+    connected,
+    error,
+    refreshTasks,
+    refreshRuns,
+    start,
+    cancel,
+    load: (runId) => {
+      currentId.value = runId;
+    },
+    current,
+    useRun: (runId) => useRun(runId, { api }),
+  };
+}

package/src/vitePlugin.js

@@ -0,0 +1,253 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+/**
+ * @typedef {object} CfasimServerOptions
+ * @property {string} [bin] The `cfasim` executable to run (default: `$CFASIM_BIN`, else `cfasim` on PATH, falling back to `uvx cfasim@<this package's version>`)
+ * @property {string} [tasks] Passed as `--tasks`: a Python module or `.py` file, or the name of the Rust tasks binary (default: `cfasim serve` detects it from the project)
+ * @property {string[]} [command] Full command to start the server; overrides every other option that shapes it, and does not get `--app-url` (default: `cfasim serve --port <port> --output <output> --app-url <dev server url>`)
+ * @property {number} [port] Port the server listens on (default: 8765)
+ * @property {string} [output] Directory that holds one folder per run, passed as `--output` (default: "output")
+ * @property {boolean} [csv] Also write `<table>.csv` for each output table when a run finishes (passes `--csv`)
+ * @property {boolean} [debug] Build a Rust tasks binary without `--release` (passes `--debug`)
+ * @property {string} [cwd] Directory to start the server in (default: `process.cwd()`, the project root where `pyproject.toml` or `Cargo.toml` lives)
+ */
+
+const DEFAULT_PORT = 8765;
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const STOP_TIMEOUT_MS = 5000;
+
+/** @type {Record<symbol, Map<number, Promise<void>> | undefined>} */
+const globals = /** @type {any} */ (globalThis);
+/**
+ * Servers still shutting down, by port. A Vite restart builds a new plugin
+ * instance whose server must wait for the old one to free the port; the map
+ * lives on globalThis so a re-bundled copy of this module shares it.
+ */
+const stopping = (globals[Symbol.for("cfasim-server.stopping")] ??= new Map());
+
+/** @param {import("node:child_process").ChildProcess} proc */
+const exited = (proc) => proc.exitCode !== null || proc.signalCode !== null;
+
+/** This package's version, which is also the matching `cfasim` CLI version. */
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    );
+    return typeof pkg.version === "string" ? pkg.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Signal a child's whole process group (a detached child leads one); falls
+ * back to the child alone where groups are unavailable.
+ * @param {number} pid
+ * @param {NodeJS.Signals} signal
+ */
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/**
+ * The `serve` arguments shared by every launcher.
+ * @param {CfasimServerOptions} options
+ * @param {string} [appUrl]
+ * @returns {string[]}
+ */
+function serveArgs(options, appUrl) {
+  const args = [
+    "serve",
+    "--port",
+    String(options.port ?? DEFAULT_PORT),
+    "--output",
+    options.output ?? "output",
+  ];
+  if (options.csv) args.push("--csv");
+  if (options.debug) args.push("--debug");
+  if (options.tasks) args.push("--tasks", options.tasks);
+  if (appUrl) args.push("--app-url", appUrl);
+  return args;
+}
+
+/**
+ * Build the argv used to start the server.
+ * @param {CfasimServerOptions} [options]
+ * @param {string} [appUrl] Where the page is served; the server prints it once it is up
+ * @returns {string[]}
+ */
+export function serverCommand(options = {}, appUrl) {
+  if (options.command) return [...options.command];
+  const bin = options.bin ?? process.env.CFASIM_BIN ?? "cfasim";
+  return [bin, ...serveArgs(options, appUrl)];
+}
+
+/**
+ * The command to try when `cfasim` is not installed: the matching release
+ * through `uvx`, which caches it after the first run. `undefined` when the
+ * user chose the executable themselves.
+ * @param {CfasimServerOptions} [options]
+ * @param {string} [appUrl]
+ * @returns {string[] | undefined}
+ */
+export function fallbackCommand(options = {}, appUrl) {
+  if (options.command || options.bin || process.env.CFASIM_BIN)
+    return undefined;
+  const version = packageVersion();
+  const spec = version ? `cfasim@${version}` : "cfasim";
+  return ["uvx", spec, ...serveArgs(options, appUrl)];
+}
+
+/**
+ * The dev server's local URL, from the bound port (Vite may not get the port
+ * it asked for) and the resolved config.
+ * @param {import("vite").ViteDevServer} server
+ * @returns {string | undefined}
+ */
+function appUrl(server) {
+  const address = server.httpServer?.address();
+  if (!address || typeof address === "string") return undefined;
+  const protocol = server.config.server.https ? "https" : "http";
+  return `${protocol}://localhost:${address.port}${server.config.base}`;
+}
+
+/**
+ * Vite plugin that starts `cfasim serve` next to the dev server and proxies
+ * `/api` to it. It only runs for `vite dev`; a production build is a static
+ * site that you serve with `cfasim serve --static dist`.
+ *
+ * @param {CfasimServerOptions} [options]
+ * @returns {import("vite").Plugin}
+ */
+export function cfasimServer(options = {}) {
+  const port = options.port ?? DEFAULT_PORT;
+  const cwd = options.cwd ?? process.cwd();
+
+  return {
+    name: "cfasim-server",
+    apply: "serve",
+    config() {
+      return {
+        server: {
+          proxy: {
+            "/api": { target: `http://127.0.0.1:${port}` },
+          },
+        },
+      };
+    },
+    configureServer(server) {
+      const logger = server.config.logger;
+      let closing = false;
+      /** @type {import("node:child_process").ChildProcess | undefined} */
+      let child;
+
+      /**
+       * @param {string[]} command
+       * @param {string[] | undefined} fallback Tried when `command[0]` is not installed
+       */
+      const launch = (command, fallback) => {
+        logger.info(`[cfasim-server] starting: ${command.join(" ")}`);
+        // Own process group, so stopping signals a launcher (uvx) and the
+        // server it started together.
+        child = spawn(command[0], command.slice(1), {
+          cwd,
+          stdio: "inherit",
+          detached: true,
+        });
+        child.on("error", (err) => {
+          if (
+            fallback &&
+            !closing &&
+            /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+          ) {
+            logger.warn(
+              `[cfasim-server] ${command[0]} is not installed; trying ${fallback.slice(0, 2).join(" ")}`,
+            );
+            launch(fallback, undefined);
+            return;
+          }
+          logger.error(
+            `[cfasim-server] failed to start (${err.message}). Install the cfasim CLI (\`cargo install cfasim\` or \`uv tool install cfasim\`) or set CFASIM_BIN to its path.`,
+          );
+        });
+        child.on("exit", (code, signal) => {
+          if (closing || code === 0 || code === null) return;
+          logger.error(
+            `[cfasim-server] exited with code ${code}${signal ? ` (${signal})` : ""}. If port ${port} is in use, stop the other server or set a different \`port\`.`,
+          );
+        });
+      };
+
+      // Start once Vite has its port, so the server can tell the user which
+      // URL to open (the API port is the one people open by mistake).
+      const start = () => {
+        if (closing) return;
+        const previous = stopping.get(port);
+        if (previous) {
+          // After a Vite restart, the old server may still hold the port.
+          void previous.then(start);
+          return;
+        }
+        const url = appUrl(server);
+        const opts = { ...options, port };
+        launch(serverCommand(opts, url), fallbackCommand(opts, url));
+      };
+      const httpServer = server.httpServer;
+      if (httpServer && !httpServer.listening) {
+        httpServer.once("listening", start);
+      } else {
+        start();
+      }
+
+      const stop = () => {
+        if (closing) return;
+        closing = true;
+        for (const sig of SIGNALS) process.off(sig, onSignal);
+        process.off("exit", stop);
+        const proc = child;
+        const pid = proc?.pid;
+        if (!proc || exited(proc) || pid === undefined) return;
+        /** @type {Promise<void>} */
+        const done = new Promise((resolve) => {
+          proc.once("exit", () => resolve());
+          setTimeout(resolve, STOP_TIMEOUT_MS).unref();
+        });
+        stopping.set(port, done);
+        void done.then(() => {
+          if (stopping.get(port) === done) stopping.delete(port);
+        });
+        signalGroup(pid, "SIGTERM");
+        // The server stops its worker and exits on SIGTERM; this is the
+        // backstop for a launcher that ignores it.
+        const backstop = setTimeout(() => {
+          if (!exited(proc)) signalGroup(pid, "SIGKILL");
+        }, 3000);
+        backstop.unref();
+      };
+      // Vite's own SIGTERM handling exits without running "exit" listeners,
+      // so hook the signals too or the server outlives the dev server.
+      // Listening suppresses Node's default exit, so hand the signal back
+      // afterwards (signal-exit, which rolldown installs, only re-raises when
+      // it is the sole listener, so waiting for it would hang). SIGTERM is
+      // Vite's to finish: it closes the server and exits.
+      /** @param {NodeJS.Signals} sig */
+      const onSignal = (sig) => {
+        stop();
+        if (sig !== "SIGTERM") process.kill(process.pid, sig);
+      };
+      for (const sig of SIGNALS) process.once(sig, onSignal);
+      process.once("exit", stop);
+      httpServer?.once("close", stop);
+    },
+  };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.