saturndocs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SaturnDocs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auth-FRCFGNYT.js

@@ -0,0 +1,14 @@
+import {
+  AUTH_METADATA,
+  authStatusOf,
+  registerAuth
+} from "./chunk-3P2OFTXR.js";
+import "./chunk-TKISMN3P.js";
+import "./chunk-KGJESHJC.js";
+import "./chunk-M2BZEDAS.js";
+import "./chunk-GYRVGWDM.js";
+export {
+  AUTH_METADATA,
+  authStatusOf,
+  registerAuth
+};

package/dist/brokenLinks-TTOBP4P7.js

@@ -0,0 +1,48 @@
+import {
+  scanBrokenLinks
+} from "./chunk-OEAEX5YW.js";
+import {
+  findWebDir
+} from "./chunk-VXEUNRVA.js";
+import {
+  messageOf,
+  resolveDocsDir
+} from "./chunk-VNYDYHXM.js";
+
+// src/commands/brokenLinks.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import pc from "picocolors";
+function registerBrokenLinks(program, cliDir) {
+  program.command("broken-links").description("Scan the built site for broken internal links").argument("[dir]", "docs directory (contains docs.json)").action(async (dir) => {
+    resolveDocsDir(dir);
+    let webDir;
+    try {
+      webDir = findWebDir(cliDir);
+    } catch (error) {
+      console.error(pc.red(`error: ${messageOf(error)}`));
+      process.exit(1);
+    }
+    let distDir = join(webDir, "dist");
+    if (!existsSync(distDir)) {
+      console.error(
+        pc.red(`error: ${distDir} does not exist. Run "saturndocs build" first.`)
+      );
+      process.exit(1);
+    }
+    const clientDir = join(distDir, "client");
+    if (existsSync(clientDir)) distDir = clientDir;
+    const misses = await scanBrokenLinks(distDir);
+    if (misses.length > 0) {
+      console.error(pc.red(`\u2716 ${misses.length} broken internal link(s):`));
+      for (const miss of misses) {
+        console.error(pc.red(`  ${miss.source} -> ${miss.href}`));
+      }
+      process.exit(1);
+    }
+    console.log(pc.green(`\u2713 no broken internal links in ${distDir}.`));
+  });
+}
+export {
+  registerBrokenLinks
+};

package/dist/build-F5PWGP57.js

@@ -0,0 +1,39 @@
+import {
+  findWebDir
+} from "./chunk-VXEUNRVA.js";
+import {
+  messageOf,
+  resolveDocsDir
+} from "./chunk-VNYDYHXM.js";
+
+// src/commands/build.ts
+import { execa } from "execa";
+import pc from "picocolors";
+function registerBuild(program, cliDir) {
+  program.command("build").description("Build the static site for a docs directory").argument("[dir]", "docs directory (contains docs.json)").action(async (dir) => {
+    const docsDir = resolveDocsDir(dir);
+    let webDir;
+    try {
+      webDir = findWebDir(cliDir);
+    } catch (error) {
+      console.error(pc.red(`error: ${messageOf(error)}`));
+      process.exit(1);
+    }
+    console.log(pc.dim(`saturndocs build: astro build in ${webDir}`));
+    try {
+      await execa("astro", ["build"], {
+        cwd: webDir,
+        preferLocal: true,
+        localDir: webDir,
+        stdio: "inherit",
+        env: { SATURNDOCS_DOCS_DIR: docsDir }
+      });
+    } catch (error) {
+      console.error(pc.red(`astro build failed: ${messageOf(error)}`));
+      process.exit(1);
+    }
+  });
+}
+export {
+  registerBuild
+};

package/dist/chunk-3P2OFTXR.js

@@ -0,0 +1,71 @@
+import {
+  asCliError,
+  clientFor
+} from "./chunk-TKISMN3P.js";
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  commandMetadata,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  listSites,
+  resolveGlobalOptions,
+  successResult
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/auth.ts
+var AUTH_METADATA = Object.freeze([
+  commandMetadata("auth status", {
+    description: "Read GET /v1/sites with the credential in SATURNDOCS_MANAGEMENT_TOKEN and report the site it resolves to. One read succeeding proves read access and nothing else: the server never returns the credential's scopes, so this command does not list them.",
+    target: { arguments: [] },
+    effect: "Nothing. One read of the site listing.",
+    output: { fields: ["current", "sites", "read_verified"], ids: [], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs auth status", description: "Check that the credential in the environment can read, and see which site it acts on." },
+      { command: "saturndocs auth status --json --no-input", description: "The same check as one result object, for an agent." }
+    ]
+  })
+]);
+function authStatusOf(discovery) {
+  return { current: discovery.current, sites: discovery.sites, read_verified: true };
+}
+function statusText(status) {
+  const others = status.sites.map((site) => site.site_id).filter((id) => id !== status.current);
+  const reach = others.length === 0 ? "" : `
+Also reached: ${others.join(", ")}.`;
+  return [
+    `Read access verified: GET /v1/sites answered.`,
+    `This credential acts on ${status.current}.${reach}`,
+    "The server does not report a credential's permissions, so nothing here says whether this one may write or approve."
+  ].join("\n");
+}
+function registerAuth(program, _cliDir, environment = {}) {
+  const auth = program.command("auth").description("Check the management credential in the environment");
+  const status = auth.command("status").action(async (_options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "auth status", siteId: null };
+    try {
+      const client = clientFor(globals, environment);
+      const discovery = await listSites(client);
+      const data = authStatusOf(discovery);
+      context.siteId = data.current;
+      if (globals.site !== null && globals.site !== data.current && !data.sites.some((site) => site.site_id === globals.site)) {
+        throw invalidInput(`This credential acts on ${data.current}, not ${globals.site}.`);
+      }
+      process.exitCode = writer.write(successResult(context, data), { text: statusText(data) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(status, AUTH_METADATA[0]);
+}
+
+export {
+  AUTH_METADATA,
+  authStatusOf,
+  registerAuth
+};

package/dist/chunk-3V753MRI.js

@@ -0,0 +1,100 @@
+import {
+  asCliError,
+  clientFor
+} from "./chunk-TKISMN3P.js";
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  CliError,
+  commandMetadata,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  readSiteStatus,
+  resolveGlobalOptions,
+  resolveTarget,
+  statusBlocker,
+  statusIds,
+  statusLimitations,
+  statusRecovery,
+  statusSections,
+  successResult
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/status.ts
+var STATUS_METADATA = Object.freeze([
+  commandMetadata("status", {
+    description: "A bounded briefing on one site, composed from the reads that already exist: the site itself, one page of conversations, one page of the pending suggestion tab, and one page of activity. There is no status route on the server and nothing here pages on your behalf. Each section reports available, empty, or unavailable on its own, so a route that answered 503 leaves the other sections' data and identities untouched instead of blanking them. Every number comes from a field the server sent \u2014 the request failed and waiting tallies and the suggestion counts \u2014 and never from the length of a page. A credential the server refuses fails the command rather than being reported as a quiet site.",
+    target: { arguments: [] },
+    effect: "Nothing. Four independent reads of one site.",
+    output: {
+      fields: ["site", "requests", "suggestions", "activity", "counts", "attention"],
+      ids: ["thread_id", "job_id", "attempt"],
+      limitations: ["section_unavailable", "page_bounded"]
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs status --site acme", description: "The briefing as lines of text, one per section." },
+      { command: "saturndocs status --site acme --json", description: "The same briefing as one result object, with each section's state and server error." }
+    ]
+  })
+]);
+function sectionLine(part) {
+  if (part.state === "unavailable") {
+    return `${part.section}: unavailable \u2014 ${part.error?.message ?? "the read failed and said nothing."} ${part.recovery?.command ?? ""}`.trimEnd();
+  }
+  return `${part.section}: ${part.state}`;
+}
+function countLine(status) {
+  const counts = status.counts;
+  const parts = [];
+  if (counts.requests_failed !== null) parts.push(`${counts.requests_failed} failed request(s)`);
+  if (counts.requests_waiting !== null) parts.push(`${counts.requests_waiting} conversation(s) waiting`);
+  if (counts.suggestions !== null) parts.push(`${counts.suggestions.pending} pending suggestion(s)`);
+  return parts.length === 0 ? "counts: none supplied by the server. What is listed above is one page, not a total." : `counts: ${parts.join(", ")}`;
+}
+function statusText(status) {
+  const lines = [`site: ${status.site_id}`, ...statusSections(status).map(sectionLine), countLine(status)];
+  for (const item of status.attention) {
+    lines.push(`${item.summary} ${item.recovery.command ?? ""}`.trimEnd());
+  }
+  return lines.join("\n");
+}
+function namedSite(site) {
+  if (site === null || site.trim() === "") {
+    throw invalidInput("status reads one site, so it needs --site <site-id>. Run saturndocs sites list to see the site this credential reaches.");
+  }
+  return site;
+}
+function registerStatus(program, _cliDir, environment = {}) {
+  const command = program.command("status").action(async (_options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "status", siteId: globals.site };
+    try {
+      const site = namedSite(globals.site);
+      const client = clientFor(globals, environment);
+      const target = await resolveTarget(client, { site });
+      context.siteId = target.site_id;
+      const status = await readSiteStatus(client, target.site_id);
+      context.limitations = statusLimitations(status);
+      context.ids = statusIds(status);
+      context.recovery = statusRecovery(status);
+      const blocker = statusBlocker(status);
+      if (blocker !== null) {
+        throw new CliError(blocker.code, blocker.message, { server: blocker.server, data: status });
+      }
+      process.exitCode = writer.write(successResult(context, status), { text: statusText(status) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(command, STATUS_METADATA[0]);
+}
+
+export {
+  STATUS_METADATA,
+  statusText,
+  registerStatus
+};

package/dist/chunk-5KX4ZK5E.js

@@ -0,0 +1,104 @@
+import {
+  COMMAND_GROUPS
+} from "./chunk-QLFODLVN.js";
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  CLIENT_ERROR_CATEGORIES,
+  CLIENT_ERROR_CODES,
+  CLIENT_SCHEMA_VERSION,
+  COMMAND_SCHEMA_VERSION,
+  EXIT,
+  EXIT_MEANINGS,
+  GLOBAL_FLAGS,
+  commandMetadata,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  resolveGlobalOptions,
+  selectorFor,
+  successResult
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/schema.ts
+var SCHEMA_METADATA = Object.freeze([
+  commandMetadata("schema", {
+    description: "Print this CLI's own command metadata. With no selector it lists the registered groups and the versions, exit codes, and error codes every command shares; with a selector it prints that one command's target rules, permissions, text sources, flags, output, and examples.",
+    target: { arguments: [{ name: "selector", required: false, description: "A group or a command, spoken with dots: requests, or requests.create." }] },
+    effect: "Nothing. The document is built in this process from the command registry.",
+    output: {
+      fields: ["schema_version", "result_schema_version", "groups", "global_flags", "exits", "errors", "group", "commands", "command"],
+      ids: [],
+      limitations: []
+    },
+    errors: ["invalid_input", "interrupted"],
+    examples: [
+      { command: "saturndocs schema", description: "Every registered group and the shared contract." },
+      { command: "saturndocs schema requests.create", description: "One command's full metadata." },
+      { command: "saturndocs schema --json", description: "The same document inside the result envelope every command writes." }
+    ]
+  })
+]);
+async function metadataOf(group) {
+  return group.metadata === void 0 ? [] : await group.metadata();
+}
+function sharedContract() {
+  return {
+    schema_version: COMMAND_SCHEMA_VERSION,
+    result_schema_version: CLIENT_SCHEMA_VERSION,
+    global_flags: GLOBAL_FLAGS,
+    exits: Object.entries(EXIT).map(([name, code]) => ({ name, code, meaning: EXIT_MEANINGS[name] })),
+    errors: CLIENT_ERROR_CODES.map((code) => ({ code, ...CLIENT_ERROR_CATEGORIES[code] }))
+  };
+}
+async function rootDocument(groups) {
+  const listed = await Promise.all(
+    groups.map(async (group) => ({
+      name: group.name,
+      summary: group.summary,
+      commands: (await metadataOf(group)).map((entry) => entry.selector)
+    }))
+  );
+  return { ...sharedContract(), groups: listed };
+}
+function unknownSelector(selector, known) {
+  throw invalidInput(
+    `saturndocs schema does not know ${selector}. Run saturndocs schema for the list. Known here: ${known.join(", ")}.`
+  );
+}
+async function schemaDocument(selector, groups = COMMAND_GROUPS) {
+  if (selector === null || selector === "") return rootDocument(groups);
+  const normalized = selectorFor(selector.trim());
+  const groupName = normalized.split(".")[0];
+  const group = groups.find((candidate) => candidate.name === groupName);
+  if (group === void 0) unknownSelector(normalized, groups.map((candidate) => candidate.name));
+  const commands = await metadataOf(group);
+  const command = commands.find((entry) => entry.selector === normalized);
+  if (command !== void 0) return { ...sharedContract(), command };
+  if (normalized === groupName && commands.length > 0) {
+    return { ...sharedContract(), group: group.name, summary: group.summary, commands };
+  }
+  unknownSelector(normalized, commands.length === 0 ? groups.filter((candidate) => candidate.metadata !== void 0).map((candidate) => candidate.name) : commands.map((entry) => entry.selector));
+}
+function registerSchema(program) {
+  const metadata = SCHEMA_METADATA[0];
+  const command = program.command("schema").argument("[selector]", "A group or a command, spoken with dots: requests.create.").action(async (selector, _options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "schema", siteId: null };
+    try {
+      const document = await schemaDocument(selector ?? null);
+      process.exitCode = writer.write(successResult(context, document), { text: JSON.stringify(document, null, 2) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(error, context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+}
+
+export {
+  SCHEMA_METADATA,
+  schemaDocument,
+  registerSchema
+};

package/dist/chunk-CMNX5DLQ.js

@@ -0,0 +1,119 @@
+import {
+  asCliError,
+  clientFor
+} from "./chunk-TKISMN3P.js";
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  commandMetadata,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  listSites,
+  readSiteDetail,
+  resolveGlobalOptions,
+  resolveTarget,
+  successResult
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/sites.ts
+var SITES_METADATA = Object.freeze([
+  commandMetadata("sites list", {
+    description: "List the sites GET /v1/sites returns for the credential in SATURNDOCS_MANAGEMENT_TOKEN. A management credential is bound to one site, so this is that site and not an account-wide listing; primary_host is null on that answer and is reported as null.",
+    target: { arguments: [] },
+    effect: "Nothing. One read of the site listing.",
+    output: { fields: ["current", "sites"], ids: [], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs sites list", description: "The sites this credential reaches." },
+      { command: "saturndocs sites list --json", description: "The same listing as one result object." }
+    ]
+  }),
+  commandMetadata("sites get", {
+    description: "Read one site: its hostnames, the release readers are seeing, its reader status, its latest job, and the usage meters the server records. With --connections it also reads the documentation repository and the watched product repositories. Whatever the server leaves out is reported as absent rather than filled in.",
+    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 site, and two more when --connections is given.",
+    output: {
+      fields: ["site_id", "site.hostnames", "site.active_release", "site.reader_status", "site.latest_job", "site.usage", "connections.docs_repo", "connections.product_connections"],
+      ids: ["release_id"],
+      limitations: []
+    },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs sites get", description: "The site the credential resolves to." },
+      { command: "saturndocs sites get acme --connections", description: "One site with its documentation repository and watched repositories." },
+      { command: "saturndocs sites get --json", description: "The site read as one result object, with the resolved site_id in the envelope." }
+    ]
+  })
+]);
+function requestedSite(positional, flag) {
+  const named = positional ?? flag ?? void 0;
+  if (positional !== void 0 && flag !== null && positional !== flag) {
+    throw invalidInput(`This command was given two sites: ${positional} and --site ${flag}. Name one.`);
+  }
+  return named;
+}
+function listText(discovery) {
+  const lines = discovery.sites.map((site) => `${site.site_id}${site.site_id === discovery.current ? " (current)" : ""}  ${site.primary_host ?? "no primary host returned"}`);
+  return [...lines, "A management credential reaches only its own site, so this is not a full account listing."].join("\n");
+}
+function detailText(detail) {
+  const site = detail.site;
+  const release = site.active_release;
+  const lines = [
+    `site: ${detail.site_id}`,
+    `hostnames: ${site.hostnames.length === 0 ? "none returned" : site.hostnames.join(", ")}`,
+    `reader status: ${site.reader_status ?? "not reported"}`,
+    release === null ? "active release: none" : `active release: ${release.release_id} (${release.state}), activated ${release.activated_at ?? "at an unrecorded time"}`,
+    site.latest_job === null ? "latest job: none" : `latest job: ${site.latest_job.state}${site.latest_job.error_code === null ? "" : ` (${site.latest_job.error_code})`}`,
+    `usage: ${site.usage === void 0 || Object.keys(site.usage).length === 0 ? "nothing measured" : Object.entries(site.usage).map(([name, meter]) => `${name} ${JSON.stringify(meter)}`).join("; ")}`
+  ];
+  if (detail.connections !== null) {
+    const docs = detail.connections.docs_repo;
+    lines.push(
+      docs.docs_repo === null ? "docs repo: not connected" : `docs repo: ${docs.docs_repo.repository ?? "repository name not recorded"} (${docs.docs_repo.state}), ${docs.pages_count === null ? "page count unavailable" : `${docs.pages_count} pages`}`,
+      `watched repositories: ${detail.connections.product_connections.product_connections.length}`
+    );
+  }
+  return lines.join("\n");
+}
+function registerSites(program, _cliDir, environment = {}) {
+  const sites = program.command("sites").description("Discover and inspect the sites this credential reaches");
+  const list = sites.command("list").action(async (_options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "sites list", siteId: null };
+    try {
+      const discovery = await listSites(clientFor(globals, environment));
+      context.siteId = discovery.current;
+      process.exitCode = writer.write(successResult(context, discovery), { text: listText(discovery) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(list, SITES_METADATA[0]);
+  const get = sites.command("get").argument("[site-id]", "The site to read. Defaults to the site the credential resolves to.").action(async (siteId, options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const context = { command: "sites get", 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 detail = await readSiteDetail(client, target.site_id, { connections: options.connections === true });
+      if (detail.site.active_release !== null) context.ids = { release_id: detail.site.active_release.release_id };
+      process.exitCode = writer.write(successResult(context, detail), { text: detailText(detail) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(asCliError(error), context));
+    }
+  });
+  applyCommandHelp(get, SITES_METADATA[1]);
+}
+
+export {
+  SITES_METADATA,
+  requestedSite,
+  registerSites
+};