@spunto/build 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# `@spunto/build`
+
+The parts of [Spunto](https://spunto.net)'s **Build** pillar that are the same whoever runs the
+control plane — [Spunto Cloud](https://spunto.net) and
+[Spunto Lite](https://github.com/spuntodotnet/spunto-lite) both ship them.
+
+Built on the same idea as [`@spunto/design-system`](https://www.npmjs.com/package/@spunto/design-system),
+one layer down: that package owns what the two products *look* like, this one owns what they *agree
+on*.
+
+```bash
+npm install @spunto/build
+```
+
+## What's in it
+
+### `@spunto/build/steps` — the build-log protocol
+
+A `docker build` for a devcontainer image does a dozen things in one opaque stream. Instead of a new
+channel, the build script prints a marker around each block and the control plane parses it back out
+of the log it already forwards:
+
+```ts
+import { BuildStepTracker, stepStartLine, stepEndLine, type BuildStep } from "@spunto/build/steps"
+
+// …in the script generator, next to the block it brackets:
+const lines = [stepStartLine("feature:node"), installNode(), stepEndLine("feature:node")]
+
+// …in whatever forwards the build log:
+const tracker = new BuildStepTracker(plan)
+const { text, changed } = tracker.ingest(chunk) // markers become banners, steps become live
+```
+
+Also here: `stepMarker` (same bytes, for emitters that aren't a shell), `renderStoredBuildLog`
+(replay a finished build with the same banners), and `EXTENSION_FAILED_MARKER` /
+`parseFailedExtensions` — the second marker, for extensions code-server couldn't install.
+
+### `@spunto/build/extensions` — which registry, and how to ask it
+
+code-server resolves `--install-extension <id>` against **one** registry. If your picker searches a
+different one, users pick extensions the build cannot install. One entry point in front of both
+supported protocols keeps that from happening:
+
+```ts
+import { parseGallery, searchExtensions, codeServerGallery } from "@spunto/build/extensions"
+
+const gallery = parseGallery(rawBlob) // null = Open VSX, the default
+const hits = await searchExtensions(gallery, "prettier")
+const forCodeServer = codeServerGallery(rawBlob) // the same choice, handed to the worker
+```
+
+`parseGallery` takes the operator's raw value from wherever you keep it — a database column, an
+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.
+
+## 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.
+
+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
+the environment — so that one control plane can scope a setting per organization and another per
+process without either shape leaking in here.
+
+That rule is what makes the package testable, safe to import from a node agent as well as from an
+API, and the reason it can't simply be folded into the design system: a script generator needs
+strict, canonical shapes, while the design system deliberately models everything as optional so a UI
+degrades instead of throwing.
+
+## What's deliberately *not* in it
+
+Image script generation (`buildImageScript` & co.), the devcontainer catalogs, the Docker client and
+the terminal bridge — all still duplicated between the two products, all staged for later. The
+reasoning, the measurements and the plan are in
+[RFC 0021](https://github.com/coderhammer/spunto/blob/main/rfc/0021-paquet-partage-build.md).
+
+## Development
+
+```bash
+npm install
+npm test        # vitest
+npm run typecheck
+```
+
+Published to npm from `main` by `.github/workflows/publish-build.yml`; bump the version in
+`package.json` to cut a release.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@spunto/build",
+  "version": "0.1.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",
+  "homepage": "https://spunto.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coderhammer/spunto.git",
+    "directory": "packages/build"
+  },
+  "keywords": [
+    "devcontainer",
+    "code-server",
+    "open-vsx",
+    "docker",
+    "spunto"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./steps": {
+      "types": "./src/steps/index.ts",
+      "import": "./src/steps/index.ts"
+    },
+    "./extensions": {
+      "types": "./src/extensions/index.ts",
+      "import": "./src/extensions/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^4.1.10"
+  }
+}

package/src/extensions/extension-registry.ts

@@ -0,0 +1,164 @@
+// Single entry point for "which registry are extension ids resolved against?".
+//
+// Two protocols are supported and exactly one is active at a time:
+//   - Open VSX (./open-vsx) — the default, and what code-server uses out of the box;
+//   - an `extensionquery` gallery (./gallery-client), selected by an operator-supplied JSON blob.
+//
+// The point of routing everything through here is that the picker's search and the worker's
+// code-server can't disagree: the same blob is what gets handed to code-server (at image-build time
+// and at spawn time) *and* what selects the client below. An extension the UI can find stays an
+// extension the worker can install.
+//
+// **Everything is a parameter.** Nothing is memoized at import time and nothing is read from the
+// environment: every function takes the already-parsed gallery. That is what lets one control plane
+// scope the setting per organization (a database column) and another scope it per process (an
+// environment variable) without either shape leaking in here — each parses its own source once and
+// passes the result down.
+//
+// No gallery is hardcoded and none is special-cased: whatever the operator supplies is the whole
+// configuration.
+
+import * as galleryClient from "./gallery-client"
+import * as openVsx from "./open-vsx"
+import { RegistryError, type ExtensionSuggestion } from "./extensions"
+
+/** The parts of the operator's gallery blob this app reads itself. */
+export type ExtensionGallery = {
+  /** Base of the gallery API — `<serviceUrl>/extensionquery` is what gets queried. */
+  serviceUrl: string
+  /** Human-facing item page, used to build "view on <registry>" links. */
+  itemUrl?: string
+  /** Product scope for galleries hosting several catalogs (see gallery-client). */
+  productTarget?: string
+  /** The blob to hand to code-server, normalized. */
+  forward: string
+}
+
+/** What a UI needs to name the active registry instead of hardcoding "Open VSX". */
+export type ExtensionRegistryInfo = {
+  /** Display name — "Open VSX", or the configured gallery's host. */
+  name: string
+  /** Registry homepage, for "view on <name>" links. */
+  homeUrl?: string
+  /** True when the org configured a gallery, i.e. Open VSX is not in play. */
+  custom: boolean
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() ? v.trim() : undefined
+}
+
+/**
+ * Parses an operator's gallery blob. Anything unusable — not JSON, not an object, no `serviceUrl`
+ * — comes back as `null`, i.e. "Open VSX".
+ *
+ * The fallback is the whole point: a blob we couldn't parse is a blob we'd be searching Open VSX
+ * against, and shipping it to code-server anyway would recreate the exact split-brain this module
+ * exists to prevent. `parseGalleryOrThrow` is the strict variant to validate a write with, so an
+ * unusable value can't reach storage in the first place.
+ */
+export function parseGallery(raw: string | null | undefined): ExtensionGallery | null {
+  try {
+    return parseGalleryOrThrow(raw)
+  } catch (e) {
+    console.warn(`[extensions] Ignoring the configured extension gallery (${(e as Error).message}) — falling back to Open VSX`)
+    return null
+  }
+}
+
+/** Same parse, but throws on an unusable blob — use it to validate what you accept on write. */
+export function parseGalleryOrThrow(raw: string | null | undefined): ExtensionGallery | null {
+  if (!raw || !raw.trim()) return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error("not valid JSON")
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not a JSON object")
+  const obj = parsed as Record<string, unknown>
+  const serviceUrl = str(obj.serviceUrl)?.replace(/\/+$/, "")
+  if (!serviceUrl) throw new Error('missing "serviceUrl"')
+  try {
+    new URL(serviceUrl)
+  } catch {
+    throw new Error('"serviceUrl" is not an absolute URL')
+  }
+  return {
+    serviceUrl,
+    itemUrl: str(obj.itemUrl)?.replace(/\/+$/, ""),
+    productTarget: str(obj.productTarget),
+    // Everything the operator wrote is forwarded, not just the keys above: code-server understands
+    // more of them than we do (cacheUrl, controlUrl, …) and ignores the ones it doesn't.
+    forward: JSON.stringify({ ...obj, serviceUrl }),
+  }
+}
+
+/**
+ * The `EXTENSIONS_GALLERY` value to give code-server, or null to leave it alone (Open VSX). Takes
+ * the raw stored value so callers don't have to parse first.
+ */
+export function codeServerGallery(raw: string | null | undefined): string | null {
+  return parseGallery(raw)?.forward ?? null
+}
+
+/** Names the registry a given gallery (or `null` = the default) stands for. */
+export function registryInfo(gallery: ExtensionGallery | null): ExtensionRegistryInfo {
+  if (!gallery) return { name: "Open VSX", homeUrl: "https://open-vsx.org", custom: false }
+  let name = "the configured gallery"
+  let homeUrl: string | undefined
+  try {
+    const url = new URL(gallery.serviceUrl)
+    name = url.hostname
+    homeUrl = gallery.itemUrl || url.origin
+  } catch {
+    /* a serviceUrl we can't parse still works as a fetch target; it just stays unnamed */
+  }
+  return { name, homeUrl, custom: true }
+}
+
+/** Registry page for one id, for the "view on <registry>" links. */
+export function extensionUrl(gallery: ExtensionGallery | null, id: string): string | undefined {
+  if (!gallery) return `https://open-vsx.org/extension/${id.replace(".", "/")}`
+  return gallery.itemUrl ? `${gallery.itemUrl}?itemName=${encodeURIComponent(id)}` : undefined
+}
+
+/** Re-points registry-agnostic suggestions (ids only) at the active registry. */
+export function withRegistryUrls(gallery: ExtensionGallery | null, suggestions: ExtensionSuggestion[]): ExtensionSuggestion[] {
+  return suggestions.map((s) => ({ ...s, url: extensionUrl(gallery, s.id) }))
+}
+
+/**
+ * Options that only apply to the default (Open VSX) branch — a gallery carries its own endpoint in
+ * the blob, so there is nothing left to configure once one is active.
+ */
+export type RegistryOptions = {
+  /** Base of the Open VSX REST API, for a mirror. Ignored when a gallery is active. */
+  openVsxApiUrl?: string
+}
+
+/** Full-text search against the active registry. Throws `RegistryError` if it's down. */
+export function searchExtensions(
+  gallery: ExtensionGallery | null,
+  query: string,
+  size?: number,
+  opts?: RegistryOptions,
+): Promise<ExtensionSuggestion[]> {
+  return gallery
+    ? galleryClient.searchExtensions(gallery, query, size)
+    : openVsx.searchExtensions(query, size, { apiUrl: opts?.openVsxApiUrl })
+}
+
+/** Exact lookup against the active registry. Null = a real "no such extension". */
+export function lookupExtension(
+  gallery: ExtensionGallery | null,
+  id: string,
+  opts?: RegistryOptions,
+): Promise<ExtensionSuggestion | null> {
+  return gallery
+    ? galleryClient.lookupExtension(gallery, id)
+    : openVsx.lookupExtension(id, { apiUrl: opts?.openVsxApiUrl })
+}
+
+export { RegistryError }
+export type { ExtensionSuggestion }

package/src/extensions/extensions.ts

@@ -0,0 +1,46 @@
+// Pure helpers and types around VS Code extension identifiers. No I/O — safe to import from a
+// validation schema, from a client bundle, or from a script generator (see ./extension-registry for
+// the clients that actually talk to a registry).
+
+/**
+ * Registry call that couldn't be completed (network, timeout, 5xx). Shared by both registry clients
+ * so callers can tell "we couldn't ask" apart from a real "no such extension" verdict, whichever
+ * registry is active. It is an *upstream* failure: surface it as a 503, never a 500.
+ */
+export class RegistryError extends Error {}
+
+/** An extension as a picker shows it — a curated default, or a search hit from either registry. */
+export type ExtensionSuggestion = {
+  /** `publisher.extension-id`, as passed to `code-server --install-extension`. */
+  id: string
+  /** Human-readable name, e.g. "Prettier - Code formatter". */
+  label: string
+  publisher: string
+  description?: string
+  downloads?: number
+  /** Publisher verified by the registry (Open VSX namespace ownership / gallery domain check). */
+  verified?: boolean
+  /** Latest published version, e.g. "11.0.0". */
+  version?: string
+  /** The extension's own icon, when the registry exposes one. */
+  iconUrl?: string
+  /** Registry page, for a "view on <registry>" link. */
+  url?: string
+}
+
+/**
+ * `publisher.extension-name`, the identifier code-server resolves against the registry. Deliberately
+ * permissive on the characters publishers actually use, strict on the shape (exactly one dot).
+ */
+export function parseExtensionId(id: string): { publisher: string; name: string } | null {
+  const m = /^([A-Za-z0-9][A-Za-z0-9._-]*?)\.([A-Za-z0-9][A-Za-z0-9._-]*)$/.exec(id.trim())
+  if (!m) return null
+  const [, publisher, name] = m
+  if (publisher.includes(".")) return null
+  return { publisher, name }
+}
+
+/** Shape check only — says nothing about the id existing on any registry. */
+export function isExtensionId(id: string): boolean {
+  return parseExtensionId(id) !== null
+}

package/src/extensions/gallery-client.ts

@@ -0,0 +1,137 @@
+// Client for a VS Code *extension gallery* — the `extensionquery` protocol code-server switches to
+// when you hand it an `EXTENSIONS_GALLERY` JSON blob.
+//
+// It is nothing like Open VSX's REST API (./open-vsx): a gallery exposes a single
+// `POST <serviceUrl>/extensionquery` endpoint taking a filter/flag document. That's why an Open VSX
+// mirror URL could never double as a gallery setting — the two protocols don't share a single route.
+//
+// Nothing here is specific to any one gallery: the endpoint, the item URLs and the product scope all
+// come from the operator's setting. Only the subset needed to fill an ExtensionSuggestion is
+// implemented — search by text, and exact lookup of `publisher.name`.
+
+import type { ExtensionGallery } from "./extension-registry"
+import { RegistryError, parseExtensionId, type ExtensionSuggestion } from "./extensions"
+
+const TIMEOUT_MS = 8000
+
+/** `criteria[].filterType` values understood by the query endpoint. */
+const FILTER = { ExtensionName: 7, Target: 8, SearchText: 10, ExcludeWithFlags: 12 } as const
+/** `sortBy` / `sortOrder`: most installed first. */
+const SORT_BY_INSTALL_COUNT = 4
+const SORT_ORDER_DESCENDING = 2
+/** IncludeVersions (0x1) | IncludeStatistics (0x100) | IncludeLatestVersionOnly (0x200). */
+const FLAGS = 0x1 | 0x100 | 0x200
+/** ExcludeWithFlags value that drops unpublished entries from the results. */
+const UNPUBLISHED_FLAG = "4096"
+
+type GalleryExtension = {
+  extensionName?: string
+  displayName?: string
+  shortDescription?: string
+  publisher?: { publisherName?: string; displayName?: string; isDomainVerified?: boolean }
+  statistics?: { statisticName?: string; value?: number }[]
+  /** Latest first, since the query asks for the latest version only. */
+  versions?: { version?: string }[]
+}
+
+type QueryResponse = { results?: { extensions?: GalleryExtension[] }[] }
+
+type Criterion = { filterType: number; value: string }
+
+function toSuggestion(gallery: ExtensionGallery, e: GalleryExtension): ExtensionSuggestion | null {
+  const publisher = e.publisher?.publisherName
+  if (!publisher || !e.extensionName) return null
+  const id = `${publisher}.${e.extensionName}`
+  return {
+    id,
+    label: e.displayName || e.extensionName,
+    publisher,
+    description: e.shortDescription || undefined,
+    downloads: e.statistics?.find((s) => s.statisticName === "install")?.value,
+    verified: e.publisher?.isDomainVerified === true,
+    version: e.versions?.[0]?.version,
+    // No `iconUrl`: a gallery only exposes icons behind an asset type whose identifier is
+    // vendor-specific, and this client stays gallery-agnostic. The field is optional and the cards
+    // fall back to a placeholder.
+    url: gallery.itemUrl ? `${gallery.itemUrl}?itemName=${encodeURIComponent(id)}` : undefined,
+  }
+}
+
+async function extensionQuery(
+  gallery: ExtensionGallery,
+  criteria: Criterion[],
+  pageSize: number,
+): Promise<GalleryExtension[]> {
+  const body = {
+    filters: [
+      {
+        criteria: [
+          // Galleries that host more than one product's catalog need to be told which one we want,
+          // or a search for "pipeline" happily returns extensions for IDEs code-server could never
+          // load. Operator-supplied and optional: a single-product gallery doesn't need it.
+          ...(gallery.productTarget ? [{ filterType: FILTER.Target, value: gallery.productTarget }] : []),
+          { filterType: FILTER.ExcludeWithFlags, value: UNPUBLISHED_FLAG },
+          ...criteria,
+        ],
+        pageNumber: 1,
+        pageSize,
+        sortBy: SORT_BY_INSTALL_COUNT,
+        sortOrder: SORT_ORDER_DESCENDING,
+      },
+    ],
+    assetTypes: [],
+    flags: FLAGS,
+  }
+
+  let res: Response
+  try {
+    res = await fetch(`${gallery.serviceUrl}/extensionquery`, {
+      method: "POST",
+      headers: {
+        // The api-version is not optional: without it the gallery answers 400.
+        accept: "application/json;api-version=3.0-preview.1",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    })
+  } catch (e) {
+    throw new RegistryError(`Extension gallery unreachable: ${(e as Error).message}`)
+  }
+  if (!res.ok) throw new RegistryError(`Extension gallery query failed (${res.status})`)
+
+  const payload = (await res.json().catch(() => null)) as QueryResponse | null
+  if (!payload) throw new RegistryError("Extension gallery returned a malformed response")
+  return payload.results?.[0]?.extensions ?? []
+}
+
+/** Full-text search, most installed first. Throws `RegistryError` if the gallery is down. */
+export async function searchExtensions(
+  gallery: ExtensionGallery,
+  query: string,
+  size = 20,
+): Promise<ExtensionSuggestion[]> {
+  const extensions = await extensionQuery(
+    gallery,
+    [{ filterType: FILTER.SearchText, value: query }],
+    Math.min(Math.max(size, 1), 50),
+  )
+  return extensions.map((e) => toSuggestion(gallery, e)).filter((e): e is ExtensionSuggestion => e !== null)
+}
+
+/**
+ * Exact lookup of `publisher.extension-id`.
+ * Returns null when the gallery has no such extension — a real verdict, unlike a `RegistryError`,
+ * which means we simply couldn't ask.
+ */
+export async function lookupExtension(gallery: ExtensionGallery, id: string): Promise<ExtensionSuggestion | null> {
+  if (!parseExtensionId(id)) return null
+  // ExtensionName matches the *full* `publisher.name`, but the endpoint is happy to answer with
+  // near-misses, so the id still has to be checked on the way out.
+  const extensions = await extensionQuery(gallery, [{ filterType: FILTER.ExtensionName, value: id }], 1)
+  for (const e of extensions) {
+    const suggestion = toSuggestion(gallery, e)
+    if (suggestion && suggestion.id.toLowerCase() === id.toLowerCase()) return suggestion
+  }
+  return null
+}

package/src/extensions/index.ts

@@ -0,0 +1,30 @@
+// Resolving VS Code extension ids: which registry answers, and how to ask it.
+//
+// One entry point (`./extension-registry`) sits in front of two protocols — Open VSX and an
+// `extensionquery` gallery — so that the picker's search and the worker's code-server can never end
+// up on different registries. Start at `parseGallery`; everything else takes its result.
+//
+// Nothing here touches a database or an environment variable. The only I/O is outbound HTTP to a
+// public registry, with no platform credential attached — see the package README.
+
+export { isExtensionId, parseExtensionId, RegistryError } from "./extensions"
+export type { ExtensionSuggestion } from "./extensions"
+
+export {
+  codeServerGallery,
+  extensionUrl,
+  lookupExtension,
+  parseGallery,
+  parseGalleryOrThrow,
+  registryInfo,
+  searchExtensions,
+  withRegistryUrls,
+} from "./extension-registry"
+export type { ExtensionGallery, ExtensionRegistryInfo, RegistryOptions } from "./extension-registry"
+
+// The two clients, for a caller that already knows which protocol it wants. `./extension-registry`
+// is the normal way in — reach for these only to bypass the choice deliberately.
+export { DEFAULT_OPEN_VSX_API } from "./open-vsx"
+export type { OpenVsxOptions } from "./open-vsx"
+export * as openVsx from "./open-vsx"
+export * as gallery from "./gallery-client"

package/src/extensions/open-vsx.ts

@@ -0,0 +1,109 @@
+// Open VSX registry client — the registry code-server resolves `--install-extension <id>` against
+// out of the box.
+//
+// Keeping search and install on one registry is the point: an extension the picker can find is an
+// extension the build can install. Which registry that is isn't decided here —
+// ./extension-registry picks between this client and the gallery client depending on the caller's
+// gallery setting, and hands the same choice to code-server so the two can't drift apart.
+//
+// The base URL is a **parameter**, not an environment variable. Both control planes expose the same
+// `OPEN_VSX_API` knob for pointing at a mirror, but each reads its own environment at its own
+// boundary and passes the result down: a package that reached into `process.env` at import time
+// would be untestable, unusable outside Node, and would make the mirror a property of the process
+// rather than of the call.
+
+import { RegistryError, parseExtensionId, type ExtensionSuggestion } from "./extensions"
+
+/** Where an unconfigured caller resolves ids. A mirror is passed per call, see `OpenVsxOptions`. */
+export const DEFAULT_OPEN_VSX_API = "https://open-vsx.org/api"
+
+export type OpenVsxOptions = {
+  /** Base of the Open VSX REST API, for a mirror. Defaults to `DEFAULT_OPEN_VSX_API`. */
+  apiUrl?: string
+}
+
+function apiBase(opts?: OpenVsxOptions): string {
+  return (opts?.apiUrl?.trim() || DEFAULT_OPEN_VSX_API).replace(/\/+$/, "")
+}
+
+const TIMEOUT_MS = 8000
+
+type OpenVsxExtension = {
+  name?: string
+  namespace?: string
+  displayName?: string
+  description?: string
+  downloadCount?: number
+  verified?: boolean
+  deprecated?: boolean
+  version?: string
+  /** `/-/search` flattens the icon here; `/{namespace}/{name}` nests it under `files`. */
+  files?: { icon?: string | null } | null
+}
+
+function toSuggestion(e: OpenVsxExtension): ExtensionSuggestion | null {
+  if (!e.namespace || !e.name) return null
+  return {
+    id: `${e.namespace}.${e.name}`,
+    label: e.displayName || e.name,
+    publisher: e.namespace,
+    description: e.description || undefined,
+    downloads: e.downloadCount,
+    verified: e.verified,
+    version: e.version,
+    // Passed through rather than dropped: the picker's cards draw the real icon, and it's already
+    // in the payload the registry answered with.
+    iconUrl: e.files?.icon ?? undefined,
+    url: `https://open-vsx.org/extension/${e.namespace}/${e.name}`,
+  }
+}
+
+async function registryFetch(path: string, opts?: OpenVsxOptions): Promise<Response> {
+  try {
+    return await fetch(`${apiBase(opts)}${path}`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    })
+  } catch (e) {
+    throw new RegistryError(`Open VSX unreachable: ${(e as Error).message}`)
+  }
+}
+
+/** Full-text search, most downloaded first. Throws `RegistryError` if the registry is down. */
+export async function searchExtensions(
+  query: string,
+  size = 20,
+  opts?: OpenVsxOptions,
+): Promise<ExtensionSuggestion[]> {
+  const params = new URLSearchParams({
+    query,
+    size: String(Math.min(Math.max(size, 1), 50)),
+    sortBy: "downloadCount",
+    sortOrder: "desc",
+    includeAllVersions: "false",
+  })
+  const res = await registryFetch(`/-/search?${params}`, opts)
+  if (!res.ok) throw new RegistryError(`Open VSX search failed (${res.status})`)
+  const body = (await res.json()) as { extensions?: OpenVsxExtension[] }
+  return (body.extensions ?? [])
+    .filter((e) => !e.deprecated)
+    .map(toSuggestion)
+    .filter((e): e is ExtensionSuggestion => e !== null)
+}
+
+/**
+ * Exact lookup of `publisher.extension-id`.
+ * Returns null when the registry answers "no such extension" — a real verdict, unlike a
+ * `RegistryError`, which means we simply couldn't ask.
+ */
+export async function lookupExtension(id: string, opts?: OpenVsxOptions): Promise<ExtensionSuggestion | null> {
+  const parts = parseExtensionId(id)
+  if (!parts) return null
+  const res = await registryFetch(`/${encodeURIComponent(parts.publisher)}/${encodeURIComponent(parts.name)}`, opts)
+  if (res.status === 404) return null
+  if (!res.ok) throw new RegistryError(`Open VSX lookup failed (${res.status})`)
+  const body = (await res.json()) as OpenVsxExtension & { error?: string }
+  // Open VSX answers 200 with an `error` payload for unknown namespaces.
+  if (body.error || !body.namespace || !body.name) return null
+  return toSuggestion(body)
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// @spunto/build — the parts of Spunto's Build pillar that are the same whoever runs the control
+// 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
+// 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"

package/src/steps/build-steps.ts

@@ -0,0 +1,198 @@
+// Image build, seen as a list of blocks instead of a wall of log.
+//
+// A project image build does a lot in one `docker build`: pull the base image, create the user,
+// install code-server, install tmux, install an SSH server, install each devcontainer feature,
+// install each VS Code extension, then bake the DinD seed. The only thing a UI could show without
+// this is the raw log, which tells you *something is happening* but not *what*.
+//
+// The mechanism is deliberately the cheapest one that works end-to-end: the generated build script
+// `echo`es a marker line around each block, and the control plane parses those markers out of the
+// log stream it already forwards. No extra channel, no protocol change on the wire — the "hook" is
+// a line of output. Anything that can print to stdout inside (or beside) the build can therefore
+// declare a step, including code that runs next to `docker build` rather than in it (the DinD seed
+// bake is declared exactly this way).
+//
+// **Why this lives in a package.** A marker is a contract between three programs that cannot import
+// each other: the shell script that emits it, the control plane that parses it, and the UI that
+// renders the result. Spunto Cloud had the emitter in its API and the same literal re-typed by hand
+// in its node agent; Spunto Lite had neither. One copy, here, is what keeps them from drifting.
+//
+// The step *plan* is meant to be built at the same place the script is generated, so the list a UI
+// shows greyed-out upfront can't drift from the blocks the script actually runs. Persist it next to
+// the build and a finished build replays with its blocks and timings, exactly like the live one.
+
+export type BuildStepState = "pending" | "running" | "done" | "error" | "skipped"
+
+/** Drives the icon in the UI — a family of block, not a status. */
+export type BuildStepKind = "image" | "runtime" | "feature" | "extensions" | "finalize"
+
+export type BuildStep = {
+  /** Stable identifier, also what the markers carry (e.g. `code-server`, `feature:node`). */
+  id: string
+  label: string
+  kind: BuildStepKind
+  /** Secondary line: the image ref, the feature's OCI ref, "3 extensions"… */
+  detail?: string
+  state: BuildStepState
+  /** ISO timestamps, stamped by the control plane when the markers are seen. */
+  startedAt?: string
+  completedAt?: string
+}
+
+const MARKER_PREFIX = "::spunto:step:"
+const MARKER_RE = /^::spunto:step:(start|end):(.+?)[ \t]*$/
+
+/** Shell line a build script emits to declare that a block starts. */
+export function stepStartLine(id: string): string {
+  return `echo '${MARKER_PREFIX}start:${id}'`
+}
+
+/** Shell line a build script emits to declare that a block finished successfully. */
+export function stepEndLine(id: string): string {
+  return `echo '${MARKER_PREFIX}end:${id}'`
+}
+
+/** The same two markers, as plain strings — for emitters that aren't shell (the agent). */
+export const stepMarker = {
+  start: (id: string) => `${MARKER_PREFIX}start:${id}\n`,
+  end: (id: string) => `${MARKER_PREFIX}end:${id}\n`,
+}
+
+function durationLabel(step: BuildStep): string {
+  if (!step.startedAt || !step.completedAt) return ""
+  const ms = new Date(step.completedAt).getTime() - new Date(step.startedAt).getTime()
+  if (!(ms > 0)) return ""
+  return ms < 1000 ? ` — ${ms}ms` : ` — ${(ms / 1000).toFixed(1)}s`
+}
+
+/**
+ * What replaces a marker in the terminal. The markers are machine-readable, but the log is still
+ * the thing a human scrolls through when a build fails: turning them into a banner makes the raw
+ * output readable block by block too, instead of leaving a stray `::spunto:step:…` line behind.
+ */
+// Newlines are bare `\n`: the caller is expected to run the text through the same xterm
+// normalisation it already applies to the rest of the log stream, which is what turns them into
+// `\r\n`. Emitting `\r\n` here would double up for callers that normalise.
+function startBanner(step: BuildStep): string {
+  return `\n\x1b[38;5;208m▸\x1b[0m \x1b[1m${step.label}\x1b[0m\n`
+}
+
+function endBanner(step: BuildStep): string {
+  return `\x1b[2m  ✓ ${step.label}${durationLabel(step)}\x1b[0m\n`
+}
+
+/** True when `s` could still grow into a marker — used to decide whether to hold a partial line. */
+function couldBeMarker(s: string): boolean {
+  return s.length > 0 && (MARKER_PREFIX.startsWith(s) || s.startsWith(MARKER_PREFIX))
+}
+
+/**
+ * Consumes a build's log stream, keeps the step list up to date, and hands back the text to show.
+ *
+ * Chunk boundaries are respected: a trailing partial line is only held back when it could still
+ * become a marker, so pull-progress redraws (which carry cursor-control sequences and no marker)
+ * keep flowing through untouched.
+ */
+export class BuildStepTracker {
+  private residual = ""
+
+  constructor(public steps: BuildStep[]) {}
+
+  private find(id: string): BuildStep | undefined {
+    return this.steps.find((s) => s.id === id)
+  }
+
+  /** Feed a raw chunk. Returns the text to forward and whether the step list changed. */
+  ingest(chunk: string, now = new Date()): { text: string; changed: boolean } {
+    const buf = this.residual + chunk
+    const parts = buf.split("\n")
+    this.residual = parts.pop() ?? ""
+
+    let text = ""
+    let changed = false
+
+    for (const rawLine of parts) {
+      const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine
+      const m = MARKER_RE.exec(line)
+      if (!m) {
+        text += rawLine + "\n"
+        continue
+      }
+      const [, kind, id] = m
+      const step = this.find(id)
+      if (!step) continue // unknown id — swallow the marker rather than leak it to the terminal
+      if (kind === "start") {
+        // Starting a block implicitly closes whatever was still running: the agent-side phases
+        // (base image pull) have no end marker of their own, they end when the script speaks.
+        for (const s of this.steps) {
+          if (s !== step && s.state === "running") {
+            s.state = "done"
+            s.completedAt = now.toISOString()
+            text += endBanner(s)
+          }
+        }
+        step.state = "running"
+        step.startedAt = now.toISOString()
+        text += startBanner(step)
+      } else {
+        step.state = "done"
+        step.completedAt = now.toISOString()
+        text += endBanner(step)
+      }
+      changed = true
+    }
+
+    if (this.residual && !couldBeMarker(this.residual)) {
+      text += this.residual
+      this.residual = ""
+    }
+
+    return { text, changed }
+  }
+
+  /**
+   * Close the list when the build itself ends. Success marks everything left as done; a failure
+   * marks the running block as the culprit and everything after it as never-reached.
+   */
+  finish(state: "ready" | "error", now = new Date()): { text: string; changed: boolean } {
+    let text = ""
+    if (this.residual) {
+      text += this.residual
+      this.residual = ""
+    }
+    let changed = false
+    for (const s of this.steps) {
+      if (s.state === "running") {
+        s.state = state === "ready" ? "done" : "error"
+        s.completedAt = now.toISOString()
+        if (state === "ready") text += endBanner(s)
+        changed = true
+      } else if (s.state === "pending") {
+        s.state = state === "ready" ? "done" : "skipped"
+        changed = true
+      }
+    }
+    return { text, changed }
+  }
+}
+
+/**
+ * Re-render a stored log for replay: same banners as the live stream, using the timings already
+ * recorded on the persisted steps. Keeps "watch a build" and "reopen a finished build" identical.
+ */
+export function renderStoredBuildLog(logs: string, steps: BuildStep[] | null | undefined): string {
+  if (!steps || steps.length === 0) return logs.replace(new RegExp(`^${MARKER_PREFIX}.*$\n?`, "gm"), "")
+  const byId = new Map(steps.map((s) => [s.id, s]))
+  return logs
+    .split("\n")
+    .map((rawLine) => {
+      const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine
+      const m = MARKER_RE.exec(line)
+      if (!m) return rawLine
+      const step = byId.get(m[2])
+      if (!step) return null
+      return m[1] === "start" ? startBanner(step).replace(/\n$/, "") : endBanner(step).replace(/\n$/, "")
+    })
+    .filter((l): l is string => l !== null)
+    .join("\n")
+}

package/src/steps/extension-failures.ts

@@ -0,0 +1,35 @@
+// The second marker a build script emits, and the one Spunto Cloud is currently missing.
+//
+// Installing a VS Code extension is a nice-to-have, not a prerequisite: a miss must not fail the
+// build. But "must not fail the build" degenerated into "is never reported" — and code-server does
+// not reliably exit non-zero on an unknown id, so testing `$?` alone lets an
+// `Extension 'x' not found` scroll past as a success. A project ends up running without the
+// extension it was configured with, and nothing anywhere says so.
+//
+// Same shape as `./build-steps`: the script prints a prefixed line, the control plane greps it back
+// out of the log it already stores. `emitExtensionFailure` is the shell-side half,
+// `parseFailedExtensions` the reader. Keeping the two in one file is the point — a marker whose
+// emitter and parser live apart is a marker that breaks silently.
+//
+// Note what this does *not* prescribe: whether to also check that the extension landed on disk,
+// what to write into the image, when to give up. That is the build script's business (see
+// `buildImageScript` in each control plane). This file owns the wire format and nothing else.
+
+/** Prefix every line reporting an extension the build could not install carries. */
+export const EXTENSION_FAILED_MARKER = "[build] EXTENSION FAILED:"
+
+const FAILED_RE = /^\[build\] EXTENSION FAILED: (\S+)/gm
+
+/**
+ * Shell line a build script emits for one extension it failed to install. `id` is interpolated as
+ * written, so pass a literal id or a shell expansion (`"$_ext"`) — never unvalidated user input on
+ * a path that isn't already quoted by the caller.
+ */
+export function extensionFailedLine(id: string, reason?: string): string {
+  return reason ? `${EXTENSION_FAILED_MARKER} ${id} — ${reason}` : `${EXTENSION_FAILED_MARKER} ${id}`
+}
+
+/** Extension ids the given build log reports as failed, in script order, deduplicated. */
+export function parseFailedExtensions(logs: string): string[] {
+  return [...new Set(Array.from(logs.matchAll(FAILED_RE), (m) => m[1]))]
+}

package/src/steps/index.ts

@@ -0,0 +1,16 @@
+// The build-log protocol: what a build script prints so that a control plane can turn a wall of
+// text into a list of blocks, and a list of extensions it failed to install.
+//
+// Nothing here reads a database, opens a socket, or renders anything. Emitters produce strings,
+// parsers consume strings — see the package README for the rule this entry point obeys.
+
+export {
+  BuildStepTracker,
+  renderStoredBuildLog,
+  stepEndLine,
+  stepMarker,
+  stepStartLine,
+} from "./build-steps"
+export type { BuildStep, BuildStepKind, BuildStepState } from "./build-steps"
+
+export { EXTENSION_FAILED_MARKER, extensionFailedLine, parseFailedExtensions } from "./extension-failures"