shipbench 0.2.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()) {
@@ -4153,6 +4155,46 @@ function parseTaskBody(rawBody) {
   }
   return { body: description, comments };
 }
+function assertBodyWithoutUpdatesMarker(body) {
+  let fence = null;
+  for (const line of body.split(/\r?\n/)) {
+    if (!fence && line.trimEnd() === UPDATES_HEADING) {
+      throw new Error(
+        `Invalid task description: remove the "${UPDATES_HEADING}" heading \u2014 that section is written by \`task comment\`. Put the heading in a code fence if the description means it literally.`
+      );
+    }
+    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 {
     return (0, import_gray_matter.default)(fileContent);
@@ -4360,7 +4402,8 @@ function taskFileSlugs(result) {
     ])
   ];
 }
-async function createTask(adapter, config, title, fields) {
+async function createTask(adapter, config, title, fields, body) {
+  if (body !== void 0) assertBodyWithoutUpdatesMarker(body);
   const [existingFiles, archivedFiles] = await Promise.all([
     adapter.listFiles(TASKS_DIR),
     adapter.listFiles(ARCHIVE_DIR)
@@ -4394,7 +4437,7 @@ async function createTask(adapter, config, title, fields) {
       created: now,
       updated: now
     },
-    body: "",
+    body: body ?? "",
     comments: []
   };
   await adapter.writeFile(`${TASKS_DIR}/${slug}.md`, serializeTask(task));
@@ -4408,6 +4451,7 @@ async function createTask(adapter, config, title, fields) {
   return task;
 }
 async function updateTask(adapter, config, slug, fields, body) {
+  if (body !== void 0) assertBodyWithoutUpdatesMarker(body);
   const path = `${TASKS_DIR}/${slug}.md`;
   const content = await adapter.readFile(path);
   const task = parseTaskFile(slug, content);
@@ -4449,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);
@@ -4484,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);
@@ -4818,8 +4864,12 @@ Every file in \`tasks/\` is a Markdown document with a YAML frontmatter block. S
 
 Read the narrowest thing that answers the question. Because each task has a slug, read one task when one task is enough. Use list, search, or archive reads only for broader questions.
 
+Write a description with the task instead of after it: \`shipbench task create "Task title" --body-file description.md\`, and \`shipbench task edit <slug> --body-file revised.md\` to replace one. ShipBench reads the file as UTF-8 itself, so multi-line Markdown never passes through shell quoting or a shell's encoding.
+
 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/\`.
 `;
 }
@@ -4890,6 +4940,12 @@ 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.
 
+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.
 
 ## Choosing What to Work On
@@ -4973,9 +5029,12 @@ Prefer the ShipBench CLI for task mutations when it is available. The CLI routes
 - **Inspect dependencies**: \`shipbench task graph --json\`
 - **Include descriptions in a list**: \`shipbench task list --json --include-body\`
 - **Create a task**: \`shipbench task create "Task title" --status=todo\`
+- **Create a task with a description**: \`shipbench task create "Task title" --body-file=description.md\` (or \`--body "One-line description."\`)
+- **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\`
@@ -4994,7 +5053,7 @@ Use direct edits only when the CLI is unavailable or when changing task descript
 
 - **Create a task**: Add a new \`.md\` file in \`tasks/\` following the format above.
 - **Move a task**: Change the \`status\` field and update the \`updated\` timestamp.
-- **Edit a task**: Modify frontmatter fields and/or the description above \`## Task Updates\`. Always update \`updated\`.
+- **Edit a task**: Modify frontmatter fields and/or the description above \`## Task Updates\`. Always update \`updated\`. The CLI reaches descriptions \u2014 use \`task edit\` rather than rewriting a file by hand.
 - **Add an Update without the CLI**: Append a \`### <ISO 8601 timestamp>\` heading and text below the trailing \`## Task Updates\` marker.
 - **Edit an Update without the CLI**: Change only its text; preserve the \`###\` timestamp heading and update the frontmatter \`updated\` value.
 - **Delete an Update without the CLI**: Remove its heading and text, remove an empty \`## Task Updates\` section, and update the frontmatter \`updated\` value.
@@ -5004,7 +5063,7 @@ Use direct edits only when the CLI is unavailable or when changing task descript
 
 - Never invent status values not listed in \`config.json\`.
 - Reorder tasks only when the user explicitly asks for it.
-- Always update the \`updated\` timestamp when modifying a task.
+- Always update the \`updated\` timestamp when modifying a task by hand. Every CLI mutation maintains it for you.
 - Do not modify \`config.json\` unless explicitly asked.
 - Do not read \`layout.json\` as the visible order or modify it; the CLI and Board own this partial index.
 - Do not read or modify \`tasks/archive/\` unless the user explicitly asks about archived work.
@@ -5357,6 +5416,7 @@ import { statSync } from "fs";
 import { basename, resolve as resolve3 } from "path";
 
 // src/cli.ts
+import { readFile as readFile3 } from "fs/promises";
 import { Command, InvalidArgumentError, Option } from "commander";
 
 // src/boardServer.ts
@@ -6567,7 +6627,7 @@ async function runTui(options2) {
 }
 
 // src/cli.ts
-var VERSION = true ? "0.2.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);
 }
@@ -6656,6 +6716,33 @@ function formatTaskDependencyGraph(graph) {
   }
   return lines;
 }
+function bodyOption() {
+  return new Option("--body <text>", "Description as Markdown text").conflicts([
+    "bodyFile"
+  ]);
+}
+function bodyFileOption() {
+  return new Option(
+    "--body-file <path>",
+    '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));
+  return Buffer.concat(chunks).toString("utf8");
+}
 function enableExitOverride(command) {
   command.exitOverride();
   for (const child of command.commands) enableExitOverride(child);
@@ -6684,7 +6771,30 @@ function createCli(opts) {
   });
   const fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
   const runGit = opts.runGit ?? runGitCommand;
-  const program = new Command().name("shipbench").description("Git-native project management for solo developers.").version(VERSION, "-v, --version", "output the version").option(
+  const readTextFile = opts.readTextFile ?? ((path) => readFile3(path, "utf8"));
+  const readStdin = opts.readStdin ?? readProcessStdin;
+  const resolveBody = async (raw) => {
+    if (raw.bodyFile === void 0) return raw.body;
+    if (raw.bodyFile === "-") return readStdin();
+    try {
+      return await readTextFile(raw.bodyFile);
+    } catch (error) {
+      throw new Error(
+        `Cannot read --body-file "${raw.bodyFile}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  };
+  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"
   );
@@ -6802,15 +6912,25 @@ function createCli(opts) {
     "Slugs this task depends on (comma-separated, repeatable)",
     accumulateCommaList,
     []
-  ).option("--json", "Output the created task as JSON").action(async (title, raw) => {
+  ).addOption(bodyOption()).addOption(bodyFileOption()).option("--json", "Output the created task as JSON").addHelpText(
+    "after",
+    "\nPrefer --body-file for anything multi-line: the file is read as UTF-8 by\nShipBench, so the description never passes through shell quoting or encoding.\n"
+  ).action(async (title, raw) => {
+    const body = await resolveBody(raw);
     const config = await loadCliConfig();
-    const created = await createTask(adapter, config, title, {
-      status: raw.status,
-      assignee: raw.assignee,
-      priority: raw.priority,
-      tags: raw.tags,
-      depends_on: raw.dependsOn
-    });
+    const created = await createTask(
+      adapter,
+      config,
+      title,
+      {
+        status: raw.status,
+        assignee: raw.assignee,
+        priority: raw.priority,
+        tags: raw.tags,
+        depends_on: raw.dependsOn
+      },
+      body
+    );
     if (raw.json) {
       data(
         JSON.stringify(
@@ -6829,19 +6949,72 @@ function createCli(opts) {
     }
     chrome(`Created task: ${created.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 editCommand = task.command("edit <slug>").description("Replace a task's Markdown description").addOption(bodyOption()).addOption(bodyFileOption()).option("--json", "Output the edited task as JSON").addHelpText(
+    "after",
+    "\nThe description is replaced whole and an empty value clears it. The Task\nUpdates section is never touched \u2014 use `shipbench task comment` for those.\n"
+  );
+  editCommand.action(async (slug, raw) => {
+    const body = await resolveBody(raw);
+    if (body === void 0) {
+      editCommand.error(
+        'Provide --body <text> or --body-file <path> (use "-" to read stdin).'
+      );
+      return;
+    }
+    const config = await loadCliConfig();
+    const existing = await getTask(adapter, config, slug);
+    if (!existing) {
+      const archived = await getTask(adapter, config, slug, { archived: true });
+      editCommand.error(
+        archived ? `Task '${slug}' is archived. Unarchive it before editing.` : `Task '${slug}' not found.`
+      );
+      return;
+    }
+    const { task: edited } = await updateTask(adapter, config, slug, {}, body);
+    if (raw.json) {
+      data(
+        JSON.stringify(
+          {
+            slug: edited.slug,
+            status: edited.frontmatter.status,
+            frontmatter: edited.frontmatter,
+            body: edited.body,
+            comments: edited.comments
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    chrome(
+      body.trim() ? `Updated description on ${edited.slug}` : `Cleared description on ${edited.slug}`
+    );
+  });
+  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(
@@ -6849,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.2.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.2.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.2.0"
+    "@shipbench/core": "0.4.0"
   },
   "scripts": {
     "build": "tsup",