Types

Why it existsCopy Anchor Link

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 dependency would run the wrong way. Instead, the package owns the types, and each product's ORM schema declares its JSON columns with $type<…>() pointing at them:

import type { ProjectFeature, Repository, SetupStatus } from "@spunto/build/types"

export const projects = pgTable("projects", {
  features: jsonb("features").$type<ProjectFeature[]>(),
  repositories: jsonb("repositories").$type<Repository[]>().notNull(),
})
export const workers = pgTable("workers", {
  setupStatus: jsonb("setup_status").$type<SetupStatus>(),
})

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.

These are the strict, canonical shapes a control plane writes. The design system deliberately models the same data as lax, optional shapes so a UI degrades instead of throwing; TypeScript's structural typing joins the two without either package importing the other.

Project shapesCopy Anchor Link

ProjectFeatureCopy Anchor Link

A devcontainer feature as a project selects it.

RepositoryCopy Anchor Link

A repository cloned into a worker's workspace.

Setup statusCopy Anchor Link

SetupStatusCopy Anchor Link

What a worker reports about its own setup. Written to WORKER_STATUS_FILE (./naming) by the generated setup script, read back by the control plane. The JSON layout is in Formats → Worker status.

type RepoSetupState = "pending" | "cloning" | "done" | "error"
/** `null` = the project has no such command. */
type LifecycleState = "pending" | "running" | "done" | "error" | null

{
  "phase": "cloning",
  "repos": [{ "name": "acme/app", "state": "cloning" }],
  "postCreate": "pending",
  "postStart": null,
  "timings": { "initializing": 1767225600000, "credentials": 1767225601200, "cloning": 1767225603400 }
}

RepoSetupState and LifecycleState are not exported by name; use SetupStatus["repos"][number]["state"] and SetupStatus["postCreate"] if you need them.

BuildStep, BuildStepKind, BuildStepStateCopy Anchor Link

Re-exported from ./steps, so an ORM schema can type a build's persisted step plan from this entry point too.

Worker status vocabularyCopy Anchor Link

The list of statuses a worker row can carry, what a status carries with it, and which transitions are allowed — a versioned contract between control planes, not an application detail.

WORKER_STATUSES / WorkerStatusCopy Anchor Link

const WORKER_STATUSES = [
  "provisioning", "building", "pulling", "starting", "ready",
  "stopping", "stopped", "deleting", "exited", "unknown", "error",
] as const
type WorkerStatus = (typeof WORKER_STATUSES)[number]

Three different "something is wrong" statuses, told apart on purpose:

• stopped — someone asked for it;
• exited — the container died on its own;
• error — a platform operation failed.

WorkerStatusReasonCopy Anchor Link

Why a worker is in its status:

WorkerStatusMetaCopy Anchor Link

What a status carries with it. One object, so a new case is not a migration.

WORKER_STATUS_TRANSITIONSCopy Anchor Link

const WORKER_STATUS_TRANSITIONS: Record<WorkerStatus, readonly WorkerStatus[]>

The allowed transitions, as a graph, not an ordered list — the lifecycle is not linear. building is a wait nested inside provisioning, so building → provisioning is legitimate.

Two decisions are encoded here:

1. A pre-container worker never goes unknown. provisioning, building and pulling lead to error when the node drops: the wait lived in the control plane and nobody will resume it. unknown means "the container probably exists, we can't see it" — there is nothing to not see before it exists.
2. deleting leads nowhere except failure: afterwards the row no longer exists, and "deleted" is not a status.

canTransition(from, to)Copy Anchor Link

function canTransition(from: WorkerStatus, to: WorkerStatus): boolean

true if from → to is in the graph.

async function setStatus(worker: Worker, to: WorkerStatus, meta: WorkerStatusMeta = {}) {
  if (!canTransition(worker.status, to)) {
    logger.warn(`refusing ${worker.status} → ${to} for ${worker.id}`)
    return
  }
  const previousStatus = to === "unknown" ? worker.status : undefined
  await db
    .update(workers)
    .set({ status: to, statusMeta: { ...meta, previousStatus, at: new Date().toISOString() } })
    .where(eq(workers.id, worker.id))
}

isSettingUp(status)Copy Anchor Link

function isSettingUp(status: WorkerStatus): boolean

The worker is not usable yet and the platform is working on it: provisioning, building, pulling or starting. This is the predicate that decides between a progress bar and a button. unknown is excluded — announcing a setup in flight for a machine nobody can see would be exactly the lie that status exists to avoid.

isTerminal(status)Copy Anchor Link

function isTerminal(status: WorkerStatus): boolean

Nothing moves on its own any more; an action is needed to leave: stopped, exited or error. unknown is not terminal (the node reconnecting will settle it), and neither is deleting (it ends with the row disappearing, not with a status).