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

package/README.md

@@ -22,7 +22,7 @@ accepts signed S3 and Azure BlockBlob reservations, including reservations from
 its URL out of logs. Uploading bytes alone does not attach an asset; complete the
 matching task or Screen finalization command separately.
 
-The current CLI contract is **0.4.0**, coordinated with the official Skill's exact
+The current CLI contract is **0.5.0**, coordinated with the official Skill's exact
 pin. It breaks 0.2.0 callers: Spec, Capability, Glossary, Proposal and
 authoring-history commands address shared knowledge with `--workspace-id` instead of
 `--project-id`, `project directory` is replaced by `spec list`, Session grants
@@ -36,7 +36,7 @@ seven-day Better Auth CLI Session. It supports the Node.js 24 runtime line;
 Node.js 22 and unverified future major versions are intentionally unsupported.
 
 ```bash
-npm install --global @gonovus-ai/spec-flow-cli@0.4.0
+npm install --global @gonovus-ai/spec-flow-cli@0.5.0
 specflow auth login
 specflow auth status
 specflow auth logout
@@ -824,3 +824,136 @@ the same editing and publication contract. To move a Spec to Unassigned, use
 `specflow spec update --workspace-id <id> --spec-id <id> --capability-id none
 --expected-version <version>`. Capability deletion rejects child Capabilities;
 deleting a leaf moves its Specs to Unassigned and records their placement changes.
+
+
+Connect 1–50 repositories atomically with one idempotency key:
+
+```bash
+specflow github connection connect-batch --project-id PROJECT_ID \
+  --repository owner/tasks:10:20 --repository owner/mobile:10:21 \
+  --outbound-repository-id 20 --idempotency-key UUID
+```
+
+Repeat `--repository owner/name:installationId:repositoryId` for each repository.
+Use `--no-outbound` to explicitly select none. Without either option, only the
+first repository of the Project's first batch becomes outbound; later batches
+only create from GitHub. A Project with an outbound repository cannot nominate
+another during connection. Workspace binding conflicts reject the whole batch.
+A real Web/CLI Session with current Workspace settings permission and personal
+GitHub administrator access to every repository is required. The single-repository
+`github connection connect` command remains available.
+
+## Spec responsibility, Scenario discussions and audit pages (0.5.0)
+
+Version 0.5.0 adds these commands compatibly to 0.4.0 (ADR 0065). The Skill
+source pins the matching minor version; publishing remains a separate release.
+All commands emit the existing JSON result on stdout; `--json` is accepted
+explicitly. Failures keep the existing structured stderr and exit categories.
+
+```bash
+specflow spec owner read --workspace-id W --spec-id PAY-S1
+specflow spec owner candidates --workspace-id W --spec-id PAY-S1
+specflow spec owner assign --workspace-id W --spec-id PAY-S1 --user-id USER --expected-version '"1"' --idempotency-key UUID
+specflow spec owner clear --workspace-id W --spec-id PAY-S1 --expected-version '"2"' --idempotency-key UUID
+specflow spec discussion targets --workspace-id W --spec-id PAY-S1 --context-kind Published
+specflow spec discussion list --workspace-id W --spec-id PAY-S1 --context-kind Published --scenario-id PAY-S1-1 --limit 30
+specflow spec discussion comments --workspace-id W --spec-id PAY-S1 --thread-id THREAD_UUID --limit 30
+specflow spec discussion start --workspace-id W --spec-id PAY-S1 --scenario-id PAY-S1-1 --context-hash HASH --content 'Question' --idempotency-key UUID
+specflow spec discussion reply --workspace-id W --spec-id PAY-S1 --thread-id THREAD_UUID --context-kind WorkingDraft --context-hash HASH --content 'Reply' --idempotency-key UUID
+specflow spec discussion edit-comment --workspace-id W --spec-id PAY-S1 --thread-id THREAD_UUID --comment-id COMMENT_UUID --content 'Edited' --expected-version '"1"' --idempotency-key UUID
+specflow spec discussion delete-comment --workspace-id W --spec-id PAY-S1 --thread-id THREAD_UUID --comment-id COMMENT_UUID --expected-version '"2"' --idempotency-key UUID
+specflow spec discussion resolve --workspace-id W --spec-id PAY-S1 --thread-id THREAD_UUID --expected-version '"3"' --idempotency-key UUID
+specflow spec discussion reopen --workspace-id W --spec-id PAY-S1 --thread-id THREAD_UUID --expected-version '"4"' --idempotency-key UUID
+specflow project rename --project-id PROJECT_UUID --name 'Delivery' --expected-version '"1"' --idempotency-key UUID
+specflow project audit-log --project-id PROJECT_UUID --limit 50
+specflow workspace audit-log --workspace-id W --limit 50
+```
+
+Owner reads return `{ owner, version }`, candidates return `{ candidates }`, and
+assignment/clear return `{ version }`. Responsibility grants no additional access;
+only currently eligible Workspace members can be assigned. Clearing is explicit.
+
+Discussion targets return `{ targets, targetsAvailable, currentContext,
+canComment }`. Obtain the allocated Scenario ID and its `context.hash` there;
+pass the exact hash as `--context-hash` to start/reply. Every discussion command
+accepts `--context-kind Published|WorkingDraft` (default Published). Never use a
+Published hash for different Working Draft content. `SPEC_DISCUSSION_CONTEXT_CHANGED`
+retains its public code and maps to `Invalid Operation`; deliberately reread the
+selected context before submitting a new intent. Edits preserve original comment
+context, and deletion retains a tombstone. Only authors edit/delete their comments;
+initiators or current Spec editors resolve/reopen threads. Use `comments[].version`
+for comment writes and `threads[].version` for status writes; they are independent.
+Discussion writes return `{ threadId, commentId, replayed }`.
+
+Thread, comment and audit reads return one bounded page and `nextCursor`; repeat
+with `--cursor <nextCursor>` and the same scope/view/filter to continue. Discussion
+pages have `threads` or `comments`; audit pages have `events` including original
+source and actor attribution. Audit access is checked separately for the Project
+or Workspace. Rename returns the existing `{ project }` lifecycle result; it
+retains Project identity and rejects ordinary writes to Archived Projects.
+
+All new writes require an explicit UUID idempotency key. A bounded transport retry
+reuses the same input, observed version, credential and key; retain that key after
+an ambiguous result. Stale versions map to `Resource Changed`. The CLI neither
+fetches a replacement version nor changes the requested context automatically.
+Workspace read Tokens cannot use these private operations. Current Role, eligibility,
+credential and lifecycle rules remain enforced by the existing service endpoints.
+
+## Shared task views, statistics, colors and personal tasks (ZTA-875/876/878)
+
+```sh
+specflow work-item view list --project-id PROJECT
+specflow work-item view save --project-id PROJECT --input '{"id":"UUID","name":"Mine","layout":"list","groupedByStatus":false,"filters":{"assignees":[],"customFields":{},"dueDates":[],"labels":[],"priorities":[],"search":"","sortBy":"number","sortOrder":"asc","statuses":[]}}'
+specflow work-item view save --project-id PROJECT --input '<complete view JSON without version>' --expected-version '"1"'
+specflow work-item statistics --project-id PROJECT --query '{"view":"list","assignee":"USER_ID","priority":"high,urgent"}'
+specflow workspace my-work-items --workspace-id WORKSPACE --limit 50 [--cursor CURSOR]
+specflow work-item-custom-field create --project-id PROJECT --name Risk --type dropdown --option High --option Low --option-colors '["danger",null]'
+specflow work-item-custom-field option-colors --project-id PROJECT --field-id FIELD --colors '["warning",null]' --expected-version '"1"' --idempotency-key UUID
+specflow work-item-custom-field option-colors --project-id PROJECT --field-id FIELD --clear --expected-version '"2"' --idempotency-key UUID
+```
+
+Views retain the existing board/list layout and complete filters, including optional
+`repositoryConnectionId`. Save omits the expected version only for a new ID.
+Identical immediate retries use the same ID, content and observed version; the
+server owns replay and stale-version behavior. No view Idempotency-Key is invented.
+Statistics returns the server aggregate, including trends at `overview.timeline`;
+there is no client page counting. Query accepts existing server selection keys:
+`view`, `repositoryConnectionId`, `assignee`, `customFields`, `due`, `dueAfter`,
+`dueBefore`, `label`, `priority`, `search`, `sortBy`, `sortOrder`, `startAfter`,
+`startBefore`, `status`. CSV and customFields JSON strings retain server semantics.
+Personal tasks returns `total`, Project `groups` and `nextCursor` from the current
+User's authorized unfinished tasks in Active Projects; retain the server cursor.
+Colors align one-to-one with dropdown options; null entries clear individual colors,
+`--clear` clears all. The server validates color values, lengths and field type.
+Assistant can discover views, statistics/trends, option colors and my unfinished
+Work Items. View and color writes wait for approval and retain version preconditions.
+
+## Local Screen image files (ZTA-881 CLI)
+
+```sh
+specflow map screen image-upload --workspace-id WORKSPACE --screen-id SCREEN --file ./image.png --content-type image/png --expected-version '"1"' --idempotency-key RESERVE_KEY --finalize-key FINALIZE_KEY
+specflow map screen image-download --workspace-id WORKSPACE --screen-id SCREEN --asset-id ASSET_UUID --output-file ./download.png
+```
+
+Upload reserves against the observed Screen version, validates the returned fresh
+HTTP(S) reservation, PUTs bytes without Session credentials or redirects, and
+finalizes using a separate retained key and the same version. Local files must be
+nonempty regular files of at most 10 MiB; server MIME/size checks still apply.
+Retain both phase keys and identical inputs after failures. Once finalized, a new
+reservation attempt with the old reserve key returns upload-expired; reread the
+Screen to resolve an ambiguous completion. Existing image-reserve/image-finalize/
+image-remove commands remain available for explicit phase control.
+Download accepts only authorized Workspace/Screen/asset identities, never an
+arbitrary URL, and creates a new owner-only file without overwriting existing files.
+Assistant image handling is outside this CLI slice.
+
+Global search uses the server's cross-resource search and current authority:
+
+```sh
+specflow search-global --query 'PAY-12' --limit 20
+specflow search-global --query 'payment' --limit 20 --cursor '<nextCursor>'
+```
+
+The JSON response preserves object kind, ID, owning Workspace/Project, totalCount
+and nextCursor. Continue with the same query until nextCursor is null. The server
+has no type filter. `specflow spec search` retains its published-Spec semantics.

package/dist/cli.js

@@ -3,13 +3,18 @@ import { randomUUID } from "node:crypto";
 import createClient from "openapi-fetch";
 import { z } from "zod";
 import { addAuthenticationCommandTopology } from "./authentication-command-topology.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 { registerProductMapCommands } from "./product-map-commands.js";
+import { registerProjectAdministrationCommands } from "./project-administration-commands.js";
+import { registerSpecDiscussionCommands } from "./spec-discussion-commands.js";
+import { registerSpecOwnerCommands } from "./spec-owner-commands.js";
 import { specFlowCliUserAgent } from "./user-agent.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) {
@@ -1267,7 +1272,22 @@ 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 });
+    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) => {
+        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 }));
+    });
+    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 timeEntry = workItem.command("time-entry").description("Record and read task time entries");
     timeEntry.command("list")
@@ -2164,6 +2184,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 +2201,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 +2214,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 }),