primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/guides.js

@@ -2,13 +2,238 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join, basename } from "path";
 import { error, info, warn, formatTable, json, keyValue, } from "../lib/output.js";
+import { getServerUrl } from "../lib/config.js";
+import { resolveChannelBranch } from "../lib/channel.js";
+import { wholeListEnvelope } from "../lib/paginate.js";
 const GUIDES_CACHE_DIR = process.env.PRIMITIVE_CONFIG_DIR
     ? join(process.env.PRIMITIVE_CONFIG_DIR, "guides")
     : join(homedir(), ".primitive", "guides");
 const CACHE_META_FILE = join(GUIDES_CACHE_DIR, "cache-meta.json");
-const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/Primitive-Labs/primitive-docs/main/guides";
+// The public publish-only site repo. Guides are pushed there (alongside the
+// built docs site) by primitive-docs/scripts/publish-gh-pages.mjs; the docs
+// SOURCE lives in the js-bao-wss monorepo, which is private and therefore
+// can't serve raw URLs to end users. (The alpha channel's browsable site is
+// served from `main/alpha/`; guides still come from the `alpha` branch.)
+const GITHUB_RAW_ROOT = "https://raw.githubusercontent.com/Primitive-Labs/primitive-docs-site";
+const DEFAULT_DOCS_BRANCH = "main";
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const CLIENT_PACKAGE_NAME = "js-bao-wss-client";
+// Channel resolution now lives in lib/channel.ts, shared with the template
+// download in `primitive init` (issue #1934). Re-exported here because the
+// public shapes originated in this module (issue #1463).
+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 function resolveDocsBranch(serverUrl, override = process.env.PRIMITIVE_GUIDES_BRANCH) {
+    return resolveChannelBranch(serverUrl, override, "PRIMITIVE_GUIDES_BRANCH");
+}
+/**
+ * Resolve the docs branch for the current invocation, reading the target from
+ * `getServerUrl()`. Logged-out / legacy-no-creds makes `getServerUrl()` throw;
+ * we treat that as "no target" and fall back to `main` (the override still
+ * applies). Only the branch decision is wrapped here — an invalid override
+ * still throws out to the command's error handler.
+ */
+function resolveDocsBranchForInvocation() {
+    let serverUrl;
+    try {
+        serverUrl = getServerUrl();
+    }
+    catch {
+        serverUrl = undefined;
+    }
+    return resolveDocsBranch(serverUrl);
+}
+// Language aliases — map the agent's natural vocabulary onto canonical values.
+const LANGUAGE_ALIASES = {
+    typescript: "ts",
+    javascript: "ts",
+    js: "ts",
+};
+/**
+ * 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 function normalizeLanguage(value) {
+    if (value === undefined)
+        return undefined;
+    const lower = value.trim().toLowerCase();
+    if (lower === "")
+        return undefined;
+    return LANGUAGE_ALIASES[lower] ?? lower;
+}
+/**
+ * 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 function normalizePlatform(value) {
+    if (value === undefined)
+        return undefined;
+    const lower = value.trim().toLowerCase();
+    if (lower === "")
+        return undefined;
+    return lower;
+}
+/**
+ * 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 function selectVariant(guide, request) {
+    const reqLang = request.language;
+    const reqPlat = request.platform;
+    const variants = guide.variants ?? [];
+    // 0. No flags supplied at all → deterministically serve the default file.
+    if (reqLang === undefined && reqPlat === undefined) {
+        return { file: guide.file, matchedOn: "default" };
+    }
+    // A variant "matches" a dimension if the request omits it (wildcard) OR the
+    // variant pins it to exactly the requested value. A variant that omits a
+    // dimension is agnostic and matches any requested value for that dimension.
+    const langMatches = (v) => reqLang === undefined || v.language === undefined || v.language === reqLang;
+    const platMatches = (v) => reqPlat === undefined || v.platform === undefined || v.platform === reqPlat;
+    // 1. Exact pair: variant pins both requested dimensions to the request.
+    if (reqLang !== undefined && reqPlat !== undefined) {
+        const exact = variants.find((v) => v.language === reqLang && v.platform === reqPlat);
+        if (exact)
+            return { file: exact.file, matchedOn: "exact" };
+    }
+    // 2. Language requested. Prefer a platform-agnostic variant that pins the
+    //    language (reported as "language" — pinned one dim, agnostic on the
+    //    other). If none exists, honor the omitted-platform wildcard and fall
+    //    back to a pair-specific variant that still satisfies the request
+    //    (e.g. only `{swift,ios}` published + `--language swift`). That fallback
+    //    pins BOTH dimensions to satisfy the request, so it's reported as
+    //    "exact" — the variant is as specific as an exact-pair hit.
+    if (reqLang !== undefined) {
+        const langAgnostic = variants.find((v) => v.language === reqLang && v.platform === undefined);
+        if (langAgnostic)
+            return { file: langAgnostic.file, matchedOn: "language" };
+        const langWildcard = variants.find((v) => v.language === reqLang && platMatches(v));
+        if (langWildcard)
+            return { file: langWildcard.file, matchedOn: "exact" };
+    }
+    // 3. Platform requested (symmetric to pass 2). Prefer a language-agnostic
+    //    variant that pins the platform ("platform"); otherwise honor the
+    //    omitted-language wildcard and fall back to a pair-specific variant
+    //    satisfying the request, reported as "exact".
+    if (reqPlat !== undefined) {
+        const platAgnostic = variants.find((v) => v.platform === reqPlat && v.language === undefined);
+        if (platAgnostic)
+            return { file: platAgnostic.file, matchedOn: "platform" };
+        const platWildcard = variants.find((v) => v.platform === reqPlat && langMatches(v));
+        if (platWildcard)
+            return { file: platWildcard.file, matchedOn: "exact" };
+    }
+    // 4. Nothing matched → the guide's default file (never throws).
+    return { file: guide.file, matchedOn: "default" };
+}
+/**
+ * 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 function deriveLanguages(manifest) {
+    const languages = new Set();
+    for (const guide of manifest.guides ?? []) {
+        for (const variant of guide.variants ?? []) {
+            if (variant.language !== undefined)
+                languages.add(variant.language);
+        }
+    }
+    languages.add(manifest.defaults?.language ?? "ts");
+    for (const entry of Object.values(manifest.platforms ?? {})) {
+        if (entry.language)
+            languages.add(entry.language);
+    }
+    return languages;
+}
+/**
+ * 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 function validateAndResolveRequest(manifest, rawLanguage, rawPlatform) {
+    const language = normalizeLanguage(rawLanguage);
+    const platform = normalizePlatform(rawPlatform);
+    const supportedLanguages = deriveLanguages(manifest);
+    const platforms = manifest.platforms; // may be undefined (back-compat)
+    // Validate --language (independent of the platforms block).
+    if (language !== undefined && !supportedLanguages.has(language)) {
+        const supported = [...supportedLanguages].sort().join(", ");
+        let message = `Unknown language "${language}". Supported languages: ${supported}`;
+        // Cross-hint: the value names a known platform, not a language.
+        if (platforms && platforms[language]) {
+            message += `. Did you mean --platform ${language}?`;
+        }
+        return { error: message };
+    }
+    let effectiveLanguage = language;
+    // Validate + infer --platform — active ONLY when the platforms block exists.
+    if (platform !== undefined && platforms !== undefined) {
+        if (!platforms[platform]) {
+            const supported = Object.keys(platforms).sort().join(", ");
+            let message = `Unknown platform "${platform}". Supported platforms: ${supported}`;
+            // Cross-hint: the value names a known language, not a platform
+            // (the reporter's exact `--platform swift` case).
+            if (supportedLanguages.has(platform)) {
+                message += `. Did you mean --language ${platform}?`;
+            }
+            return { error: message };
+        }
+        // Infer the language from the platform; an explicit --language wins.
+        effectiveLanguage = language ?? platforms[platform].language;
+    }
+    // else: no platforms block → back-compat pass-through (no validate, no infer).
+    return { language: effectiveLanguage, platform };
+}
 function detectClientVersion() {
     const clientPkgPath = join(process.cwd(), "node_modules", CLIENT_PACKAGE_NAME, "package.json");
     try {
@@ -56,18 +281,21 @@ function formatClientVersion(info) {
 function formatGuidesVersion(info) {
     return info.version;
 }
-function getVersionCacheDir(version) {
-    return join(GUIDES_CACHE_DIR, version);
+// Cache paths are segmented by branch (#1463): ~/.primitive/guides/{branch}/
+// {version}/... so a `next` fetch never overwrites the `main` cached copy of
+// the same version+filename (and vice versa).
+function getVersionCacheDir(branch, version) {
+    return join(GUIDES_CACHE_DIR, branch, version);
 }
-function getManifestPath(version) {
-    return join(getVersionCacheDir(version), "manifest.json");
+function getManifestPath(branch, version) {
+    return join(getVersionCacheDir(branch, version), "manifest.json");
 }
-function getGuidesCacheDir(version) {
-    return join(getVersionCacheDir(version), "guides");
+function getGuidesCacheDir(branch, version) {
+    return join(getVersionCacheDir(branch, version), "guides");
 }
-function ensureCacheDir(version) {
-    const versionDir = getVersionCacheDir(version);
-    const guidesDir = getGuidesCacheDir(version);
+function ensureCacheDir(branch, version) {
+    const versionDir = getVersionCacheDir(branch, version);
+    const guidesDir = getGuidesCacheDir(branch, version);
     if (!existsSync(versionDir)) {
         mkdirSync(versionDir, { recursive: true });
     }
@@ -98,11 +326,15 @@ function isCacheExpired(fetchedAt) {
     const fetchedTime = new Date(fetchedAt).getTime();
     return Date.now() - fetchedTime > CACHE_TTL_MS;
 }
-function getManifestUrl(version) {
-    return `${GITHUB_RAW_BASE}/${version}/guides.json`;
+/** The raw-GitHub base for a site-repo branch, e.g. `.../primitive-docs-site/main/guides`. */
+function githubRawBase(branch) {
+    return `${GITHUB_RAW_ROOT}/${branch}/guides`;
 }
-function getGuideUrl(version, fileName) {
-    return `${GITHUB_RAW_BASE}/${version}/${fileName}`;
+export function buildManifestUrl(branch, version) {
+    return `${githubRawBase(branch)}/${version}/guides.json`;
+}
+export function buildGuideUrl(branch, version, fileName) {
+    return `${githubRawBase(branch)}/${version}/${fileName}`;
 }
 async function fetchWithTimeout(url, timeoutMs = 10000) {
     const controller = new AbortController();
@@ -115,11 +347,26 @@ async function fetchWithTimeout(url, timeoutMs = 10000) {
         clearTimeout(timeout);
     }
 }
-async function fetchManifestForVersion(version, forceRefresh = false) {
-    ensureCacheDir(version);
+/**
+ * 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 class ManifestNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ManifestNotFoundError";
+    }
+}
+async function fetchManifestForVersion(branch, version, forceRefresh = false) {
+    ensureCacheDir(branch, version);
     const meta = loadCacheMeta();
-    const manifestPath = getManifestPath(version);
-    const cacheExpired = isCacheExpired(meta.manifestFetchedAt?.[version]);
+    const manifestPath = getManifestPath(branch, version);
+    const cacheExpired = isCacheExpired(meta.manifestFetchedAt?.[branch]?.[version]);
     const hasCachedManifest = existsSync(manifestPath);
     // If cache is valid and not forcing refresh, use it
     if (!forceRefresh && !cacheExpired && hasCachedManifest) {
@@ -132,11 +379,11 @@ async function fetchManifestForVersion(version, forceRefresh = false) {
         }
     }
     // Try to fetch from network
-    const manifestUrl = getManifestUrl(version);
+    const manifestUrl = buildManifestUrl(branch, version);
     try {
         const response = await fetchWithTimeout(manifestUrl);
         if (response.status === 404) {
-            return null; // Version doesn't exist
+            return null; // Version (or branch) doesn't exist
         }
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -145,7 +392,8 @@ async function fetchManifestForVersion(version, forceRefresh = false) {
         // Save to cache
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
         meta.manifestFetchedAt = meta.manifestFetchedAt || {};
-        meta.manifestFetchedAt[version] = new Date().toISOString();
+        meta.manifestFetchedAt[branch] = meta.manifestFetchedAt[branch] || {};
+        meta.manifestFetchedAt[branch][version] = new Date().toISOString();
         saveCacheMeta(meta);
         return { manifest, fromCache: false, stale: false };
     }
@@ -163,15 +411,15 @@ async function fetchManifestForVersion(version, forceRefresh = false) {
         throw new Error(`Failed to fetch guides manifest: ${err.message}`);
     }
 }
-async function fetchManifest(versionInfo, forceRefresh = false) {
+async function fetchManifest(branch, versionInfo, forceRefresh = false) {
     // Try the requested version first
-    const result = await fetchManifestForVersion(versionInfo.version, forceRefresh);
+    const result = await fetchManifestForVersion(branch, versionInfo.version, forceRefresh);
     if (result) {
         return { ...result, versionInfo };
     }
     // Version not found, fall back to latest (unless already trying latest)
     if (versionInfo.version !== "latest") {
-        const fallbackResult = await fetchManifestForVersion("latest", forceRefresh);
+        const fallbackResult = await fetchManifestForVersion(branch, "latest", forceRefresh);
         if (fallbackResult) {
             const fallbackInfo = {
                 version: "latest",
@@ -182,30 +430,133 @@ async function fetchManifest(versionInfo, forceRefresh = false) {
             return { ...fallbackResult, versionInfo: fallbackInfo };
         }
     }
-    throw new Error(`Failed to fetch guides manifest for ${versionInfo.version}`);
+    // Every candidate URL 404'd — the branch/version is genuinely absent. Signal
+    // this with a typed error so `resolveManifest` can tell it apart from a
+    // transport/server error (which arrives as a plain `Error` from
+    // `fetchManifestForVersion`) and only fall back to `main` in the former case.
+    throw new ManifestNotFoundError(`Failed to fetch guides manifest for ${versionInfo.version}`);
+}
+/**
+ * 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 async function resolveManifest(requestedBranch, versionInfo, forceRefresh = false) {
+    try {
+        const result = await fetchManifest(requestedBranch, versionInfo, forceRefresh);
+        return { ...result, branch: requestedBranch, requestedBranch, branchFellBack: false };
+    }
+    catch (err) {
+        // Only a genuinely-absent branch/version (a 404 on every candidate URL) may
+        // fall back to `main`. A transport/server error must surface — see the
+        // function doc.
+        if (!(err instanceof ManifestNotFoundError)) {
+            throw err;
+        }
+        if (requestedBranch === DEFAULT_DOCS_BRANCH) {
+            throw err; // already on main; nothing to fall back to
+        }
+        const result = await fetchManifest(DEFAULT_DOCS_BRANCH, versionInfo, forceRefresh);
+        return {
+            ...result,
+            branch: DEFAULT_DOCS_BRANCH,
+            requestedBranch,
+            branchFellBack: true,
+        };
+    }
 }
-async function fetchGuide(guide, version, forceRefresh = false) {
-    ensureCacheDir(version);
+/**
+ * One stderr line reporting the served docs branch, only when a non-`main`
+ * branch was requested (alpha detection or the override) — a plain `main`
+ * target prints nothing so stdout/stderr stay clean for the common case
+ * (#1463, behavior 8). Uses `info()` (stderr) so guide content on stdout is
+ * never polluted.
+ */
+function reportDocsBranch(resolved) {
+    if (resolved.requestedBranch === DEFAULT_DOCS_BRANCH)
+        return;
+    if (resolved.branchFellBack) {
+        info(`Guides branch: ${resolved.requestedBranch} unavailable; using main`);
+    }
+    else {
+        info(`Guides branch: ${resolved.requestedBranch}`);
+    }
+}
+/**
+ * Internal error thrown by `fetchGuide` on a non-ok guide-file response. NOT
+ * exported. `status` lets the `get` action distinguish a 404 (the cached
+ * manifest may name a file that was renamed/removed upstream — heal by
+ * refetching the manifest) from a transport error (keep the stale-cache
+ * fallback). `staleContent` carries the on-disk copy for the failed filename,
+ * if any, so the action can serve it as the option-(b) last resort (#1034).
+ */
+class GuideFetchError extends Error {
+    status;
+    selectedFile;
+    staleContent;
+    constructor(status, message, selectedFile, staleContent) {
+        super(message);
+        this.status = status;
+        this.selectedFile = selectedFile;
+        this.staleContent = staleContent;
+        this.name = "GuideFetchError";
+    }
+}
+/** Read an on-disk cached guide file, or undefined if absent/corrupted. */
+function readCachedGuide(cachedPath) {
+    if (!existsSync(cachedPath))
+        return undefined;
+    try {
+        return readFileSync(cachedPath, "utf-8");
+    }
+    catch {
+        return undefined; // corrupted cache
+    }
+}
+async function fetchGuide(guide, branch, version, request = {}, forceRefresh = false) {
+    ensureCacheDir(branch, version);
     const meta = loadCacheMeta();
-    const guideFileName = basename(guide.file);
-    const cachedPath = join(getGuidesCacheDir(version), guideFileName);
-    const fetchedAt = meta.guidesFetchedAt?.[version]?.[guide.topic];
+    // Resolve the variant filename for the requested (language, platform).
+    const { file: selectedFile } = selectVariant(guide, request);
+    const guideFileName = basename(selectedFile);
+    const cachedPath = join(getGuidesCacheDir(branch, version), guideFileName);
+    // Freshness is keyed by branch + the RESOLVED filename (not topic): a `ts`
+    // fetch cannot mark the `swift` variant fresh (#977), and a `next` fetch
+    // cannot mark the `main` copy of the same file fresh (#1463, behavior 7).
+    const fetchedAt = meta.guidesFetchedAt?.[branch]?.[version]?.[guideFileName];
     const cacheExpired = isCacheExpired(fetchedAt);
     const hasCachedGuide = existsSync(cachedPath);
     // If cache is valid and not forcing refresh, use it
     if (!forceRefresh && !cacheExpired && hasCachedGuide) {
         try {
             const content = readFileSync(cachedPath, "utf-8");
-            return { content, fromCache: true, stale: false };
+            return { content, fromCache: true, stale: false, selectedFile };
         }
         catch {
             // Cache corrupted, will fetch fresh
         }
     }
     // Try to fetch from network
-    const guideUrl = getGuideUrl(version, guide.file);
+    const guideUrl = buildGuideUrl(branch, version, selectedFile);
     try {
         const response = await fetchWithTimeout(guideUrl);
+        if (response.status === 404) {
+            // The cache-derived filename no longer exists upstream (a docs rename /
+            // removal). Let the 404 escape to the `get` action so it can refetch the
+            // manifest and re-resolve — heal must take priority over serving stale.
+            // Attach the on-disk copy (if any) so the action can serve it as the
+            // option-(b) last resort when the heal can't help (#1034).
+            throw new GuideFetchError(404, `Failed to fetch guide "${guide.topic}": HTTP 404: ${response.statusText}`, selectedFile, readCachedGuide(cachedPath));
+        }
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}: ${response.statusText}`);
         }
@@ -213,40 +564,101 @@ async function fetchGuide(guide, version, forceRefresh = false) {
         // Save to cache
         writeFileSync(cachedPath, content);
         meta.guidesFetchedAt = meta.guidesFetchedAt || {};
-        meta.guidesFetchedAt[version] = meta.guidesFetchedAt[version] || {};
-        meta.guidesFetchedAt[version][guide.topic] = new Date().toISOString();
+        meta.guidesFetchedAt[branch] = meta.guidesFetchedAt[branch] || {};
+        meta.guidesFetchedAt[branch][version] = meta.guidesFetchedAt[branch][version] || {};
+        meta.guidesFetchedAt[branch][version][guideFileName] = new Date().toISOString();
         saveCacheMeta(meta);
-        return { content, fromCache: false, stale: false };
+        return { content, fromCache: false, stale: false, selectedFile };
     }
     catch (err) {
-        // Network failed, try stale cache
-        if (hasCachedGuide) {
-            try {
-                const content = readFileSync(cachedPath, "utf-8");
-                return { content, fromCache: true, stale: true };
-            }
-            catch {
-                // Cache corrupted
-            }
+        // A 404 must reach the action (heal takes priority over stale) — re-throw it
+        // unchanged rather than serving the stale copy here.
+        if (err instanceof GuideFetchError && err.status === 404) {
+            throw err;
+        }
+        // Non-404 (transport error / 5xx): serve the stale on-disk copy if present
+        // (Fork F — transport problems are not manifest skew), else throw.
+        const stale = readCachedGuide(cachedPath);
+        if (stale !== undefined) {
+            return { content: stale, fromCache: true, stale: true, selectedFile };
         }
         throw new Error(`Failed to fetch guide "${guide.topic}": ${err.message}`);
     }
 }
+/** Normalize a guide's variants for display / --json output. */
+function normalizeVariants(guide) {
+    return (guide.variants ?? []).map((v) => ({
+        ...(v.language !== undefined ? { language: v.language } : {}),
+        ...(v.platform !== undefined ? { platform: v.platform } : {}),
+        file: v.file,
+    }));
+}
+/**
+ * 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 function formatLanguages(guide) {
+    const variants = guide.variants ?? [];
+    if (variants.length === 0)
+        return "default";
+    const languages = variants
+        .map((v) => v.language)
+        .filter((l) => l !== undefined);
+    if (languages.length === 0)
+        return "default";
+    return [...new Set(languages)].join("; ");
+}
+/**
+ * Render the manifest-level platform→language legend for `guides list`, e.g.
+ * `web -> ts, ios -> swift, macos -> swift`. When the manifest has no
+ * `platforms` block (older manifests / stale cache, before
+ * Primitive-Labs/primitive-docs#194), platforms aren't modeled yet, so this
+ * reports `none defined yet` rather than implying a map that doesn't exist.
+ */
+function formatPlatformsLegend(manifest) {
+    const platforms = manifest.platforms;
+    if (!platforms || Object.keys(platforms).length === 0) {
+        return "none defined yet";
+    }
+    return Object.entries(platforms)
+        .map(([platform, entry]) => `${platform} -> ${entry.language}`)
+        .join(", ");
+}
 export function registerGuidesCommands(program) {
     const guides = program
         .command("guides")
         .description("Access Primitive how-to guides for building apps")
         .addHelpText("after", `
 Examples:
-  $ primitive guides list              # List available guides
-  $ primitive guides list --json       # List as JSON for programmatic use
-  $ primitive guides get documents     # Fetch and display the documents guide
-  $ primitive guides get workflows     # Fetch and display the workflows guide
-  $ primitive guides list --version 1  # List guides for client v1
+  $ primitive guides list                          # List available guides + languages
+  $ primitive guides list --json                   # List as JSON for programmatic use
+  $ primitive guides get documents                 # Fetch the default (TS) documents guide
+  $ primitive guides get documents --language swift  # Fetch the Swift variant
+  $ primitive guides get documents --platform ios   # Fetch the platform's language (e.g. Swift)
+  $ primitive guides list --guide-version 1        # List guides for client v1
+  $ primitive guides list --guide-version latest   # List guides for the latest line
+
+Language & platform:
+  --language <ts|swift|...> fetches a specific language variant of a guide.
+  Aliases: typescript/javascript/js -> ts.
+  --platform <web|ios|macos|...> selects the language a platform targets: the
+  guides manifest maps each platform to its language (e.g. ios -> swift), so
+  'guides get documents --platform ios' returns the Swift guide. An explicit
+  --language always wins the language dimension.
+  Unknown --language values (always), and unknown --platform values (once the
+  manifest publishes its platform map), are rejected with a clear error listing
+  the supported values — mirroring 'init --platform'. Run 'guides list' to see
+  the supported languages and platforms.
 
 Versioning:
   By default, guides are fetched for the detected ${CLIENT_PACKAGE_NAME} version.
-  Use --version to explicitly request a specific major version.
+  Use --guide-version to explicitly request a specific major version (e.g. 1, 2,
+  or 'latest'). (The flag is --guide-version, not --version, because the root
+  'primitive --version' prints the CLI version and would otherwise swallow it.)
   Falls back to 'latest' if the version is not found.
 
 Cache:
@@ -259,19 +671,38 @@ Cache:
         .description("List available guides")
         .option("--json", "Output as JSON")
         .option("--refresh", "Force refresh from network")
-        .option("--version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .option("--guide-version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .option("--language <lang>", "Language to validate (ts, swift, ...; informational on list)")
+        .option("--platform <platform>", "Platform to validate (web, ios, macos, ...; informational on list)")
         .action(async (options) => {
         try {
-            const requestedVersion = resolveVersion(options.version);
-            const { manifest, stale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
+            const requestedVersion = resolveVersion(options.guideVersion);
+            const requestedBranch = resolveDocsBranchForInvocation();
+            const resolved = await resolveManifest(requestedBranch, requestedVersion, options.refresh);
+            const { manifest, stale, versionInfo, branch } = resolved;
+            // Validate the requested dimensions against the loaded manifest (same
+            // rules as `get`, for one mental model — Q3). They have no per-row
+            // effect on `list`, but an unknown value should fail loudly here too.
+            const resolution = validateAndResolveRequest(manifest, options.language, options.platform);
+            if (resolution.error) {
+                error(resolution.error);
+                process.exit(1);
+            }
+            const reqLanguage = normalizeLanguage(options.language);
+            const reqPlatform = normalizePlatform(options.platform);
+            const supportedLanguages = [...deriveLanguages(manifest)].sort();
+            // Report the served docs branch (stderr) when alpha/override is involved.
+            reportDocsBranch(resolved);
             if (stale) {
                 warn("Using stale cache (network unavailable)");
             }
             if (options.json) {
+                // The one list envelope (#3646): the guides are `items`, and the
+                // resolution context a caller needs to interpret them — which
+                // version and branch answered, which dimensions were asked for —
+                // sits beside the envelope's three keys.
                 json({
-                    version: versionInfo.version,
-                    versionSource: versionInfo.source,
-                    guides: manifest.guides.map((g) => ({
+                    ...wholeListEnvelope(manifest.guides.map((g) => ({
                         topic: g.topic,
                         description: g.description,
                         keywords: g.keywords,
@@ -279,7 +710,16 @@ Cache:
                         concepts: g.concepts,
                         prerequisites: g.prerequisites,
                         relatedGuides: g.relatedGuides,
-                    })),
+                        availableVariants: normalizeVariants(g),
+                    }))),
+                    version: versionInfo.version,
+                    versionSource: versionInfo.source,
+                    guidesBranch: branch,
+                    defaults: manifest.defaults ?? null,
+                    platforms: manifest.platforms ?? null,
+                    supportedLanguages,
+                    language: reqLanguage ?? null,
+                    platform: reqPlatform ?? null,
                 });
                 return;
             }
@@ -289,14 +729,41 @@ Cache:
             }
             keyValue("Client version", formatClientVersion(versionInfo));
             keyValue("Guides version", formatGuidesVersion(versionInfo));
+            // Manifest-level legend: spell out languages and the platform→language
+            // map explicitly, so `--language`/`--platform` are no longer ambiguous.
+            keyValue("Languages", supportedLanguages.join(", "));
+            keyValue("Platforms", formatPlatformsLegend(manifest));
             console.log("");
-            console.log(formatTable(manifest.guides, [
+            const rows = manifest.guides.map((g) => ({
+                topic: g.topic,
+                description: g.description,
+                languages: formatLanguages(g),
+            }));
+            // Size DESCRIPTION from the live terminal width so wide terminals show
+            // the full description (the guides.json contract budgets descriptions
+            // at <=100 chars; DESCRIPTION_MAX mirrors that cap — see
+            // primitive-docs `scripts/sync-guides-json.mjs`) while the table never
+            // wraps. Floor 48 keeps today's readable width on an 80-col terminal;
+            // on a non-TTY (piped) the column is sized to the cap so full
+            // descriptions reach `grep`/agents. `truncate` defensively clips a
+            // description that violates the upstream contract.
+            const DESCRIPTION_MAX = 100;
+            console.log(formatTable(rows, [
                 { header: "TOPIC", key: "topic" },
-                { header: "DESCRIPTION", key: "description", width: 60 },
+                {
+                    header: "DESCRIPTION",
+                    key: "description",
+                    flex: true,
+                    truncate: true,
+                    flexFloor: 48,
+                    flexMax: DESCRIPTION_MAX,
+                },
+                { header: "LANGUAGES", key: "languages" },
             ]));
             console.log("");
-            keyValue("Cache location", getVersionCacheDir(versionInfo.version));
-            info("Use 'primitive guides get <topic>' to fetch a guide.");
+            keyValue("Cache location", getVersionCacheDir(branch, versionInfo.version));
+            info("Use 'primitive guides get <topic> --language <ts|swift>' to fetch a guide.");
+            info("Example: primitive guides get documents --language swift");
         }
         catch (err) {
             error(err.message);
@@ -310,22 +777,50 @@ Cache:
         .argument("<topic>", "Guide topic (e.g., documents, workflows, prompts)")
         .option("--json", "Output metadata as JSON instead of content")
         .option("--refresh", "Force refresh from network")
-        .option("--version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .option("--guide-version <version>", "Fetch guides for a specific major version (e.g., 1, 2, or 'latest')")
+        .option("--language <lang>", "Language variant to fetch (ts, swift, ...; aliases typescript/javascript/js -> ts)")
+        .option("--platform <platform>", "Platform whose language to fetch (web, ios, macos, ...; inferred from the manifest)")
         .action(async (topic, options) => {
         try {
-            const requestedVersion = resolveVersion(options.version);
-            const { manifest, stale: manifestStale, versionInfo } = await fetchManifest(requestedVersion, options.refresh);
+            const requestedVersion = resolveVersion(options.guideVersion);
+            const requestedBranch = resolveDocsBranchForInvocation();
+            const resolved = await resolveManifest(requestedBranch, requestedVersion, options.refresh);
+            const { manifest, fromCache, stale: manifestStale, versionInfo, branch } = resolved;
             const guide = manifest.guides.find((g) => g.topic.toLowerCase() === topic.toLowerCase());
             if (!guide) {
                 const availableTopics = manifest.guides.map((g) => g.topic).join(", ");
                 error(`Guide "${topic}" not found. Available topics: ${availableTopics}`);
                 process.exit(1);
             }
+            // Validate both flags against the loaded manifest and resolve the
+            // effective language (issue #1219). An unknown value is a hard error;
+            // `--platform ios` infers its language (e.g. swift) when the manifest
+            // publishes a `platforms` block, while an explicit `--language` wins.
+            const resolution = validateAndResolveRequest(manifest, options.language, options.platform);
+            if (resolution.error) {
+                error(resolution.error);
+                process.exit(1);
+            }
+            // `reqLanguage` is the EFFECTIVE language after platform inference; pass
+            // it to both the JSON selection and the content fetch so they can't
+            // desynchronize.
+            const reqLanguage = resolution.language;
+            const reqPlatform = resolution.platform;
+            const requestedAnyDimension = normalizeLanguage(options.language) !== undefined ||
+                normalizePlatform(options.platform) !== undefined;
+            const selection = selectVariant(guide, {
+                language: reqLanguage,
+                platform: reqPlatform,
+            });
+            // Report the served docs branch (stderr) when alpha/override is involved.
+            reportDocsBranch(resolved);
             if (options.json) {
-                // Output just metadata
+                // Output just metadata — does NOT fetch content. `selectedFile` is the
+                // file that WOULD be served for this request (see selection above).
                 json({
                     version: versionInfo.version,
                     versionSource: versionInfo.source,
+                    guidesBranch: branch,
                     topic: guide.topic,
                     description: guide.description,
                     keywords: guide.keywords,
@@ -333,16 +828,79 @@ Cache:
                     concepts: guide.concepts,
                     prerequisites: guide.prerequisites,
                     relatedGuides: guide.relatedGuides,
-                    cacheLocation: join(getGuidesCacheDir(versionInfo.version), basename(guide.file)),
+                    language: reqLanguage ?? null,
+                    platform: reqPlatform ?? null,
+                    defaultPlatform: manifest.defaults?.platform ?? null,
+                    selectedFile: selection.file,
+                    matchedOn: selection.matchedOn,
+                    availableVariants: normalizeVariants(guide),
+                    cacheLocation: join(getGuidesCacheDir(branch, versionInfo.version), basename(selection.file)),
                 });
                 return;
             }
-            const { content, stale: guideStale } = await fetchGuide(guide, versionInfo.version, options.refresh);
-            if (manifestStale || guideStale) {
+            const request = { language: reqLanguage, platform: reqPlatform };
+            let result;
+            try {
+                result = await fetchGuide(guide, branch, versionInfo.version, request, options.refresh);
+            }
+            catch (err) {
+                // Only a 404 is healable here. Transport errors already served stale
+                // (or threw) inside fetchGuide; rethrow anything that isn't a 404.
+                if (!(err instanceof GuideFetchError && err.status === 404)) {
+                    throw err;
+                }
+                // Heal only when the manifest came from cache — then the named file
+                // may have been renamed/removed upstream while our manifest is stale.
+                // Force a manifest refetch, re-find the topic, and retry the file
+                // ONCE. A fresh-from-network manifest (incl. --refresh) makes the 404
+                // authoritative, so we skip straight to the last resort below (#1034).
+                if (fromCache) {
+                    try {
+                        // Heal on the SAME branch the manifest resolved on, so the
+                        // manifest and guide never disagree (#1463, behavior 4).
+                        const refreshed = await fetchManifest(branch, requestedVersion, /* forceRefresh */ true);
+                        const freshGuide = refreshed.manifest.guides.find((g) => g.topic.toLowerCase() === topic.toLowerCase());
+                        if (freshGuide) {
+                            // Re-calling fetchGuide recomputes selectVariant + the cache path
+                            // for the (possibly new) filename — no extra resolve site. If the
+                            // filename is unchanged it just 404s again and falls through.
+                            const retried = await fetchGuide(freshGuide, branch, refreshed.versionInfo.version, request, options.refresh);
+                            if (basename(retried.selectedFile) !== basename(err.selectedFile)) {
+                                warn(`Guide "${topic}" file moved upstream; refreshed manifest and retried.`);
+                            }
+                            result = retried;
+                        }
+                    }
+                    catch {
+                        // Heal failed (manifest refetch failed / retry 404'd / topic gone)
+                        // → fall through to the option-(b) last resort on the ORIGINAL error.
+                    }
+                }
+                // Option (b) last resort — applies to ALL 404s, not just cached-manifest
+                // ones, so `--refresh`-on-404 still serves an old on-disk copy as it
+                // does today. Serve the old copy if we have one; otherwise surface the
+                // original terminal 404.
+                if (!result) {
+                    if (err.staleContent !== undefined) {
+                        result = { content: err.staleContent, stale: true, selectedFile: err.selectedFile };
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+            if (manifestStale || result.stale) {
                 warn("Using stale cache (network unavailable)");
             }
+            // Transparency note (issue #1219): a language/platform was requested but
+            // this topic has no variant pinning it, so the default file was served.
+            // This closes the residual silent-fallback footgun beyond `--platform`.
+            // The note goes to STDERR (via `info`) so stdout stays clean for piping.
+            if (requestedAnyDimension && selection.matchedOn === "default") {
+                info(`No ${reqLanguage ?? reqPlatform} variant for "${guide.topic}"; served the default guide.`);
+            }
             // Print the guide content directly to stdout
-            console.log(content);
+            console.log(result.content);
         }
         catch (err) {
             error(err.message);