saturndocs 0.1.0

package/dist/chunk-STCCGFKC.js

@@ -0,0 +1,246 @@
+import {
+  applyCommandHelp
+} from "./chunk-M2BZEDAS.js";
+import {
+  CliError,
+  commandMetadata,
+  createClient,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  isManagementError,
+  requireCommitSha,
+  resolveGlobalOptions,
+  resolveTarget,
+  successResult
+} from "./chunk-GYRVGWDM.js";
+
+// src/commands/manage.ts
+import { readFile } from "fs/promises";
+var METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var PUBLIC_READS = /* @__PURE__ */ new Set(["", "openapi.json"]);
+var SITELESS_READS = /* @__PURE__ */ new Set(["", "openapi.json", "sites"]);
+var SIDE_EFFECTING_GETS = [
+  /^suggestions\/[^/]+\/session\/ws$/u,
+  /^credentials$/u,
+  /^github\/install$/u,
+  /^slack\/install$/u
+];
+var EXACT_REVIEW_ROUTES = /^suggestions\/[^/]+\/(approve|dismiss)$/u;
+function routeOf(path) {
+  const withoutQuery = path.split("?")[0] ?? "";
+  return withoutQuery.replace(/^\//u, "").replace(/\/+$/u, "");
+}
+function validatePath(path) {
+  if (/[\u0000-\u001f\u007f]/u.test(path) || path.startsWith(" ") || path.endsWith(" ")) {
+    throw invalidInput("A management operation path may not contain control characters or surrounding spaces. Nothing was sent.");
+  }
+  const pathname = path.split("?")[0] ?? "";
+  for (const segment of pathname.split("/")) {
+    let decoded;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+      throw invalidInput("A management operation path contains an invalid escape. Nothing was sent.");
+    }
+    if (decoded === "." || decoded === "..") {
+      throw invalidInput("A management operation path may not contain relative segments. Nothing was sent.");
+    }
+  }
+}
+function plan(method, path, options, token) {
+  const verb = method.toUpperCase();
+  if (!METHODS.includes(verb)) throw invalidInput(`${method} is not a management method. Use GET, POST, PUT, PATCH, or DELETE.`);
+  if (path.startsWith("//") || path.includes("\\") || path.includes("#")) {
+    throw invalidInput("Use a relative management operation path, with no host, fragment, or backslash.");
+  }
+  validatePath(path);
+  if (options.site !== void 0 && options.site.trim() === "") throw invalidInput("--site needs a site id.");
+  const route = routeOf(path);
+  const siteListing = verb === "GET" && route === "sites" && options.site === void 0;
+  if (route.split("/").includes("sites") && !siteListing) {
+    throw invalidInput("A management operation path may not name a site. Pass the site as --site, which is the target this command verifies.");
+  }
+  const mutation = verb !== "GET" || SIDE_EFFECTING_GETS.some((pattern) => pattern.test(route));
+  if (mutation && (options.site === void 0 || options.site.trim() === "")) {
+    throw invalidInput(`${verb} ${route === "" ? "/v1" : route} acts on a site, so it needs an explicit --site. Nothing was sent.`);
+  }
+  if (!mutation && options.site === void 0 && !SITELESS_READS.has(route)) {
+    throw invalidInput(`Reading ${route} needs an explicit --site. Only the discovery reads answer without one.`);
+  }
+  const suffix = path === "" ? "" : `/${path.replace(/^\//u, "")}`;
+  const target = options.site === void 0 ? `/v1${suffix}` : `/v1/sites/${encodeURIComponent(options.site)}${suffix}`;
+  return {
+    verb,
+    path: target,
+    route,
+    mutation,
+    exactReview: EXACT_REVIEW_ROUTES.test(route),
+    anonymous: token === void 0 && verb === "GET" && options.site === void 0 && PUBLIC_READS.has(route)
+  };
+}
+async function readData(options) {
+  if (options.data === void 0) return null;
+  let raw;
+  if (options.data.startsWith("@")) {
+    const file = options.data.slice(1);
+    try {
+      raw = await readFile(file, "utf8");
+    } catch (error) {
+      throw invalidInput(`manage could not read ${file}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+  } else {
+    raw = options.data;
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw invalidInput("--data must be JSON, or @path to a file holding JSON. Nothing was sent.", { cause: error });
+  }
+  const object = value !== null && typeof value === "object" && !Array.isArray(value);
+  return { value, fields: object ? value : null };
+}
+function withReviewedHashes(fields, options, route) {
+  const base = options.base ?? fields.expected_base_sha;
+  const head = options.head ?? fields.expected_head_sha;
+  if (base === void 0 || head === void 0) {
+    throw invalidInput(`${route} publishes or closes the exact revision that was reviewed, so it needs --base and --head (or expected_base_sha and expected_head_sha in --data). Nothing was sent.`);
+  }
+  return {
+    ...fields,
+    expected_base_sha: requireCommitSha(base, "--base"),
+    expected_head_sha: requireCommitSha(head, "--head")
+  };
+}
+async function buildBody(current, options) {
+  const data = await readData(options);
+  if (data !== null && data.fields === null && current.exactReview) {
+    throw invalidInput(`${current.route} needs its reviewed hashes in a JSON object, not ${Array.isArray(data.value) ? "an array" : "a bare value"}.`);
+  }
+  const fields = current.exactReview ? withReviewedHashes(data?.fields ?? {}, options, current.route) : data?.fields ?? null;
+  if (options.file !== void 0 && options.file.length > 0) {
+    if (current.verb === "GET") throw invalidInput("A GET operation carries no file parts.");
+    if (data !== null && data.fields === null) throw invalidInput("File uploads need --data to hold a JSON object of fields.");
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields ?? {})) {
+      form.set(key, typeof value === "string" ? value : JSON.stringify(value));
+    }
+    for (const part of options.file) {
+      const separator = part.indexOf("=");
+      if (separator < 1) throw invalidInput(`Use --file field=path; ${part} names no field.`);
+      const filePath = part.slice(separator + 1);
+      let contents;
+      try {
+        contents = Uint8Array.from(await readFile(filePath));
+      } catch (error) {
+        throw invalidInput(`manage could not read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+      }
+      form.set(part.slice(0, separator), new Blob([contents]), filePath.split(/[\\/]/u).pop());
+    }
+    return { rawBody: form };
+  }
+  if (fields !== null) return { body: fields };
+  if (data === null) return {};
+  return { body: data.value };
+}
+function requireJsonMedia(headers) {
+  const media = (headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+  if (media === "" || media === "application/json" || media.endsWith("+json")) return;
+  throw new CliError("transport_failure", `The management API answered ${media}, which this command does not read. Only JSON operations are supported here.`);
+}
+function classify(error) {
+  if (isManagementError(error)) {
+    return new CliError(error.detail.code, error.detail.message, { server: error.detail.server, cause: error });
+  }
+  return error;
+}
+async function callManagement(method, path, options, token, fetchImpl = fetch) {
+  try {
+    const current = plan(method, path, options, token);
+    const body = await buildBody(current, options);
+    if (current.verb === "GET" && (body.body !== void 0 || body.rawBody !== void 0)) {
+      throw invalidInput("A GET operation carries no body. Nothing was sent.");
+    }
+    const client = createClient({
+      origin: options.api,
+      token,
+      fetchImpl,
+      ...options.timeout === void 0 ? {} : { deadlineMs: options.timeout * 1e3 }
+    });
+    if (current.mutation) await resolveTarget(client, { site: options.site, mutation: true });
+    const response = await client.request({
+      method: current.verb,
+      path: current.path,
+      ...body,
+      ...options.revision === void 0 ? {} : { revision: options.revision },
+      exactReview: current.exactReview,
+      mutation: current.mutation,
+      anonymous: current.anonymous
+    });
+    requireJsonMedia(response.headers);
+    return response.data;
+  } catch (error) {
+    throw classify(error);
+  }
+}
+var MANAGE_METADATA = Object.freeze([
+  commandMetadata("manage", {
+    description: "Send one management operation to the dashboard API and print what came back. The path, the method, and the body are the caller's; the target, precondition, and credential rules are the same as for every named command. Anything that acts \u2014 every non-GET, and the GET routes the permission table gives a write or access permission \u2014 needs an explicit --site that the credential is checked against before the call.",
+    target: {
+      arguments: [
+        { name: "method", required: true, description: "GET, POST, PUT, PATCH, or DELETE." },
+        { name: "path", required: false, description: "The operation path under the site, such as requests. It may not name a site." }
+      ]
+    },
+    effect: "Whatever the chosen operation does. A GET on a read route reads; anything else may write.",
+    idempotency: "expected_review",
+    text_sources: ["--data"],
+    output: { fields: [], ids: [], limitations: [] },
+    errors: ["invalid_input", "unauthorized", "forbidden", "not_found", "stale_review", "conflict", "rate_limited", "service_unavailable", "transport_failure", "interrupted"],
+    examples: [
+      { command: "saturndocs manage GET requests --site acme", description: "Read one site's requests through the raw operation." },
+      { command: "saturndocs manage POST requests --site acme --data @request.json --json", description: "Send a body read from a file and take the shared result envelope." },
+      { command: "saturndocs manage POST suggestions/sug-1/approve --site acme --base <sha> --head <sha>", description: "Publish exactly the reviewed revision; without both hashes nothing is sent." }
+    ]
+  })
+]);
+function registerManage(program) {
+  const metadata = MANAGE_METADATA[0];
+  const command = program.command("manage").argument("<method>", "GET, POST, PUT, PATCH, or DELETE.").argument("[path]", "The operation path under the site, such as requests.").option("--api <origin>", "Management API origin", "https://app.saturndocs.com").option("--revision <revision>", "Revision from the settings read or proposal review; required for settings writes").option("--data <json-or-@file>", "JSON request body").option("--file <field=path>", "Upload a file; repeat for multiple fields", (value, prior) => [...prior, value], []).option("--base <sha>", "The reviewed base SHA, for a raw approval or dismissal").option("--head <sha>", "The reviewed head SHA, for a raw approval or dismissal").action(async (method, path, options, self) => {
+    const globals = resolveGlobalOptions(self);
+    const writer = createResultWriter({ json: globals.json });
+    const site = globals.site ?? options.site;
+    const context = { command: "manage", siteId: site ?? null };
+    try {
+      const data = await callManagement(method, path ?? "", {
+        ...options,
+        site,
+        ...globals.api === null ? {} : { api: globals.api },
+        ...globals.timeout === null ? {} : { timeout: globals.timeout }
+      }, process.env.SATURNDOCS_MANAGEMENT_TOKEN);
+      process.exitCode = writer.write(successResult(context, data), { text: JSON.stringify(data, null, 2) });
+    } catch (error) {
+      process.exitCode = writer.write(failureResult(error, context));
+    }
+  });
+  applyCommandHelp(command, metadata);
+  command.addHelpText(
+    "after",
+    [
+      "Mutation rules, stricter than the pre-M7 command:",
+      "  A path may not name a site; --site is the only target, and it is verified against the credential before any write.",
+      "  Every non-GET, and GET on credentials, github/install, slack/install, or a suggestion session stream, needs --site.",
+      "  A raw approve or dismiss needs --base and --head, or expected_base_sha and expected_head_sha in --data.",
+      "  Without --site only GET, GET openapi.json, and GET sites answer; the first two need no credential.",
+      "  Authentication: SATURNDOCS_MANAGEMENT_TOKEN. Provider installation returns an authorization URL.",
+      ""
+    ].join("\n")
+  );
+}
+
+export {
+  callManagement,
+  MANAGE_METADATA,
+  registerManage
+};

package/dist/chunk-TKISMN3P.js

@@ -0,0 +1,39 @@
+import {
+  interruptSignal
+} from "./chunk-KGJESHJC.js";
+import {
+  CliError,
+  createClient,
+  isManagementError
+} from "./chunk-GYRVGWDM.js";
+
+// src/adapter/client.ts
+var TOKEN_VARIABLE = "SATURNDOCS_MANAGEMENT_TOKEN";
+function clientFor(globals, environment = {}) {
+  const env = environment.env ?? process.env;
+  const signal = environment.signal ?? interruptSignal() ?? void 0;
+  const config = {
+    token: env[TOKEN_VARIABLE],
+    ...globals.api === null ? {} : { origin: globals.api },
+    ...environment.fetchImpl === void 0 ? {} : { fetchImpl: environment.fetchImpl },
+    ...signal === void 0 ? {} : { signal },
+    ...globals.timeout === null ? {} : { deadlineMs: globals.timeout * 1e3 }
+  };
+  return createClient(config);
+}
+function asCliError(error) {
+  if (!isManagementError(error)) return error;
+  return new CliError(error.detail.code, error.detail.message, {
+    server: error.detail.server,
+    retryable: error.detail.retryable,
+    mutation: error.detail.mutation,
+    exit: error.detail.exit,
+    cause: error
+  });
+}
+
+export {
+  TOKEN_VARIABLE,
+  clientFor,
+  asCliError
+};