shipbench 0.1.1 → 0.3.0

package/dist/index.js

@@ -4153,6 +4153,17 @@ 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);
+  }
+}
 function parseFrontmatter(fileContent) {
   try {
     return (0, import_gray_matter.default)(fileContent);
@@ -4360,7 +4371,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 +4406,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 +4420,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);
@@ -4810,7 +4823,7 @@ Visible order comes from \`config.json\`, the task files, and this partial index
 - The Uncategorized column and the \`done_column\` both ignore \`layout\` entirely.
 - The CLI and Board do not record \`layout[done_column]\`; any existing entry is removed on the next layout write.
 
-Do not read \`layout.json\` alone to determine board order. \`shipbench task list\` returns live tasks in canonical board order, and its JSON output includes each task's zero-based \`position\` within its column. Code clients can apply \`orderedTasksForColumn\` to the task files. Treat the index as machine-managed: do not hand-edit or hand-order it. You may gitignore it if ordering should stay machine-local, but Harbor and fresh clones will then fall back to deterministic \`created\`-descending order for unlisted tasks.
+Do not read \`layout.json\` alone to determine board order. \`shipbench task list --json\` returns live tasks in canonical board order, including each task's zero-based \`position\` within its column. Direct file readers must apply the rules above. Treat the index as machine-managed: do not hand-edit or hand-order it. You may gitignore it if ordering should stay machine-local, but Harbor and fresh clones will then fall back to deterministic \`created\`-descending order for unlisted tasks.
 
 ## Task files
 
@@ -4818,6 +4831,8 @@ 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.
 
 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 +4905,8 @@ 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.
+
 Do not hand-edit content below the \`## Task Updates\` marker when the CLI is available.
 
 ## Choosing What to Work On
@@ -4944,7 +4961,7 @@ Note that \`depends_on\` and the task's column are orthogonal. A column says whe
 
 \`layout.json\` is a partial, machine-managed index, not the visible order. It can omit \`done_column\`, unlisted tasks, and whole columns; retain stale slugs until another layout write; or be absent or gitignored. Reading it alone can therefore give the wrong answer.
 
-\`shipbench task list\` reports live tasks in configured column order and visible within-column order; JSON output includes each task's zero-based \`position\` within its column. Code clients can apply \`orderedTasksForColumn\` to the task files. When working directly with the plain files, combine task statuses with \`config.json\` and the ordering rules in \`README.md\`; do not use \`layout.json\` alone as the answer.
+\`shipbench task list --json\` reports live tasks in configured column order and visible within-column order, including each task's zero-based \`position\` within its column. When working directly with the plain files, combine task statuses with \`config.json\` and the ordering rules in \`README.md\`; do not use \`layout.json\` alone as the answer.
 
 ## Changing Board Order
 
@@ -4973,6 +4990,8 @@ 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."\`
@@ -4994,7 +5013,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 +5023,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 +5376,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 +6587,7 @@ async function runTui(options2) {
 }
 
 // src/cli.ts
-var VERSION = true ? "0.1.1" : "0.0.0-dev";
+var VERSION = true ? "0.3.0" : "0.0.0-dev";
 function commaList(value) {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
@@ -6656,6 +6676,23 @@ 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"]);
+}
+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,6 +6721,19 @@ function createCli(opts) {
   });
   const fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
   const runGit = opts.runGit ?? runGitCommand;
+  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 program = new Command().name("shipbench").description("Git-native project management for solo developers.").version(VERSION, "-v, --version", "output the version").option(
     "-C <path>",
     "Run as if ShipBench was started in the specified directory"
@@ -6802,15 +6852,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,6 +6889,48 @@ function createCli(opts) {
     }
     chrome(`Created task: ${created.slug}`);
   });
+  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 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) {
       throw new InvalidArgumentError(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipbench",
-  "version": "0.1.1",
+  "version": "0.3.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.1.1"
+    "@shipbench/board": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "gray-matter": "^4.0.3",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "@shipbench/core": "0.1.1"
+    "@shipbench/core": "0.3.0"
   },
   "scripts": {
     "build": "tsup",