Merge branch 'feature/hidden-issues-cli-staff' into 'main'

cli: surface the hidden-issue flag, only when it is set

Closes #330

See merge request postgres-ai/postgresai!394

Author: Sarumyan

cli/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+### Added
+
+- `issues list` and `issues view` (and their MCP counterparts `list_issues` /
+  `view_issue`) now surface the staff-only hidden-issue flag. It is rendered
+  **only when true**: hidden issues are filtered out server-side for everyone
+  but PostgresAI staff, so a non-staff response can only ever carry
+  `is_hidden: false`, and printing that would disclose that the mechanism
+  exists. `issues list --hidden-only` (MCP: `list_issues` with
+  `hidden_only: true`) lists just the hidden ones.
+
+  Requires platform-all !712, which resolves staff from the access-token
+  header. Until it is deployed the CLI degrades silently rather than erroring:
+  `--hidden-only` returns an empty list and `is_hidden` never appears. The
+  same silence applies to a credential that does not qualify as staff — the
+  token must be personal, live, and, if it is a per-organization token, issued
+  on or after 2026-08-14.
+
+  Issue requests now carry `x-pgai-include-hidden`, the server's opt-in for
+  hidden rows. It is a client capability declaration — "this client will mark
+  hidden issues" — not a user preference. The platform default-excludes hidden
+  rows from any token caller that omits it, so older CLI versions (and curl,
+  scripts, MCP clients) keep seeing exactly what they see today rather than
+  receiving staff-internal issues they would render as ordinary ones.
+
 ### Fixed
 
 - `checkup --markdown` previously performed server-side conversion and sent the

cli/README.md

@@ -299,7 +299,7 @@ required** — the server will not assume an organization. Call `orgs_list` (or
 run `pgai orgs`) to discover the available ids.
 
 Tools exposed:
-- `list_issues`: returns the same JSON as `postgresai issues list` (args: `{ org_id, status?, limit?, offset?, debug? }`).
+- `list_issues`: returns the same JSON as `postgresai issues list` (args: `{ org_id, status?, hidden_only?, limit?, offset?, debug? }`).
 - `view_issue`: view a single issue with its comments (args: `{ issue_id, org_id, debug? }`).
 - `create_issue`: create a new issue (args: `{ title, description?, org_id, attachments?, debug? }`).
 - `update_issue`: update title/description/status/labels (args: `{ issue_id, org_id, title?, description?, status?, labels?, attachments?, debug? }`).
@@ -350,7 +350,8 @@ sensitive.
 ### Issues management (`issues` group)
 
 ```bash
-postgresai issues list                                       # List issues (shows: id, title, status, created_at)
+postgresai issues list                                       # List issues (shows: id, title, status, created_at; is_hidden only when set)
+postgresai issues list --hidden-only                         # Only hidden issues (PostgresAI staff)
 postgresai issues view <issueId>                             # View issue details and comments
 postgresai issues create --org-id <id> --title <t>           # Create a new issue
 postgresai issues update <issueId> [--title ... --status ...]# Update an existing issue
@@ -364,6 +365,21 @@ postgresai issues files download <url> [-o <path>]           # Download a file
 #   --json           Output raw JSON (overrides default YAML)
 ```
 
+#### Hidden issues (PostgresAI staff)
+
+Hidden issues are staff-internal. `issues list` and `issues view` mark them
+with `is_hidden: true`; the key is omitted entirely otherwise, so ordinary
+issues look exactly as they always have. `--hidden-only` lists just the hidden
+ones, filtered server-side.
+
+Staff access is granted per credential, not per person, and a credential that
+does not qualify simply sees nothing — `--hidden-only` returns an empty list
+and `is_hidden` never appears, with no error, which is indistinguishable from
+"there are no hidden issues". The token must be personal, not revoked, not
+expired, and — if it is a per-organization token rather than a global one —
+issued on or after 2026-08-14. Re-issue the token if `--hidden-only` comes
+back unexpectedly empty.
+
 #### Attaching files to issues and comments (`--attach`)
 
 `create`, `update`, `post-comment`, and `update-comment` accept a repeatable

cli/bin/postgres-ai.ts

@@ -11,7 +11,7 @@ import { fileURLToPath } from "url";
 import * as crypto from "node:crypto";
 import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
-import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment, fetchActionItem, fetchActionItems, createActionItem, updateActionItem, type ConfigChange } from "../lib/issues";
+import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment, fetchActionItem, fetchActionItems, createActionItem, updateActionItem, withVisibleHiddenFlag, type ConfigChange } from "../lib/issues";
 import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, renderMarkdownForTerminal, parseFlexibleDate } from "../lib/reports";
 import {
   executeJoeCommand,
@@ -4798,9 +4798,10 @@ withOrgOptions(issues.command("list"))
   .option("--status <status>", "filter by status: open, closed, or all (default: all)")
   .option("--limit <n>", "max number of issues to return (default: 20)", parseInt)
   .option("--offset <n>", "number of issues to skip (default: 0)", parseInt)
+  .option("--hidden-only", "list only hidden issues (PostgresAI staff)")
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (opts: OrgOptions & { status?: string; limit?: number; offset?: number; debug?: boolean; json?: boolean }) => {
+  .action(async (opts: OrgOptions & { status?: string; limit?: number; offset?: number; hiddenOnly?: boolean; debug?: boolean; json?: boolean }) => {
     const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching issues...");
     try {
       const rootOpts = program.opts<CliOptions>();
@@ -4839,16 +4840,22 @@ withOrgOptions(issues.command("list"))
         status: statusFilter,
         limit: opts.limit,
         offset: opts.offset,
+        hiddenOnly: !!opts.hiddenOnly,
         debug: !!opts.debug,
       });
       spinner.stop();
       const trimmed = Array.isArray(result)
-        ? (result as any[]).map((r) => ({
-            id: (r as any).id,
-            title: (r as any).title,
-            status: (r as any).status,
-            created_at: (r as any).created_at,
-          }))
+        ? (result as any[]).map((r) =>
+            // Route through the same helper as `issues view` so the
+            // "render is_hidden only when true" rule lives in one place.
+            withVisibleHiddenFlag({
+              id: (r as any).id,
+              title: (r as any).title,
+              status: (r as any).status,
+              created_at: (r as any).created_at,
+              is_hidden: (r as any).is_hidden,
+            })
+          )
         : result;
       printResult(trimmed, opts.json);
     } catch (err) {
@@ -4889,7 +4896,7 @@ withOrgOptions(issues.command("view <issueId>"))
       spinner.update("Fetching comments...");
       const comments = await fetchIssueComments({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
       spinner.stop();
-      const combined = { issue, comments };
+      const combined = { issue: withVisibleHiddenFlag(issue), comments };
       printResult(combined, opts.json);
     } catch (err) {
       spinner.stop();