@spunto/build 0.3.0 → 0.4.0

package/src/types/index.ts

@@ -0,0 +1,68 @@
+// The shapes a worker's environment is described by, and the shape it reports back in.
+//
+// These live here rather than in either product's ORM schema because the dependency runs the wrong
+// way otherwise: a script generator needs to know what a feature is, and it cannot import a Drizzle
+// table — let alone two, one on Postgres and one on SQLite. So the package owns the types, and each
+// schema declares its JSON column with `$type<…>()` pointing at them.
+//
+// That makes them **versioned contract**. `SetupStatus` in particular is what a shell script writes
+// into a file inside a container and a control plane reads back out minutes later: changing it is a
+// migration, not an edit. It already was one — this file just gives it somewhere to be written down.
+
+/** A devcontainer feature as a project selects it. */
+export type ProjectFeature = {
+  id: string
+  /** Set for a hand-typed OCI ref that isn't in the catalog. */
+  ociRef?: string
+  /** Filename of an install script the platform ships itself, instead of an OCI ref. */
+  localScript?: string
+  options?: Record<string, string>
+}
+
+/** A repository cloned into a worker's workspace. */
+export type Repository = {
+  id: string
+  /** `git` = cloned from a raw URL with the project's deploy key, rather than through a forge app. */
+  provider: string
+  /** `owner/repo` for a forge, a human label for a raw URL. */
+  project: string
+  /** Directory under `/workspace`. */
+  workspacePath: string
+  /** Which forge-app installation grants access. Instance-scoped — never travels in a spec. */
+  installationId?: number
+  cloneUrl?: string
+  /** Absent/empty = the remote's default branch. We do not guess it. */
+  branch?: string
+}
+
+/** How far a repository's clone got. */
+export type RepoSetupState = "pending" | "cloning" | "done" | "error"
+
+/** How far a lifecycle command got. `null` = the project has none. */
+export type LifecycleState = "pending" | "running" | "done" | "error" | null
+
+/**
+ * What a worker reports about its own setup, written to `WORKER_STATUS_FILE` (`../naming`) by the
+ * generated setup script and read back by the control plane.
+ *
+ * `phase` is deliberately a flat enum rather than a state machine: the writer is a shell script,
+ * and the only thing it can do reliably is overwrite a field.
+ */
+export type SetupStatus = {
+  phase: "initializing" | "credentials" | "dotfiles" | "cloning" | "lifecycle" | "ready" | "error"
+  repos: { name: string; state: RepoSetupState }[]
+  postCreate: LifecycleState
+  postStart: LifecycleState
+  error?: string
+  /**
+   * Per-phase start timestamps (ms epoch), stamped container-side at each transition. Keys are
+   * phase milestones in order: `initializing`, `credentials`, `shell`, `dotfiles`, `cloning`,
+   * `postCreate`, `postStart`, `ready`.
+   *
+   * Optional, and absent on older workers and hard crashes — so a reader derives a segment's
+   * duration as "next present milestone minus this one" rather than assuming the next key exists.
+   */
+  timings?: Record<string, number>
+}
+
+export type { BuildStep, BuildStepKind, BuildStepState } from "../steps/build-steps"