shipbench 0.3.0 → 0.4.0

package/dist/index.js

@@ -4029,6 +4029,8 @@ var CONFIG_PATH2 = ".shipbench/config.json";
 var LAYOUT_PATH2 = ".shipbench/layout.json";
 var UPDATES_HEADING = "## Task Updates";
 var ISO_8601_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+var ATX_HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+var ENTRY_HEADING_TEXT = /^\d{4}-\d{2}-\d{2}/;
 var updatesParseWarnings = /* @__PURE__ */ new WeakMap();
 var ArchiveBlockedError = class extends Error {
   constructor(slug, dependentSlugs) {
@@ -4109,11 +4111,17 @@ function parseTaskBody(rawBody) {
     const outsideFence = fence === null;
     const fenceOnLine = /^\s{0,3}(`{3,}|~{3,})/.test(line);
     if (outsideFence && !fenceOnLine) {
-      const heading = line.match(/^###\s+(.+?)\s*$/);
-      if (heading) {
+      const heading = line.match(ATX_HEADING);
+      if (heading && ENTRY_HEADING_TEXT.test(heading[2])) {
+        if (heading[1].length !== 3) {
+          return malformedUpdates(
+            body,
+            `expected each entry heading to use "### <ISO 8601 timestamp>".`
+          );
+        }
         const previousError = finishComment();
         if (previousError) return malformedUpdates(body, previousError);
-        const nextTimestamp = heading[1];
+        const nextTimestamp = heading[2];
         if (!ISO_8601_TIMESTAMP.test(nextTimestamp) || Number.isNaN(Date.parse(nextTimestamp))) {
           return malformedUpdates(
             body,
@@ -4124,12 +4132,6 @@ function parseTaskBody(rawBody) {
         textLines = [];
         continue;
       }
-      if (/^#{1,6}(?:\s|$)/.test(line)) {
-        return malformedUpdates(
-          body,
-          `expected each entry heading to use "### <ISO 8601 timestamp>".`
-        );
-      }
     }
     if (timestamp === null) {
       if (line.trim()) {
@@ -4163,6 +4165,35 @@ function assertBodyWithoutUpdatesMarker(body) {
     }
     fence = updateFence(line, fence);
   }
+  if (fence) {
+    throw new Error(
+      "Invalid task description: close the code fence this description opens. An open fence runs past the end of the description and hides the Updates section from every read."
+    );
+  }
+}
+function assertCommentTextIsParsable(text) {
+  let fence = null;
+  for (const line of text.split(/\r?\n/)) {
+    if (!fence) {
+      if (line.trimEnd() === UPDATES_HEADING) {
+        throw new Error(
+          `Invalid task update: remove the "${UPDATES_HEADING}" heading \u2014 a second one would leave the section unreadable. Put it in a code fence if the update means it literally.`
+        );
+      }
+      const heading = line.match(ATX_HEADING);
+      if (heading && ENTRY_HEADING_TEXT.test(heading[2])) {
+        throw new Error(
+          `Invalid task update: "${line.trim()}" reads as an entry heading and would split this update in two. Indent it, fence it, or drop the leading "#".`
+        );
+      }
+    }
+    fence = updateFence(line, fence);
+  }
+  if (fence) {
+    throw new Error(
+      "Invalid task update: close the code fence this update opens. An open fence runs past the end of the update and swallows the entries below it."
+    );
+  }
 }
 function parseFrontmatter(fileContent) {
   try {
@@ -4462,6 +4493,7 @@ async function addComment(adapter, config, slug, text) {
   if (!normalizedText) {
     throw new Error("Task update text must not be blank.");
   }
+  assertCommentTextIsParsable(normalizedText);
   const path = `${TASKS_DIR}/${slug}.md`;
   const content = await adapter.readFile(path);
   const task = parseTaskFile(slug, content);
@@ -4497,6 +4529,7 @@ async function editComment(adapter, config, slug, index, text) {
   if (!normalizedText) {
     throw new Error("Task update text must not be blank.");
   }
+  assertCommentTextIsParsable(normalizedText);
   const path = `${TASKS_DIR}/${slug}.md`;
   const content = await adapter.readFile(path);
   const task = parseTaskFile(slug, content);
@@ -4835,6 +4868,8 @@ Write a description with the task instead of after it: \`shipbench task create "
 
 Each task may end with a reserved \`## Task Updates\` section. Use it for time-anchored decisions, pivots, and external events that would lose meaning without their timestamp. Keep timeless facts in the description instead. Append with \`shipbench task comment <slug> "What changed and why."\`, edit text with \`shipbench task comment edit <slug> <index> "Corrected text."\`, or delete with \`shipbench task comment delete <slug> <index>\`. Indices are zero-based. Edits preserve the entry's timestamp; Git preserves earlier text and deleted entries.
 
+Both commands also take \`--body <text>\` and \`--body-file <path>\` in place of the positional text, and \`--body-file\` is the one to reach for when an update runs to several lines: ShipBench reads the file as UTF-8 itself, so the prose never passes through shell quoting or a shell's encoding.
+
 Archived tasks live in \`tasks/archive/\` and are excluded from normal board reads. Archiving moves the file without changing its frontmatter or timestamps; unarchiving restores the same file to \`tasks/\`.
 `;
 }
@@ -4905,7 +4940,11 @@ This heuristic is guidance, not a validation rule. Core stores each entry as \`{
 
 Append through \`shipbench task comment <slug> "What changed and why."\`. Edit text with \`shipbench task comment edit <slug> <index> "Corrected text."\`; delete an entry with \`shipbench task comment delete <slug> <index>\`. Indices are zero-based. Editing never changes the entry's timestamp. Git preserves earlier text and deleted entries.
 
-A description may not contain a \`## Task Updates\` heading of its own \u2014 the next read would file part of it as entries, so ShipBench rejects the write. Put the heading in a code fence when a description means it literally.
+Append and edit both accept \`--body <text>\` or \`--body-file <path>\` instead of the positional text, the same pair \`task create\` and \`task edit\` take. Use \`--body-file\` for anything multi-line: ShipBench reads the file as UTF-8, so the text never passes through shell quoting or encoding.
+
+Update text is prose. Markdown headings inside it are yours to use \u2014 only a column-0 \`### <ISO 8601 timestamp>\` line opens a new entry. Three things are rejected on write, because the next read would mis-file them: a \`## Task Updates\` heading of its own, a column-0 heading whose text is a date, and an unclosed code fence.
+
+A description may not contain a \`## Task Updates\` heading of its own \u2014 the next read would file part of it as entries, so ShipBench rejects the write. It also may not leave a code fence open, which would swallow the marker below it and hide every entry. Put the heading in a code fence when a description means it literally.
 
 Do not hand-edit content below the \`## Task Updates\` marker when the CLI is available.
 
@@ -4994,7 +5033,8 @@ Prefer the ShipBench CLI for task mutations when it is available. The CLI routes
 - **Rewrite a description**: \`shipbench task edit <slug> --body-file=description.md\` (replaces it whole; \`--body ""\` clears it)
 - **Create a dependent task**: \`shipbench task create "Task title" --depends-on=other-slug,another-slug\`
 - **Add a time-anchored update**: \`shipbench task comment <slug> "What changed and why."\`
-- **Edit an update's text**: \`shipbench task comment edit <slug> <index> "Corrected text."\`
+- **Add a multi-line update**: \`shipbench task comment <slug> --body-file update.md\`
+- **Edit an update's text**: \`shipbench task comment edit <slug> <index> "Corrected text."\` (also takes \`--body-file\`)
 - **Delete an update**: \`shipbench task comment delete <slug> <index>\`
 - **Move a task**: \`shipbench task move <slug> --to=in-progress\`
 - **Complete a task**: \`shipbench task move <slug> --to=done\`
@@ -6587,7 +6627,7 @@ async function runTui(options2) {
 }
 
 // src/cli.ts
-var VERSION = true ? "0.3.0" : "0.0.0-dev";
+var VERSION = true ? "0.4.0" : "0.0.0-dev";
 function commaList(value) {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
@@ -6677,10 +6717,9 @@ function formatTaskDependencyGraph(graph) {
   return lines;
 }
 function bodyOption() {
-  return new Option(
-    "--body <text>",
-    "Description as Markdown text"
-  ).conflicts(["bodyFile"]);
+  return new Option("--body <text>", "Description as Markdown text").conflicts([
+    "bodyFile"
+  ]);
 }
 function bodyFileOption() {
   return new Option(
@@ -6688,6 +6727,17 @@ function bodyFileOption() {
     'Read the description from a UTF-8 file; "-" reads stdin'
   ).conflicts(["body"]);
 }
+function updateTextOption() {
+  return new Option("--body <text>", "Update text as Markdown").conflicts([
+    "bodyFile"
+  ]);
+}
+function updateTextFileOption() {
+  return new Option(
+    "--body-file <path>",
+    'Read the update text from a UTF-8 file; "-" reads stdin'
+  ).conflicts(["body"]);
+}
 async function readProcessStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
@@ -6734,7 +6784,17 @@ function createCli(opts) {
       );
     }
   };
-  const program = new Command().name("shipbench").description("Git-native project management for solo developers.").version(VERSION, "-v, --version", "output the version").option(
+  const resolveUpdateText = async (command, positional, raw) => {
+    const fromOption = await resolveBody(raw);
+    if (positional != null && fromOption !== void 0) {
+      command.error(
+        "Pass the update text once: either positionally or with --body / --body-file, not both."
+      );
+      return void 0;
+    }
+    return positional ?? fromOption;
+  };
+  const program = new Command().name("shipbench").description("Git-native project management for solo developers.").enablePositionalOptions().version(VERSION, "-v, --version", "output the version").option(
     "-C <path>",
     "Run as if ShipBench was started in the specified directory"
   );
@@ -6931,19 +6991,30 @@ function createCli(opts) {
       body.trim() ? `Updated description on ${edited.slug}` : `Cleared description on ${edited.slug}`
     );
   });
-  const comment = task.command("comment").description("Manage timestamped entries in the task Updates section").argument("[slug]", "Task slug").argument("[text]", "Update text").action(async (slug, text) => {
-    if (!slug || text === void 0) {
+  const BODY_FILE_HELP = "\nPrefer --body-file for anything multi-line: the file is read as UTF-8 by\nShipBench, so the text never passes through shell quoting or encoding.\n";
+  const commentCommand = task.command("comment").description("Manage timestamped entries in the task Updates section").argument("[slug]", "Task slug").argument("[text]", "Update text").addOption(updateTextOption()).addOption(updateTextFileOption()).addHelpText("after", BODY_FILE_HELP);
+  commentCommand.action(async (slug, text, raw) => {
+    const resolved = await resolveUpdateText(commentCommand, text, raw);
+    if (!slug || resolved === void 0) {
       throw new InvalidArgumentError(
-        "Append requires a task slug and update text."
+        "Append requires a task slug and update text (positional, --body <text>, or --body-file <path>)."
       );
     }
     const config = await loadCliConfig();
-    const updated = await addComment(adapter, config, slug, text);
+    const updated = await addComment(adapter, config, slug, resolved);
     chrome(`Added update to ${updated.slug}`);
   });
-  comment.command("edit <slug> <index> <text>").description(
+  const commentEditCommand = commentCommand.command("edit <slug> <index> [text]").description(
     "Edit an Updates entry by zero-based index without changing its timestamp"
-  ).action(async (slug, index, text) => {
+  ).addOption(updateTextOption()).addOption(updateTextFileOption()).addHelpText("after", BODY_FILE_HELP);
+  commentEditCommand.action(async (slug, index, text, raw) => {
+    const resolved = await resolveUpdateText(commentEditCommand, text, raw);
+    if (resolved === void 0) {
+      commentEditCommand.error(
+        "Provide the replacement text positionally, or with --body <text> or --body-file <path>."
+      );
+      return;
+    }
     const config = await loadCliConfig();
     const parsedIndex = parseNonNegativeInteger(index);
     const updated = await editComment(
@@ -6951,11 +7022,11 @@ function createCli(opts) {
       config,
       slug,
       parsedIndex,
-      text
+      resolved
     );
     chrome(`Edited update ${parsedIndex} on ${updated.slug}`);
   });
-  comment.command("delete <slug> <index>").description("Delete an Updates entry by zero-based index").action(async (slug, index) => {
+  commentCommand.command("delete <slug> <index>").description("Delete an Updates entry by zero-based index").action(async (slug, index) => {
     const config = await loadCliConfig();
     const parsedIndex = parseNonNegativeInteger(index);
     const updated = await deleteComment(adapter, config, slug, parsedIndex);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipbench",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Git-native project management for solo developers. Your task board lives in your repository as Markdown.",
   "license": "MIT",
   "repository": {
@@ -33,14 +33,14 @@
   "dependencies": {
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
-    "@shipbench/board": "0.3.0"
+    "@shipbench/board": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "gray-matter": "^4.0.3",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "@shipbench/core": "0.3.0"
+    "@shipbench/core": "0.4.0"
   },
   "scripts": {
     "build": "tsup",