@spunto/build 0.2.0 → 0.3.0

package/README.md

@@ -75,11 +75,43 @@ paths a worker and its control plane agree on — `WORKER_STATUS_FILE` / `worker
 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.2.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",
@@ -38,6 +38,10 @@
     "./naming": {
       "types": "./src/naming/index.ts",
       "import": "./src/naming/index.ts"
+    },
+    "./spec": {
+      "types": "./src/spec/index.ts",
+      "import": "./src/spec/index.ts"
     }
   },
   "files": [
@@ -52,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,9 +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

@@ -29,7 +29,13 @@ export function workerNetworkName(workerId: string): string {
   return `mp-worker-${workerId}-net`
 }
 
-/** The named volumes a worker owns, and what each holds. */
+/**
+ * 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]
 
@@ -92,10 +98,20 @@ export function workerStatusPath(home: string): string {
 export const EXTENSIONS_DIR = "/opt/mp-extensions"
 
 /**
- * Directory of executables a devcontainer feature can drop to have them run at container start.
- * The devcontainer `entrypoint` contract, implemented on our side.
+ * **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_DIR = "/etc/mp-feature-entrypoints"
+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

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",
+  )
+}