primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/guides.d.ts

@@ -0,0 +1,223 @@
+import { Command } from "commander";
+export { normalizeServerUrl, isValidBranchName } from "../lib/channel.js";
+/**
+ * Resolve which branch of the published site repo to fetch guides from.
+ *
+ * Branches of primitive-docs-site are named after the deploy environment
+ * whose docs they carry (published as part of each deploy — see
+ * primitive-docs/scripts/publish-gh-pages.mjs): `main` = production,
+ * `alpha` = the alpha environment. Precedence (originally issue #1463,
+ * repointed at consolidation): the undocumented `PRIMITIVE_GUIDES_BRANCH`
+ * override (validated as a plausible git ref), then alpha server-URL
+ * detection, then `main`. See `resolveChannelBranch` for the shared logic.
+ */
+export declare function resolveDocsBranch(serverUrl: string | undefined, override?: string | undefined): string;
+/**
+ * A single available guide variant. `file` is always present; `language`
+ * and/or `platform` are optional — an omitted dimension means the variant is
+ * agnostic on that dimension (matches any requested value). This expresses all
+ * three categories from docs PR #81: language-only (e.g. javascript),
+ * platform-only (e.g. android), and pair-specific (e.g. swift_ios).
+ */
+export interface GuideVariant {
+    language?: string;
+    platform?: string;
+    file: string;
+}
+export interface Guide {
+    topic: string;
+    /**
+     * The default variant — always present. Served when nothing is requested,
+     * or when a requested (language, platform) combination matches no variant.
+     */
+    file: string;
+    /** Available variants (docs PR #81 shape). Absent for concept-only guides. */
+    variants?: GuideVariant[];
+    description: string;
+    keywords: string[];
+    useCases: string[];
+    concepts: string[];
+    prerequisites: string[];
+    relatedGuides: string[];
+}
+export interface Manifest {
+    /** Manifest-level defaults (docs PR #81). Informational; surfaced in --json. */
+    defaults?: {
+        language?: string;
+        platform?: string;
+    };
+    /**
+     * Optional platform→language map (issue #1219; authored in
+     * Primitive-Labs/primitive-docs#194, consumed here). Maps each supported
+     * platform to the language its guides are written in, e.g.
+     * `{ web: { language: "ts" }, ios: { language: "swift" } }`. The CLI reads
+     * this to infer a language from `--platform` — it NEVER hardcodes the map.
+     * Absent on older manifests / stale cache: in that case `--platform` is not
+     * validated or inferred (back-compat pass-through). See
+     * `validateAndResolveRequest`.
+     */
+    platforms?: Record<string, {
+        language: string;
+    }>;
+    guides: Guide[];
+}
+interface VersionInfo {
+    version: string;
+    source: "flag" | "detected" | "default";
+    clientVersion?: string;
+    fallbackFrom?: string;
+}
+/**
+ * Normalize a `--language` flag value: lowercase, trim, and map known aliases
+ * (typescript/javascript/js → ts). Unknown values pass through unchanged.
+ *
+ * NOTE: guide flags are intentionally NOT validated against a fixed enum. An
+ * unknown/typo'd value simply matches no variant and falls back to the guide's
+ * default `file` (the "never fail" behavior from #977). This DIVERGES from
+ * `init --platform`, which validates and exits for unsupported values
+ * (cli/src/commands/init.ts) — that divergence is deliberate and guide-specific.
+ */
+export declare function normalizeLanguage(value: string | undefined): string | undefined;
+/**
+ * Normalize a `--platform` flag value: lowercase + trim. No aliases for now.
+ * Like `normalizeLanguage`, unknown values pass through and fall back to the
+ * default `file` rather than erroring (guide-specific "never fail" behavior).
+ */
+export declare function normalizePlatform(value: string | undefined): string | undefined;
+export type MatchedOn = "exact" | "language" | "platform" | "default";
+export interface VariantSelection {
+    /** The variant filename to fetch/serve. */
+    file: string;
+    /**
+     * Which dimensions the matched variant actually pinned:
+     * - "exact"    — variant pins both the requested language AND platform
+     * - "language" — variant pins (and matched) language only
+     * - "platform" — variant pins (and matched) platform only
+     * - "default"  — no variant matched; the guide's default `file` is served
+     *
+     * A language-pinned/platform-agnostic hit is reported as "language", NOT
+     * "exact", so agents don't over-trust specificity the manifest didn't claim.
+     */
+    matchedOn: MatchedOn;
+}
+/**
+ * Select the guide variant filename for a requested (language, platform).
+ *
+ * Implemented as ordered `find()` passes — NOT a wildcard scoring system —
+ * with the no-flags case special-cased to the default `file`:
+ *
+ *   0. No flags at all          → guide.file (deterministic "default")
+ *   1. Exact pair               → variant pins BOTH requested dims
+ *   2. Language-only            → variant pins language; platform agnostic
+ *   3. Platform-only            → variant pins platform; language agnostic
+ *   4. Default                  → guide.file
+ *
+ * An omitted REQUEST dimension acts as a wildcard during matching (a
+ * `--language swift` request matches a swift variant regardless of platform).
+ * This function NEVER throws — an unknown/typo'd/unavailable combination simply
+ * falls through to the guide's default `file`.
+ */
+export declare function selectVariant(guide: Guide, request: {
+    language?: string;
+    platform?: string;
+}): VariantSelection;
+/**
+ * The global set of languages a manifest supports. Derived (never hardcoded)
+ * from: every guide variant's `language`, the manifest-level `defaults.language`
+ * (falling back to `"ts"` when absent), and every `platforms[*].language`. Used
+ * to validate `--language` and to render the `guides list` legend / `--json`.
+ *
+ * Derived per-request from the manifest ACTUALLY loaded (so it stays correct
+ * for stale-cache / `--guide-version` fallbacks), and grows automatically as
+ * new languages appear in the manifest — no CLI change needed.
+ */
+export declare function deriveLanguages(manifest: Manifest): Set<string>;
+/**
+ * The outcome of validating + resolving a `(--language, --platform)` request.
+ * This is a PURE result — `validateAndResolveRequest` never calls `error()` or
+ * `process.exit()`; the command action does that when `error` is set (keeps the
+ * helper unit-testable, per the design's implementation hygiene note).
+ */
+export interface ResolveResult {
+    /** Effective language to select on, after platform→language inference. */
+    language?: string;
+    /** The requested platform, passed to `selectVariant` for exact-pair matching. */
+    platform?: string;
+    /** When set, validation failed; the action prints `error(...)` and exits 1. */
+    error?: string;
+}
+/**
+ * Validate the requested `(language, platform)` against the loaded manifest and
+ * resolve the effective language (issue #1219). Behavior:
+ *
+ *  - Normalizes both values first (lowercase + trim, aliases, `"" → undefined`)
+ *    via the existing `normalizeLanguage`/`normalizePlatform` helpers, then
+ *    validates the NORMALIZED value.
+ *  - `--language` is validated against `deriveLanguages(manifest)` whether or
+ *    not a `platforms` block exists (the set is derivable from any manifest).
+ *  - `--platform` is validated + inferred ONLY when `manifest.platforms` is
+ *    present. With the block, an unknown platform is a hard error and a known
+ *    platform infers `language = platforms[p].language` (an explicit
+ *    `--language` always wins the language dimension). WITHOUT the block, the
+ *    platform passes through unvalidated and uninferred — today's non-enforcing
+ *    behavior, so older manifests / stale cache don't start hard-failing.
+ *  - Unknown values produce a hard-error message mirroring `init --platform`'s
+ *    style, plus a cross-hint when the bad value names the other dimension
+ *    (`--platform swift` → "Did you mean --language swift?", and vice versa).
+ */
+export declare function validateAndResolveRequest(manifest: Manifest, rawLanguage: string | undefined, rawPlatform: string | undefined): ResolveResult;
+export declare function buildManifestUrl(branch: string, version: string): string;
+export declare function buildGuideUrl(branch: string, version: string, fileName: string): string;
+interface FetchManifestResult {
+    manifest: Manifest;
+    fromCache: boolean;
+    stale: boolean;
+    versionInfo: VersionInfo;
+}
+/**
+ * Thrown by `fetchManifest` when a branch/version genuinely has no published
+ * manifest — every candidate manifest URL returned 404. Distinct from a
+ * transport or server error (timeout, DNS, 5xx), which `fetchManifest` lets
+ * propagate as a plain `Error`. `resolveManifest` relies on this distinction:
+ * only a truly-absent branch may fall back to `main`; a transient failure must
+ * surface so an alpha/preview invocation is never silently downgraded to
+ * production `main` docs on a flake (#1463).
+ */
+export declare class ManifestNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * The manifest, plus the branch it was actually served from. `branchFellBack`
+ * is true when a non-`main` branch (`next`, or a `PRIMITIVE_GUIDES_BRANCH`
+ * override) had no manifest and we fell back to `main` (#1463, behavior 3).
+ */
+interface ResolvedManifest extends FetchManifestResult {
+    branch: string;
+    requestedBranch: string;
+    branchFellBack: boolean;
+}
+/**
+ * Fetch the manifest for `requestedBranch`, falling back to `main` **only when
+ * the non-`main` branch has no published manifest** — i.e. every candidate URL
+ * 404s and `fetchManifest` throws a `ManifestNotFoundError`. That fallback
+ * covers a `PRIMITIVE_GUIDES_BRANCH` override that names a nonexistent
+ * branch.
+ *
+ * A transport or server error (timeout, DNS, 5xx) on the requested branch is
+ * NOT a missing branch — it arrives as a plain `Error` and is re-thrown, never
+ * downgraded to `main`. Silently serving production `main` docs for an
+ * alpha/preview invocation because of a transient flake would be wrong: a
+ * preview run must fail loudly rather than quietly return the wrong branch's
+ * docs (#1463).
+ */
+export declare function resolveManifest(requestedBranch: string, versionInfo: VersionInfo, forceRefresh?: boolean): Promise<ResolvedManifest>;
+/**
+ * Compact rendering of the LANGUAGES a guide offers, for the `guides list`
+ * table (issue #1219 renamed the ambiguous `COMBINATIONS` column to
+ * `LANGUAGES`). Lists each variant's `language`, de-duplicated and order-
+ * preserving; a guide with no language-pinned variants renders `default`.
+ * Platforms are surfaced separately as a manifest-level legend, since they are
+ * a manifest-wide map rather than a per-guide attribute.
+ */
+export declare function formatLanguages(guide: Guide): string;
+export declare function registerGuidesCommands(program: Command): void;