@spunto/build 0.13.0 → 0.14.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.14.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/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 } : {}) } }
+}