@spunto/build 0.1.0 → 0.3.0

package/README.md

@@ -53,11 +53,65 @@ const forCodeServer = codeServerGallery(rawBlob) // the same choice, handed to t
 environment variable — and every other function takes its result. Nothing is memoized at import
 time, so one process can serve several tenants on several registries.
 
+### `@spunto/build/naming` — the names both sides have to pronounce the same way
+
+A worker is a container called `mp-worker-<id>`, with volumes and a network named after it, running
+an image called `mp-proj-<slug>:v<n>`. None of that is an implementation detail — each name is a
+contract between the script that writes it, the Docker client that looks it up and the UI that
+shows it:
+
+```ts
+import { workerContainerName, workerVolumePrefix, projectImageRef } from "@spunto/build/naming"
+
+docker.getContainer(workerContainerName(workerId))
+const ref = projectImageRef(projectId, version)   // mp-proj-my-app:v7
+```
+
+Also here: `workerNetworkName`, `workerVolumeName`, `isProjectImageRef`, `SHARED_NETWORK`, and the
+paths a worker and its control plane agree on — `WORKER_STATUS_FILE` / `workerStatusPath`,
+`EXTENSIONS_DIR`, `FEATURE_ENTRYPOINTS_DIR`, `EXTENSION_FAILURES_FILE`.
+
+**These are formats, not preferences.** Changing a value renames things that already exist on
+running machines: a live worker's container and volumes keep the name they were created with. Read
+a diff in that file as a migration, not a rename.
+
+### `@spunto/build/spec` — a project as a file you can carry between Spuntos
+
+Both products describe the same thing — an image, some features, some extensions, repositories,
+lifecycle commands. Lite could already export that to JSON; Cloud could not. And Lite's format
+announced itself as `spunto-lite/project`, putting the producer's name in the signature and making
+the file local by construction.
+
+```ts
+import { buildProjectSpec, parseProjectSpec, projectSpecFilename } from "@spunto/build/spec"
+
+const file = JSON.stringify(buildProjectSpec(project), null, 2)  // kind: "spunto/project"
+const spec = parseProjectSpec(await uploaded.text())             // throws a toast-safe message
+```
+
+Files exported by Lite before this package are still accepted on read; new ones always carry the
+neutral kind.
+
+**Secrets travel as names only** — values are write-only by design, and a spec is a file people
+mail each other. Instance identity (id, version history, deploy key) never travels either.
+
+**Shape here, policy there.** These schemas check that a file is well-formed, not that it is
+acceptable: mount-path rules, extension-id existence, git-ref validity all stay with the product
+doing the import, which validates its own create payload anyway. And a product **ignores the
+fields it has no feature for** — shared volumes are a Lite concept, the task settings a Cloud one,
+both optional. Dropping a field the target cannot honour is the correct outcome; refusing the file
+is not.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**
 React, **no** `process.env`, and knows **nothing** about organizations, users or compute nodes.
 
+`zod` is the one exception, and a deliberate one: `./spec` describes a file format that two
+products have to validate identically, and re-deriving the same schema on each side is exactly the
+duplication this package exists to remove. It is a **peer** dependency (`^4`), so a consumer's own
+zod is the one used — which matters, since apps extend these schemas with their own.
+
 Concretely: **no platform I/O**. No database, no Docker socket, no WebSocket. This package produces
 strings and parses strings; its only network call is outbound HTTP to a public extension registry,
 with no platform credential attached. Configuration arrives as function parameters — never read from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Spunto's shared Build engine \u2014 the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,14 @@
     "./extensions": {
       "types": "./src/extensions/index.ts",
       "import": "./src/extensions/index.ts"
+    },
+    "./naming": {
+      "types": "./src/naming/index.ts",
+      "import": "./src/naming/index.ts"
+    },
+    "./spec": {
+      "types": "./src/spec/index.ts",
+      "import": "./src/spec/index.ts"
     }
   },
   "files": [
@@ -48,6 +56,10 @@
   },
   "devDependencies": {
     "typescript": "^5",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "zod": "^4"
   }
 }

package/src/index.ts

@@ -2,8 +2,10 @@
 // plane: the build-log protocol, and VS Code extension resolution.
 //
 // Subpath imports are the normal way in (`@spunto/build/steps`, `@spunto/build/extensions`); this
-// root re-exports both for callers that would rather have one import. Nothing in this package reads
+// root re-exports them all for callers that would rather have one import. Nothing in this package reads
 // a database, opens a socket, or renders anything — see README.md for the rule and why it matters.
 
 export * from "./steps/index"
 export * from "./extensions/index"
+export * from "./naming/index"
+export * from "./spec/index"

package/src/naming/index.ts

@@ -0,0 +1,121 @@
+// The names both control planes have to pronounce the same way.
+//
+// A worker is a container called `mp-worker-<id>`, with volumes named after it, on a network named
+// after it, running an image called `mp-proj-<slug>:v<n>`, writing its progress to a file at a
+// fixed path. None of that is an implementation detail: each name is a contract between the shell
+// script that writes it, the Docker client that looks it up, and the UI that shows it.
+//
+// Until now none of them had a single definition. `mp-worker-<id>` was rebuilt by hand in fourteen
+// places across two apps — and a typo in one of them doesn't fail to compile, it produces a
+// container nobody can find at runtime. Spunto Lite rebuilds the same names again, on its side.
+//
+// **These are formats, not preferences.** Changing a value here renames things that already exist
+// on real machines: a running worker's container and volumes keep the name they were created with.
+// Treat every constant below as versioned protocol, the same way `../steps` treats its markers.
+//
+// The `mp-` prefix is historical (the product was called something else) and is deliberately left
+// alone: it is baked into containers, volumes and images that are running right now.
+
+/** Container that *is* the worker. */
+export function workerContainerName(workerId: string): string {
+  return `mp-worker-${workerId}`
+}
+
+/**
+ * Per-worker bridge network. Isolates each worker at L3 so no worker can reach another worker's
+ * container IP directly, bypassing the proxy.
+ */
+export function workerNetworkName(workerId: string): string {
+  return `mp-worker-${workerId}-net`
+}
+
+/**
+ * The named volumes a worker may own.
+ *
+ * `home` is historical: nothing creates it any more, but workers created before it was dropped
+ * still have one, so teardown has to keep looking for it. Spawning creates `workspace`, plus
+ * `docker` and `containerd` when the project runs docker-in-docker.
+ */
+export const WORKER_VOLUME_KINDS = ["workspace", "home", "docker", "containerd"] as const
+export type WorkerVolumeKind = (typeof WORKER_VOLUME_KINDS)[number]
+
+/** One of a worker's named volumes — `workspace` for the code, `docker`/`containerd` for DinD. */
+export function workerVolumeName(workerId: string, kind: WorkerVolumeKind): string {
+  return `mp-worker-${workerId}-${kind}`
+}
+
+/**
+ * Prefix every volume of one worker shares. Teardown and disk accounting both scan by prefix rather
+ * than by listing kinds, so that a volume added later is still found by code written before it.
+ */
+export function workerVolumePrefix(workerId: string): string {
+  return `mp-worker-${workerId}-`
+}
+
+/**
+ * Image a project's workers boot from, keyed by the project's *version* — see the image cache in
+ * docs/architecture-deep-dive.md. The slug is derived, not stored: an image ref may only hold
+ * lowercase alphanumerics and separators, and a project id is not guaranteed to.
+ */
+export function projectImageRef(projectId: string, version: number): string {
+  const slug = projectId
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+  return `mp-proj-${slug}:v${version}`
+}
+
+/** True for an image this platform built, as opposed to a base image it pulled. */
+export function isProjectImageRef(ref: string): boolean {
+  return /^mp-proj-[a-z0-9-]+:v\d+$/.test(ref)
+}
+
+/**
+ * Network every shared service joins under its slug, and every worker joins at spawn, so a
+ * workspace reaches `http://<slug>:<port>` by DNS. Spunto Lite's "shared services"; the local
+ * counterpart of the Ship pillar.
+ */
+export const SHARED_NETWORK = "mp-shared-net"
+
+/**
+ * Where a worker reports its own setup progress, read back by the control plane.
+ *
+ * Relative to the user's home rather than absolute: the remote user is a project setting, so the
+ * absolute path is only known once you know who the worker runs as — hence `workerStatusPath`.
+ */
+export const WORKER_STATUS_FILE = ".mp-status.json"
+
+/** Absolute path of the status file for a given home directory, e.g. `/home/vscode`. */
+export function workerStatusPath(home: string): string {
+  return `${home.replace(/\/+$/, "")}/${WORKER_STATUS_FILE}`
+}
+
+/**
+ * VS Code extensions are installed into the *image*, at a system path — not into a home, which is
+ * per worker and would make every worker re-download them.
+ */
+export const EXTENSIONS_DIR = "/opt/mp-extensions"
+
+/**
+ * **A file, not a directory** — a newline-separated, `sort -u`'d list of commands to run at
+ * container start. The devcontainer `entrypoint` contract, implemented on our side: a feature
+ * declares one, the image build appends it here, every boot reads the file back and runs each line.
+ *
+ * (Named `_DIR` in 0.2.0, which was wrong and is corrected here before anything depended on it.)
+ */
+export const FEATURE_ENTRYPOINTS_FILE = "/etc/mp-feature-entrypoints"
+
+/**
+ * Where entrypoints are accumulated *during* the image build, before being merged into
+ * `FEATURE_ENTRYPOINTS_FILE`. Separate because each feature install runs in its own layer and
+ * appends blindly; the merge is what deduplicates.
+ */
+export const FEATURE_ENTRYPOINTS_STAGING_FILE = "/tmp/mp-feature-entrypoints"
+
+/**
+ * Extensions the image build could not install, one id per line. Left in the image so a worker can
+ * tell what is missing without anyone re-reading the build log — see `EXTENSION_FAILED_MARKER` in
+ * `../steps`, which is the same information on its way out.
+ */
+export const EXTENSION_FAILURES_FILE = "/etc/mp-extension-failures"

package/src/spec/index.ts

@@ -0,0 +1,162 @@
+// A project, as a file you can carry from one Spunto to another.
+//
+// Both products describe the same thing — a devcontainer environment: an image, some features,
+// some extensions, repositories to clone, lifecycle commands. Spunto Lite could already export
+// that to JSON and import it back; Spunto Cloud could not. And Lite's format announced itself as
+// `spunto-lite/project`, which put the producer's name in the format's signature and made the
+// file local by construction.
+//
+// One format, `spunto/project`, is what turns "prototype it locally, then move it to the cloud"
+// from a slide into a feature.
+//
+// **What travels and what does not.** The spec holds what describes the *environment*, never what
+// identifies an instance: no id, no version history, no deploy key, no favourite flag. Secrets
+// travel as **names only** — their values are write-only by design, and a spec is a file people
+// mail each other. The names are there so an import can lay out the rows left to fill in.
+//
+// **Shape here, policy there.** These schemas check that a file is well-formed, not that it is
+// acceptable: whether a mount path is allowed, whether an extension id exists on the configured
+// registry, whether a branch name is valid git — all of that stays with the product doing the
+// import, which validates its own create payload anyway. A format that enforced one product's
+// policy would stop being portable the day the other's policy differed.
+//
+// **A product ignores the fields it has no feature for.** Shared volumes are a Lite concept, the
+// task settings are a Cloud one; both are optional, and importing a Cloud spec into Lite is
+// supposed to drop the task settings rather than fail. Losing a field the target cannot honour is
+// the correct outcome — refusing the file is not.
+
+import { z } from "zod"
+
+/** What a file produced today announces itself as. */
+export const PROJECT_SPEC_KIND = "spunto/project"
+
+/**
+ * Kinds still accepted on read. `spunto-lite/project` is what every file exported by Spunto Lite
+ * before this package says, and those files are on people's disks — refusing them to tidy up a
+ * string would break the only half of the feature that already shipped.
+ */
+export const LEGACY_PROJECT_SPEC_KINDS = ["spunto-lite/project"] as const
+
+export const PROJECT_SPEC_VERSION = 1
+
+const KindSchema = z
+  .string()
+  .refine(
+    (k) => k === PROJECT_SPEC_KIND || (LEGACY_PROJECT_SPEC_KINDS as readonly string[]).includes(k),
+    `Expected "${PROJECT_SPEC_KIND}"`,
+  )
+
+/** A repository cloned into the workspace. `id` is an instance handle — optional in a file. */
+export const SpecRepositorySchema = z.object({
+  id: z.string().optional(),
+  /** `git` = cloned from a raw URL with the project's deploy key, rather than through a forge app. */
+  provider: z.enum(["github", "gitlab", "bitbucket", "git"]),
+  /** `owner/repo`, or a human label for a raw URL. */
+  project: z.string().min(1),
+  /** Directory under `/workspace`. */
+  workspacePath: z.string().min(1),
+  cloneUrl: z.string().optional(),
+  /** Absent/empty = whatever the remote's default is. We do not guess it. */
+  branch: z.string().optional(),
+})
+
+export const SpecFeatureSchema = z.object({
+  id: z.string().min(1),
+  /** Set for a hand-typed OCI ref that is not in the catalog of the instance that exported. */
+  ociRef: z.string().optional(),
+  options: z.record(z.string(), z.string()).optional(),
+})
+
+/** Lite's project-level volume, mounted in every worker of the project. */
+export const SpecSharedVolumeSchema = z.object({
+  name: z.string().min(1),
+  mountPath: z.string().min(1),
+})
+
+export const SpecProjectSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().nullable().optional(),
+  image: z.string().min(1),
+  features: z.array(SpecFeatureSchema).default([]),
+  vscodeExtensions: z.array(z.string()).default([]),
+  prewarmImages: z.array(z.string()).default([]),
+  dind: z.boolean().default(false),
+  postCreateCommand: z.string().nullable().optional(),
+  postStartCommand: z.string().nullable().optional(),
+  repositories: z.array(SpecRepositorySchema).default([]),
+  forwardPorts: z.array(z.number().int().min(1).max(65535)).default([]),
+  /** Names, never values. See the note at the top of this file. */
+  secretNames: z.array(z.string()).default([]),
+
+  // ── Optional, product-specific. Absent is normal; unsupported is not an error. ──
+
+  /** Spunto Lite. A declaration only — the volume is created on first spawn wherever it lands. */
+  sharedVolumes: z.array(SpecSharedVolumeSchema).optional(),
+
+  /** Spunto Cloud — how delegated work runs and reports. Meaningless to a product without tasks. */
+  taskAgentCommand: z.string().optional(),
+  taskAgentProtocol: z.enum(["none", "claude-json", "claude-stream", "jsonl"]).optional(),
+  taskFollowUpCommand: z.string().optional(),
+  taskResetCommand: z.string().optional(),
+  taskValidateCommand: z.string().optional(),
+  taskCancelCommand: z.string().optional(),
+  taskReviewMode: z.enum(["stop", "keep"]).optional(),
+  taskAgentModel: z.string().optional(),
+})
+
+export const ProjectSpecSchema = z.object({
+  kind: KindSchema,
+  version: z.literal(PROJECT_SPEC_VERSION),
+  /** Informational only — nothing reads it back. */
+  exportedAt: z.string().optional(),
+  project: SpecProjectSchema,
+})
+
+export type ProjectSpec = z.infer<typeof ProjectSpecSchema>
+export type SpecProject = z.infer<typeof SpecProjectSchema>
+export type SpecRepository = z.infer<typeof SpecRepositorySchema>
+
+/** Wraps a project in a fresh envelope. Always writes the current kind, never a legacy one. */
+export function buildProjectSpec(project: SpecProject, now: Date = new Date()): ProjectSpec {
+  return {
+    kind: PROJECT_SPEC_KIND,
+    version: PROJECT_SPEC_VERSION,
+    exportedAt: now.toISOString(),
+    project,
+  }
+}
+
+/** Download filename for a project's spec, e.g. `my-app.spunto-project.json`. */
+export function projectSpecFilename(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+  return `${slug || "project"}.spunto-project.json`
+}
+
+/**
+ * Parses the text of an uploaded file into a validated spec.
+ *
+ * Throws an `Error` whose message is safe to put straight in a toast — this runs on a file a human
+ * picked, so "why can't I import this?" has to be answerable without opening a console.
+ */
+export function parseProjectSpec(text: string): ProjectSpec {
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    throw new Error("Not a valid JSON file")
+  }
+  const parsed = ProjectSpecSchema.safeParse(raw)
+  if (parsed.success) return parsed.data
+
+  // A file that at least claims to be a spec deserves to be told what is wrong with it; anything
+  // else is someone importing the wrong file, and the useful answer is which file to look for.
+  const looksLikeSpec = typeof raw === "object" && raw !== null && "kind" in raw
+  throw new Error(
+    looksLikeSpec
+      ? `Unsupported project spec: ${z.prettifyError(parsed.error).split("\n")[0]}`
+      : "Not a Spunto project spec",
+  )
+}