saturndocs 0.1.0

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import {
+  COMMAND_GROUPS,
+  selectCommandGroup
+} from "./chunk-QLFODLVN.js";
+import {
+  installInterrupt
+} from "./chunk-KGJESHJC.js";
+import {
+  EXIT,
+  applyGlobalFlags,
+  applyGlobalFlagsDeep,
+  createResultWriter,
+  failureResult,
+  invalidInput,
+  wantsJson
+} from "./chunk-GYRVGWDM.js";
+
+// src/cli.ts
+import { readFileSync } from "fs";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { Command, CommanderError } from "commander";
+var cliDir = dirname(fileURLToPath(import.meta.url));
+function cliVersion() {
+  try {
+    const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    const version = manifest.version;
+    return typeof version === "string" ? version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function commandFromArgv(argv) {
+  const group = selectCommandGroup(argv);
+  if (group === void 0) return "saturndocs";
+  const index = argv.indexOf(group.name);
+  const next = argv[index + 1];
+  return next !== void 0 && !next.startsWith("-") ? `${group.name} ${next}` : group.name;
+}
+function createProgram() {
+  const program = new Command();
+  program.name("saturndocs").description("SaturnDocs CLI: init, validate, dev, build, deploy, broken-links, openapi-check").version(cliVersion()).addHelpCommand(false).showHelpAfterError().configureHelp({ subcommandTerm: (command) => command.name() });
+  applyGlobalFlags(program);
+  return program;
+}
+async function registerGroup(program, group) {
+  const register = await group.load();
+  const before = new Set(program.commands);
+  register(program, cliDir);
+  for (const command of program.commands) {
+    if (!before.has(command)) applyGlobalFlagsDeep(command);
+  }
+}
+function addPlaceholder(program, group, writer) {
+  program.command(group.name).description(group.summary).allowUnknownOption(true).allowExcessArguments(true).helpOption(false).argument("[args...]").action(async () => {
+    process.exitCode = await run(process.argv, group, writer);
+  });
+}
+async function run(argv, forced, reuse) {
+  const json = wantsJson(argv);
+  const writer = reuse ?? createResultWriter({ json });
+  const program = createProgram();
+  if (json) program.exitOverride();
+  const selected = forced ?? selectCommandGroup(argv);
+  for (const group of COMMAND_GROUPS) {
+    if (group === selected) await registerGroup(program, group);
+    else addPlaceholder(program, group, writer);
+  }
+  const interrupt = reuse === void 0 ? installInterrupt({ writer, context: () => ({ command: commandFromArgv(argv) }) }) : void 0;
+  try {
+    await program.parseAsync([...argv]);
+    return process.exitCode === void 0 ? EXIT.success : Number(process.exitCode);
+  } catch (error) {
+    return report(error, argv, writer);
+  } finally {
+    interrupt?.dispose();
+  }
+}
+function report(error, argv, writer) {
+  const context = { command: commandFromArgv(argv) };
+  if (error instanceof CommanderError) {
+    if (error.exitCode === 0) return EXIT.success;
+    if (!writer.json) return error.exitCode;
+    writer.write(failureResult(invalidInput(error.message.replace(/^error: /, "")), context));
+    return EXIT.invalid_input;
+  }
+  if (!writer.json) {
+    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
+`);
+    return 1;
+  }
+  return writer.write(failureResult(error, context));
+}
+process.exitCode = await run(process.argv);

package/dist/deploy-QU7DCKWU.js

@@ -0,0 +1,11 @@
+import {
+  deployBundle,
+  registerDeploy
+} from "./chunk-I6U4V7B4.js";
+import "./chunk-S45UWCML.js";
+import "./chunk-R3X2DPFF.js";
+import "./chunk-VNYDYHXM.js";
+export {
+  deployBundle,
+  registerDeploy
+};

package/dist/dev-VDSDCBO2.js

@@ -0,0 +1,43 @@
+import {
+  findWebDir
+} from "./chunk-VXEUNRVA.js";
+import {
+  messageOf,
+  resolveDocsDir
+} from "./chunk-VNYDYHXM.js";
+
+// src/commands/dev.ts
+import { execa } from "execa";
+import pc from "picocolors";
+function registerDev(program, cliDir) {
+  program.command("dev").description("Start the Astro dev server for a docs directory").argument("[dir]", "docs directory (contains docs.json)").option("--port <port>", "port for the dev server").action(async (dir, options) => {
+    const docsDir = resolveDocsDir(dir);
+    let webDir;
+    try {
+      webDir = findWebDir(cliDir);
+    } catch (error) {
+      console.error(pc.red(`error: ${messageOf(error)}`));
+      process.exit(1);
+    }
+    const args = ["dev"];
+    if (options.port) args.push("--port", options.port);
+    console.log(
+      pc.dim(`saturndocs dev: astro ${args.join(" ")} in ${webDir}`)
+    );
+    try {
+      await execa("astro", args, {
+        cwd: webDir,
+        preferLocal: true,
+        localDir: webDir,
+        stdio: "inherit",
+        env: { SATURNDOCS_DOCS_DIR: docsDir }
+      });
+    } catch (error) {
+      console.error(pc.red(`astro dev failed: ${messageOf(error)}`));
+      process.exit(1);
+    }
+  });
+}
+export {
+  registerDev
+};

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+import { Command } from 'commander';
+import { CommandMetadata, ClientErrorCode, ServerFault, MutationOutcome, ExitCode, ClientLimitation, ClientRecovery, DurableIds, ClientError, ClientFailure, ClientSuccess, ClientResult, TextInput, ManagementClient, SiteDiscovery, PagesResult, SiteStatus } from '@saturndocs/management-client';
+import { DocsConfig } from '@saturndocs/config';
+import { AbiViolation } from '@saturndocs/source-abi';
+import { BrandExtraction, extractBrandFromUrl } from '@saturndocs/brand';
+export { BrandAssetExtraction, BrandExtraction, BrandFetchOptions, BrandFetcher, ColorCandidate, DEFAULT_PRIMARY_COLOR, FetchImplementation, LogoCandidate, LogoSelection, ScoredColor, UrlValidator, colorToHex, deriveDocsJson, extensionForContentType, extractBrandFromUrl, extractBrandText, extractCssColorCandidates, extractManifestUrl, extractStylesheetUrls, extractThemeColorMetas, fetchBrandAsset, normalizeHexColor, normalizeHttpUrl, parseCssColor, pickPrimaryColor, scoreColorCandidates, selectLogoAssets } from '@saturndocs/brand';
+
+/** Every group registers the same way, whether or not it takes the cli directory. */
+type RegisterGroup = (program: Command, cliDir: string) => void;
+interface CommandGroup {
+    /** The top-level command name, as it appears in help. */
+    readonly name: string;
+    readonly summary: string;
+    /**
+     * Pulls in the renderer or the workspace build. Kept out of help and out of
+     * every management run, which must work from a directory with no docs in it.
+     */
+    readonly renderer: boolean;
+    readonly load: () => Promise<RegisterGroup>;
+    /**
+     * The group's command metadata, for `saturndocs schema` and for help. Lazy for
+     * the same reason as `load`. A management group without it is a drift-test
+     * failure; a local workspace group (`renderer: true`) has none.
+     */
+    readonly metadata?: () => Promise<readonly CommandMetadata[]>;
+}
+/**
+ * The order help prints. A later issue adds one line; nothing else in the
+ * entry point or the smoke test changes.
+ */
+declare const COMMAND_GROUPS: readonly CommandGroup[];
+declare const COMMAND_GROUP_NAMES: readonly string[];
+declare function findCommandGroup(name: string): CommandGroup | undefined;
+/**
+ * Which group this invocation runs, read from raw argv so only that group's
+ * module is imported. Everything else stays a name and a summary in help.
+ */
+declare function selectCommandGroup(argv: readonly string[]): CommandGroup | undefined;
+
+/** The envelope fields a command knows before it knows whether it succeeded. */
+interface ResultContext {
+    command: string;
+    siteId?: string | null;
+    ids?: DurableIds;
+    limitations?: readonly ClientLimitation[];
+    recovery?: ClientRecovery | null;
+}
+interface CliErrorOptions {
+    server?: ServerFault | null;
+    retryable?: boolean;
+    mutation?: MutationOutcome;
+    exit?: ExitCode;
+    limitations?: readonly ClientLimitation[];
+    recovery?: ClientRecovery | null;
+    /** A partial result worth keeping beside the failure, such as a dismissal whose cleanup did not finish. */
+    data?: unknown;
+    cause?: unknown;
+}
+/** An error the client classified. Anything else reaching the top level is unclassified. */
+declare class CliError extends Error {
+    readonly code: ClientErrorCode;
+    readonly server: ServerFault | null;
+    readonly retryable: boolean;
+    readonly mutation: MutationOutcome;
+    readonly exit: ExitCode;
+    readonly limitations: readonly ClientLimitation[];
+    readonly recovery: ClientRecovery | null;
+    readonly data: unknown;
+    constructor(code: ClientErrorCode, message: string, options?: CliErrorOptions);
+}
+/** Every refusal the client makes before a request leaves the process. */
+declare function invalidInput(message: string, options?: CliErrorOptions): CliError;
+declare function interrupted(message?: string, options?: CliErrorOptions): CliError;
+declare function clientError(code: ClientErrorCode, message: string, server?: ServerFault | null): ClientError;
+declare function successResult(context: ResultContext, data: unknown): ClientSuccess;
+declare function failureResult(error: unknown, context: ResultContext): ClientFailure;
+
+interface TextSink {
+    write(chunk: string): unknown;
+}
+interface ResultWriterOptions {
+    json: boolean;
+    stdout?: TextSink;
+    stderr?: TextSink;
+}
+interface WriteOptions {
+    /** What a person sees on stdout for a success when `--json` is off. */
+    text?: string;
+}
+/**
+ * The single stdout path for a command that reports a result. One invocation
+ * writes one envelope: a second call is dropped so an interrupt racing a
+ * finished command cannot append a second object to a stream an agent parses
+ * whole.
+ */
+interface ResultWriter {
+    readonly json: boolean;
+    readonly written: boolean;
+    write(result: ClientResult, options?: WriteOptions): ExitCode;
+}
+declare function createResultWriter(options: ResultWriterOptions): ResultWriter;
+/** Whether the invocation asked for one machine-readable result, read before Commander parses. */
+declare function wantsJson(argv: readonly string[]): boolean;
+
+/** The stdin cap for a command whose operation declares no text limit. */
+declare const STDIN_BYTE_CEILING = 1048576;
+interface TextInputFlags {
+    text?: string;
+    file?: string;
+}
+interface StdinSource extends AsyncIterable<Uint8Array | string> {
+    isTTY?: boolean;
+}
+interface ReadTextOptions {
+    /** The command name, so the refusal names what needs the text. */
+    command: string;
+    requirement: TextInput;
+    /** Code points the operation accepts. Checked before any HTTP call. */
+    limit: number | null;
+    /** False under `--no-input`: stdin is read only when `--file -` names it. */
+    interactive?: boolean;
+    stdin?: StdinSource;
+    readFileImpl?: (path: string) => Promise<string>;
+}
+/**
+ * Resolve the one text source a mutation accepts. Exclusivity, the size limit,
+ * and the stdin bound are all settled here so no oversized or ambiguous body
+ * reaches the transport.
+ */
+declare function readTextInput(flags: TextInputFlags, options: ReadTextOptions): Promise<string | null>;
+
+interface GlobalOptions {
+    json: boolean;
+    site: string | null;
+    api: string | null;
+    /** False under `--no-input`: nothing is read from a terminal. */
+    input: boolean;
+    /** Seconds. */
+    timeout: number | null;
+}
+/**
+ * The same five flags on every level, so `--json` before the subcommand and
+ * `--json` after it are the same invocation. Commander otherwise refuses a
+ * parent's option once a subcommand name has been read. A command that already
+ * declares one of these keeps its own: the global is not redeclared over it.
+ */
+declare function applyGlobalFlags(command: Command): Command;
+/** Every command a group registered, including nested subcommands. */
+declare function applyGlobalFlagsDeep(command: Command): void;
+/**
+ * Root to leaf, explicit values only: a default on the subcommand must not
+ * overwrite what the caller put before the subcommand name.
+ */
+declare function resolveGlobalOptions(command: Command): GlobalOptions;
+
+interface SignalSource {
+    on(signal: "SIGINT", handler: () => void): unknown;
+    off(signal: "SIGINT", handler: () => void): unknown;
+}
+interface InterruptOptions {
+    writer: ResultWriter;
+    /** Read when the signal arrives, so a command that has learnt its ids still reports them. */
+    context: () => ResultContext;
+    exit?: (code: number) => void;
+    source?: SignalSource;
+}
+interface InterruptHandle {
+    /** Aborted on SIGINT so local work stops instead of racing the exit. */
+    readonly signal: AbortSignal;
+    dispose(): void;
+}
+/** The running invocation's interrupt signal, for work a command starts after the entry point installed it. */
+declare function interruptSignal(): AbortSignal | null;
+/**
+ * SIGINT stops local work, reports what the command knew, and exits 130.
+ * Nothing remote is cancelled, so the result never says the work was undone.
+ */
+declare function installInterrupt(options: InterruptOptions): InterruptHandle;
+
+/** The `after` help body, built so schema and `--help` cannot describe the command differently. */
+declare function helpBody(metadata: CommandMetadata): string;
+/**
+ * Description, flags, and examples from the one metadata entry, so help and
+ * `saturndocs schema` cannot drift apart. A flag the command already declared
+ * keeps its own declaration, including its parser and default.
+ */
+declare function applyCommandHelp(command: Command, metadata: CommandMetadata): Command;
+
+declare const SCHEMA_METADATA: readonly CommandMetadata[];
+/**
+ * The metadata document for a selector, or for the whole CLI when there is
+ * none. Only the named group's module is imported, so asking about one command
+ * does not load every other one.
+ */
+declare function schemaDocument(selector: string | null, groups?: readonly CommandGroup[]): Promise<Record<string, unknown>>;
+declare function registerSchema(program: Command): void;
+
+declare const MANAGE_METADATA: readonly CommandMetadata[];
+
+/** The only place a management credential is read. It never reaches argv, help, or a result. */
+declare const TOKEN_VARIABLE = "SATURNDOCS_MANAGEMENT_TOKEN";
+interface ClientEnvironment {
+    env?: Record<string, string | undefined>;
+    /** Injected for tests; passed on as a bare function, never as a method of this object. */
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}
+/**
+ * One client per invocation, built from the global flags and the environment.
+ * The token is read here rather than passed through a command's options, so a
+ * credential cannot arrive on a command line an agent later logs.
+ */
+declare function clientFor(globals: GlobalOptions, environment?: ClientEnvironment): ManagementClient;
+/**
+ * A classified client failure carried into the CLI's own error type, so the
+ * envelope reports the code and the server's own fault rather than the
+ * unclassified bucket every uncaught throw lands in.
+ */
+declare function asCliError(error: unknown): unknown;
+
+declare const AUTH_METADATA: readonly CommandMetadata[];
+interface AuthStatus {
+    /** The site the credential resolves to, exactly as discovery returned it. */
+    current: string;
+    sites: SiteDiscovery["sites"];
+    /** One read answered. It says nothing about write or approve permission. */
+    read_verified: true;
+}
+declare function authStatusOf(discovery: SiteDiscovery): AuthStatus;
+declare function registerAuth(program: Command, _cliDir: string, environment?: ClientEnvironment): void;
+
+declare const SITES_METADATA: readonly CommandMetadata[];
+/** The one site id, from the argument or the global flag; two that disagree are refused before any read. */
+declare function requestedSite(positional: string | undefined, flag: string | null): string | undefined;
+declare function registerSites(program: Command, _cliDir: string, environment?: ClientEnvironment): void;
+
+declare const PAGES_METADATA: readonly CommandMetadata[];
+/**
+ * What the answer does not cover. An unpublished site and counts the edge could
+ * not supply in full are both reported here, so a caller reading only the
+ * limitations still learns the list is not a complete picture.
+ */
+declare function pagesLimitations(result: PagesResult): readonly ClientLimitation[];
+declare function registerPages(program: Command, _cliDir: string, environment?: ClientEnvironment): void;
+
+declare const REQUESTS_METADATA: readonly CommandMetadata[];
+/** The one `requests` command tree. A later sibling module adds its own register call and metadata here. */
+declare function registerRequests(program: Command, _cliDir: string, environment?: ClientEnvironment): void;
+
+declare const REQUESTS_CREATE_METADATA: readonly CommandMetadata[];
+interface CreateEnvironment extends ClientEnvironment {
+    stdin?: StdinSource;
+    readFileImpl?: (path: string) => Promise<string>;
+}
+declare function registerRequestsCreate(group: Command, environment?: CreateEnvironment): void;
+
+declare const STATUS_METADATA: readonly CommandMetadata[];
+declare function statusText(status: SiteStatus): string;
+declare function registerStatus(program: Command, _cliDir: string, environment?: ClientEnvironment): void;
+
+/**
+ * Walk up the directory tree from `startDir` looking for the SaturnDocs
+ * workspace root. The root is the first ancestor directory that contains BOTH
+ * a `pnpm-workspace.yaml` file and an `apps/web` directory. Returns the
+ * absolute path of that root.
+ *
+ * Throws a readable Error when no such ancestor exists.
+ */
+declare function findWorkspaceRoot(startDir: string): string;
+/**
+ * Resolve the absolute path of the `apps/web` Astro application directory by
+ * finding the workspace root above `startDir`.
+ */
+declare function findWebDir(startDir: string): string;
+
+interface ResolvedPage {
+    /** The navigation page entry, e.g. "writing/components" or "index". */
+    entry: string;
+    /** Absolute path of the source file on disk. */
+    file: string;
+    /** Which extension resolved. */
+    ext: ".mdx" | ".md";
+}
+/**
+ * Apply the fixed file-resolution rule shared by validate and the web app:
+ * for entry `p`, the source file is
+ * `<docsDir>/pages/p.mdx`, falling back to `<docsDir>/pages/p.md`. If both
+ * exist it is an error; if neither exists it is an error.
+ */
+declare function resolvePageFile(docsDir: string, entry: string): ResolvedPage;
+/**
+ * Site URL for a navigation page entry. The literal entry "index" maps to the
+ * site root "/"; every other entry maps to "/" + entry.
+ */
+declare function pageUrl(entry: string): string;
+/** All page entries across every navigation group, in navigation order. */
+declare function collectPageEntries(config: DocsConfig): string[];
+
+/** A single internal link in the built site that does not resolve to a file. */
+interface BrokenLink {
+    /** The HTML file containing the link, relative to the dist directory. */
+    source: string;
+    /** The raw href/src value as written in the HTML. */
+    href: string;
+}
+/**
+ * Scan every `*.html` file under `distDir` for internal `href`/`src` targets
+ * and return the ones that do not resolve to a file in dist. Results are
+ * de-duplicated by (source file, href).
+ */
+declare function scanBrokenLinks(distDir: string): Promise<BrokenLink[]>;
+
+/**
+ * Validate a docs directory. Returns a list of human-readable error strings;
+ * an empty list means the directory is valid. Checks performed:
+ * - `docs.json` loads and passes the schema.
+ * - `models.toml` (only if present) loads and passes the schema.
+ * - every navigation page resolves under the file-resolution rule.
+ * - every navigation-group `openapi` file exists and parses.
+ */
+declare function validateDocs(docsDir: string): Promise<string[]>;
+
+/**
+ * Render a list of rows as a fixed-width, column-aligned text table with a
+ * header row and a divider. Each cell is left-aligned and padded to the widest
+ * value in its column. Returns the table as a single newline-joined string.
+ */
+declare function renderTable(headers: string[], rows: string[][]): string;
+
+interface BundleArchive {
+    path: string;
+    byteLength: number;
+    sha256: string;
+    warnings: AbiViolation[];
+    cleanup(): Promise<void>;
+}
+declare function createBundleArchive(inputDir: string): Promise<BundleArchive>;
+
+type JobStatus = {
+    job_id: string;
+    state: string;
+    revision_id?: string;
+    release_id?: string;
+    generation?: number;
+    error_code?: string;
+};
+declare function deployBundle(input: {
+    docsDir: string;
+    apiUrl: string;
+    token: string;
+    promote: boolean;
+    idempotencyKey?: string;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    onState?: (status: JobStatus) => void;
+}): Promise<JobStatus>;
+
+interface InitOptions {
+    name?: string;
+    primary?: string;
+    fromUrl?: string;
+    yes?: boolean;
+}
+interface InitDependencies {
+    extractBrand?: typeof extractBrandFromUrl;
+}
+interface InitResult {
+    docsDir: string;
+    config: DocsConfig;
+    extraction?: BrandExtraction;
+}
+declare function scaffoldDocsProject(dir?: string, options?: InitOptions, dependencies?: InitDependencies): Promise<InitResult>;
+declare function buildDocsConfig(input: {
+    name: string;
+    description: string;
+    primary: string;
+    logo?: string;
+    favicon?: string;
+}): DocsConfig;
+
+export { AUTH_METADATA, type AuthStatus, type BrokenLink, type BundleArchive, COMMAND_GROUPS, COMMAND_GROUP_NAMES, CliError, type ClientEnvironment, type CommandGroup, type CreateEnvironment, type GlobalOptions, type InitOptions, type InitResult, type InterruptHandle, MANAGE_METADATA, PAGES_METADATA, REQUESTS_CREATE_METADATA, REQUESTS_METADATA, type RegisterGroup, type ResolvedPage, type ResultContext, type ResultWriter, SCHEMA_METADATA, SITES_METADATA, STATUS_METADATA, STDIN_BYTE_CEILING, TOKEN_VARIABLE, type TextInputFlags, applyCommandHelp, applyGlobalFlags, applyGlobalFlagsDeep, asCliError, authStatusOf, buildDocsConfig, clientError, clientFor, collectPageEntries, createBundleArchive, createResultWriter, deployBundle, failureResult, findCommandGroup, findWebDir, findWorkspaceRoot, helpBody, installInterrupt, interruptSignal, interrupted, invalidInput, pageUrl, pagesLimitations, readTextInput, registerAuth, registerPages, registerRequests, registerRequestsCreate, registerSchema, registerSites, registerStatus, renderTable, requestedSite, resolveGlobalOptions, resolvePageFile, scaffoldDocsProject, scanBrokenLinks, schemaDocument, selectCommandGroup, statusText, successResult, validateDocs, wantsJson };