@popoverai/dotrequirements 0.39.4 → 0.39.5

package/dist/commands/solution/create.d.ts

@@ -4,7 +4,9 @@
  * JSON), its title, its description, its plan in the stored shape, and the
  * inputs that already exist. `--description` says what the solution is
  * beyond its title, in Markdown, and wins over the file's. The backend validates the plan and refuses an invalid one
- * with the rules it broke.
+ * with the rules it broke. `--idea` names where the idea is: an image is
+ * read and uploaded first, so the solution is created only once each one
+ * has (PLAN-13).
  */
 export declare function createCommand(file: string | undefined, options?: {
     title?: string;

package/dist/commands/solution/create.js

@@ -2,18 +2,24 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { api } from "../../convex.js";
 import { solutionClient } from "./client.js";
+import { readImage } from "./image.js";
 import { planPayload, readPlanFile } from "./plan-file.js";
 import { parseThing } from "./things.js";
+import { uploadToApp } from "./upload.js";
+const NOT_CREATED = "no solution was created";
 /**
  * `dotreq solution create [file]`: with no file, a solution from the
  * project's default plan, titled with `--title`; with a plan file (YAML or
  * JSON), its title, its description, its plan in the stored shape, and the
  * inputs that already exist. `--description` says what the solution is
  * beyond its title, in Markdown, and wins over the file's. The backend validates the plan and refuses an invalid one
- * with the rules it broke.
+ * with the rules it broke. `--idea` names where the idea is: an image is
+ * read and uploaded first, so the solution is created only once each one
+ * has (PLAN-13).
  */
 export async function createCommand(file, options = {}) {
-    const idea = options.idea?.map(parseThing);
+    const references = options.idea?.map(parseThing);
+    const images = readIdeaImages(references ?? []);
     const described = options.description?.trim() || undefined;
     if (!file) {
         const title = options.title?.trim();
@@ -21,6 +27,7 @@ export async function createCommand(file, options = {}) {
             throw new Error("A solution from the project's default plan needs a title: --title <title>.");
         }
         const client = solutionClient();
+        const idea = await ideaThings(client, references, images);
         const id = await client.mutation(api.solutions.mutations.create, {
             project: client.project,
             title,
@@ -37,6 +44,7 @@ export async function createCommand(file, options = {}) {
         throw new Error(`${file} needs a plan, and a title in the file or as --title (docs/working/plan-surfaces.md).`);
     }
     const client = solutionClient();
+    const idea = await ideaThings(client, references, images);
     const id = await client.mutation(api.solutions.mutations.create, {
         project: client.project,
         title,
@@ -49,4 +57,47 @@ export async function createCommand(file, options = {}) {
     });
     console.log(`Created "${title}": ${id}`);
 }
+/**
+ * Each image the idea names, read and checked before anything is uploaded
+ * or created: a path with no file, a format a browser can't show (PLAN-13.2,
+ * 13.3), or two of one file name, which the solution can't tell apart
+ * (13.4, SIGHT-10).
+ */
+function readIdeaImages(references) {
+    const images = new Map();
+    const named = new Map();
+    for (const thing of references) {
+        if (thing.kind !== "image")
+            continue;
+        const image = readImage(thing.path, NOT_CREATED);
+        const earlier = named.get(image.name);
+        if (earlier !== undefined) {
+            throw new Error(`${earlier} and ${thing.path} are both called ${image.name}, so ${NOT_CREATED}. Rename one of them.`);
+        }
+        named.set(image.name, thing.path);
+        images.set(thing, image);
+    }
+    return images;
+}
+/**
+ * The idea as the backend keeps it, in the order given: each image uploaded
+ * for the project, as a rehearsal's input image is, and kept as its stored
+ * copy's id and name (PLAN-13.0, 13.1). One that doesn't upload stops the
+ * command before the solution is created (13.5).
+ */
+async function ideaThings(client, references, images) {
+    if (!references)
+        return undefined;
+    const idea = [];
+    for (const thing of references) {
+        const image = images.get(thing);
+        if (!image) {
+            idea.push(thing);
+            continue;
+        }
+        const storageId = await uploadToApp(client, api.solutions.images.inputUploadUrl, { project: client.project }, image, `so ${NOT_CREATED}. Run the command again.`);
+        idea.push({ kind: "image", storageId, name: image.name });
+    }
+    return idea;
+}
 //# sourceMappingURL=create.js.map

package/dist/commands/solution/image.d.ts

@@ -27,8 +27,11 @@ export type Image = {
     contentType: ImageContentType;
     bytes: Uint8Array<ArrayBuffer>;
 };
-/** The image at a path, or a refusal naming the accepted formats (SIGHT-9.0.0). */
-export declare function readImage(path: string): Image;
+/**
+ * The image at a path, or a refusal naming the accepted formats
+ * (SIGHT-9.0.0) and what came of it: by default, that nothing was submitted.
+ */
+export declare function readImage(path: string, outcome?: string): Image;
 /** What image format the bytes hold, read from the file's signature. */
 export declare function imageFormat(bytes: Uint8Array): ImageFormat;
 /**

package/dist/commands/solution/image.js

@@ -18,16 +18,19 @@ import { uploadToApp } from "./upload.js";
  * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
  */
 export const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
-/** The image at a path, or a refusal naming the accepted formats (SIGHT-9.0.0). */
-export function readImage(path) {
+/**
+ * The image at a path, or a refusal naming the accepted formats
+ * (SIGHT-9.0.0) and what came of it: by default, that nothing was submitted.
+ */
+export function readImage(path, outcome = "nothing was submitted") {
     const full = resolve(path);
     if (!existsSync(full) || !statSync(full).isFile()) {
-        throw new Error(`There is no file at ${path}, so nothing was submitted.`);
+        throw new Error(`There is no file at ${path}, so ${outcome}.`);
     }
     const bytes = new Uint8Array(readFileSync(full));
     const format = imageFormat(bytes);
     if ("refused" in format) {
-        throw new Error(`${path} isn't an image a browser can show (${format.refused}), so nothing was submitted. Submit ${ACCEPTED_IMAGE_FORMATS}.`);
+        throw new Error(`${path} isn't an image a browser can show (${format.refused}), so ${outcome}. Submit ${ACCEPTED_IMAGE_FORMATS}.`);
     }
     return { name: basename(full), contentType: format.contentType, bytes };
 }

package/dist/commands/solution/index.js

@@ -200,7 +200,7 @@ export function registerSolution(program) {
         .description("Create a solution from the project's default plan, or from a plan file (YAML or JSON: title, plan, inputs)")
         .option("--title <title>", "The solution's title: required without a file, else when the file has none")
         .option("--description <text>", "What the solution is beyond its title, in Markdown: wins over the file's")
-        .option("--idea <reference...>", "Where the idea is written down, for the outcome that makes the solution exist: document:<id>, file:<path>[@<branch>], link:<url>")
+        .option("--idea <reference...>", "Where the idea is written down, for the outcome that makes the solution exist: document:<id>, file:<path>[@<branch>], link:<url>, image:<path>")
         .action(wrap(createCommand));
     whereOptions(solution
         .command("status")

package/dist/commands/solution/upload.d.ts

@@ -12,7 +12,8 @@ export type Upload = {
  * the solution it is for (none for an image a rehearsal gives an input,
  * REHEARSE-4.7), the file POSTed to it with its type, and the stored copy's
  * id back. Convex sets no size
- * limit on these uploads; the POST has two minutes.
+ * limit on these uploads; the POST has two minutes. A failure names the
+ * file, then says what came of it: by default, that nothing was submitted.
  */
 export declare function uploadToApp(client: ReturnType<typeof solutionClient>, uploadUrl: FunctionReference<"mutation">, 
 /** The upload URL endpoint's arguments: the solution, or the project for a rehearsal's input. */
@@ -20,5 +21,5 @@ args: {
     solutionId: string;
 } | {
     project: string;
-}, file: Upload): Promise<string>;
+}, file: Upload, outcome?: string): Promise<string>;
 //# sourceMappingURL=upload.d.ts.map

package/dist/commands/solution/upload.js

@@ -4,23 +4,27 @@
  * the solution it is for (none for an image a rehearsal gives an input,
  * REHEARSE-4.7), the file POSTed to it with its type, and the stored copy's
  * id back. Convex sets no size
- * limit on these uploads; the POST has two minutes.
+ * limit on these uploads; the POST has two minutes. A failure names the
+ * file, then says what came of it: by default, that nothing was submitted.
  */
 export async function uploadToApp(client, uploadUrl, 
 /** The upload URL endpoint's arguments: the solution, or the project for a rehearsal's input. */
-args, file) {
+args, file, outcome = "so nothing was submitted. Submit it again.") {
     const url = await client.mutation(uploadUrl, args);
     const response = await fetch(url, {
         method: "POST",
         headers: { "Content-Type": file.contentType },
         body: file.bytes,
+    }).catch((error) => {
+        // The connection dropped, or never opened.
+        throw new Error(`Uploading ${file.name} failed (${error instanceof Error ? error.message : String(error)}), ${outcome}`);
     });
     if (!response.ok) {
-        throw new Error(`Uploading ${file.name} failed (${response.status} ${response.statusText}), so nothing was submitted. Submit it again.`);
+        throw new Error(`Uploading ${file.name} failed (${response.status} ${response.statusText}), ${outcome}`);
     }
     const { storageId } = (await response.json());
     if (!storageId) {
-        throw new Error(`Uploading ${file.name} returned no id, so nothing was submitted. Submit it again.`);
+        throw new Error(`Uploading ${file.name} returned no id, ${outcome}`);
     }
     return storageId;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.39.4",
+  "version": "0.39.5",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {