@getrefino/onboarding 0.1.0-rc.1

package/dist/plan.js

@@ -0,0 +1,447 @@
+/**
+ * Turn an inspection and a scan into a serializable migration plan. The
+ * plan is the contract between the CLI, the agent instructions, the safe
+ * apply step and the verifier.
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { parseCopy } from "@getrefino/core";
+import { exists, isDirectory, readText } from "./fs.js";
+import { appDirectory, packageManagerExec, packageManagerRun } from "./inspect.js";
+import { scanCopy } from "./scan.js";
+import { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN } from "./templates-hosted.js";
+export const TOOL_NAME = "refino";
+/**
+ * The published version of this package. A prerelease build names the commit
+ * it came from, so plans, instructions and the dependency pins a site
+ * receives say exactly which build produced them.
+ */
+export const TOOL_VERSION = createRequire(import.meta.url)("../package.json").version;
+const PRERELEASE_VERSION = /^\d+\.\d+\.\d+-/;
+/**
+ * Dependency range for the runtime packages. Any prerelease (a smoke build or
+ * a release candidate) is pinned exactly, so a site records the one build it
+ * was tested against and never floats onto a later prerelease or onto the
+ * eventual stable release. Stable versions get a caret.
+ */
+export function dependencyRange(version = TOOL_VERSION) {
+    return PRERELEASE_VERSION.test(version) ? version : `^${version}`;
+}
+export const PLAN_DIR = ".refino";
+export const PLAN_FILE = `${PLAN_DIR}/plan.json`;
+export const INSTRUCTIONS_FILE = `${PLAN_DIR}/AGENT_INSTRUCTIONS.md`;
+export const CONFIG_FILE = "refino.config.json";
+export const BOILERPLATE_DIR = "refino";
+export function defaultContentFile(inspection) {
+    if (inspection.refino.contentFile)
+        return inspection.refino.contentFile;
+    const appDir = appDirectory(inspection);
+    if (inspection.sourceDir === "src" || isDirectory(join(appDir, "src/content")))
+        return "src/content/copy.json";
+    return "content/copy.json";
+}
+function extension(inspection, jsx) {
+    return inspection.language === "typescript" ? (jsx ? "tsx" : "ts") : jsx ? "jsx" : "js";
+}
+/** Validate and normalize the Refino connection given on the command line. */
+export function resolveRefinoSite(option) {
+    if (!option)
+        return null;
+    if (!REFINO_SITE_ID_PATTERN.test(option.siteId))
+        throw new Error(`Refino site id must look like site_<32 hex characters>, got ${JSON.stringify(option.siteId)}.`);
+    const raw = option.appUrl ?? DEFAULT_REFINO_APP_URL;
+    let appUrl;
+    try {
+        const url = new URL(raw);
+        if (url.origin !== raw.replace(/\/+$/, "") || (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1"))
+            throw new Error("not an origin");
+        appUrl = url.origin;
+    }
+    catch {
+        throw new Error(`Refino app URL must be an https origin such as ${DEFAULT_REFINO_APP_URL}, got ${JSON.stringify(raw)}.`);
+    }
+    return { siteId: option.siteId, appUrl };
+}
+export function hostLabel(kind) {
+    switch (kind) {
+        case "refino-hosted":
+            return "Refino-hosted copy API";
+        case "next-route-handlers":
+            return "Next.js route handler";
+        case "cloudflare-pages-functions":
+            return "Cloudflare Pages Function";
+        case "vercel-functions":
+            return "Vercel Function";
+        case "netlify-functions":
+            return "Netlify Function";
+        case "next-api-routes":
+            return "Next.js API route";
+        case "custom-server":
+            return "server route";
+        default:
+            return "serverless function";
+    }
+}
+/**
+ * Choose the host path that serves /api/copy and /api/edit-session. The
+ * behaviour is generated once (refino/request-handlers); this decides
+ * which thin wrapper files the host expects, and whether the tool can write
+ * them itself. Inspection facts only; nothing site-specific.
+ */
+export function hostIntegration(inspection, refino = null) {
+    const ext = extension(inspection, false);
+    const provider = inspection.hosting.provider;
+    if (refino) {
+        return {
+            kind: "refino-hosted",
+            provider,
+            generated: true,
+            copyEndpoint: `${refino.appUrl}/api/sites/${refino.siteId}/copy`,
+            sessionEndpoint: `${refino.appUrl}/api/editor/token`,
+            notes: [
+                "Refino hosts the copy API: the browser loads and saves through it with a short-lived editor token, and Refino commits to the repository with the credential stored for this site. This deployment holds no editor password, no session secret, no repository token and no copy adapter, and needs no server functions; it works as a static export on any host.",
+                `Owners start editing at this site's /edit, which sends them to ${refino.appUrl} to sign in; the site must be registered there with exactly this deployment's origin (scheme, host, port) or authorization is refused.`,
+            ],
+        };
+    }
+    const apiDir = inspection.server.apiDir;
+    const serverless = (kind, dir, notes, generated = true) => ({
+        kind,
+        provider,
+        generated,
+        copyEndpoint: `${dir}/copy.${ext}`,
+        sessionEndpoint: `${dir}/edit-session.${ext}`,
+        notes,
+    });
+    const noFilesystem = "Production functions have no writable filesystem: set COPY_ADAPTER=github there with the COPY_GITHUB_* variables; COPY_ADAPTER=local only works in a local Node process.";
+    if (inspection.server.kind === "next-route-handlers") {
+        const base = inspection.routesDir ?? "app";
+        const notes = [
+            "Route handlers under app/api serve both endpoints; the root layout reads the session cookie, so pages are rendered per request.",
+        ];
+        if (provider === "vercel")
+            notes.push("Vercel: functions have no writable filesystem, so production uses COPY_ADAPTER=github; set EDITOR_PASSWORD, EDITOR_SESSION_SECRET and the COPY_* variables in the project's environment settings (Production scope), not in a committed file.");
+        else if (provider === "netlify")
+            notes.push("Netlify (Next runtime): functions have no writable filesystem, so production uses COPY_ADAPTER=github; set the EDITOR_* and COPY_* variables in the site's environment settings.");
+        else if (provider === "cloudflare")
+            notes.push("Cloudflare (OpenNext/next-on-pages): the Workers runtime has no filesystem, so production uses COPY_ADAPTER=github; node:crypto in editor-auth needs the nodejs_compat compatibility flag.");
+        else
+            notes.push("A long-running Node server can use COPY_ADAPTER=local against a checkout; serverless or read-only deployments must use COPY_ADAPTER=github.");
+        return { kind: "next-route-handlers", provider, generated: true, copyEndpoint: `${base}/api/copy/route.${ext}`, sessionEndpoint: `${base}/api/edit-session/route.${ext}`, notes };
+    }
+    if (inspection.server.kind === "next-api-routes") {
+        const base = inspection.routesDir ?? "pages";
+        return {
+            kind: "next-api-routes",
+            provider,
+            generated: false,
+            copyEndpoint: `${base}/api/copy.${ext}`,
+            sessionEndpoint: `${base}/api/edit-session.${ext}`,
+            notes: ["Pages Router API routes use Node's req/res objects, which the generated request-handlers do not adapt yet; the agent writes two small routes that build a Request from req and write the Response back (documented in the instructions).", noFilesystem],
+        };
+    }
+    if (inspection.server.kind === "custom-server") {
+        const dir = inspection.server.apiDir ?? "server";
+        return serverless("custom-server", `${dir}/refino`, ["An existing server hosts the endpoints. The agent mounts the generated request-handlers on /api/copy and /api/edit-session (a Request in, a Response out); frameworks with Web-standard handlers (Hono, h3) pass the request straight through."], false);
+    }
+    if (provider === "cloudflare" || apiDir === "functions") {
+        return serverless("cloudflare-pages-functions", "functions/api", [
+            "Cloudflare Pages Functions: functions/api/copy and functions/api/edit-session are mapped to /api/copy and /api/edit-session automatically; configuration is read from context.env (the project's variables).",
+            "The Workers runtime has no filesystem, so production uses COPY_ADAPTER=github; node:crypto in editor-auth needs the nodejs_compat compatibility flag on the Pages project (Settings → Functions → Compatibility flags).",
+            "Local test without deploying: put the variables in .dev.vars (git-ignored), build, then `npx wrangler pages dev <build output dir> --compatibility-flags nodejs_compat`.",
+        ]);
+    }
+    if (provider === "netlify" || apiDir === "netlify/functions") {
+        return serverless("netlify-functions", "netlify/functions", ["Netlify Functions 2.0: each file default-exports a Request → Response handler mounted at the path in its `config`; configuration is read from process.env (the site's environment variables).", noFilesystem]);
+    }
+    if (provider === "vercel") {
+        return serverless("vercel-functions", "api", ["Vercel Functions (Node.js runtime, Web-standard signature): api/copy and api/edit-session export GET/POST/DELETE handlers and are served at /api/copy and /api/edit-session; configuration is read from process.env (the project's environment variables).", noFilesystem]);
+    }
+    return serverless("unknown-serverless", "api", ["No hosting provider was identified. The behaviour is in the generated request-handlers; the agent adds one function per route in the host's format that passes the Request and the environment object through.", noFilesystem], false);
+}
+/** Where a serverless copy endpoint lives for the detected host. */
+export function serverlessEndpointPath(inspection, _ext) {
+    const host = hostIntegration(inspection);
+    return { path: host.copyEndpoint, note: host.notes[0] ?? "" };
+}
+export function integrationPoints(inspection, refino = null) {
+    const ts = (jsx) => extension(inspection, jsx);
+    const notesProvider = [];
+    const notesEndpoint = [];
+    let providerFile;
+    let providerStrategy;
+    let endpointPath;
+    let endpointKind;
+    if (refino) {
+        const host = hostIntegration(inspection, refino);
+        const base = inspection.routesDir ?? (inspection.router === "next-pages" ? "pages" : "app");
+        providerFile =
+            inspection.router === "next-app"
+                ? (inspection.layouts.find((layout) => layout === `${base}/layout.${ts(true)}` || /^(src\/)?app\/layout\./.test(layout)) ?? inspection.layouts[0] ?? `${base}/layout.${ts(true)}`)
+                : inspection.router === "next-pages"
+                    ? (inspection.layouts[0] ?? `${base}/_app.${ts(true)}`)
+                    : (inspection.routes[0]?.file ?? inspection.entry);
+        providerStrategy = "refino-hosted";
+        notesProvider.push(`Render <CopyEditing content={copy}> from ${BOILERPLATE_DIR}/copy-editing.${ts(true)} around everything ${providerFile ?? "the root component"} renders; pass no editing prop. Edit mode is decided in the browser from the Refino editor session, so the server never reads cookies and pages can stay static.`);
+        return {
+            provider: { file: providerFile, strategy: providerStrategy, notes: notesProvider },
+            endpoint: { path: host.copyEndpoint, kind: "refino-hosted", notes: [host.notes[0]] },
+            host,
+            auth: { strategy: "refino-hosted", existing: inspection.auth.libraries, notes: ["Owners sign in to Refino (GitHub) and Refino authorizes this site per request; the site has no login of its own."] },
+            persistence: {
+                local: { adapter: "none (Refino writes to the repository)", filePath: defaultContentFile(inspection) },
+                github: { adapter: "Refino (credential stored per site in Refino)", envVars: [] },
+            },
+            boilerplateDir: BOILERPLATE_DIR,
+        };
+    }
+    switch (inspection.router) {
+        case "next-app": {
+            const base = inspection.routesDir ?? "app";
+            providerFile = inspection.layouts.find((layout) => layout === `${base}/layout.${ts(true)}` || /^(src\/)?app\/layout\./.test(layout)) ?? inspection.layouts[0] ?? `${base}/layout.${ts(true)}`;
+            if (inspection.server.kind === "static") {
+                // output: "export": the layout cannot read cookies and route handlers cannot be exported.
+                providerStrategy = "next-app-root-layout-client-session";
+                notesProvider.push(`Render <CopyEditing content={copy}> around {children} in the root layout (${providerFile}); pass no editing prop. ${inspection.nextConfig.file ?? "next.config"} sets output: "export", so the layout cannot read cookies; the generated client component ${BOILERPLATE_DIR}/copy-editing.${ts(true)} asks GET /api/edit-session in the browser and turns edit mode on only for a 204.`);
+                const serverless = serverlessEndpointPath(inspection, ts(false));
+                endpointPath = serverless.path;
+                endpointKind = "serverless-function";
+                notesEndpoint.push(`Route handlers under ${base}/api cannot be used with output: "export". ${serverless.note}`);
+                break;
+            }
+            providerStrategy = "next-app-root-layout";
+            notesProvider.push(`Render <CopyEditing content={copy} editing={await isEditorAuthenticated()}> around {children} in the root layout (${providerFile}). The layout is a server component, so the provider is wrapped by the generated client component ${BOILERPLATE_DIR}/copy-editing.${ts(true)}.`);
+            endpointPath = `${base}/api/copy/route.${ts(false)}`;
+            endpointKind = "next-route-handler";
+            notesEndpoint.push("GET and POST handlers wrapping createContentApi; both call isEditorAuthenticated() first.");
+            break;
+        }
+        case "next-pages": {
+            const base = inspection.routesDir ?? "pages";
+            providerFile = inspection.layouts[0] ?? `${base}/_app.${ts(true)}`;
+            providerStrategy = "next-pages-app";
+            notesProvider.push(`Wrap <Component {...pageProps} /> in ${providerFile} with RefinoProvider. Compute the editing flag in getServerSideProps or via a small /api/edit-session check, never from the query string.`);
+            endpointPath = `${base}/api/copy.${ts(false)}`;
+            endpointKind = "next-api-route";
+            notesEndpoint.push("Single API route switching on req.method, wrapping createContentApi; re-check the session cookie on every request.");
+            break;
+        }
+        default: {
+            providerFile = inspection.routes[0]?.file ?? inspection.entry;
+            providerStrategy = "wrap-app-component";
+            notesProvider.push(`Wrap the root component in ${providerFile ?? "the entry file"} with the generated ${BOILERPLATE_DIR}/copy-editing.${ts(true)} (CopyEditing). It asks GET /api/edit-session in the browser and turns edit mode on only for a 204; never derive edit mode from a query parameter.`);
+            if (inspection.server.kind === "custom-server") {
+                endpointPath = `${inspection.server.apiDir ?? "server"}/refino.${ts(false)}`;
+                endpointKind = "custom-server-route";
+                notesEndpoint.push(`Add GET/POST /api/copy to the existing server (${inspection.server.apiDir ?? "server code"}) wrapping createContentApi behind the owner check.`);
+            }
+            else {
+                const serverless = serverlessEndpointPath(inspection, ts(false));
+                endpointPath = serverless.path;
+                endpointKind = "serverless-function";
+                notesEndpoint.push(`This site has no server. Add one serverless function per route (/api/copy, /api/edit-session) wrapping createContentApi behind the session check. ${serverless.note}`);
+            }
+        }
+    }
+    const authStrategy = inspection.auth.libraries.length > 0 ? "reuse-existing-auth" : "generated-password-login";
+    return {
+        provider: { file: providerFile, strategy: providerStrategy, notes: notesProvider },
+        endpoint: { path: endpointPath, kind: endpointKind, notes: notesEndpoint },
+        host: hostIntegration(inspection),
+        auth: { strategy: authStrategy, existing: inspection.auth.libraries, notes: inspection.auth.notes },
+        persistence: {
+            local: { adapter: "@getrefino/core/local-file", filePath: defaultContentFile(inspection) },
+            github: { adapter: "@getrefino/github", envVars: ["COPY_ADAPTER", "COPY_GITHUB_TOKEN", "COPY_GITHUB_REPO", "COPY_GITHUB_BRANCH", "COPY_FILE_PATH"] },
+        },
+        boilerplateDir: BOILERPLATE_DIR,
+    };
+}
+export function verificationCommands(inspection) {
+    const commands = [];
+    const pm = inspection.packageManager;
+    for (const key of ["typecheck", "lint", "test", "build"]) {
+        const script = inspection.scripts[key];
+        if (script)
+            commands.push(packageManagerRun(pm, script));
+        // A TypeScript project without a typecheck script: the build may not type-check
+        // (Vite never does; Next can be told to ignore errors), so run tsc directly.
+        else if (key === "typecheck" && inspection.language === "typescript" && inspection.typescript && exists(join(appDirectory(inspection), "tsconfig.json"))) {
+            commands.push(packageManagerExec(pm, "tsc --noEmit"));
+        }
+    }
+    return commands;
+}
+export function buildPlan(inspection, scan, options = {}) {
+    const appDir = appDirectory(inspection);
+    const contentFile = options.contentFile ?? defaultContentFile(inspection);
+    const refino = resolveRefinoSite(options.refino);
+    const integration = integrationPoints(inspection, refino);
+    const routes = options.all ? inspection.routes.map((route) => route.path) : (options.routes ?? (inspection.routes.some((route) => route.path === "/") ? ["/"] : inspection.routes.slice(0, 1).map((route) => route.path)));
+    const includeShared = options.includeShared ?? true;
+    // Existing copy: a proposed id that already holds different text needs a decision, never an overwrite.
+    let existing = {};
+    const existingText = readText(join(appDir, contentFile));
+    if (existingText !== null) {
+        try {
+            existing = { ...parseCopy(existingText) };
+        }
+        catch {
+            // Invalid file (verify will report it); still read what we can for collision checks.
+            try {
+                const loose = JSON.parse(existingText);
+                for (const [key, value] of Object.entries(loose))
+                    if (typeof value === "string")
+                        existing[key] = value;
+            }
+            catch {
+                existing = {};
+            }
+        }
+    }
+    const candidates = scan.candidates.map((candidate) => {
+        if (candidate.status === "selected" && candidate.id && candidate.id in existing && existing[candidate.id] !== candidate.text) {
+            return { ...candidate, status: "needs-review", reason: `"${candidate.id}" already exists in ${contentFile} with different text; pick a new id or confirm the replacement.` };
+        }
+        return candidate;
+    });
+    const byScope = {};
+    const byFile = {};
+    let selected = 0;
+    let needsReview = 0;
+    let unsupported = 0;
+    let excluded = 0;
+    for (const candidate of candidates) {
+        if (candidate.status === "selected")
+            selected += 1;
+        else if (candidate.status === "needs-review")
+            needsReview += 1;
+        else if (candidate.status === "unsupported")
+            unsupported += 1;
+        else
+            excluded += 1;
+        if (candidate.status === "selected" || candidate.status === "needs-review") {
+            byScope[candidate.scope] = (byScope[candidate.scope] ?? 0) + 1;
+            byFile[candidate.file] = (byFile[candidate.file] ?? 0) + 1;
+        }
+    }
+    const files = [];
+    const contentExists = exists(join(appDir, contentFile));
+    files.push({ path: PLAN_FILE, action: "create", description: "Machine-readable migration plan for coding agents." });
+    files.push({ path: INSTRUCTIONS_FILE, action: "create", description: "Repository-specific instructions for a coding agent." });
+    files.push({ path: contentFile, action: contentExists ? "merge" : "create", description: contentExists ? "Add selected IDs that are missing; existing values are never changed." : "Canonical copy file with the selected strings." });
+    files.push({ path: CONFIG_FILE, action: exists(join(appDir, CONFIG_FILE)) ? "modify" : "create", description: "Tells refino verify where the content file and endpoint live." });
+    const nextAppWithServer = inspection.router === "next-app" && inspection.server.kind !== "static";
+    const host = integration.host;
+    if (refino) {
+        files.push({ path: inspection.packageJson ?? "package.json", action: "modify", description: "Add @getrefino/core and @getrefino/react to dependencies (no @getrefino/github: Refino writes to the repository)." });
+        files.push({ path: `${BOILERPLATE_DIR}/`, action: "create", description: "Public Refino constants, the browser-side authorization client, the provider wrapper and the /edit page component (skipped for files that already exist). No secrets, no server code." });
+        if (inspection.router === "next-app") {
+            files.push({ path: `${inspection.routesDir ?? "app"}/edit/layout.${extension(inspection, true)}`, action: "create", description: "Marks /edit noindex (the client page cannot export metadata)." });
+            files.push({ path: `${inspection.routesDir ?? "app"}/edit/page.${extension(inspection, true)}`, action: "create", description: "/edit: sends the owner to Refino and finishes the authorization (client component, works as a static export)." });
+        }
+        else if (inspection.router === "next-pages") {
+            files.push({ path: `${inspection.routesDir ?? "pages"}/edit.${extension(inspection, true)}`, action: "create", description: "/edit: sends the owner to Refino and finishes the authorization." });
+        }
+    }
+    else {
+        files.push({ path: inspection.packageJson ?? "package.json", action: "modify", description: "Add @getrefino/core, @getrefino/react and @getrefino/github to dependencies." });
+        files.push({ path: ".env.example", action: exists(join(appDir, ".env.example")) ? "append" : "create", description: "Document EDITOR_* and COPY_* variables (no values)." });
+        files.push({ path: `${BOILERPLATE_DIR}/`, action: "create", description: "Isolated auth, adapter, request-handler and provider-wrapper boilerplate (skipped for files that already exist)." });
+    }
+    if (!refino && host.generated) {
+        files.push({ path: host.copyEndpoint, action: "create", description: `${hostLabel(host.kind)} serving GET/POST /api/copy through ${BOILERPLATE_DIR}/request-handlers.` });
+        files.push({ path: host.sessionEndpoint, action: "create", description: `${hostLabel(host.kind)} serving GET/POST/DELETE /api/edit-session (probe, login, logout).` });
+    }
+    if (refino) {
+        // Hosted: no login page, no route handlers, no host functions.
+    }
+    else if (nextAppWithServer) {
+        files.push({ path: `${inspection.routesDir ?? "app"}/edit/page.${extension(inspection, true)}`, action: "create", description: "Minimal /edit login page." });
+    }
+    else if (inspection.router === "next-app") {
+        files.push({ path: `${inspection.routesDir ?? "app"}/edit/layout.${extension(inspection, true)}`, action: "create", description: "Marks /edit noindex (the client page cannot export metadata)." });
+        files.push({ path: `${inspection.routesDir ?? "app"}/edit/page.${extension(inspection, true)}`, action: "create", description: "Minimal static /edit login page (posts to the serverless /api/edit-session)." });
+    }
+    const unresolved = [];
+    if (!inspection.supported)
+        unresolved.push(...inspection.unsupportedReasons);
+    if (refino && inspection.router !== "next-app" && inspection.router !== "next-pages") {
+        unresolved.push(`Add a route for /edit that renders the generated ${BOILERPLATE_DIR}/edit-page (the owner's entry point for Refino sign-in); the instructions describe it.`);
+    }
+    if (!refino && !inspection.server.capable) {
+        unresolved.push(host.generated
+            ? `No server capability detected (${inspection.server.notes[0] ?? "static site"}); the generated ${hostLabel(host.kind)}s ${host.copyEndpoint} and ${host.sessionEndpoint} host /api/copy and /api/edit-session and must be deployed with the site.`
+            : `No server capability detected (${inspection.server.notes[0] ?? "static site"}); a serverless function must host /api/copy and /api/edit-session before editing works. The instructions describe it for ${inspection.hosting.provider ?? "an unidentified host"}.`);
+    }
+    if (needsReview > 0)
+        unresolved.push(`${needsReview} candidate(s) need a human or agent decision on naming or inclusion (status "needs-review").`);
+    if (unsupported > 0)
+        unresolved.push(`${unsupported} string(s) mix markup or interpolation and are not plain text (status "unsupported"). Split them or leave them in code.`);
+    // Hosted mode decides edit mode in the browser from the Refino editor session, so no page computes a flag.
+    if (!refino && inspection.router === "next-pages")
+        unresolved.push("Pages Router: the editing flag must be computed server-side per page (getServerSideProps) or via an auth-check endpoint.");
+    if (!refino && !host.generated)
+        unresolved.push(`The endpoint behaviour is generated as ${BOILERPLATE_DIR}/request-handlers; mounting it for this host (${host.kind}) is an agent task described in the instructions.`);
+    if (inspection.git.isRepository && inspection.git.clean === false)
+        unresolved.push("Working tree has uncommitted changes; commit or stash before letting an agent modify files.");
+    return {
+        version: 1,
+        generatedAt: (options.now ?? new Date()).toISOString(),
+        tool: { name: TOOL_NAME, version: TOOL_VERSION },
+        repository: {
+            root: inspection.root,
+            appRoot: inspection.appRoot,
+            framework: inspection.framework,
+            router: inspection.router,
+            language: inspection.language,
+            packageManager: inspection.packageManager,
+            react: inspection.react?.version ?? null,
+            next: inspection.next?.version ?? null,
+            scripts: inspection.scripts,
+            git: inspection.git,
+            hosting: inspection.hosting.provider,
+            auth: inspection.auth.libraries,
+            server: inspection.server.kind,
+            // Mode-aware: the self-hosted prescriptions ("the copy endpoint must be a
+            // serverless function", "the endpoint belongs in functions/") contradict a
+            // hosted plan, where Refino serves the copy API and the site has none.
+            serverNotes: refino ? inspection.server.notes : [...inspection.server.notes, ...inspection.server.selfHosted],
+        },
+        scope: {
+            routes,
+            includeShared,
+            description: options.all ? "Every discovered route plus shared chrome." : `${routes.join(", ") || "no routes"}${includeShared ? " plus shared chrome (layouts, navigation, footer)" : ""}.`,
+        },
+        contentFile: { path: contentFile, exists: contentExists },
+        configFile: { path: CONFIG_FILE, exists: exists(join(appDir, CONFIG_FILE)) },
+        integration,
+        refino,
+        copy: candidates,
+        summary: { selected, needsReview, unsupported, excluded, byScope, byFile },
+        files,
+        verification: { commands: verificationCommands(inspection), cli: "npx @getrefino/cli verify" },
+        unresolved,
+    };
+}
+/** Convenience: inspect + scan + plan in one call. */
+export function planMigration(inspection, options = {}) {
+    const scanOptions = {};
+    resolveRefinoSite(options.refino); // fail fast on a malformed connection before scanning
+    if (options.routes)
+        scanOptions.routes = options.routes;
+    if (options.all !== undefined)
+        scanOptions.all = options.all;
+    if (options.includeShared !== undefined)
+        scanOptions.includeShared = options.includeShared;
+    const scan = scanCopy(inspection, scanOptions);
+    return buildPlan(inspection, scan, options);
+}
+/** The copy-file content a plan would create: selected candidates only, in scan order. */
+export function planContent(plan) {
+    const content = {};
+    for (const candidate of plan.copy) {
+        if (candidate.status === "selected" && candidate.id && !(candidate.id in content))
+            content[candidate.id] = candidate.text;
+    }
+    return content;
+}

package/dist/scan.d.ts

@@ -0,0 +1,67 @@
+import type { DataflowContext } from "./dataflow.js";
+import type { CopyCandidate, CopyClassification, RepositoryInspection, ScanResult } from "./types.js";
+export interface ScanOptions {
+    /** Restrict to these route paths (files reachable from them). Shared files are included when includeShared is true. */
+    readonly routes?: readonly string[];
+    readonly includeShared?: boolean;
+    /** Scan every source file regardless of route reachability. */
+    readonly all?: boolean;
+}
+export interface RawCandidate {
+    readonly text: string;
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly source: CopyCandidate["source"];
+    readonly element: string | null;
+    readonly key: string | null;
+    readonly component: string | null;
+    readonly scope: string;
+    readonly classification: CopyClassification;
+    readonly reason: string;
+    /** Context for ID generation. */
+    readonly context: CandidateContext;
+}
+export interface CandidateContext {
+    /** Ancestor JSX tags, outermost first, within the enclosing component. */
+    readonly ancestors: readonly string[];
+    /** Nearest landmark hint: id or first className token of a section-like ancestor. */
+    readonly landmark: string | null;
+    readonly className: string | null;
+    /** Name of the array variable when the candidate comes from a data object. */
+    readonly collection: string | null;
+    /** Explicit id/key/slug/name of the data item, when present. */
+    readonly itemKey: string | null;
+    /** Title-ish text of the data item / component element, for deriving keys. */
+    readonly itemTitle: string | null;
+    /** Position of this element among same-tag siblings inside the same parent. */
+    readonly siblingIndex: number;
+    /** How many same-tag siblings (including this one) share the parent. */
+    readonly siblingCount: number;
+    readonly insideMap: boolean;
+    /** True for an inline element (link, emphasis) that sits inside a sentence with other text. */
+    readonly inlineInSentence: boolean;
+    /** Literal path of the enclosing link (`href`, `to`), when it is a site path. Names repeated links stably. */
+    readonly href: string | null;
+    /** True when the data array lives in another module than the JSX that maps it; the collection then names the section. */
+    readonly collectionImported: boolean;
+    /**
+     * The value is demonstrably rendered but a person should confirm the id or
+     * the inclusion: an ordinal position, one of several alternative states, or
+     * a string a handler assigns. Forces `needs-review`.
+     */
+    readonly ambiguous?: boolean;
+    readonly route: string | null;
+}
+/** JSX text keeps entities as written (`&`); the copy file must hold the real characters. */
+export declare function decodeJsxEntities(text: string): string;
+/** Tailwind-style utility tokens (`sticky`, `py-24`, `lg:grid-cols-2`, `text-[1rem]`) never name a section. */
+export declare function isUtilityClass(token: string): boolean;
+export interface ScanFileOptions {
+    /** Shared across the files of one scan so a data module mapped by two components is reported once. */
+    readonly emitted?: Set<string>;
+    /** Shared component-render lookups, so one component is analysed once per scan. */
+    readonly flow?: DataflowContext;
+}
+export declare function scanFile(appDir: string, absoluteFile: string, scope: string, route: string | null, options?: ScanFileOptions): RawCandidate[];
+export declare function scanCopy(inspection: RepositoryInspection, options?: ScanOptions): ScanResult;