@networkbase/cli 2.1.1 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@ import crypto from "node:crypto";
3
3
  import fs from "node:fs";
4
4
  import path from "node:path";
5
5
 
6
- import { DIR_NAME, readUserConfig } from "../config.mjs";
6
+ import { DIR_NAME, readUserConfig, writeProjectConfig } from "../config.mjs";
7
7
  import { CliError, EXIT, usage } from "../errors.mjs";
8
8
  import { safe } from "../print/style.mjs";
9
9
  import { scanLocal, toRelative, toRemote } from "../sync/local.mjs";
@@ -19,6 +19,8 @@ import { branchTask, resolveTask } from "./tasks.mjs";
19
19
 
20
20
  /** Paths given on the command line, as paths relative to the linked folder. @param {Context} ctx @param {string} root */
21
21
  export function relativeArgs(ctx, root) {
22
+ // No paths given: the folders this copy keeps (C3, nb sync --only), or everything.
23
+ if (!ctx.positionals.length && ctx.project?.only?.length) return [...ctx.project.only];
22
24
  return ctx.positionals.map((p) => {
23
25
  const rel = path.relative(root, path.resolve(ctx.cwd, p));
24
26
  if (rel.startsWith("..") || path.isAbsolute(rel)) throw usage(`${p} is outside the linked folder ${root}`);
@@ -31,6 +33,8 @@ export function relativeArgs(ctx, root) {
31
33
  * @param {Context} ctx @param {{ only?: string[] }} [options]
32
34
  */
33
35
  export async function buildPlan(ctx, options = {}) {
36
+ // A copy that keeps only some folders (C3) plans just those, so status doesn't list the rest as server-only.
37
+ if (!options.only?.length && ctx.project?.only?.length) options = { ...options, only: ctx.project.only };
34
38
  const { root, project } = ctx.requireRoot();
35
39
  const state = readState(root, project.workspaceId);
36
40
  let offline = false;
@@ -77,9 +81,17 @@ export function recordBase(state, p, f) {
77
81
  /** @param {Context} ctx */
78
82
  export async function status(ctx) {
79
83
  // The day's counts ride along (C2 "a home screen in nb status"); offline or refused, status still works.
80
- const todayP = ctx.api.get("/api/v1/home").then((/** @type {any} */ h) => ({ dueThisWeek: h.tasks.dueThisWeek, overdue: h.tasks.overdue, unread: h.unread }), () => null);
84
+ const started = ctx.project?.startedTask?.id ?? null;
85
+ const homeP = ctx.api.get("/api/v1/home", { query: started ? { task: started } : {} }).then((/** @type {any} */ h) => h, () => null);
81
86
  const { root, project, items, skipped, offline, manifest } = await buildPlan(ctx);
82
- const today = await todayP;
87
+ const home = /** @type {any} */ (await homeP);
88
+ const today = home ? { dueThisWeek: home.tasks.dueThisWeek, overdue: home.tasks.overdue, unread: home.unread } : null;
89
+ // A started task deleted elsewhere (or no longer yours to see) stops being this folder's task (found in M4a).
90
+ if (started && home && home.currentTask === null) {
91
+ writeProjectConfig(root, { ...project, startedTask: null });
92
+ ctx.out.note(ctx.out.c.muted(`#${project.startedTask?.number ?? ""} was deleted (or you can't see it now), so no task is started here: nb task start <n>`));
93
+ project.startedTask = null;
94
+ }
83
95
  const changed = items.filter((i) => i.state !== "unchanged");
84
96
  const conflicts = changed.filter((i) => i.state === "conflict");
85
97
  const data = {
@@ -329,6 +341,11 @@ export async function push(ctx) {
329
341
  folder: ctx.flags.folder ?? null,
330
342
  confirmSecrets: Boolean(ctx.flags["confirm-secrets"]),
331
343
  keyBase,
344
+ // A big file shows how far it got (C3), on one line in a terminal.
345
+ onBytes: ctx.out.interactive && !ctx.out.json ? (p, sent, total) => {
346
+ const mb = (/** @type {number} */ n) => (n / 1024 / 1024).toFixed(1);
347
+ ctx.out.stderr.write(`\r\x1b[2K${ctx.out.c.muted(`Uploading ${safe(p)} ${mb(sent)} of ${mb(total)} MB`)}${sent >= total ? "\n" : ""}`);
348
+ } : undefined,
332
349
  }, (done, total) => { if (total > 1) ctx.out.note(ctx.out.c.muted(`Uploading ${done} of ${total}`)); }).catch((error) => handlePushError(ctx, root, state, error instanceof CliError && error.code === "OFFLINE" ? queueOffline() : error))
333
350
  : { files: [], transition: null };
334
351
 
@@ -413,6 +430,20 @@ function handlePushError(ctx, root, state, error) {
413
430
  /** Pull, then push changed tracked files; new files are pushed by naming them (report §17.4). @param {Context} ctx */
414
431
  export async function sync(ctx) {
415
432
  oldStatusFlags(ctx);
433
+ // `nb sync --only design/ docs/` remembers which folders this copy keeps; `--only all` goes back to everything (C3).
434
+ if (ctx.flags.only !== undefined) {
435
+ const { root, project } = ctx.requireRoot();
436
+ const raw = /** @type {string[]} */ ([ctx.flags.only].flat()).concat(ctx.positionals).flatMap((x) => String(x).split(",")).map((x) => x.trim()).filter(Boolean);
437
+ const only = raw.includes("all") ? [] : raw.map((p) => {
438
+ const rel = path.relative(root, path.resolve(ctx.cwd, p));
439
+ if (rel.startsWith("..") || path.isAbsolute(rel)) throw usage(`${p} is outside the linked folder ${root}`);
440
+ return rel;
441
+ });
442
+ writeProjectConfig(root, { ...project, only });
443
+ ctx.project = { ...project, only };
444
+ ctx.positionals = [];
445
+ ctx.out.note(only.length ? `This copy keeps ${only.map((o) => `${o}/`).join(", ")} in sync · nb sync --only all for everything` : "This copy keeps everything in sync");
446
+ }
416
447
  await replayQueue(ctx);
417
448
  const pulled = await pull(ctx, { quietResult: true });
418
449
  if (pulled === EXIT.conflict) {
@@ -4,7 +4,7 @@ import { execFile } from "node:child_process";
4
4
 
5
5
  import { CliError, EXIT, usage } from "../errors.mjs";
6
6
  import { safe } from "../print/style.mjs";
7
- import { formatDate } from "./tasks.mjs";
7
+ import { formatWhen } from "./tasks.mjs";
8
8
 
9
9
  /** @typedef {import("../context.mjs").Context} Context */
10
10
 
@@ -21,7 +21,7 @@ export async function inbox(ctx) {
21
21
  const { c, sym } = ctx.out;
22
22
  ctx.out.result("nb.inbox/1", { unread: p.unreadCount, items }, (d) => d.items.length ? [
23
23
  `${d.unread} unread`,
24
- ...d.items.map((i, n) => `${i.readAt ? " " : c.brand(sym.brand)} ${String(n + 1).padStart(2)} ${c.muted(formatDate(i.activityAt ?? i.createdAt))} ${safe(i.title)}${i.body ? c.muted(` · ${safe(String(i.body)).replace(/\n/g, " ").slice(0, 80)}`) : ""}`),
24
+ ...d.items.map((i, n) => `${i.readAt ? " " : c.brand(sym.brand)} ${String(n + 1).padStart(2)} ${c.muted(formatWhen(i.activityAt ?? i.createdAt))} ${i.href ? ctx.out.link(safe(i.title), new URL(i.href, ctx.profile.origin).toString(), ctx.profile.origin) : safe(i.title)}${i.body ? c.muted(` · ${safe(String(i.body)).replace(/\n/g, " ").slice(0, 80)}`) : ""}`),
25
25
  c.muted(" nb inbox reply <n> \"text\" · nb inbox approve <n> · nb inbox read <n> · nb inbox open <n>"),
26
26
  ] : "Nothing in your inbox", { page: true });
27
27
  }
@@ -59,7 +59,10 @@ export async function inboxReply(ctx) {
59
59
  if (!ref || !text) throw usage('nb inbox reply <n> "your reply"');
60
60
  const [item] = await pick({ ...ctx, positionals: [ref] });
61
61
  const refs = taskOf(item, ref);
62
- await ctx.api.post("/api/v1/extension/comments", { kind: "task", ...(refs.projectId ? { projectId: refs.projectId } : {}), taskId: refs.taskId, text, ...(refs.commentId ? { replyTo: refs.commentId } : {}) });
62
+ // @names become real mentions in the item's workspace (C4).
63
+ const { withMentions } = await import("./tasks.mjs");
64
+ const said = refs.projectId ? await withMentions({ ...ctx, requireWorkspace: () => /** @type {string} */ (refs.projectId) }, text) : text;
65
+ await ctx.api.post("/api/v1/extension/comments", { kind: "task", ...(refs.projectId ? { projectId: refs.projectId } : {}), taskId: refs.taskId, text: said, ...(refs.commentId ? { replyTo: refs.commentId } : {}) });
63
66
  await ctx.api.post("/api/v1/inbox/read", { ids: [item.id] });
64
67
  ctx.out.result("nb.inbox.reply/1", { item: item.id, taskId: refs.taskId }, () => `${ctx.out.c.success(ctx.out.sym.done)} Replied on ${safe(item.title)}`);
65
68
  }
@@ -128,3 +131,68 @@ async function follow(ctx) {
128
131
  }
129
132
  return EXIT.ok;
130
133
  }
134
+
135
+ // ───────────────────────────────── settings and mute (report C4, M4b): the same as Settings → Notifications
136
+
137
+ const CATEGORIES = ["mentions", "tasks", "workflows", "projects", "applications", "connections"];
138
+ const hhmm = (/** @type {number} */ m) => `${String(Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
139
+
140
+ /**
141
+ * `nb inbox settings` shows them; `--on tasks`, `--off projects`, `--quiet 22:00-08:00|off`, `--pause 2h|off` change
142
+ * only what's named.
143
+ * @param {Context} ctx
144
+ */
145
+ export async function inboxSettings(ctx) {
146
+ /** @type {Record<string, unknown>} */
147
+ const change = {};
148
+ const names = (/** @type {unknown} */ v) => /** @type {string[]} */ ([v ?? []].flat()).flatMap((x) => String(x).split(",")).map((x) => x.trim()).filter(Boolean);
149
+ for (const [flag, on] of /** @type {const} */ ([["on", true], ["off", false]])) {
150
+ for (const n of names(ctx.flags[flag])) {
151
+ if (!CATEGORIES.includes(n)) throw usage(`${n} isn't a kind of notification`, `Kinds: ${CATEGORIES.join(", ")}`);
152
+ change[n] = on;
153
+ }
154
+ }
155
+ if (ctx.flags.quiet !== undefined) {
156
+ const q = String(ctx.flags.quiet);
157
+ const m = /^(\d{1,2}):(\d{2})-(\d{1,2}):(\d{2})$/.exec(q);
158
+ if (q !== "off" && !m) throw usage("--quiet takes 22:00-08:00, or off");
159
+ change.quietHours = q === "off" ? { enabled: false, startMinute: 1320, endMinute: 480 } : { enabled: true, startMinute: Number(m?.[1]) * 60 + Number(m?.[2]), endMinute: Number(m?.[3]) * 60 + Number(m?.[4]), timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone };
160
+ }
161
+ if (ctx.flags.pause !== undefined) {
162
+ const p = String(ctx.flags.pause);
163
+ const m = /^(\d{1,3})(m|h|d)$/.exec(p);
164
+ if (p !== "off" && !m) throw usage("--pause takes 30m, 2h, 1d, or off");
165
+ change.pausedUntil = p === "off" ? null : new Date(Date.now() + Number(m?.[1]) * (m?.[2] === "d" ? 86_400_000 : m?.[2] === "h" ? 3_600_000 : 60_000)).toISOString();
166
+ }
167
+ const { preferences: p } = /** @type {any} */ (Object.keys(change).length ? await ctx.api.patch("/api/v1/me/notifications", change) : await ctx.api.get("/api/v1/me/notifications"));
168
+ const { c } = ctx.out;
169
+ ctx.out.result("nb.inbox.settings/1", p, (d) => [
170
+ ...CATEGORIES.map((k) => ` ${k.padEnd(13)}${d[k] ? c.success("on") : c.muted("off")}`),
171
+ ` quiet hours ${d.quietHours?.enabled ? `${hhmm(d.quietHours.startMinute)}–${hhmm(d.quietHours.endMinute)}` : c.muted("off")}`,
172
+ ` paused ${d.pausedUntil && Date.parse(d.pausedUntil) > Date.now() ? `until ${new Date(d.pausedUntil).toLocaleString()}` : c.muted("no")}`,
173
+ ` muted ${d.mutedScopes?.length ? d.mutedScopes.map((/** @type {any} */ s) => safe(s.label ?? `${s.kind} ${String(s.value).slice(0, 8)}`)).join(", ") : c.muted("nothing")}`,
174
+ c.muted(" nb inbox settings --off projects · --quiet 22:00-08:00 · --pause 2h · nb inbox mute <workspace|#task>"),
175
+ ]);
176
+ }
177
+
178
+ /** `nb inbox mute deepscope-ai` or `nb inbox mute #4`; `--off` unmutes. @param {Context} ctx */
179
+ export async function inboxMute(ctx) {
180
+ const ref = ctx.positionals[0];
181
+ if (!ref) throw usage("nb inbox mute <workspace|#task> [--off]");
182
+ /** @type {{ kind: "project" | "task", value: string, label: string }} */
183
+ let scope;
184
+ if (/^(#|T-)?\d+$/i.test(ref)) {
185
+ const { resolveTask } = await import("./tasks.mjs");
186
+ const t = await resolveTask(ctx, ref, { brief: true });
187
+ scope = { kind: "task", value: t.id, label: `#${t.taskNumber} ${t.title}`.slice(0, 200) };
188
+ } else {
189
+ const { workspaces } = /** @type {any} */ (await ctx.api.get("/api/v1/extension/workspaces"));
190
+ const w = workspaces.find((/** @type {any} */ x) => String(x.slug).toLowerCase() === ref.toLowerCase() || String(x.title).toLowerCase() === ref.toLowerCase());
191
+ if (!w) throw new CliError("WORKSPACE_NOT_FOUND", `No workspace ${ref} in your list`, { hint: "nb workspace list" });
192
+ scope = { kind: "project", value: w.id, label: w.title };
193
+ }
194
+ const { preferences } = /** @type {any} */ (await ctx.api.get("/api/v1/me/notifications"));
195
+ const others = (preferences.mutedScopes ?? []).filter((/** @type {any} */ s) => !(s.kind === scope.kind && s.value === scope.value));
196
+ await ctx.api.patch("/api/v1/me/notifications", { mutedScopes: ctx.flags.off ? others : [...others, scope] });
197
+ ctx.out.result("nb.inbox.mute/1", { ...scope, muted: !ctx.flags.off }, (d) => `${ctx.out.c.success(ctx.out.sym.done)} ${d.muted ? "Muted" : "Unmuted"} ${safe(d.label)}`);
198
+ }
@@ -47,11 +47,43 @@ export async function help(ctx) {
47
47
  ctx.out.result("nb.help/1", helpData(), () => overviewHelp(process.stdout.columns), { page: true });
48
48
  return;
49
49
  }
50
+ // A topic (C5): how a part of nb fits together.
51
+ const { TOPICS } = await import("../help-topics.mjs");
52
+ const topic = TOPICS[name];
53
+ if (topic) {
54
+ ctx.out.result("nb.help.topic/1", { topic: name, ...topic }, (d) => [ctx.out.c.bold(d.title), "", ...d.lines.map((/** @type {string} */ l) => ` ${l}`), "", "Examples", ...d.examples.map((/** @type {string} */ e) => ` ${e}`)]);
55
+ return;
56
+ }
50
57
  const spec = COMMANDS.find((c) => c.name === name);
51
- if (!spec) throw usage(`No command called nb ${name}`, "See nb help");
58
+ if (!spec) throw usage(`No command or topic called ${name}`, `See nb help, or a topic: ${Object.keys(TOPICS).join(", ")}`);
52
59
  ctx.out.result("nb.help.command/1", helpData().commands.find((c) => c.name === name), () => commandHelp(spec));
53
60
  }
54
61
 
62
+ /**
63
+ * How nb was installed (C5 `nb upgrade`), from where its own script lives.
64
+ * @param {string} script process.argv[1] @returns {"npx" | "npm" | "other"}
65
+ */
66
+ export function installMethod(script) {
67
+ const s = script.split("\\").join("/");
68
+ if (/\/_npx\//.test(s)) return "npx";
69
+ if (/\/node_modules\/@networkbase\/cli\//.test(s)) return "npm";
70
+ return "other";
71
+ }
72
+
73
+ /** `nb upgrade` (C5): updates the CLI the way it was installed; npx needs nothing. Asks first. @param {Context} ctx */
74
+ export async function upgrade(ctx) {
75
+ const how = installMethod(fs.realpathSync(process.argv[1] ?? ""));
76
+ const command = "npm i -g @networkbase/cli@latest";
77
+ if (how === "npx") return ctx.out.result("nb.upgrade/1", { how, command: null }, () => "npx runs the latest nb each time: nothing to update");
78
+ if (how === "other" || ctx.flags["dry-run"]) return ctx.out.result("nb.upgrade/1", { how, command }, (d) => (d.how === "other" ? [`This nb wasn't installed with npm (${safe(process.argv[1] ?? "")}).`, ` To use npm: ${command}`] : `Would run: ${command}`));
79
+ const { confirm } = await import("../tui/ask.mjs");
80
+ if (!(await confirm(ctx, { key: "upgrade", question: `Update nb ${ctx.version} to the latest?`, preview: command, yesLabel: "Update", defaultYes: true }))) return 130;
81
+ const { spawnSync } = await import("node:child_process");
82
+ const run = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", ["i", "-g", "@networkbase/cli@latest"], { stdio: "inherit", shell: process.platform === "win32" });
83
+ if (run.status !== 0) throw new CliError("UPGRADE_FAILED", "npm couldn't update nb", { hint: `Run it yourself: ${command}` });
84
+ ctx.out.result("nb.upgrade/1", { how, command, updated: true }, () => `${ctx.out.c.success(ctx.out.sym.done)} Updated nb · nb --version`);
85
+ }
86
+
55
87
  /** @param {Context} ctx */
56
88
  export async function version(ctx) {
57
89
  let server = null;
@@ -74,10 +106,16 @@ export async function completion(ctx) {
74
106
  const [head, sub] = c.name.split(" ");
75
107
  if (sub && head) (subs[head] ??= []).push(sub);
76
108
  }
109
+ // Real names after a command that takes a task, a person or a file (C8): `nb complete <kind>` answers from a cache.
110
+ const { ARG_KINDS } = await import("./complete.mjs");
111
+ const oneWord = Object.entries(ARG_KINDS).filter(([k]) => !k.includes(" "));
112
+ const twoWords = Object.entries(ARG_KINDS).filter(([k]) => k.includes(" "));
113
+ const caseOf = (/** @type {Array<[string, string]>} */ list, /** @type {(kind: string) => string} */ run) => list.map(([k, kind]) => ` "${k}") ${run(kind)};;`).join("\n");
77
114
  const scripts = /** @type {Record<string, string>} */ ({
78
- zsh: `#compdef nb\n_nb() {\n local -a cmds\n if (( CURRENT == 2 )); then cmds=(${names.join(" ")}); _describe 'command' cmds; return; fi\n case $words[2] in\n${Object.entries(subs).map(([h, s]) => ` ${h}) cmds=(${s.join(" ")}); _describe 'subcommand' cmds;;`).join("\n")}\n esac\n}\ncompdef _nb nb`,
79
- bash: `_nb() {\n local cur=\${COMP_WORDS[COMP_CWORD]}\n if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${names.join(" ")}" -- "$cur")); return; fi\n case \${COMP_WORDS[1]} in\n${Object.entries(subs).map(([h, s]) => ` ${h}) COMPREPLY=($(compgen -W "${s.join(" ")}" -- "$cur"));;`).join("\n")}\n esac\n}\ncomplete -F _nb nb`,
80
- fish: [`complete -c nb -f -n '__fish_use_subcommand' -a '${names.join(" ")}'`, ...Object.entries(subs).map(([h, s]) => `complete -c nb -f -n '__fish_seen_subcommand_from ${h}' -a '${s.join(" ")}'`)].join("\n"),
115
+ zsh: `#compdef nb\n_nb() {\n local -a cmds names\n if (( CURRENT == 2 )); then cmds=(${names.join(" ")}); _describe 'command' cmds; return; fi\n local kind=""\n case "$words[2]" in\n${caseOf(oneWord, (k) => `kind=${k}`)}\n esac\n if (( CURRENT >= 4 )) || [[ -n $kind ]]; then\n case "$words[2] $words[3]" in\n${caseOf(twoWords, (k) => `kind=${k}`)}\n esac\n fi\n if [[ -n $kind ]] && (( CURRENT >= 3 )); then names=(\${(f)"$(nb complete $kind 2>/dev/null | tr '\\t' ':')"}); _describe 'name' names; return; fi\n case $words[2] in\n${Object.entries(subs).map(([h, s]) => ` ${h}) cmds=(${s.join(" ")}); _describe 'subcommand' cmds;;`).join("\n")}\n esac\n}\ncompdef _nb nb`,
116
+ bash: `_nb() {\n local cur=\${COMP_WORDS[COMP_CWORD]} kind=""\n if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${names.join(" ")}" -- "$cur")); return; fi\n case "\${COMP_WORDS[1]}" in\n${caseOf(oneWord, (k) => `kind=${k}`)}\n esac\n if [ "$COMP_CWORD" -ge 3 ]; then case "\${COMP_WORDS[1]} \${COMP_WORDS[2]}" in\n${caseOf(twoWords, (k) => `kind=${k}`)}\n esac; fi\n if [ -n "$kind" ]; then COMPREPLY=($(nb complete "$kind" "$cur" 2>/dev/null | cut -f1)); return; fi\n case \${COMP_WORDS[1]} in\n${Object.entries(subs).map(([h, s]) => ` ${h}) COMPREPLY=($(compgen -W "${s.join(" ")}" -- "$cur"));;`).join("\n")}\n esac\n}\ncomplete -F _nb nb`,
117
+ fish: [`complete -c nb -f -n '__fish_use_subcommand' -a '${names.join(" ")}'`, ...Object.entries(subs).map(([h, s]) => `complete -c nb -f -n '__fish_seen_subcommand_from ${h}' -a '${s.join(" ")}'`),
118
+ ...Object.entries(ARG_KINDS).map(([k, kind]) => { const [h, s] = k.split(" "); return `complete -c nb -f -n '__fish_seen_subcommand_from ${h}${s ? `; and __fish_seen_subcommand_from ${s}` : ""}' -a '(nb complete ${kind} 2>/dev/null)'`; })].join("\n"),
81
119
  powershell: `Register-ArgumentCompleter -Native -CommandName nb -ScriptBlock {\n param($word, $ast)\n $parts = $ast.CommandElements | ForEach-Object { $_.ToString() }\n $subs = @{ ${Object.entries(subs).map(([h, s]) => `'${h}' = @('${s.join("','")}')`).join("; ")} }\n $list = if ($parts.Count -le 2) { @('${names.join("','")}') } else { $subs[$parts[1]] }\n $list | Where-Object { $_ -like "$word*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }\n}`,
82
120
  });
83
121
  if (!shell || !scripts[shell]) throw usage("Choose a shell: nb completion zsh|bash|fish|powershell");
@@ -89,6 +127,9 @@ const SETTINGS = /** @type {Record<string, { describe: string, check: (v: string
89
127
  editor: { describe: "Editor for nb doc edit and -m with no text", check: (v) => v.length > 0 },
90
128
  "base-cache-mb": { describe: "Space for offline diff copies (MB)", check: (v) => /^\d+$/.test(v) },
91
129
  presence: { describe: "Show teammates what you're editing: on or off", check: (v) => v === "on" || v === "off" },
130
+ // A company network (report C6): its proxy and its own certificates.
131
+ proxy: { describe: "Proxy for every request, like http://proxy.corp:8080 (Node 22.21+ or 24+)", check: (v) => /^https?:\/\/[^\s]+$/.test(v) },
132
+ "ca-file": { describe: "Extra certificates (a PEM file) your company network needs", check: (v) => v.length > 0 && fs.existsSync(v) },
92
133
  });
93
134
 
94
135
  /** @param {Context} ctx */
@@ -119,6 +160,8 @@ export function openInBrowser(url) {
119
160
  /** @param {Context} ctx */
120
161
  export async function open(ctx) {
121
162
  const target = ctx.positionals[0];
163
+ // --code (C10): the file in VS Code or Cursor, from this linked folder.
164
+ if (ctx.flags.code) return openInCode(ctx, target);
122
165
  const slug = ctx.project?.slug ?? ctx.flags.workspace;
123
166
  if (!slug) throw new CliError("NOT_LINKED", "No workspace to open", { hint: "Run nb init <workspace>, or pass --workspace" });
124
167
  const base = `${ctx.profile.origin}/workspaces/${encodeURIComponent(slug)}`;
@@ -127,6 +170,62 @@ export async function open(ctx) {
127
170
  ctx.out.result("nb.open/1", { url, opened }, (d) => (d.opened ? `Opened ${d.url}` : `Open ${d.url}`));
128
171
  }
129
172
 
173
+ /** Which of Cursor and VS Code is on PATH (Cursor first: it's the one people pick when they have both). @param {NodeJS.ProcessEnv} env */
174
+ function codeEditor(env) {
175
+ const dirs = String(env.PATH ?? "").split(path.delimiter).filter(Boolean);
176
+ const names = process.platform === "win32" ? ["cursor.cmd", "code.cmd"] : ["cursor", "code"];
177
+ for (const name of names) for (const dir of dirs) if (fs.existsSync(path.join(dir, name))) return path.join(dir, name);
178
+ return null;
179
+ }
180
+
181
+ /** @param {Context} ctx @param {string | undefined} target */
182
+ async function openInCode(ctx, target) {
183
+ const { root } = ctx.requireRoot();
184
+ const editor = codeEditor(ctx.env);
185
+ if (!editor) throw new CliError("NOT_FOUND", "Neither VS Code nor Cursor is on your PATH", { hint: "In VS Code: Command Palette → \"Shell Command: Install 'code' command in PATH\"" });
186
+ const file = target ? path.resolve(ctx.cwd, target) : root;
187
+ if (target && !path.relative(root, file).split(path.sep).every((s) => s !== "..")) throw usage(`${target} is outside the linked folder ${root}`);
188
+ const { spawn } = await import("node:child_process");
189
+ // The folder too, so the editor opens in this workspace's window.
190
+ spawn(editor, target ? [root, file] : [root], { detached: true, stdio: "ignore", shell: process.platform === "win32" }).unref();
191
+ ctx.out.result("nb.open.code/1", { editor: path.basename(editor).replace(/\.cmd$/, ""), path: file }, (d) => `Opened ${safe(path.relative(root, d.path) || ".")} in ${d.editor === "cursor" ? "Cursor" : "VS Code"}`);
192
+ }
193
+
194
+ /**
195
+ * `nb uninstall` (C14): signs out (revoking this sign-in), deletes ~/.networkbase (sign-ins, caches, settings) and the
196
+ * lines nb setup shell added, then says how to remove the package itself. Linked folders keep their .networkbase
197
+ * (nb unlink in each). Asks first.
198
+ * @param {Context} ctx
199
+ */
200
+ export async function uninstall(ctx) {
201
+ const { confirm } = await import("../tui/ask.mjs");
202
+ const { globalDir } = await import("../config.mjs");
203
+ const dir = globalDir(ctx.env);
204
+ if (!(await confirm(ctx, { key: "uninstall", question: `Sign out and delete ${dir} (sign-ins, caches, settings)?`, yesLabel: "Uninstall", defaultYes: false }))) return 130;
205
+ let signedOut = false;
206
+ if (ctx.profile.token && ctx.profile.profile?.source !== "env") {
207
+ signedOut = await ctx.api.post("/api/v1/extension/session", {}).then(() => true, () => false);
208
+ }
209
+ fs.rmSync(dir, { recursive: true, force: true });
210
+ /** @type {string[]} */
211
+ const cleaned = [];
212
+ for (const rc of Object.values(RC)) {
213
+ const file = rc.file(os.homedir());
214
+ if (!fs.existsSync(file)) continue;
215
+ const text = fs.readFileSync(file, "utf8");
216
+ const kept = text.split("\n").filter((l) => l !== "# NetworkBase CLI" && l !== rc.line && l !== rc.prompt);
217
+ if (kept.length !== text.split("\n").length) { fs.writeFileSync(file, kept.join("\n")); cleaned.push(file); }
218
+ }
219
+ const how = installMethod(fs.realpathSync(process.argv[1] ?? ""));
220
+ const remove = how === "npm" ? "npm rm -g @networkbase/cli" : how === "npx" ? null : "Remove nb the way you installed it";
221
+ ctx.out.result("nb.uninstall/1", { signedOut, removed: dir, shellFiles: cleaned, remove }, (d) => [
222
+ `${ctx.out.c.success(ctx.out.sym.done)} ${d.signedOut ? "Signed out (the sign-in is revoked), and deleted" : "Deleted"} ${safe(d.removed)}`,
223
+ ...d.shellFiles.map((/** @type {string} */ f) => ` Removed nb's lines from ${safe(f)}`),
224
+ ...(d.remove ? [` Last step: ${d.remove}`] : [" npx keeps nothing installed: you're done"]),
225
+ ctx.out.c.muted(" Linked folders keep their .networkbase folder; nb unlink in each removes it"),
226
+ ]);
227
+ }
228
+
130
229
  /** Health checks with a next step each (A6.4). @param {Context} ctx */
131
230
  export async function doctor(ctx) {
132
231
  const checks = await runChecks(ctx);
@@ -244,8 +343,11 @@ async function runChecks(ctx) {
244
343
  add("Version", !(latest && newer(latest, ctx.version)), latest && newer(latest, ctx.version) ? `${ctx.version}; ${latest} is out` : ctx.version, latest && newer(latest, ctx.version) ? "npm i -g @networkbase/cli" : "");
245
344
 
246
345
  // Proxy and company certificates (A6.4): Node ignores HTTPS_PROXY unless told to.
247
- const proxy = ctx.env.HTTPS_PROXY || ctx.env.https_proxy || ctx.env.HTTP_PROXY || ctx.env.http_proxy;
248
- if (proxy) add("Proxy", Boolean(ctx.env.NODE_USE_ENV_PROXY), ctx.env.NODE_USE_ENV_PROXY ? "used (NODE_USE_ENV_PROXY=1)" : "set but Node won't use it", ctx.env.NODE_USE_ENV_PROXY ? "" : "export NODE_USE_ENV_PROXY=1");
346
+ // nb turns NODE_USE_ENV_PROXY on itself (C6, lib/network.mjs); Node's fetch can only follow a proxy from 22.21 and 24.
347
+ const { proxyCapable } = await import("../network.mjs");
348
+ const proxy = readUserConfig(ctx.env).proxy || ctx.env.HTTPS_PROXY || ctx.env.https_proxy || ctx.env.HTTP_PROXY || ctx.env.http_proxy;
349
+ const canProxy = proxyCapable(process.versions.node);
350
+ if (proxy) add("Proxy", canProxy, canProxy ? `through ${proxy}` : `${proxy} is set, but Node ${process.versions.node} can't use it`, canProxy ? "" : "Install Node 22 LTS (22.21 or later) or Node 24");
249
351
  const ca = ctx.env.NODE_EXTRA_CA_CERTS;
250
352
  if (ca) add("Certificates", fs.existsSync(ca), fs.existsSync(ca) ? `extra certificates from ${ca}` : `NODE_EXTRA_CA_CERTS points to a missing file: ${ca}`, fs.existsSync(ca) ? "" : "Fix the path or unset it");
251
353
 
@@ -12,10 +12,15 @@ import { buildPlan, localPathOf, moveToLocalTrash, recordBase, relativeArgs } fr
12
12
 
13
13
  /** @typedef {import("../context.mjs").Context} Context */
14
14
 
15
+ /** One diff line, coloured. @param {any} c @param {{ kind: string, text: string }} l */
16
+ const paint = (c, l) => (l.kind === "@" ? c.muted(l.text) : l.kind === "+" ? c.success(`+${safe(l.text)}`) : l.kind === "-" ? c.danger(`-${safe(l.text)}`) : ` ${safe(l.text)}`);
17
+
15
18
  // ───────────────────────────────── diff
16
19
 
17
20
  /** @param {Context} ctx */
18
21
  export async function diff(ctx) {
22
+ // Two server versions (C3): nb diff report.md --from v1 --to v3 (--to defaults to the active one).
23
+ if (ctx.flags.from) return versionDiff(ctx);
19
24
  const { root } = ctx.requireRoot();
20
25
  const plan = await buildPlan(ctx, { only: relativeArgs(ctx, root) });
21
26
  const changed = plan.items.filter((i) => i.local && (i.state === "modified" || i.state === "conflict" || i.state === "added"));
@@ -35,12 +40,36 @@ export async function diff(ctx) {
35
40
  lines.push(c.bold(`${f.state === "added" ? "new" : f.state}: ${safe(f.path)}`));
36
41
  if (f.binary) { lines.push(c.muted(" binary file changed")); continue; }
37
42
  if (!f.diff) { lines.push(c.muted(" no saved copy of the last-pulled version to compare (it was large, or pulled before 2.0)")); continue; }
38
- for (const l of f.diff.lines) lines.push(l.kind === "@" ? c.muted(l.text) : l.kind === "+" ? c.success(`+${safe(l.text)}`) : l.kind === "-" ? c.danger(`-${safe(l.text)}`) : ` ${safe(l.text)}`);
43
+ for (const l of f.diff.lines) lines.push(paint(c, l));
39
44
  }
40
45
  return lines;
41
46
  });
42
47
  }
43
48
 
49
+ /** @param {Context} ctx */
50
+ async function versionDiff(ctx) {
51
+ const p = ctx.positionals[0];
52
+ if (!p) throw usage("nb diff <path> --from v1 [--to v3]");
53
+ const num = (/** @type {unknown} */ v) => Number(String(v ?? "").replace(/^v/i, ""));
54
+ const { nodeOf } = await import("./browse.mjs");
55
+ const node = await nodeOf(ctx, p);
56
+ const nodeId = node.nodeId ?? node.id;
57
+ const projectId = ctx.requireWorkspace();
58
+ const from = num(ctx.flags.from);
59
+ let to = ctx.flags.to ? num(ctx.flags.to) : null;
60
+ if (to === null) to = (/** @type {any} */ (await ctx.api.get("/api/v1/extension/file-history", { query: { projectId, nodeId } }))).activeVersion;
61
+ if (!Number.isInteger(from) || from < 1 || !Number.isInteger(to) || /** @type {number} */ (to) < 1) throw usage("Versions look like v1, v3", "See them: nb file history <path>");
62
+ const read = async (/** @type {number} */ v) => /** @type {any} */ (await ctx.api.get("/api/v1/extension/file-history", { query: { projectId, nodeId, version: v } })).content;
63
+ const [a, b] = await Promise.all([read(from), read(/** @type {number} */ (to))]);
64
+ const binary = String(a).includes("\u0000") || String(b).includes("\u0000");
65
+ const result = binary ? null : unifiedDiff(String(a), String(b));
66
+ const { c } = ctx.out;
67
+ ctx.out.result("nb.diff.versions/1", { path: node.path ?? p, from, to, binary, diff: result }, (d) => [
68
+ c.bold(`${safe(d.path)}: v${d.from} → v${d.to}`),
69
+ ...(d.binary ? [c.muted(" binary file: no line diff")] : !d.diff?.lines.length ? [c.muted(" the same content")] : d.diff.lines.map((/** @type {any} */ l) => paint(c, l))),
70
+ ]);
71
+ }
72
+
44
73
  // ───────────────────────────────── resolve
45
74
 
46
75
  /** @param {Context} ctx */
@@ -20,6 +20,8 @@ export const GLOBAL_FLAGS = {
20
20
  profile: { type: "string", describe: "Account profile (several accounts or servers)", valueName: "name" },
21
21
  "api-url": { type: "string", describe: "Server for this profile", valueName: "url" },
22
22
  confirm: { type: "string", describe: "The yes for a change held for confirmation (exit 7 gives the token)", valueName: "token" },
23
+ "dry-run": { type: "boolean", describe: "Show what would change, and change nothing" },
24
+ format: { type: "string", describe: "Lists as table (default), json, csv or md", valueName: "table|json|csv|md" },
23
25
  help: { type: "boolean", short: "h", describe: "Help for this command" },
24
26
  };
25
27
 
@@ -40,6 +42,8 @@ const FILTERS = {
40
42
  sprint: { type: "string", describe: "A sprint name, current, or id", valueName: "sprint" },
41
43
  priority: { type: "string", describe: "low,medium,high,urgent", valueName: "list" },
42
44
  sort: { type: "string", describe: "due, priority or updated (default)", valueName: "by" },
45
+ label: { type: "string", describe: "Only tasks with this label", valueName: "label" },
46
+ starred: { type: "boolean", describe: "Only tasks you starred" },
43
47
  };
44
48
  /** 1.x status flags: still accepted so old scripts run, never shown (P2.9). @type {Record<string, FlagSpec>} */
45
49
  const OLD_STATUS = {
@@ -72,10 +76,13 @@ export const COMMANDS = [
72
76
  { group: "Account and setup", name: "status", summary: "What changed here, the started task, conflicts", usage: "nb status", module: "files", fn: "status", exit: [0, 3, 4, 8] },
73
77
  { group: "Account and setup", name: "doctor", summary: "Check sign-in, server, link, Node and this folder", usage: "nb doctor [--repair]", module: "misc", fn: "doctor",
74
78
  flags: { repair: { type: "boolean", describe: "Fix what can be fixed (lock, temp files)" } } },
75
- { group: "Account and setup", name: "open", summary: "Open the workspace, a task or a file in the browser", usage: "nb open [task|path]", module: "misc", fn: "open" },
79
+ { group: "Account and setup", name: "open", summary: "Open the workspace, a task or a file in the browser (--code: in VS Code or Cursor)", usage: "nb open [task|path] [--code]", module: "misc", fn: "open", flags: { code: { type: "boolean", describe: "Open the file in VS Code or Cursor instead" } } },
80
+ { group: "Account and setup", name: "uninstall", summary: "Sign out and remove nb's data and shell lines (asks first)", usage: "nb uninstall", module: "misc", fn: "uninstall", exit: [0, 7, 130] },
76
81
  { group: "Account and setup", name: "version", summary: "CLI, Node and server versions", usage: "nb version", module: "misc", fn: "version" },
82
+ { group: "Account and setup", name: "complete", hidden: true, summary: "Names for tab completion (from a 10-minute cache)", usage: "nb complete tasks|members|files [prefix]", module: "complete", fn: "complete", flags: { refresh: { type: "boolean", describe: "Update the cache now" } } },
77
83
  { group: "Account and setup", name: "home", hidden: true, summary: "Where you are and what to do next", usage: "nb", module: "misc", fn: "home", exit: [0, 3, 4, 8] },
78
- { group: "Account and setup", name: "help", summary: "Help for a command", usage: "nb help [command]", module: "misc", fn: "help" },
84
+ { group: "Account and setup", name: "help", summary: "Help for a command, or a topic: files, agents, classes, sign-in, offline", usage: "nb help [command|topic]", module: "misc", fn: "help" },
85
+ { group: "Account and setup", name: "upgrade", summary: "Update nb the way it was installed (asks first)", usage: "nb upgrade [--dry-run]", module: "misc", fn: "upgrade", flags: { "dry-run": { type: "boolean", describe: "Show the command, run nothing" } } },
79
86
  { group: "Account and setup", name: "completion", summary: "Shell completion script", usage: "nb completion zsh|bash|fish|powershell", module: "misc", fn: "completion" },
80
87
  { group: "Account and setup", name: "setup shell", summary: "Add completions to your shell (asks first)", usage: "nb setup shell [zsh|bash|fish|powershell]", module: "misc", fn: "setupShell" },
81
88
  { group: "Account and setup", name: "prompt", summary: "Workspace and task for your shell prompt", usage: "nb prompt", module: "misc", fn: "prompt", hidden: true },
@@ -84,9 +91,10 @@ export const COMMANDS = [
84
91
  { group: "Account and setup", name: "config", summary: "Show or change settings", usage: "nb config list | get <key> | set <key> <value>", module: "misc", fn: "config" },
85
92
 
86
93
  // Files
87
- { group: "Files", name: "undo", summary: "Undo your last change from this machine (24 hours)", usage: "nb undo [token] [--list]", module: "undo", fn: "undo",
94
+ { group: "Files", name: "undo", summary: "Undo your last change from this machine (24 hours)", usage: "nb undo [n|token] [--list]", module: "undo", fn: "undo",
88
95
  flags: { list: { type: "boolean", describe: "Changes you can undo, newest first" }, session: { type: "boolean", describe: "Everything this agent session did (inside nb mcp)" } }, exit: [0, 1, 4] },
89
- { group: "Files", name: "diff", summary: "Changes against the version you last pulled", usage: "nb diff [path...]", module: "resolve", fn: "diff" },
96
+ { group: "Files", name: "diff", summary: "Changes against the version you last pulled, or between two versions", usage: "nb diff [path...] | nb diff <path> --from v1 [--to v3]", module: "resolve", fn: "diff",
97
+ flags: { from: { type: "string", describe: "Compare this server version…", valueName: "vN" }, to: { type: "string", describe: "…with this one (default: the active one)", valueName: "vN" } } },
90
98
  { group: "Files", name: "pull", summary: "Download changes; never overwrites your edits", usage: "nb pull [path...]", module: "files", fn: "pull", flags: { ...DRY }, exit: [0, 4, 8] },
91
99
  { group: "Files", name: "push", summary: "Upload changes; same path = new version", usage: "nb push <path...> [--task 4 --as draft] [-m text]", module: "files", fn: "push",
92
100
  flags: { ...TASK, ...AS, ...MESSAGE, ...DRY, ...OLD_STATUS,
@@ -102,19 +110,34 @@ export const COMMANDS = [
102
110
  { group: "Files", name: "queue", summary: "Pushes waiting to send while offline: what, since when, why", usage: "nb queue", module: "files", fn: "queue" },
103
111
  { group: "Files", name: "queue retry", summary: "Send the queued pushes now", usage: "nb queue retry", module: "files", fn: "queueRetry", exit: [0, 4, 8] },
104
112
  { group: "Files", name: "queue drop", summary: "Forget queued pushes (your files stay as they are)", usage: "nb queue drop <n…> | --all", module: "files", fn: "queueDrop", flags: { all: { type: "boolean", describe: "Every queued push" } } },
105
- { group: "Files", name: "sync", summary: "Pull, then push changed tracked files", usage: "nb sync", module: "files", fn: "sync", flags: { ...MESSAGE, ...OLD_STATUS }, exit: [0, 4, 8] },
113
+ { group: "Files", name: "sync", summary: "Pull, then push changed tracked files", usage: "nb sync [--only design/ docs/ | --only all]", module: "files", fn: "sync", flags: { ...MESSAGE, ...OLD_STATUS, only: { type: "string", multiple: true, describe: "Keep only these folders in sync from now on (all = everything)", valueName: "folder" } }, exit: [0, 4, 8] },
106
114
  { group: "Files", name: "resolve", summary: "Settle a conflict", usage: "nb resolve <path> --mine|--theirs|--both", module: "resolve", fn: "resolve",
107
115
  flags: { mine: { type: "boolean", describe: "Keep yours and push it" }, theirs: { type: "boolean", describe: "Take the server's version" }, both: { type: "boolean", describe: "Keep both as separate files" } } },
108
116
  { group: "Files", name: "watch", summary: "Push your saves as drafts; pull teammates' changes (foreground)", usage: "nb watch [--no-pull]", module: "watch", fn: "watch",
109
- flags: { "no-pull": { type: "boolean", describe: "Only push; don't pull other people's changes" } } },
117
+ flags: { "no-pull": { type: "boolean", describe: "Only push; don't pull other people's changes" }, inbox: { type: "boolean", describe: "Also show your notifications as they come" } } },
110
118
  { group: "Account and setup", name: "inbox", summary: "Your notifications, as in the app", usage: "nb inbox [--unread] [--follow [--notify]]", module: "inbox", fn: "inbox",
111
119
  flags: { unread: { type: "boolean", describe: "Only unread" }, follow: { type: "boolean", describe: "Keep waiting and print new ones" }, notify: { type: "boolean", describe: "With --follow: also a desktop notification" } },
112
120
  examples: ["nb inbox --unread", "nb inbox --follow --notify"] },
113
121
  { group: "Account and setup", name: "inbox read", summary: "Mark inbox items read", usage: "nb inbox read <n…> | --all", module: "inbox", fn: "inboxRead", flags: { all: { type: "boolean", describe: "Every unread item" } } },
114
122
  { group: "Account and setup", name: "inbox reply", summary: "Reply on an inbox item's task", usage: "nb inbox reply <n> \"text\"", module: "inbox", fn: "inboxReply", flags: { ...MESSAGE }, examples: ["nb inbox reply 1 \"fixed, thanks\""] },
115
123
  { group: "Account and setup", name: "inbox approve", summary: "Approve the task an inbox item asks you to review", usage: "nb inbox approve <n>", module: "inbox", fn: "inboxApprove" },
124
+ { group: "Account and setup", name: "inbox settings", summary: "Which notifications you get, quiet hours, pause", usage: "nb inbox settings [--on kinds] [--off kinds] [--quiet 22:00-08:00|off] [--pause 2h|off]", module: "inbox", fn: "inboxSettings",
125
+ flags: { on: { type: "string", multiple: true, describe: "Turn kinds on: mentions, tasks, workflows, projects, applications, connections", valueName: "kinds" }, off: { type: "string", multiple: true, describe: "Turn kinds off", valueName: "kinds" },
126
+ quiet: { type: "string", describe: "Quiet hours, like 22:00-08:00, or off", valueName: "hours" }, pause: { type: "string", describe: "Pause for 30m, 2h, 1d, or off", valueName: "time" } } },
127
+ { group: "Account and setup", name: "inbox mute", summary: "Mute a workspace or a task (--off to unmute)", usage: "nb inbox mute <workspace|#task> [--off]", module: "inbox", fn: "inboxMute", flags: { off: { type: "boolean", describe: "Unmute" } } },
116
128
  { group: "Account and setup", name: "inbox open", summary: "Open an inbox item in the browser", usage: "nb inbox open <n>", module: "inbox", fn: "inboxOpen" },
117
- { group: "Files", name: "file list", summary: "Files in the workspace", usage: "nb file list [folder] [--task 4]", module: "docs", fn: "fileList", flags: { ...TASK } },
129
+ { group: "Files", name: "file list", summary: "Files in the workspace", usage: "nb file list [folder] [--task 4] [--starred]", module: "docs", fn: "fileList", flags: { ...TASK, starred: { type: "boolean", describe: "Only files you starred (the same as the Files tab)" } } },
130
+ { group: "Files", name: "file trash", summary: "What's in the workspace Trash, with days left", usage: "nb file trash [name]", module: "browse", fn: "fileTrash" },
131
+ { group: "Files", name: "file restore", summary: "Bring a file back from the Trash", usage: "nb file restore <path>", module: "browse", fn: "fileRestore" },
132
+ { group: "Files", name: "file mkdir", summary: "Make a folder in the workspace", usage: "nb file mkdir <folder>", module: "browse", fn: "fileMkdir" },
133
+ { group: "Files", name: "file copy", summary: "Copy a file to a new path (a new file, same content)", usage: "nb file copy <file> <to>", module: "browse", fn: "fileCopy" },
134
+ { group: "Files", name: "file lock", summary: "Show teammates you're editing a file, until Ctrl+C or --for", usage: "nb file lock <path> [--for 30m]", module: "browse", fn: "fileLock",
135
+ flags: { for: { type: "string", describe: "How long: 30s, 10m, 2h (default: until Ctrl+C)", valueName: "time" } } },
136
+ { group: "Files", name: "edit", summary: "Edit a file in your editor; a new version when it closes", usage: "nb edit <file> [-m note]", module: "docs", fn: "fileEdit", flags: { ...MESSAGE } },
137
+ { group: "Files", name: "commit", summary: "git commit with the current task linked (NetworkBase-Task trailer)", usage: 'nb commit -m "message" [-a] [--task 4]', module: "extras", fn: "commit",
138
+ flags: { ...MESSAGE, all: { type: "boolean", short: "a", describe: "Commit every changed tracked file (git commit -a)" }, task: { type: "string", describe: "This task instead of the current one", valueName: "n" } } },
139
+ { group: "Files", name: "file recent", summary: "Files you changed lately", usage: "nb file recent", module: "docs", fn: "fileRecent" },
140
+ { group: "Files", name: "file star", summary: "Star a file, shared with the Files tab (--off to unstar)", usage: "nb file star <path> [--off]", module: "docs", fn: "fileStar", flags: { off: { type: "boolean", describe: "Unstar" } } },
118
141
  { group: "Files", name: "file history", summary: "A file's versions: who, when, based on, which is active", usage: "nb file history <path>", module: "browse", fn: "fileHistory" },
119
142
  { group: "Files", name: "file use", summary: "Make an earlier version active (as Use this version in the app)", usage: "nb file use <path> v<n>", module: "browse", fn: "fileUse", examples: ["nb file use report.md v1"] },
120
143
  { group: "Files", name: "file move", summary: "Move a file to another folder (asks first)", usage: "nb file move <path> <folder>", module: "browse", fn: "fileMove" },
@@ -148,8 +171,17 @@ export const COMMANDS = [
148
171
  flags: { ...MESSAGE, check: { type: "string", multiple: true, describe: "A check you ran: name=pass|fail[:note]", valueName: "check" } } },
149
172
  { group: "Tasks", name: "task review", summary: "Approve or ask for changes (reviewers)", usage: "nb task review <task> approve|changes [-m reason]", module: "tasks", fn: "review", flags: { ...MESSAGE } },
150
173
  { group: "Tasks", name: "task resubmit", summary: "Send for review again after changes", usage: "nb task resubmit <task>", module: "tasks", fn: "resubmit" },
151
- { group: "Tasks", name: "task edit", summary: "Change a task's title, description, priority or due date", usage: "nb task edit <task…> [--title text] [-m description] [--priority high] [--due friday|none]", module: "work", fn: "taskEdit",
152
- flags: { title: { type: "string", describe: "New title", valueName: "text" }, ...MESSAGE, priority: { type: "string", describe: "low, medium, high or urgent", valueName: "level" }, due: { type: "string", describe: "A date, or none", valueName: "date" } } },
174
+ { group: "Tasks", name: "task edit", summary: "Change a task's title, description, priority or due date", usage: "nb task edit <task…> [--title text] [-m description] [--priority high] [--due friday|none] [--label bug] [--blocked-by 7] [--link url]", module: "work", fn: "taskEdit",
175
+ flags: { title: { type: "string", describe: "New title", valueName: "text" }, ...MESSAGE, priority: { type: "string", describe: "low, medium, high or urgent", valueName: "level" }, due: { type: "string", describe: "A date, or none", valueName: "date" },
176
+ label: { type: "string", multiple: true, describe: "Add a label (or several, comma-separated)", valueName: "label" }, unlabel: { type: "string", multiple: true, describe: "Remove a label", valueName: "label" },
177
+ "blocked-by": { type: "string", multiple: true, describe: "This task waits on that one", valueName: "task" }, "not-blocked-by": { type: "string", multiple: true, describe: "Stop waiting on that task", valueName: "task" },
178
+ link: { type: "string", multiple: true, describe: "Add a link, like a pull request (https://…)", valueName: "url" } },
179
+ examples: ["nb task edit 4 --label bug --blocked-by 7", "nb task edit 4 --link https://github.com/acme/app/pull/42"] },
180
+ { group: "Tasks", name: "task remind", summary: "Remind me about a task at a time (in the inbox)", usage: 'nb task remind <task> "tomorrow 9am" [-m note] | --list | --off', module: "work", fn: "taskRemind",
181
+ flags: { ...MESSAGE, list: { type: "boolean", describe: "Your reminders on the task" }, off: { type: "boolean", describe: "Cancel your reminders on the task" } },
182
+ examples: ['nb task remind 4 "tomorrow 9am"', 'nb task remind 4 "in 2 hours" -m "check the build"'] },
183
+ { group: "Tasks", name: "task watch", summary: "Hear about a task's changes without being assigned (--off to stop)", usage: "nb task watch <task> [--off]", module: "work", fn: "taskWatch", flags: { off: { type: "boolean", describe: "Stop" } } },
184
+ { group: "Tasks", name: "task star", summary: "Star a task for nb task list --starred (--off to unstar)", usage: "nb task star <task> [--off]", module: "work", fn: "taskStar", flags: { off: { type: "boolean", describe: "Unstar" } } },
153
185
  { group: "Tasks", name: "task assign", summary: "Assign tasks to someone, you, or nobody", usage: "nb task assign <task…> <@username|me|none> | --to @sam", module: "work", fn: "taskAssign",
154
186
  flags: { to: { type: "string", describe: "Who: @username, me or none (for several tasks)", valueName: "person" } }, examples: ["nb task assign 4 @sam", "nb task assign 3 4 5 --to me"] },
155
187
  { group: "Tasks", name: "task report", summary: "Report progress with checks, without finishing", usage: "nb task report <task> -m summary [--check name=pass]", module: "work", fn: "taskReport",
@@ -169,8 +201,9 @@ export const COMMANDS = [
169
201
  { group: "Classes", name: "review list", summary: "Hand-ins waiting for your review", usage: "nb review list -w <organization> [--mine]", module: "assignments", fn: "reviewList",
170
202
  flags: { mine: { type: "boolean", describe: "Only assignments you review" } }, examples: ["nb review list -w physics-101 --mine"] },
171
203
  { group: "Classes", name: "review view", summary: "A hand-in: files, note, late, AI policy", usage: "nb review view <n>", module: "assignments", fn: "reviewView" },
172
- { group: "Classes", name: "review approve", summary: "Approve a hand-in", usage: "nb review approve <n>", module: "assignments", fn: "reviewApprove" },
173
- { group: "Classes", name: "review return", summary: "Return a hand-in with what to fix", usage: "nb review return <n> -m reason [--fix-by date]", module: "assignments", fn: "reviewReturn",
204
+ { group: "Classes", name: "review approve", summary: "Approve a hand-in, or several", usage: "nb review approve <n…>", module: "assignments", fn: "reviewApprove", examples: ["nb review approve 3 5 8"] },
205
+ { group: "Classes", name: "review diff", summary: "What changed since the last hand-in", usage: "nb review diff <n>", module: "assignments", fn: "reviewDiff" },
206
+ { group: "Classes", name: "review return", summary: "Return hand-ins with what to fix", usage: "nb review return <n…> -m reason [--fix-by date]", module: "assignments", fn: "reviewReturn",
174
207
  flags: { ...MESSAGE, "fix-by": { type: "string", describe: "When it can be handed in again by", valueName: "date" } } },
175
208
  { group: "Classes", name: "review pull", summary: "Download a hand-in to reviews/ (read-only)", usage: "nb review pull <n>", module: "assignments", fn: "reviewPull" },
176
209
  { group: "Tasks", name: "task pull", summary: "Bring a task's panel files into .tasks/", usage: "nb task pull <task>", module: "tasks", fn: "pullTask" },
@@ -181,7 +214,11 @@ export const COMMANDS = [
181
214
  { group: "Tasks", name: "subtask edit", summary: "Rename a subtask", usage: "nb subtask edit <n> \"<title>\" [--task 4]", module: "work", fn: "subtaskEdit", flags: { ...TASK } },
182
215
  { group: "Tasks", name: "subtask delete", summary: "Delete a subtask (asks first)", usage: "nb subtask delete <n> [--task 4]", module: "work", fn: "subtaskDelete", flags: { ...TASK } },
183
216
  { group: "Tasks", name: "subtask move", summary: "Move a subtask to another position", usage: "nb subtask move <n> <position> [--task 4]", module: "work", fn: "subtaskMove", flags: { ...TASK } },
184
- { group: "Tasks", name: "comment add", summary: "Comment on a task", usage: "nb comment add -m \"<text>\" [--task 4]", module: "tasks", fn: "commentAdd", flags: { ...TASK, ...MESSAGE, file: { type: "string", describe: "Comment on lines of a file instead: path:12 or path:12-18", valueName: "path:line" } } },
217
+ { group: "Tasks", name: "comment add", summary: "Comment on a task", usage: "nb comment add -m \"<text>\" [--task 4] [--reply <id>] [--doc readme]", module: "tasks", fn: "commentAdd", flags: { ...TASK, ...MESSAGE, file: { type: "string", describe: "Comment on lines of a file instead: path:12 or path:12-18", valueName: "path:line" },
218
+ reply: { type: "string", describe: "Reply to this comment (its id from nb comment list)", valueName: "id" }, doc: { type: "string", describe: "Comment on a doc instead (readme, …)", valueName: "slug" } },
219
+ examples: ['nb comment add -m "@sam can you check this?"', 'nb comment add --reply 3f2a9c1e -m "done"', 'nb comment add --doc readme -m "Install step is out of date"'] },
220
+ { group: "Tasks", name: "comment edit", summary: "Edit your own comment", usage: "nb comment edit <id> -m \"new text\" [--task 4]", module: "tasks", fn: "commentEdit", flags: { ...TASK, ...MESSAGE } },
221
+ { group: "Tasks", name: "comment delete", summary: "Delete your own comment (asks first)", usage: "nb comment delete <id> [--task 4]", module: "tasks", fn: "commentDelete", flags: { ...TASK }, exit: [0, 7, 130] },
185
222
  { group: "Tasks", name: "comment list", summary: "A task's comments, or a file's line comments", usage: "nb comment list [--task 4] [--file path]", module: "work", fn: "commentList", flags: { ...TASK, file: { type: "string", describe: "A file's line comments", valueName: "path" } } },
186
223
  { group: "Tasks", name: "comment resolve", summary: "Resolve (or --reopen) a file comment thread", usage: "nb comment resolve <thread id> --file <path> [--reopen]", module: "work", fn: "commentResolve", flags: { file: { type: "string", describe: "The file", valueName: "path" }, reopen: { type: "boolean", describe: "Open it again" } } },
187
224
 
@@ -218,8 +255,18 @@ export const COMMANDS = [
218
255
  { group: "Docs and workspaces", name: "sprint list", summary: "Sprints (or the workspace's own word for them)", usage: "nb sprint list", module: "browse", fn: "sprintList" },
219
256
  { group: "Docs and workspaces", name: "sprint view", summary: "One sprint and its tasks", usage: "nb sprint view <name or number>", module: "browse", fn: "sprintView" },
220
257
  { group: "Docs and workspaces", name: "update post", summary: "Post an update to the workspace (asks first)", usage: "nb update post -m text", module: "browse", fn: "updatePost", flags: { ...MESSAGE } },
258
+ { group: "Docs and workspaces", name: "member invite", summary: "Invite someone into one of the workspace's open roles", usage: 'nb member invite @username --role "<open role>" [-m note]', module: "docs", fn: "memberInvite",
259
+ flags: { role: { type: "string", describe: "The open role's title", valueName: "role" }, ...MESSAGE } },
260
+ { group: "Docs and workspaces", name: "member role", summary: "Change a member's role (owner and admins)", usage: "nb member role @username admin|member|viewer", module: "docs", fn: "memberRole" },
261
+ { group: "Docs and workspaces", name: "member remove", summary: "Remove a member (asks first)", usage: "nb member remove @username", module: "docs", fn: "memberRemove", exit: [0, 7, 130] },
262
+ { group: "Docs and workspaces", name: "workspace leave", summary: "Leave this workspace (asks first)", usage: "nb workspace leave", module: "docs", fn: "workspaceLeave", exit: [0, 7, 130] },
263
+ { group: "Docs and workspaces", name: "update list", summary: "The workspace's updates", usage: "nb update list", module: "browse", fn: "updateList" },
264
+ { group: "Docs and workspaces", name: "update view", summary: "One update and its comments", usage: "nb update view <n>", module: "browse", fn: "updateView" },
265
+ { group: "Docs and workspaces", name: "update like", summary: "Like an update (again to unlike)", usage: "nb update like <n>", module: "browse", fn: "updateLike" },
266
+ { group: "Docs and workspaces", name: "update comment", summary: "Comment on an update", usage: "nb update comment <n> -m text", module: "browse", fn: "updateComment", flags: { ...MESSAGE } },
221
267
  { group: "Docs and workspaces", name: "member list", summary: "People in the workspace", usage: "nb member list [name]", module: "docs", fn: "memberList" },
222
- { group: "Docs and workspaces", name: "search", summary: "Find files by name", usage: "nb search \"<text>\"", module: "docs", fn: "search" },
268
+ { group: "Docs and workspaces", name: "search", summary: "Find tasks, files, comments, docs and people", usage: "nb search \"<text>\" [--in tasks,files,comments,docs,people]", module: "docs", fn: "search",
269
+ flags: { in: { type: "string", describe: "Only these: tasks, files, comments, docs, people", valueName: "kinds" } }, examples: ['nb search "login"', 'nb search "login" --in tasks,comments'] },
223
270
  ];
224
271
 
225
272
  /** Old 1.x names → new commands (report §17.5); they work through 2.x and print the new name once a day. */