saturndocs 0.1.0

package/dist/chunk-U7PKMSB3.js

@@ -0,0 +1,465 @@
+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_REQUEST_WAIT_MS,
+  REQUEST_TEXT_LIMIT,
+  checkedRequestText,
+  checkedSubmissionId,
+  commandMetadata,
+  createRequest,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  listRequestThreads,
+  readRequestThread,
+  replyToRequest,
+  requestWaitErrorCode,
+  resolveGlobalOptions,
+  resolveTarget,
+  retryRequest,
+  successResult,
+  waitForRequest
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/requests/create.ts
+var REQUESTS_CREATE_METADATA = Object.freeze([
+  commandMetadata("requests create", {
+    description: "Submit one documentation request and return the queued job it opened, without waiting for the draft. The job that comes back is the root of the conversation, so it is the id every later read, answer, and retry names. --submission-id is a UUID you mint and keep: replaying it with the same words recovers that same job in a fresh process, and sending different words under it is refused as a conflict rather than replacing what is already running.",
+    target: { arguments: [] },
+    effect: "Queues one documentation request on the named site. Nothing is published.",
+    idempotency: "submission_id",
+    output: { fields: ["job_id", "state"], ids: ["submission_id", "thread_id", "job_id"], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "interrupted"],
+    examples: [
+      { command: 'saturndocs requests create --site acme --submission-id 5f80c9a2-012b-4dee-8de4-97d44cd28b60 --text "Document the export option" --page pages/export.mdx', description: "One short request about one page." },
+      { command: "saturndocs requests create --site acme --submission-id 5f80c9a2-012b-4dee-8de4-97d44cd28b60 --file request.md", description: "The request read from a file, which is also how a lost answer is replayed." },
+      { command: "saturndocs requests create --site acme --submission-id 5f80c9a2-012b-4dee-8de4-97d44cd28b60 --file - --json", description: "The request read from stdin, as one result object." }
+    ]
+  })
+]);
+function quoted(value) {
+  return /^[\w.\-/@]+$/u.test(value) ? value : JSON.stringify(value);
+}
+function recoveryFor(siteId, flags, submissionId) {
+  const stdin = flags.file === "-";
+  const source = flags.file === void 0 || stdin ? null : `--file ${quoted(flags.file)}`;
+  const line = source === null ? null : ["saturndocs requests create", `--site ${quoted(siteId)}`, `--submission-id ${submissionId}`, flags.page === void 0 ? null : `--page ${quoted(flags.page)}`, source].filter((part) => part !== null).join(" ");
+  const replaySource = stdin ? "the same text on stdin" : source === null ? "the same --text" : `the same ${source}`;
+  return {
+    command: line,
+    replay: { submission_id: submissionId, stdin },
+    message: `It is not known whether the request was queued. Nothing was sent again. Read the conversations on ${siteId}, or send it once more with --submission-id ${submissionId}, ${replaySource}${flags.page === void 0 ? "" : ` and --page ${flags.page}`}: the same id with the same words recovers the one job, and with different words it is refused.`
+  };
+}
+function registerRequestsCreate(group, environment = {}) {
+  const metadata = REQUESTS_CREATE_METADATA[0];
+  const command = group.command("create").action(async (_options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const flags = self.opts();
+    const context = { command: "requests create", siteId: globals.site };
+    let recovery = null;
+    try {
+      const submissionId = checkedSubmissionId(flags.submissionId ?? "");
+      const text = await readTextInput(flags, {
+        command: "requests create",
+        requirement: metadata.text.requirement,
+        limit: metadata.text.limit ?? REQUEST_TEXT_LIMIT,
+        interactive: globals.input,
+        stdin: environment.stdin,
+        readFileImpl: environment.readFileImpl
+      });
+      const request = checkedRequestText(text ?? "");
+      const client = clientFor(globals, environment);
+      const target = await resolveTarget(client, { site: globals.site ?? void 0, mutation: true });
+      context.siteId = target.site_id;
+      recovery = recoveryFor(target.site_id, flags, submissionId);
+      const queued = await createRequest(client, {
+        siteId: target.site_id,
+        submissionId,
+        request,
+        page: flags.page ?? null
+      });
+      const resolved = {
+        ...context,
+        ids: { submission_id: submissionId, thread_id: queued.job_id, job_id: queued.job_id }
+      };
+      process.exitCode = writer.write(successResult(resolved, queued), {
+        text: `${queued.job_id} ${queued.state}; thread ${queued.job_id}`
+      });
+    } catch (error) {
+      const failure = asCliError(error);
+      if (failure instanceof CliError && failure.mutation === "unknown" && recovery !== null) context.recovery = recovery;
+      process.exitCode = writer.write(failureResult(failure, context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+
+// src/commands/requests/read.ts
+var REQUESTS_READ_METADATA = Object.freeze([
+  commandMetadata("requests list", {
+    description: "One page of conversations, newest original request first. The listing is always read as threads, so each entry carries the request that started it, the newest job and its state, whether it is waiting on an answer, and the most recent turns. Paging is the server's: one page per invocation, and next_cursor is the only way to the next one.",
+    target: { arguments: [] },
+    effect: "Nothing. This reads one page.",
+    output: {
+      fields: ["threads", "page_cursor", "next_cursor", "has_newer", "failed", "waiting"],
+      ids: [],
+      limitations: ["page_bounded"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs requests list --site acme", description: "The newest page of conversations." },
+      { command: "saturndocs requests list --site acme --limit 50 --json", description: "A larger page as one result object." },
+      { command: "saturndocs requests list --site acme --cursor eyJ...", description: "The page after the one whose next_cursor is given." }
+    ]
+  }),
+  commandMetadata("requests get", {
+    description: "One conversation bounded to its newest 100 turns: the request that started it, its latest job, whether it is waiting on an answer, and the returned turns oldest first. The server supplies no total or cursor, so older turns may not be present. Any job of the thread names it, so a reply's job id reads the same conversation as its root. A thread whose latest job failed is a successful read; the failure is in the result, not in the exit code.",
+    target: { arguments: [{ name: "job", required: true, description: "Any job of the conversation, including a reply." }] },
+    effect: "Nothing. This reads one conversation.",
+    output: {
+      fields: ["root", "thread_id", "site_id", "open", "latest_job", "entries"],
+      ids: ["thread_id", "job_id", "attempt", "suggestion_id"],
+      limitations: ["page_bounded"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs requests get job-2f1c --site acme", description: "The newest 100 turns behind one request." },
+      { command: "saturndocs requests get job-reply-9 --json", description: "A reply's job id, which resolves to its root thread." }
+    ]
+  })
+]);
+async function prepare(globals, environment) {
+  const client = clientFor(globals, environment);
+  const target = await resolveTarget(client, globals.site === null ? {} : { site: globals.site });
+  return { client, siteId: target.site_id };
+}
+function integerFlag(value, name) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw invalidInput(`${name} takes a whole number.`);
+  return parsed;
+}
+function registerList(group, environment) {
+  const metadata = REQUESTS_READ_METADATA[0];
+  const command = group.command("list").action(async (_options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "requests list", siteId: null };
+    try {
+      const flags = self.opts();
+      const limit = integerFlag(flags.limit, "--limit");
+      const run = await prepare(globals, environment);
+      context.siteId = run.siteId;
+      const page = await listRequestThreads(run.client, {
+        siteId: run.siteId,
+        cursor: flags.cursor,
+        limit
+      });
+      const bounded = {
+        ...context,
+        siteId: run.siteId,
+        limitations: [{
+          code: "page_bounded",
+          message: page.next_cursor === null ? "One page was read. The server reported no page after it." : "One page was read. Pass its next_cursor to read the page after it.",
+          at: "threads"
+        }]
+      };
+      process.exitCode = writer.write(successResult(bounded, page), {
+        text: `${page.threads.length} conversation(s)${page.next_cursor === null ? "" : "; more follow"}`
+      });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+function idsOf(thread) {
+  const ids = {
+    thread_id: thread.thread_id,
+    job_id: thread.latest_job.job_id,
+    attempt: thread.latest_job.attempt
+  };
+  if (thread.latest_job.suggestion_id !== null) ids.suggestion_id = thread.latest_job.suggestion_id;
+  if (thread.latest_job.pr_number !== null) ids.pr_number = thread.latest_job.pr_number;
+  return ids;
+}
+function registerGet(group, environment) {
+  const metadata = REQUESTS_READ_METADATA[1];
+  const command = group.command("get").argument("<job>", "Any job of the conversation, including a reply.").action(async (job, _options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "requests get", siteId: null };
+    try {
+      const run = await prepare(globals, environment);
+      context.siteId = run.siteId;
+      const thread = await readRequestThread(run.client, {
+        siteId: run.siteId,
+        jobId: job
+      });
+      context.siteId = thread.site_id;
+      context.ids = idsOf(thread);
+      context.limitations = [{
+        code: "page_bounded",
+        message: "The server bounds this read to the newest 100 entries and supplies no total or cursor, so older entries may not be present.",
+        at: "entries"
+      }];
+      process.exitCode = writer.write(successResult(context, thread), {
+        text: `${thread.thread_id}: ${thread.latest_job.state}, ${thread.entries.length} turn(s)${thread.open ? ", waiting on an answer" : ""}`
+      });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+function registerRequestsRead(group, environment = {}) {
+  registerList(group, environment);
+  registerGet(group, environment);
+}
+
+// src/commands/requests/reply.ts
+var REQUESTS_REPLY_METADATA = Object.freeze([
+  commandMetadata("requests reply", {
+    description: "Answer a clarification on a conversation that is waiting on one. The conversation is named by any of its jobs, as the positional argument or as --thread, and the root it resolves to is the thread the answer joins; the answer opens a new job of its own and the root thread id does not change. The page and the reader evidence the original request carried are the conversation's, so this command never sends them again and never replaces them. --submission-id is a UUID you mint and keep: replaying it with the same words recovers the job the answer already opened, even once the conversation has stopped waiting.",
+    target: { arguments: [{ name: "job", required: false, description: "Any job of the conversation to answer, including a reply. --thread takes the same value." }] },
+    effect: "Adds one answer to an existing conversation on the named site and queues the job it opens. Nothing is published.",
+    idempotency: "submission_id",
+    output: { fields: ["job_id", "state"], ids: ["submission_id", "thread_id", "job_id"], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "interrupted"],
+    examples: [
+      { command: 'saturndocs requests reply job-2f1c --site acme --submission-id 6f80c9a2-012b-4dee-8de4-97d44cd28b60 --text "Use the public option name"', description: "One answer to the question the conversation is waiting on." },
+      { command: "saturndocs requests reply --thread job-2f1c --site acme --submission-id 6f80c9a2-012b-4dee-8de4-97d44cd28b60 --file answer.md", description: "The same, with the conversation named by the contract's own flag and the answer read from a file." },
+      { command: "saturndocs requests reply job-reply-9 --site acme --submission-id 6f80c9a2-012b-4dee-8de4-97d44cd28b60 --file - --json", description: "A reply's job id, which resolves to its root, with the answer on stdin." }
+    ]
+  })
+]);
+function quoted2(value) {
+  return /^[\w.\-/@]+$/u.test(value) ? value : JSON.stringify(value);
+}
+function recoveryFor2(siteId, job, flags, submissionId) {
+  const stdin = flags.file === "-";
+  const source = flags.file === void 0 || stdin ? null : `--file ${quoted2(flags.file)}`;
+  const line = source === null ? null : ["saturndocs requests reply", quoted2(job), `--site ${quoted2(siteId)}`, `--submission-id ${submissionId}`, source].join(" ");
+  const replaySource = stdin ? "the same text on stdin" : source === null ? "the same --text" : `the same ${source}`;
+  return {
+    command: line,
+    replay: { submission_id: submissionId, stdin },
+    message: `It is not known whether the answer was added to ${job}. Nothing was sent again. Read the conversation with saturndocs requests get ${job}, or send it once more with --submission-id ${submissionId} and ${replaySource}: the same id with the same words recovers the one job even after the conversation stops waiting, and with different words it is refused.`
+  };
+}
+function threadArgument(job, flags) {
+  const named = job ?? flags.thread;
+  if (named === void 0 || named.trim() === "") {
+    throw invalidInput("requests reply needs the conversation to answer. Pass the job as the argument, or --thread <job>.");
+  }
+  if (job !== void 0 && flags.thread !== void 0 && job !== flags.thread) {
+    throw invalidInput(`requests reply was given two conversations, ${job} and --thread ${flags.thread}. Name one.`);
+  }
+  return named;
+}
+function registerRequestsReply(group, environment = {}) {
+  const metadata = REQUESTS_REPLY_METADATA[0];
+  const command = group.command("reply").argument("[job]", "Any job of the conversation to answer, including a reply.").option("--thread <thread>", "The conversation to answer, when it is not given as the argument.").action(async (job, _options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const flags = self.opts();
+    const context = { command: "requests reply", siteId: globals.site };
+    let recovery = null;
+    try {
+      const named = threadArgument(job, flags);
+      const submissionId = checkedSubmissionId(flags.submissionId ?? "");
+      const text = await readTextInput(flags, {
+        command: "requests reply",
+        requirement: metadata.text.requirement,
+        limit: metadata.text.limit ?? REQUEST_TEXT_LIMIT,
+        interactive: globals.input,
+        stdin: environment.stdin,
+        readFileImpl: environment.readFileImpl
+      });
+      const request = checkedRequestText(text ?? "");
+      const client = clientFor(globals, environment);
+      const target = await resolveTarget(client, { site: globals.site ?? void 0, mutation: true });
+      context.siteId = target.site_id;
+      recovery = recoveryFor2(target.site_id, named, flags, submissionId);
+      const reply = await replyToRequest(client, {
+        siteId: target.site_id,
+        jobId: named,
+        submissionId,
+        request
+      });
+      const resolved = {
+        ...context,
+        ids: { submission_id: submissionId, thread_id: reply.threadId, job_id: reply.queued.job_id }
+      };
+      process.exitCode = writer.write(successResult(resolved, reply.queued), {
+        text: `${reply.queued.job_id} ${reply.queued.state}; thread ${reply.threadId}`
+      });
+    } catch (error) {
+      const failure = asCliError(error);
+      if (failure instanceof CliError && failure.mutation === "unknown" && recovery !== null) context.recovery = recovery;
+      process.exitCode = writer.write(failureResult(failure, context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+
+// src/commands/requests/retry.ts
+var REQUESTS_RETRY_METADATA = Object.freeze([
+  commandMetadata("requests retry", {
+    description: "Send one failed request again. The job keeps its own id and the conversation keeps its history, so the attempt is the only thing telling the new run from the one that failed. The attempt the server returns is reported as it is, including the null it sends when the operations Worker named none: nothing here fills one in. A job that is not failed is the server's own refusal, with its sentence saying which state it is in, on exit 4.",
+    target: { arguments: [{ name: "job", required: true, description: "The failed job to send again." }] },
+    effect: "Queues one more run of a failed request on the named site. Nothing is published.",
+    output: { fields: ["job_id", "state", "attempt"], ids: ["job_id", "attempt"], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "service_unavailable", "transport_failure", "unknown_outcome", "interrupted"],
+    examples: [
+      { command: "saturndocs requests retry job-2f1c --site acme", description: "Send a failed request through the agent again." },
+      { command: "saturndocs requests retry job-2f1c --site acme --json", description: "The same, as one result object carrying the returned attempt." }
+    ]
+  })
+]);
+function registerRequestsRetry(group, environment = {}) {
+  const metadata = REQUESTS_RETRY_METADATA[0];
+  const command = group.command("retry").argument("<job>", "The failed job to send again.").action(async (job, _options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "requests retry", siteId: globals.site };
+    try {
+      const client = clientFor(globals, environment);
+      const target = await resolveTarget(client, { site: globals.site ?? void 0, mutation: true });
+      context.siteId = target.site_id;
+      const retried = await retryRequest(client, { siteId: target.site_id, jobId: job });
+      const resolved = { ...context, ids: { job_id: retried.job_id, attempt: retried.attempt } };
+      process.exitCode = writer.write(successResult(resolved, retried), {
+        text: `${retried.job_id} ${retried.state}; attempt ${retried.attempt === null ? "unknown" : retried.attempt}`
+      });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+
+// src/commands/requests/wait.ts
+var REQUESTS_WAIT_METADATA = Object.freeze([
+  commandMetadata("requests wait", {
+    description: "Follow one conversation until its latest job says what came of it: a draft with the suggestion it produced, a clarification question, a conclusion that nothing needed changing, a failure, or a cancellation. Only the latest job's current attempt counts, so a retry is never reported as the failure the previous attempt wrote. A job that ends without writing any turn is reported as an outcome that could not be read, never as a guess. The deadline covers the waiting and the reads in flight alike; reaching it exits 6 with the last state that was verified and the command to resume with, and the remote job keeps running. Interrupting cancels nothing remote.",
+    target: { arguments: [{ name: "job", required: true, description: "Any job of the conversation to follow." }] },
+    effect: "Nothing. This reads one conversation until it concludes or the deadline passes.",
+    output: {
+      fields: ["outcome", "state", "job_id", "attempt", "suggestion_id", "thread", "polls", "elapsed_ms"],
+      ids: ["thread_id", "job_id", "attempt", "suggestion_id"],
+      limitations: []
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "remote_failure", "wait_timeout", "interrupted"],
+    examples: [
+      { command: "saturndocs requests wait job-2f1c --site acme", description: "Follow a request to its draft, its question, or its failure." },
+      { command: "saturndocs requests wait job-2f1c --site acme --timeout 300 --json", description: "The same, bounded to five minutes, as one result object." }
+    ]
+  })
+]);
+function idsOf2(result) {
+  const ids = { attempt: result.attempt };
+  if (result.thread !== null) ids.thread_id = result.thread.thread_id;
+  if (result.job_id !== null) ids.job_id = result.job_id;
+  if (result.suggestion_id !== null) ids.suggestion_id = result.suggestion_id;
+  return ids;
+}
+function resumeCommand(verb, result, job, siteId) {
+  return `saturndocs requests ${verb} ${result.job_id ?? job} --site ${siteId}`;
+}
+function recoveryFor3(result, job, siteId) {
+  const state = result.state ?? "unknown";
+  if (result.outcome === "timed_out") {
+    return {
+      command: resumeCommand("wait", result, job, siteId),
+      replay: null,
+      message: `The job was ${state} on ${siteId} when the deadline passed. It is still running; this resumes the wait.`
+    };
+  }
+  if (result.outcome === "failed") {
+    return { command: resumeCommand("retry", result, job, siteId), replay: null, message: `The job failed on ${siteId}. This sends it again under the same job id.` };
+  }
+  if (result.outcome === "cancelled" || result.outcome === "outcome_unknown") {
+    return { command: resumeCommand("get", result, job, siteId), replay: null, message: `Read the conversation on ${siteId} before asking again; it was ${state} and carried no result to act on.` };
+  }
+  if (result.outcome === "question" && result.thread !== null) {
+    return {
+      command: `saturndocs requests reply --thread ${result.thread.thread_id} --site ${siteId}`,
+      replay: null,
+      message: "Answering is a reply on the root thread, not a new request."
+    };
+  }
+  return null;
+}
+function textFor(result) {
+  const job = result.job_id ?? "the request";
+  const suffix = result.suggestion_id === null ? "" : ` (${result.suggestion_id})`;
+  return `${job} ${result.outcome}${suffix}: ${result.note}`;
+}
+function registerRequestsWait(group, environment = {}) {
+  const metadata = REQUESTS_WAIT_METADATA[0];
+  const command = group.command("wait").argument("<job>", "Any job of the conversation to follow.").action(async (job, _options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "requests wait", siteId: globals.site };
+    try {
+      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 waitForRequest(client, {
+        siteId: target.site_id,
+        jobId: job,
+        deadlineMs: globals.timeout === null ? DEFAULT_REQUEST_WAIT_MS : globals.timeout * 1e3,
+        signal
+      });
+      const resolved = {
+        ...context,
+        ids: idsOf2(result),
+        recovery: recoveryFor3(result, job, target.site_id)
+      };
+      const code = requestWaitErrorCode(result.outcome);
+      if (code === null) {
+        process.exitCode = writer.write(successResult(resolved, result), { text: textFor(result) });
+        return;
+      }
+      const failed = new CliError(code, textFor(result), { 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/requests/index.ts
+var REQUESTS_METADATA = Object.freeze([...REQUESTS_READ_METADATA, ...REQUESTS_CREATE_METADATA, ...REQUESTS_REPLY_METADATA, ...REQUESTS_RETRY_METADATA, ...REQUESTS_WAIT_METADATA]);
+function registerRequests(program, _cliDir, environment = {}) {
+  const group = program.command("requests").description("Documentation requests and the conversations behind them");
+  registerRequestsRead(group, environment);
+  registerRequestsCreate(group, environment);
+  registerRequestsReply(group, environment);
+  registerRequestsRetry(group, environment);
+  registerRequestsWait(group, environment);
+}
+
+export {
+  REQUESTS_CREATE_METADATA,
+  registerRequestsCreate,
+  REQUESTS_METADATA,
+  registerRequests
+};

package/dist/chunk-VNYDYHXM.js

@@ -0,0 +1,22 @@
+// src/commands/common.ts
+import { existsSync } from "fs";
+import { resolve } from "path";
+import pc from "picocolors";
+function resolveDocsDir(dir) {
+  const docsDir = resolve(dir ?? process.cwd());
+  if (!existsSync(resolve(docsDir, "docs.json"))) {
+    console.error(
+      pc.red(`error: no docs.json found in ${docsDir}. Pass a docs directory.`)
+    );
+    process.exit(1);
+  }
+  return docsDir;
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export {
+  resolveDocsDir,
+  messageOf
+};

package/dist/chunk-VXEUNRVA.js

@@ -0,0 +1,26 @@
+// src/lib/workspace.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+function findWorkspaceRoot(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    if (existsSync(join(dir, "pnpm-workspace.yaml")) && existsSync(join(dir, "apps", "web"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(
+        `Could not locate the SaturnDocs workspace root (a directory with pnpm-workspace.yaml and apps/web) at or above ${startDir}.`
+      );
+    }
+    dir = parent;
+  }
+}
+function findWebDir(startDir) {
+  return join(findWorkspaceRoot(startDir), "apps", "web");
+}
+
+export {
+  findWorkspaceRoot,
+  findWebDir
+};

package/dist/chunk-XO4CUC7V.js

@@ -0,0 +1,99 @@
+import {
+  requestedSite
+} from "./chunk-CMNX5DLQ.js";
+import {
+  asCliError,
+  clientFor
+} from "./chunk-TKISMN3P.js";
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  PAGE_TRAFFIC_WINDOWS,
+  commandMetadata,
+  createResultWriter,
+  failureResult,
+  listPages,
+  pagesUnavailable,
+  resolveGlobalOptions,
+  resolveTarget,
+  successResult
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/pages.ts
+import { InvalidArgumentError } from "commander";
+var PAGES_METADATA = Object.freeze([
+  commandMetadata("pages list", {
+    description: "Read the pages of the release readers are seeing, with where each one is read, where its source is, and how often it was read in the traffic window. A site with no live release answers unavailable: no_release and carries no page list at all, which this command reports as such rather than as a published site with nothing in it.",
+    target: { arguments: [{ name: "site-id", required: false, description: "The site to read. Defaults to the site the credential resolves to." }] },
+    effect: "Nothing. One read of the published page listing.",
+    output: { fields: ["site_id", "days", "release_id", "traffic", "pages", "unavailable"], ids: ["release_id"], limitations: ["page_bounded", "section_unavailable"] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs pages list", description: "Every published page of the live release, over the server's default window." },
+      { command: "saturndocs pages list --days 30", description: "The same list with a 30-day traffic window." },
+      { command: "saturndocs pages list --json", description: "The listing as one result object, with the resolved site_id in the envelope." }
+    ]
+  })
+]);
+function trafficWindow(value) {
+  const days = Number(value);
+  if (!PAGE_TRAFFIC_WINDOWS.includes(days)) {
+    throw new InvalidArgumentError(`The server keeps ${PAGE_TRAFFIC_WINDOWS.join(", ")} day windows and no others.`);
+  }
+  return days;
+}
+function pagesLimitations(result) {
+  if (pagesUnavailable(result)) {
+    return [{
+      code: "section_unavailable",
+      message: "This site has no live release, so there is no published page list to read. That is not a site whose published list is empty.",
+      at: "pages"
+    }];
+  }
+  if (result.traffic === "partial") {
+    return [{ code: "page_bounded", message: "The edge returned as many address counts as one answer holds, so some reads are missing from the view and agent-read figures.", at: "pages" }];
+  }
+  if (result.traffic === "not_configured" || result.traffic === "failed") {
+    return [{
+      code: "section_unavailable",
+      message: `Traffic figures are ${result.traffic}: every views and agent_reads figure below is 0 because nothing was counted, not because nobody read the page.`,
+      at: "pages"
+    }];
+  }
+  return [];
+}
+function listText(result) {
+  if (pagesUnavailable(result)) {
+    return `${result.site_id}: no live release, so there is no published page list. Publish a release before reading pages.`;
+  }
+  const head = `${result.site_id}: release ${result.release_id}, ${result.pages.length} published pages, traffic ${result.traffic} over ${result.days} days`;
+  return [head, ...result.pages.map((page) => `${page.url}  views ${page.views}  agent reads ${page.agent_reads}  ${page.path}`)].join("\n");
+}
+function registerPages(program, _cliDir, environment = {}) {
+  const pages = program.command("pages").description("Read the published pages of the release readers are seeing");
+  const list = pages.command("list").argument("[site-id]", "The site to read. Defaults to the site the credential resolves to.").option("--days <n>", `Traffic window: ${PAGE_TRAFFIC_WINDOWS.join(", ")}.`, trafficWindow).action(async (siteId, options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "pages list", siteId: null };
+    try {
+      const client = clientFor(globals, environment);
+      const named = requestedSite(siteId, globals.site);
+      const target = await resolveTarget(client, named === void 0 ? {} : { site: named });
+      context.siteId = target.site_id;
+      const result = await listPages(client, target.site_id, options.days === void 0 ? {} : { days: options.days });
+      context.limitations = pagesLimitations(result);
+      if (!pagesUnavailable(result)) context.ids = { release_id: result.release_id };
+      process.exitCode = writer.write(successResult(context, result), { text: listText(result) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(list, PAGES_METADATA[0]);
+}
+
+export {
+  PAGES_METADATA,
+  pagesLimitations,
+  registerPages
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node