@dennisrongo/dsh-todo 0.4.0 → 0.5.0

package/README.md

@@ -31,15 +31,23 @@ next to the code it describes.
   standup actually asks about: what is moving, and what is stuck.
 - **Priority** — `P0`–`P3`, shown as a chip. Only P0/P1 are coloured, so the
   list flags what is urgent instead of turning into a rainbow.
-- **Release and sprint** — two independent labels: what ships together
-  (`v1.2.0`) and when it is worked (`Sprint 24`). A task can be in both.
+- **Release and sprint** — two independent numeric labels: what ships
+  together (`1.5`, `0.5.1`) and when it is worked (`24`). A task can be in
+  both. A **release** takes up to three numbers, so a patch release has a label
+  of its own; a **sprint** is a single decimal. Never alpha (`v1.5` is
+  refused), so labels sort by version — `1.10` above `1.9`, `0.5.1` above
+  `0.5`. The inputs accept only digits and a dot as you type; a value that is
+  still not a valid label is flagged with an inline error and never saved.
 - **Group by** — None · Status · Release · Sprint · Priority, with collapsible
   section headers carrying their own `done/total` and progress bar. Grouping by
   status gives you a kanban board without drag-and-drop.
 - **Task detail modal** — click a task's title to open the full dialog: a
   roomy description box plus status, priority, release, sprint and due date.
-  Esc or the backdrop closes it, focus is trapped inside and returned to the row
-  you came from, and edits commit on close so a stray click never loses them.
+  Focus is trapped inside and returned to the row you came from, and text edits
+  commit on close so a stray click never loses them. **Done is the save**: it is
+  the only control that refuses to proceed while a release or sprint is invalid.
+  Esc, the backdrop and the X always let you out, discarding an unsaved bad
+  label rather than trapping you in the dialog.
 - **Expandable rows** — the chevron still gives a quick in-row peek without
   leaving the list. Double-click a title to rename it inline. One scannable line
   collapsed is what lets a task carry nine fields without becoming a wall of text.
@@ -55,8 +63,14 @@ next to the code it describes.
   restored (↩) or permanently deleted from the Archive view.
 - **Full editing** — add, check off, click-to-edit the title, edit the
   description and labels, reorder (▲/▼), archive, and delete. Release and sprint
-  inputs suggest labels already in use, so free text converges on a shared
+  inputs suggest labels already in use, so values converge on a shared
   vocabulary without a releases table to administer.
+- **Suggest** — a button in the tab header scans the workspace and proposes
+  concrete next tasks: unresolved `TODO`/`FIXME`/`HACK` comments, features the
+  docs promise but the code does not implement, and modules with no tests. Each
+  proposal comes with a one-line rationale, a priority, and a `file:line`
+  pointer where one exists. Tick the ones you want and **Add selected** files
+  them into the backlog. Never automatic — it runs only when you click it.
 - **Themed** — colors come only from the shell's `--dsw-*` tokens, so it follows
   light/dark automatically. Respects `prefers-reduced-motion`.
 
@@ -101,12 +115,27 @@ dsh profiles set `autoInstallPeers: false`, so this resolves correctly.
 pnpm install
 pnpm run build      # node build/build.mjs — emits lib/index.js + lib/client.js
 pnpm run typecheck  # tsc --noEmit
-pnpm test           # node test/smoke.mjs — offline, exercises the BUILT lib/ output
-pnpm run test:icons # headless Chrome: icon sizes and the 40px row budget
-pnpm run test:modal # headless Chrome: the dialog escapes the list's scroll container
+pnpm test                # offline: client + CLI, exercising the BUILT lib/ output
+pnpm run test:cli        # just the in-process CLI suite
+pnpm run test:integration # spawns the real bin — one full agent workflow
+pnpm run test:icons      # headless Chrome: icon sizes and the 40px row budget
+pnpm run test:modal      # headless Chrome: the dialog escapes the list's scroll container
+pnpm run test:agent      # OPT-IN: a real model drives the CLI (needs a key; costs tokens)
 ```
 
-`pnpm test` asserts against `lib/`, so **build before testing**.
+`pnpm test` asserts against `lib/`, so **build before testing** (the script rebuilds first).
+
+The CLI has two layers on purpose. `test/cli.test.mjs` calls into `lib/cli.js` in-process;
+`test/cli-integration.mjs` **spawns the real binary** for one realistic agent workflow — plan a
+release, inspect it, hit a refusal, recover from the payload alone, finish and archive — because
+the in-process suite cannot see the shebang'd entry point, `process.exitCode`, the stdout/stderr
+split, or argv as a shell delivers it.
+
+`pnpm run test:agent` is the odd one out and is **not** part of `pnpm test`: it hands a real
+model nothing but the binary path and a goal, then asserts on the resulting database rather than
+on anything the model said. It answers a question no offline test can — is `help` enough to
+drive this thing, and is a refusal message enough to recover from? It needs `DEEPSEEK_API_KEY`
+exported (it runs the harness in a throwaway `DSH_HOME`, which has no stored credentials).
 
 ## Install into a dsh profile
 
@@ -156,6 +185,46 @@ swallow a move.
 `clearCompleted` (hard delete of done items) is still exported for callers that
 want it, but it is no longer wired to a button.
 
+## Suggest — what to work on next
+
+The list holds work someone already thought of. Deciding what to do *next*
+usually happens somewhere else — reading the code and noticing what is missing.
+**Suggest**, in the tab header, moves that into the tab.
+
+Clicking it reads the workspace and proposes concrete tasks from three kinds of
+evidence:
+
+- **Unresolved comments** — `TODO`, `FIXME` and `HACK`, with the file and line.
+- **Docs-vs-implementation gaps** — the README and the file tree together, so
+  what is promised but absent has somewhere to show up.
+- **Untested modules** — source files with no matching test file. A name-based
+  hint rather than a coverage run, so it is offered as a hint.
+
+Each suggestion arrives as a checkbox row: a title, a one-line rationale, a
+priority, and a `file:line` pointer where there is one to give. Nothing is
+ticked by default — you opted into scanning, not into the results. **Add
+selected** writes the ticked rows into the backlog as real tasks, with the
+rationale as the description. Until then they are **proposals**: nothing is
+stored, and closing the dialog discards them.
+
+**Refresh returns genuinely new ideas, not a reshuffle.** Every title already
+shown joins the exclusion set, alongside every unfinished task already in the
+backlog, so the scan is told what not to repeat. Rows you have already ticked
+survive a refresh — the selection is yours, not the model's.
+
+> **A scan spends tokens.** It runs a real model session in the background —
+> created, prompted, and archived when the scan finishes or you close the
+> dialog; it never appears in the sidebar and is never navigated to. Nothing is
+> scheduled and nothing is automatic: a scan happens when you click **Suggest**
+> or **Refresh**, and only then.
+
+What is sent is a **bounded digest**, not the repository: a capped file tree, a
+capped list of comment matches one line each, and a leading slice of the README
+and `package.json`. Vendored and generated directories (`node_modules`, `lib`,
+`dist`, `vendor`, `target` and the rest) never enter it. Anything left out is
+marked in the digest rather than dropped quietly, so a big repository yields a
+smaller scan rather than a confident one about code it never read.
+
 ## CLI — for you and for AI agents
 
 The same list is reachable from a terminal, so an agent can shell out and manage your tasks
@@ -181,14 +250,14 @@ experimental-feature warning on stderr; it is harmless, and `2>/dev/null` silenc
 ```bash
 cd ~/projects/my-app          # the workspace IS the current directory
 
-dsh-todo add "Fix token refresh" --priority p0 --release v1.2.0 --due 2026-03-14
-dsh-todo add "Write migration guide" --sprint "Sprint 24"
+dsh-todo add "Fix token refresh" --priority p0 --release 1.5 --due 2026-03-14
+dsh-todo add "Write migration guide" --sprint 24
 dsh-todo list
 ```
 
 ```text
-[ ] tmtcfbutukp4j todo        p0 Fix token refresh  (release=v1.2.0 due=2026-03-14)
-[ ] tmtcfbuxr5y9x todo        p2 Write migration guide  (sprint=Sprint 24)
+[ ] tmtcfbutukp4j todo        p0 Fix token refresh  (release=1.5 due=2026-03-14)
+[ ] tmtcfbuxr5y9x todo        p2 Write migration guide  (sprint=24)
 [ ] tmtcfbv071e6w in-progress p2 Ship it
 ```
 
@@ -198,7 +267,7 @@ That is the whole display contract — it stays greppable and diffable.
 Move work along, then file it away:
 
 ```bash
-dsh-todo update tmtcfbut --status in-progress --sprint "Sprint 24"
+dsh-todo update tmtcfbut --status in-progress --sprint 24
 dsh-todo show tmtcfbut                  # everything about one task
 dsh-todo done tmtcfbut
 dsh-todo archive                        # archive EVERY completed task
@@ -231,15 +300,15 @@ dsh-todo --workspace ~/projects/other list --open
 | `--json` | all | Machine-readable output, **including on errors** |
 | `--status <s>` | add, update, list | `backlog` · `todo` · `in-progress` · `blocked` · `done` |
 | `--priority <p>` | add, update, list | `p0`–`p3` (default `p2`) |
-| `--release <label>` | add, update, list | e.g. `v1.2.0` |
-| `--sprint <label>` | add, update, list | e.g. `"Sprint 24"` |
+| `--release <n[.n[.n]]>` | add, update, list | Numbers only, up to three: `1`, `1.5`, `0.5.1`; `v1.5` is refused |
+| `--sprint <n[.n]>` | add, update, list | Numbers only, one dot at most: `24`, `1.5`; `0.5.1` is refused |
 | `--due <YYYY-MM-DD>` | add, update | A calendar day; impossible dates are refused |
 | `--description <text>` | add, update | Body text — acceptance criteria, repro steps |
 | `--title <text>` | update | Rename |
 | `--open` | list | Everything unfinished, whatever stage |
 | `--archived` | list | Show archived tasks *instead of* active ones |
 
-Filters combine, so `list --open --priority p0 --release v1.2.0` is an AND across all three.
+Filters combine, so `list --open --priority p0 --release 1.5` is an AND across all three.
 `--key value` and `--key=value` are both accepted.
 
 ### Driving it from a script or an agent
@@ -253,6 +322,7 @@ dsh-todo list --open --json
 
 ```json
 {
+  "ok": true,
   "count": 3,
   "items": [
     {
@@ -260,7 +330,7 @@ dsh-todo list --open --json
       "title": "Fix token refresh",
       "status": "todo",
       "priority": "p0",
-      "release": "v1.2.0",
+      "release": "1.5",
       "dueDate": "2026-03-14",
       "createdAt": 1787889639378
     }
@@ -268,19 +338,41 @@ dsh-todo list --open --json
 }
 ```
 
-`list` returns `{ count, items }`; `add` / `update` / `done` / `reopen` / `rm` return
-`{ item, revision }`; `archive` returns `{ archived, revision }`; `show` returns the task
-itself. A failure returns `{ error, code }` and exits with that code:
+**Every payload leads with `ok`**, so a caller never has to infer the verdict from the
+shape of what came back. On success `ok` is `true` and the command's own keys follow:
+`list` adds `{ count, items }`; `add` / `update` / `done` / `reopen` / `rm` add
+`{ item, revision }` — the stored task, so a write can be confirmed without a second
+call; `archive` adds `{ archived, revision }`; `show` adds the task itself.
+
+A failure returns `ok: false` with `error` and `code`, and exits with that code:
 
 ```bash
 $ dsh-todo update nope --status done --json; echo "exit=$?"
 {
+  "ok": false,
   "error": "no task matching \"nope\"",
   "code": 3
 }
 exit=3
 ```
 
+A **refused value** says which field it refused, what that field accepts, and what it was
+given — enough for an agent to correct itself without parsing the sentence. Nothing is
+written when a value is refused:
+
+```bash
+$ dsh-todo add "Ship it" --release v1.5 --json; echo "exit=$?"
+{
+  "ok": false,
+  "error": "--release must be a version number like 1.5 or 0.5.1 (up to three numbers) (got \"v1.5\") — nothing was saved",
+  "code": 2,
+  "field": "release",
+  "expected": "a version number like 1.5 or 0.5.1 (up to three numbers)",
+  "got": "v1.5"
+}
+exit=2
+```
+
 Exit codes are distinct so a script can branch on **why** a command failed:
 
 | Code | Means |
@@ -338,15 +430,29 @@ list. That is the designed reconciliation, not lost data.
 | `description` | The body: acceptance criteria, repro steps, links. Its own 5000 cap, because reusing the title's 500 would silently truncate real notes. |
 | `status` | `backlog \| todo \| in-progress \| blocked \| done`. **The source of truth** — there is no separate `done` flag to fall out of sync. |
 | `priority` | `p0`–`p3`, default `p2` so an unranked task sits mid-pile rather than jumping the queue. |
-| `release` | What ships together, e.g. `v1.2.0`. |
-| `sprint` | When it is worked, e.g. `Sprint 24`. |
+| `release` | What ships together, e.g. `1.5` or `0.5.1`. One to three numbers. |
+| `sprint` | When it is worked, e.g. `24`. A single decimal — no patch segment. |
 | `dueDate` | `YYYY-MM-DD`. A calendar day, not an instant — an epoch would bind it to a timezone and let one task read as two different days. Impossible dates like `2025-02-31` are rejected rather than rolled forward. |
 
-**Release and sprint are separate on purpose.** A task can be worked in Sprint 24
-and ship in v1.3.0; collapsing them into one field loses the ability to answer
-either question. Both are free text rather than entities — grouping and
+**Release and sprint are separate on purpose.** A task can be worked in sprint 24
+and ship in 1.3; collapsing them into one field loses the ability to answer
+either question. Both are **numeric labels** rather than entities, refused at
+every write path — CLI and UI alike — if they are anything else, so grouping and
 filtering work with no releases table, no CRUD, and no migration to rename one.
 
+The two shapes differ, because the fields mean different things:
+
+| Field | Pattern | Passes | Refused |
+| --- | --- | --- | --- |
+| `release` | `^\d+(\.\d+){0,2}$` | `1`, `1.5`, `0.5.1` | `v1.5`, `1.2.3.4`, `1.` |
+| `sprint` | `^\d+(\.\d+)?$` | `1`, `1.5`, `24` | `Sprint 24`, `0.5.1` |
+
+A release carries a **patch segment** so a fix shipping on top of 0.5 gets its own
+label; a sprint is a point on a calendar, not a shipped artefact, so it takes none.
+Being numeric means labels sort by **version semantics** — compared segment by
+segment, so `1.10` ranks above `1.9` and `0.5.1` sits between `0.5` and `0.6`.
+Labels stored before the rule still load, group, and display unchanged.
+
 `completedAt` is written only by the status transition, so it can never claim a
 task is finished that isn't. Absent optional fields are absent *keys*, never
 `''`, so "no release" has exactly one representation.

package/lib/bin.js

@@ -24,6 +24,14 @@ function normalizeLabel(raw) {
   const text = raw.replace(/\s+/g, " ").trim().slice(0, MAX_LABEL);
   return text.length > 0 ? text : void 0;
 }
+var RELEASE_LABEL_RE = /^\d+(\.\d+){0,2}$/;
+var SPRINT_LABEL_RE = /^\d+(\.\d+)?$/;
+function normalizeVersionLabel(raw, field) {
+  const label = normalizeLabel(raw);
+  if (label === void 0) return void 0;
+  const pattern = field === "release" ? RELEASE_LABEL_RE : SPRINT_LABEL_RE;
+  return pattern.test(label) ? label : void 0;
+}
 var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 function normalizeDueDate(raw) {
   if (typeof raw !== "string") return void 0;
@@ -36,6 +44,8 @@ function normalizeDueDate(raw) {
 var MAX_TEXT = 500;
 var MAX_DESC = 5e3;
 var MAX_LABEL = 60;
+var SUGGESTIONS_DIR = ".dsh";
+var SUGGESTIONS_FILE = `${SUGGESTIONS_DIR}/suggestions.json`;
 
 // src/db.ts
 var DOT_DSH = ".dsh";
@@ -78,6 +88,7 @@ function migrateSchema(db) {
   add("release", "release TEXT");
   add("sprint", "sprint TEXT");
   add("due_date", "due_date TEXT");
+  add("session_id", "session_id TEXT");
   if (addedTitle && columns.has("text")) {
     db.exec("UPDATE todo SET title = text WHERE title IS NULL");
   }
@@ -93,7 +104,7 @@ function readList(db) {
   const updatedAt = Number(db.prepare("SELECT value FROM meta WHERE key = 'updatedAt'").get()?.value ?? 0);
   const rows = db.prepare(
     `SELECT id, title, description, status, priority, release, sprint, due_date,
-              created_at, completed_at, archived_at
+              session_id, created_at, completed_at, archived_at
        FROM todo ORDER BY position ASC`
   ).all();
   const text = (v) => v === null || v === void 0 ? void 0 : String(v);
@@ -108,6 +119,7 @@ function readList(db) {
       ...normalizeLabel(row.release) !== void 0 ? { release: normalizeLabel(row.release) } : {},
       ...normalizeLabel(row.sprint) !== void 0 ? { sprint: normalizeLabel(row.sprint) } : {},
       ...normalizeDueDate(row.due_date) !== void 0 ? { dueDate: normalizeDueDate(row.due_date) } : {},
+      ...text(row.session_id) !== void 0 ? { sessionId: text(row.session_id) } : {},
       createdAt: Number(row.created_at),
       ...row.completed_at !== null && row.completed_at !== void 0 ? { completedAt: Number(row.completed_at) } : {},
       ...row.archived_at !== null && row.archived_at !== void 0 ? { archivedAt: Number(row.archived_at) } : {}
@@ -121,8 +133,8 @@ function writeList(db, items, revision, updatedAt = Date.now()) {
     db.prepare("DELETE FROM todo").run();
     const insert = db.prepare(
       `INSERT INTO todo (id, title, description, status, priority, release, sprint, due_date,
-                         text, done, created_at, completed_at, archived_at, position)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+                         session_id, text, done, created_at, completed_at, archived_at, position)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     );
     items.forEach((item, index) => {
       insert.run(
@@ -134,6 +146,7 @@ function writeList(db, items, revision, updatedAt = Date.now()) {
         item.release ?? null,
         item.sprint ?? null,
         item.dueDate ?? null,
+        item.sessionId ?? null,
         item.title,
         item.status === "done" ? 1 : 0,
         item.createdAt,
@@ -191,10 +204,13 @@ var CliError = class extends Error {
   /**
    * @param message - human-readable reason.
    * @param code - process exit code, from {@link EXIT}.
+   * @param details - extra machine-readable fields merged into the `--json`
+   * error payload, so an agent can correct itself without parsing the sentence.
    */
-  constructor(message, code = EXIT.usage) {
+  constructor(message, code = EXIT.usage, details = {}) {
     super(message);
     this.code = code;
+    this.details = details;
     this.name = "CliError";
   }
 };
@@ -212,6 +228,16 @@ function oneOf(options, key, allowed) {
   }
   return raw;
 }
+function assertLabel(field, raw) {
+  if (raw === void 0 || raw === "") return;
+  if (normalizeVersionLabel(raw, field) !== void 0) return;
+  const shape = field === "release" ? "a version number like 1.5 or 0.5.1 (up to three numbers)" : "a decimal number like 1.5 (one dot at most)";
+  throw new CliError(
+    `--${field} must be ${shape} (got "${raw}") \u2014 nothing was saved`,
+    EXIT.usage,
+    { field, expected: shape, got: raw }
+  );
+}
 function resolveWorkspace(options, cwd) {
   return resolve2(str(options, "workspace") ?? cwd);
 }
@@ -274,6 +300,7 @@ function formatItem(item) {
   if (item.release) meta.push(`release=${item.release}`);
   if (item.sprint) meta.push(`sprint=${item.sprint}`);
   if (item.dueDate) meta.push(`due=${item.dueDate}`);
+  if (item.sessionId) meta.push(`session=${item.sessionId}`);
   if (isArchived(item)) meta.push("archived");
   return bits.join(" ") + (meta.length ? `  (${meta.join(" ")})` : "");
 }
@@ -299,9 +326,11 @@ Options
 
   --status <s>               ${STATUSES.join("|")}
   --priority <p>             ${PRIORITIES.join("|")}
-  --release <label>          e.g. v1.2.0        (empty string clears)
-  --sprint <label>           e.g. "Sprint 24"   (empty string clears)
+  --release <n[.n[.n]]>      e.g. 1.5 or 0.5.1   (empty string clears)
+  --sprint <n[.n]>           e.g. 24             (empty string clears)
   --due <YYYY-MM-DD>         Calendar day       (empty string clears)
+  --session <id>             Harness session working the task (update only;
+                             empty string clears)
   --description <text>       Body text          (empty string clears)
   --title <text>             Rename (update only)
 
@@ -311,8 +340,8 @@ Ids may be given as any unambiguous prefix.
 
 Examples
   dsh-todo list --open --json
-  dsh-todo add "Fix token refresh" --priority p0 --release v1.2.0 --due 2026-03-14
-  dsh-todo update t1a2 --status in-progress --sprint "Sprint 24"
+  dsh-todo add "Fix token refresh" --priority p0 --release 1.5 --due 2026-03-14
+  dsh-todo update t1a2 --status in-progress --sprint 24
   dsh-todo done t1a2
 `;
 function run(parsed, cwd, now = Date.now, rand = Math.random) {
@@ -349,6 +378,7 @@ function run(parsed, cwd, now = Date.now, rand = Math.random) {
         `release     ${item.release ?? "-"}`,
         `sprint      ${item.sprint ?? "-"}`,
         `due         ${item.dueDate ?? "-"}`,
+        `session     ${item.sessionId ?? "-"}`,
         `created     ${new Date(item.createdAt).toISOString()}`,
         ...item.completedAt ? [`completed   ${new Date(item.completedAt).toISOString()}`] : [],
         ...item.archivedAt ? [`archived    ${new Date(item.archivedAt).toISOString()}`] : [],
@@ -360,8 +390,12 @@ function run(parsed, cwd, now = Date.now, rand = Math.random) {
       const title = positional.join(" ").trim();
       if (!title) throw new CliError("add needs a title");
       const description = str(options, "description");
-      const release = normalizeLabel(str(options, "release"));
-      const sprint = normalizeLabel(str(options, "sprint"));
+      const releaseRaw = str(options, "release");
+      const sprintRaw = str(options, "sprint");
+      assertLabel("release", releaseRaw);
+      assertLabel("sprint", sprintRaw);
+      const release = normalizeVersionLabel(releaseRaw, "release");
+      const sprint = normalizeVersionLabel(sprintRaw, "sprint");
       const dueRaw = str(options, "due");
       if (dueRaw !== void 0 && dueRaw !== "" && normalizeDueDate(dueRaw) === void 0) {
         throw new CliError(`--due must be a real calendar date as YYYY-MM-DD (got "${dueRaw}")`);
@@ -390,10 +424,13 @@ function run(parsed, cwd, now = Date.now, rand = Math.random) {
       const release = str(options, "release");
       const sprint = str(options, "sprint");
       const due = str(options, "due");
+      const session = str(options, "session");
       if (due !== void 0 && due !== "" && normalizeDueDate(due) === void 0) {
         throw new CliError(`--due must be a real calendar date as YYYY-MM-DD (got "${due}")`);
       }
-      if (status === void 0 && priority === void 0 && title === void 0 && description === void 0 && release === void 0 && sprint === void 0 && due === void 0) {
+      assertLabel("release", release);
+      assertLabel("sprint", sprint);
+      if (status === void 0 && priority === void 0 && title === void 0 && description === void 0 && release === void 0 && sprint === void 0 && due === void 0 && session === void 0) {
         throw new CliError("update needs at least one field to change");
       }
       let updated;
@@ -415,7 +452,7 @@ function run(parsed, cwd, now = Date.now, rand = Math.random) {
           }
           for (const [key, raw] of [["release", release], ["sprint", sprint]]) {
             if (raw === void 0) continue;
-            const label = normalizeLabel(raw);
+            const label = normalizeVersionLabel(raw, key);
             if (label !== void 0) next[key] = label;
             else delete next[key];
           }
@@ -424,6 +461,10 @@ function run(parsed, cwd, now = Date.now, rand = Math.random) {
             if (value !== void 0) next.dueDate = value;
             else delete next.dueDate;
           }
+          if (session !== void 0) {
+            if (session) next.sessionId = session.slice(0, MAX_LABEL);
+            else delete next.sessionId;
+          }
           updated = next;
           return next;
         });
@@ -489,12 +530,14 @@ function main(argv, cwd = process.cwd()) {
   const wantsJson = parsed.options.json === true;
   try {
     const outcome = run(parsed, cwd);
-    console.log(wantsJson ? JSON.stringify(outcome.json, null, 2) : outcome.text);
+    const json = outcome.json !== null && typeof outcome.json === "object" && !Array.isArray(outcome.json) ? { ok: true, ...outcome.json } : { ok: true, result: outcome.json };
+    console.log(wantsJson ? JSON.stringify(json, null, 2) : outcome.text);
     return EXIT.ok;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const code = error instanceof CliError ? error.code : 1;
-    if (wantsJson) console.log(JSON.stringify({ error: message, code }, null, 2));
+    const details = error instanceof CliError ? error.details : {};
+    if (wantsJson) console.log(JSON.stringify({ ok: false, error: message, code, ...details }, null, 2));
     else console.error(`dsh-todo: ${message}`);
     return code;
   }