@bli-cockpit/cli 0.2.244 → 0.2.245

package/dist/commands/local-args-tower-milestone.js

@@ -0,0 +1,120 @@
+/**
+ * `cockpit milestone` argument parsing (BLI-22360).
+ *
+ *   list [--project <ref>] [--archived]
+ *   show <ref> [--project <ref>] [--limit <n>] [--cursor <c>]
+ *   create --project <ref> --name "<n>" [--description <text|->] [--target YYYY-MM-DD]
+ *   update <ref> [--project <ref>] [--name <n>] [--description <text|-|none>] [--target <day|none>] [--expected-updated-at <ts>]
+ *   archive|restore <ref> [--project <ref>] [--expected-updated-at <ts>]
+ *   add|remove <ref> <ticket> [<ticket> ...] [--project <ref>]
+ *
+ * A milestone ref is an id or an exact, case-insensitive name; two milestones with one name are refused by the door
+ * (`milestone_ref_ambiguous`) with their ids, never guessed. `--request-id` belongs to every write.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const ACTIONS = ["list", "show", "create", "update", "archive", "restore", "add", "remove"];
+const WRITES = ["create", "update", "archive", "restore", "add", "remove"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+export const MILESTONE_TICKETS_MAX = 50;
+function target(value, action) {
+    if (value === undefined)
+        return undefined;
+    if (value.trim().toLowerCase() === "none") {
+        if (action !== "update")
+            throw new Error("--target none clears a date on `milestone update`; leave --target off instead.");
+        return null;
+    }
+    if (!DAY.test(value) || new Date(`${value}T12:00:00Z`).toISOString().slice(0, 10) !== value) {
+        throw new Error("--target must be a calendar date as YYYY-MM-DD, or none.");
+    }
+    return value;
+}
+export function parseMilestoneArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home", "--dashboard-url", "--json", "--archived", "--project", "--name", "--description", "--target",
+            "--limit", "--cursor", "--request-id", "--expected-updated-at",
+        ],
+        valueFlags: [
+            "--home", "--dashboard-url", "--project", "--name", "--description", "--target",
+            "--limit", "--cursor", "--request-id", "--expected-updated-at",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!ACTIONS.includes(action)) {
+        throw new Error(`Unknown milestone command: ${first}. Try list, show, create, update, archive, restore, add or remove.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    const given = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    let ref;
+    let tickets = [];
+    if (action === "list" || action === "create") {
+        if (rest.length > 0)
+            throw new Error(`milestone ${action} does not take "${rest[0]}".`);
+    }
+    else if (action === "add" || action === "remove") {
+        if (rest.length < 2)
+            throw new Error(`milestone ${action} takes a milestone and at least one ticket: milestone ${action} <milestone> BLI-123 [BLI-124 ...].`);
+        ref = rest[0];
+        tickets = [...new Set(rest.slice(1).flatMap((t) => t.split(",")).map((t) => t.trim()).filter(Boolean))];
+        if (tickets.length > MILESTONE_TICKETS_MAX)
+            throw new Error(`At most ${MILESTONE_TICKETS_MAX} tickets per call.`);
+    }
+    else {
+        if (rest.length !== 1)
+            throw new Error(`milestone ${action} takes exactly one milestone id or name.`);
+        ref = rest[0];
+    }
+    if (action !== "create" && action !== "update" && (given("--name") || given("--description") || given("--target"))) {
+        throw new Error("--name, --description and --target belong to milestone create and update.");
+    }
+    if (action !== "list" && given("--archived"))
+        throw new Error("--archived belongs to milestone list.");
+    if (action !== "show" && (given("--limit") || given("--cursor")))
+        throw new Error("--limit and --cursor belong to milestone show.");
+    if (!WRITES.includes(action) && given("--request-id"))
+        throw new Error("--request-id belongs to the milestone writes.");
+    if (!["update", "archive", "restore"].includes(action) && given("--expected-updated-at")) {
+        throw new Error("--expected-updated-at belongs to milestone update, archive and restore.");
+    }
+    const project = optionalNonEmpty(values.flags.get("--project"));
+    const name = optionalNonEmpty(values.flags.get("--name"));
+    if (action === "create" && (!project || !name))
+        throw new Error('milestone create needs --project <project> and --name "<name>".');
+    const rawDescription = values.flags.get("--description");
+    const description = rawDescription === undefined ? undefined
+        : action === "update" && rawDescription.trim().toLowerCase() === "none" ? null : rawDescription;
+    const targetDate = target(values.flags.get("--target"), action);
+    if (action === "update" && name === undefined && description === undefined && targetDate === undefined) {
+        throw new Error("milestone update needs --name, --description (or none) or --target (or none). Archive with `milestone archive`.");
+    }
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const expectedUpdatedAt = optionalNonEmpty(values.flags.get("--expected-updated-at"));
+    if (expectedUpdatedAt && Number.isNaN(Date.parse(expectedUpdatedAt))) {
+        throw new Error("--expected-updated-at must be the updated_at timestamp you last read.");
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+    return {
+        kind: "milestone",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(ref === undefined ? {} : { ref }),
+        ...(project ? { project } : {}),
+        includeArchived: values.booleans.has("--archived"),
+        ...(name ? { name } : {}),
+        ...(description === undefined ? {} : { description }),
+        ...(targetDate === undefined ? {} : { targetDate }),
+        tickets,
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor ? { cursor } : {}),
+        ...(requestId ? { requestId } : {}),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+        json: values.booleans.has("--json"),
+    };
+}

package/dist/commands/local-args-tower-work.js

@@ -23,6 +23,7 @@ import { NOTIFY_ACTIONS, NOTIFY_VALUE_FLAGS, isNotifyAction, parseNotifyArgs } f
 import { VIEW_BOOLEAN_FLAGS, VIEW_VALUE_FLAGS, parseViewArgs } from "./view-args.js";
 import { parseTemplateArgs } from "./template-args.js";
 import { CYCLE_BOOLEAN_FLAGS, CYCLE_VALUE_FLAGS, parseCycleArgs, readCycleField } from "./cycle-args.js";
+import { readArchivedFlag, readIssuePage } from "./issue-page-args.js";
 const ISSUE_ACTIONS = new Set([
     "mutation-status",
     "board",
@@ -37,6 +38,9 @@ const ISSUE_ACTIONS = new Set([
     "restore",
     "label",
     "batch",
+    // BLI-22367: reversible archive. `restore` stays the description-version verb.
+    "archive",
+    "unarchive",
     "relations",
     "relate",
     "unrelate",
@@ -56,6 +60,8 @@ const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
     "versions",
     "restore",
     "label",
+    "archive",
+    "unarchive",
     "relations",
     "relate",
     "unrelate",
@@ -99,6 +105,7 @@ const ISSUE_ALLOWED_FLAGS = [
     "--sort",
     "--dir",
     "--all",
+    "--archived",
     "--body-stdin",
     "--json",
     ...VIEW_BOOLEAN_FLAGS,
@@ -174,9 +181,10 @@ export function parseIssueArgs(args) {
         throw new Error("--request-id must be a UUID.");
     if (action === "mutation-status" && !UUID_PATTERN.test(issueRef ?? ""))
         throw new Error("mutation-status needs a request UUID.");
-    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore", "label", "batch", "relate", "unrelate"].includes(action)) {
-        throw new Error("Write-safety flags belong to create, update, move, comment, restore, label, relate, unrelate or batch.");
+    if ((requestId || expectedRevision !== undefined) && !["create", "update", "move", "comment", "restore", "label", "batch", "relate", "unrelate", "archive", "unarchive"].includes(action)) {
+        throw new Error("Write-safety flags belong to create, update, move, comment, restore, label, relate, unrelate, archive, unarchive or batch.");
     }
+    const archived = readArchivedFlag(action, values);
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
     const fields = readIssueFields(action, values);
@@ -192,61 +200,18 @@ export function parseIssueArgs(args) {
     if (action === "board" && boardProject && !UUID_PATTERN.test(boardProject))
         throw new Error("board --project requires a uuid.");
     const priority = readIssuePriority(values);
-    const estimate = readIssueSize(values);
+    const estimate = readIssueSize(action, values);
+    checkNoneClears(action, values);
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
     const versionNumber = readIssueVersion(action, values);
-    return { ...buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page, fields), ...readRelationFlags(action, values) };
-}
-const INSTANT = /^\d{4}-\d\d-\d\d(?:T\d\d:\d\d:\d\d(?:\.\d{1,6})?(?:Z|[+-]\d\d:\d\d))?$/;
-/** BLI-21315: the cursor contract's flags. Filters and sort belong to `list`; `--cursor` also to `history`. */
-function readIssuePage(action, values) {
-    const named = ["--q", "--created-after", "--created-before", "--updated-after", "--updated-before", "--sort", "--dir"];
-    for (const flag of named) {
-        if (values.flags.has(flag) && action !== "list")
-            throw new Error(`${flag} belongs to \`cockpit ticket list\`.`);
-    }
-    if (values.booleans.has("--all") && action !== "list")
-        throw new Error("--all belongs to `cockpit ticket list`.");
-    if (values.flags.has("--cursor") && action !== "list" && action !== "history") {
-        throw new Error("--cursor belongs to `cockpit ticket list` and `cockpit ticket history`.");
-    }
-    const instants = {};
-    for (const flag of ["--created-after", "--created-before", "--updated-after", "--updated-before"]) {
-        const value = optionalNonEmpty(values.flags.get(flag));
-        if (value !== undefined && (!INSTANT.test(value) || !Number.isFinite(Date.parse(value)))) {
-            throw new Error(`${flag} must be a UTC instant like 2026-10-01T00:00:00Z or a date like 2026-10-01.`);
-        }
-        instants[flag] = value;
-    }
-    const sort = optionalNonEmpty(values.flags.get("--sort"));
-    if (sort !== undefined && sort !== "updated_at" && sort !== "created_at")
-        throw new Error("--sort must be updated_at or created_at.");
-    const dir = optionalNonEmpty(values.flags.get("--dir"));
-    if (dir !== undefined && dir !== "asc" && dir !== "desc")
-        throw new Error("--dir must be asc or desc.");
-    const all = values.booleans.has("--all");
-    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
-    if (all && cursor)
-        throw new Error("--all walks from the start; drop --cursor, or pass --cursor without --all to read one page.");
-    const q = optionalNonEmpty(values.flags.get("--q"));
-    return {
-        ...(cursor ? { cursor } : {}),
-        ...(q ? { q } : {}),
-        ...(instants["--created-after"] ? { createdAfter: instants["--created-after"] } : {}),
-        ...(instants["--created-before"] ? { createdBefore: instants["--created-before"] } : {}),
-        ...(instants["--updated-after"] ? { updatedAfter: instants["--updated-after"] } : {}),
-        ...(instants["--updated-before"] ? { updatedBefore: instants["--updated-before"] } : {}),
-        ...(sort ? { sort } : {}),
-        ...(dir ? { dir } : {}),
-        ...(all ? { all } : {}),
-    };
+    return { ...buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page, fields), ...readRelationFlags(action, values), ...(archived ? { archived } : {}) };
 }
 function readIssueAction(values) {
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!ISSUE_ACTIONS.has(action)) {
-        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, label, relations, relate, unrelate, views, templates, cycles, inbox, read, unread, subscribe, unsubscribe, notifications, history, versions, restore, batch, or mutation-status.`);
+        throw new Error(`Unknown issue command: ${first}. Try board, list, show, create, update, move, comment, label, archive, unarchive, relations, relate, unrelate, views, templates, cycles, inbox, read, unread, subscribe, unsubscribe, notifications, history, versions, restore, batch, or mutation-status.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -318,9 +283,37 @@ function readIssuePriority(values) {
     }
     return priority;
 }
-function readIssueSize(values) {
+/**
+ * `--size S|M|L`, or `none` on update to clear the size (BLI-22367). Only ever what the person typed: no surface
+ * picks a size for them.
+ */
+function readIssueSize(action, values) {
     const raw = optionalNonEmpty(values.flags.get("--size"));
-    return raw === undefined ? undefined : estimateForSize(raw);
+    if (raw === undefined)
+        return undefined;
+    if (raw.toLowerCase() === "none") {
+        if (action !== "update")
+            throw new Error("--size none clears a size on `cockpit ticket update`; leave --size off to create without one.");
+        return null;
+    }
+    return estimateForSize(raw);
+}
+/**
+ * ONE spelling clears a field on update: `none` (BLI-22367). `--parent none` and `--project none` join the existing
+ * `--assignee none`, `--due none`, `--cycle none` and `--size none`. On create there is nothing to clear, so `none`
+ * is refused rather than looked up as a ticket or project called "none".
+ */
+function checkNoneClears(action, values) {
+    for (const flag of ["--parent", "--project"]) {
+        const value = optionalNonEmpty(values.flags.get(flag));
+        if (value?.toLowerCase() !== "none")
+            continue;
+        if (action === "update")
+            continue;
+        throw new Error(action === "create"
+            ? `${flag} none clears it on \`cockpit ticket update\`; leave ${flag} off to create without one.`
+            : `${flag} none clears it on \`cockpit ticket update\` only.`);
+    }
 }
 function readIssueAssignee(action, values) {
     // An assignee is `me`, `unassigned`, or a person's uuid. A name or an

package/dist/commands/local-args-tower.js

@@ -33,6 +33,7 @@ export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_
 export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
 export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";
 export { parseGithubArgs } from "./local-args-tower-github.js";
+export { parseMilestoneArgs } from "./local-args-tower-milestone.js";
 export { parseSearchArgs } from "./local-args-tower-search.js";
 export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";

package/dist/commands/local-args.js

@@ -19,6 +19,7 @@ import { parseGlossaryArgs } from "./glossary.js";
 import { parseSpendArgs } from "./spend.js";
 import { parsePushArgs } from "./push.js";
 import { parseRootsArgs } from "./roots.js";
+import { parseMilestoneArgs } from "./local-args-tower-milestone.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
 import { parseCiArgs, parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseHitsArgs, parseIntentionsArgs, parseWhoArgs, parsePeopleArgs, parseApprovalsArgs, parseDrillsArgs, parseManagerArgs, parseImageArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
@@ -90,6 +91,7 @@ const COMMAND_PARSERS = new Map([
     ["mail", (_command, rest) => parseMailArgs(rest)],
     ["cal", (_command, rest) => parseCalArgs(rest)],
     ["project", (_command, rest) => parseProjectArgs(rest)],
+    ["milestone", (_command, rest) => parseMilestoneArgs(rest)],
     ["search", (_command, rest) => parseSearchArgs(rest)],
     ["github", (_command, rest) => parseGithubArgs(rest)],
     ["release", (_command, rest) => parseReleaseArgs(rest)],

package/dist/commands/local-command-shapes-milestone.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/local-help-commands-tower.js

@@ -18,6 +18,7 @@ import { DOCS_FORMATTING_HELP } from "./local-help-docs-formatting.js";
 import { DOCS_INBOX_HELP } from "./local-help-docs-inbox.js";
 import { DOCS_RECOVERY_HELP } from "./local-help-docs-recovery.js";
 import { PROJECT_HELP } from "./local-help-project.js";
+import { MILESTONE_HELP } from "./local-help-milestone.js";
 import { INBOX_HELP_LINES } from "./local-help-inbox.js";
 import { WORK_NOTIFY_HELP_LINES } from "./local-help-work-notify.js";
 import { VIEWS_HELP_LINES } from "./local-help-views.js";
@@ -122,7 +123,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "issue",
         [
-            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|label <id>|relations <id>|relate <id>|unrelate <id>|views [list|show|save|update|favorite|unfavorite|settings]|templates [list|show|versions|save|update|apply]|cycles [list|show|create|update|map]|inbox|read <notification-id>...|unread <notification-id>...|subscribe <id>|unsubscribe <id>|notifications [set|receipts]|history <id>|versions <id>|restore <id> --version <n>|batch|mutation-status <request-uuid>] [flags]",
+            "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|label <id>|archive <id>|unarchive <id>|relations <id>|relate <id>|unrelate <id>|views [list|show|save|update|favorite|unfavorite|settings]|templates [list|show|versions|save|update|apply]|cycles [list|show|create|update|map]|inbox|read <notification-id>...|unread <notification-id>...|subscribe <id>|unsubscribe <id>|notifications [set|receipts]|history <id>|versions <id>|restore <id> --version <n>|batch|mutation-status <request-uuid>] [flags]",
             "",
             "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
             "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--label <name>] [--q <text>] [--created-after|--created-before|--updated-after|--updated-before <utc instant|date>] [--sort updated_at|created_at] [--dir desc|asc] [--limit <n>] [--cursor <c>] [--all] — the issues you may see, most recently updated first. A page is 100 by default and at most 500. Filters run in the database BEFORE the page, so a label or title match deep in the set is found. --q is a case-insensitive title contains (% and _ are literal); *-after is inclusive, *-before is exclusive. --json adds next_cursor, has_more, coverage (complete|capped|failed_partial), requested, returned, unique: pass next_cursor back as --cursor with the same other flags. --all walks every page and streams ONE JSON OBJECT PER LINE (NDJSON; rows carry assignee_id, no names), then a final {\"type\":\"coverage\",...} line naming the coverage; an interrupted walk ends with coverage failed_partial, the reason and the resume cursor, and exits 1. Each row carries assignee_name/assignee_email alongside the bare assignee_id (BLI-10450, one extra `cockpit team members` call for the whole page, never per row), and a `size` label (S/M/L) alongside the raw `estimate` when it matches Tower's own scale (BLI-10575). --json shape: { issues: [{ id, identifier, title, state, priority, estimate, size, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
@@ -130,14 +131,15 @@ export const TOWER_COMMAND_HELP = [
             "show <id> [<id>...] — one or more issues: title, state, priority, size, assignee (name and email, not just its id), description, and every comment on each. Several ids read in one call — one bad id never loses the rest.",
             "  --json shape: one id answers { issue, comments }, unchanged from before BLI-10450 (plus `estimate`/`size`, BLI-10575). Several ids answer { issues: [{ ref, ok, issue, comments } | { ref, ok: false, error, detail }] }.",
             "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--size S|M|L] [--assignee me|<uuid>] [--parent <id>] [--state <state>] [--due YYYY-MM-DD] [--file <path>] — --state is the starting state (default backlog); --due sets a due date. The DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description. --size maps onto the existing `estimate` column, Tower's own scale: S=1, M=3, L=5 (BLI-10575) — an estimate outside that scale (an imported Linear point value, say) just has no size label on a read. --json shape: { issue }.",
-            "update <id> [--title \"<t>\"] [--priority 0-4] [--size S|M|L] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--due YYYY-MM-DD|none] [--file <path>|--body-stdin] — only the fields you pass change: a field you leave off is never touched. --due none clears the due date; --assignee none clears the owner. A size already on the ticket that is not S, M or L (an imported estimate such as 8) stays as it is until you pass --size. State does NOT move here; use move. --json shape: { issue }.",
+            "update <id> [--title \"<t>\"] [--priority 0-4] [--size S|M|L|none] [--assignee me|<uuid>|none] [--project <name|id>|none] [--parent <id>|none] [--cycle <name|id>|none] [--due YYYY-MM-DD|none] [--file <path>|--body-stdin] — only the fields you pass change: a field you leave off is never touched. `none` is the ONE spelling that clears: --size none, --assignee none, --project none, --parent none (top-level again), --cycle none and --due none (BLI-22367). A committed write prints \"Saved in Tower (revision N). Linear copy: pending|delivered|failed|not mirrored (reason)\"; a refusal says \"not committed: nothing changed\" unless the answer was genuinely lost (then check mutation-status). A size already on the ticket that is not S, M or L (an imported estimate such as 8) stays as it is until you pass --size. State does NOT move here; use move. --json shape: { issue }.",
             "label <id> [--add <label>]... [--remove <label>]... [--request-id <uuid>] [--expected-revision <n>] — adds and removes EXISTING labels (names match exactly, ignoring case; a uuid also works) in one receipt, one history row and one revision step. An unknown name is refused by name and nothing changes; labels are never created here. Any member may detach. --json shape: { issue, labels, mutation }. relations <id> [--json] — what blocks what: Blocks, Blocked by, Related, Duplicate of, Duplicates, and Not in Tower (an imported Linear edge to a ticket Tower does not have, shown as text). A sub-ticket is NOT a blocker and is not listed here. Edges to a deleted or unreadable ticket are left out and counted (coverage.hidden). --json shape: { relations: { blocks, blocked_by, related, duplicates, duplicate_of, unmapped, coverage } }, each item { relation_id, kind, source: native|linear, issue: { id, identifier, title, state } }. relate <id> --blocks <id> | --blocked-by <id> | --related <id> | --duplicate-of <id> [--request-id <uuid>] [--expected-revision <n>] — exactly one kind flag; records one edge as one receipt, one history row and one revision step (--blocked-by stores the edge from the other ticket). Refusals by name: relation_exists, relation_inverse_blocks, relation_self, relation_target_not_found_or_unreadable. unrelate <id> --relation <relation-id> | the same kind flag plus the other ticket — removes the edge (kept as removed, never re-imported). Refusal: relation_not_found. Setting --parent so a ticket would sit under its own sub-ticket is refused as circular_parent, a chain deeper than 200 as hierarchy_too_deep. --json shape: { issue, relation_id, mutation }. Also: move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
+            "archive <id> | unarchive <id> [--request-id <uuid>] [--expected-revision <n>] — archive HIDES a ticket from lists, the board and counts; nothing is deleted, `show` still reads it (marked ARCHIVED), and unarchive brings it back with every field, comment and history row (BLI-22367). One receipt, one history row, one revision step. Tower-only: the Linear copy (if any) is not touched, so the receipt says not mirrored (archive_is_tower_only). Refusals: issue_already_archived, issue_not_archived, revision_conflict, request_id_reused. `list --archived [--q <text>] [--project <name|id>] [--limit <n>] [--cursor <c>] [--all]` lists archived tickets only, most recently archived first. --json shape: { issue, mutation }.",
             "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
             "Writes accept --request-id <uuid> and --expected-revision <n>. Keep the UUID and identical fields across retries; JSON includes mutation receipt and mirror delivery separately.",
             "mutation-status <request-uuid> — check your own local commit and mirror delivery after a lost response; no receipt means unknown_check_again.",
             "history <id> [--limit <n>] [--cursor <c>] — every recorded state move and reassignment, oldest first; --json carries the same page fields as list.",
             "versions <id> [--limit <n>] — every saved description, newest first, each with its number, id, author, source and time (BLI-21300). --json shape: { versions: [{ id, version, markdown, author_id, source, restored_from_version, created_at }] }.",
-            "restore <id> --version <n> [--request-id <uuid>] [--expected-revision <n>] — writes version <n>'s text back as a NEW version; nothing is rewritten, so the restore can itself be undone. A stale revision conflicts and changes nothing. --json shape: { issue, mutation }. batch [--file <path>] [--request-id <uuid>] — changes up to 50 tickets in one call (BLI-21551). Reads { \"items\": [...] } (or a bare array) from stdin or --file, never argv. Each item is { issue, expected_revision?, request_id?, state? | priority? | assignee? | size? | project? | due_date? }: a state move OR field changes, not both, and one item per ticket. It is NOT all-or-nothing: every item is its own change with its own receipt, one stderr line each. Exit 0 only when every item committed, 1 otherwise; the batch request id is printed, and a retry with --request-id writes nothing twice. --json shape: { ok, request_id, requested, committed, refused, unknown, items: [{ index, issue, outcome, reason?, message?, request_id, revision?, row? }] }. Example: echo '{\"items\":[{\"issue\":\"BLI-1\",\"priority\":2},{\"issue\":\"BLI-2\",\"state\":\"done\"}]}' | cockpit ticket batch --json.",
+            "restore <id> --version <n> [--request-id <uuid>] [--expected-revision <n>] — writes version <n>'s text back as a NEW version; nothing is rewritten, so the restore can itself be undone. A stale revision conflicts and changes nothing. --json shape: { issue, mutation }. batch [--file <path>] [--request-id <uuid>] — changes up to 50 tickets in one call (BLI-21551). Reads { \"items\": [...] } (or a bare array) from stdin or --file, never argv. Each item is { issue, expected_revision?, request_id?, state? | priority? | assignee? | size? | project? | parent? | cycle? | due_date? } (\"none\" or null clears assignee, size, project, parent, cycle and due_date): a state move OR field changes, not both, and one item per ticket. It is NOT all-or-nothing: every item is its own change with its own receipt, one stderr line each. Exit 0 only when every item committed, 1 otherwise; the batch request id is printed, and a retry with --request-id writes nothing twice. --json shape: { ok, request_id, requested, committed, refused, unknown, items: [{ index, issue, outcome, reason?, message?, request_id, revision?, row? }] }. Example: echo '{\"items\":[{\"issue\":\"BLI-1\",\"priority\":2},{\"issue\":\"BLI-2\",\"state\":\"done\"}]}' | cockpit ticket batch --json.",
             ...VIEWS_HELP_LINES,
             ...TEMPLATES_HELP_LINES,
             ...CYCLES_HELP_LINES,
@@ -216,6 +218,7 @@ export const TOWER_COMMAND_HELP = [
         ],
     ],
     PROJECT_HELP,
+    MILESTONE_HELP,
     [
         "speed",
         [

package/dist/commands/local-help-milestone.js

@@ -0,0 +1,23 @@
+/** `cockpit milestone` help (BLI-22360), kept beside the parser in local-args-tower-milestone.ts. */
+export const MILESTONE_HELP = [
+    "milestone",
+    [
+        "Usage: cockpit milestone [list] [--project <id|name>] [--archived] [--json]",
+        "       cockpit milestone show <id|name> [--project <id|name>] [--limit <n>] [--cursor <c>] [--json]",
+        '       cockpit milestone create --project <id|name> --name "<name>" [--description <text|->] [--target YYYY-MM-DD] [--request-id <uuid>] [--json]',
+        "       cockpit milestone update <id|name> [--project <p>] [--name <n>] [--description <text|-|none>] [--target <day|none>] [--expected-updated-at <ts>] [--request-id <uuid>] [--json]",
+        "       cockpit milestone archive|restore <id|name> [--project <p>] [--expected-updated-at <ts>] [--request-id <uuid>] [--json]",
+        "       cockpit milestone add|remove <id|name> <ticket> [<ticket> ...] [--project <p>] [--request-id <uuid>] [--json]",
+        "",
+        "Project milestones: a dated goal inside ONE project, with the tickets that make it up. Not Tower Manager's timeline milestones.",
+        "list — a project's milestones (every project's without --project), target date first, each with its progress. --archived includes archived ones.",
+        "show <ref> — the milestone, its progress and a page of its tickets. <ref> is an id or an exact name (case-folded, never fuzzy); --project narrows a name to one project; two milestones with one name are milestone_ref_ambiguous and the message lists their ids.",
+        "Progress is a count: done of (done + open) tickets. Canceled tickets are shown but left out of the total; estimates never weight it. Points (estimate sum over the estimated tickets only) and how many tickets carry an estimate are printed beside it. A milestone with more than 5,000 tickets says its counts are a floor.",
+        "create / update — name 1 to 120 characters, unique among the project's active milestones; `--description -` reads stdin, `--description none` and `--target none` clear (update). A milestone never moves to another project.",
+        "archive / restore — soft: tickets keep their milestone, nothing is deleted, there is no delete verb. An archived milestone refuses new tickets (milestone_archived).",
+        "add / remove <milestone> <tickets...> — up to 50 ticket ids or identifiers, one receipt each; one refusal never stops the others. A ticket must already be in the milestone's project (milestone_project_mismatch); a ticket is in at most one milestone, so add moves it from another. remove only takes out tickets that are in this milestone. Moving a ticket to another project takes it out of its milestone.",
+        "Milestones are Tower-only during the Linear dual run: a milestone write is delivery tower_only, and a ticket's milestone change says Linear copy not_mirrored (milestone_not_mirrored). The same --request-id replays the first receipts.",
+        "Refusals keep Tower's label: milestone_not_found_or_unreadable, milestone_ref_ambiguous, milestone_name_required, milestone_name_taken, milestone_date_invalid, milestone_already_archived, milestone_not_archived, milestone_archived, milestone_project_mismatch, project_archived, project_not_found_or_unreadable, revision_conflict, request_id_reused, invalid_body.",
+        "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+    ],
+];

package/dist/commands/local-help-project.js

@@ -16,6 +16,7 @@ export const PROJECT_HELP = [
         "Every write returns a receipt with delivery tower_only: a project write never reaches Linear and never queues a Linear change. The same --request-id replays the first receipt; with another body it is request_id_reused.",
         "--expected-updated-at is the updated_at you last read (shown by show and --json); a stale one is revision_conflict with the current project and changes nothing.",
         "Refusals keep Tower's label: project_name_required, project_name_taken, project_owned_by_linear (a project imported from Linear is named there; archive and restore still work), project_already_archived, project_not_archived, project_not_found_or_unreadable, revision_conflict, request_id_reused, invalid_body.",
+        "BLI-22360 planning fields on create and update: --lead <email|me|none>, --member <email[,email]|none> (the whole set; repeatable), --add-member / --remove-member (update), --status backlog|planned|started|paused|completed|canceled|none, --priority none|urgent|high|medium|low (or 0-4), --start / --target <YYYY-MM-DD|none> with --start-resolution / --target-resolution month|quarter|halfYear|year|day (a date without one is an exact day), --content-file <path> or --content <text|none> (the long body; --description stays the short summary). People are matched by exact email, never by name. show prints them, the project's milestones and their progress (see `cockpit milestone`). Refusals: project_status_invalid, project_dates_invalid, project_person_not_found.",
         "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
     ],
 ];

package/dist/commands/local-help.js

@@ -79,6 +79,7 @@ export const rootCommandNames = new Set([
     "mail",
     "cal",
     "project",
+    "milestone",
     "search",
     "github",
     "release",
@@ -147,6 +148,7 @@ const COMMAND_SUMMARY_LINES = [
     "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|draft --account <id> --to <a> --subject <s> [--reply-to <message id>]|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--attach <path>]... [--dashboard-url <url>] [--json]",
     "  cockpit cal [event <id> [--occurrence-start <iso>]|export <id> [--occurrence-start <iso>]|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|view-settings|view-settings-change|people <label>|availability --with <label|email> --from <d> --to <d>|overlays [--pin <label|email>|--remove <email>]|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|duplicate <event id> [--keep-invitees]|batch|undo [<change id>]|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
     "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
+    "  cockpit milestone [list|show|create|update|archive|restore|add|remove] [--project <p>] [--json]",
     "  cockpit github <pr|merge|retitle|rerun> <owner/repo> <n> [--claim <state>] [--method squash|merge|rebase] [--title \"<text>\"] [--run <id>] [--confirm <code>] [--dashboard-url <url>] [--json]",
     `  cockpit search "<words>" [--kind <category,...>] [--limit <n>] [--dashboard-url <url>] [--json]`,
     "  cockpit search --categories [--dashboard-url <url>] [--json]",

package/dist/commands/local.js

@@ -47,6 +47,7 @@ import { runIssue } from "./issue.js";
 import { runCal } from "./cal.js";
 import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
+import { runMilestone } from "./milestone.js";
 import { runGithub } from "./github.js";
 import { runSearch } from "./search.js";
 import { runCareers } from "./careers.js";
@@ -203,6 +204,7 @@ async function runTowerCommand(command, io) {
         case "issue": return await runIssue(command, io);
         case "mail": return await runMail(command, io);
         case "project": return await runProject(command, io);
+        case "milestone": return await runMilestone(command, io);
         case "search": return await runSearch(command, io);
         case "github": return await runGithub(command, io);
         case "careers": return await runCareers(command, io);

package/dist/commands/milestone.js

@@ -0,0 +1,157 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { BODY_MAX_CHARS, READ_DEADLINE_MS, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+const TAG = "[milestone cli]";
+export const milestoneLine = (m) => `${m.id}  ${m.name}  target ${m.target_date ?? "none"}${m.archived_at ? "  [archived]" : ""}  ${m.progress?.summary ?? ""}`.trimEnd();
+function refuse(door, answer) {
+    const mutation = answer.body?.mutation;
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+function projectQuery(command) {
+    return command.project ? `?project=${encodeURIComponent(command.project)}` : "";
+}
+/** `--description -` reads the text from stdin; anything else is the text itself. */
+async function readDescription(value, io) {
+    if (value !== "-")
+        return { ok: true, text: value };
+    if (isInteractiveStdin(io))
+        return { ok: false, detail: "--description - reads the text from stdin, and nothing is piped in." };
+    try {
+        return { ok: true, text: await readPipedText(io.stdin, { maxChars: BODY_MAX_CHARS, overflowMessage: `A milestone description is limited to ${BODY_MAX_CHARS} characters.` }) };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function runMilestone(command, io) {
+    const door = await openAgentDoor("milestone", command, io);
+    const ref = command.ref ? encodeURIComponent(command.ref) : "";
+    const writeIds = command.requestId ? { request_id: command.requestId } : {};
+    switch (command.action) {
+        case "list": {
+            const query = new URLSearchParams();
+            if (command.project)
+                query.set("project", command.project);
+            if (command.includeArchived)
+                query.set("include_archived", "true");
+            const answer = await askAgentDoor(door, {
+                path: `/api/work/milestones${query.size > 0 ? `?${query}` : ""}`, method: "GET", label: "milestone list", timeoutMs: READ_DEADLINE_MS,
+            });
+            if (!answer.ok)
+                return refuse(door, answer);
+            const body = answer.body;
+            const rows = body.milestones ?? [];
+            console.error(`${TAG} list done`, JSON.stringify({ returned: rows.length, coverage: body.coverage ?? null }));
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body });
+            if (rows.length === 0)
+                writeLine(door.io.stdout, "No milestones here. Create one with `cockpit milestone create --project <p> --name <n>`.");
+            for (const row of rows)
+                writeLine(door.io.stdout, milestoneLine(row));
+            if (body.coverage === "capped")
+                writeLine(door.io.stdout, "\nOnly the first 500 milestones are listed.");
+            return 0;
+        }
+        case "show": {
+            const query = new URLSearchParams();
+            if (command.project)
+                query.set("project", command.project);
+            if (command.limit !== undefined)
+                query.set("limit", String(command.limit));
+            if (command.cursor)
+                query.set("cursor", command.cursor);
+            const answer = await askAgentDoor(door, {
+                path: `/api/work/milestones/${ref}${query.size > 0 ? `?${query}` : ""}`, method: "GET", label: "milestone show", timeoutMs: READ_DEADLINE_MS,
+            });
+            if (!answer.ok)
+                return refuse(door, answer);
+            const body = answer.body;
+            console.error(`${TAG} show done`, JSON.stringify({ milestone_id: body.milestone.id, members: body.issues?.length ?? 0, has_more: Boolean(body.has_more) }));
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body });
+            const out = door.io.stdout;
+            writeLine(out, milestoneLine(body.milestone));
+            writeLine(out, `project ${body.project?.name ?? body.milestone.project_id}  updated ${body.milestone.updated_at ?? ""}`);
+            if (body.milestone.description)
+                writeLine(out, `\n${body.milestone.description}`);
+            writeLine(out, `\nProgress: ${body.progress?.summary ?? "no progress summary"}`);
+            for (const issue of body.issues ?? [])
+                writeLine(out, `${(issue.identifier ?? "").padEnd(9)}  ${(issue.state ?? "").padEnd(11)}  ${issue.title ?? ""}`);
+            if (body.has_more && body.next_cursor)
+                writeLine(out, `More tickets: --cursor ${body.next_cursor}`);
+            return 0;
+        }
+        case "create":
+        case "update": {
+            const description = await readDescription(command.description, io);
+            if (!description.ok)
+                return failAgentDoor(door, TAG, "invalid_body", description.detail);
+            const payload = {
+                ...writeIds,
+                ...(command.action === "create" ? { project: command.project } : {}),
+                ...(command.action === "update" && command.expectedUpdatedAt ? { expected_updated_at: command.expectedUpdatedAt } : {}),
+                ...(command.name === undefined ? {} : { name: command.name }),
+                ...(description.text === undefined ? {} : { description: description.text }),
+                ...(command.targetDate === undefined ? {} : { target_date: command.targetDate }),
+            };
+            return await write(command, door, command.action === "create"
+                ? { path: "/api/work/milestones", method: "POST", body: payload }
+                : { path: `/api/work/milestones/${ref}${projectQuery(command)}`, method: "PATCH", body: payload });
+        }
+        case "archive":
+        case "restore":
+            return await write(command, door, {
+                path: `/api/work/milestones/${ref}${projectQuery(command)}`,
+                method: "PATCH",
+                body: { ...writeIds, ...(command.expectedUpdatedAt ? { expected_updated_at: command.expectedUpdatedAt } : {}), archived: command.action === "archive" },
+            });
+        case "add":
+        case "remove":
+            return await membership(command, door, ref, writeIds);
+    }
+}
+async function write(command, door, req) {
+    const answer = await askAgentDoor(door, { ...req, label: `milestone ${command.action}`, timeoutMs: WRITE_DEADLINE_MS });
+    if (!answer.ok)
+        return refuse(door, answer);
+    const body = answer.body;
+    console.error(`${TAG} ${command.action} committed`, JSON.stringify({ milestone_id: body.milestone.id, request_id: body.mutation?.request_id ?? null, delivery: body.mutation?.delivery?.status ?? null }));
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    const label = { create: "Created", update: "Updated", archive: "Archived", restore: "Restored" }[command.action] ?? "Saved";
+    writeLine(door.io.stdout, `${label}: ${milestoneLine(body.milestone)}`);
+    writeLine(door.io.stdout, `Request ID ${body.mutation?.request_id ?? "?"}, delivery ${body.mutation?.delivery?.status ?? "tower_only"} (milestones never reach Linear).`);
+    return 0;
+}
+async function membership(command, door, ref, writeIds) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/milestones/${ref}/issues${projectQuery(command)}`,
+        method: "POST",
+        label: `milestone ${command.action}`,
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { ...writeIds, [command.action]: command.tickets },
+    });
+    // 207 means some items were refused: still a readable answer with every receipt.
+    const body = (("body" in answer ? answer.body : undefined) ?? {});
+    if (!answer.ok && !Array.isArray(body.items))
+        return refuse(door, answer);
+    const items = body.items ?? [];
+    console.error(`${TAG} ${command.action} done`, JSON.stringify({
+        request_id: body.request_id ?? null, asked: items.length, committed: body.committed ?? 0, refused: body.refused ?? 0, skipped: body.skipped ?? 0, unknown: body.unknown ?? 0,
+    }));
+    const failed = (body.refused ?? 0) + (body.unknown ?? 0) > 0;
+    if (door.json) {
+        emitAgentDoor(door, { ok: !failed, ...body });
+        return failed ? 1 : 0;
+    }
+    for (const item of items) {
+        const linear = item.delivery?.status ? `  Linear copy: ${item.delivery.status}${item.delivery.reason ? ` (${item.delivery.reason})` : ""}` : "";
+        writeLine(door.io.stdout, `${(item.identifier ?? item.ref).padEnd(9)}  ${item.action} ${item.outcome}${item.reason ? ` ${item.reason}` : ""}${linear}`);
+        if (item.message && item.outcome !== "committed")
+            writeLine(door.io.stdout, `           ${item.message}`);
+    }
+    writeLine(door.io.stdout, `\n${body.committed ?? 0} committed, ${body.refused ?? 0} refused, ${body.skipped ?? 0} skipped, ${body.unknown ?? 0} unknown. Request ID ${body.request_id ?? "?"} (retry with it to replay).`);
+    if (body.progress?.summary)
+        writeLine(door.io.stdout, `Progress: ${body.progress.summary}`);
+    return failed ? 1 : 0;
+}