@fieldwork-ai/cli 0.16.0

package/dist/commands/kb-pages.js

@@ -0,0 +1,97 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { apiJson, requireOrgId } from "../http.js";
+import { EXIT, fail } from "../output.js";
+/** One page's full detail, including its serialized content. */
+export async function lookupPage(kbFileId) {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base/${kbFileId}`);
+    return body.page;
+}
+/** The server's line-based frontmatter shape (src/lib/kb/frontmatter.ts):
+ * `summary:` between `---` fences, body verbatim after the closing fence. */
+export function parseKbContent(content) {
+    const lines = content.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    let summary = null;
+    for (const line of lines.slice(1, closeIdx)) {
+        const match = line.match(/^summary:\s*(.*)$/);
+        if (match)
+            summary = match[1].trim();
+    }
+    if (!summary)
+        return null;
+    const body = lines
+        .slice(closeIdx + 1)
+        .join("\n")
+        .replace(/^\n/, "");
+    return { summary, body };
+}
+/**
+ * Create-or-update one page from full local content. Returns what happened.
+ * `existing` is the tree row when the path is already taken, resolved by the
+ * caller — null creates.
+ */
+export async function putPage(pagePath, content, summaryFlag, existing) {
+    const parsed = parseKbContent(content);
+    let summary;
+    let body;
+    if (parsed) {
+        ({ summary, body } = parsed);
+    }
+    else if (summaryFlag) {
+        summary = summaryFlag;
+        body = content;
+    }
+    else {
+        fail(`${pagePath}: content must start with a frontmatter block (---\\nsummary: ...\\n---), or pass --summary to wrap it`, EXIT.usage);
+    }
+    if (existing) {
+        await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base/${existing.kb_file_id}`, {
+            method: "PUT",
+            body: JSON.stringify({
+                body_changed: true,
+                summary,
+                body,
+                base_revision_number: existing.latest_revision_number,
+            }),
+        });
+        return "updated";
+    }
+    await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base`, {
+        method: "POST",
+        body: JSON.stringify({ path: pagePath, summary, body }),
+    });
+    return "created";
+}
+export function assertSafeKbPath(pagePath) {
+    if (pagePath.startsWith("/") || pagePath.split("/").some((seg) => seg === "..")) {
+        fail(`refusing unsafe page path "${pagePath}"`, EXIT.usage);
+    }
+}
+/** All .md files under dir, keyed by their dir-relative (= KB) path. */
+export function readMarkdownTree(dir) {
+    const files = {};
+    const walk = (rel) => {
+        for (const entry of readdirSync(path.join(dir, rel))) {
+            if (entry.startsWith("."))
+                continue;
+            const relPath = rel ? `${rel}/${entry}` : entry;
+            const abs = path.join(dir, relPath);
+            if (statSync(abs).isDirectory())
+                walk(relPath);
+            else if (entry.endsWith(".md"))
+                files[relPath] = readFileSync(abs, "utf8");
+        }
+    };
+    try {
+        walk("");
+    }
+    catch (err) {
+        fail(`could not read ${dir}: ${err instanceof Error ? err.message : "unknown error"}`, EXIT.usage);
+    }
+    return files;
+}

package/dist/commands/kb.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerKbCommands(program: Command): void;

package/dist/commands/kb.js

@@ -0,0 +1,196 @@
+import { readFileSync } from "node:fs";
+import { apiJson, getContext, requireOrgId } from "../http.js";
+import { EXIT, confirm, fail, note, printData } from "../output.js";
+import { writeBundle } from "../bundle.js";
+import { assertSafeKbPath, lookupPage, putPage, readMarkdownTree } from "./kb-pages.js";
+import { downloadFile, uploadFile } from "./kb-blobs.js";
+import { isMarkdown } from "../content-kind.js";
+async function listTree() {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base`);
+    return body.files ?? [];
+}
+async function rowAt(kbPath) {
+    return (await listTree()).find((r) => r.path === kbPath) ?? null;
+}
+export function registerKbCommands(program) {
+    const kb = program
+        .command("kb")
+        .description("The Knowledge Base: markdown pages and the org's other files, in one tree");
+    kb
+        .command("ls [prefix]")
+        .description("List everything, optionally under a path prefix")
+        .action(async (prefix) => {
+        const { json } = getContext();
+        const rows = (await listTree()).filter((r) => !prefix || r.path.startsWith(prefix));
+        if (json) {
+            printData({ files: rows }, true);
+            return;
+        }
+        for (const r of rows) {
+            const page = isMarkdown(r.content_type);
+            const detail = page ? (r.summary ?? "") : `${r.bytes ?? 0} bytes`;
+            printData(`${page ? "page" : "file"}\t${r.path}\t${detail}`, false);
+        }
+    });
+    kb
+        .command("get <path>")
+        .description("Read a page's content, or download a file")
+        .option("--out <file>", 'write bytes to this file ("-" streams to stdout)')
+        .action(async (kbPath, opts) => {
+        const { json } = getContext();
+        const row = await rowAt(kbPath);
+        if (!row)
+            fail(`nothing at "${kbPath}"`, EXIT.notFound);
+        // A page prints its content; --out asks for bytes, which the download
+        // route serves for any row, markdown included.
+        if (!isMarkdown(row.content_type) || opts.out) {
+            await downloadFile(row, opts.out, json);
+            return;
+        }
+        const page = await lookupPage(row.kb_file_id);
+        if (json) {
+            printData(page, true);
+            return;
+        }
+        printData(page.content, false);
+    });
+    kb
+        .command("put <path> [localPath]")
+        .description("Write a page (from --file or stdin), or upload a file when localPath is given")
+        .option("--file <file>", "pages: read content from this file (default: stdin)")
+        .option("--summary <line>", "pages: wrap frontmatter-less content with this summary")
+        .option("--content-type <type>", "files: override the extension-derived content type")
+        .action(async (kbPath, localPath, opts) => {
+        const { json, yes } = getContext();
+        // A positional local path means "upload this"; everything else is a
+        // page write. Explicit rather than inferred from the extension, so
+        // uploading a .md document stays possible.
+        if (localPath) {
+            const result = await uploadFile(localPath, kbPath, opts.contentType, yes);
+            printData({ file_id: result.fileId, path: result.path, bytes: result.bytes }, json);
+            return;
+        }
+        assertSafeKbPath(kbPath);
+        let content;
+        if (opts.file) {
+            try {
+                content = readFileSync(opts.file, "utf8");
+            }
+            catch {
+                fail(`could not read ${opts.file}`, EXIT.usage);
+            }
+        }
+        else {
+            content = readFileSync(0, "utf8");
+        }
+        const existing = await rowAt(kbPath);
+        if (existing && !isMarkdown(existing.content_type)) {
+            fail(`"${kbPath}" holds ${existing.content_type} — replace it by uploading, not by writing a page`, EXIT.usage);
+        }
+        const outcome = await putPage(kbPath, content, opts.summary, existing);
+        printData({ path: kbPath, outcome }, json);
+    });
+    kb
+        .command("search <query>")
+        .description("Full-text search over pages")
+        .action(async (query) => {
+        const { json } = getContext();
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/knowledge-base?q=${encodeURIComponent(query)}`);
+        if (json) {
+            printData(body, true);
+            return;
+        }
+        for (const hit of body.results) {
+            printData(`${hit.path}: ${hit.snippet.replace(/\s+/g, " ")}`, false);
+        }
+    });
+    kb
+        .command("rm <path>")
+        .description("Delete a page or a file")
+        .action(async (kbPath) => {
+        const { json, yes } = getContext();
+        const row = await rowAt(kbPath);
+        if (!row)
+            fail(`nothing at "${kbPath}"`, EXIT.notFound);
+        const kind = isMarkdown(row.content_type) ? "page" : "file";
+        await confirm(`Delete ${kind} "${kbPath}"?`, yes);
+        const base = `/api/organizations/${requireOrgId()}`;
+        await apiJson(`${base}/knowledge-base/${row.kb_file_id}`, { method: "DELETE" });
+        printData({ path: kbPath, kind, deleted: true }, json);
+    });
+    kb
+        .command("mv <from> <to>")
+        .description("Move or rename a page or a file")
+        .action(async (from, to) => {
+        const { json, yes } = getContext();
+        const row = await rowAt(from);
+        if (!row)
+            fail(`nothing at "${from}"`, EXIT.notFound);
+        const kind = isMarkdown(row.content_type) ? "page" : "file";
+        await confirm(`Move ${kind} "${from}" to "${to}"?`, yes);
+        const base = `/api/organizations/${requireOrgId()}`;
+        await apiJson(`${base}/knowledge-base/${row.kb_file_id}`, {
+            method: "PATCH",
+            body: JSON.stringify({ path: to }),
+        });
+        printData({ from, to, kind }, json);
+    });
+    kb
+        .command("pull")
+        .description("Materialize every readable page into a directory of markdown files")
+        .requiredOption("--dir <dir>", "target directory")
+        .action(async (opts) => {
+        const { json } = getContext();
+        // Pages only: documents are bytes, and writing them into a markdown tree
+        // would produce files that `push` could not send back.
+        const rows = (await listTree()).filter((r) => isMarkdown(r.content_type));
+        const files = {};
+        for (const row of rows) {
+            assertSafeKbPath(row.path);
+            const page = await lookupPage(row.kb_file_id);
+            files[row.path] = page.content;
+        }
+        const pulled = writeBundle(opts.dir, files);
+        if (json) {
+            printData({ dir: opts.dir, pulled }, true);
+            return;
+        }
+        note(`Pulled ${pulled.length} page(s) into ${opts.dir}/`);
+    });
+    kb
+        .command("push")
+        .description("Write changed/new local markdown files back to the Knowledge Base (never prunes)")
+        .requiredOption("--dir <dir>", "source directory of .md files (paths mirror Knowledge Base paths)")
+        .option("--summary <line>", "summary for frontmatter-less new pages")
+        .action(async (opts) => {
+        const { json, yes } = getContext();
+        const local = readMarkdownTree(opts.dir);
+        const tree = new Map((await listTree()).map((r) => [r.path, r]));
+        const changed = [];
+        let unchanged = 0;
+        for (const [pagePath, content] of Object.entries(local)) {
+            assertSafeKbPath(pagePath);
+            const row = tree.get(pagePath);
+            // A path names exactly one thing: a page write must not land on bytes.
+            if (row && !isMarkdown(row.content_type)) {
+                fail(`"${pagePath}" holds ${row.content_type} — replace it by uploading, not by pushing a page`, EXIT.usage);
+            }
+            if (row && (await lookupPage(row.kb_file_id)).content === content)
+                unchanged += 1;
+            else
+                changed.push(pagePath);
+        }
+        if (changed.length === 0) {
+            if (json)
+                printData({ written: [], unchanged }, true);
+            else
+                note(`Nothing to push — ${unchanged} page(s) unchanged.`);
+            return;
+        }
+        await confirm(`Push ${changed.length} changed page(s)?\n${changed.map((p) => `  ${p}`).join("\n")}\n`, yes);
+        for (const pagePath of changed) {
+            await putPage(pagePath, local[pagePath], opts.summary, tree.get(pagePath) ?? null);
+        }
+        printData({ written: changed, unchanged }, json);
+    });
+}

package/dist/commands/tasks.d.ts

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+export interface LabelRow {
+    task_label_id: string;
+    name: string;
+    color: string;
+}
+/**
+ * Add-this / drop-that arguments over the labels a task already wears.
+ *
+ * The API takes the COMPLETE set — absent leaves labels alone, an array
+ * replaces. People at a prompt think in deltas, though, and a `--label` that
+ * quietly dropped whatever else the task wore is a good way to lose a label
+ * nobody was looking at. So the deltas are applied over `current` here, and
+ * `--no-labels` is the one way to say "none".
+ *
+ * Names resolve case-insensitively, matching the server. A name matching
+ * nothing comes back as `missing` rather than throwing, because whether that
+ * is a typo or a new label is the caller's question, not this function's.
+ */
+export declare function labelDelta(current: LabelRow[], known: LabelRow[], opts: {
+    add: string[];
+    remove: string[];
+    clear: boolean;
+}): {
+    ids: string[];
+    missing: string[];
+};
+export declare function registerTaskCommands(program: Command): void;

package/dist/commands/tasks.js

@@ -0,0 +1,320 @@
+import { apiJson, getContext, requireOrgId } from "../http.js";
+import { EXIT, confirm, fail, note, printData } from "../output.js";
+import { readStdin } from "./tool.js";
+async function resolveTask(identifier) {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/tasks?identifier=${encodeURIComponent(identifier)}`);
+    const task = body.tasks?.[0];
+    if (!task)
+        fail(`No task "${identifier}"`, EXIT.notFound);
+    return task;
+}
+async function resolveProject(key) {
+    const body = await apiJson(`/api/organizations/${requireOrgId()}/projects?key=${encodeURIComponent(key)}`);
+    const project = body.projects?.[0];
+    if (!project)
+        fail(`No project "${key}"`, EXIT.notFound);
+    return project;
+}
+/**
+ * Add-this / drop-that arguments over the labels a task already wears.
+ *
+ * The API takes the COMPLETE set — absent leaves labels alone, an array
+ * replaces. People at a prompt think in deltas, though, and a `--label` that
+ * quietly dropped whatever else the task wore is a good way to lose a label
+ * nobody was looking at. So the deltas are applied over `current` here, and
+ * `--no-labels` is the one way to say "none".
+ *
+ * Names resolve case-insensitively, matching the server. A name matching
+ * nothing comes back as `missing` rather than throwing, because whether that
+ * is a typo or a new label is the caller's question, not this function's.
+ */
+export function labelDelta(current, known, opts) {
+    const byName = new Map(known.map((l) => [l.name.toLowerCase(), l]));
+    const ids = new Set(opts.clear ? [] : current.map((l) => l.task_label_id));
+    for (const name of opts.remove) {
+        const label = byName.get(name.trim().toLowerCase());
+        if (label)
+            ids.delete(label.task_label_id);
+    }
+    const missing = [];
+    for (const name of opts.add) {
+        const label = byName.get(name.trim().toLowerCase());
+        if (label)
+            ids.add(label.task_label_id);
+        else
+            missing.push(name.trim());
+    }
+    return { ids: [...ids], missing };
+}
+/** The same, with the project's labels read (and missing ones minted) over HTTP. */
+async function resolveLabelIds(projectId, current, opts) {
+    if (opts.add.length === 0 && opts.remove.length === 0 && !opts.clear)
+        return undefined;
+    const route = `/api/organizations/${requireOrgId()}/projects/${projectId}/labels`;
+    const known = (await apiJson(route)).labels ?? [];
+    const { ids, missing } = labelDelta(current, known, opts);
+    if (missing.length > 0 && !opts.create) {
+        const available = known.length > 0 ? known.map((l) => l.name).join(", ") : "none yet";
+        fail(`No label ${missing.map((m) => `"${m}"`).join(", ")} in this project (has: ${available}). Pass --new-label to create it.`, EXIT.notFound);
+    }
+    for (const name of missing) {
+        const created = await apiJson(route, {
+            method: "POST",
+            body: JSON.stringify({ name }),
+        });
+        ids.push(created.label.task_label_id);
+        note(`Created label ${created.label.name}`);
+    }
+    return ids;
+}
+function formatRow(task) {
+    const flags = [task.status];
+    if (!task.is_ready && task.status !== "done" && task.status !== "canceled")
+        flags.push("blocked");
+    const assignee = task.assignee_name ?? task.assignee_email ?? "";
+    return `${task.identifier}\t${flags.join(",")}\t${task.title}${assignee ? `\t${assignee}` : ""}`;
+}
+/** `-` reads the body from stdin, matching the kb_files convention. */
+async function bodyFrom(literal, flag) {
+    if (literal === "-") {
+        const piped = await readStdin();
+        if (piped === null)
+            fail(`${flag} - requires text on stdin`, EXIT.usage);
+        return piped;
+    }
+    if (!literal)
+        fail(`${flag} is required`, EXIT.usage);
+    return literal;
+}
+export function registerTaskCommands(program) {
+    const tasks = program.command("tasks").description("Work items (projects, statuses, blockers)");
+    tasks
+        .command("projects")
+        .description("List task projects")
+        .action(async () => {
+        const { json } = getContext();
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/projects`);
+        if (json) {
+            printData(body, true);
+            return;
+        }
+        for (const p of body.projects ?? []) {
+            printData(`${p.key}\t${p.name}\t${p.open_task_count} open, ${p.ready_task_count} ready`, false);
+        }
+    });
+    tasks
+        .command("list")
+        .description("List work items")
+        .option("--project <key>", "only this project")
+        .option("--status <statuses>", "comma-separated: backlog,todo,in_progress,done,canceled")
+        .option("--assignee <who>", '"me" or a user id')
+        .option("--ready", "only work that can be started right now")
+        .option("--parent <identifier>", "only sub-tasks of this task")
+        .option("--all", "include done and canceled")
+        .option("-q, --query <text>", "match title and description")
+        .action(async (opts) => {
+        const { json } = getContext();
+        const params = new URLSearchParams();
+        if (opts.project)
+            params.set("project", (await resolveProject(opts.project)).project_id);
+        if (opts.status)
+            params.set("status", opts.status);
+        if (opts.assignee)
+            params.set("assignee", opts.assignee);
+        if (opts.ready)
+            params.set("ready", "true");
+        if (opts.all)
+            params.set("include_closed", "true");
+        if (opts.query)
+            params.set("q", opts.query);
+        if (opts.parent)
+            params.set("parent", (await resolveTask(opts.parent)).task_id);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/tasks?${params.toString()}`);
+        if (json) {
+            printData(body, true);
+            return;
+        }
+        for (const task of body.tasks ?? [])
+            printData(formatRow(task), false);
+    });
+    tasks
+        .command("ready")
+        .description("Work that can be started right now (open, unblocked, no open sub-tasks)")
+        .option("--project <key>", "only this project")
+        .action(async (opts) => {
+        const { json } = getContext();
+        const params = new URLSearchParams({ ready: "true" });
+        if (opts.project)
+            params.set("project", (await resolveProject(opts.project)).project_id);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/tasks?${params.toString()}`);
+        if (json) {
+            printData(body, true);
+            return;
+        }
+        for (const task of body.tasks ?? [])
+            printData(formatRow(task), false);
+    });
+    tasks
+        .command("show <identifier>")
+        .description("One work item in full, with sub-tasks, blockers, and comments")
+        .action(async (identifier) => {
+        const task = await resolveTask(identifier);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}`);
+        printData(body, getContext().json);
+    });
+    tasks
+        .command("create")
+        .description("Create a work item")
+        .requiredOption("--project <key>", "project key, e.g. OPS")
+        .requiredOption("--title <title>", "one-line summary")
+        .option("--description <text>", '"-" reads from stdin')
+        .option("--status <status>", "defaults to backlog")
+        .option("--assignee <who>", '"me" or a user id')
+        .option("--parent <identifier>", "make this a sub-task")
+        .option("--due <date>", "YYYY-MM-DD")
+        .option("--label <name...>", "put this label on it (repeatable)", [])
+        .option("--new-label", "create any --label that doesn't exist yet")
+        .action(async (opts) => {
+        const project = await resolveProject(opts.project);
+        const description = opts.description === undefined ? undefined : await bodyFrom(opts.description, "--description");
+        const labelIds = await resolveLabelIds(project.project_id, [], {
+            add: opts.label,
+            remove: [],
+            clear: false,
+            create: opts.newLabel === true,
+        });
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/projects/${project.project_id}/tasks`, {
+            method: "POST",
+            body: JSON.stringify({
+                title: opts.title,
+                description,
+                status: opts.status,
+                assigned_to_user_id: opts.assignee,
+                parent_task_id: opts.parent ? (await resolveTask(opts.parent)).task_id : undefined,
+                due_on: opts.due,
+                label_ids: labelIds,
+            }),
+        });
+        note(`Created ${body.task.identifier}`);
+        printData(body.task, getContext().json);
+    });
+    tasks
+        .command("update <identifier>")
+        .description("Change a work item")
+        .option("--title <title>")
+        .option("--description <text>", '"-" reads from stdin')
+        .option("--status <status>")
+        .option("--assignee <who>", '"me" or a user id')
+        .option("--unassign", "clear the assignee")
+        .option("--parent <identifier>")
+        .option("--no-parent", "detach from its parent")
+        .option("--after <identifier>", "place directly after this task")
+        .option("--before <identifier>", "place directly before this task")
+        .option("--project <key>", "move to this project (renumbers the task)")
+        .option("--due <date>", "YYYY-MM-DD")
+        .option("--no-due", "clear the due date")
+        .option("--label <name...>", "add this label, keeping the others (repeatable)", [])
+        .option("--remove-label <name...>", "take this label off (repeatable)", [])
+        .option("--no-labels", "take every label off")
+        .option("--new-label", "create any --label that doesn't exist yet")
+        .action(async (identifier, opts) => {
+        const task = await resolveTask(identifier);
+        const payload = {};
+        if (opts.title)
+            payload.title = opts.title;
+        if (opts.description !== undefined) {
+            payload.description = await bodyFrom(opts.description, "--description");
+        }
+        if (opts.status)
+            payload.status = opts.status;
+        if (opts.unassign)
+            payload.assigned_to_user_id = null;
+        else if (opts.assignee)
+            payload.assigned_to_user_id = opts.assignee;
+        if (opts.parent === false)
+            payload.parent_task_id = null;
+        else if (typeof opts.parent === "string") {
+            payload.parent_task_id = (await resolveTask(opts.parent)).task_id;
+        }
+        if (opts.after)
+            payload.rank_after_task_id = (await resolveTask(opts.after)).task_id;
+        if (opts.before)
+            payload.rank_before_task_id = (await resolveTask(opts.before)).task_id;
+        if (opts.project)
+            payload.project_id = (await resolveProject(opts.project)).project_id;
+        if (opts.due === false)
+            payload.due_on = null;
+        else if (typeof opts.due === "string")
+            payload.due_on = opts.due;
+        // Against the project the task will BE in. A move drops the old
+        // project's labels server-side — the destination has its own
+        // vocabulary — so there is nothing to carry over either.
+        const destination = payload.project_id ?? task.project_id;
+        const labelIds = await resolveLabelIds(destination, payload.project_id ? [] : task.labels, {
+            add: opts.label,
+            remove: opts.removeLabel,
+            clear: opts.labels === false,
+            create: opts.newLabel === true,
+        });
+        if (labelIds)
+            payload.label_ids = labelIds;
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}`, { method: "PATCH", body: JSON.stringify(payload) });
+        // A move renumbers, and a silent renumber is how people lose a task.
+        if (body.task.identifier !== task.identifier) {
+            note(`${task.identifier} → ${body.task.identifier}`);
+        }
+        printData(body.task, getContext().json);
+    });
+    tasks
+        .command("done <identifier>")
+        .description("Mark a work item done")
+        .action(async (identifier) => {
+        const task = await resolveTask(identifier);
+        const body = await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}`, { method: "PATCH", body: JSON.stringify({ status: "done" }) });
+        note(`${body.task.identifier} is done`);
+    });
+    tasks
+        .command("comment <identifier> [text]")
+        .description('Add a comment ("-" reads from stdin)')
+        .action(async (identifier, text) => {
+        const task = await resolveTask(identifier);
+        const body = await bodyFrom(text ?? "-", "comment text");
+        await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}/comments`, {
+            method: "POST",
+            body: JSON.stringify({ body }),
+        });
+        note(`Commented on ${task.identifier}`);
+    });
+    tasks
+        .command("block <identifier>")
+        .description("Record that this task waits on another")
+        .requiredOption("--by <identifier>", "the task it waits on")
+        .action(async (identifier, opts) => {
+        const [task, blocker] = [await resolveTask(identifier), await resolveTask(opts.by)];
+        await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}/dependencies`, {
+            method: "POST",
+            body: JSON.stringify({ blocking_task_id: blocker.task_id }),
+        });
+        note(`${task.identifier} is now blocked by ${blocker.identifier}`);
+    });
+    tasks
+        .command("unblock <identifier>")
+        .description("Clear a blocked-by relationship")
+        .requiredOption("--by <identifier>", "the task it no longer waits on")
+        .action(async (identifier, opts) => {
+        const [task, blocker] = [await resolveTask(identifier), await resolveTask(opts.by)];
+        await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}/dependencies?blocking_task_id=${blocker.task_id}`, { method: "DELETE" });
+        note(`${task.identifier} is no longer blocked by ${blocker.identifier}`);
+    });
+    tasks
+        .command("delete <identifier>")
+        .description("Delete a work item")
+        .option("--cascade", "also delete its sub-tasks")
+        .action(async (identifier, opts) => {
+        const { yes } = getContext();
+        const task = await resolveTask(identifier);
+        await confirm(`Delete ${task.identifier} "${task.title}"?`, yes);
+        await apiJson(`/api/organizations/${requireOrgId()}/tasks/${task.task_id}${opts.cascade ? "?cascade=true" : ""}`, { method: "DELETE" });
+        note(`Deleted ${task.identifier}`);
+    });
+}

package/dist/commands/tool.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+/**
+ * `fieldwork tool run <name>` argument assembly (the httpie convention):
+ * --args takes a JSON object ('-' reads stdin); repeated --arg entries merge
+ * over it — `k=v` as a string, `k:=v` JSON-parsed.
+ */
+export declare function buildToolArgs(argsOption: string | undefined, argEntries: string[], stdin: string | null): Record<string, unknown>;
+/** Merge `k=v` (string) / `k:=json` entries into base — shared by tool run's
+ * --arg and the query verbs' --param. */
+export declare function applyArgEntries(base: Record<string, unknown>, entries: string[], flag: string): Record<string, unknown>;
+export declare function readStdin(): Promise<string | null>;
+export declare function registerToolCommands(program: Command): void;