exponential-cli 1.8.0 → 1.9.0

package/README.md

@@ -70,9 +70,17 @@ exponential actions create -n "Task name" -d "Description" -p <project-id> --pri
 exponential actions update --id <action-id> --kanban DONE
 exponential actions update --id <action-id> -n "New name" --priority "2nd Priority" --due 2026-03-15
 
-# Get today's actions
+# Set the do-date (when you plan to work on it). This is what `today` partitions on,
+# and it takes precedence over --due.
+exponential actions update --id <action-id> --scheduled-start 2026-08-05T09:00
+exponential actions update --id <action-id> --scheduled-start null   # clear it
+
+# What's actually on your plate: overdue + today + inbox
 exponential actions today
 
+# Just the actions whose dueDate is today (excludes overdue — see note below)
+exponential actions today --due-only
+
 # Get actions in a date range
 exponential actions range --start 2024-01-01 --end 2024-01-31
 
@@ -80,6 +88,48 @@ exponential actions range --start 2024-01-01 --end 2024-01-31
 exponential actions kanban --project <project-id>
 ```
 
+#### Triaging an overdue pile
+
+A large overdue count is usually not a large number of missed commitments — it's
+a few bulk writes (a generated project plan, an import) that stamped every row
+with one identical timestamp. `actions overdue` separates the two:
+
+```bash
+exponential actions overdue
+```
+
+```
+Overdue: 43
+
+21 of these were bulk-created — stamped with one identical timestamp,
+so almost certainly never individually due.
+
+  17 actions stamped 2026-07-25T08:29:55.483Z (10d overdue)
+    Projects: Entity Money Map, Net Worth Baseline, Tax Reserve System, …
+    Amnesty: exponential actions defer --ids cmqcgvtlh…,cmqcgvtnn…,…
+
+19 individually dated — real debt, oldest first.
+   12d  Send out the job description for the data engineering role [Hiring]
+```
+
+Then pick a disposition:
+
+```bash
+# Amnesty: clear the dates, back to the project backlog untimed.
+# For work that was never really due on the date it carries.
+exponential actions defer --ids id1,id2,id3
+
+# Reschedule: still due, just later.
+exponential actions reschedule --ids id1,id2 --to today
+exponential actions reschedule --ids id1,id2 --to 2026-08-10
+```
+
+> **Note on `actions today`:** as of v1.9.0 this returns the same
+> overdue/today/inbox partition the `/today` page renders, rather than a
+> due-date-only list. The old behaviour silently omitted the overdue pile — it
+> would report 6 actions while 43 sat overdue. Pass `--due-only` for the
+> previous output shape.
+
 ### Projects
 
 ```bash

package/dist/index.js

@@ -329,6 +329,91 @@ ${statusBadge} ${chalk3.bold(action.name)}`);
   }
   console.log();
 }
+function outputTodaysActionsJson(t, filters = {}) {
+  console.log(JSON.stringify({
+    overdue: { count: t.overdue.count, actions: t.overdue.actions },
+    today: { count: t.today.count, actions: t.today.actions },
+    inbox: { count: t.inbox.count, actions: t.inbox.actions },
+    total: t.overdue.count + t.today.count + t.inbox.count,
+    filters
+  }, null, 2));
+}
+function printTodayGroup(label, group, color) {
+  if (group.count === 0) return;
+  const truncated = group.count > group.actions.length ? chalk3.gray(` (showing ${group.actions.length})`) : "";
+  console.log(`
+${chalk3[color].bold(`${label} (${group.count})`)}${truncated}`);
+  for (const a of group.actions) {
+    const when = a.scheduledStart ?? a.dueDate;
+    const stamp = when ? chalk3.gray(formatDate(new Date(when))) : "";
+    const project = a.projectName ? chalk3.cyan(` [${a.projectName}]`) : "";
+    console.log(`  ${a.name}${project} ${stamp}`);
+    console.log(chalk3.gray(`    ID: ${a.id}`));
+  }
+}
+function outputTodaysActionsPretty(t) {
+  const total = t.overdue.count + t.today.count + t.inbox.count;
+  if (total === 0) {
+    console.log(chalk3.gray("Nothing on your plate."));
+    return;
+  }
+  console.log(chalk3.bold("\nOn your plate"));
+  console.log(chalk3.gray("\u2500".repeat(50)));
+  printTodayGroup("Overdue", t.overdue, "red");
+  printTodayGroup("Today", t.today, "green");
+  printTodayGroup("Inbox", t.inbox, "gray");
+  if (t.overdue.count > 0) {
+    console.log(chalk3.gray(`
+Run "exponential actions overdue" to see why the overdue pile is that size.`));
+  }
+  console.log();
+}
+function outputOverdueTriageJson(t) {
+  console.log(JSON.stringify(t, null, 2));
+}
+function outputOverdueTriagePretty(t) {
+  if (t.totalOverdue === 0) {
+    console.log(chalk3.green("Nothing overdue."));
+    return;
+  }
+  console.log(chalk3.bold(`
+Overdue: ${t.totalOverdue}`));
+  console.log(chalk3.gray("\u2500".repeat(50)));
+  if (t.cohorts.length > 0) {
+    console.log(
+      `
+${chalk3.yellow.bold(`${t.cohortCount} of these were bulk-created`)} ${chalk3.gray("\u2014 stamped with one identical timestamp, so almost certainly never individually due.")}`
+    );
+    for (const c of t.cohorts) {
+      console.log(
+        `
+  ${chalk3.bold(`${c.count} actions`)} stamped ${chalk3.gray(c.stampedAt.toISOString())} ${chalk3.red(`(${c.daysOverdue}d overdue)`)}`
+      );
+      if (c.projectNames.length > 0) {
+        console.log(`    ${chalk3.cyan("Projects:")} ${c.projectNames.join(", ")}`);
+      }
+      for (const a of c.actions.slice(0, 4)) {
+        console.log(chalk3.gray(`      \xB7 ${a.name.substring(0, 62)}`));
+      }
+      if (c.actions.length > 4) {
+        console.log(chalk3.gray(`      \xB7 \u2026 and ${c.actions.length - 4} more`));
+      }
+      console.log(
+        chalk3.gray(`    Amnesty: `) + `exponential actions defer --ids ${c.actionIds.slice(0, 2).join(",")}${c.actionIds.length > 2 ? ",\u2026" : ""}`
+      );
+    }
+  }
+  if (t.loose.length > 0) {
+    console.log(`
+${chalk3.bold(`${t.loose.length} individually dated`)} ${chalk3.gray("\u2014 real debt, oldest first.")}`);
+    for (const a of t.loose) {
+      const project = a.projectName ? chalk3.cyan(` [${a.projectName}]`) : "";
+      console.log(`  ${chalk3.red(`${String(a.daysOverdue).padStart(3)}d`)}  ${a.name.substring(0, 62)}${project}`);
+      console.log(chalk3.gray(`        ID: ${a.id}`));
+    }
+  }
+  console.log();
+}
 function outputProjectsJson(projects) {
   const output = {
     projects: projects.map(transformProject),
@@ -1312,6 +1397,22 @@ var VALID_PRIORITIES = [
   "Watch",
   "Someday Maybe"
 ];
+function parseNullableDate(raw, flag) {
+  if (raw === void 0) return void 0;
+  if (raw === "null") return null;
+  const parsed = new Date(raw);
+  if (isNaN(parsed.getTime())) {
+    throw new Error(`Invalid --${flag} value "${raw}". Use YYYY-MM-DD, an ISO datetime, or "null".`);
+  }
+  return parsed;
+}
+function parseIds(raw) {
+  const ids = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  if (ids.length === 0) {
+    throw new Error("No action IDs supplied. Pass --ids id1,id2");
+  }
+  return ids;
+}
 function createActionsCommand() {
   const actions = new Command2("actions").description("Manage actions/tasks");
   actions.command("list").description("List all actions").option("--project <id>", "Filter by project ID").option("--status <status>", "Filter by kanban status (BACKLOG, TODO, IN_PROGRESS, IN_REVIEW, DONE)").option("--assignee <id>", "Filter by assignee ID").action(async (options, cmd) => {
@@ -1337,16 +1438,76 @@ function createActionsCommand() {
       handleError(error, useJson);
     }
   });
-  actions.command("today").description("Get actions due today").option("--workspace <id>", "Filter by workspace ID").action(async (options, cmd) => {
+  actions.command("today").description("What's on your plate: overdue, today, and inbox").option("--workspace <id>", "Filter by workspace ID").option("--due-only", "Only actions whose dueDate is today (the pre-1.8 shape \u2014 excludes overdue)").action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
     try {
       const client = getClient();
-      const actions2 = await client.actions.getToday(options.workspace);
+      if (options.dueOnly) {
+        const actions2 = await client.actions.getToday(options.workspace);
+        if (useJson) {
+          outputActionsJson(actions2, { workspaceId: options.workspace });
+        } else {
+          outputActionsPretty(actions2);
+        }
+        return;
+      }
+      const todays = await client.actions.getTodaysActions(options.workspace);
       if (useJson) {
-        outputActionsJson(actions2, { workspaceId: options.workspace });
+        outputTodaysActionsJson(todays, { workspaceId: options.workspace });
       } else {
-        outputActionsPretty(actions2);
+        outputTodaysActionsPretty(todays);
+      }
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
+  actions.command("overdue").description("Why the overdue pile is that size: bulk-created cohorts vs real debt").option("--workspace <id>", "Filter by workspace ID").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const client = getClient();
+      const triage = await client.actions.getOverdueTriage(options.workspace);
+      if (useJson) {
+        outputOverdueTriageJson(triage);
+      } else {
+        outputOverdueTriagePretty(triage);
+      }
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
+  actions.command("defer").description("Amnesty: clear dates so actions fall back to their project backlog untimed").requiredOption("--ids <ids>", "Comma-separated action IDs").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const ids = parseIds(options.ids);
+      const client = getClient();
+      const result = await client.actions.bulkDefer(ids);
+      if (useJson) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`\u2713 ${result.message}`);
+      }
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
+  actions.command("reschedule").description('Move actions to a new do-date (use "actions defer" if they were never really due)').requiredOption("--ids <ids>", "Comma-separated action IDs").requiredOption("--to <date>", 'New do-date (YYYY-MM-DD, or "today")').action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const ids = parseIds(options.ids);
+      const when = options.to === "today" ? /* @__PURE__ */ new Date() : new Date(options.to);
+      if (isNaN(when.getTime())) {
+        throw new Error('Invalid date format. Use YYYY-MM-DD or "today"');
+      }
+      const client = getClient();
+      const result = await client.actions.bulkReschedule(ids, when);
+      if (useJson) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`\u2713 Rescheduled ${result.count} action${result.count === 1 ? "" : "s"}`);
       }
     } catch (error) {
       handleError(error, useJson);
@@ -1395,7 +1556,7 @@ function createActionsCommand() {
       handleError(error, useJson);
     }
   });
-  actions.command("update").description("Update an existing action").requiredOption("--id <id>", "Action ID to update").option("-n, --name <name>", "New action name").option("-d, --description <text>", "New description").option("-p, --project <id>", "Move to project ID").option("--priority <priority>", "Priority (Quick, Scheduled, 1st Priority, etc.)").option("--status <status>", "Status (ACTIVE, COMPLETED, CANCELLED)").option("--kanban <status>", "Kanban status (BACKLOG, TODO, IN_PROGRESS, IN_REVIEW, DONE)").option("--due <date>", 'Due date (YYYY-MM-DD or "null" to clear)').action(async (options, cmd) => {
+  actions.command("update").description("Update an existing action").requiredOption("--id <id>", "Action ID to update").option("-n, --name <name>", "New action name").option("-d, --description <text>", "New description").option("-p, --project <id>", "Move to project ID").option("--priority <priority>", "Priority (Quick, Scheduled, 1st Priority, etc.)").option("--status <status>", "Status (ACTIVE, COMPLETED, CANCELLED)").option("--kanban <status>", "Kanban status (BACKLOG, TODO, IN_PROGRESS, IN_REVIEW, DONE)").option("--due <date>", 'Due date (YYYY-MM-DD or "null" to clear)').option("--scheduled-start <datetime>", 'Do-date: when you plan to work on it (YYYY-MM-DD, ISO datetime, or "null" to clear). This is what /today partitions on.').option("--scheduled-end <datetime>", 'End of the time block (YYYY-MM-DD, ISO datetime, or "null" to clear)').action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
     try {
@@ -1411,6 +1572,8 @@ function createActionsCommand() {
           throw new Error("Invalid due date format. Use YYYY-MM-DD");
         }
       }
+      const scheduledStart = parseNullableDate(options.scheduledStart, "scheduled-start");
+      const scheduledEnd = parseNullableDate(options.scheduledEnd, "scheduled-end");
       const client = getClient();
       const action = await client.actions.update({
         id: options.id,
@@ -1420,7 +1583,9 @@ function createActionsCommand() {
         priority: options.priority,
         status: options.status,
         kanbanStatus: options.kanban,
-        dueDate
+        dueDate,
+        scheduledStart,
+        scheduledEnd
       });
       if (useJson) {
         outputActionJson(action);
@@ -2034,7 +2199,7 @@ function createEpicsCommand() {
       const globalOpts = cmd.optsWithGlobals();
       const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
       try {
-        const parseNullableDate = (v) => {
+        const parseNullableDate2 = (v) => {
           if (v === void 0) return void 0;
           if (v === "null") return null;
           const d = new Date(v);
@@ -2053,8 +2218,8 @@ function createEpicsCommand() {
           description,
           status,
           priority,
-          startDate: parseNullableDate(options.start),
-          targetDate: parseNullableDate(options.target)
+          startDate: parseNullableDate2(options.start),
+          targetDate: parseNullableDate2(options.target)
         });
         if (useJson) outputEpicJson(epic);
         else {
@@ -2500,6 +2665,17 @@ var FEATURE_STATUSES = [
   "DEPRECATED",
   "ARCHIVED"
 ];
+function summarizeTicket(ticket) {
+  return {
+    id: ticket.id,
+    shortId: ticket.shortId ?? null,
+    number: ticket.number ?? null,
+    title: ticket.title
+  };
+}
+function ticketLabel(ticket) {
+  return ticket.shortId ?? (ticket.number != null ? `#${ticket.number}` : ticket.id);
+}
 function validateFeatureStatus(value) {
   if (!value) return void 0;
   if (!FEATURE_STATUSES.includes(value)) {
@@ -2606,6 +2782,119 @@ function createFeaturesCommand() {
       }
     }
   );
+  features.command("delete <id>").description(
+    "Delete a feature. Refuses if it still has tickets \u2014 deleting a feature does not delete its tickets, it unlinks them (Ticket.featureId is SetNull), silently orphaning them in the product backlog."
+  ).option(
+    "--with-tickets",
+    "Delete the feature's tickets first, then the feature (destructive)"
+  ).option(
+    "--orphan-tickets",
+    "Delete the feature anyway, leaving its tickets in the backlog unlinked"
+  ).action(
+    async (id, options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        if (options.withTickets && options.orphanTickets) {
+          throw new Error(
+            "--with-tickets and --orphan-tickets are mutually exclusive"
+          );
+        }
+        const client = getClient();
+        const feature = await client.features.get(id);
+        const tickets = feature._count?.tickets === 0 ? [] : await client.tickets.list({
+          productId: feature.productId,
+          featureId: feature.id
+        });
+        if (tickets.length > 0 && !options.withTickets && !options.orphanTickets) {
+          const reason = `has ${tickets.length} ticket${tickets.length === 1 ? "" : "s"}`;
+          if (useJson) {
+            console.log(
+              JSON.stringify(
+                {
+                  deleted: false,
+                  id: feature.id,
+                  reason,
+                  tickets: tickets.map(summarizeTicket)
+                },
+                null,
+                2
+              )
+            );
+          } else {
+            console.error(
+              `
+Refusing to delete "${feature.name}": it ${reason}.
+Deleting the feature would leave them unlinked in the product backlog.
+  --with-tickets    delete those tickets first, then the feature
+  --orphan-tickets  delete the feature anyway and unlink them`
+            );
+            for (const t of tickets) {
+              console.error(`  - ${ticketLabel(t)} ${t.title}`);
+            }
+          }
+          process.exitCode = 1;
+          return;
+        }
+        const ticketsDeleted = [];
+        const ticketsFailed = [];
+        if (options.withTickets) {
+          for (const ticket of tickets) {
+            try {
+              await client.tickets.delete(ticket.id);
+              ticketsDeleted.push(summarizeTicket(ticket));
+            } catch (error) {
+              ticketsFailed.push({
+                ...summarizeTicket(ticket),
+                error: error instanceof Error ? error.message : String(error)
+              });
+            }
+          }
+        }
+        if (ticketsFailed.length > 0) {
+          const reason = `failed to delete ${ticketsFailed.length} of ${tickets.length} tickets`;
+          if (useJson) {
+            console.log(
+              JSON.stringify(
+                { deleted: false, id: feature.id, reason, ticketsDeleted, ticketsFailed },
+                null,
+                2
+              )
+            );
+          } else {
+            console.error(`
+Aborted: ${reason}. Feature "${feature.name}" was NOT deleted.`);
+            for (const t of ticketsFailed) {
+              console.error(`  - ${t.shortId ?? t.id}: ${t.error}`);
+            }
+          }
+          process.exitCode = 1;
+          return;
+        }
+        await client.features.delete(feature.id);
+        const ticketsOrphaned = options.orphanTickets ? tickets.map(summarizeTicket) : [];
+        if (useJson) {
+          console.log(
+            JSON.stringify(
+              { deleted: true, id: feature.id, ticketsDeleted, ticketsOrphaned },
+              null,
+              2
+            )
+          );
+        } else {
+          console.log("\n\u2713 Feature deleted");
+          if (ticketsDeleted.length > 0) {
+            console.log(`  ${ticketsDeleted.length} ticket(s) deleted with it`);
+          }
+          if (ticketsOrphaned.length > 0) {
+            console.log(`  ${ticketsOrphaned.length} ticket(s) left unlinked in the backlog`);
+          }
+        }
+      } catch (error) {
+        handleError(error, useJson);
+      }
+    }
+  );
   features.command("link-page").description("Link a Knowledge page (PRD, spec, research) to a feature").requiredOption("--feature <id>", "Feature CUID").requiredOption("--page <id>", "Page CUID").option("--scope <id>", "Feature scope CUID to pin the page to").action(
     async (options, cmd) => {
       const globalOpts = cmd.optsWithGlobals();