saturndocs 0.1.0

package/dist/suggestions-4WFQ3APX.js

@@ -0,0 +1,739 @@
+import {
+  readTextInput
+} from "./chunk-N7QPZMLP.js";
+import {
+  asCliError,
+  clientFor
+} from "./chunk-TKISMN3P.js";
+import {
+  interruptSignal
+} from "./chunk-KGJESHJC.js";
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  CliError,
+  DEFAULT_SUGGESTION_WAIT_MS,
+  DISMISS_REASONS,
+  SUGGESTION_TABS,
+  approveSuggestion,
+  commandMetadata,
+  conversationIds,
+  createResultWriter,
+  createSuggestionPreview,
+  dismissSuggestion,
+  failureResult,
+  getSuggestion,
+  getSuggestionPreview,
+  invalidInput,
+  listSuggestions,
+  parseSuggestionWaitTarget,
+  previewIds,
+  readConversation,
+  renderDiffText,
+  requestChangesIds,
+  requestSuggestionChanges,
+  resolveGlobalOptions,
+  resolveTarget,
+  retryIds,
+  retrySuggestion,
+  reviewDecisionIds,
+  sendSessionMessage,
+  successResult,
+  suggestionDiff,
+  suggestionIds,
+  suggestionLimitations,
+  suggestionWaitErrorCode,
+  waitForSuggestion
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/suggestions/runtime.ts
+async function runSuggestionCommand(name, self, run, options = {}) {
+  const globals = resolveGlobalOptions(self);
+  const writer = createResultWriter({ json: globals.json });
+  let siteId = globals.site;
+  try {
+    const client = clientFor(globals);
+    const target = await resolveTarget(client, { ...globals.site === null ? {} : { site: globals.site }, mutation: options.mutation });
+    siteId = target.site_id;
+    const outcome = await run({ client, site: target.site_id, globals });
+    const context = { command: name, siteId: target.site_id, ids: outcome.ids, limitations: outcome.limitations };
+    process.exitCode = writer.write(successResult(context, outcome.data), { text: outcome.text });
+  } catch (error) {
+    process.exitCode = writer.write(failureResult(asCliError(error), { command: name, siteId }));
+  }
+}
+
+// src/commands/suggestions/read.ts
+var SUGGESTIONS_READ_METADATA = Object.freeze([
+  commandMetadata("suggestions list", {
+    description: "One tab of a site's suggestions, one page per invocation. `counts` is the server's tally for every tab and `next_cursor` is its own token, so a bounded page is never reported as the site's total.",
+    target: { arguments: [] },
+    effect: "Nothing. This reads.",
+    output: { fields: ["state", "counts", "suggestions", "next_cursor"], ids: [], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs suggestions list --site acme", description: "The pending tab, which is the server's default." },
+      { command: "saturndocs suggestions list --site acme --state failed", description: "One other tab." },
+      { command: "saturndocs suggestions list --site acme --cursor eyJ0IjoxfQ --json", description: "The next page, as one result object." }
+    ]
+  }),
+  commandMetadata("suggestions get", {
+    description: "One suggestion as the server holds it: the reviewed base and head, the revision, the rationale, the provenance of the run that drafted it, its open questions, what kind of failure it hit, every identity it links, its publication, and the GitHub files-changed URL. A hand-edited head and missing page content are reported as limitations rather than left for the caller to notice.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion to read." }] },
+    effect: "Nothing. This reads.",
+    output: {
+      fields: ["suggestion.base_sha", "suggestion.head_sha", "suggestion.revision", "suggestion.rationale", "suggestion.provenance", "suggestion.questions", "suggestion.failure_kind", "suggestion.publication", "suggestion.files_changed_url"],
+      ids: ["suggestion_id", "base_sha", "head_sha", "thread_id", "job_id", "release_id", "pr_number"],
+      limitations: ["hand_edited", "content_unavailable", "section_unavailable"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs suggestions get sug1:0123456789abcdef --site acme", description: "Everything the detail route carries." },
+      { command: "saturndocs suggestions get sug1:0123456789abcdef --site acme --json", description: "The same, with the reviewed hashes in the envelope's ids." }
+    ]
+  })
+]);
+function listText(page) {
+  const lines = [`${page.state}: ${page.suggestions.length} of ${page.counts[page.state]} on this tab`];
+  for (const suggestion of page.suggestions) {
+    lines.push(`${suggestion.suggestion_id}  ${suggestion.state}  ${suggestion.title ?? suggestion.first_path ?? "(untitled)"}`);
+  }
+  lines.push(`counts: ${SUGGESTION_TABS.map((tab) => `${tab}=${page.counts[tab]}`).join(" ")}`);
+  lines.push(page.next_cursor === null ? "next_cursor: none; this is the last page" : `next_cursor: ${page.next_cursor}`);
+  return lines.join("\n");
+}
+function detailText(detail) {
+  const s = detail.suggestion;
+  const lines = [
+    `${s.suggestion_id}  ${s.state}  revision ${s.revision ?? "unknown"}`,
+    `base ${s.base_sha}`,
+    `head ${s.head_sha ?? "unknown"}${typeof s.head_edited_by === "string" && s.head_edited_by !== "" ? ` (edited on GitHub by ${s.head_edited_by})` : ""}`,
+    `files changed: ${s.files_changed_url ?? "no pull-request URL was recorded"}`
+  ];
+  if (s.title !== null && s.title !== void 0) lines.push(`title: ${s.title}`);
+  if (s.failure_kind !== null && s.failure_kind !== void 0) lines.push(`failure (${s.failure_kind}): ${s.failure_reason ?? s.error_message ?? "no reason was recorded"}`);
+  for (const entry of s.rationale ?? []) lines.push(`rationale: ${entry.change} [${entry.affects.join(", ")}]`);
+  for (const question of s.questions ?? []) lines.push(`question ${question.question_id}${question.answered_at === null ? " (unanswered)" : ""}: ${question.body}`);
+  if (s.provenance != null) lines.push(`provenance: ${s.provenance.outcome} by ${s.provenance.model ?? "an unnamed model"}, job ${s.provenance.analysis_job_id ?? "unknown"}`);
+  if (s.publication != null) lines.push(`publication: ${s.publication.state}, job ${s.publication.job_id}, release ${s.publication.release_id ?? "none"}, activated ${s.publication.activated_at ?? "not yet"}`);
+  if (s.request_thread_id != null) lines.push(`request thread: ${s.request_thread_id}`);
+  return lines.join("\n");
+}
+function pageSize(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw invalidInput(`--limit takes a whole number; ${value} is not one.`);
+  return parsed;
+}
+function registerSuggestionsRead(group) {
+  const [list, get] = SUGGESTIONS_READ_METADATA;
+  applyCommandHelp(
+    group.command("list").action(async (options, self) => {
+      await runSuggestionCommand("suggestions list", self, async ({ client, site }) => {
+        const limit = pageSize(options.limit);
+        const page = await listSuggestions(client, { site, state: options.state, cursor: options.cursor, limit });
+        return { data: page, text: listText(page) };
+      });
+    }),
+    list
+  );
+  applyCommandHelp(
+    group.command("get").argument("<suggestion-id>", "The suggestion to read.").action(async (suggestionId, _options, self) => {
+      await runSuggestionCommand("suggestions get", self, async ({ client, site }) => {
+        const detail = await getSuggestion(client, { site, suggestionId });
+        return {
+          data: detail,
+          ids: suggestionIds(detail.suggestion),
+          limitations: suggestionLimitations(detail.suggestion),
+          text: detailText(detail)
+        };
+      });
+    }),
+    get
+  );
+}
+
+// src/commands/suggestions/diff.ts
+var SUGGESTIONS_DIFF_METADATA = Object.freeze([
+  commandMetadata("suggestions diff", {
+    description: "The suggestion's page content as a diff. Where the detail route supplied a diff it is formatted as given; where it supplied complete before and after text the two are compared in this process. No diff is computed anywhere else and none is invented: a page with neither side supplied is reported as unavailable, a deletion is reported as a deletion, and a server-truncated comparison, a hand-edited head, and lines dropped at the output bound are each named. The result hands the review to the owner rather than claiming to have done one.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion to diff." }] },
+    effect: "Nothing. This reads one suggestion and formats what came back.",
+    output: {
+      fields: ["suggestion_id", "base_sha", "head_sha", "revision", "files_changed_url", "pages", "bytes", "review"],
+      ids: ["suggestion_id", "base_sha", "head_sha"],
+      limitations: ["content_unavailable", "page_bounded", "output_truncated", "hand_edited", "section_unavailable", "review_incomplete"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs suggestions diff sug1:0123456789abcdef --site acme", description: "Every changed page, inside the output bound." },
+      { command: "saturndocs suggestions diff sug1:0123456789abcdef --site acme --path guides/cli.mdx", description: "One page, when the whole set does not fit." },
+      { command: "saturndocs suggestions diff sug1:0123456789abcdef --site acme --json", description: "The same diff and the same limitations, as one result object." }
+    ]
+  })
+]);
+function registerSuggestionsDiff(group) {
+  const metadata = SUGGESTIONS_DIFF_METADATA[0];
+  applyCommandHelp(
+    group.command("diff").argument("<suggestion-id>", "The suggestion to diff.").action(async (suggestionId, options, self) => {
+      await runSuggestionCommand("suggestions diff", self, async ({ client, site }) => {
+        const detail = await getSuggestion(client, { site, suggestionId });
+        const result = suggestionDiff(detail.suggestion, { path: options.path });
+        return {
+          data: result,
+          ids: suggestionIds(detail.suggestion),
+          limitations: result.limitations,
+          text: renderDiffText(result)
+        };
+      });
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/preview.ts
+var SUGGESTIONS_PREVIEW_METADATA = Object.freeze([
+  commandMetadata("suggestions preview", {
+    description: "What preview of this suggestion exists on the site. The default invocation reads and builds nothing. --create asks the server to build a preview of the current revision; it is a manage:write call, so it needs an explicit --site and is sent only after the read that proves the credential names that site. The state the server returns is reported as it stands and nothing is waited for. Only a built preview of the current revision that came with an address is reported as one that opens: a preview of an earlier revision and a ready state with no address are each reported as what they are. There is no preview of a revision other than the last one built, and nothing here opens a browser.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion to preview." }] },
+    effect: "Nothing by default. With --create, the server is asked to build a preview of the suggestion's current revision, which starts work on the site's infrastructure.",
+    output: {
+      fields: ["state", "revision", "current", "url", "leave_url", "error", "current_preview_available", "requested_build"],
+      ids: ["suggestion_id"],
+      limitations: ["activation_unknown", "review_incomplete", "content_unavailable"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs suggestions preview sug1:0123456789abcdef --site acme", description: "What preview exists now. Nothing is built." },
+      { command: "saturndocs suggestions preview sug1:0123456789abcdef --site acme --create", description: "Ask for a preview of the current revision, then read the state the server returned." },
+      { command: "saturndocs suggestions preview sug1:0123456789abcdef --site acme --json", description: "The same reading, with the preview address in the result object." }
+    ]
+  })
+]);
+var STATE_LINES = Object.freeze({
+  none: "No preview has been built for this suggestion.",
+  building: "A preview build is running. Read this again to find out how it ended.",
+  ready: "A preview has been built.",
+  failed: "The preview build failed."
+});
+function previewText(result) {
+  const lines = [
+    `${result.suggestion_id}  ${result.state}  revision ${result.revision === null ? "none" : result.revision}${result.state === "none" ? "" : result.current ? " (current)" : " (not the current revision)"}`,
+    STATE_LINES[result.state]
+  ];
+  if (result.error !== null) lines.push(`failure: ${result.error}`);
+  if (result.current_preview_available) {
+    lines.push(`open: ${String(result.url)}`);
+    if (result.leave_url !== null) lines.push(`leave: ${result.leave_url}`);
+    lines.push("That address carries the token that opens the preview. Treat it as a credential.");
+  } else if (result.url !== null) {
+    lines.push(`open (revision ${result.revision === null ? "unknown" : result.revision}, not the current one): ${result.url}`);
+    if (result.leave_url !== null) lines.push(`leave: ${result.leave_url}`);
+  }
+  return lines.join("\n");
+}
+function registerSuggestionsPreview(group) {
+  const metadata = SUGGESTIONS_PREVIEW_METADATA[0];
+  applyCommandHelp(
+    group.command("preview").argument("<suggestion-id>", "The suggestion to preview.").action(async (suggestionId, options, self) => {
+      const create = options.create === true;
+      await runSuggestionCommand(
+        "suggestions preview",
+        self,
+        async ({ client, site }) => {
+          const result = create ? await createSuggestionPreview(client, { site, suggestionId }) : await getSuggestionPreview(client, { site, suggestionId });
+          return { data: result, ids: previewIds(result), limitations: result.limitations, text: previewText(result) };
+        },
+        // Only --create writes; the default read must not demand more of a --site than any other read.
+        { mutation: create }
+      );
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/approve.ts
+var SUGGESTIONS_APPROVE_METADATA = Object.freeze([
+  commandMetadata("suggestions approve", {
+    description: "Merge exactly the revision named by --base and --head. Both are mandatory here although the server leaves them optional, because an approval missing one publishes whatever the head moved to since it was read. A base or head that no longer matches is refused as a stale review and the hashes the suggestion holds now are never substituted: the answer is to read the revision again. An approval that starts a merge is reported as publishing, which is not a published site, and one that produces another revision is reported as work nobody has reviewed yet.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion whose reviewed revision is approved." }] },
+    effect: "Merges the reviewed revision's pull request and starts the publication of the release that follows it.",
+    idempotency: "expected_review",
+    output: {
+      fields: ["state", "published", "publication_started", "review_required", "pr_number", "merge_commit_sha", "failure"],
+      ids: ["suggestion_id", "base_sha", "head_sha", "pr_number"],
+      limitations: ["review_incomplete", "activation_unknown"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "stale_review", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "remote_failure", "interrupted"],
+    examples: [
+      {
+        command: "saturndocs suggestions approve sug1:0123456789abcdef --site acme --base aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --head bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        description: "Approve the exact revision the preceding read and diff covered."
+      },
+      {
+        command: "saturndocs suggestions approve sug1:0123456789abcdef --site acme --base aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --head bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --json",
+        description: "The same approval, with the outcome and the reviewed identities as one result object."
+      }
+    ]
+  })
+]);
+function approveText(result) {
+  const lines = [
+    `${result.suggestion_id}  ${result.state}${result.pr_number === null ? "" : `  pull request #${result.pr_number}`}`,
+    `base ${result.base_sha}`,
+    `head ${result.head_sha}`
+  ];
+  if (result.merge_commit_sha !== null) lines.push(`merge commit ${result.merge_commit_sha}`);
+  lines.push(
+    result.state === "publishing" ? "The reviewed revision was merged and its publication has started. This command cannot say a release went live." : "The approval started another revision instead of publishing."
+  );
+  return lines.join("\n");
+}
+function approvalFailed(result) {
+  const failure = result.failure;
+  const reason = failure?.reason ?? "The server gave no reason.";
+  const code = failure?.code === null || failure?.code === void 0 ? "" : ` (${failure.code})`;
+  return new CliError("remote_failure", `The merge of the reviewed revision failed${code}: ${reason} Nothing was published.`, {
+    data: result,
+    limitations: result.limitations
+  });
+}
+function registerSuggestionsApprove(group) {
+  const metadata = SUGGESTIONS_APPROVE_METADATA[0];
+  applyCommandHelp(
+    group.command("approve").argument("<suggestion-id>", "The suggestion whose reviewed revision is approved.").action(async (suggestionId, options, self) => {
+      await runSuggestionCommand(
+        "suggestions approve",
+        self,
+        async ({ client, site }) => {
+          const result = await approveSuggestion(client, { site, suggestionId, base: options.base, head: options.head });
+          if (result.state === "failed") throw approvalFailed(result);
+          return { data: result, ids: reviewDecisionIds(result), limitations: result.limitations, text: approveText(result) };
+        },
+        { mutation: true }
+      );
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/dismiss.ts
+var SUGGESTIONS_DISMISS_METADATA = Object.freeze([
+  commandMetadata("suggestions dismiss", {
+    description: `Dismiss exactly the revision named by --base and --head, with a reason the server stores: ${DISMISS_REASONS.join(", ")}. The optional note is the text of the dismissal and comes from --text or --file, as it does for every other text this CLI sends. This is a manage:write operation and needs no approval permission. Both hashes are mandatory here although the server leaves them optional, so a head that moved after the review is refused as a stale review rather than dismissed unseen. A dismissal the server recorded whose pull request is still open is reported as incomplete cleanup, because nothing here closes it.`,
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion whose reviewed revision is dismissed." }] },
+    effect: "Marks the reviewed revision dismissed and asks GitHub to close its pull request.",
+    idempotency: "expected_review",
+    output: {
+      fields: ["state", "reason", "pr_number", "pull_request_closed", "cleanup_complete"],
+      ids: ["suggestion_id", "base_sha", "head_sha", "pr_number"],
+      limitations: ["cleanup_incomplete"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "stale_review", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "remote_failure", "interrupted"],
+    examples: [
+      {
+        command: "saturndocs suggestions dismiss sug1:0123456789abcdef --site acme --base aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --head bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --reason not_needed",
+        description: "Dismiss the exact revision that was reviewed."
+      },
+      {
+        command: 'saturndocs suggestions dismiss sug1:0123456789abcdef --site acme --base aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --head bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb --reason wrong_pages --text "It edits a page we removed." --json',
+        description: "The same dismissal with a note, as one result object."
+      }
+    ]
+  })
+]);
+function dismissText(result) {
+  const lines = [
+    `${result.suggestion_id}  dismissed (${result.reason})`,
+    `base ${result.base_sha}`,
+    `head ${result.head_sha}`
+  ];
+  if (result.pr_number !== null) {
+    lines.push(`pull request #${result.pr_number}: ${result.pull_request_closed === true ? "closed" : "not reported as closed"}`);
+  }
+  return lines.join("\n");
+}
+function cleanupIncomplete(result) {
+  const first = result.limitations[0];
+  return new CliError("remote_failure", `${result.suggestion_id} is dismissed, and its GitHub cleanup did not finish. ${first?.message ?? ""}`.trim(), {
+    data: result,
+    limitations: result.limitations
+  });
+}
+function registerSuggestionsDismiss(group) {
+  const metadata = SUGGESTIONS_DISMISS_METADATA[0];
+  applyCommandHelp(
+    group.command("dismiss").argument("<suggestion-id>", "The suggestion whose reviewed revision is dismissed.").action(async (suggestionId, options, self) => {
+      await runSuggestionCommand(
+        "suggestions dismiss",
+        self,
+        async ({ client, site, globals }) => {
+          const note = await readTextInput(options, {
+            command: "suggestions dismiss",
+            requirement: metadata.text.requirement,
+            limit: metadata.text.limit,
+            interactive: globals.input
+          });
+          const result = await dismissSuggestion(client, { site, suggestionId, base: options.base, head: options.head, reason: options.reason, note });
+          if (!result.cleanup_complete) throw cleanupIncomplete(result);
+          return { data: result, ids: reviewDecisionIds(result), limitations: result.limitations, text: dismissText(result) };
+        },
+        { mutation: true }
+      );
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/conversation.ts
+var SUGGESTIONS_CONVERSATION_METADATA = Object.freeze([
+  commandMetadata("suggestions conversation", {
+    description: "The transcript of one suggestion's conversation, oldest first: every note, question, and answer with the revision it was said against and the documents cited for it. This reads one page of the session route and nothing else; there is no streaming and no interactive chat here, and a turn is sent with `suggestions message`.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion whose conversation is read." }] },
+    effect: "Nothing. This reads.",
+    output: { fields: ["entries", "latest_revision"], ids: ["suggestion_id"], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs suggestions conversation sug1:0123456789abcdef --site acme", description: "Everything said about this suggestion, with each entry's revision." },
+      { command: "saturndocs suggestions conversation sug1:0123456789abcdef --site acme --json", description: "The same transcript as one result object." }
+    ]
+  })
+]);
+function conversationText(result) {
+  const lines = [
+    `${result.suggestion_id}  ${result.entries.length} ${result.entries.length === 1 ? "entry" : "entries"}  latest revision ${result.latest_revision ?? "none"}`
+  ];
+  for (const entry of result.entries) {
+    lines.push(`[revision ${entry.revision}] ${entry.kind} by ${entry.author ?? "an unnamed author"} at ${entry.created_at}: ${entry.body}`);
+    for (const evidence of entry.evidence ?? []) lines.push(`    evidence: ${evidence.title} (${evidence.document}) ${evidence.url}`);
+  }
+  if (result.entries.length === 0) lines.push("No entries. Nothing has been said about this suggestion.");
+  return lines.join("\n");
+}
+function registerSuggestionsConversation(group) {
+  const metadata = SUGGESTIONS_CONVERSATION_METADATA[0];
+  applyCommandHelp(
+    group.command("conversation").argument("<suggestion-id>", "The suggestion whose conversation is read.").action(async (suggestionId, _options, self) => {
+      await runSuggestionCommand("suggestions conversation", self, async ({ client, site }) => {
+        const result = await readConversation(client, { site, suggestionId });
+        return { data: result, ids: conversationIds(result), text: conversationText(result) };
+      });
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/message.ts
+var SUGGESTIONS_MESSAGE_METADATA = Object.freeze([
+  commandMetadata("suggestions message", {
+    description: "Send one turn to a suggestion's conversation: a question about the draft, or the answer to a question the suggestion asked. `--question-id` names a question of this suggestion, which is not a request thread id and is refused if it is one. The answer comes back whole with the documents cited for it, and `started_revision` says what happened: false is an answer saved in the transcript, true is a revision run whose draft nobody has reviewed. One turn per invocation; there is no streaming and no interactive chat. If the answer to a sent message cannot be read, the result is an unknown outcome rather than a failure and nothing is sent again, because the turn may already be recorded.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion to speak to." }] },
+    effect: "Records the turn in the suggestion's conversation, which may queue a revision run.",
+    output: {
+      fields: ["answer", "evidence", "started_revision", "saved_answer", "question_id"],
+      ids: ["suggestion_id"],
+      limitations: ["review_incomplete"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "interrupted"],
+    examples: [
+      {
+        command: 'saturndocs suggestions message sug1:0123456789abcdef --site acme --text "Keep the public name." --question-id question-example',
+        description: "Answer one of the suggestion's own questions."
+      },
+      {
+        command: "saturndocs suggestions message sug1:0123456789abcdef --site acme --file - --json",
+        description: "Ask about the draft with the text on stdin, as one result object."
+      }
+    ]
+  })
+]);
+function messageText(result) {
+  const lines = [
+    `${result.suggestion_id}  ${result.started_revision ? "queued a revision" : "answer saved; nothing was queued"}`
+  ];
+  if (result.question_id !== null) lines.push(`answered suggestion question ${result.question_id} (a question of this suggestion, not a request thread)`);
+  lines.push(result.answer);
+  for (const evidence of result.evidence) lines.push(`evidence: ${evidence.title} (${evidence.document}) ${evidence.url}`);
+  if (result.started_revision) lines.push(result.limitations[0]?.message ?? "");
+  return lines.filter((line) => line !== "").join("\n");
+}
+function registerSuggestionsMessage(group) {
+  const metadata = SUGGESTIONS_MESSAGE_METADATA[0];
+  applyCommandHelp(
+    group.command("message").argument("<suggestion-id>", "The suggestion to speak to.").action(async (suggestionId, options, self) => {
+      await runSuggestionCommand(
+        "suggestions message",
+        self,
+        async ({ client, site, globals }) => {
+          const message = await readTextInput(options, {
+            command: "suggestions message",
+            requirement: metadata.text.requirement,
+            limit: metadata.text.limit,
+            interactive: globals.input
+          });
+          const result = await sendSessionMessage(client, { site, suggestionId, message: message ?? "", questionId: options.questionId });
+          return { data: result, ids: conversationIds(result), limitations: result.limitations, text: messageText(result) };
+        },
+        { mutation: true }
+      );
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/request-changes.ts
+var SUGGESTIONS_REQUEST_CHANGES_METADATA = Object.freeze([
+  commandMetadata("suggestions request-changes", {
+    description: "Ask for a revision of a suggestion, with the note saying what to change. The note comes from --text or --file, as every other text this CLI sends does. What the call did is reported exactly: `revision_queued` is a revision run this call started, and `already_requested` is a revision asked for earlier that is still running, which this note did not join and did not change. Neither is a published change; the draft a revision produces has nobody's review.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion to revise." }] },
+    effect: "Queues a revision run for the suggestion when no earlier request is still running.",
+    output: {
+      fields: ["state", "revision", "pr_number", "revision_queued", "already_requested"],
+      ids: ["suggestion_id", "pr_number"],
+      limitations: ["review_incomplete"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "interrupted"],
+    examples: [
+      {
+        command: 'saturndocs suggestions request-changes sug1:0123456789abcdef --site acme --text "Remove the internal flag."',
+        description: "Ask for one revision."
+      },
+      {
+        command: "saturndocs suggestions request-changes sug1:0123456789abcdef --site acme --file notes.md --json",
+        description: "The same request with the note in a file, as one result object."
+      }
+    ]
+  })
+]);
+function requestChangesText(result) {
+  const revision = result.revision === null ? "an unnumbered revision" : `revision ${result.revision}`;
+  const lines = [
+    result.already_requested ? `${result.suggestion_id}  nothing queued: ${revision} was asked for earlier and is still running` : `${result.suggestion_id}  queued ${revision}`
+  ];
+  if (result.pr_number !== null) lines.push(`pull request #${result.pr_number}`);
+  lines.push(result.limitations[0]?.message ?? "");
+  return lines.filter((line) => line !== "").join("\n");
+}
+function registerSuggestionsRequestChanges(group) {
+  const metadata = SUGGESTIONS_REQUEST_CHANGES_METADATA[0];
+  applyCommandHelp(
+    group.command("request-changes").argument("<suggestion-id>", "The suggestion to revise.").action(async (suggestionId, options, self) => {
+      await runSuggestionCommand(
+        "suggestions request-changes",
+        self,
+        async ({ client, site, globals }) => {
+          const note = await readTextInput(options, {
+            command: "suggestions request-changes",
+            requirement: metadata.text.requirement,
+            limit: metadata.text.limit,
+            interactive: globals.input
+          });
+          const result = await requestSuggestionChanges(client, { site, suggestionId, note: note ?? "" });
+          return { data: result, ids: requestChangesIds(result), limitations: result.limitations, text: requestChangesText(result) };
+        },
+        { mutation: true }
+      );
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/retry.ts
+var SUGGESTIONS_RETRY_METADATA = Object.freeze([
+  commandMetadata("suggestions retry", {
+    description: "Retry whichever part of this suggestion failed. The server decides which: an analysis that failed or timed out is queued again and answers with the job and the attempt to follow, a publication that failed is attempted again and answers with the same outcome an approval does, and a revision that failed is refused as not retryable with the server's own reason. This is a manage:approve operation even on the analysis path, because the same route serves the merge. It carries no reviewed hashes and approves no draft: an answer of revising is another revision nobody has read, never an approval of it. An answer this client cannot read is reported as an unknown outcome and the retry is not sent again.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion, or the analysis job id the Failed tab shows in its place, to retry." }] },
+    effect: "Queues the failed analysis again, or merges the failed publication again. Neither is reported as finished.",
+    output: {
+      fields: ["kind", "job_id", "attempt", "budget_tokens", "state", "published", "publication_started", "review_required", "pr_number", "merge_commit_sha", "failure"],
+      ids: ["suggestion_id", "job_id", "attempt", "pr_number"],
+      limitations: ["review_incomplete", "activation_unknown"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "remote_failure", "interrupted"],
+    examples: [
+      {
+        command: "saturndocs suggestions retry sug1:0123456789abcdef --site acme",
+        description: "Retry whichever of the analysis and the publication failed."
+      },
+      {
+        command: "saturndocs suggestions retry sug1:0123456789abcdef --site acme --json",
+        description: "The same retry, with the job or the publication outcome as one result object."
+      }
+    ]
+  })
+]);
+function retryText(result, site) {
+  if (result.kind === "analysis") {
+    return [
+      `${result.suggestion_id}  analysis queued again  job ${result.job_id}${result.attempt === null ? "" : `  attempt ${String(result.attempt)}`}`,
+      `The analysis was queued again and has not run yet. Follow it with saturndocs activity get ${result.job_id} --site ${site}.`
+    ].join("\n");
+  }
+  const lines = [`${result.suggestion_id}  ${result.state}${result.pr_number === null ? "" : `  pull request #${result.pr_number}`}`];
+  if (result.merge_commit_sha !== null) lines.push(`merge commit ${result.merge_commit_sha}`);
+  lines.push(
+    result.state === "publishing" ? "The publication was attempted again and its build has started. This command cannot say a release went live." : "The retry started another revision instead of publishing. Nobody has reviewed it."
+  );
+  return lines.join("\n");
+}
+function retryFailed(result) {
+  const reason = result.failure?.reason ?? "The server gave no reason.";
+  const code = result.failure?.code === null || result.failure?.code === void 0 ? "" : ` (${result.failure.code})`;
+  return new CliError("remote_failure", `The retried publication failed again${code}: ${reason} Nothing was published.`, {
+    data: result,
+    limitations: result.limitations
+  });
+}
+function registerSuggestionsRetry(group) {
+  const metadata = SUGGESTIONS_RETRY_METADATA[0];
+  applyCommandHelp(
+    group.command("retry").argument("<suggestion-id>", "The suggestion, or the analysis job id the Failed tab shows in its place, to retry.").action(async (suggestionId, _options, self) => {
+      await runSuggestionCommand(
+        "suggestions retry",
+        self,
+        async ({ client, site }) => {
+          const result = await retrySuggestion(client, { site, suggestionId });
+          if (result.kind === "publication" && result.state === "failed") throw retryFailed(result);
+          return { data: result, ids: retryIds(result), limitations: result.limitations, text: retryText(result, site) };
+        },
+        { mutation: true }
+      );
+    }),
+    metadata
+  );
+}
+
+// src/commands/suggestions/wait.ts
+var SUGGESTIONS_WAIT_METADATA = Object.freeze([
+  commandMetadata("suggestions wait", {
+    description: "Follow one suggestion to the state named by --until. With reviewable it ends on the revision to read, with its base, its head, and what a reading of it does not cover; a revision whose page content the server withheld is handed back for its owner to read on GitHub rather than reported as reviewed. With published it ends only where the release the suggestion's own publication names shows an activation record of its own, because a merged pull request, a succeeded publication job, and a finished build are none of them publication; whether that release is the one readers see now is reported separately, and an activation record that could not be read stays unknown rather than becoming no. A dismissal, a supersession, a failure, and an approval that led to another revision each end the wait with their own outcome. Nothing here approves, retries, or picks a release the suggestion did not name.",
+    target: { arguments: [{ name: "suggestion-id", required: true, description: "The suggestion to follow." }] },
+    effect: "Nothing. This reads one suggestion, and the release it names, until the target is reached or the deadline passes.",
+    output: {
+      fields: ["target", "outcome", "state", "revision", "base_sha", "head_sha", "pr_number", "publication_job_id", "release", "owner_handoff", "polls", "elapsed_ms"],
+      ids: ["suggestion_id", "base_sha", "head_sha", "job_id", "release_id", "pr_number"],
+      limitations: ["content_unavailable", "hand_edited", "section_unavailable", "activation_unknown"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "remote_failure", "wait_timeout", "interrupted"],
+    examples: [
+      {
+        command: "saturndocs suggestions wait sug1:0123456789abcdef --until reviewable --site acme",
+        description: "Wait for the revision to be ready to read, and report what reading it does not cover."
+      },
+      {
+        command: "saturndocs suggestions wait sug1:0123456789abcdef --until published --site acme --timeout 900 --json",
+        description: "Wait for the linked release to show activation, bounded to fifteen minutes, as one result object."
+      }
+    ]
+  })
+]);
+function idsOf(result, suggestionId) {
+  const ids = result.suggestion === null ? { suggestion_id: suggestionId } : suggestionIds(result.suggestion);
+  if (result.release !== null) ids.release_id = result.release.release_id;
+  return ids;
+}
+function readCommand(suggestionId, siteId) {
+  return `saturndocs suggestions get ${suggestionId} --site ${siteId}`;
+}
+function recoveryFor(result, suggestionId, siteId) {
+  const state = result.state ?? "unknown";
+  if (result.outcome === "timed_out") {
+    return {
+      command: `saturndocs suggestions wait ${suggestionId} --until ${result.target} --site ${siteId}`,
+      replay: null,
+      message: `The suggestion was ${state} on ${siteId} when the deadline passed. Nothing was cancelled; this resumes the wait.`
+    };
+  }
+  if (result.outcome === "review_required") {
+    return { command: readCommand(suggestionId, siteId), replay: null, message: "A revision nobody has read is waiting. Read it before approving anything." };
+  }
+  if (result.outcome === "failed" || result.outcome === "dismissed" || result.outcome === "superseded" || result.outcome === "no_longer_reviewable") {
+    return { command: readCommand(suggestionId, siteId), replay: null, message: `The suggestion is ${state} on ${siteId}. Read it before deciding what to do next.` };
+  }
+  if (result.release !== null && result.release.active_release_status === "unknown") {
+    return {
+      command: `saturndocs releases get ${result.release.release_id} --site ${siteId}`,
+      replay: null,
+      message: "The release went live. Whether it is the one readers see now could not be read here."
+    };
+  }
+  if (result.owner_handoff) {
+    return { command: `saturndocs suggestions diff ${suggestionId} --site ${siteId}`, replay: null, message: "The page content is not in this result; read the pull request before approving." };
+  }
+  return null;
+}
+function textFor(result, suggestionId) {
+  const head = `${suggestionId}  ${result.outcome}  (${result.state ?? "state unread"})`;
+  const release = result.release === null ? null : `release ${result.release.release_id}: ${result.release.summary}`;
+  return [head, result.note, release].filter((line) => line !== null).join("\n");
+}
+function registerSuggestionsWait(group, environment = {}) {
+  const metadata = SUGGESTIONS_WAIT_METADATA[0];
+  const command = group.command("wait").argument("<suggestion-id>", "The suggestion to follow.").action(async (suggestionId, options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "suggestions wait", siteId: globals.site };
+    try {
+      const until = parseSuggestionWaitTarget(options.until);
+      const signal = environment.signal ?? interruptSignal() ?? void 0;
+      const client = clientFor(globals, environment);
+      const target = await resolveTarget(client, { site: globals.site ?? void 0, signal });
+      context.siteId = target.site_id;
+      const result = await waitForSuggestion(client, {
+        site: target.site_id,
+        suggestionId,
+        until,
+        deadlineMs: globals.timeout === null ? DEFAULT_SUGGESTION_WAIT_MS : globals.timeout * 1e3,
+        signal
+      });
+      const resolved = {
+        ...context,
+        ids: idsOf(result, suggestionId),
+        limitations: result.limitations,
+        recovery: recoveryFor(result, suggestionId, target.site_id)
+      };
+      const code = suggestionWaitErrorCode(result.outcome);
+      if (code === null) {
+        process.exitCode = writer.write(successResult(resolved, result), { text: textFor(result, suggestionId) });
+        return;
+      }
+      const failed = new CliError(code, textFor(result, suggestionId), { recovery: resolved.recovery, data: result });
+      process.exitCode = writer.write(failureResult(failed, resolved));
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+
+// src/commands/suggestions/index.ts
+var SUGGESTIONS_METADATA = Object.freeze([
+  ...SUGGESTIONS_READ_METADATA,
+  ...SUGGESTIONS_DIFF_METADATA,
+  ...SUGGESTIONS_PREVIEW_METADATA,
+  ...SUGGESTIONS_APPROVE_METADATA,
+  ...SUGGESTIONS_DISMISS_METADATA,
+  ...SUGGESTIONS_CONVERSATION_METADATA,
+  ...SUGGESTIONS_MESSAGE_METADATA,
+  ...SUGGESTIONS_REQUEST_CHANGES_METADATA,
+  ...SUGGESTIONS_RETRY_METADATA,
+  ...SUGGESTIONS_WAIT_METADATA
+]);
+function registerSuggestions(program) {
+  const group = program.command("suggestions").description("Read, diff, and act on a site's suggestions");
+  registerSuggestionsRead(group);
+  registerSuggestionsDiff(group);
+  registerSuggestionsPreview(group);
+  registerSuggestionsApprove(group);
+  registerSuggestionsDismiss(group);
+  registerSuggestionsConversation(group);
+  registerSuggestionsMessage(group);
+  registerSuggestionsRequestChanges(group);
+  registerSuggestionsRetry(group);
+  registerSuggestionsWait(group);
+}
+export {
+  SUGGESTIONS_METADATA,
+  registerSuggestions
+};