@getrefino/onboarding 0.1.0-rc.1

package/dist/verify.js

@@ -0,0 +1,403 @@
+/**
+ * Verify an integrated site without modifying it. Produces a list of
+ * checks with fixes an agent can act on, and optionally runs the
+ * repository's own verification scripts.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { isContentId, parseCopy } from "@getrefino/core";
+import ts from "typescript";
+import { exists, isFile, isTestOrStoryFile, readJson, readText, rel, walkFiles } from "./fs.js";
+import { parseSource, readPathAliases, reachableFiles, resolveImport } from "./graph.js";
+import { LEGACY_CONFIG_FILE_NAME, appDirectory, inspectRepository } from "./inspect.js";
+import { BOILERPLATE_DIR, CONFIG_FILE, verificationCommands } from "./plan.js";
+const SECRET_NAMES = ["COPY_GITHUB_TOKEN", "EDITOR_SESSION_SECRET", "EDITOR_PASSWORD"];
+const SERVER_ONLY_IMPORTS = ["@getrefino/github", "@getrefino/core/local-file"];
+function collectEditableTextUses(appDir, files) {
+    const uses = [];
+    for (const file of files) {
+        const text = readText(file);
+        if (!text || !text.includes("EditableText"))
+            continue;
+        const source = parseSource(file, text);
+        const visit = (node) => {
+            if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && node.tagName.text === "EditableText") {
+                const { line } = source.getLineAndCharacterOfPosition(node.getStart(source));
+                const attr = node.attributes.properties.find((prop) => ts.isJsxAttribute(prop) && ts.isIdentifier(prop.name) && prop.name.text === "id");
+                let id = null;
+                let pattern = null;
+                if (attr?.initializer) {
+                    if (ts.isStringLiteral(attr.initializer))
+                        id = attr.initializer.text;
+                    else if (ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
+                        const expression = attr.initializer.expression;
+                        if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))
+                            id = expression.text;
+                        else if (ts.isTemplateExpression(expression)) {
+                            const HOLE = "__REFINO_HOLE__";
+                            const literal = expression.head.text + expression.templateSpans.map((span) => `${HOLE}${span.literal.text}`).join("");
+                            pattern = new RegExp(`^${literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").split(HOLE).join("[A-Za-z0-9_-]+")}$`);
+                        }
+                    }
+                }
+                uses.push({ file: rel(appDir, file), line: line + 1, id, pattern });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return uses;
+}
+/**
+ * Components a provider file renders outside its <CopyEditing>/<RefinoProvider>
+ * whose render tree contains EditableText: their ids would show up as visible text.
+ */
+function uncoveredComponents(appDir, providerFile, editableFiles) {
+    const absolute = join(appDir, providerFile);
+    const text = readText(absolute);
+    if (!text)
+        return [];
+    const source = parseSource(absolute, text);
+    const providerRanges = [];
+    const outsideTags = new Map();
+    const isProviderTag = (node) => ts.isIdentifier(node.tagName) && /^(CopyEditing|RefinoProvider)$/.test(node.tagName.text);
+    const collectProviders = (node) => {
+        if (ts.isJsxElement(node) && isProviderTag(node.openingElement))
+            providerRanges.push([node.getStart(source), node.getEnd()]);
+        ts.forEachChild(node, collectProviders);
+    };
+    collectProviders(source);
+    if (providerRanges.length === 0)
+        return [];
+    const collectOutside = (node) => {
+        if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[A-Z]/.test(node.tagName.text) && !isProviderTag(node)) {
+            const start = node.getStart(source);
+            if (!providerRanges.some(([from, to]) => start >= from && start < to))
+                outsideTags.set(node.tagName.text, true);
+        }
+        ts.forEachChild(node, collectOutside);
+    };
+    collectOutside(source);
+    if (outsideTags.size === 0)
+        return [];
+    const aliases = readPathAliases(appDir);
+    const importedFrom = new Map();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause)
+            continue;
+        const resolved = resolveImport(absolute, statement.moduleSpecifier.text, appDir, aliases);
+        if (!resolved)
+            continue;
+        if (statement.importClause.name)
+            importedFrom.set(statement.importClause.name.text, resolved);
+        const bindings = statement.importClause.namedBindings;
+        if (bindings && ts.isNamedImports(bindings))
+            for (const element of bindings.elements)
+                importedFrom.set(element.name.text, resolved);
+    }
+    const cache = new Map();
+    const problems = [];
+    for (const tag of outsideTags.keys()) {
+        const file = importedFrom.get(tag);
+        if (!file)
+            continue;
+        const reached = reachableFiles(file, appDir, aliases, cache, { renderTreeOnly: true });
+        const hit = [...reached].find((candidate) => editableFiles.has(candidate));
+        if (hit)
+            problems.push(`<${tag} /> in ${providerFile} renders EditableText (${rel(appDir, hit)}) but sits outside the provider`);
+    }
+    return problems;
+}
+function duplicateKeys(text) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const match of text.matchAll(/^\s*"((?:[^"\\]|\\.)*)"\s*:/gm)) {
+        const key = match[1];
+        if (seen.has(key))
+            duplicates.add(key);
+        seen.add(key);
+    }
+    return [...duplicates];
+}
+function isClientFile(text, framework) {
+    if (/^\s*["']use client["']/.test(text))
+        return true;
+    // Outside Next.js every component file is a browser file.
+    return framework !== "next" && /from ["']react["']/.test(text);
+}
+const SELF_HOSTED_MODULES = ["request-handlers", "editor-auth", "content-adapter", "editor-session"];
+const SELF_HOSTED_ENDPOINTS = ["app/api/copy/route", "src/app/api/copy/route", "app/api/edit-session/route", "src/app/api/edit-session/route", "functions/api/copy", "functions/api/edit-session", "api/copy", "api/edit-session", "netlify/functions/copy", "netlify/functions/edit-session", "pages/api/copy", "pages/api/edit-session"];
+const SITE_SECRET_NAMES = ["EDITOR_PASSWORD", "EDITOR_SESSION_SECRET", "COPY_GITHUB_TOKEN", "COPY_ADAPTER"];
+/**
+ * A Refino-hosted site must hold the public constants and the browser
+ * client, and nothing of the self-hosted path: no endpoint files, no
+ * adapter, no secrets, no server-side edit decision.
+ */
+function hostedChecks(appDir, inspection, hosted, sourceFiles, rendersProvider, add) {
+    const relFiles = sourceFiles.map((file) => rel(appDir, file));
+    const find = (base) => relFiles.find((file) => new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.(tsx?|jsx?)$`).test(file));
+    const siteFile = find(`${BOILERPLATE_DIR}/refino-site`);
+    const siteText = siteFile ? (readText(join(appDir, siteFile)) ?? "") : "";
+    if (!siteFile)
+        add({ id: "refino-site", status: "fail", message: `No ${BOILERPLATE_DIR}/refino-site module with the public Refino constants.`, fix: `Run \`refino init --agent --refino-site ${hosted.siteId}\` to generate it.` });
+    else if (!siteText.includes(JSON.stringify(hosted.siteId)) || !siteText.includes(JSON.stringify(hosted.appUrl)))
+        add({ id: "refino-site", status: "fail", message: `${siteFile} does not name site ${hosted.siteId} at ${hosted.appUrl} as ${CONFIG_FILE} does.`, fix: "Regenerate the module or fix the config so both agree." });
+    else
+        add({ id: "refino-site", status: "pass", message: `Connected to Refino site ${hosted.siteId} at ${hosted.appUrl}.` });
+    const missing = ["refino-client", "copy-editing", "edit-page"].filter((name) => !find(`${BOILERPLATE_DIR}/${name}`));
+    if (missing.length > 0)
+        add({ id: "refino-client", status: "fail", message: `Missing generated hosted modules: ${missing.map((name) => `${BOILERPLATE_DIR}/${name}`).join(", ")}.`, fix: "Run `refino init --agent --refino-site …` again; existing files are kept." });
+    else
+        add({ id: "refino-client", status: "pass", message: "Browser-side Refino client, provider wrapper and /edit page are present." });
+    const editRoute = inspection.router === "next-app" ? find(`${inspection.routesDir ?? "app"}/edit/page`) : inspection.router === "next-pages" ? find(`${inspection.routesDir ?? "pages"}/edit`) : relFiles.find((file) => !file.startsWith(`${BOILERPLATE_DIR}/`) && /from ["'][^"']*edit-page["']/.test(readText(join(appDir, file)) ?? ""));
+    if (editRoute)
+        add({ id: "edit-route", status: "pass", message: `/edit is served by ${editRoute}.` });
+    else
+        add({ id: "edit-route", status: "fail", message: "Nothing serves /edit, the owner's entry point for Refino sign-in.", fix: inspection.router === "next-app" || inspection.router === "next-pages" ? "Run `refino init --agent --refino-site …` to generate the /edit route." : `Add a route for /edit rendering the default export of ${BOILERPLATE_DIR}/edit-page.` });
+    const leftovers = [...SELF_HOSTED_MODULES.map((name) => find(`${BOILERPLATE_DIR}/${name}`)), ...SELF_HOSTED_ENDPOINTS.map((base) => find(base))].filter((file) => Boolean(file));
+    if (leftovers.length > 0)
+        add({ id: "hosted-leftovers", status: "fail", message: "Self-hosted endpoint or auth files exist although Refino hosts the copy API.", details: leftovers, fix: "Delete them: a Refino-hosted site runs no editor endpoints and holds no secrets." });
+    else
+        add({ id: "hosted-leftovers", status: "pass", message: "No self-hosted endpoints or auth modules remain." });
+    const mentions = [];
+    for (const file of relFiles) {
+        const text = readText(join(appDir, file)) ?? "";
+        for (const name of SITE_SECRET_NAMES)
+            if (text.includes(name))
+                mentions.push(`${file} mentions ${name}`);
+    }
+    if (mentions.length > 0)
+        add({ id: "hosted-secrets", status: "fail", message: "The site references editor or repository secrets that hosted mode must not use.", details: mentions, fix: "Remove them; Refino holds the credential for this site." });
+    else
+        add({ id: "hosted-secrets", status: "pass", message: "No editor password, session secret, repository token or copy adapter in the site." });
+    for (const file of rendersProvider) {
+        const text = readText(join(appDir, file)) ?? "";
+        if (/from ["']next\/headers["']/.test(text) || /editor-session["']/.test(text) || /editing=\{/.test(text))
+            add({ id: "hosted-provider", status: "fail", message: `${file} decides edit mode on the server; a Refino-hosted site decides it in the browser.`, fix: `Render <CopyEditing content={copy}> from ${BOILERPLATE_DIR}/copy-editing without an editing prop and without next/headers.` });
+    }
+}
+export function verifyIntegration(rootPath, options = {}) {
+    const inspection = inspectRepository(rootPath, options);
+    const appDir = appDirectory(inspection);
+    const checks = [];
+    const add = (check) => checks.push(check);
+    // A site onboarded before the Refino rename still has the legacy config file.
+    const config = readJson(join(appDir, CONFIG_FILE)) ?? readJson(join(appDir, LEGACY_CONFIG_FILE_NAME));
+    const contentFile = options.contentFile ?? config?.contentFile ?? inspection.refino.contentFile ?? "content/copy.json";
+    const hosted = typeof config?.refino?.siteId === "string" && typeof config.refino.appUrl === "string" ? { siteId: config.refino.siteId, appUrl: config.refino.appUrl } : null;
+    // Packages
+    const installed = inspection.refino.packages.map((pkg) => pkg.name);
+    const legacyInstalled = installed.filter((name) => name.startsWith("@inline-copy/"));
+    const missingPackages = ["@getrefino/core", "@getrefino/react"].filter((name) => !installed.includes(name));
+    if (missingPackages.length > 0 && legacyInstalled.length > 0) {
+        add({
+            id: "packages",
+            status: "fail",
+            message: `This site still depends on the pre-rename packages (${legacyInstalled.join(", ")}).`,
+            fix: "Replace every @inline-copy/* dependency and import with the matching @getrefino/* package, then install.",
+        });
+    }
+    else if (missingPackages.length > 0) {
+        add({ id: "packages", status: "fail", message: `Missing dependencies: ${missingPackages.join(", ")}.`, fix: `Add them to package.json dependencies and install.` });
+    }
+    else {
+        const versions = inspection.refino.packages.map((pkg) => pkg.version.replace(/^[\^~]/, "").split(".")[0]);
+        const majors = new Set(versions);
+        if (majors.size > 1)
+            add({ id: "packages", status: "warn", message: `@getrefino packages have different major versions (${inspection.refino.packages.map((p) => `${p.name}@${p.version}`).join(", ")}).`, fix: "Align them to the same version." });
+        else
+            add({ id: "packages", status: "pass", message: `Installed: ${inspection.refino.packages.map((p) => `${p.name}@${p.version}`).join(", ")}.` });
+        if (!exists(join(appDir, "node_modules", "@getrefino", "core")))
+            add({ id: "packages-installed", status: "warn", message: "node_modules does not contain @getrefino/core yet.", fix: "Run the package manager install." });
+    }
+    // Content file
+    const contentPath = join(appDir, contentFile);
+    let content = null;
+    const contentText = readText(contentPath);
+    if (contentText === null) {
+        add({ id: "content-file", status: "fail", message: `Canonical copy file not found at ${contentFile}.`, fix: "Create it (a flat JSON object of id -> string) or set contentFile in refino.config.json." });
+    }
+    else {
+        try {
+            content = { ...parseCopy(contentText) };
+            add({ id: "content-file", status: "pass", message: `${contentFile} parses; ${Object.keys(content).length} ids.` });
+        }
+        catch (error) {
+            add({ id: "content-file", status: "fail", message: `${contentFile} is invalid: ${error.message}`, fix: "Make it a flat JSON object whose keys are dotted ids and values are plain strings." });
+        }
+        const duplicates = duplicateKeys(contentText);
+        if (duplicates.length > 0)
+            add({ id: "content-duplicates", status: "fail", message: `Duplicate ids in ${contentFile}: ${duplicates.join(", ")}.`, fix: "Keep one entry per id." });
+        else
+            add({ id: "content-duplicates", status: "pass", message: "No duplicate ids." });
+        if (content) {
+            const invalid = Object.keys(content).filter((id) => !isContentId(id));
+            if (invalid.length > 0)
+                add({ id: "content-ids", status: "fail", message: `Invalid ids: ${invalid.join(", ")}.`, fix: "Use dotted segments of letters, digits, - and _ only." });
+            else
+                add({ id: "content-ids", status: "pass", message: "All ids are valid." });
+        }
+    }
+    // Source scan
+    const sourceFiles = walkFiles(appDir).filter((file) => !isTestOrStoryFile(rel(appDir, file)));
+    const uses = collectEditableTextUses(appDir, sourceFiles);
+    if (uses.length === 0) {
+        add({ id: "editable-text", status: "fail", message: "No <EditableText> usages found.", fix: "Replace the selected strings with <EditableText id=\"…\" as=\"tag\" /> as described in .refino/AGENT_INSTRUCTIONS.md." });
+    }
+    else {
+        add({ id: "editable-text", status: "pass", message: `${uses.length} <EditableText> usage(s) in ${new Set(uses.map((use) => use.file)).size} file(s).` });
+        const withoutId = uses.filter((use) => !use.id && !use.pattern);
+        if (withoutId.length > 0)
+            add({ id: "editable-text-ids", status: "warn", message: `${withoutId.length} <EditableText> usage(s) have a non-literal id and cannot be checked statically.`, details: withoutId.map((use) => `${use.file}:${use.line}`) });
+        if (content) {
+            const ids = new Set(Object.keys(content));
+            const missing = uses.filter((use) => use.id && !ids.has(use.id));
+            if (missing.length > 0)
+                add({ id: "missing-ids", status: "fail", message: `${missing.length} EditableText id(s) are not in ${contentFile}.`, details: missing.map((use) => `${use.id} (${use.file}:${use.line})`), fix: "Add the id to the copy file with the original text, or fix the id in the component." });
+            else
+                add({ id: "missing-ids", status: "pass", message: "Every literal EditableText id exists in the copy file." });
+            const referenced = new Set();
+            for (const use of uses) {
+                if (use.id)
+                    referenced.add(use.id);
+                if (use.pattern)
+                    for (const id of ids)
+                        if (use.pattern.test(id))
+                            referenced.add(id);
+            }
+            const orphans = [...ids].filter((id) => !referenced.has(id));
+            const hasDynamicIds = uses.some((use) => !use.id && !use.pattern);
+            if (orphans.length > 0)
+                add({ id: "orphan-ids", status: hasDynamicIds ? "warn" : "warn", message: `${orphans.length} id(s) in ${contentFile} are not referenced by any EditableText${hasDynamicIds ? " (some usages have dynamic ids, so this may be fine)" : ""}.`, details: orphans, fix: "Remove unused ids or reference them." });
+            else
+                add({ id: "orphan-ids", status: "pass", message: "Every id is referenced." });
+        }
+    }
+    // Provider: generated boilerplate (refino/copy-editing) does not count until something renders it.
+    const boilerplatePrefix = `${BOILERPLATE_DIR}/`;
+    const rendersProvider = sourceFiles
+        .map((file) => rel(appDir, file))
+        .filter((file) => !file.startsWith(boilerplatePrefix))
+        .filter((file) => {
+        const text = readText(join(appDir, file)) ?? "";
+        return text.includes("RefinoProvider") || /from ["'][^"']*copy-editing["']/.test(text);
+    });
+    if (rendersProvider.length === 0) {
+        add({ id: "provider", status: "fail", message: inspection.refino.providerFiles.length > 0 ? "RefinoProvider exists only in generated boilerplate; nothing renders it yet." : "RefinoProvider is not rendered anywhere.", fix: "Wrap the app root (layout, _app or App) with the provider (CopyEditing from refino/copy-editing); see the instructions." });
+    }
+    else {
+        add({ id: "provider", status: "pass", message: `Provider rendered from ${rendersProvider.join(", ")}.` });
+        const editableFiles = new Set(uses.map((use) => join(appDir, use.file)));
+        const uncovered = rendersProvider.flatMap((file) => uncoveredComponents(appDir, file, editableFiles));
+        if (uncovered.length > 0)
+            add({ id: "provider-coverage", status: "fail", message: "Some editable chrome is rendered outside the provider; its ids would be displayed as text.", details: uncovered, fix: "Move those components inside <CopyEditing> (wrap everything the layout renders, not only {children})." });
+        else
+            add({ id: "provider-coverage", status: "pass", message: "Every component the provider file renders is inside the provider." });
+        for (const file of rendersProvider) {
+            const text = readText(join(appDir, file)) ?? "";
+            if (/editing(?:=\{true\}|=\{!0\}|\s*:\s*true\b)/.test(text))
+                add({ id: "provider-editing-literal", status: "fail", message: `${file} hard-codes editing={true}.`, fix: "Compute editing from a server-side session check." });
+            if (/searchParams[^\n]*edit|\?edit=|get\(["']edit["']\)/.test(text))
+                add({ id: "provider-editing-query", status: "fail", message: `${file} appears to derive edit mode from the URL.`, fix: "Edit mode must come from an authenticated server check, never a query parameter." });
+        }
+    }
+    if (hosted) {
+        hostedChecks(appDir, inspection, hosted, sourceFiles, rendersProvider, add);
+    }
+    // Endpoint (self-hosted only; a hosted site has none)
+    const endpointPath = !hosted && config?.endpoint ? join(appDir, config.endpoint) : null;
+    if (hosted) {
+        // Checked above.
+    }
+    else if (endpointPath && isFile(endpointPath)) {
+        add({ id: "endpoint", status: "pass", message: `Copy endpoint exists at ${config.endpoint}.` });
+    }
+    else if (inspection.refino.endpointFiles.length > 0) {
+        add({ id: "endpoint", status: "pass", message: `createContentApi used in ${inspection.refino.endpointFiles.join(", ")}.` });
+    }
+    else {
+        add({ id: "endpoint", status: "fail", message: "No copy endpoint found (nothing calls createContentApi).", fix: `Create an authenticated GET/POST endpoint at ${config?.endpoint ?? "/api/copy"} wrapping createContentApi.` });
+    }
+    // The session endpoint (GET probe, POST login, DELETE logout) must exist next to the copy endpoint;
+    // static sites decide edit mode in the browser by asking it, server-rendered sites log in through it.
+    const sessionFile = hosted ? null : (config?.sessionEndpoint ?? (inspection.server.kind === "static" && config?.endpoint ? config.endpoint.replace(/\/copy(\.\w+)$/, "/edit-session$1") : null));
+    if (sessionFile && sessionFile !== config?.endpoint) {
+        if (isFile(join(appDir, sessionFile)))
+            add({ id: "session-endpoint", status: "pass", message: `Session endpoint exists at ${sessionFile}.` });
+        else
+            add({ id: "session-endpoint", status: "fail", message: `No session endpoint at ${sessionFile}.`, fix: "Create the /api/edit-session function (GET 204/401, POST login, DELETE logout) as described in .refino/AGENT_INSTRUCTIONS.md; without it edit mode never turns on." });
+    }
+    // Next.js static export: nothing dynamic may be left under app/ or the build fails.
+    if (inspection.nextConfig.output === "export") {
+        const routesDir = inspection.routesDir ?? "app";
+        const leftoverHandlers = sourceFiles
+            .map((file) => rel(appDir, file))
+            .filter((file) => new RegExp(`^${routesDir}/api/(copy|edit-session)/route\\.`).test(file));
+        if (leftoverHandlers.length > 0)
+            add({ id: "static-export-route-handlers", status: "fail", message: `Route handlers exist but ${inspection.nextConfig.file} sets output: "export".`, details: leftoverHandlers, fix: `Delete them and serve /api/copy and /api/edit-session from ${config?.endpoint ? `${config.endpoint} and its edit-session sibling` : "the host's serverless functions"}.` });
+        for (const file of rendersProvider) {
+            const text = readText(join(appDir, file)) ?? "";
+            if (/from ["']next\/headers["']/.test(text) || /editor-session["']/.test(text))
+                add({ id: "static-export-provider", status: "fail", message: `${file} reads request state (next/headers or editor-session), which a static export cannot do.`, fix: "Render <CopyEditing content={copy}> without an editing prop; the generated wrapper probes GET /api/edit-session in the browser." });
+        }
+    }
+    const adapterUsed = sourceFiles.some((file) => /create(GitHub|LocalFile)ContentAdapter/.test(readText(file) ?? ""));
+    if (hosted) {
+        if (adapterUsed)
+            add({ id: "adapter", status: "fail", message: "A persistence adapter is constructed although Refino hosts the copy API.", fix: "Remove the local adapter and any repository credential; Refino writes to the repository." });
+        else
+            add({ id: "adapter", status: "pass", message: "No persistence adapter in the site: Refino writes to the repository." });
+    }
+    else if (!adapterUsed)
+        add({ id: "adapter", status: "fail", message: "No persistence adapter is constructed.", fix: "Use createLocalFileContentAdapter (dev) and createGitHubContentAdapter (production) behind the endpoint." });
+    else
+        add({ id: "adapter", status: "pass", message: "A persistence adapter is constructed server-side." });
+    // Secret safety
+    const leaks = [];
+    for (const file of sourceFiles) {
+        const text = readText(file) ?? "";
+        const relative = rel(appDir, file);
+        if (/NEXT_PUBLIC_(COPY_GITHUB|EDITOR_)|VITE_(COPY_GITHUB|EDITOR_)/.test(text))
+            leaks.push(`${relative}: exposes a Refino secret with a public prefix`);
+        if (!isClientFile(text, inspection.framework))
+            continue;
+        for (const name of SERVER_ONLY_IMPORTS)
+            if (text.includes(`"${name}"`) || text.includes(`'${name}'`))
+                leaks.push(`${relative}: client file imports ${name}`);
+        for (const secret of SECRET_NAMES)
+            if (text.includes(secret))
+                leaks.push(`${relative}: client file mentions ${secret}`);
+        if (/from ["'][^"']*(content-adapter|editor-auth|request-handlers)["']/.test(text))
+            leaks.push(`${relative}: client file imports server-only Refino module`);
+    }
+    if (leaks.length > 0)
+        add({ id: "secrets", status: "fail", message: "Persistence code or secrets reachable from the browser.", details: leaks, fix: "Move adapter construction and secrets into server-only modules." });
+    else
+        add({ id: "secrets", status: "pass", message: "No adapters or secrets in client code." });
+    // Env documentation (self-hosted only)
+    const envExample = readText(join(appDir, ".env.example"));
+    if (hosted) {
+        if (envExample && /EDITOR_PASSWORD|COPY_GITHUB_TOKEN|COPY_ADAPTER/.test(envExample))
+            add({ id: "env-example", status: "warn", message: ".env.example still documents self-hosted EDITOR_*/COPY_* variables that a Refino-hosted site does not use.", fix: "Remove the Refino block from .env.example." });
+        else
+            add({ id: "env-example", status: "pass", message: "No editor or repository variables are needed: Refino hosts them." });
+    }
+    else if (envExample && envExample.includes("COPY_GITHUB_TOKEN"))
+        add({ id: "env-example", status: "pass", message: ".env.example documents the Refino variables." });
+    else
+        add({ id: "env-example", status: "warn", message: ".env.example does not document EDITOR_*/COPY_* variables.", fix: "Run `refino init --agent` or add the block by hand." });
+    // Scripts (plus a tsc fallback when a TypeScript project has no typecheck script).
+    const commands = [];
+    for (const command of verificationCommands(inspection)) {
+        if (!options.run) {
+            commands.push({ command, ran: false, ok: null });
+            continue;
+        }
+        const [bin, ...args] = command.split(" ");
+        const result = spawnSync(bin, args, { cwd: appDir, encoding: "utf8", env: { ...process.env, CI: "1" } });
+        const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim().split("\n").slice(-30).join("\n");
+        commands.push({ command, ran: true, ok: result.status === 0, output });
+    }
+    const ok = checks.every((check) => check.status !== "fail") && commands.every((command) => command.ok !== false);
+    return { ok, checks, commands };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@getrefino/onboarding",
+  "version": "0.1.0-rc.1",
+  "description": "The engine behind `npx @getrefino/cli init`: deterministic repository inspection, copy discovery, migration planning, agent instructions and verification for adding Refino to an existing React site. Development tooling only; never part of a site's runtime.",
+  "keywords": [
+    "refino",
+    "onboarding",
+    "codemod",
+    "migration",
+    "agent",
+    "copy"
+  ],
+  "license": "MIT",
+  "homepage": "https://refino.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forant/inline-copy.git",
+    "directory": "packages/onboarding"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "typescript": ">=5.5 <7",
+    "@getrefino/core": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.2",
+    "vitest": "5.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}