fimo 0.3.1 → 0.3.2-experimental.1783354419249

package/dist/runtime/shared/fimo-config.types.d.ts

@@ -57,5 +57,7 @@ export interface FimoConfig {
     i18n?: FimoI18nConfig;
     routes?: Record<string, FimoRouteConfig>;
     version?: string | number;
+    /** The project's framework. Absent means the Fimo template (react-router). */
+    framework?: 'react-router' | 'next' | string;
 }
 //# sourceMappingURL=fimo-config.types.d.ts.map

package/dist/runtime/shared/fimo-config.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fimo-config.types.d.ts","sourceRoot":"","sources":["../../../src/runtime/shared/fimo-config.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B"}
+{"version":3,"file":"fimo-config.types.d.ts","sourceRoot":"","sources":["../../../src/runtime/shared/fimo-config.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;CAC9C"}

package/dist/runtime/shared/labels-fetch.server.d.ts

@@ -0,0 +1,14 @@
+export interface LabelBundle {
+    dictionaries: Record<string, Record<string, string>>;
+    defaultLocale: string;
+    locales: string[];
+    updatedAt: string | null;
+}
+export declare function serializeBundle(bundle: LabelBundle): string;
+export declare function labelSignature(bundle: LabelBundle): string;
+export declare function emptyLabelBundle(rootDir: string): LabelBundle;
+export declare function resolveTenantApiUrl(env: Record<string, string>): string | undefined;
+export declare function loadLabelBundle(rootDir: string): Promise<LabelBundle>;
+export declare function fetchWithTimeout(url: URL, timeoutMs: number): Promise<Response>;
+export declare function readProjectEnv(rootDir: string): Promise<Record<string, string>>;
+//# sourceMappingURL=labels-fetch.server.d.ts.map

package/dist/runtime/shared/labels-fetch.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels-fetch.server.d.ts","sourceRoot":"","sources":["../../../src/runtime/shared/labels-fetch.server.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAM3D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE1D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAU7D;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAOnF;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwC3E;AA+BD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAQrF;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAWrF"}

package/dist/runtime/shared/labels-fetch.server.js

@@ -0,0 +1,145 @@
+// Framework-neutral label fetching (server-side). Shared by the Vite
+// translations plugin (fimo/vite) and the Next server loaders (fimo/next/server).
+import { Buffer } from 'node:buffer';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getFimoDefaultLocale, getFimoLocales } from '../i18n/locale.js';
+import { getConfigServer } from './fimo-config.server.js';
+// The tenant API base URL env var, in framework flavor order. Vite projects
+// use VITE_API_URL; wrapped Next projects use NEXT_PUBLIC_FIMO_API_URL.
+const API_URL_ENV_KEYS = ['VITE_API_URL', 'NEXT_PUBLIC_FIMO_API_URL'];
+export function serializeBundle(bundle) {
+    return JSON.stringify({
+        dictionaries: bundle.dictionaries,
+        defaultLocale: bundle.defaultLocale,
+        locales: bundle.locales,
+    });
+}
+export function labelSignature(bundle) {
+    return Buffer.from(serializeBundle(bundle)).toString('base64');
+}
+export function emptyLabelBundle(rootDir) {
+    const config = getConfigServer(rootDir);
+    const defaultLocale = getFimoDefaultLocale(config);
+    const locales = getFimoLocales(config);
+    return {
+        dictionaries: Object.fromEntries(locales.map((locale) => [locale, {}])),
+        defaultLocale,
+        locales,
+        updatedAt: null,
+    };
+}
+export function resolveTenantApiUrl(env) {
+    for (const key of API_URL_ENV_KEYS) {
+        if (env[key]) {
+            return env[key];
+        }
+    }
+    return undefined;
+}
+export async function loadLabelBundle(rootDir) {
+    const config = getConfigServer(rootDir);
+    const defaultLocale = getFimoDefaultLocale(config);
+    const locales = getFimoLocales(config);
+    const env = await readProjectEnv(rootDir);
+    const apiUrl = resolveTenantApiUrl(env);
+    if (!apiUrl) {
+        return {
+            dictionaries: Object.fromEntries(locales.map((locale) => [locale, {}])),
+            defaultLocale,
+            locales,
+            updatedAt: null,
+        };
+    }
+    try {
+        const loaded = await Promise.all(locales.map((locale) => fetchLabelDictionary(apiUrl, locale).catch(() => ({ locale, labels: {}, updatedAt: null }))));
+        const sortedUpdatedAt = loaded
+            .map((entry) => entry.updatedAt)
+            .filter((value) => typeof value === 'string')
+            .sort();
+        const updatedAt = sortedUpdatedAt[sortedUpdatedAt.length - 1];
+        return {
+            dictionaries: Object.fromEntries(loaded.map((entry) => [entry.locale, entry.labels])),
+            defaultLocale,
+            locales,
+            updatedAt: updatedAt ?? null,
+        };
+    }
+    catch {
+        return {
+            dictionaries: Object.fromEntries(locales.map((locale) => [locale, {}])),
+            defaultLocale,
+            locales,
+            updatedAt: null,
+        };
+    }
+}
+async function fetchLabelDictionary(apiUrl, locale) {
+    const url = new URL('/labels', apiUrl);
+    url.searchParams.set('locale', locale);
+    const response = await fetchWithTimeout(url, 4000);
+    if (!response.ok) {
+        return { locale, labels: {}, updatedAt: null };
+    }
+    const body = (await response.json());
+    if (Array.isArray(body.data)) {
+        return {
+            locale,
+            labels: Object.fromEntries(body.data.map((row) => [row.key, row.value ?? row.defaultValue ?? ''])),
+            updatedAt: null,
+        };
+    }
+    return {
+        locale,
+        labels: body.data?.labels ?? {},
+        updatedAt: body.data?.updatedAt ?? null,
+    };
+}
+export async function fetchWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function readProjectEnv(rootDir) {
+    const values = {
+        ...(await readEnvFile(join(rootDir, '.env'))),
+        ...(await readEnvFile(join(rootDir, '.env.local'))),
+    };
+    for (const key of API_URL_ENV_KEYS) {
+        if (process.env[key]) {
+            values[key] = process.env[key];
+        }
+    }
+    return values;
+}
+async function readEnvFile(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const values = {};
+        for (const line of content.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#')) {
+                continue;
+            }
+            const index = trimmed.indexOf('=');
+            if (index === -1) {
+                continue;
+            }
+            const key = trimmed.slice(0, index).trim();
+            const value = trimmed
+                .slice(index + 1)
+                .trim()
+                .replace(/^['"]|['"]$/g, '');
+            values[key] = value;
+        }
+        return values;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/scripts/detect-framework.d.ts

@@ -0,0 +1,12 @@
+export type DetectedFramework = 'next' | 'react-router' | 'vite';
+export interface FrameworkDetection {
+    framework: DetectedFramework | null;
+    /** For Next.js: the app-router directory (`app` or `src/app`) when present. */
+    appDir?: string;
+}
+/**
+ * Detect the framework of an existing site from its package.json and layout.
+ * Used by `fimo init` (adopt-existing-site) and the wrap migration to decide
+ * how routes are discovered and which env flavor to write.
+ */
+export declare function detectFramework(cwd: string): FrameworkDetection;

package/dist/scripts/detect-framework.js

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Detect the framework of an existing site from its package.json and layout.
+ * Used by `fimo init` (adopt-existing-site) and the wrap migration to decide
+ * how routes are discovered and which env flavor to write.
+ */
+export function detectFramework(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return { framework: null };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return { framework: null };
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) {
+        const appDir = ['app', 'src/app'].find((dir) => existsSync(join(cwd, dir)));
+        return { framework: 'next', appDir };
+    }
+    if (deps['react-router'] || deps['@react-router/dev']) {
+        return { framework: 'react-router' };
+    }
+    if (deps.vite) {
+        return { framework: 'vite' };
+    }
+    return { framework: null };
+}

package/dist/scripts/detect-framework.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/detect-framework.test.js

@@ -0,0 +1,39 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { detectFramework } from './detect-framework.js';
+let dir;
+const project = (deps, dirs = []) => {
+    dir = mkdtempSync(join(tmpdir(), 'detect-framework-'));
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 't', dependencies: deps }));
+    for (const d of dirs) {
+        mkdirSync(join(dir, d), { recursive: true });
+    }
+    return dir;
+};
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('detectFramework', () => {
+    it('detects next with the app dir', () => {
+        expect(detectFramework(project({ next: '^15.0.0' }, ['app']))).toEqual({ framework: 'next', appDir: 'app' });
+        expect(detectFramework(project({ next: '^15.0.0' }, ['src/app']))).toEqual({
+            framework: 'next',
+            appDir: 'src/app',
+        });
+    });
+    it('detects react-router and vite', () => {
+        expect(detectFramework(project({ 'react-router': '^7.0.0' })).framework).toBe('react-router');
+        expect(detectFramework(project({ vite: '^7.0.0' })).framework).toBe('vite');
+    });
+    it('prefers next over an incidental vite dep', () => {
+        expect(detectFramework(project({ next: '^15.0.0', vite: '^7.0.0' }, ['app'])).framework).toBe('next');
+    });
+    it('returns null without a package.json or known framework', () => {
+        expect(detectFramework(join(tmpdir(), 'nope-does-not-exist')).framework).toBeNull();
+        expect(detectFramework(project({ express: '^4.0.0' })).framework).toBeNull();
+    });
+});

package/dist/scripts/lib/discover-next-routes.d.ts

@@ -0,0 +1,11 @@
+export interface DiscoveredRoute {
+    id: string;
+    path: string;
+    label: string;
+}
+/**
+ * Discover page routes of a Next.js app-router directory (`app/` or
+ * `src/app/`). Returns display routes for `fimo-config.json#routes` so the
+ * Studio page switcher can enumerate a wrapped site's pages.
+ */
+export declare function discoverNextRoutes(appDir: string): DiscoveredRoute[];

package/dist/scripts/lib/discover-next-routes.js

@@ -0,0 +1,76 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const PAGE_FILES = new Set(['page.tsx', 'page.jsx', 'page.ts', 'page.js', 'page.mdx']);
+const titleCase = (seg) => seg
+    .replace(/[_\-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join(' ');
+function segmentToPath(segment) {
+    // Route groups `(marketing)` don't contribute URL segments. Parallel-route
+    // slots `@modal` and private folders `_lib` are not standalone pages.
+    if (segment.startsWith('(')) {
+        return '';
+    }
+    if (segment.startsWith('@') || segment.startsWith('_')) {
+        return null;
+    }
+    const catchAll = segment.match(/^\[\.\.\.(.+)\]$/) ?? segment.match(/^\[\[\.\.\.(.+)\]\]$/);
+    if (catchAll) {
+        return `:${catchAll[1]}*`;
+    }
+    const param = segment.match(/^\[(.+)\]$/);
+    if (param) {
+        return `:${param[1]}`;
+    }
+    return segment;
+}
+/**
+ * Discover page routes of a Next.js app-router directory (`app/` or
+ * `src/app/`). Returns display routes for `fimo-config.json#routes` so the
+ * Studio page switcher can enumerate a wrapped site's pages.
+ */
+export function discoverNextRoutes(appDir) {
+    const routes = [];
+    const walk = (dir, segments) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        if (entries.some((entry) => PAGE_FILES.has(entry))) {
+            const parts = segments.filter((s) => s.length > 0);
+            const routePath = `/${parts.join('/')}`.replace(/\/+/g, '/');
+            const lastStatic = [...parts].reverse().find((p) => !p.startsWith(':'));
+            routes.push({
+                id: routePath === '/' ? 'home' : parts.map((p) => p.replace(/^:/, '')).join('-'),
+                path: routePath,
+                label: routePath === '/' ? 'Home' : titleCase(lastStatic ?? parts[parts.length - 1] ?? routePath),
+            });
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (!isDir) {
+                continue;
+            }
+            const mapped = segmentToPath(entry);
+            if (mapped === null) {
+                continue;
+            }
+            walk(full, [...segments, mapped]);
+        }
+    };
+    walk(appDir, []);
+    return routes.sort((a, b) => a.path.localeCompare(b.path));
+}

package/dist/scripts/lib/discover-next-routes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/lib/discover-next-routes.test.js

@@ -0,0 +1,40 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { discoverNextRoutes } from './discover-next-routes.js';
+let dir;
+const app = (pages) => {
+    dir = mkdtempSync(join(tmpdir(), 'next-routes-'));
+    for (const page of pages) {
+        const full = join(dir, page);
+        mkdirSync(join(full, '..'), { recursive: true });
+        writeFileSync(full, 'export default function Page() { return null }');
+    }
+    return dir;
+};
+afterEach(() => {
+    if (dir) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('discoverNextRoutes', () => {
+    it('discovers static routes', () => {
+        const routes = discoverNextRoutes(app(['page.tsx', 'about/page.tsx', 'pricing/page.tsx']));
+        expect(routes.map((r) => r.path)).toEqual(['/', '/about', '/pricing']);
+        expect(routes[0]).toEqual({ id: 'home', path: '/', label: 'Home' });
+        expect(routes[1]).toEqual({ id: 'about', path: '/about', label: 'About' });
+    });
+    it('maps dynamic and catch-all segments', () => {
+        const routes = discoverNextRoutes(app(['blog/[slug]/page.tsx', 'docs/[...path]/page.tsx']));
+        expect(routes.map((r) => r.path)).toEqual(['/blog/:slug', '/docs/:path*']);
+        expect(routes[0].label).toBe('Blog');
+    });
+    it('collapses route groups and skips private and parallel segments', () => {
+        const routes = discoverNextRoutes(app(['(marketing)/features/page.tsx', '_internal/secret/page.tsx', '@modal/photo/page.tsx']));
+        expect(routes.map((r) => r.path)).toEqual(['/features']);
+    });
+    it('returns [] for a missing directory', () => {
+        expect(discoverNextRoutes(join(tmpdir(), 'does-not-exist'))).toEqual([]);
+    });
+});

package/dist/scripts/render-parity/capture.d.ts

@@ -0,0 +1,34 @@
+import { type ParityBaseline } from './types.js';
+export interface CaptureOptions {
+    cwd: string;
+    packageManager: string;
+    routes: Array<{
+        path: string;
+    }>;
+    framework: string | null;
+    bootTimeoutMs?: number;
+    routeTimeoutMs?: number;
+    onProgress?: (message: string) => void;
+}
+export declare class CaptureError extends Error {
+    readonly stderrTail: string;
+    constructor(message: string, stderrTail?: string);
+}
+export declare function findFreePort(): Promise<number>;
+interface DevServer {
+    origin: string;
+    stderrTail: () => string;
+    stop: () => Promise<void>;
+}
+export declare function startDevServer(opts: {
+    cwd: string;
+    packageManager: string;
+    bootTimeoutMs: number;
+}): Promise<DevServer>;
+/**
+ * Boot the project's own dev server, capture every static route's normalized
+ * signature, and tear the server down. Baseline and check both run through
+ * this identical pipeline — that symmetry is the gate's correctness property.
+ */
+export declare function captureParityBaseline(opts: CaptureOptions): Promise<ParityBaseline>;
+export {};

package/dist/scripts/render-parity/capture.js

@@ -0,0 +1,192 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { extractRouteSignature } from './normalize-html.js';
+import { PARITY_BASELINE_VERSION } from './types.js';
+const DEFAULT_BOOT_TIMEOUT_MS = 90_000;
+const DEFAULT_ROUTE_TIMEOUT_MS = 60_000;
+const READINESS_POLL_MS = 500;
+const KILL_GRACE_MS = 5_000;
+export class CaptureError extends Error {
+    stderrTail;
+    constructor(message, stderrTail = '') {
+        super(message);
+        this.name = 'CaptureError';
+        this.stderrTail = stderrTail;
+    }
+}
+export function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+function preflight(cwd) {
+    if (!fs.existsSync(path.join(cwd, 'node_modules'))) {
+        throw new CaptureError('node_modules is missing — run your package manager install first.');
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        if (!pkg.scripts?.dev) {
+            throw new CaptureError('No `dev` script in package.json — the parity capture boots your dev server.');
+        }
+    }
+    catch (error) {
+        if (error instanceof CaptureError) {
+            throw error;
+        }
+        throw new CaptureError('Could not read package.json.');
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function startDevServer(opts) {
+    preflight(opts.cwd);
+    const port = await findFreePort();
+    const child = spawn(opts.packageManager, ['run', 'dev'], {
+        cwd: opts.cwd,
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, PORT: String(port), NEXT_TELEMETRY_DISABLED: '1', BROWSER: 'none' },
+    });
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+    child.stdout?.on('data', (chunk) => {
+        stdoutBuffer = `${stdoutBuffer}${chunk.toString()}`.slice(-8_000);
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderrBuffer = `${stderrBuffer}${chunk.toString()}`.slice(-8_000);
+    });
+    let exited = false;
+    child.on('exit', () => {
+        exited = true;
+    });
+    const stop = async () => {
+        if (exited || child.pid === undefined) {
+            return;
+        }
+        try {
+            if (process.platform === 'win32') {
+                spawn('taskkill', ['/pid', String(child.pid), '/T', '/F']);
+            }
+            else {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+        }
+        catch {
+            child.kill('SIGTERM');
+        }
+        const deadline = Date.now() + KILL_GRACE_MS;
+        while (!exited && Date.now() < deadline) {
+            await sleep(100);
+        }
+        if (!exited && child.pid !== undefined && process.platform !== 'win32') {
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+    };
+    // Readiness: any HTTP response counts as listening. Dev scripts that
+    // hardcode their own port are handled by sniffing the child's stdout.
+    const probe = async (origin) => {
+        try {
+            await fetch(origin, { signal: AbortSignal.timeout(2_000) });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const deadline = Date.now() + opts.bootTimeoutMs;
+    let origin = `http://127.0.0.1:${port}`;
+    while (Date.now() < deadline) {
+        if (exited) {
+            await stop();
+            throw new CaptureError('The dev server exited before becoming ready.', stderrBuffer || stdoutBuffer);
+        }
+        if (await probe(origin)) {
+            return { origin, stderrTail: () => stderrBuffer, stop };
+        }
+        const sniffed = stdoutBuffer.match(/(?:localhost|127\.0\.0\.1):(\d{2,5})/);
+        if (sniffed && Number(sniffed[1]) !== port) {
+            const candidate = `http://127.0.0.1:${sniffed[1]}`;
+            if (await probe(candidate)) {
+                origin = candidate;
+                return { origin, stderrTail: () => stderrBuffer, stop };
+            }
+        }
+        await sleep(READINESS_POLL_MS);
+    }
+    await stop();
+    throw new CaptureError(`The dev server did not answer within ${Math.round(opts.bootTimeoutMs / 1000)}s.`, stderrBuffer || stdoutBuffer);
+}
+async function fetchRoute(origin, routePath, timeoutMs) {
+    const response = await fetch(new URL(routePath, origin), {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { accept: 'text/html' },
+    });
+    return { status: response.status, html: await response.text() };
+}
+/**
+ * Boot the project's own dev server, capture every static route's normalized
+ * signature, and tear the server down. Baseline and check both run through
+ * this identical pipeline — that symmetry is the gate's correctness property.
+ */
+export async function captureParityBaseline(opts) {
+    const bootTimeoutMs = opts.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
+    const routeTimeoutMs = opts.routeTimeoutMs ?? DEFAULT_ROUTE_TIMEOUT_MS;
+    const routes = {};
+    const staticRoutes = opts.routes.filter((route) => !route.path.includes(':'));
+    for (const route of opts.routes) {
+        if (route.path.includes(':')) {
+            routes[route.path] = { skipped: 'dynamic-params' };
+        }
+    }
+    opts.onProgress?.('starting your dev server');
+    const server = await startDevServer({ cwd: opts.cwd, packageManager: opts.packageManager, bootTimeoutMs });
+    try {
+        // Sequential on purpose: dev compilers choke on parallel cold compiles.
+        for (const route of staticRoutes) {
+            opts.onProgress?.(`capturing ${route.path}`);
+            try {
+                let result = await fetchRoute(server.origin, route.path, routeTimeoutMs).catch(async () => {
+                    // One retry: first-compile latency and transient dev-server flake.
+                    await sleep(1_000);
+                    return fetchRoute(server.origin, route.path, routeTimeoutMs);
+                });
+                if (result.status >= 500) {
+                    await sleep(1_000);
+                    const retried = await fetchRoute(server.origin, route.path, routeTimeoutMs).catch(() => null);
+                    if (retried) {
+                        result = retried;
+                    }
+                }
+                routes[route.path] = {
+                    signature: extractRouteSignature(result.html, { origin: server.origin, status: result.status }),
+                };
+            }
+            catch (error) {
+                routes[route.path] = { skipped: 'fetch-failed', error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+    }
+    finally {
+        await server.stop();
+    }
+    return {
+        version: PARITY_BASELINE_VERSION,
+        capturedAt: new Date().toISOString(),
+        engine: 'dev-server',
+        framework: opts.framework,
+        command: `${opts.packageManager} run dev`,
+        routes,
+    };
+}

package/dist/scripts/render-parity/capture.test.d.ts

@@ -0,0 +1 @@
+export {};