@thallylabs/migrate 0.2.25 → 0.2.26

package/README.md

@@ -332,30 +332,43 @@ generic unknown-component fallback.
 
 ### Access-restricted pages
 
-A gated Mintlify page must never migrate as public. A page is withheld when its
-frontmatter sets a non-empty `groups` (list or string) or `public: false`
-(also `"false"`, `no`, `off`, `0`; empty `groups` restricts nothing), or when it sits
-under a navigation group or tab that sets `groups` (a list of strings) or
-`public: false`. `public: true` alone is not gating. Withheld pages are not
-written to `src/content` and are removed from navigation (emptied groups and
-tabs included), whether or not navigation lists them. The original file is
-written unchanged to `migration-quarantine/<original path>` at the project
-root, which no runtime content reader, search index, or `llms` output walks;
-`create-thally-docs` also adds it to the project's `.gitignore` (appended once,
-existing entries kept) so it is never committed or pushed. A public page that
-imports a withheld page as a component does not inline it (a `gated-page`
-warning names the importer). Invalid frontmatter fails the run rather than
-importing the page. Each page gets a
-`gated-page` warning, plus a summary; `create-thally-docs` prints these last
-under an "ACCESS-RESTRICTED CONTENT" heading and the report records them and a
-`quarantined` count. Links from other pages to a withheld page are left as
-authored and will fail `thally check`; images and other assets used only by
-gated pages are still copied to `public/`. Mintlify's site-wide authentication mode lives in its
-dashboard and cannot be read from a repository, so when any page sets
+Restricted Mintlify pages migrate as real pages with normalized access
+frontmatter that the Thally runtime enforces (see `/guides/authenticated-docs`):
+
+- Frontmatter `groups` becomes a list of trimmed group names (`groups: admin`
+  and `groups: "a, b"` become lists); `public` becomes a boolean (`"false"`,
+  `no`, `off`, `0` are `false`; `true`/`"true"` is `true`). Empty `groups`
+  restricts nothing.
+- Rules on navigation containers (a group, tab, version, dropdown, anchor,
+  language, or `menu` item) are pushed down into the frontmatter of every page
+  below them, because the runtime reads access only from pages: container
+  `groups` (a list of strings) and `public: false` restrict, and Mintlify's
+  group-level `public: true` opens pages that name no groups of their own.
+  Pages stay in navigation where they were.
+- Rules combine to the strictest: nested and page group lists intersect,
+  `public: false` anywhere wins, and a page listed under both an open and a
+  restricted container gets the restricted rule.
+
+A page whose rules cannot be carried over safely fails closed instead: a
+malformed value (`public: maybe`, `groups: [1]`), group lists that share no
+group, or frontmatter that declares `groups`/`public` but cannot be parsed or
+read. Such a page is not written to `src/content`, is removed from navigation,
+and its original is written unchanged to `migration-quarantine/<original path>`
+at the project root, which no runtime reader walks; `create-thally-docs` adds
+that folder to `.gitignore`. Each quarantined page gets a `gated-page` warning.
+
+What a restricted page uses must not leak through surfaces that are not access
+controlled: it is never inlined into another page (a `gated-page` warning names
+the importer), images and other assets used only by restricted pages are not
+copied to `public/` (they are saved under `migration-quarantine/assets/`), and
+OpenAPI operations documented only on restricted pages are withheld from the
+published spec. One `gated-page` summary counts the restricted pages and notes
+that Thally hides them from everyone until reader authentication is configured
+in `docs.json` `auth`; no `auth` block is generated, because Mintlify's
+dashboard settings cannot be read from a repository. When any page sets
 `public: true` (which implies the source site required sign-in for everything
-else) one `gated-page` warning says Thally will publish every imported page.
-Restricted-container `groups` and `public: false` are honored fail-closed even
-though Mintlify documents only `"public": true` on a group.
+else), one more `gated-page` warning says every unrestricted page will be
+public until `auth` is configured.
 
 ### Site-wide scripts, styles, fonts, and settings
 

package/dist/index.d.ts

@@ -230,6 +230,13 @@ interface MigrationPage {
     mode?: 'default' | 'wide' | 'custom' | 'center' | 'home';
     hidden?: boolean;
     noindex?: boolean;
+    /**
+     * Reader access groups (frontmatter `groups`): trimmed, non-empty names the
+     * runtime matches exactly. The page needs a signed-in reader in one of them.
+     */
+    groups?: Array<string>;
+    /** Frontmatter `public`: `true` opens the page to anyone, `false` needs any signed-in reader. */
+    public?: boolean;
     /** Social/SEO overrides from `og:*` and `twitter:*` frontmatter, keyed by the migrated frontmatter field. */
     meta?: Partial<Record<'ogTitle' | 'ogDescription' | 'ogImage' | 'twitterTitle' | 'twitterDescription' | 'twitterImage', string>>;
     /** OpenAPI operation key rendered by Thally instead of ordinary MDX. */
@@ -254,7 +261,7 @@ interface MigrationAsset {
 }
 interface MigrationWarning {
     code: 'collision' | 'invalid-page' | 'missing-page' | 'unsupported-config' | 'limit-reached' | 'fetch-failed' | 'skipped-file'
-    /** Access-restricted source page withheld from the published site (or a site-wide auth risk). */
+    /** Access-restricted source content: migrated with access rules, withheld (quarantined), or a site-wide auth risk. */
      | 'gated-page';
     message: string;
     source?: string;
@@ -281,7 +288,11 @@ interface MigrationBundle {
     remoteApiSpecs?: Array<RemoteApiSpec>;
     /** Customer-owned component source and registry; paths are repository-relative. */
     componentFiles?: Array<RenderedMigrationFile>;
-    /** Access-restricted source pages, written outside every published path. */
+    /**
+     * Restricted content that cannot be published safely (pages whose access
+     * rules are malformed or contradictory, and assets used only by restricted
+     * pages), written outside every published path.
+     */
     quarantinedFiles?: Array<RenderedMigrationFile>;
     /** Access-restricted pages the file limit dropped: neither published nor saved in quarantinedFiles. */
     droppedGatedPages?: number;
@@ -448,6 +459,30 @@ declare function detectRepositoryDocsDir(repositoryDir: string): string;
 /** Import an already-available repository directory into a canonical bundle. */
 declare function migrateRepository(options: RepositoryMigrationOptions): MigrationBundle;
 
+/**
+ * Mintlify-only helpers: page access rules, site-wide CSS/JS/font assets,
+ * and appearance settings. Kept apart from the generic repository walk so the
+ * rules that decide how restricted pages migrate (and what is quarantined)
+ * are auditable in one place.
+ *
+ * Access invariant: a restricted page migrates with normalized `groups` /
+ * `public` frontmatter that the Thally runtime enforces; anything ambiguous
+ * (malformed values, group lists that share no group) fails closed and the
+ * page is quarantined instead.
+ */
+
+/** Access imposed by every navigation container above one appearance of a page. */
+interface NavigationAccess {
+    /** Intersection of every container group list on the path. */
+    groups?: Array<string>;
+    /** Some container on the path sets `public: false`. */
+    hasPublicFalse: boolean;
+    /** Some container on the path sets `public: true` (Mintlify's documented group flag). */
+    hasPublicTrue: boolean;
+    /** Set when a container value is malformed or nested group lists share no group. */
+    problem?: string;
+}
+
 /**
  * Navigation projection for imported sites. Mintlify's schema is intentionally
  * more expressive than Thally's tab/group model, so complex containers are
@@ -459,16 +494,24 @@ interface MintlifyPageReference {
     navigationId: string;
     locale?: string;
 }
-/** A page listed under an access-restricted navigation container. */
-interface MintlifyGatedReference {
+/**
+ * One appearance of a page reference in navigation, with the access rules of
+ * every container above it. Thally reads access only from page frontmatter,
+ * so these are pushed down into the frontmatter of the pages they cover.
+ */
+interface MintlifyReferenceAccess {
     ref: string;
-    reason: string;
+    access: NavigationAccess;
 }
 interface MintlifyNavigationResult {
     docsConfig: MigrationDocsConfig;
     pageReferences: Array<MintlifyPageReference>;
-    /** Pages under a restricted container; withheld from `docsConfig` and `pageReferences`. */
-    gatedReferences: Array<MintlifyGatedReference>;
+    /**
+     * Access imposed by navigation containers, one entry per appearance of a
+     * page (open appearances included, so a page listed in several places can
+     * be given the strictest rule). Restricted pages stay in `docsConfig`.
+     */
+    referenceAccess: Array<MintlifyReferenceAccess>;
     /** `sourceRef` mounts under a restricted container; never resolved, so nothing of theirs is imported. */
     gatedSourceRefs: Array<string>;
     warnings: Array<MigrationWarning>;