@thallylabs/migrate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Thally Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# `@thallylabs/migrate`
+
+The shared migration engine used by the Thally CLI, MCP server, and Thally
+Cloud. It imports documentation repositories and public documentation URLs
+into one canonical bundle before any caller writes files.

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * 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' | 'gitbook' | 'nextra' | 'vitepress' | 'starlight' | 'thally' | 'generic' | 'unknown';
+interface MigrationNavigationGroup {
+    group: string;
+    icon?: string;
+    pages: Array<string | MigrationNavigationGroup>;
+}
+interface MigrationNavigationTab {
+    tab: string;
+    href?: string;
+    groups?: Array<MigrationNavigationGroup>;
+    api?: {
+        source: string;
+    };
+}
+interface MigrationDocsConfig {
+    tabs: Array<MigrationNavigationTab>;
+    theme?: 'default' | 'maple' | 'sharp' | 'minimal';
+    ai?: {
+        chat?: boolean;
+        label?: string;
+        icon?: string;
+    };
+    admin?: {
+        enabled?: boolean;
+    };
+    analytics?: {
+        enabled?: boolean;
+    };
+    redirects?: Array<{
+        source: string;
+        destination: string;
+        permanent?: boolean;
+    }>;
+    i18n?: {
+        defaultLocale: string;
+        locales: Array<{
+            code: string;
+            label: string;
+        }>;
+    };
+}
+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;
+    description: string;
+    keywords: Array<string>;
+    body: string;
+    source: string;
+}
+interface MigrationAsset {
+    /** Path below `public`, always normalized and traversal-free. */
+    path: string;
+    content: Uint8Array;
+}
+interface MigrationWarning {
+    code: 'collision' | 'invalid-page' | 'missing-page' | 'unsupported-config' | 'limit-reached' | 'fetch-failed' | 'skipped-file';
+    message: string;
+    source?: string;
+}
+interface MigrationBundle {
+    sourceUrl: string;
+    sourceKind: 'repository' | 'url';
+    platform: MigrationPlatform;
+    pages: Array<MigrationPage>;
+    assets: Array<MigrationAsset>;
+    docsConfig: MigrationDocsConfig;
+    warnings: Array<MigrationWarning>;
+    stats: {
+        discovered: number;
+        imported: number;
+        skipped: number;
+    };
+}
+interface MigrationFetchRequest {
+    accept: string;
+}
+interface MigrationFetchResponse {
+    finalUrl: URL;
+    body: string;
+    contentType: string;
+    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;
+}
+
+/**
+ * Repository adapter for the shared migration engine. Traversal is bounded,
+ * symbolic links are ignored, and Git is always invoked with an argument array
+ * so source-controlled branch names can never become shell commands.
+ */
+
+interface GitHubRepositorySource {
+    owner: string;
+    repo: string;
+    branch: string;
+    docsDir: string;
+    cloneUrl: string;
+}
+interface RepositoryMigrationOptions {
+    repositoryDir: string;
+    sourceUrl: string;
+    docsDir?: string;
+    platform?: MigrationPlatform;
+}
+/** Parse and validate a public GitHub repository URL. */
+declare function parseGitHubRepositoryUrl(rawUrl: string): GitHubRepositorySource;
+/** Clone a repository without a shell; callers own and remove `targetDir`. */
+declare function cloneGitHubRepository(source: GitHubRepositorySource, targetDir: string): Promise<void>;
+/** Detect a supported repository docs platform from unambiguous config files. */
+declare function detectRepositoryPlatform(repositoryDir: string): MigrationPlatform;
+/** Pick the first conventional content root containing Markdown. */
+declare function detectRepositoryDocsDir(repositoryDir: string): string;
+/** Import an already-available repository directory into a canonical bundle. */
+declare function migrateRepository(options: RepositoryMigrationOptions): MigrationBundle;
+
+/**
+ * Navigation projection for imported sites. Mintlify's schema is intentionally
+ * more expressive than Thally's tab/group model, so complex containers are
+ * flattened predictably while preserving page order and nested groups.
+ */
+
+interface MintlifyPageReference {
+    ref: string;
+    navigationId: string;
+    locale?: string;
+}
+interface MintlifyNavigationResult {
+    docsConfig: MigrationDocsConfig;
+    pageReferences: Array<MintlifyPageReference>;
+    warnings: Array<MigrationWarning>;
+}
+/** Read `docs.json`/`mint.json`, including bounded local JSON references. */
+declare function readMintlifyConfig(repositoryRoot: string): Record<string, unknown> | null;
+/** Convert current and legacy Mintlify navigation into Thally's schema. */
+declare function projectMintlifyNavigation(config: Record<string, unknown>): MintlifyNavigationResult;
+/** Build deterministic fallback navigation from imported default-locale pages. */
+declare function buildNavigationFromPages(pages: Array<MigrationPage>): MigrationDocsConfig;
+
+/** Markdown/MDX normalization that preserves every component Thally supports. */
+
+/** Normalize only syntax Thally cannot render; supported Mintlify JSX stays intact. */
+declare function normalizeMdx(body: string): string;
+/** Parse source Markdown or MDX into the canonical page representation. */
+declare function parseMarkdownPage(input: {
+    id: string;
+    navigationId?: string;
+    locale?: string;
+    raw: string;
+    source: string;
+}): MigrationPage | null;
+
+/** 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;
+}): Array<RenderedMigrationFile>;
+
+/**
+ * Public URL adapter for the shared migration engine. Discovery prefers
+ * machine-readable Markdown and sitemaps, remains scoped to the submitted docs
+ * path, then falls back to bounded navigation crawling and HTML extraction.
+ */
+
+interface UrlMigrationOptions {
+    sourceUrl: string;
+    fetcher?: MigrationFetcher;
+    maxPages?: number;
+    concurrency?: number;
+    maxTotalBytes?: number;
+}
+/** Validate the transport-level shape of a docs URL; hosted callers add SSRF checks. */
+declare function validateMigrationUrl(value: string): URL;
+/** Fetch implementation for local CLI usage. Cloud injects its pinned network boundary. */
+declare const defaultMigrationFetcher: MigrationFetcher;
+/** Crawl one public docs origin into a canonical, caller-independent bundle. */
+declare function migrateUrl(options: UrlMigrationOptions): Promise<MigrationBundle>;
+
+export { type GitHubRepositorySource, type MigrationAsset, type MigrationBundle, type MigrationDocsConfig, type MigrationFetchRequest, type MigrationFetchResponse, type MigrationFetcher, type MigrationNavigationGroup, type MigrationNavigationTab, type MigrationPage, type MigrationPlatform, type MigrationWarning, type RenderedMigrationFile, type RepositoryMigrationOptions, type UrlMigrationOptions, buildNavigationFromPages, cloneGitHubRepository, defaultMigrationFetcher, detectRepositoryDocsDir, detectRepositoryPlatform, mergeMigrationConfig, migrateRepository, migrateUrl, normalizeMdx, parseGitHubRepositoryUrl, parseMarkdownPage, projectMintlifyNavigation, readMintlifyConfig, renderMigrationFiles, validateMigrationUrl };