@networkbase/cli 2.0.3 → 2.1.0

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.
@@ -22,7 +22,7 @@ export async function inbox(ctx) {
22
22
  ctx.out.result("nb.inbox/1", { unread: p.unreadCount, items }, (d) => d.items.length ? [
23
23
  `${d.unread} unread`,
24
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)}`) : ""}`),
25
- c.muted(" nb inbox read <n> · nb inbox open <n> · nb inbox --follow"),
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
  }
28
28
 
@@ -45,6 +45,38 @@ export async function inboxRead(ctx) {
45
45
  ctx.out.result("nb.inbox.read/1", { read: res.read }, (d) => `${ctx.out.c.success(ctx.out.sym.done)} Marked ${d.read} read`);
46
46
  }
47
47
 
48
+ /** The task an inbox item is about; replying and approving work on those (C4). @param {any} item @param {string} ref */
49
+ function taskOf(item, ref) {
50
+ const refs = item.entityRefs ?? {};
51
+ if (!refs.taskId) throw new CliError("NOT_A_TASK", "That item isn't about a task, so there's nothing to reply to here", { hint: `nb inbox open ${ref}` });
52
+ return /** @type {{ taskId: string, projectId?: string, commentId?: string }} */ (refs);
53
+ }
54
+
55
+ /** `nb inbox reply 3 "done"` (C4): a comment on the item's task, as a reply when the item is a comment. @param {Context} ctx */
56
+ export async function inboxReply(ctx) {
57
+ const [ref, ...words] = ctx.positionals;
58
+ const text = String(ctx.flags.message ?? words.join(" ")).trim();
59
+ if (!ref || !text) throw usage('nb inbox reply <n> "your reply"');
60
+ const [item] = await pick({ ...ctx, positionals: [ref] });
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 } : {}) });
63
+ await ctx.api.post("/api/v1/inbox/read", { ids: [item.id] });
64
+ 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
+ }
66
+
67
+ /** `nb inbox approve 3` (C4): approve the task waiting for your review. @param {Context} ctx */
68
+ export async function inboxApprove(ctx) {
69
+ const ref = ctx.positionals[0];
70
+ if (!ref) throw usage("nb inbox approve <n>");
71
+ const [item] = await pick(ctx);
72
+ const refs = taskOf(item, ref);
73
+ const { task } = /** @type {any} */ (await ctx.api.get("/api/v1/extension/task-detail", { query: { taskId: refs.taskId, brief: "1" } }));
74
+ if (task.reviewStatus !== "pending") throw new CliError("NOTHING_TO_APPROVE", `#${task.taskNumber} isn't waiting for review`, { hint: `nb inbox open ${ref}` });
75
+ await ctx.api.patch("/api/v1/extension/task-update", { kind: "approve", projectId: task.projectId, taskId: task.id, expectedUpdatedAt: new Date(task.updatedAt).toISOString() });
76
+ await ctx.api.post("/api/v1/inbox/read", { ids: [item.id] });
77
+ ctx.out.result("nb.inbox.approve/1", { number: task.taskNumber }, (d) => `${ctx.out.c.success(ctx.out.sym.done)} Approved #${d.number}`);
78
+ }
79
+
48
80
  /** @param {Context} ctx */
49
81
  export async function inboxOpen(ctx) {
50
82
  const [item] = await pick(ctx);
@@ -29,7 +29,10 @@ export async function init(ctx) {
29
29
  }
30
30
  if (!chosen) {
31
31
  if (!workspaces.length) throw new CliError("WORKSPACE_NOT_FOUND", "You have no workspaces yet", { hint: "Create one at networkbase.in first" });
32
- const slug = await ask(ctx, { key: "workspace", header: "Workspace", question: "Which workspace should this folder link to?", options: workspaces.slice(0, 9).map((/** @type {any} */ w, /** @type {number} */ i) => ({ value: w.slug, label: safe(w.title), description: w.slug, recommended: i === 0 })) });
32
+ // The workspace named like this folder (or its repository) comes first (C1).
33
+ const matches = folderMatches(workspaces, here);
34
+ const ordered = [...matches, ...workspaces.filter((/** @type {any} */ w) => !matches.includes(w))];
35
+ const slug = await ask(ctx, { key: "workspace", header: "Workspace", question: "Which workspace should this folder link to?", options: ordered.slice(0, 9).map((/** @type {any} */ w, /** @type {number} */ i) => ({ value: w.slug, label: safe(w.title), description: i === 0 && matches.length ? `${w.slug} · matches this folder` : w.slug, recommended: i === 0 })) });
33
36
  chosen = workspaces.find((/** @type {any} */ w) => w.slug === slug);
34
37
  }
35
38
  const remoteRoot = ctx.flags.path ? `/${String(ctx.flags.path).replace(/^\/+|\/+$/g, "")}` : "/";
@@ -46,6 +49,35 @@ export async function init(ctx) {
46
49
  ctx.out.c.muted(`Next: nb pull to get the files, or edit and nb push <files>${ctx.flags.task ? "" : " (nb task start <n> to work on a task)"}`));
47
50
  }
48
51
 
52
+ const plain = (/** @type {unknown} */ s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
53
+
54
+ /** The folder's name and its git repository's name: what a person most likely called the workspace. @param {string} cwd */
55
+ function folderNames(cwd) {
56
+ const names = new Set([plain(path.basename(cwd))]);
57
+ for (let dir = cwd; ; dir = path.dirname(dir)) {
58
+ const config = path.join(dir, ".git", "config");
59
+ if (fs.existsSync(config)) {
60
+ const url = /\[remote "origin"\][^[]*?url\s*=\s*(\S+)/.exec(fs.readFileSync(config, "utf8"))?.[1];
61
+ if (url) names.add(plain(path.basename(url).replace(/\.git$/, "")));
62
+ if (dir !== cwd) names.add(plain(path.basename(dir)));
63
+ break;
64
+ }
65
+ if (path.dirname(dir) === dir) break;
66
+ }
67
+ names.delete("");
68
+ return [...names];
69
+ }
70
+
71
+ /**
72
+ * Workspaces whose slug or title matches this folder or its repository, best first (C1).
73
+ * @template {{ slug: string, title: string }} W @param {W[]} workspaces @param {string} cwd @returns {W[]}
74
+ */
75
+ export function folderMatches(workspaces, cwd) {
76
+ const names = folderNames(cwd);
77
+ const score = (/** @type {W} */ w) => Math.max(0, ...[plain(w.slug), plain(w.title)].flatMap((label) => names.map((n) => (label === n ? 3 : label && (label.includes(n) || n.includes(label)) && Math.min(label.length, n.length) >= 3 ? 2 : 0))));
78
+ return workspaces.map((w, i) => ({ w, s: score(w), i })).filter((x) => x.s > 0).sort((a, b) => b.s - a.s || a.i - b.i).map((x) => x.w);
79
+ }
80
+
49
81
  /**
50
82
  * 1.x left a mirror folder and maybe a background process (A1.20). The mirror moves aside (never deleted);
51
83
  * the old auto-push process is stopped.
@@ -4,7 +4,7 @@
4
4
  import crypto from "node:crypto";
5
5
  import readline from "node:readline";
6
6
 
7
- import { HOSTED_EXCLUDED, callTool as runTool, toolList as listTools } from "../mcp/tools.mjs";
7
+ import { HOSTED_EXCLUDED, accessCard, callTool as runTool, readAccess, toolList as listTools } from "../mcp/tools.mjs";
8
8
 
9
9
  /** @typedef {import("../context.mjs").Context} Context */
10
10
 
@@ -37,12 +37,17 @@ const RESOURCES = [
37
37
  /**
38
38
  * One MCP message handler for both servers (report A7.1): `nb mcp` over stdio, and the hosted one over HTTP
39
39
  * (src/app/api/mcp, P6.1). `hosted` leaves out tools that need a local folder and the local undo log.
40
- * @param {{ where: { cwd: string, env: NodeJS.ProcessEnv }, send: (message: any) => void, version: string, hosted?: boolean }} options
40
+ * `access` is who the server works for and what it may do (report A6): the hosted server passes it from its own
41
+ * database; `nb mcp` reads it from /api/v1/me once, on first use.
42
+ * @param {{ where: { cwd: string, env: NodeJS.ProcessEnv }, send: (message: any) => void, version: string, hosted?: boolean, access?: () => Promise<any> }} options
41
43
  */
42
- export function createMcpHandler({ where, send, version, hosted = false }) {
44
+ export function createMcpHandler({ where, send, version, hosted = false, access }) {
43
45
  const cancelled = new Set();
44
46
  const ctx = { version };
45
- const toolList = () => listTools(hosted);
47
+ /** @type {Promise<any> | null} */
48
+ let accessRead = null;
49
+ const getAccess = () => (accessRead ??= (access ? access() : readAccess(where)).catch(() => null));
50
+ const toolList = async () => listTools(hosted, await getAccess());
46
51
  const callTool = (/** @type {string} */ name, /** @type {any} */ args, /** @type {any} */ w) =>
47
52
  hosted && HOSTED_EXCLUDED.has(name)
48
53
  ? Promise.resolve({ isError: true, content: [{ type: "text", text: `${name} needs NetworkBase on your computer (nb mcp); the hosted server can't use local files` }] })
@@ -63,14 +68,14 @@ export function createMcpHandler({ where, send, version, hosted = false }) {
63
68
  protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
64
69
  capabilities: { tools: { listChanged: false }, resources: { listChanged: false }, prompts: { listChanged: false }, logging: {} },
65
70
  serverInfo: { name: "networkbase", title: "NetworkBase", version: ctx.version },
66
- instructions: INSTRUCTIONS,
71
+ instructions: [accessCard(await getAccess()), INSTRUCTIONS].filter(Boolean).join("\n\n"),
67
72
  });
68
73
  }
69
74
  case "ping":
70
75
  case "logging/setLevel":
71
76
  return reply({});
72
77
  case "tools/list":
73
- return reply({ tools: toolList() });
78
+ return reply({ tools: await toolList() });
74
79
  case "tools/call": {
75
80
  if (typeof params?.name !== "string") return fail(-32602, "tools/call needs a tool name");
76
81
  const progressToken = params?._meta?.progressToken;
@@ -12,6 +12,34 @@ import { safe } from "../print/style.mjs";
12
12
 
13
13
  /** @typedef {import("../context.mjs").Context} Context */
14
14
 
15
+ /** `nb` on its own (report C1): signed out → sign in; not linked → the matching workspace; linked → nb status. @param {Context} ctx */
16
+ export async function home(ctx) {
17
+ const { c } = ctx.out;
18
+ if (!ctx.profile.token) {
19
+ ctx.out.result("nb.home/1", { state: "signed-out" }, () => [
20
+ `${c.brand("NetworkBase")} ${c.muted(ctx.version)}`, "", "You're not signed in.", "",
21
+ ` nb login ${c.muted("Sign in (one click in your browser)")}`,
22
+ ` nb help ${c.muted("What the CLI can do")}`,
23
+ ]);
24
+ return;
25
+ }
26
+ if (!ctx.project) {
27
+ const { folderMatches } = await import("./link.mjs");
28
+ const { workspaces } = /** @type {any} */ (await ctx.api.get("/api/v1/extension/workspaces"));
29
+ const matches = folderMatches(workspaces, ctx.cwd).slice(0, 3).map((/** @type {any} */ w) => ({ slug: w.slug, title: w.title }));
30
+ ctx.out.result("nb.home/1", { state: "not-linked", matches, workspaces: workspaces.length }, (d) => [
31
+ "This folder isn't linked to a workspace.",
32
+ ...(d.matches.length
33
+ ? ["", `Best match${d.matches.length > 1 ? "es" : ""}:`, ...d.matches.map((/** @type {any} */ m) => ` nb init ${safe(m.slug)} ${c.muted(safe(m.title))}`)]
34
+ : ["", ` nb init ${c.muted(d.workspaces ? "Choose one of your workspaces" : "Create a workspace at networkbase.in first")}`]),
35
+ ` nb help ${c.muted("What the CLI can do")}`,
36
+ ]);
37
+ return;
38
+ }
39
+ const { status } = await import("./files.mjs");
40
+ return status(ctx);
41
+ }
42
+
15
43
  /** @param {Context} ctx */
16
44
  export async function help(ctx) {
17
45
  const name = ctx.positionals.join(" ");
@@ -136,15 +164,40 @@ export async function feedback(ctx) {
136
164
 
137
165
  /** One short line for your shell prompt: the linked workspace and started task. No network; empty outside a link. @param {Context} ctx */
138
166
  export async function prompt(ctx) {
139
- if (!ctx.project) return;
140
- const task = ctx.project.startedTask?.number ? ` #${ctx.project.startedTask.number}` : "";
141
- ctx.out.raw(`${safe(ctx.project.slug ?? "nb")}${task}`);
167
+ if (!ctx.project || !ctx.root) return;
168
+ const { branchTask } = await import("./tasks.mjs");
169
+ const number = ctx.project.startedTask?.number ?? branchTask(ctx.root);
170
+ // "2 changed": tracked files whose size or time moved since the last sync, by stat only (it runs on every prompt).
171
+ // ponytail: new untracked files aren't counted, and past 3,000 tracked files the count is left out.
172
+ let changed = 0;
173
+ try {
174
+ const { readState } = await import("../sync/state.mjs");
175
+ const { toRelative } = await import("../sync/local.mjs");
176
+ const entries = Object.entries(readState(ctx.root, ctx.project.workspaceId).files);
177
+ if (entries.length <= 3000) {
178
+ for (const [remotePath, base] of entries) {
179
+ const rel = toRelative(ctx.project.remoteRoot ?? "/", remotePath);
180
+ if (rel === null) continue;
181
+ try {
182
+ const st = fs.statSync(path.join(ctx.root, ...rel.split("/")));
183
+ if (st.size !== base.size || Math.trunc(st.mtimeMs) !== Math.trunc(base.mtimeMs)) changed++;
184
+ } catch {
185
+ changed++;
186
+ }
187
+ }
188
+ }
189
+ } catch {
190
+ // No sync yet: nothing to count.
191
+ }
192
+ const parts = [number ? `#${number}` : safe(ctx.project.slug ?? "nb"), changed ? `${changed} changed` : null].filter(Boolean);
193
+ // A trailing space, so `PS1='$(nb prompt)'$PS1` reads well and adds nothing outside linked folders.
194
+ ctx.out.raw(`[${parts.join(" · ")}] `);
142
195
  }
143
196
 
144
- const RC = /** @type {Record<string, { file: (home: string) => string, line: string }>} */ ({
145
- zsh: { file: (h) => path.join(h, ".zshrc"), line: "command -v nb >/dev/null && source <(nb completion zsh)" },
146
- bash: { file: (h) => path.join(h, ".bashrc"), line: "command -v nb >/dev/null && source <(nb completion bash)" },
147
- fish: { file: (h) => path.join(h, ".config", "fish", "conf.d", "nb.fish"), line: "type -q nb; and nb completion fish | source" },
197
+ const RC = /** @type {Record<string, { file: (home: string) => string, line: string, prompt: string }>} */ ({
198
+ zsh: { file: (h) => path.join(h, ".zshrc"), line: "command -v nb >/dev/null && source <(nb completion zsh)", prompt: "setopt PROMPT_SUBST; PROMPT='$(nb prompt 2>/dev/null)'$PROMPT" },
199
+ bash: { file: (h) => path.join(h, ".bashrc"), line: "command -v nb >/dev/null && source <(nb completion bash)", prompt: "PS1='$(nb prompt 2>/dev/null)'$PS1" },
200
+ fish: { file: (h) => path.join(h, ".config", "fish", "conf.d", "nb.fish"), line: "type -q nb; and nb completion fish | source", prompt: "functions -q _nb_prompt_was; or functions -c fish_prompt _nb_prompt_was; function fish_prompt; nb prompt 2>/dev/null; _nb_prompt_was; end" },
148
201
  });
149
202
 
150
203
  /** Adds completions to your shell's startup file, after a yes (A6.6). @param {Context} ctx */
@@ -158,14 +211,20 @@ export async function setupShell(ctx) {
158
211
  if (/[\\/]_npx[\\/]/.test(process.argv[1] ?? "")) ctx.out.warn("nb isn't installed, so completions won't find it: npm i -g @networkbase/cli");
159
212
  const file = rc.file(os.homedir());
160
213
  const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
161
- if (current.includes("nb completion")) return ctx.out.result("nb.setup.shell/1", { shell, file, added: false }, () => `Completions are already set up in ${file}`);
162
214
  const { confirm } = await import("../tui/ask.mjs");
163
- if (!(await confirm(ctx, { key: "shell", question: `Add nb completions to ${file}?`, preview: rc.line, yesLabel: "Add", defaultYes: true }))) return 130;
215
+ /** @type {string[]} */
216
+ const lines = [];
217
+ if (!current.includes("nb completion")) {
218
+ if (!(await confirm(ctx, { key: "shell", question: `Add nb completions to ${file}?`, preview: rc.line, yesLabel: "Add", defaultYes: true }))) return 130;
219
+ lines.push(rc.line);
220
+ }
221
+ // The current task in the prompt, [#4 · 2 changed] (C8): a separate yes, since it changes how the prompt looks.
222
+ if (!current.includes("nb prompt") && (await confirm(ctx, { key: "prompt", question: `Show the current task in your prompt too, like [#4 · 2 changed]?`, preview: rc.prompt, yesLabel: "Add", defaultYes: true }).catch(() => false))) lines.push(rc.prompt);
223
+ if (!lines.length) return ctx.out.result("nb.setup.shell/1", { shell, file, added: false }, () => `Already set up in ${file}`);
164
224
  fs.mkdirSync(path.dirname(file), { recursive: true });
165
- fs.appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}# NetworkBase CLI\n${rc.line}\n`);
166
- ctx.out.result("nb.setup.shell/1", { shell, file, added: true }, () => [
167
- `${ctx.out.c.success(ctx.out.sym.done)} Added completions to ${file}; open a new terminal to use them`,
168
- ctx.out.c.muted(` Workspace in your prompt too: ${shell === "fish" ? "add (nb prompt) to fish_prompt" : "PS1='$(nb prompt) '$PS1"}`),
225
+ fs.appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}# NetworkBase CLI\n${lines.join("\n")}\n`);
226
+ ctx.out.result("nb.setup.shell/1", { shell, file, added: true, prompt: lines.includes(rc.prompt) }, (d) => [
227
+ `${ctx.out.c.success(ctx.out.sym.done)} Added ${lines.includes(rc.line) ? "completions" : ""}${lines.length === 2 ? " and " : ""}${d.prompt ? "the task in your prompt" : ""} to ${file}; open a new terminal to use ${lines.length === 2 ? "them" : "it"}`,
169
228
  ]);
170
229
  }
171
230
 
@@ -35,6 +35,11 @@ const FILTERS = {
35
35
  all: { type: "boolean", describe: "Include tasks assigned to others" },
36
36
  status: { type: "string", describe: "todo,in_progress,blocked,review,done", valueName: "list" },
37
37
  limit: { type: "string", describe: "At most this many", valueName: "n" },
38
+ due: { type: "string", describe: "today, week, overdue, or a date", valueName: "when" },
39
+ to: { type: "string", describe: "Assigned to @username, me or none (looks at everyone's tasks)", valueName: "person" },
40
+ sprint: { type: "string", describe: "A sprint name, current, or id", valueName: "sprint" },
41
+ priority: { type: "string", describe: "low,medium,high,urgent", valueName: "list" },
42
+ sort: { type: "string", describe: "due, priority or updated (default)", valueName: "by" },
38
43
  };
39
44
  /** 1.x status flags: still accepted so old scripts run, never shown (P2.9). @type {Record<string, FlagSpec>} */
40
45
  const OLD_STATUS = {
@@ -47,10 +52,12 @@ const DRY = { "dry-run": { type: "boolean", describe: "Show what would happen, c
47
52
  /** @type {CommandSpec[]} */
48
53
  export const COMMANDS = [
49
54
  // Account and setup
50
- { group: "Account and setup", name: "login", summary: "Sign in (browser, a code, or a token from stdin)", usage: "nb login [--device] [--agent name] [--with-token]", module: "account", fn: "login",
55
+ { group: "Account and setup", name: "login", summary: "Sign in (browser, a code, or a token from stdin)", usage: "nb login [--device] [--agent name [--access full|small|read] [--workspace ws|--all-workspaces]] [--with-token]", module: "account", fn: "login",
51
56
  flags: { "with-token": { type: "boolean", describe: "Read a token from stdin (CI, scripts)" }, device: { type: "boolean", describe: "Sign in with a code you approve on another device (automatic over SSH)" },
52
- agent: { type: "string", describe: "Sign in an AI agent; you pick the one workspace it may use", valueName: "name" } },
53
- examples: ["nb login", "nb login --device", "nb login --device --agent \"Claude Code\"", "echo $NB_TOKEN | nb login --with-token"], exit: [0, 3, 130] },
57
+ agent: { type: "string", describe: "Sign in an AI agent; you approve where it works and what it may do", valueName: "name" },
58
+ access: { type: "string", describe: "What the agent asks for: full, small or read (the page starts there)", valueName: "level" },
59
+ "all-workspaces": { type: "boolean", describe: "The agent asks for all your workspaces" } },
60
+ examples: ["nb login", "nb login --device", "nb login --device --agent \"Claude Code\"", "nb login --device --agent \"Claude Code\" --access read --all-workspaces", "echo $NB_TOKEN | nb login --with-token"], exit: [0, 3, 130] },
54
61
  { group: "Account and setup", name: "logout", summary: "Revoke this device's token and sign out", usage: "nb logout [--all]", module: "account", fn: "logout",
55
62
  flags: { all: { type: "boolean", describe: "Sign out every device and agent (opens Settings to confirm it's you)" } } },
56
63
  { group: "Account and setup", name: "token list", summary: "Your signed-in devices, agents and personal tokens", usage: "nb token list", module: "account", fn: "tokenList" },
@@ -67,6 +74,7 @@ export const COMMANDS = [
67
74
  flags: { repair: { type: "boolean", describe: "Fix what can be fixed (lock, temp files)" } } },
68
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" },
69
76
  { group: "Account and setup", name: "version", summary: "CLI, Node and server versions", usage: "nb version", module: "misc", fn: "version" },
77
+ { 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] },
70
78
  { group: "Account and setup", name: "help", summary: "Help for a command", usage: "nb help [command]", module: "misc", fn: "help" },
71
79
  { group: "Account and setup", name: "completion", summary: "Shell completion script", usage: "nb completion zsh|bash|fish|powershell", module: "misc", fn: "completion" },
72
80
  { 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" },
@@ -87,9 +95,13 @@ export const COMMANDS = [
87
95
  "keep-both": { type: "boolean", describe: "A changed file whose name is taken goes in as name (2).ext" },
88
96
  force: { type: "boolean", describe: "Replace a newer server version after a conflict (asks first)" },
89
97
  recreate: { type: "boolean", describe: "Upload again files that were deleted on the server but you still have" },
98
+ "no-task": { type: "boolean", describe: "Don't link these files to the task you started" },
90
99
  "from-git": { type: "boolean", describe: "Push what the last git commit changed (its NetworkBase-Task trailer picks the task)" },
91
100
  "confirm-secrets": { type: "boolean", describe: "Upload even though a file looks like it holds a password or key" } },
92
101
  examples: ["nb push src/app.ts -m \"Fix login\"", "nb push report.pdf --task 4 --as final", "nb push shots/ --task 5 --as reference"], exit: [0, 2, 4, 5, 7, 8] },
102
+ { group: "Files", name: "queue", summary: "Pushes waiting to send while offline: what, since when, why", usage: "nb queue", module: "files", fn: "queue" },
103
+ { group: "Files", name: "queue retry", summary: "Send the queued pushes now", usage: "nb queue retry", module: "files", fn: "queueRetry", exit: [0, 4, 8] },
104
+ { 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" } } },
93
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] },
94
106
  { group: "Files", name: "resolve", summary: "Settle a conflict", usage: "nb resolve <path> --mine|--theirs|--both", module: "resolve", fn: "resolve",
95
107
  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" } } },
@@ -99,9 +111,12 @@ export const COMMANDS = [
99
111
  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" } },
100
112
  examples: ["nb inbox --unread", "nb inbox --follow --notify"] },
101
113
  { 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
+ { 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
+ { 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" },
102
116
  { group: "Account and setup", name: "inbox open", summary: "Open an inbox item in the browser", usage: "nb inbox open <n>", module: "inbox", fn: "inboxOpen" },
103
117
  { group: "Files", name: "file list", summary: "Files in the workspace", usage: "nb file list [folder] [--task 4]", module: "docs", fn: "fileList", flags: { ...TASK } },
104
- { group: "Files", name: "file history", summary: "A file's versions: who, when, how", usage: "nb file history <path>", module: "browse", fn: "fileHistory" },
118
+ { 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
+ { 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"] },
105
120
  { group: "Files", name: "file move", summary: "Move a file to another folder (asks first)", usage: "nb file move <path> <folder>", module: "browse", fn: "fileMove" },
106
121
  { group: "Files", name: "file rename", summary: "Rename a file (asks first)", usage: "nb file rename <path> <new name>", module: "browse", fn: "fileRename" },
107
122
  { group: "Files", name: "file delete", summary: "Move a file to the workspace Trash (asks first)", usage: "nb file delete <path>", module: "browse", fn: "fileDelete" },
@@ -110,27 +125,33 @@ export const COMMANDS = [
110
125
  { group: "Files", name: "file view", summary: "Print a file (pipe-safe)", usage: "nb file view <path>", module: "docs", fn: "fileView" },
111
126
 
112
127
  // Tasks
113
- { group: "Tasks", name: "task list", summary: "Tasks (default: yours, not done)", usage: "nb task list [@saved] [--mine|--all] [--status list] [--save name]", module: "tasks", fn: "list",
114
- flags: { ...FILTERS, save: { type: "string", describe: "Save these filters under a name (nb task list @name)", valueName: "name" } }, examples: ["nb task list --all --status blocked --save stuck", "nb task list @stuck"] },
128
+ { group: "Tasks", name: "task list", summary: "Tasks (default: yours, not done)", usage: "nb task list [@saved] [--mine|--all] [--status list] [--due week] [--to @sam] [--sprint current] [--priority high] [--sort due] [--save name]", module: "tasks", fn: "list",
129
+ flags: { ...FILTERS, save: { type: "string", describe: "Save these filters under a name (nb task list @name)", valueName: "name" } }, examples: ["nb task list --due week --sort due", "nb task list --all --status blocked --save stuck", "nb task list @stuck"] },
130
+ { group: "Tasks", name: "next", summary: "What to work on now: overdue, due soon, in progress", usage: "nb next [--limit 5]", module: "tasks", fn: "next",
131
+ flags: { limit: { type: "string", describe: "At most this many (default 5)", valueName: "n" } } },
115
132
  { group: "Tasks", name: "task count", summary: "How many open tasks you have", usage: "nb task count", module: "tasks", fn: "count" },
116
133
  { group: "Tasks", name: "task view", summary: "A task's details (--context: brief for an AI agent)", usage: "nb task view <task> [--context]", module: "tasks", fn: "view",
117
134
  flags: { context: { type: "boolean", describe: "Print the task brief for pasting into an AI agent" } } },
118
- { group: "Tasks", name: "task create", summary: "Create a task", usage: "nb task create \"<title>\" [-m description] [--priority high]", module: "tasks", fn: "create",
119
- flags: { ...MESSAGE, priority: { type: "string", describe: "low, medium, high or urgent", valueName: "level" }, subtask: { type: "string", multiple: true, describe: "Add a subtask (repeatable)", valueName: "title" },
135
+ { group: "Tasks", name: "task create", summary: "Create a task (yours unless --to says otherwise)", usage: "nb task create \"<title>\" [-m description] [--priority high] [--due friday] [--to @sam] [--sprint current]", module: "tasks", fn: "create",
136
+ flags: { ...MESSAGE, priority: { type: "string", describe: "low, medium, high or urgent", valueName: "level" },
137
+ due: { type: "string", describe: "When it's due: today, tomorrow, friday, next week, in 3 days, or 2026-12-01", valueName: "date" },
138
+ to: { type: "string", describe: "Who it's for: @username, me, or none (default: you)", valueName: "person" },
139
+ sprint: { type: "string", describe: "A sprint by name, or current", valueName: "sprint" }, subtask: { type: "string", multiple: true, describe: "Add a subtask (repeatable)", valueName: "title" },
120
140
  from: { type: "string", describe: "Create one task per heading in a Markdown file; - [ ] lines become subtasks", valueName: "file.md" } },
121
- examples: ["nb task create \"Fix login\" --priority high", "nb task create \"Write report\" --subtask Outline --subtask Draft", "nb task create --from tasks.md"] },
141
+ examples: ["nb task create \"Fix login\" --priority high", "nb task create \"Update the logo\" --due friday --to @sam --sprint current", "nb task create \"Write report\" --subtask Outline --subtask Draft", "nb task create --from tasks.md"] },
122
142
  { group: "Tasks", name: "task start", summary: "Make it this folder's task and move it to In progress", usage: "nb task start <task> [--branch]", module: "tasks", fn: "start",
123
143
  flags: { branch: { type: "boolean", describe: "Also switch to a git branch for it (nb/4-fix-login)" } }, examples: ["nb task start 4 --branch"] },
124
144
  { group: "Tasks", name: "task stop", summary: "Clear this folder's task (status unchanged)", usage: "nb task stop", module: "tasks", fn: "stop" },
125
- { group: "Tasks", name: "task move", summary: "Move to todo, in_progress or blocked", usage: "nb task move <task> <status> [--reason text]", module: "tasks", fn: "move",
145
+ { group: "Tasks", name: "task move", summary: "Move to todo, in_progress or blocked", usage: "nb task move <task…> <status> [--reason text]", module: "tasks", fn: "move",
126
146
  flags: { reason: { type: "string", describe: "Why (needed for blocked)", valueName: "text" } } },
127
147
  { group: "Tasks", name: "task done", summary: "Finish a task (sends it for review when required)", usage: "nb task done [task] [-m summary] [--check name=pass]", module: "tasks", fn: "done",
128
148
  flags: { ...MESSAGE, check: { type: "string", multiple: true, describe: "A check you ran: name=pass|fail[:note]", valueName: "check" } } },
129
149
  { 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 } },
130
150
  { group: "Tasks", name: "task resubmit", summary: "Send for review again after changes", usage: "nb task resubmit <task>", module: "tasks", fn: "resubmit" },
131
- { 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 2026-11-14|none]", module: "work", fn: "taskEdit",
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",
132
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" } } },
133
- { group: "Tasks", name: "task assign", summary: "Assign a task to someone, you, or nobody", usage: "nb task assign <task> <@username|me|none>", module: "work", fn: "taskAssign" },
153
+ { 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
+ 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"] },
134
155
  { 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",
135
156
  flags: { ...MESSAGE, check: { type: "string", multiple: true, describe: "A check you ran: name=pass|fail[:note]", valueName: "check" } } },
136
157
  { group: "Tasks", name: "task delete", summary: "Delete a task (owner; asks first)", usage: "nb task delete <task>", module: "work", fn: "taskDelete", exit: [0, 3, 7, 130] },
@@ -174,9 +195,13 @@ export const COMMANDS = [
174
195
  { group: "Agents", name: "ask list", summary: "Questions agents asked you", usage: "nb ask list", module: "ask", fn: "askList" },
175
196
  { group: "Agents", name: "ask answer", summary: "Answer a question an agent asked you", usage: "nb ask answer <id> <option number or text>", module: "ask", fn: "askAnswer" },
176
197
  { group: "Agents", name: "agent setup", summary: "Connect Claude Code, Codex or Cursor to this workspace (asks first)", usage: "nb agent setup claude|codex|cursor [--token agent|mine]", module: "agent", fn: "setup",
177
- flags: { token: { type: "string", describe: "agent (default): its own sign-in for this workspace only; mine: use yours", valueName: "kind" } },
198
+ flags: { token: { type: "string", describe: "agent (default): its own sign-in, which you approve; mine: use yours", valueName: "kind" } },
178
199
  examples: ["nb agent setup claude", "nb agent setup codex"] },
179
- { group: "Agents", name: "agent status", summary: "Which agents are connected here", usage: "nb agent status", module: "agent", fn: "status" },
200
+ { group: "Agents", name: "agent status", summary: "Which agents are connected here, and what each may do", usage: "nb agent status", module: "agent", fn: "status" },
201
+ { group: "Agents", name: "agent access", summary: "Change what an agent may do (opens its Settings page)", usage: "nb agent access claude|codex|cursor [--full|--small|--read-only] [--workspace ws|--all-workspaces]", module: "agent", fn: "access",
202
+ flags: { full: { type: "boolean", describe: "Full help: asks before big changes" }, small: { type: "boolean", describe: "Small changes only" }, "read-only": { type: "boolean", describe: "Read only" },
203
+ "all-workspaces": { type: "boolean", describe: "All your workspaces" } },
204
+ examples: ["nb agent access claude --read-only", "nb agent access claude --workspace design-lab --small"] },
180
205
  { group: "Agents", name: "agent remove", summary: "Disconnect an agent and remove its NetworkBase notes", usage: "nb agent remove claude|codex|cursor", module: "agent", fn: "remove" },
181
206
  { group: "Agents", name: "mcp", summary: "MCP server for Claude Code, Codex and Cursor (stdio)", usage: "nb mcp", module: "mcp", fn: "serve",
182
207
  examples: ["claude mcp add networkbase -- npx -y @networkbase/cli@2 mcp"] },
@@ -219,6 +244,14 @@ export const ALIASES = {
219
244
  ws: "workspace list",
220
245
  };
221
246
 
247
+ /** Short names people expect (report C1); each says its full name once. Not renamed, so no "until 3.0". */
248
+ export const SHORTCUTS = {
249
+ ls: "file list",
250
+ done: "task done",
251
+ add: "task add",
252
+ "task add": "task create",
253
+ };
254
+
222
255
  /** 1.x commands removed on purpose (report D2, D6), with the reason printed instead. */
223
256
  export const REMOVED = {
224
257
  "hook install": "nb hook install was removed in 2.0: it replaced your git hook and scanned the wrong files.",