@gonovus-ai/spec-flow-cli 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,17 +1,26 @@
-import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { CommanderError, InvalidArgumentError } from "commander";
 import { randomUUID } from "node:crypto";
-import createClient from "openapi-fetch";
 import { z } from "zod";
 import { addAuthenticationCommandTopology } from "./authentication-command-topology.js";
+import { itemOutput, itemListOutput, relationListOutput, relationReceiptOutput } from "./commands/work-item-output.js";
+import { registerCustomFieldColorCommands, parseOptionColors } from "./custom-field-color-commands.js";
 import { registerGitHubAccountCommands } from "./github-account-commands.js";
-import { parseHttpOrigin, unresolvedSpecFlowApiOrigin, } from "./http-origin.js";
+import { readDescription, singleDescriptionSource } from "./input/text-source.js";
 import { registerProductMapCommands } from "./product-map-commands.js";
-import { specFlowCliUserAgent } from "./user-agent.js";
+import { createProgram } from "./program.js";
+import { registerProjectAdministrationCommands } from "./project-administration-commands.js";
+import { writeSkillError, skillErrorExitCode } from "./runtime/errors.js";
+import { execute } from "./runtime/execute.js";
+import { readIdentity } from "./runtime/identity.js";
+import { writeResult } from "./runtime/output.js";
+import { selectSession, hasWorkspaceReadToken, rejectWorkspaceReadTokenOperation } from "./runtime/session.js";
+import { registerSpecDiscussionCommands } from "./spec-discussion-commands.js";
+import { registerSpecOwnerCommands } from "./spec-owner-commands.js";
 import { registerUserApiKeyCommands } from "./user-api-key-commands.js";
 import { registerWorkItemAssetCommands } from "./work-item-asset-commands.js";
 import { readWorkItemImportFile } from "./work-item-exchange-file.js";
+import { registerWorkItemQueryCommands } from "./work-item-query-commands.js";
 import { registerWorkItemResourceLinkCommands } from "./work-item-resource-link-commands.js";
-import { parseTimeEntryTimestamp, parseTimeEntryUuid, parseTimeEntryDescription } from "./work-item-time-entry-input.js";
 export function formatResourceDiagnostic(message) {
     return `${JSON.stringify({ diagnostic: { level: "warning", message } })}\n`;
 }
@@ -130,22 +139,47 @@ const findingCreateInputSchema = z
     .strict();
 export async function runCli(arguments_, dependencies) {
     let exitCode = 0;
-    const program = new Command()
-        .name("specflow")
-        .description("Read and govern SpecFlow through supported commands")
-        .option("--allow-file-fallback", "use a warned owner-only local credential file if the system store is unavailable")
-        .option("--server <url>", "SpecFlow server origin")
-        .option("--api-key-id <id>", "Use an origin-scoped User API Key from the credential store")
-        .exitOverride()
-        .configureOutput({
-        writeErr: () => undefined,
-        writeOut: dependencies.stdout,
-    });
-    const run = (request, options = {}) => executeRequest(dependencies, request, options, program.getOptionValue("server"), program.getOptionValue("apiKeyId"));
+    let outputMode = "full";
+    const warnMissingUrl = () => { dependencies.stderr(formatResourceDiagnostic("This server version does not support Work Item URLs; upgrade the server. The business operation succeeded.")); };
+    const program = createProgram(dependencies);
+    const run = async (request, options = {}) => {
+        const selected = await selectSession(dependencies, options, program.getOptionValue("server"), program.getOptionValue("apiKeyId"));
+        if ("exitCode" in selected)
+            return selected.exitCode;
+        let me;
+        if (options.resolveMe === true) {
+            if (selected.credentialKind === "workspace-read-token")
+                return rejectWorkspaceReadTokenOperation(dependencies);
+            const identity = await execute(readIdentity, selected.identityClient);
+            if (!identity.ok) {
+                writeSkillError(dependencies, identity.error);
+                return skillErrorExitCode(identity.error);
+            }
+            me = identity.data.user.id;
+        }
+        const result = await execute(client => request(client, me, selected.credentialKind), selected.client, options);
+        if (!result.ok) {
+            writeSkillError(dependencies, result.error);
+            return skillErrorExitCode(result.error);
+        }
+        return writeResult(dependencies, () => options.project === undefined ? result.data : options.project(result.data));
+    };
     registerUserApiKeyCommands(program, { dependencies, run, setExitCode: (value) => { exitCode = value; }, parseScopes: parseRoleStatements, parseLimit: parseSearchLimit });
     registerGitHubAccountCommands(program, { dependencies, run, setExitCode: (value) => { exitCode = value; } });
     const authentication = addAuthenticationCommandTopology(program);
     program.hook("preAction", (_command, actionCommand) => {
+        const names = [];
+        for (let command = actionCommand; command.parent !== null; command = command.parent)
+            names.unshift(command.name());
+        const path = names.join(" ");
+        outputMode = program.opts().output ?? (path === "work-item subtask link" ? "summary" : "full");
+        if (outputMode === "summary" && !["work-item create", "work-item read", "work-item update", "work-item assign", "work-item list", "work-item relation create", "work-item relation list", "work-item subtask link"].includes(path))
+            throw invalidArgument("Summary output is not supported for this command");
+        if (!["work-item create", "work-item assign"].includes(path)) {
+            const assignee = actionCommand.getOptionValue("assignee");
+            if (assignee === "me" || (Array.isArray(assignee) && assignee.some(value => typeof value === "string" && value.split(",").includes("me"))))
+                throw invalidArgument("This command accepts User IDs only; me is supported by work-item create and assign");
+        }
         const options = actionCommand.opts();
         if (typeof options.projectId === "string") {
             actionCommand.setOptionValue("projectId", parseProjectId(options.projectId));
@@ -166,6 +200,13 @@ export async function runCli(arguments_, dependencies) {
             throw new CommanderError(2, "specflow.authenticationCommand", "Authentication commands use the human-facing CLI boundary");
         });
     }
+    dependencies.registerAuthentication?.(program, authentication);
+    authentication.status.parent?.command("whoami").description("Read the current User ID and selected credential kind").action(async () => {
+        exitCode = await run(async (client, _me, credentialKind) => {
+            const result = await readIdentity(client);
+            return { ...result, ...(result.data === undefined ? {} : { data: { user: { id: result.data.user.id }, credentialKind } }) };
+        }, { rejectWorkspaceReadToken: true });
+    });
     const workspace = program.command("workspace");
     workspace
         .command("list")
@@ -1267,83 +1308,23 @@ export async function runCli(arguments_, dependencies) {
     });
     const workItem = program.command("work-item");
     registerWorkItemAssetCommands(workItem, { dependencies, run, setExitCode: (value) => { exitCode = value; }, rejectWrite: () => rejectTokenWrite(dependencies) });
-    registerProductMapCommands(program, { run, setExitCode: value => { exitCode = value; }, canWrite: () => !hasWorkspaceReadToken(dependencies.environment), rejectWrite: () => rejectTokenWrite(dependencies), parseOpaqueVersion });
-    registerWorkItemResourceLinkCommands(workItem, spec, { run, setExitCode: (value) => { exitCode = value; }, canWrite: () => !hasWorkspaceReadToken(dependencies.environment), rejectWrite: () => rejectTokenWrite(dependencies), parseOpaqueVersion, parseLimit: parseSearchLimit });
-    const timeEntry = workItem.command("time-entry").description("Record and read task time entries");
-    timeEntry.command("list")
-        .requiredOption("--project-id <projectId>")
-        .requiredOption("--work-item-id <workItemId>")
-        .option("--limit <limit>", "Maximum results, 1 through 100", parseSearchLimit, 50)
-        .option("--cursor <cursor>", "Opaque cursor returned by the previous page")
-        .action(async (options) => {
-        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/time-entries", { params: { path: { projectId: options.projectId, workItemId: options.workItemId }, query: { limit: options.limit, ...(options.cursor === undefined ? {} : { cursor: options.cursor }) } } }));
-    });
-    timeEntry.command("get")
-        .requiredOption("--project-id <projectId>")
-        .requiredOption("--work-item-id <workItemId>")
-        .requiredOption("--entry-id <entryId>", "Time Entry UUID", (value) => { try {
-        return parseTimeEntryUuid(value);
-    }
-    catch {
-        throw invalidArgument("Time Entry ID must be a UUID");
-    } })
+    const resourceRuntime = { run, setExitCode: (value) => { exitCode = value; }, parseOpaqueVersion, parseLimit: parseSearchLimit };
+    registerSpecOwnerCommands(spec, resourceRuntime);
+    registerSpecDiscussionCommands(spec, resourceRuntime);
+    registerProjectAdministrationCommands(project, workspace, resourceRuntime);
+    program.command("search-global").description("Search all currently accessible objects; preserves server totals and cursor")
+        .requiredOption("--query <query>")
+        .option("--types <types>", "Comma-separated kinds: project,work-item,capability,spec,glossary,screen,journey,user")
+        .option("--limit <limit>", "Server page size (1–100)", resourceRuntime.parseLimit, 20)
+        .option("--cursor <cursor>")
         .action(async (options) => {
-        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/time-entries/{entryId}", { params: { path: options } }));
+        resourceRuntime.setExitCode(await resourceRuntime.run(client => client.GET("/v1/search", {
+            params: { query: { query: options.query, limit: options.limit, ...(options.cursor === undefined ? {} : { cursor: options.cursor }), ...(options.types === undefined ? {} : { types: options.types }) } },
+        }), { rejectWorkspaceReadToken: true }));
     });
-    for (const action of ["create", "update"]) {
-        const command = timeEntry.command(action)
-            .requiredOption("--project-id <projectId>")
-            .requiredOption("--work-item-id <workItemId>")
-            .requiredOption("--start-time <timestamp>", "ISO date-time with an offset", (value) => { try {
-            return parseTimeEntryTimestamp(value);
-        }
-        catch {
-            throw invalidArgument("Start time must be a valid ISO 8601 timestamp with an offset");
-        } })
-            .option("--end-time <timestamp>", "Omit to start running, or preserve the stored end on update", (value) => { try {
-            return parseTimeEntryTimestamp(value);
-        }
-        catch {
-            throw invalidArgument("End time must be a valid ISO 8601 timestamp with an offset");
-        } })
-            .option("--description <description>", "Optional recorded work description", (value) => { try {
-            return parseTimeEntryDescription(value);
-        }
-        catch {
-            throw invalidArgument("Time Entry description exceeds the allowed limit");
-        } })
-            .requiredOption("--idempotency-key <key>", "Reuse this key and inputs for the same action", (value) => { try {
-            return parseTimeEntryUuid(value);
-        }
-        catch {
-            throw invalidArgument("Command key must be a UUID");
-        } });
-        if (action === "update")
-            command.requiredOption("--entry-id <entryId>", "Time Entry UUID", (value) => { try {
-                return parseTimeEntryUuid(value);
-            }
-            catch {
-                throw invalidArgument("Time Entry ID must be a UUID");
-            } }).requiredOption("--expected-version <version>", "Opaque version returned by SpecFlow", parseOpaqueVersion);
-        command.action(async (options) => {
-            if (hasWorkspaceReadToken(dependencies.environment)) {
-                exitCode = rejectTokenWrite(dependencies);
-                return;
-            }
-            const input = { startTime: options.startTime, ...(options.endTime === undefined ? {} : { endTime: options.endTime }), ...(options.description === undefined ? {} : { description: options.description }) };
-            if (options.endTime !== undefined && Date.parse(options.startTime) > Date.parse(options.endTime))
-                throw invalidArgument("Start time cannot follow end time");
-            const path = { projectId: options.projectId, workItemId: options.workItemId };
-            const header = { "idempotency-key": options.idempotencyKey };
-            exitCode = await run((client) => {
-                if (action === "create")
-                    return client.POST("/v1/projects/{projectId}/work-items/{workItemId}/time-entries", { body: input, params: { path, header } });
-                if (options.entryId === undefined || options.expectedVersion === undefined)
-                    throw new Error("Time Entry update requires its identity and observed version");
-                return client.PATCH("/v1/projects/{projectId}/work-items/{workItemId}/time-entries/{entryId}", { body: input, params: { path: { ...path, entryId: options.entryId }, header: { ...header, "if-match": options.expectedVersion } } });
-            }, { retryTransportOnce: true, ambiguousOutcomeMessage: "Time Entry outcome is unknown; retry the same inputs and command key" });
-        });
-    }
+    registerWorkItemQueryCommands(workItem, workspace, resourceRuntime);
+    registerProductMapCommands(program, { dependencies, run, setExitCode: value => { exitCode = value; }, canWrite: () => !hasWorkspaceReadToken(dependencies.environment), rejectWrite: () => rejectTokenWrite(dependencies), parseOpaqueVersion });
+    registerWorkItemResourceLinkCommands(workItem, spec, { run, setExitCode: (value) => { exitCode = value; }, canWrite: () => !hasWorkspaceReadToken(dependencies.environment), rejectWrite: () => rejectTokenWrite(dependencies), parseOpaqueVersion, parseLimit: parseSearchLimit });
     const workItemComment = workItem.command("comment").description("Read and manage authored task comments");
     workItemComment.command("list")
         .requiredOption("--project-id <projectId>")
@@ -1419,14 +1400,15 @@ export async function runCli(arguments_, dependencies) {
         .requiredOption("--project-id <projectId>")
         .requiredOption("--work-item-id <workItemId>")
         .action(async (options) => {
-        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/relations", { params: { path: options } }));
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/relations", { params: { path: options } }), { project: data => relationListOutput(data, outputMode, warnMissingUrl) });
     });
     workItemRelation.command("create")
+        .addHelpText("after", "\nExample: specflow work-item relation create --project-id PROJECT --work-item-id GON-78 --target-project-id PROJECT --target-work-item-id GON-79 --type subtask --idempotency-key KEY\n")
         .requiredOption("--project-id <projectId>")
         .requiredOption("--work-item-id <workItemId>")
         .requiredOption("--target-project-id <projectId>", "Target task's current Project", parseProjectId)
         .requiredOption("--target-work-item-id <workItemId>", "Target task's public identity", parseWorkItemId)
-        .requiredOption("--type <type>", "subtask, blocks or related", (value) => {
+        .requiredOption("--type <type>", "subtask (source=parent, target=child), blocks or related", (value) => {
         const result = z.enum(["subtask", "blocks", "related"]).safeParse(value);
         if (!result.success)
             throw invalidArgument("Relation type must be subtask, blocks or related");
@@ -1441,7 +1423,24 @@ export async function runCli(arguments_, dependencies) {
         exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items/{workItemId}/relations", {
             body: { targetProjectId: options.targetProjectId, targetWorkItemId: options.targetWorkItemId, relationType: options.type },
             params: { path: { projectId: options.projectId, workItemId: options.workItemId }, header: { "idempotency-key": options.idempotencyKey } },
-        }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Relation creation outcome is unknown; retry with the same inputs and command key" });
+        }), { project: data => relationReceiptOutput(data, outputMode, warnMissingUrl), retryTransportOnce: true, ambiguousOutcomeMessage: "Relation creation outcome is unknown; retry with the same inputs and command key" });
+    });
+    workItem.command("subtask").command("link")
+        .description("Link parent (source) to child (target), including across Projects")
+        .requiredOption("--project-id <projectId>", "Parent Project")
+        .requiredOption("--parent <workItemId>", "Parent public Work Item ID", parseWorkItemId)
+        .requiredOption("--child <workItemId>", "Child public Work Item ID", parseWorkItemId)
+        .option("--child-project-id <projectId>", "Child Project, defaults to parent Project", parseProjectId)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and inputs when retrying", parseRelationCommandKey)
+        .action(async (options) => {
+        if (hasWorkspaceReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run(client => client.POST("/v1/projects/{projectId}/work-items/{workItemId}/relations", {
+            body: { relationType: "subtask", targetProjectId: options.childProjectId ?? options.projectId, targetWorkItemId: options.child },
+            params: { path: { projectId: options.projectId, workItemId: options.parent }, header: { "idempotency-key": options.idempotencyKey } },
+        }), { retryTransportOnce: true, project: data => relationReceiptOutput(data, outputMode, warnMissingUrl), ambiguousOutcomeMessage: "Relation creation outcome is unknown; retry with the same inputs and command key" });
     });
     workItemRelation.command("delete")
         .requiredOption("--project-id <projectId>")
@@ -1489,7 +1488,7 @@ export async function runCli(arguments_, dependencies) {
                     limit: options.limit,
                 },
             },
-        }));
+        }), { project: data => itemListOutput(data, outputMode, warnMissingUrl) });
     });
     workItem
         .command("read")
@@ -1498,7 +1497,7 @@ export async function runCli(arguments_, dependencies) {
         .action(async (options) => {
         exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}", {
             params: { path: options },
-        }));
+        }), { project: data => itemOutput(data, outputMode, warnMissingUrl) });
     });
     workItem
         .command("assignees")
@@ -1512,33 +1511,36 @@ export async function runCli(arguments_, dependencies) {
         .command("create")
         .requiredOption("--project-id <projectId>")
         .requiredOption("--title <title>")
-        .option("--description <description>")
+        .option("--description <description>", "Inline description text", singleDescriptionSource)
+        .option("--description-file <path>", "Read description from a UTF-8 regular file, or - for piped stdin", singleDescriptionSource)
         .option("--label <labelId>", "Workspace label definition ID; repeat for several labels", collectOption, [])
-        .option("--assignee <assignee>", "Workspace member User ID")
+        .option("--assignee <assignee>", "Workspace member User ID, or me for the selected credential")
         .option("--custom-field <fieldId=value>", "Custom Field value as fieldId=value; repeat for several fields", collectOption, [])
         .option("--priority <priority>", "Work Item priority", parseWorkItemPriority)
         .option("--start-date <startDate>", "ISO 8601 date", parseWorkItemDate)
         .option("--due-date <dueDate>", "ISO 8601 date", parseWorkItemDate)
         .option("--status <status>", "Workflow Column slug or virtual status to create the Work Item in")
         .action(async (options) => {
+        const description = (await readDescription(options)) ?? undefined;
         if (hasWorkspaceReadToken(dependencies.environment)) {
             exitCode = rejectTokenWrite(dependencies);
             return;
         }
+        const customFields = options.customField.map(parseCustomFieldAssignment);
         const idempotencyKey = randomUUID();
-        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items", {
+        exitCode = await run((client, me) => client.POST("/v1/projects/{projectId}/work-items", {
             body: {
                 ...(options.assignee === undefined
                     ? {}
-                    : { assigneeId: options.assignee }),
+                    : { assigneeId: me ?? options.assignee }),
                 ...(options.customField.length === 0
                     ? {}
                     : {
-                        customFields: options.customField.map(parseCustomFieldAssignment),
+                        customFields,
                     }),
-                ...(options.description === undefined
+                ...(description === undefined
                     ? {}
-                    : { description: options.description }),
+                    : { description }),
                 ...(options.label.length === 0 ? {} : { labelIds: [...new Set(options.label)] }),
                 ...(options.dueDate === undefined
                     ? {}
@@ -1559,6 +1561,8 @@ export async function runCli(arguments_, dependencies) {
                 path: { projectId: options.projectId },
             },
         }), {
+            resolveMe: options.assignee === "me",
+            project: data => itemOutput(data, outputMode, warnMissingUrl),
             ambiguousOutcomeMessage: "Work Item creation outcome is unknown; list Work Items before retrying",
             retryTransportOnce: true,
         });
@@ -1569,7 +1573,8 @@ export async function runCli(arguments_, dependencies) {
         .requiredOption("--work-item-id <workItemId>")
         .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
         .option("--title <title>")
-        .option("--description <description>")
+        .option("--description <description>", "Inline description text", singleDescriptionSource)
+        .option("--description-file <path>", "Read description from a UTF-8 regular file, or - for piped stdin", singleDescriptionSource)
         .option("--clear-description", "Remove the Work Item description")
         .option("--priority <priority>", "Work Item priority", parseWorkItemPriority)
         .option("--start-date <startDate>", "ISO 8601 date", parseWorkItemDate)
@@ -1577,12 +1582,13 @@ export async function runCli(arguments_, dependencies) {
         .option("--clear-start-date", "Remove the Work Item start date")
         .option("--clear-due-date", "Remove the Work Item due date")
         .action(async (options) => {
+        const description = (await readDescription(options)) ?? undefined;
         if (hasWorkspaceReadToken(dependencies.environment)) {
             exitCode = rejectTokenWrite(dependencies);
             return;
         }
         if (options.title === undefined &&
-            options.description === undefined &&
+            description === undefined &&
             options.clearDescription !== true &&
             options.priority === undefined &&
             options.startDate === undefined &&
@@ -1591,10 +1597,6 @@ export async function runCli(arguments_, dependencies) {
             options.clearDueDate !== true) {
             throw invalidArgument("Work Item update requires a field change");
         }
-        if (options.clearDescription === true &&
-            options.description !== undefined) {
-            throw invalidArgument("Work Item update cannot set and clear the description together");
-        }
         if (options.clearStartDate === true && options.startDate !== undefined) {
             throw invalidArgument("Work Item update cannot set and clear the start date together");
         }
@@ -1606,9 +1608,9 @@ export async function runCli(arguments_, dependencies) {
             body: {
                 ...(options.clearDescription === true
                     ? { description: null }
-                    : options.description === undefined
+                    : description === undefined
                         ? {}
-                        : { description: options.description }),
+                        : { description }),
                 ...(options.clearDueDate === true
                     ? { dueDate: null }
                     : options.dueDate === undefined
@@ -1637,6 +1639,7 @@ export async function runCli(arguments_, dependencies) {
                 },
             },
         }), {
+            project: data => itemOutput(data, outputMode, warnMissingUrl),
             ambiguousOutcomeMessage: "Work Item update outcome is unknown; read the Work Item before retrying",
             retryTransportOnce: true,
         });
@@ -1646,7 +1649,7 @@ export async function runCli(arguments_, dependencies) {
         .requiredOption("--project-id <projectId>")
         .requiredOption("--work-item-id <workItemId>")
         .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
-        .option("--assignee <assignee>", "Workspace member User ID")
+        .option("--assignee <assignee>", "Workspace member User ID, or me for the selected credential")
         .option("--unassign", "Remove the Work Item assignee")
         .action(async (options) => {
         if (hasWorkspaceReadToken(dependencies.environment)) {
@@ -1660,9 +1663,9 @@ export async function runCli(arguments_, dependencies) {
             throw invalidArgument("Work Item assign cannot set and clear the assignee together");
         }
         const idempotencyKey = randomUUID();
-        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/work-items/{workItemId}/assignee", {
+        exitCode = await run((client, me) => client.PUT("/v1/projects/{projectId}/work-items/{workItemId}/assignee", {
             body: {
-                assigneeId: options.unassign === true ? null : (options.assignee ?? null),
+                assigneeId: options.unassign === true ? null : (me ?? options.assignee ?? null),
             },
             params: {
                 header: {
@@ -1675,6 +1678,8 @@ export async function runCli(arguments_, dependencies) {
                 },
             },
         }), {
+            resolveMe: options.assignee === "me",
+            project: data => itemOutput(data, outputMode, warnMissingUrl),
             ambiguousOutcomeMessage: "Work Item assignment outcome is unknown; read the Work Item before retrying",
             retryTransportOnce: true,
         });
@@ -1723,7 +1728,7 @@ export async function runCli(arguments_, dependencies) {
         .requiredOption("--target <[projectId/]id@version>", "Target with its observed version, e.g. PAY-1@3 or project-id/PAY-2@4; repeat within the same Workspace", parseWorkItemBulkTarget, [])
         .option("--status <status>", "Destination Workflow Column slug or virtual status (updateStatus)")
         .option("--priority <priority>", "Priority (updatePriority)", parseWorkItemPriority)
-        .option("--assignee <assignee>", "Assignee User ID (updateAssignee)")
+        .option("--assignee <assignee>", "Assignee User ID only (updateAssignee); me is not supported")
         .option("--unassign", "Clear the assignee (updateAssignee)")
         .option("--label-id <labelId>", "Work Item Label ID (addLabel/removeLabel)")
         .option("--due-date <dueDate>", "Due date (updateDueDate)", parseWorkItemDate)
@@ -2164,6 +2169,7 @@ export async function runCli(arguments_, dependencies) {
         });
     });
     const workItemCustomField = program.command("work-item-custom-field");
+    registerCustomFieldColorCommands(workItemCustomField, resourceRuntime);
     workItemCustomField
         .command("list")
         .requiredOption("--project-id <projectId>")
@@ -2180,6 +2186,7 @@ export async function runCli(arguments_, dependencies) {
         .option("--option <option>", "Dropdown option; repeat for every choice", collectOption, [])
         .option("--default-value <defaultValue>")
         .option("--required", "Reject Work Items that leave the field blank")
+        .option("--option-colors <json>", "One color or null per dropdown option", parseOptionColors)
         .action(async (options) => {
         if (hasWorkspaceReadToken(dependencies.environment)) {
             exitCode = rejectTokenWrite(dependencies);
@@ -2192,6 +2199,7 @@ export async function runCli(arguments_, dependencies) {
                     ? {}
                     : { defaultValue: options.defaultValue }),
                 name: options.name,
+                ...(options.optionColors === undefined ? {} : { optionColors: options.optionColors }),
                 ...(options.option.length === 0
                     ? {}
                     : { options: options.option }),
@@ -2533,7 +2541,7 @@ export async function runCli(arguments_, dependencies) {
     }
     catch (cause) {
         if (cause instanceof CommanderError) {
-            if (cause.code === "commander.helpDisplayed") {
+            if (cause.exitCode === 0) {
                 return cause.exitCode;
             }
             writeSkillError(dependencies, {
@@ -2547,130 +2555,6 @@ export async function runCli(arguments_, dependencies) {
         throw cause;
     }
 }
-async function executeRequest(dependencies, request, options = {}, serverFlag, apiKeyIdFlag) {
-    if (dependencies.environment.SPEC_FLOW_PROJECT_READ_TOKEN !== undefined) {
-        writeSkillError(dependencies, { message: "Project Read Tokens are retired; use a Workspace read-only Token", reason: "Authentication Failed", retryable: false });
-        return 2;
-    }
-    const environmentCredential = dependencies.environment.SPEC_FLOW_WORKSPACE_READ_TOKEN;
-    const apiKeyEnvironment = dependencies.environment.SPEC_FLOW_API_KEY;
-    const usesApiKey = apiKeyEnvironment !== undefined || apiKeyIdFlag !== undefined;
-    if (options.requireUserSession === true && (usesApiKey || hasWorkspaceReadToken(dependencies.environment))) {
-        writeSkillError(dependencies, { message: "A User Session is required for account management", reason: "Permission Denied", retryable: false });
-        return 3;
-    }
-    if ((apiKeyEnvironment !== undefined && apiKeyIdFlag !== undefined) || (usesApiKey && hasWorkspaceReadToken(dependencies.environment))) {
-        writeSkillError(dependencies, { message: "Select exactly one API Key or Workspace read-only Token credential", reason: "Invalid Operation", retryable: false });
-        return 2;
-    }
-    if (apiKeyIdFlag !== undefined && !z.uuid().safeParse(apiKeyIdFlag).success) {
-        writeSkillError(dependencies, { message: "API Key ID must be a UUID", reason: "Invalid Operation", retryable: false });
-        return 2;
-    }
-    if (apiKeyEnvironment !== undefined && !/^sfk_[A-Za-z0-9_-]{43}$/u.test(apiKeyEnvironment)) {
-        writeSkillError(dependencies, { message: "SPEC_FLOW_API_KEY does not contain a User API Key", reason: "Authentication Failed", retryable: false });
-        return 2;
-    }
-    if (options.rejectWorkspaceReadToken === true &&
-        hasWorkspaceReadToken(dependencies.environment)) {
-        return rejectWorkspaceReadTokenOperation(dependencies);
-    }
-    const baseUrl = resolveApiOrigin(dependencies, serverFlag);
-    if (baseUrl === null) {
-        return 2;
-    }
-    let credential;
-    try {
-        if (apiKeyEnvironment !== undefined)
-            credential = apiKeyEnvironment;
-        else if (typeof apiKeyIdFlag === "string") {
-            if (dependencies.credentialStore.readApiKey === undefined)
-                throw new Error("API Key storage is unavailable");
-            credential = await dependencies.credentialStore.readApiKey(apiKeyIdFlag.toLowerCase());
-        }
-        else {
-            credential = environmentCredential ?? await dependencies.credentialStore.read();
-        }
-    }
-    catch {
-        writeSkillError(dependencies, {
-            message: "The CLI credential store is temporarily unavailable",
-            reason: "Temporary Failure",
-            retryable: true,
-        });
-        return 4;
-    }
-    if (credential === null || credential.trim().length === 0) {
-        writeSkillError(dependencies, {
-            message: "An authenticated CLI Session, User API Key or Workspace read-only Token is required",
-            reason: "Authentication Failed",
-            retryable: false,
-        });
-        return 2;
-    }
-    const client = createClient({
-        baseUrl,
-        ...(usesApiKey || options.requireUserSession === true ? { redirect: "error" } : {}),
-        fetch: options.retryTransportOnce === true
-            ? retryTransportOnce(dependencies.fetch)
-            : dependencies.fetch,
-        headers: {
-            ...(usesApiKey ? { "x-api-key": credential } : { authorization: `Bearer ${credential}` }),
-            "user-agent": specFlowCliUserAgent,
-        },
-    });
-    try {
-        const result = await request(client);
-        if (result.response.ok && result.data !== undefined) {
-            const validationError = options.validateSuccess?.(result.data) ?? null;
-            if (validationError !== null) {
-                writeSkillError(dependencies, validationError);
-                return skillErrorExitCode(validationError);
-            }
-            dependencies.stdout(`${JSON.stringify(result.data)}\n`);
-            return 0;
-        }
-        if (result.response.ok && options.retryTransportOnce === true) {
-            const error = ambiguousMutationError(options.ambiguousOutcomeMessage);
-            writeSkillError(dependencies, error);
-            return skillErrorExitCode(error);
-        }
-        const error = mapHttpFailure(result.response, result.error);
-        writeSkillError(dependencies, error);
-        return skillErrorExitCode(error);
-    }
-    catch {
-        const error = options.retryTransportOnce === true
-            ? ambiguousMutationError(options.ambiguousOutcomeMessage)
-            : {
-                message: "SpecFlow is temporarily unavailable",
-                reason: "Temporary Failure",
-                retryable: true,
-            };
-        writeSkillError(dependencies, error);
-        return skillErrorExitCode(error);
-    }
-}
-function retryTransportOnce(fetch) {
-    return async (request) => {
-        const retryRequest = request.clone();
-        try {
-            return await fetch(request);
-        }
-        catch {
-            return fetch(retryRequest);
-        }
-    };
-}
-function ambiguousMutationError(message) {
-    return {
-        message: message ??
-            "Write outcome is unknown; read the target resource before trying a new command identity",
-        code: "EXECUTION_OUTCOME_UNKNOWN",
-        reason: "Temporary Failure",
-        retryable: false,
-    };
-}
 function validateIssuedWorkspaceReadToken(data) {
     if (typeof data === "object" &&
         data !== null &&
@@ -2684,21 +2568,6 @@ function validateIssuedWorkspaceReadToken(data) {
     }
     return null;
 }
-function resolveApiOrigin(dependencies, serverFlag) {
-    const flag = typeof serverFlag === "string" ? serverFlag : undefined;
-    const result = parseHttpOrigin(unresolvedSpecFlowApiOrigin(flag, dependencies.environment.SPEC_FLOW_API_URL));
-    if (result.valid) {
-        return result.origin;
-    }
-    writeSkillError(dependencies, {
-        message: flag === undefined
-            ? "SPEC_FLOW_API_URL must be an HTTP(S) origin without a path"
-            : "--server must be an HTTP(S) origin without a path",
-        reason: "Invalid Operation",
-        retryable: false,
-    });
-    return null;
-}
 function parseRelationCommandKey(value) {
     const key = value.trim();
     if (key.length === 0 || key.length > 200)
@@ -2849,7 +2718,7 @@ function workItemSelectionQuery(options) {
  */
 function workItemSelectionFlags(command) {
     return command
-        .option("--assignee <assignee>", "Filter by assignee User ID, or unassigned for items with none; repeat for several", collectOption, [])
+        .option("--assignee <assignee>", "Filter by assignee User ID only (me is not supported), or unassigned for items with none; repeat for several", collectOption, [])
         .option("--custom-field <fieldId=value>", "Filter by Custom Field value; repeat to OR values or combine fields", collectOption, [])
         .option("--due <filter>", "Filter by due bucket: dueThisWeek, dueNextWeek, or noDueDate; repeat for several", (value, previous) => [
         ...previous,
@@ -3163,146 +3032,6 @@ function rejectTokenWrite(dependencies) {
     });
     return 2;
 }
-function rejectWorkspaceReadTokenOperation(dependencies) {
-    writeSkillError(dependencies, {
-        message: "Workspace read-only Token does not permit this operation",
-        reason: "Permission Denied",
-        retryable: false,
-    });
-    return 3;
-}
-function hasWorkspaceReadToken(environment) {
-    const credential = environment.SPEC_FLOW_WORKSPACE_READ_TOKEN;
-    return credential !== undefined && credential.trim().length > 0;
-}
-function mapHttpFailure(response, payload) {
-    const failure = classifyHttpFailure(response, payload);
-    const issues = z.array(z.object({ location: z.enum(["body", "query", "path", "headers", "tool"]), path: z.array(z.union([z.string().max(100), z.number()])), rule: z.string().max(100), message: z.string().max(500) })).max(20).safeParse(z.object({ issues: z.unknown() }).safeParse(payload).data?.issues);
-    const code = readServerCode(payload);
-    const requestId = response.headers.get("x-request-id");
-    return { ...failure, ...(requestId !== null && /^[A-Za-z0-9._:-]{1,100}$/u.test(requestId) ? { requestId } : {}), status: response.status, ...(code !== null && /^[A-Z][A-Z0-9_]{0,79}$/u.test(code) ? { code } : {}), ...(issues.success ? { issues: issues.data } : {}) };
-}
-function classifyHttpFailure(response, payload) {
-    const { status } = response;
-    const serverMessage = readServerMessage(payload);
-    const serverCode = readServerCode(payload);
-    if (status === 401) {
-        return {
-            message: serverMessage ?? "Workspace read-only Token is invalid, expired, or revoked",
-            reason: "Authentication Failed",
-            retryable: false,
-        };
-    }
-    if (status === 403) {
-        return {
-            message: serverMessage ?? "Workspace read-only Token does not permit this operation",
-            reason: "Permission Denied",
-            retryable: false,
-        };
-    }
-    if (status === 404) {
-        if (serverCode === "PROJECT_NOT_ACCESSIBLE") {
-            return {
-                message: serverMessage ?? "The Project is not accessible",
-                reason: "Project Not Accessible",
-                retryable: false,
-            };
-        }
-        return {
-            message: serverMessage ?? "The requested Project resource was not found",
-            reason: "Resource Not Found",
-            retryable: false,
-        };
-    }
-    if (status === 409 && serverCode === "RESOURCE_CHANGED") {
-        return {
-            message: serverMessage ?? "The Working Draft changed after the Proposal baseline",
-            reason: "Resource Changed",
-            retryable: false,
-        };
-    }
-    if (status === 400 || status === 409 || status === 413 || status === 422 || status === 428) {
-        const diagnostics = readServerDiagnostics(payload);
-        return {
-            ...(diagnostics === undefined ? {} : { diagnostics }),
-            message: serverMessage ?? "The requested operation is invalid",
-            reason: "Invalid Operation",
-            retryable: false,
-        };
-    }
-    if (status === 412) {
-        return {
-            message: serverMessage ?? "The resource changed after it was read",
-            reason: "Resource Changed",
-            retryable: false,
-        };
-    }
-    if (status === 429) {
-        const retryAfter = response.headers.get("retry-after");
-        return {
-            message: serverMessage ?? "SpecFlow is temporarily throttling this client",
-            reason: "Temporary Failure",
-            ...(retryAfter === null ? {} : { retryAfter }),
-            retryable: true,
-        };
-    }
-    return {
-        message: serverMessage ?? "SpecFlow is temporarily unavailable",
-        reason: "Temporary Failure",
-        retryable: status >= 500,
-    };
-}
-function readServerMessage(payload) {
-    return typeof payload === "object" &&
-        payload !== null &&
-        "message" in payload &&
-        typeof payload.message === "string"
-        ? payload.message
-        : null;
-}
-function readServerCode(payload) {
-    return typeof payload === "object" &&
-        payload !== null &&
-        "code" in payload &&
-        typeof payload.code === "string"
-        ? payload.code
-        : null;
-}
-function readServerDiagnostics(payload) {
-    if (typeof payload !== "object" ||
-        payload === null ||
-        !("diagnostics" in payload) ||
-        !Array.isArray(payload.diagnostics)) {
-        return undefined;
-    }
-    const diagnostics = payload.diagnostics.flatMap((entry) => {
-        if (typeof entry !== "object" || entry === null) {
-            return [];
-        }
-        const { column, line, message, reason } = entry;
-        if (typeof reason !== "string" || typeof message !== "string") {
-            return [];
-        }
-        return [
-            {
-                ...(typeof column === "number" ? { column } : {}),
-                ...(typeof line === "number" ? { line } : {}),
-                message,
-                reason,
-            },
-        ];
-    });
-    return diagnostics.length === 0 ? undefined : diagnostics;
-}
-function skillErrorExitCode(error) {
-    if (error.reason === "Permission Denied") {
-        return 3;
-    }
-    return error.reason === "Temporary Failure" ? 4 : 2;
-}
-function writeSkillError(dependencies, error) {
-    dependencies.stderr(`${JSON.stringify({ error })}\n`);
-}
 function parseCommentContent(value) {
     const result = z.string().trim().min(1).max(20_000).refine((content) => !content.includes("\0")).safeParse(value);
     if (!result.success)