infinite-tag 0.1.1

package/dist/src/frameworks/index.js

@@ -0,0 +1,16 @@
+import { nextAppRouterAdapter } from "./next-app-router.js";
+import { nextPagesRouterAdapter } from "./next-pages-router.js";
+import { staticHtmlAdapter } from "./static-html.js";
+import { viteReactAdapter } from "./vite-react.js";
+export const frameworkAdapters = [
+    nextAppRouterAdapter,
+    nextPagesRouterAdapter,
+    viteReactAdapter,
+    staticHtmlAdapter
+];
+export function getFrameworkAdapter(framework) {
+    return frameworkAdapters.find((adapter) => adapter.id === framework);
+}
+export function isSupportedFramework(framework) {
+    return frameworkAdapters.some((adapter) => adapter.id === framework);
+}

package/dist/src/frameworks/managed-files.d.ts

@@ -0,0 +1,10 @@
+import type { InstallPlan } from "../types.js";
+export declare function isManagedInfiniteFile(source: string): boolean;
+export declare function hasExistingUnmanagedFile(root: string, relativePath: string): boolean;
+export interface RemoveManagedFileResult {
+    removed: boolean;
+    warning?: string;
+}
+export declare function removeManagedFile(root: string, relativePath: string, dryRun: boolean): RemoveManagedFileResult;
+export declare function buildAnalyticsModuleSource(plan: InstallPlan): string;
+export declare function buildClientComponentSource(analyticsImportPath?: string): string;

package/dist/src/frameworks/managed-files.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+const managedFileBanner = "// Managed by Infinite. Public install artifacts only.";
+export function isManagedInfiniteFile(source) {
+    return source.includes("Managed by Infinite");
+}
+export function hasExistingUnmanagedFile(root, relativePath) {
+    const absolutePath = join(root, relativePath);
+    return existsSync(absolutePath) && !isManagedInfiniteFile(readFileSync(absolutePath, "utf8"));
+}
+export function removeManagedFile(root, relativePath, dryRun) {
+    const absolutePath = join(root, relativePath);
+    if (!existsSync(absolutePath)) {
+        return {
+            removed: false,
+            warning: `Managed file already absent: ${relativePath}`
+        };
+    }
+    if (!isManagedInfiniteFile(readFileSync(absolutePath, "utf8"))) {
+        throw new Error(`Refusing to remove ${relativePath} because it no longer looks managed by Infinite. Remove it manually if it should go.`);
+    }
+    if (!dryRun) {
+        rmSync(absolutePath);
+    }
+    return { removed: true };
+}
+export function buildAnalyticsModuleSource(plan) {
+    const bootstrapSnippets = plan.instructions
+        .filter((instruction) => instruction.provider &&
+        /(?:^|\/)lib\/infinite-analytics\.(?:ts|js)$/.test(instruction.path))
+        .map((instruction) => instruction.snippet.trim())
+        .filter((snippet) => snippet.length > 0);
+    const ga4MeasurementId = plan.artifacts.ga4?.measurementId;
+    const externalScripts = typeof ga4MeasurementId === "string" && ga4MeasurementId.length > 0
+        ? [
+            {
+                id: "infinite-ga4-loader",
+                src: `https://www.googletagmanager.com/gtag/js?id=${ga4MeasurementId}`,
+                async: true
+            }
+        ]
+        : [];
+    return [
+        managedFileBanner,
+        "",
+        `const externalScripts = ${JSON.stringify(externalScripts, null, 2)} as const`,
+        "",
+        "const bootstrapSource = String.raw`",
+        bootstrapSnippets.join("\n\n"),
+        "`",
+        "",
+        "function ensureExternalScript(id: string, src: string, isAsync: boolean): void {",
+        '  if (document.querySelector(`script[data-infinite-id="${id}"]`)) {',
+        "    return",
+        "  }",
+        "",
+        '  const script = document.createElement("script")',
+        "  script.src = src",
+        "  script.async = isAsync",
+        '  script.setAttribute("data-infinite-id", id)',
+        "  document.head.appendChild(script)",
+        "}",
+        "",
+        "export function installInfiniteInstrumentation(): void {",
+        '  if (typeof document === "undefined") {',
+        "    return",
+        "  }",
+        "",
+        "  for (const scriptSpec of externalScripts) {",
+        "    ensureExternalScript(scriptSpec.id, scriptSpec.src, scriptSpec.async)",
+        "  }",
+        "",
+        '  if (document.getElementById("infinite-analytics-bootstrap")) {',
+        "    return",
+        "  }",
+        "",
+        '  const script = document.createElement("script")',
+        '  script.id = "infinite-analytics-bootstrap"',
+        '  script.setAttribute("data-infinite-analytics", "managed")',
+        "  script.text = bootstrapSource",
+        "  document.head.appendChild(script)",
+        "}",
+        ""
+    ].join("\n");
+}
+export function buildClientComponentSource(analyticsImportPath = "./infinite-analytics") {
+    return [
+        '"use client"',
+        "",
+        managedFileBanner,
+        "",
+        'import { useEffect } from "react"',
+        `import { installInfiniteInstrumentation } from "${analyticsImportPath}"`,
+        "",
+        "export function InfiniteAnalyticsClient(): null {",
+        "  useEffect(() => {",
+        "    installInfiniteInstrumentation()",
+        "  }, [])",
+        "",
+        "  return null",
+        "}",
+        ""
+    ].join("\n");
+}

package/dist/src/frameworks/next-app-router.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkAdapter } from "../types.js";
+export declare const nextAppRouterAdapter: FrameworkAdapter;

package/dist/src/frameworks/next-app-router.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildAnalyticsModuleSource, buildClientComponentSource, hasExistingUnmanagedFile, isManagedInfiniteFile, removeManagedFile } from "./managed-files.js";
+import { firstExistingPath, hasDependency, normalizeAppRelativePath, readRequiredFile, writeFileIfChanged } from "./shared.js";
+const layoutCandidates = [
+    "app/layout.tsx",
+    "app/layout.ts",
+    "app/layout.jsx",
+    "app/layout.js"
+];
+const pageCandidates = ["app/page.tsx", "app/page.ts", "app/page.jsx", "app/page.js"];
+const pagesRouterCandidates = [
+    "pages/_app.tsx",
+    "pages/_app.ts",
+    "pages/_app.jsx",
+    "pages/_app.js",
+    "pages/index.tsx",
+    "pages/index.ts",
+    "pages/index.jsx",
+    "pages/index.js"
+];
+const layoutFilePath = "app/layout.tsx";
+const clientComponentPath = "lib/infinite-analytics-client.tsx";
+const analyticsModulePath = "lib/infinite-analytics.ts";
+const clientImportLine = 'import { InfiniteAnalyticsClient } from "../lib/infinite-analytics-client"';
+const clientTag = "<InfiniteAnalyticsClient />";
+const missingLayoutBlocker = "Next.js App Router apply requires a root app/layout.* file so the managed client component can be mounted safely.";
+export const nextAppRouterAdapter = {
+    id: "next-app-router",
+    displayName: "Next.js App Router",
+    detect(root) {
+        if (!hasDependency(root, "next")) {
+            return null;
+        }
+        const layoutFile = firstExistingPath(root, layoutCandidates);
+        const pageFile = firstExistingPath(root, pageCandidates);
+        if (!layoutFile && !pageFile) {
+            return null;
+        }
+        const assumptions = ["Next.js app router wiring will target the app/ tree."];
+        if (firstExistingPath(root, pagesRouterCandidates)) {
+            assumptions.push("Both app/ and pages/ router trees were detected. App Router wiring was selected; confirm the app/ tree is the active router before applying.");
+        }
+        return {
+            framework: "next-app-router",
+            confidence: 0.94,
+            files: [layoutFile ?? "app/layout.tsx", pageFile ?? "app/page.tsx", "lib/infinite-analytics.ts"],
+            assumptions
+        };
+    },
+    plan(root) {
+        const detected = this.detect(root);
+        const layoutFile = firstExistingPath(root, layoutCandidates);
+        if (!layoutFile) {
+            return {
+                files: [layoutFilePath, clientComponentPath, analyticsModulePath],
+                applyMode: "plan-only",
+                instructions: [],
+                assumptions: ["Next.js app router placement points are inferred from the app/ tree."],
+                blockers: [missingLayoutBlocker],
+                confidence: detected?.confidence ?? 0.9
+            };
+        }
+        const layoutSource = readRequiredFile(root, layoutFile);
+        const blockers = [];
+        if (layoutFile !== layoutFilePath) {
+            blockers.push("Next.js App Router apply currently supports app/layout.tsx only. Other root layout entrypoints remain plan-only.");
+        }
+        if (!layoutSource.includes("<body")) {
+            blockers.push("Next.js App Router apply requires app/layout.tsx to render a <body> element.");
+        }
+        if (hasExistingUnmanagedFile(root, clientComponentPath)) {
+            blockers.push("Next.js App Router apply will not overwrite an existing unmanaged lib/infinite-analytics-client.tsx file.");
+        }
+        if (hasExistingUnmanagedFile(root, analyticsModulePath)) {
+            blockers.push("Next.js App Router apply will not overwrite an existing unmanaged lib/infinite-analytics.ts file.");
+        }
+        return {
+            files: [layoutFilePath, clientComponentPath, analyticsModulePath],
+            applyMode: blockers.length === 0 ? "supported" : "plan-only",
+            instructions: [
+                {
+                    path: layoutFilePath,
+                    action: "modify",
+                    description: "Import and mount the managed InfiniteAnalyticsClient from the root app layout.",
+                    snippet: `${clientImportLine}\n\n${clientTag}`
+                }
+            ],
+            assumptions: [
+                "Next.js app router placement points are inferred from the app/ tree."
+            ],
+            blockers,
+            confidence: detected?.confidence ?? 0.9
+        };
+    },
+    apply(context) {
+        const appRoot = context.appRoot === "." ? context.root : join(context.root, context.appRoot);
+        const currentLayout = readRequiredFile(appRoot, layoutFilePath);
+        if (!currentLayout.includes("<body")) {
+            throw new Error("Next.js App Router apply requires app/layout.tsx to render a <body> element.");
+        }
+        const analyticsModuleAbsolutePath = join(appRoot, analyticsModulePath);
+        if (existsSync(analyticsModuleAbsolutePath) &&
+            !isManagedInfiniteFile(readFileSync(analyticsModuleAbsolutePath, "utf8"))) {
+            throw new Error("Refusing to overwrite existing unmanaged analytics module at lib/infinite-analytics.ts.");
+        }
+        const clientComponentAbsolutePath = join(appRoot, clientComponentPath);
+        if (existsSync(clientComponentAbsolutePath) &&
+            !isManagedInfiniteFile(readFileSync(clientComponentAbsolutePath, "utf8"))) {
+            throw new Error("Refusing to overwrite existing unmanaged client component at lib/infinite-analytics-client.tsx.");
+        }
+        const nextLayout = upsertLayoutSource(currentLayout);
+        const nextClientComponent = buildClientComponentSource();
+        const nextAnalyticsModule = buildAnalyticsModuleSource(context.plan);
+        const changedFiles = [];
+        if (writeFileIfChanged(appRoot, layoutFilePath, nextLayout)) {
+            changedFiles.push(normalizeAppRelativePath(context.appRoot, layoutFilePath));
+        }
+        if (writeFileIfChanged(appRoot, clientComponentPath, nextClientComponent)) {
+            changedFiles.push(normalizeAppRelativePath(context.appRoot, clientComponentPath));
+        }
+        if (writeFileIfChanged(appRoot, analyticsModulePath, nextAnalyticsModule)) {
+            changedFiles.push(normalizeAppRelativePath(context.appRoot, analyticsModulePath));
+        }
+        return {
+            changedFiles,
+            warnings: []
+        };
+    },
+    uninstall(context) {
+        const appRoot = context.appRoot === "." ? context.root : join(context.root, context.appRoot);
+        const removedFiles = [];
+        const restoredFiles = [];
+        const warnings = [];
+        for (const managedPath of [clientComponentPath, analyticsModulePath]) {
+            if (hasExistingUnmanagedFile(appRoot, managedPath)) {
+                throw new Error(`Refusing to remove ${managedPath} because it no longer looks managed by Infinite. Remove it manually if it should go.`);
+            }
+        }
+        let wiringFullyRemoved = true;
+        const layoutAbsolutePath = join(appRoot, layoutFilePath);
+        if (!existsSync(layoutAbsolutePath)) {
+            warnings.push(`Managed layout already absent: ${layoutFilePath}`);
+        }
+        else {
+            const currentLayout = readFileSync(layoutAbsolutePath, "utf8");
+            const nextLayout = removeLayoutWiring(currentLayout);
+            if (nextLayout !== currentLayout) {
+                if (!context.dryRun) {
+                    writeFileIfChanged(appRoot, layoutFilePath, nextLayout);
+                }
+                restoredFiles.push(normalizeAppRelativePath(context.appRoot, layoutFilePath));
+            }
+            if (nextLayout.includes(clientImportLine) || nextLayout.includes(clientTag)) {
+                wiringFullyRemoved = false;
+                warnings.push(`Could not remove all InfiniteAnalyticsClient wiring from ${layoutFilePath} automatically. Remove the leftover lines manually.`);
+            }
+        }
+        if (wiringFullyRemoved) {
+            for (const managedPath of [clientComponentPath, analyticsModulePath]) {
+                const removal = removeManagedFile(appRoot, managedPath, context.dryRun);
+                if (removal.removed) {
+                    removedFiles.push(normalizeAppRelativePath(context.appRoot, managedPath));
+                }
+                if (removal.warning) {
+                    warnings.push(removal.warning);
+                }
+            }
+        }
+        return { removedFiles, restoredFiles, warnings };
+    }
+};
+function removeLayoutWiring(source) {
+    let next = source.replace(`${clientImportLine}\n`, "");
+    next = next.replace(`\n        ${clientTag}`, "");
+    return next;
+}
+function upsertLayoutSource(source) {
+    let next = source;
+    if (!next.includes(clientImportLine)) {
+        next = `${clientImportLine}\n${next}`;
+    }
+    if (!next.includes(clientTag)) {
+        next = next.replace(/<body\b[^>]*>/, (match) => `${match}\n        ${clientTag}`);
+    }
+    return next;
+}

package/dist/src/frameworks/next-pages-router.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkAdapter } from "../types.js";
+export declare const nextPagesRouterAdapter: FrameworkAdapter;

package/dist/src/frameworks/next-pages-router.js

@@ -0,0 +1,169 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildAnalyticsModuleSource, buildClientComponentSource, hasExistingUnmanagedFile, isManagedInfiniteFile, removeManagedFile } from "./managed-files.js";
+import { firstExistingPath, hasDependency, normalizeAppRelativePath, readRequiredFile, writeFileIfChanged } from "./shared.js";
+const appCandidates = ["pages/_app.tsx", "pages/_app.ts", "pages/_app.jsx", "pages/_app.js"];
+const indexCandidates = ["pages/index.tsx", "pages/index.ts", "pages/index.jsx", "pages/index.js"];
+const appFilePath = "pages/_app.tsx";
+const clientComponentPath = "lib/infinite-analytics-client.tsx";
+const analyticsModulePath = "lib/infinite-analytics.ts";
+const clientImportLine = 'import { InfiniteAnalyticsClient } from "../lib/infinite-analytics-client"';
+const clientTag = "<InfiniteAnalyticsClient />";
+const missingAppBlocker = "Next.js Pages Router apply requires pages/_app.* so the managed client component can be mounted safely.";
+export const nextPagesRouterAdapter = {
+    id: "next-pages-router",
+    displayName: "Next.js Pages Router",
+    detect(root) {
+        if (!hasDependency(root, "next")) {
+            return null;
+        }
+        const appFile = firstExistingPath(root, appCandidates);
+        const indexFile = firstExistingPath(root, indexCandidates);
+        if (!appFile && !indexFile) {
+            return null;
+        }
+        return {
+            framework: "next-pages-router",
+            confidence: 0.9,
+            files: [appFile ?? "pages/_app.tsx", indexFile ?? "pages/index.tsx", "lib/infinite-analytics.ts"],
+            assumptions: ["Next.js pages router wiring will target pages/_app.*."]
+        };
+    },
+    plan(root) {
+        const detected = this.detect(root);
+        const appFile = firstExistingPath(root, appCandidates);
+        if (!appFile) {
+            return {
+                files: [appFilePath, clientComponentPath, analyticsModulePath],
+                applyMode: "plan-only",
+                instructions: [],
+                assumptions: ["Next.js pages router wiring will target pages/_app.*."],
+                blockers: [missingAppBlocker],
+                confidence: detected?.confidence ?? 0.88
+            };
+        }
+        const appSource = readRequiredFile(root, appFile);
+        const componentMatches = appSource.match(/<Component\b[^>]*\/>/g) ?? [];
+        const blockers = [];
+        if (appFile !== appFilePath) {
+            blockers.push("Next.js Pages Router apply currently supports pages/_app.tsx only. Other custom App entrypoints remain plan-only.");
+        }
+        if (componentMatches.length !== 1) {
+            blockers.push("Next.js Pages Router apply requires pages/_app.tsx to render <Component {...pageProps} /> exactly once.");
+        }
+        if (hasExistingUnmanagedFile(root, clientComponentPath)) {
+            blockers.push("Next.js Pages Router apply will not overwrite an existing unmanaged lib/infinite-analytics-client.tsx file.");
+        }
+        if (hasExistingUnmanagedFile(root, analyticsModulePath)) {
+            blockers.push("Next.js Pages Router apply will not overwrite an existing unmanaged lib/infinite-analytics.ts file.");
+        }
+        return {
+            files: [appFilePath, clientComponentPath, analyticsModulePath],
+            applyMode: blockers.length === 0 ? "supported" : "plan-only",
+            instructions: [
+                {
+                    path: appFilePath,
+                    action: "modify",
+                    description: "Import and mount the managed InfiniteAnalyticsClient from pages/_app.tsx.",
+                    snippet: `${clientImportLine}\n\n${clientTag}`
+                }
+            ],
+            assumptions: [
+                "Next.js pages router placement points are inferred from the pages/ tree."
+            ],
+            blockers,
+            confidence: detected?.confidence ?? 0.88
+        };
+    },
+    apply(context) {
+        const appRoot = context.appRoot === "." ? context.root : join(context.root, context.appRoot);
+        const currentApp = readRequiredFile(appRoot, appFilePath);
+        if ((currentApp.match(/<Component\b[^>]*\/>/g) ?? []).length !== 1) {
+            throw new Error("Next.js Pages Router apply requires pages/_app.tsx to render <Component {...pageProps} /> exactly once.");
+        }
+        const analyticsModuleAbsolutePath = join(appRoot, analyticsModulePath);
+        if (existsSync(analyticsModuleAbsolutePath) &&
+            !isManagedInfiniteFile(readFileSync(analyticsModuleAbsolutePath, "utf8"))) {
+            throw new Error("Refusing to overwrite existing unmanaged analytics module at lib/infinite-analytics.ts.");
+        }
+        const clientComponentAbsolutePath = join(appRoot, clientComponentPath);
+        if (existsSync(clientComponentAbsolutePath) &&
+            !isManagedInfiniteFile(readFileSync(clientComponentAbsolutePath, "utf8"))) {
+            throw new Error("Refusing to overwrite existing unmanaged client component at lib/infinite-analytics-client.tsx.");
+        }
+        const nextApp = upsertAppSource(currentApp);
+        const nextClientComponent = buildClientComponentSource();
+        const nextAnalyticsModule = buildAnalyticsModuleSource(context.plan);
+        const changedFiles = [];
+        if (writeFileIfChanged(appRoot, appFilePath, nextApp)) {
+            changedFiles.push(normalizeAppRelativePath(context.appRoot, appFilePath));
+        }
+        if (writeFileIfChanged(appRoot, clientComponentPath, nextClientComponent)) {
+            changedFiles.push(normalizeAppRelativePath(context.appRoot, clientComponentPath));
+        }
+        if (writeFileIfChanged(appRoot, analyticsModulePath, nextAnalyticsModule)) {
+            changedFiles.push(normalizeAppRelativePath(context.appRoot, analyticsModulePath));
+        }
+        return {
+            changedFiles,
+            warnings: []
+        };
+    },
+    uninstall(context) {
+        const appRoot = context.appRoot === "." ? context.root : join(context.root, context.appRoot);
+        const removedFiles = [];
+        const restoredFiles = [];
+        const warnings = [];
+        for (const managedPath of [clientComponentPath, analyticsModulePath]) {
+            if (hasExistingUnmanagedFile(appRoot, managedPath)) {
+                throw new Error(`Refusing to remove ${managedPath} because it no longer looks managed by Infinite. Remove it manually if it should go.`);
+            }
+        }
+        let wiringFullyRemoved = true;
+        const appAbsolutePath = join(appRoot, appFilePath);
+        if (!existsSync(appAbsolutePath)) {
+            warnings.push(`Managed app entrypoint already absent: ${appFilePath}`);
+        }
+        else {
+            const currentApp = readFileSync(appAbsolutePath, "utf8");
+            const nextApp = removeAppWiring(currentApp);
+            if (nextApp !== currentApp) {
+                if (!context.dryRun) {
+                    writeFileIfChanged(appRoot, appFilePath, nextApp);
+                }
+                restoredFiles.push(normalizeAppRelativePath(context.appRoot, appFilePath));
+            }
+            if (nextApp.includes(clientImportLine) || nextApp.includes(clientTag)) {
+                wiringFullyRemoved = false;
+                warnings.push(`Could not remove all InfiniteAnalyticsClient wiring from ${appFilePath} automatically. Remove the leftover lines manually.`);
+            }
+        }
+        if (wiringFullyRemoved) {
+            for (const managedPath of [clientComponentPath, analyticsModulePath]) {
+                const removal = removeManagedFile(appRoot, managedPath, context.dryRun);
+                if (removal.removed) {
+                    removedFiles.push(normalizeAppRelativePath(context.appRoot, managedPath));
+                }
+                if (removal.warning) {
+                    warnings.push(removal.warning);
+                }
+            }
+        }
+        return { removedFiles, restoredFiles, warnings };
+    }
+};
+function removeAppWiring(source) {
+    let next = source.replace(`${clientImportLine}\n`, "");
+    next = next.replace(/<>\n {6}<InfiniteAnalyticsClient \/>\n {6}(<Component\b[^>]*\/>)\n {4}<\/>/, (_match, component) => component);
+    return next;
+}
+function upsertAppSource(source) {
+    let next = source;
+    if (!next.includes(clientImportLine)) {
+        next = `${clientImportLine}\n${next}`;
+    }
+    if (!next.includes(clientTag)) {
+        next = next.replace(/<Component\b[^>]*\/>/, (match) => `<>\n      ${clientTag}\n      ${match}\n    </>`);
+    }
+    return next;
+}

package/dist/src/frameworks/shared.d.ts

@@ -0,0 +1,17 @@
+interface WorkspacePackageJson {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+export declare function fileExists(root: string, relativePath: string): boolean;
+export declare function firstExistingPath(root: string, candidates: string[]): string | null;
+export declare function readWorkspacePackageJson(root: string): WorkspacePackageJson | null;
+export declare function hasDependency(root: string, dependencyName: string): boolean;
+export declare function readRequiredFile(root: string, relativePath: string): string;
+export declare function resolveConfinedAppRoot(root: string, appRoot: string): string;
+export declare function assertConfinedManifestFileEntry(root: string, relativePath: string): void;
+export declare function assertWriteTargetInsideRoot(root: string, absolutePath: string): void;
+export declare function writeFileIfChanged(root: string, relativePath: string, contents: string): boolean;
+export declare function writeFileAtomic(absolutePath: string, contents: string): void;
+export declare function indentBlock(source: string, spaces: number): string;
+export declare function normalizeAppRelativePath(appRoot: string, relativePath: string): string;
+export {};

package/dist/src/frameworks/shared.js

@@ -0,0 +1,136 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+export function fileExists(root, relativePath) {
+    return existsSync(join(root, relativePath));
+}
+export function firstExistingPath(root, candidates) {
+    for (const candidate of candidates) {
+        if (fileExists(root, candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function readWorkspacePackageJson(root) {
+    const packageJsonPath = join(root, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return null;
+    }
+    return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+}
+export function hasDependency(root, dependencyName) {
+    const packageJson = readWorkspacePackageJson(root);
+    if (!packageJson) {
+        return false;
+    }
+    return Boolean(packageJson.dependencies?.[dependencyName] ?? packageJson.devDependencies?.[dependencyName]);
+}
+export function readRequiredFile(root, relativePath) {
+    return readFileSync(join(root, relativePath), "utf8");
+}
+function realpathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function escapesRoot(root, target) {
+    const relativePath = relative(root, target);
+    return relativePath.startsWith("..") || isAbsolute(relativePath);
+}
+// Realpath the deepest existing ancestor, then re-append the missing tail, so
+// non-existent paths still compare correctly when the root itself sits behind
+// a symlink (e.g. macOS /var/folders -> /private/var/folders).
+function realpathNearestExistingAncestor(path) {
+    let current = path;
+    const missingTail = [];
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        missingTail.unshift(basename(current));
+        current = parent;
+    }
+    return join(realpathOrSelf(current), ...missingTail);
+}
+export function resolveConfinedAppRoot(root, appRoot) {
+    const resolvedRoot = resolve(root);
+    const resolvedAppRoot = resolve(resolvedRoot, appRoot);
+    if (escapesRoot(resolvedRoot, resolvedAppRoot)) {
+        throw new Error(`Refusing to use app root "${appRoot}" because it escapes the workspace root.`);
+    }
+    if (escapesRoot(realpathOrSelf(resolvedRoot), realpathNearestExistingAncestor(resolvedAppRoot))) {
+        throw new Error(`Refusing to use app root "${appRoot}" because it resolves outside the workspace root through a symlink.`);
+    }
+    return resolvedAppRoot;
+}
+export function assertConfinedManifestFileEntry(root, relativePath) {
+    if (isAbsolute(relativePath)) {
+        throw new Error(`Refusing to use manifest file entry "${relativePath}" because absolute paths are not allowed.`);
+    }
+    const resolvedRoot = resolve(root);
+    if (escapesRoot(resolvedRoot, resolve(resolvedRoot, relativePath))) {
+        throw new Error(`Refusing to use manifest file entry "${relativePath}" because it escapes the workspace root.`);
+    }
+}
+export function assertWriteTargetInsideRoot(root, absolutePath) {
+    const resolvedRoot = resolve(root);
+    const resolvedTarget = resolve(absolutePath);
+    if (escapesRoot(resolvedRoot, resolvedTarget)) {
+        throw new Error(`Refusing to write outside the workspace root: ${absolutePath}`);
+    }
+    let nearestExistingAncestor = dirname(resolvedTarget);
+    while (!existsSync(nearestExistingAncestor)) {
+        const parent = dirname(nearestExistingAncestor);
+        if (parent === nearestExistingAncestor) {
+            break;
+        }
+        nearestExistingAncestor = parent;
+    }
+    if (escapesRoot(realpathOrSelf(resolvedRoot), realpathOrSelf(nearestExistingAncestor))) {
+        throw new Error(`Refusing to write through a path that resolves outside the workspace root: ${absolutePath}`);
+    }
+}
+export function writeFileIfChanged(root, relativePath, contents) {
+    const absolutePath = join(root, relativePath);
+    assertWriteTargetInsideRoot(root, absolutePath);
+    const existing = existsSync(absolutePath) ? readFileSync(absolutePath, "utf8") : null;
+    if (existing === contents) {
+        return false;
+    }
+    writeFileAtomic(absolutePath, contents);
+    return true;
+}
+export function writeFileAtomic(absolutePath, contents) {
+    const stats = lstatSync(absolutePath, { throwIfNoEntry: false });
+    if (stats?.isSymbolicLink()) {
+        throw new Error(`Refusing to write through a symlink at ${absolutePath}. Replace the symlink with a regular file first.`);
+    }
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    const tempPath = `${absolutePath}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tempPath, contents);
+        renameSync(tempPath, absolutePath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+export function indentBlock(source, spaces) {
+    const prefix = " ".repeat(spaces);
+    return source
+        .split("\n")
+        .map((line) => (line.length > 0 ? `${prefix}${line}` : line))
+        .join("\n");
+}
+export function normalizeAppRelativePath(appRoot, relativePath) {
+    if (appRoot === "." || appRoot.length === 0) {
+        return relativePath;
+    }
+    return `${appRoot}/${relativePath}`;
+}

package/dist/src/frameworks/static-html.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkAdapter } from "../types.js";
+export declare const staticHtmlAdapter: FrameworkAdapter;