@spunto/build 0.13.0 → 0.15.0

package/README.md

@@ -104,6 +104,22 @@ 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.
 
+**The project's prompt is a file of its own.** `taskAgentInstructions` is prose, and a JSON string
+is the worst place to read it. A spec may instead point at a sibling file
+(`taskAgentInstructionsFile: "prompt.md"`); a **bundle** is the spec plus what it points at, as a
+plain name → text map — zipping it, or picking both files at once, is the product's job.
+
+```ts
+import { buildProjectBundle, parseProjectBundle, projectBundleFilename } from "@spunto/build/spec"
+
+const files = buildProjectBundle(project)  // { "my-app.spunto-project.json": …, "prompt.md": … }
+const spec = parseProjectBundle(files)      // prompt back inline, as taskAgentInstructions
+```
+
+A project without a prompt is a one-file bundle whose spec is what `buildProjectSpec` writes, and a
+lone spec is a valid bundle — so every file exported before bundles existed imports as before. The
+inline `taskAgentInstructions` stays accepted too (it is what a single-JSON export writes).
+
 ### `@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",

package/src/script/setup-script.ts

@@ -103,6 +103,16 @@ type CloneRepo = {
   branch?: string
 }
 
+/**
+ * How a feature's entrypoint is started: without the OpenTelemetry variables the platform gives the
+ * workload. An entrypoint is infrastructure — dockerd, containerd — and Docker instruments itself as
+ * soon as `OTEL_EXPORTER_OTLP_ENDPOINT` exists: every internal gRPC call of a docker-in-docker
+ * daemon became a span (~60 000 per quarter hour for three sandboxes, 2026-10-18), drowning the
+ * project's own services in its organization's telemetry. The project's processes keep them.
+ */
+export const ENTRYPOINT_WITHOUT_OTEL =
+  "env -u OTEL_EXPORTER_OTLP_ENDPOINT -u OTEL_EXPORTER_OTLP_TRACES_ENDPOINT -u OTEL_EXPORTER_OTLP_METRICS_ENDPOINT -u OTEL_EXPORTER_OTLP_LOGS_ENDPOINT -u OTEL_EXPORTER_OTLP_PROTOCOL -u OTEL_EXPORTER_OTLP_HEADERS -u OTEL_RESOURCE_ATTRIBUTES -u OTEL_SERVICE_NAME"
+
 /**
  * Branch actually checked out for a repo: the worker-level choice (made at creation, applies to
  * every repo of the project) wins over the project-level default carried by the repository itself.
@@ -1140,7 +1150,7 @@ export function buildSetupScript(params: SetupScriptParams): { script: string }
       "  while IFS= read -r _ep; do",
       '    if [ -f "$_ep" ]; then',
       '      echo "Starting entrypoint: $_ep"',
-      '      "$_ep" &',
+      '      ' + ENTRYPOINT_WITHOUT_OTEL + ' "$_ep" &',
       "    fi",
       "  done < " + FEATURE_ENTRYPOINTS_FILE,
       "fi",
@@ -1306,7 +1316,7 @@ export function buildStartScript(params: StartScriptParams): { script: string; h
     "  while IFS= read -r _ep; do",
     '    if [ -f "$_ep" ]; then',
     '      echo "Starting entrypoint: $_ep"',
-    '      "$_ep" &',
+    '      ' + ENTRYPOINT_WITHOUT_OTEL + ' "$_ep" &',
     "    fi",
     "  done < " + FEATURE_ENTRYPOINTS_FILE,
     "fi",
@@ -1559,7 +1569,7 @@ export function buildContainerScript(params: StartScriptParams): { script: strin
     "  while IFS= read -r _ep; do",
     '    if [ -f "$_ep" ]; then',
     '      echo "Starting entrypoint: $_ep"',
-    '      "$_ep" &',
+    '      ' + ENTRYPOINT_WITHOUT_OTEL + ' "$_ep" &',
     "    fi",
     "  done < " + FEATURE_ENTRYPOINTS_FILE,
     "fi",

package/src/spec/index.ts

@@ -24,6 +24,15 @@
 // 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.
+//
+// **The prompt is a file of its own.** A project's agent prompt (`taskAgentInstructions`) is
+// prose — paragraphs, lists, code fences — and a JSON string is the worst place to read or edit
+// it. So a spec may *point* at it (`taskAgentInstructionsFile: "prompt.md"`) instead of holding it,
+// and a **bundle** is the spec plus the files it points at (`buildProjectBundle` /
+// `parseProjectBundle`). The bundle is a plain name → text map: how it is carried (a zip, two
+// files picked together, a folder in a repo) is the product's business, not this package's. The
+// inline form stays valid — it is what a single-file export writes, and every file written
+// before the pointer existed is a file with no prompt at all.
 
 import { z } from "zod"
 
@@ -102,6 +111,13 @@ export const SpecProjectSchema = z.object({
   taskCancelCommand: z.string().optional(),
   taskReviewMode: z.enum(["stop", "keep"]).optional(),
   taskAgentModel: z.string().optional(),
+  /** Spunto Cloud — what the project's task agents are told on top of the org's instruction. */
+  taskAgentInstructions: z.string().optional(),
+  /**
+   * The same prompt, as a sibling file of the bundle (`prompt.md`) rather than a string here.
+   * Resolved by `parseProjectBundle`; `parseProjectSpec` alone leaves it as a name.
+   */
+  taskAgentInstructionsFile: z.string().min(1).optional(),
 })
 
 export const ProjectSpecSchema = z.object({
@@ -160,3 +176,74 @@ export function parseProjectSpec(text: string): ProjectSpec {
       : "Not a Spunto project spec",
   )
 }
+
+/** Name of the prompt file in a bundle written by `buildProjectBundle`. */
+export const PROJECT_PROMPT_FILENAME = "prompt.md"
+
+/** A spec and the files it points at, by name. Text only — a bundle carries no binaries. */
+export type ProjectBundle = Record<string, string>
+
+/** Download filename for a project's bundle once zipped, e.g. `my-app.spunto-project.zip`. */
+export function projectBundleFilename(name: string): string {
+  return projectSpecFilename(name).replace(/\.json$/, ".zip")
+}
+
+/**
+ * The project as a bundle: its spec, plus the prompt as `prompt.md` when it has one.
+ *
+ * A project without a prompt is a one-file bundle whose spec is byte-for-byte what
+ * `buildProjectSpec` would have written — nothing changes for a reader that only knows the JSON.
+ */
+export function buildProjectBundle(project: SpecProject, now: Date = new Date()): ProjectBundle {
+  const { taskAgentInstructions, taskAgentInstructionsFile: _ignored, ...rest } = project
+  const specName = projectSpecFilename(project.name)
+  if (!taskAgentInstructions) return { [specName]: JSON.stringify(buildProjectSpec(rest, now), null, 2) + "\n" }
+  const spec = buildProjectSpec({ ...rest, taskAgentInstructionsFile: PROJECT_PROMPT_FILENAME }, now)
+  return {
+    [specName]: JSON.stringify(spec, null, 2) + "\n",
+    // A trailing newline, like any text file an editor saves; `parseProjectBundle` trims it back.
+    [PROJECT_PROMPT_FILENAME]: taskAgentInstructions.endsWith("\n") ? taskAgentInstructions : taskAgentInstructions + "\n",
+  }
+}
+
+/** `./prompt.md`, `dir/prompt.md` (a zip made from a folder) and `prompt.md` are the same file. */
+function bundleKey(path: string): string {
+  return path.replace(/\\/g, "/").split("/").filter((s) => s && s !== ".").pop() ?? ""
+}
+
+/**
+ * Reads a bundle back into a spec whose prompt, if any, is inline (`taskAgentInstructions`) and
+ * whose `taskAgentInstructionsFile` is gone — the shape a product creates a project from.
+ *
+ * The spec is the bundle's one `.json` file (a `*.spunto-project.json` wins if there are several);
+ * a lone spec is a valid bundle, which is what makes every file exported before bundles existed
+ * import exactly as before. Files are matched by base name, so a zip of a folder works too.
+ *
+ * Throws messages written for a toast, like `parseProjectSpec`.
+ */
+export function parseProjectBundle(bundle: ProjectBundle): ProjectSpec {
+  const files = new Map<string, string>()
+  for (const [path, text] of Object.entries(bundle)) {
+    const key = bundleKey(path)
+    // macOS archives carry `__MACOSX/._x` shadows of every file; they are never what was meant.
+    if (key && !key.startsWith("._") && !path.includes("__MACOSX")) files.set(key, text)
+  }
+
+  const jsons = [...files.keys()].filter((k) => k.toLowerCase().endsWith(".json"))
+  const preferred = jsons.filter((k) => k.toLowerCase().endsWith(".spunto-project.json"))
+  const candidates = preferred.length ? preferred : jsons
+  if (candidates.length === 0) throw new Error("No project spec (.json) in what was imported")
+  if (candidates.length > 1) throw new Error(`Several project specs to choose from: ${candidates.join(", ")}`)
+
+  const spec = parseProjectSpec(files.get(candidates[0])!)
+  const { taskAgentInstructionsFile: ref, ...project } = spec.project
+  if (!ref) return spec
+
+  const text = files.get(bundleKey(ref))
+  if (text === undefined) {
+    throw new Error(`The spec's prompt is in ${ref}, which was not imported with it — pick both files, or the .zip`)
+  }
+  // The file wins over an inline copy: it is the one a human edits.
+  const prompt = text.replace(/\s+$/, "")
+  return { ...spec, project: { ...project, ...(prompt ? { taskAgentInstructions: prompt } : {}) } }
+}