@spunto/build 0.3.0 → 0.4.0

package/README.md

@@ -102,6 +102,52 @@ fields it has no feature for** — shared volumes are a Lite concept, the task s
 both optional. Dropping a field the target cannot honour is the correct outcome; refusing the file
 is not.
 
+### `@spunto/build/script` — turning a project spec into the shell a worker runs
+
+Four generators, one recipe: `buildImageScript` bakes the project image, `buildSetupScript` is the
+first boot, `buildStartScript` is every boot, `buildWorkerScript` assembles the container CMD.
+
+```ts
+import { buildImageScript, IMAGE_RECIPE_VERSION } from "@spunto/build/script"
+
+const { script, steps, hasDinD } = buildImageScript({ features, vscodeExtensions })
+```
+
+No filesystem, no clock: the one install script the platform ships itself is embedded as a string
+(`local-features.ts`), and every path a generated script writes to comes from `./naming` rather
+than a literal.
+
+`buildContainerScript` and `buildSetupPlan` are shaped by one product's model — an agent that
+orchestrates setup phase by phase instead of a container running one long CMD. They live here
+because they share every helper in the file; splitting them out would fork the helpers, which is
+the duplication this package exists to remove.
+
+### `@spunto/build/catalogs` — what a project picker offers
+
+`AVAILABLE_IMAGES`, `AVAILABLE_FEATURES`, `SUGGESTED_EXTENSIONS`. Data, but shared data: the two
+hand-maintained copies had already drifted, one of them advertising Oh My Zsh in a feature the
+image recipe explicitly disables.
+
+Project *templates* are deliberately absent — one product's clone a starter repository and carry
+onboarding-gallery presentation, the other's only configure an environment. They answer different
+questions.
+
+### `@spunto/build/types` — the shapes both schemas point at
+
+`ProjectFeature`, `Repository`, `SetupStatus`. Declared here so each product's ORM can point its
+JSON columns at them with `$type<…>()`, instead of a generator having to import a database schema.
+`SetupStatus` is what a shell script writes into a container and a control plane reads back minutes
+later: changing it is a migration, not an edit.
+
+### `@spunto/build/agent-stream` — reading an agent session as it happens
+
+One adapter per harness dialect, one vocabulary out. A CLI's JSON output is an output format, not
+an API; adapters normalise into a small set of event types so stored history doesn't date the first
+time a vendor reshuffles a field.
+
+Here for the reason that inverts the rest of the package: **nothing has forked this yet.** Putting
+it in the shared package now costs nothing and means the second product never writes its own.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**
@@ -110,7 +156,11 @@ React, **no** `process.env`, and knows **nothing** about organizations, users or
 `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.
+zod is the one used — which matters, since apps extend these schemas with their own. And an
+**optional** one, because a peer applies to the whole package while only `./spec` needs it: a
+consumer that imports `./naming` or `./steps` and nothing else should not have a schema library
+installed on its behalf. Import `./spec` without zod and resolution fails loudly, which is the
+right trade for not taxing every other entry point.
 
 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -31,22 +31,39 @@
       "types": "./src/steps/index.ts",
       "import": "./src/steps/index.ts"
     },
-    "./extensions": {
-      "types": "./src/extensions/index.ts",
-      "import": "./src/extensions/index.ts"
-    },
     "./naming": {
       "types": "./src/naming/index.ts",
       "import": "./src/naming/index.ts"
     },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "import": "./src/types/index.ts"
+    },
+    "./catalogs": {
+      "types": "./src/catalogs/index.ts",
+      "import": "./src/catalogs/index.ts"
+    },
+    "./extensions": {
+      "types": "./src/extensions/index.ts",
+      "import": "./src/extensions/index.ts"
+    },
     "./spec": {
       "types": "./src/spec/index.ts",
       "import": "./src/spec/index.ts"
+    },
+    "./script": {
+      "types": "./src/script/index.ts",
+      "import": "./src/script/index.ts"
+    },
+    "./agent-stream": {
+      "types": "./src/agent-stream/index.ts",
+      "import": "./src/agent-stream/index.ts"
     }
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
     "README.md"
   ],
   "scripts": {
@@ -61,5 +78,10 @@
   },
   "peerDependencies": {
     "zod": "^4"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   }
 }