exponential-cli 1.11.1 → 1.11.2

package/README.md

@@ -130,14 +130,69 @@ exponential actions reschedule --ids id1,id2 --to 2026-08-10
 > would report 6 actions while 43 sat overdue. Pass `--due-only` for the
 > previous output shape.
 
+### Goals and OKRs
+
+Objectives are goals; they carry **integer** ids. Their key results carry CUIDs
+and live under `goals kr`.
+
+```bash
+# List a workspace's objectives, or the annual → quarterly cascade
+exponential goals list --workspace clear --period Q3-2026
+exponential goals list --workspace clear --tree
+exponential goals list --all-workspaces       # "what am I neglecting" is cross-workspace
+
+exponential goals get 46
+exponential goals create --workspace clear --title "Ship the CLI" --period Q3-2026
+
+# Close a quarter. set-status/close write ONLY the status column.
+exponential goals close --id 46                       # → completed
+exponential goals set-status --id 46 --status on-hold
+
+# Everything else is a partial update: fields you don't pass are left alone,
+# and "none" is how you clear one.
+exponential goals update --id 46 --title "Ship the CLI, properly"
+exponential goals update --id 46 --workspace none     # make it personal
+exponential goals reparent --id 47 --parent 46        # or --parent none
+exponential goals delete --id 46                      # refuses if it has key results
+
+exponential goals periods
+exponential goals stats --workspace clear --period Q3-2026
+
+# The quarter at a glance: objectives with their key results nested
+exponential okrs list --workspace clear
+```
+
+Key results:
+
+```bash
+exponential goals kr list --goal 46
+exponential goals kr list --workspace clear --status at-risk
+exponential goals kr create --goal 46 --title "Weekly active agents" --target 500 --unit count
+exponential goals kr checkin --id <cuid> --value 120 --note "post-launch bump"
+exponential goals kr update --id <cuid> --target 600
+exponential goals kr link --id <cuid> --feature <feature-cuid>   # or --project <cuid>
+exponential goals kr unlink --id <cuid> --project <cuid>
+exponential goals kr delete --id <cuid>
+```
+
 ### Projects
 
 ```bash
 # List all projects
 exponential projects list
 
-# List projects in a workspace
-exponential projects list --workspace <workspace-id>
+# List projects in a workspace (slug or CUID)
+exponential projects list --workspace clear
+
+# One project, with its objectives, key results, DRI and actions
+exponential projects get <cuid|slug>
+
+# Partial update — unnamed fields are preserved
+exponential projects update --id <cuid> --name "KR support" --status COMPLETED
+exponential projects update --id <cuid> --product none
+
+# Refuses while the project still has actions or OKR links
+exponential projects delete --id <cuid> [--force]
 ```
 
 ### Workspaces

package/dist/index.js

@@ -1748,6 +1748,63 @@ OKRs (${objectives.length} objectives, ${totalKeyResults} key results)`)
   }
   console.log();
 }
+function outputProjectJson(project) {
+  console.log(JSON.stringify({
+    ...transformProject(project),
+    // The detail read has no `workspace` relation to expand, unlike the list
+    // read — so `transformProject` alone would emit `workspace: null` and no id
+    // at all, which reads as "personal project" rather than "not fetched".
+    workspaceId: project.workspaceId,
+    slug: project.slug ?? null,
+    productId: project.productId ?? null,
+    driId: project.driId ?? null,
+    dri: project.dri ?? null,
+    team: project.team ?? null,
+    goals: project.goals ?? [],
+    keyResults: project.keyResults?.map((k) => ({
+      id: k.keyResultId,
+      title: k.keyResult?.title ?? null,
+      goal: k.keyResult?.goal ?? null
+    })) ?? [],
+    outcomes: project.outcomes ?? [],
+    actionCount: project.actions?.length ?? null,
+    createdAt: project.createdAt ? new Date(project.createdAt).toISOString() : null
+  }, null, 2));
+}
+function outputProjectPretty(project) {
+  console.log(chalk3.gray("\u2500".repeat(50)));
+  console.log(`
+${chalk3.bold(project.name)}`);
+  console.log(chalk3.gray(`  ID: ${project.id}`));
+  if (project.status) console.log(`  ${chalk3.cyan("Status:")} ${project.status}`);
+  if (project.priority) console.log(`  ${chalk3.magenta("Priority:")} ${project.priority}`);
+  if (project.workspace) {
+    console.log(`  ${chalk3.yellow("Workspace:")} ${project.workspace.name} (${project.workspace.slug})`);
+  }
+  if (project.description) {
+    console.log(`  ${chalk3.gray("Description:")} ${project.description.substring(0, 200)}${project.description.length > 200 ? "..." : ""}`);
+  }
+  if (project.dri) {
+    console.log(`  ${chalk3.magenta("DRI:")} ${project.dri.name ?? project.dri.email ?? project.dri.id}`);
+  }
+  if (project.goals?.length) {
+    console.log(`  ${chalk3.cyan("Objectives:")}`);
+    for (const g of project.goals) {
+      console.log(`    - #${g.id} ${g.title}`);
+    }
+  }
+  if (project.keyResults?.length) {
+    console.log(`  ${chalk3.cyan("Key results:")}`);
+    for (const k of project.keyResults) {
+      const objective = k.keyResult?.goal ? chalk3.gray(` (objective #${k.keyResult.goal.id})`) : "";
+      console.log(`    - ${k.keyResult?.title ?? k.keyResultId} ${chalk3.gray(`[${k.keyResultId}]`)}${objective}`);
+    }
+  }
+  if (project.actions?.length) {
+    console.log(`  ${chalk3.cyan("Actions:")} ${project.actions.length}`);
+  }
+  console.log();
+}
 
 // src/commands/actions.ts
 var VALID_PRIORITIES = [
@@ -3279,6 +3336,17 @@ function summarizeTicket(ticket) {
 function ticketLabel(ticket) {
   return ticket.shortId ?? (ticket.number != null ? `#${ticket.number}` : ticket.id);
 }
+function parseFeatureGoalId(value) {
+  if (value === void 0) return void 0;
+  if (value === "none") return null;
+  const id = Number(value);
+  if (!Number.isInteger(id)) {
+    throw new Error(
+      `--goal must be a whole number or "none", got "${value}". Find one with \`exponential goals list\`.`
+    );
+  }
+  return id;
+}
 function validateFeatureStatus(value) {
   if (!value) return void 0;
   if (!FEATURE_STATUSES.includes(value)) {
@@ -3358,7 +3426,10 @@ function createFeaturesCommand() {
       }
     }
   );
-  features.command("update").description("Update an existing feature").requiredOption("--id <id>", "Feature CUID").option("-n, --name <name>", "New name").option("-d, --description <text>", "New description").option("--vision <text>", "New vision text").option("--status <status>", `Status: ${FEATURE_STATUSES.join(", ")}`).option("--priority <n>", "Priority 0-4", parseInt).option("--effort <n>", "Effort estimate", parseFloat).option("--area <id>", 'Area CUID ("none" to clear)').action(
+  features.command("update").description("Update an existing feature").requiredOption("--id <id>", "Feature CUID").option("-n, --name <name>", "New name").option("-d, --description <text>", "New description").option("--vision <text>", "New vision text").option("--status <status>", `Status: ${FEATURE_STATUSES.join(", ")}`).option("--priority <n>", "Priority 0-4", parseInt).option("--effort <n>", "Effort estimate", parseFloat).option("--area <id>", 'Area CUID ("none" to clear)').option(
+    "--goal <id|none>",
+    'Objective (goal) id this feature serves ("none" to clear). For progress rollup, link the finer Feature\u2192key-result edge with `goals kr link --feature`.'
+  ).action(
     async (options, cmd) => {
       const globalOpts = cmd.optsWithGlobals();
       const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
@@ -3373,7 +3444,8 @@ function createFeaturesCommand() {
           status,
           priority: options.priority,
           effort: options.effort,
-          areaId: options.area === "none" ? null : options.area
+          areaId: options.area === "none" ? null : options.area,
+          goalId: parseFeatureGoalId(options.goal)
         });
         if (useJson) outputFeatureJson(feature);
         else {
@@ -4033,15 +4105,41 @@ function createProductsCommand() {
 
 // src/commands/projects.ts
 import { Command as Command17 } from "commander";
+var PROJECT_STATUSES = [
+  "ACTIVE",
+  "ON_HOLD",
+  "COMPLETED",
+  "CANCELLED"
+];
+var PROJECT_PRIORITIES = ["HIGH", "MEDIUM", "LOW", "NONE"];
+function validateProjectStatus(value) {
+  if (!value) return void 0;
+  if (!PROJECT_STATUSES.includes(value)) {
+    throw new Error(
+      `Invalid project status "${value}". Valid: ${PROJECT_STATUSES.join(", ")}`
+    );
+  }
+  return value;
+}
+function validateProjectPriority(value) {
+  if (!value) return void 0;
+  if (!PROJECT_PRIORITIES.includes(value)) {
+    throw new Error(
+      `Invalid project priority "${value}". Valid: ${PROJECT_PRIORITIES.join(", ")}`
+    );
+  }
+  return value;
+}
 function createProjectsCommand() {
   const projects = new Command17("projects").description("Manage projects");
-  projects.command("list").description("List all projects").option("--workspace <id>", "Filter by workspace ID").option("--include-actions", "Include actions in output").action(async (options, cmd) => {
+  projects.command("list").description("List all projects").option("--workspace <slug|id>", "Workspace slug or CUID").option("--include-actions", "Include actions in output").action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
     try {
       const client = getClient();
+      const workspaceId = options.workspace ? await resolveWorkspaceId(client, options.workspace) : void 0;
       const projects2 = await client.projects.list({
-        workspaceId: options.workspace,
+        workspaceId,
         includeActions: options.includeActions
       });
       if (useJson) {
@@ -4053,6 +4151,101 @@ function createProjectsCommand() {
       handleError(error, useJson);
     }
   });
+  projects.command("get <id>").description(
+    "Get one project with its objectives, key results, DRI and actions \u2014 none of which `projects list` carries. Accepts a CUID, a slug, or the slug-cuid form from app URLs."
+  ).action(async (id, _options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const client = getClient();
+      const project = await client.projects.get(id);
+      if (useJson) outputProjectJson(project);
+      else outputProjectPretty(project);
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
+  projects.command("update").description(
+    "Update a project. Only the fields you pass are written; the rest are read back from the project and re-sent unchanged."
+  ).requiredOption("--id <cuid>", "Project CUID").option("-n, --name <name>", "New name").option("-d, --description <text>", "New description").option("--status <status>", `Status: ${PROJECT_STATUSES.join(", ")}`).option("--priority <priority>", `Priority: ${PROJECT_PRIORITIES.join(", ")}`).option("--product <cuid|none>", 'Product to file the project under ("none" to unlink)').option("--dri <userId|none>", 'Directly responsible individual ("none" to clear)').action(
+    async (options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        const status = validateProjectStatus(options.status);
+        const priority = validateProjectPriority(options.priority);
+        const client = getClient();
+        const updated = await client.projects.update({
+          id: options.id,
+          name: options.name,
+          description: options.description,
+          status,
+          priority,
+          productId: options.product === void 0 ? void 0 : options.product === "none" ? null : options.product,
+          driId: options.dri === void 0 ? void 0 : options.dri === "none" ? null : options.dri
+        });
+        if (useJson) outputProjectJson(updated);
+        else {
+          console.log("\n\u2713 Project updated");
+          outputProjectPretty(updated);
+        }
+      } catch (error) {
+        handleError(error, useJson);
+      }
+    }
+  );
+  projects.command("delete").description(
+    "Delete a project. Refuses while it still has actions or is linked to an objective or key result, unless --force."
+  ).requiredOption("--id <cuid>", "Project CUID").option("--force", "Delete anyway, taking the actions and links with it").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+    try {
+      const client = getClient();
+      const project = await client.projects.get(options.id);
+      const actions = project.actions ?? [];
+      const goals = project.goals ?? [];
+      const keyResults = project.keyResults ?? [];
+      const blockers = [
+        actions.length ? `${actions.length} action(s)` : null,
+        goals.length ? `${goals.length} objective link(s)` : null,
+        keyResults.length ? `${keyResults.length} key result link(s)` : null
+      ].filter(Boolean);
+      if (blockers.length > 0 && !options.force) {
+        const payload2 = {
+          deleted: false,
+          id: project.id,
+          reason: `has ${blockers.join(", ")}`,
+          actionCount: actions.length,
+          goals: goals.map((g) => ({ id: g.id, title: g.title })),
+          keyResults: keyResults.map((k) => ({ id: k.keyResultId }))
+        };
+        if (useJson) console.log(JSON.stringify(payload2, null, 2));
+        else {
+          console.error(
+            `Project "${project.name}" has ${blockers.join(", ")}.
+Re-run with --force to delete it anyway.`
+          );
+        }
+        process.exitCode = 1;
+        return;
+      }
+      await client.projects.delete(project.id);
+      const payload = {
+        deleted: true,
+        id: project.id,
+        actionsDeleted: actions.length
+      };
+      if (useJson) console.log(JSON.stringify(payload, null, 2));
+      else {
+        console.log("\u2713 Project deleted");
+        if (actions.length) {
+          console.log(`  ${actions.length} action(s) went with it`);
+        }
+      }
+    } catch (error) {
+      handleError(error, useJson);
+    }
+  });
   return projects;
 }
 
@@ -4809,10 +5002,17 @@ function createKeyResultsCommand() {
       try {
         const status = validateKeyResultStatus(options.status);
         const client = getClient();
-        const workspaceId = options.workspace ? await resolveWorkspaceId(client, options.workspace) : void 0;
+        const goalId = options.goal ? parseGoalId(options.goal) : void 0;
+        let workspaceId;
+        if (options.workspace) {
+          workspaceId = await resolveWorkspaceId(client, options.workspace);
+        } else if (goalId !== void 0) {
+          const goal = await client.goals.get(goalId);
+          workspaceId = goal.workspaceId ?? void 0;
+        }
         const list = await client.goals.keyResults.list({
           workspaceId,
-          goalId: options.goal ? parseGoalId(options.goal) : void 0,
+          goalId,
           period: options.period,
           status,
           onlyMine: options.mine
@@ -5170,15 +5370,25 @@ function createGoalsCommand() {
   );
   goals.command("update").description(
     "Update an objective. Only the flags you pass are written \u2014 everything else is left exactly as it is. For a status change use `set-status`; to re-parent use `reparent`."
-  ).requiredOption("--id <n>", "Objective ID (a number)").option("-t, --title <text>", "New title").option("-d, --description <text>", 'New description ("none" clears it)').option("--why <text>", 'Why this goal matters ("none" clears it)').option("--period <period>", 'New period ("none" clears it)').option("--dri <userId>", "Directly responsible individual (user ID)").option("--status <status>", `Status: ${GOAL_WRITABLE_STATUSES.join(", ")}`).option("--project <cuid>", 'Replace the project links with this project ("none" clears them)').action(
+  ).requiredOption("--id <n>", "Objective ID (a number)").option("-t, --title <text>", "New title").option("-d, --description <text>", 'New description ("none" clears it)').option("--why <text>", 'Why this goal matters ("none" clears it)').option("--period <period>", 'New period ("none" clears it)').option("--dri <userId>", "Directly responsible individual (user ID)").option("--status <status>", `Status: ${GOAL_WRITABLE_STATUSES.join(", ")}`).option("--project <cuid>", 'Replace the project links with this project ("none" clears them)').option(
+    "-w, --workspace <slug|id|none>",
+    'Re-home the objective; "none" makes it personal'
+  ).action(
     async (options, cmd) => {
       const globalOpts = cmd.optsWithGlobals();
       const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
       try {
         const status = validateWritableGoalStatus(options.status);
         const clearable = (value) => value === void 0 ? void 0 : value === "none" ? null : value;
-        const goal = await getClient().goals.update({
+        const client = getClient();
+        let workspaceId;
+        if (options.workspace === "none") workspaceId = null;
+        else if (options.workspace !== void 0) {
+          workspaceId = await resolveWorkspaceId(client, options.workspace);
+        }
+        const goal = await client.goals.update({
           id: parseGoalId(options.id),
+          workspaceId,
           title: options.title,
           description: clearable(options.description),
           whyThisGoal: clearable(options.why),
@@ -5258,21 +5468,60 @@ function createGoalsCommand() {
       handleError(error, useJson);
     }
   });
-  goals.command("delete").description("Delete an objective").requiredOption("--id <n>", "Objective ID (a number)").action(async (options, cmd) => {
-    const globalOpts = cmd.optsWithGlobals();
-    const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
-    try {
-      const id = parseGoalId(options.id);
-      await getClient().goals.delete(id);
-      if (useJson) {
-        console.log(JSON.stringify({ deleted: true, id }, null, 2));
-      } else {
-        console.log("\u2713 Goal deleted");
+  goals.command("delete").description(
+    "Delete an objective. Refuses while it still has key results \u2014 deleting an objective deletes them too (KeyResult.goalId cascades), taking their check-in history with them."
+  ).requiredOption("--id <n>", "Objective ID (a number)").option(
+    "--with-key-results",
+    "Delete the objective and cascade-delete its key results (destructive)"
+  ).action(
+    async (options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);
+      try {
+        const id = parseGoalId(options.id);
+        const client = getClient();
+        const goal = await client.goals.get(id);
+        const keyResults = goal.keyResults ?? [];
+        const children = goal.childGoals ?? [];
+        if (keyResults.length > 0 && !options.withKeyResults) {
+          const payload2 = {
+            deleted: false,
+            id,
+            reason: `has ${keyResults.length} key result(s)`,
+            keyResults: keyResults.map((kr) => ({ id: kr.id }))
+          };
+          if (useJson) console.log(JSON.stringify(payload2, null, 2));
+          else {
+            console.error(
+              `Objective #${id} has ${keyResults.length} key result(s). Deleting it deletes them too.
+Re-run with --with-key-results to go ahead, or move them with \`goals kr update --id <cuid> --goal <other>\`.`
+            );
+          }
+          process.exitCode = 1;
+          return;
+        }
+        await client.goals.delete(id);
+        const payload = {
+          deleted: true,
+          id,
+          keyResultsDeleted: keyResults.map((kr) => ({ id: kr.id })),
+          childGoalsDetached: children.map((c) => ({ id: c.id, title: c.title }))
+        };
+        if (useJson) console.log(JSON.stringify(payload, null, 2));
+        else {
+          console.log("\u2713 Goal deleted");
+          if (keyResults.length) {
+            console.log(`  ${keyResults.length} key result(s) deleted with it`);
+          }
+          if (children.length) {
+            console.log(`  ${children.length} sub-goal(s) left detached`);
+          }
+        }
+      } catch (error) {
+        handleError(error, useJson);
       }
-    } catch (error) {
-      handleError(error, useJson);
     }
-  });
+  );
   goals.command("periods").description("List the conventional OKR period strings").action(async (_options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const useJson = shouldUseJson(globalOpts.json, globalOpts.pretty);