@thallylabs/migrate 0.2.27 → 0.2.28

package/dist/url-migration-CDjLZVaN.d.ts

@@ -0,0 +1,512 @@
+/**
+ * Provider-neutral, JSON-safe migration journal. Captures are inert evidence;
+ * hosts own network restrictions, browser sessions and durable artifact storage.
+ */
+
+interface MigrationNavigationOccurrence {
+    label: string;
+    url?: string;
+    children?: Array<MigrationNavigationOccurrence>;
+}
+interface MigrationCaptureState {
+    id: string;
+    /** Human-readable name of a tab/disclosure alternative, never executable code. */
+    label: string;
+    response: MigrationFetchResponse;
+}
+interface MigrationCapturedAsset {
+    url: string;
+    contentType: string;
+    content: Uint8Array;
+}
+interface MigrationCapture extends MigrationFetchResponse {
+    /** Capture adapters expand only safe read-only states; no forms or API actions. */
+    states?: Array<MigrationCaptureState>;
+    navigation?: Array<MigrationNavigationOccurrence>;
+    assets?: Array<MigrationCapturedAsset>;
+    locale?: string;
+    version?: string;
+    /** Durable evidence reference supplied by the host; no embedded credentials. */
+    artifactRef?: string;
+}
+interface MigrationCaptureProvider {
+    capture(request: {
+        url: URL;
+        signal?: AbortSignal;
+    }): Promise<MigrationCapture>;
+}
+interface MigrationEvidence {
+    sha256: string;
+    byteLength?: number;
+    finalUrl: string;
+    contentType: string;
+    artifactRef?: string;
+    states: Array<{
+        id: string;
+        label: string;
+        sha256: string;
+        code?: Array<string>;
+    }>;
+    /** Exact decoded technical payloads, including whitespace and trailing newlines. */
+    code: Array<string>;
+    anchors: Array<string>;
+    links: Array<string>;
+}
+interface MigrationJournalAsset {
+    url: string;
+    path: string;
+    contentType: string;
+    sha256: string;
+    /** Base64 keeps checkpoints portable through JSON persistence. */
+    base64: string;
+}
+interface UrlMigrationRecord {
+    url: string;
+    discoveredBy: Array<string>;
+    outcome: 'pending' | 'imported' | 'excluded' | 'failed' | 'alias';
+    reason?: string;
+    aliasOf?: string;
+    evidence?: MigrationEvidence;
+    page?: MigrationPage;
+    pageSha256?: string;
+    assets?: Array<MigrationJournalAsset>;
+    version?: string;
+    issues?: Array<UrlMigrationIssue>;
+}
+interface UrlMigrationCheckpoint {
+    schemaVersion: 1;
+    converterVersion: string;
+    sourceUrl: string;
+    scopePath: string;
+    captureVersion: string;
+    records: Array<UrlMigrationRecord>;
+    navigation: Array<MigrationNavigationOccurrence>;
+}
+interface UrlMigrationCheckpointDelta {
+    schemaVersion: 1;
+    converterVersion: string;
+    scopePath: string;
+    captureVersion: string;
+    sourceUrl: string;
+    /** Changed records only, replace by URL. Commit evidence before acknowledging. */
+    records: Array<UrlMigrationRecord>;
+    navigation?: Array<MigrationNavigationOccurrence>;
+}
+interface UrlMigrationIssue {
+    code: 'missing-page' | 'missing-anchor' | 'code-mismatch' | 'asset-failed' | 'unsafe-content' | 'unsupported-component' | 'navigation-missing' | 'collision';
+    source: string;
+    message: string;
+}
+interface UrlMigrationValidation {
+    status: 'passed' | 'partial' | 'cancelled';
+    issues: Array<UrlMigrationIssue>;
+    counts: Record<UrlMigrationRecord['outcome'], number>;
+}
+interface UrlMigrationRun {
+    bundle: MigrationBundle;
+    checkpoint: UrlMigrationCheckpoint;
+    validation: UrlMigrationValidation;
+    /** Hosts resume bounded slices but must review hard scope/budget limits. */
+    stopReason?: 'capture-limit' | 'page-limit' | 'byte-limit' | 'cancelled' | 'complete';
+}
+interface UrlMigrationRunOptions {
+    sourceUrl: string;
+    platform?: MigrationPlatform;
+    /** Exact selected path boundary; defaults to the submitted URL directory. */
+    scopePath?: string;
+    maxPages?: number;
+    concurrency?: number;
+    batchSize?: number;
+    maxTotalBytes?: number;
+    fetcher?: MigrationFetcher;
+    /** Hosts that inject text fetching must also inject their safe binary boundary. */
+    assetFetcher?: (url: URL, signal?: AbortSignal) => Promise<MigrationCapturedAsset>;
+    captureProvider?: MigrationCaptureProvider;
+    /** Change this when browser/extraction policy changes; prevents stale reuse. */
+    captureVersion?: string;
+    checkpoint?: UrlMigrationCheckpoint;
+    signal?: AbortSignal;
+    /** Stop after this many captures and return a resumable partial result. */
+    maxCaptures?: number;
+    /** Retry transient failures by default; imported records still require hashes. */
+    retryFailed?: boolean;
+    /** Reconcile durable artifacts; false requeues a previously committed record. */
+    reconcile?: (record: UrlMigrationRecord) => Promise<boolean>;
+    /** Bounded deltas avoid serializing the whole inventory after every page. */
+    onCheckpoint?: (delta: UrlMigrationCheckpointDelta) => Promise<void>;
+    /** Stream evidence/output to durable storage before a record is committed. */
+    onRecord?: (record: UrlMigrationRecord) => Promise<void>;
+}
+
+/**
+ * Canonical migration contracts shared by repository, CLI, MCP, and hosted
+ * import paths. Callers materialize this bundle only after discovery and
+ * normalization finish, so a partial crawl can never leave a half-written site.
+ */
+type MigrationPlatform = 'mintlify' | 'docusaurus' | 'fern' | 'gitbook' | 'nextra' | 'vitepress' | 'starlight' | 'thally' | 'generic' | 'unknown';
+interface MigrationNavigationGroup {
+    defaultOpen?: boolean;
+    group: string;
+    icon?: string;
+    hidden?: boolean;
+    pages: Array<string | MigrationNavigationGroup>;
+}
+interface MigrationNavigationTab {
+    tab: string;
+    /** Reader-facing label when `tab` includes a version for unique identity. */
+    displayLabel?: string;
+    version?: string;
+    description?: string;
+    icon?: string;
+    href?: string;
+    hidden?: boolean;
+    /** Root page/group nodes used when the source has no synthetic section heading. */
+    pages?: Array<string | MigrationNavigationGroup>;
+    groups?: Array<MigrationNavigationGroup>;
+    api?: {
+        source: string;
+        navigation?: boolean;
+    };
+}
+interface MigrationBannerConfig {
+    content: string | Record<string, string>;
+    dismissible?: boolean;
+    id?: string;
+    revision?: string;
+    type?: 'info' | 'warning' | 'critical';
+    color?: {
+        light?: string;
+        dark?: string;
+    };
+}
+interface MigrationNavbarConfig {
+    links?: Array<{
+        label: string;
+        href: string;
+        type?: 'github';
+        button?: {
+            background: string;
+            color?: string;
+        };
+    }>;
+    /** Explicit null suppresses the starter's sample call to action. */
+    primary?: {
+        label: string;
+        href: string;
+        type?: 'github';
+    } | null;
+    /** Local public assets used until an owner uploads a brand replacement. */
+    /** Explicit null requests a text-only brand when the source has no logo. */
+    logo?: {
+        light: string;
+        dark?: string;
+        showTitle?: boolean;
+        rightText?: string;
+    } | null;
+}
+interface MigrationFooterConfig {
+    socials?: Record<string, string>;
+    /** Literal footer attribution; `{year}` is resolved by the site at render time. */
+    copyright?: string;
+    links?: Array<{
+        heading: string;
+        items: Array<{
+            label: string;
+            href: string;
+        }>;
+    }>;
+}
+interface MigrationDocsConfig {
+    markdown?: {
+        enabled?: boolean;
+    };
+    /** Local site-authored CSS projected from a source docs site, served from public/. */
+    stylesheets?: Array<string>;
+    /** `false` hides the breadcrumb trail; Mintlify pages show only a group eyebrow. */
+    breadcrumbs?: boolean;
+    tabs: Array<MigrationNavigationTab>;
+    navigation?: {
+        /** How sibling documentation collections are presented to readers. */
+        display?: 'tabs' | 'dropdown';
+        versions?: Array<{
+            label: string;
+            prefix: string;
+            href: string;
+            default?: boolean;
+            hidden?: boolean;
+        }>;
+        shortcuts?: Array<{
+            label: string;
+            href: string;
+            icon?: string;
+        }>;
+    };
+    theme?: 'default' | 'maple' | 'sharp' | 'minimal';
+    appearance?: {
+        default?: 'system' | 'light' | 'dark';
+        showToggle?: boolean;
+    };
+    background?: {
+        image?: string;
+        imageDark?: string;
+        decoration?: 'none' | 'grid' | 'gradient';
+    };
+    /** Icon set for content `icon` names; Mintlify's `icons.library` carries through. */
+    contextual?: {
+        options?: Array<string>;
+    };
+    colors?: Partial<Record<'light' | 'dark', {
+        primary?: string;
+        accent?: string;
+    }>>;
+    icons?: {
+        library?: 'lucide' | 'fontawesome' | 'tabler';
+    };
+    banner?: MigrationBannerConfig;
+    navbar?: MigrationNavbarConfig;
+    favicon?: {
+        light: string;
+        dark?: string;
+    };
+    footer?: MigrationFooterConfig;
+    seo?: {
+        indexing?: 'navigable' | 'all';
+        titleSeparator?: string;
+        sitemap?: 'navigable';
+        metatags?: Record<string, string>;
+    };
+    fonts?: {
+        body?: {
+            family: string;
+            weight?: Array<string>;
+        };
+        heading?: {
+            family: string;
+            weight?: Array<string>;
+        };
+    };
+    feedback?: {
+        thumbsRating?: boolean;
+    };
+    customScripts?: Array<{
+        src: string;
+        strategy?: 'beforeInteractive' | 'afterInteractive' | 'lazyOnload';
+    }>;
+    ai?: {
+        chat?: boolean;
+        label?: string;
+        icon?: string;
+    };
+    admin?: {
+        enabled?: boolean;
+    };
+    analytics?: {
+        enabled?: boolean;
+    };
+    /** Manual API pages: default server(s) and auth for `api:` frontmatter pages. */
+    api?: {
+        mdx?: {
+            server?: string | Array<string>;
+            auth?: {
+                method?: 'bearer' | 'basic' | 'key';
+                name?: string;
+            };
+        };
+        /** Mintlify `api.playground.display`; `auth` is carried as `simple`. */
+        playground?: {
+            display: 'interactive' | 'simple' | 'none';
+        };
+        /** `false` hides the visible "OpenAPI specification" line; Mintlify does not show it. */
+        specLink?: boolean;
+    };
+    /** Third-party analytics in Mintlify's `integrations` shape; validated again by the renderer. */
+    integrations?: {
+        ga4?: {
+            measurementId: string;
+        };
+        gtm?: {
+            tagId: string;
+        };
+        posthog?: {
+            apiKey: string;
+            apiHost?: string;
+            sessionRecording?: boolean;
+        };
+        plausible?: {
+            domain: string;
+            server?: string;
+        };
+    };
+    redirects?: Array<{
+        source: string;
+        destination: string;
+        permanent?: boolean;
+    }>;
+    i18n?: {
+        defaultLocale: string;
+        locales: Array<{
+            code: string;
+            label: string;
+        }>;
+        /** Source-authored navigation labels and ordering for each translation. */
+        navigation?: Record<string, Array<MigrationNavigationTab>>;
+    };
+}
+interface MigrationPage {
+    /** Path below `src/content`, without the `.mdx` extension. */
+    id: string;
+    /** Locale-independent page id used by the shared navigation projection. */
+    navigationId: string;
+    locale?: string;
+    title: string;
+    /** Authored display H1 when the source uses a different metadata title. */
+    headingTitle?: string;
+    navTitle?: string;
+    /** Sidebar icon name or image URL from page frontmatter, with its optional style. */
+    icon?: string;
+    iconType?: 'regular' | 'solid' | 'outline' | 'brands';
+    description: string;
+    /** Keep SEO/search description without repeating it above Docusaurus body copy. */
+    descriptionPlacement?: 'body';
+    badge?: string;
+    keywords: Array<string>;
+    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. */
+    openapi?: string;
+    /** Manual API page: `METHOD <url-or-path>`; rendered by Thally's playground. */
+    api?: string;
+    /** Page-level playground auth override: bearer | basic | key | none. */
+    authMethod?: string;
+    /** Page-level `playground` override: interactive | simple | none (`auth` becomes `simple`). */
+    playground?: 'interactive' | 'simple' | 'none';
+    body: string;
+    source: string;
+    /** Set when the page's frontmatter was invalid YAML; the page is kept with a best-effort salvage. */
+    frontmatterError?: string;
+}
+interface MigrationAsset {
+    /** Path below `public` (or below the project root when `projectRelative`), always normalized and traversal-free. */
+    path: string;
+    content: Uint8Array;
+    /** Write at the project root instead of `public/`, so the host never serves it statically. */
+    projectRelative?: boolean;
+}
+interface MigrationWarning {
+    code: 'collision' | 'invalid-page' | 'missing-page' | 'unsupported-config' | 'limit-reached' | 'fetch-failed' | 'skipped-file'
+    /** Access-restricted source content: migrated with access rules, withheld (quarantined), or a site-wide auth risk. */
+     | 'gated-page';
+    message: string;
+    source?: string;
+}
+/** A repository-configured remote OpenAPI spec, downloaded after the bundle is built. */
+interface RemoteApiSpec {
+    url: string;
+    tabLabel?: string;
+    parentTab?: string;
+    icon?: string;
+    hidden?: boolean;
+    /** Operation keys (`get /x`) only access-restricted pages document; marked `x-excluded` after download. */
+    withheldOperations?: Array<string>;
+    /** Operation keys published pages or docs.json also name; keeps a shared `$ref` path item public. */
+    keptOperations?: Array<string>;
+}
+interface MigrationBundle {
+    sourceUrl: string;
+    sourceKind: 'repository' | 'url';
+    platform: MigrationPlatform;
+    pages: Array<MigrationPage>;
+    assets: Array<MigrationAsset>;
+    /** Repository-configured remote specs awaiting a bounded network fetch by the host. */
+    remoteApiSpecs?: Array<RemoteApiSpec>;
+    /** Customer-owned component source and registry; paths are repository-relative. */
+    componentFiles?: Array<RenderedMigrationFile>;
+    /**
+     * 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;
+    /** Mintlify `sourceRef` repositories imported under a mount path, with their page counts. */
+    sourceRefs?: Array<{
+        repo: string;
+        mountPath: string;
+        pages: number;
+    }>;
+    docsConfig: MigrationDocsConfig;
+    site?: {
+        name?: string;
+        description?: string;
+        /**
+         * Source theme accent color(s), each a `#rrggbb`/`#rgb` hex string.
+         * Follows Mintlify's own `colors` schema: `light` is the color used in
+         * dark mode and `dark` is the color used in light mode. Fern's colors
+         * are normal (its `light`/`dark` match the mode they paint), so
+         * extraction swaps them onto this shape for a single downstream contract.
+         */
+        colors?: {
+            primary?: string;
+            light?: string;
+            dark?: string;
+        };
+    };
+    warnings: Array<MigrationWarning>;
+    /** Evidence checks are independent of whether generated site code builds. */
+    urlMigrationValidation?: UrlMigrationValidation;
+    stats: {
+        discovered: number;
+        imported: number;
+        skipped: number;
+    };
+}
+interface MigrationFetchRequest {
+    accept: string;
+}
+interface MigrationFetchResponse {
+    finalUrl: URL;
+    body: string;
+    contentType: string;
+    /** Capture adapters should retain target errors even when provider calls succeed. */
+    status?: number;
+    headers?: Record<string, string | undefined>;
+}
+/**
+ * Network boundary injected by each host. Thally Cloud supplies a DNS-pinned,
+ * SSRF-safe implementation; the local CLI uses the user's normal network.
+ */
+type MigrationFetcher = (url: URL, request: MigrationFetchRequest) => Promise<MigrationFetchResponse>;
+interface RenderedMigrationFile {
+    path: string;
+    content: string | Uint8Array;
+}
+
+/** Render canonical migration bundles into a portable Thally repository tree. */
+
+/** Merge imported tabs into an existing site without duplicating changelog tabs. */
+declare function mergeMigrationConfig(existing: MigrationDocsConfig, incoming: MigrationDocsConfig): MigrationDocsConfig;
+/** Materialize every canonical page, asset, and config as repository file changes. */
+declare function renderMigrationFiles(bundle: MigrationBundle, options?: {
+    existingConfig?: MigrationDocsConfig;
+    existingComponentRegistry?: string;
+}): Array<RenderedMigrationFile>;
+
+/** Classify using the final response; an index must never become article text. */
+declare function classifyMigrationResponse(document: MigrationFetchResponse): 'page' | 'index' | 'asset' | 'unsupported';
+/** Validate every selected outcome, source payload, internal destination and anchor. */
+declare function validateUrlMigration(checkpoint: UrlMigrationCheckpoint, cancelled?: boolean): UrlMigrationValidation;
+/** Run capture/conversion in bounded batches and resume only reconciled artifacts. */
+declare function runUrlMigration(options: UrlMigrationRunOptions): Promise<UrlMigrationRun>;
+
+export { runUrlMigration as A, validateUrlMigration as B, type MigrationPage as M, type RenderedMigrationFile as R, type UrlMigrationCheckpoint as U, type MigrationAsset as a, type MigrationNavigationGroup as b, type MigrationWarning as c, type MigrationFetcher as d, type MigrationPlatform as e, type MigrationBundle as f, type MigrationDocsConfig as g, type MigrationCapture as h, type MigrationCaptureProvider as i, type MigrationCaptureState as j, type MigrationCapturedAsset as k, type MigrationEvidence as l, type MigrationFetchRequest as m, type MigrationFetchResponse as n, type MigrationJournalAsset as o, type MigrationNavigationOccurrence as p, type MigrationNavigationTab as q, type UrlMigrationCheckpointDelta as r, type UrlMigrationIssue as s, type UrlMigrationRecord as t, type UrlMigrationRun as u, type UrlMigrationRunOptions as v, type UrlMigrationValidation as w, classifyMigrationResponse as x, mergeMigrationConfig as y, renderMigrationFiles as z };

package/dist/url-migration.d.ts

@@ -0,0 +1 @@
+export { a as MigrationAsset, f as MigrationBundle, h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, g as MigrationDocsConfig, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, d as MigrationFetcher, o as MigrationJournalAsset, b as MigrationNavigationGroup, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, M as MigrationPage, e as MigrationPlatform, c as MigrationWarning, R as RenderedMigrationFile, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-migration-CDjLZVaN.js';