@getrefino/onboarding 0.1.0-rc.1

package/dist/inspect.js

@@ -0,0 +1,471 @@
+/**
+ * Deterministic repository inspection. Reads files only; never runs the
+ * project, never calls a model. Everything reported here can be checked by
+ * opening the files it names.
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { exists, findUp, isDirectory, isFile, readJson, readText, rel, toPosix, walkFiles } from "./fs.js";
+import { discoverRoutes } from "./graph.js";
+function dep(pkg, name) {
+    if (pkg.dependencies?.[name])
+        return { name, version: pkg.dependencies[name], kind: "dependencies" };
+    if (pkg.devDependencies?.[name])
+        return { name, version: pkg.devDependencies[name], kind: "devDependencies" };
+    return null;
+}
+function hasDep(pkg, name) {
+    return dep(pkg, name) !== null;
+}
+function detectPackageManager(root, pkg) {
+    const declared = pkg?.packageManager?.split("@")[0];
+    if (declared === "pnpm" || declared === "npm" || declared === "yarn" || declared === "bun")
+        return declared;
+    // Lockfiles live at the workspace root, which may be above the app being inspected.
+    const lock = findUp(root, ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb", "package-lock.json"]);
+    if (!lock)
+        return "unknown";
+    if (lock.endsWith("pnpm-lock.yaml"))
+        return "pnpm";
+    if (lock.endsWith("yarn.lock"))
+        return "yarn";
+    if (lock.endsWith("bun.lock") || lock.endsWith("bun.lockb"))
+        return "bun";
+    return "npm";
+}
+function detectMonorepo(root, pkg) {
+    const patterns = [];
+    let tool = null;
+    const workspaceYaml = readText(join(root, "pnpm-workspace.yaml"));
+    if (workspaceYaml) {
+        // pnpm-workspace.yaml also carries settings such as onlyBuiltDependencies; only a
+        // `packages:` list makes it a workspace.
+        const workspacePatterns = pnpmWorkspacePackages(workspaceYaml);
+        if (workspacePatterns.length > 0) {
+            tool = "pnpm";
+            patterns.push(...workspacePatterns);
+        }
+    }
+    const workspaces = pkg?.workspaces;
+    if (workspaces) {
+        tool ??= exists(join(root, "yarn.lock")) ? "yarn" : "npm";
+        patterns.push(...(Array.isArray(workspaces) ? workspaces : (workspaces.packages ?? [])));
+    }
+    if (exists(join(root, "turbo.json")))
+        tool ??= "turbo";
+    if (exists(join(root, "lerna.json")))
+        tool ??= "lerna";
+    if (exists(join(root, "nx.json")))
+        tool ??= "nx";
+    if (!tool && patterns.length === 0)
+        return { detected: false, tool: null, apps: [] };
+    const apps = [];
+    for (const pattern of patterns) {
+        const base = pattern.replace(/\/?\*+$/, "");
+        const baseDir = join(root, base);
+        if (!isDirectory(baseDir))
+            continue;
+        if (pattern.endsWith("*")) {
+            for (const name of walkDirs(baseDir)) {
+                if (exists(join(baseDir, name, "package.json")))
+                    apps.push(toPosix(join(base, name)));
+            }
+        }
+        else if (exists(join(baseDir, "package.json"))) {
+            apps.push(toPosix(base));
+        }
+    }
+    return { detected: true, tool, apps: apps.sort() };
+}
+/** The `packages:` entries of a pnpm-workspace.yaml (block list or inline array). */
+export function pnpmWorkspacePackages(yaml) {
+    const inline = yaml.match(/^packages\s*:\s*\[([^\]]*)\]/m);
+    if (inline) {
+        return inline[1]
+            .split(",")
+            .map((item) => item.trim().replace(/^["']|["']$/g, ""))
+            .filter((item) => item.length > 0);
+    }
+    const lines = yaml.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^packages\s*:\s*$/.test(line));
+    if (start === -1)
+        return [];
+    const patterns = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\s*(#|$)/.test(line))
+            continue;
+        const item = line.match(/^\s+-\s*["']?([^"'#]+?)["']?\s*$/);
+        if (!item)
+            break;
+        patterns.push(item[1].trim());
+    }
+    return patterns;
+}
+function walkDirs(dir) {
+    try {
+        return readdirSync(dir).filter((name) => !name.startsWith(".") && isDirectory(join(dir, name)));
+    }
+    catch {
+        return [];
+    }
+}
+/** Pick the app to onboard: the workspace package that looks most like a React site. */
+function chooseAppRoot(root, monorepo, rootPkg) {
+    if (!monorepo.detected)
+        return ".";
+    if (rootPkg && (hasDep(rootPkg, "next") || hasDep(rootPkg, "react")))
+        return ".";
+    let best = null;
+    for (const app of monorepo.apps) {
+        const pkg = readJson(join(root, app, "package.json"));
+        if (!pkg)
+            continue;
+        let score = 0;
+        if (hasDep(pkg, "next"))
+            score += 3;
+        if (hasDep(pkg, "vite"))
+            score += 2;
+        if (hasDep(pkg, "react"))
+            score += 1;
+        if (app.startsWith("apps/"))
+            score += 1;
+        if (score > 0 && (!best || score > best.score))
+            best = { path: app, score };
+    }
+    return best?.path ?? ".";
+}
+function detectScripts(pkg) {
+    const scripts = pkg?.scripts ?? {};
+    const pick = (names) => names.find((name) => scripts[name] !== undefined);
+    const result = {};
+    const build = pick(["build"]);
+    const test = pick(["test", "test:unit", "vitest", "jest"]);
+    const typecheck = pick(["typecheck", "type-check", "types", "check-types", "tsc", "check"]);
+    const lint = pick(["lint", "eslint"]);
+    const dev = pick(["dev", "start"]);
+    if (build)
+        result.build = build;
+    if (test)
+        result.test = test;
+    if (typecheck)
+        result.typecheck = typecheck;
+    if (lint)
+        result.lint = lint;
+    if (dev)
+        result.dev = dev;
+    return result;
+}
+const AUTH_LIBRARIES = [
+    "next-auth",
+    "@auth/core",
+    "@auth/nextjs",
+    "@clerk/nextjs",
+    "@clerk/clerk-react",
+    "@supabase/ssr",
+    "@supabase/supabase-js",
+    "@supabase/auth-helpers-nextjs",
+    "lucia",
+    "iron-session",
+    "jose",
+    "jsonwebtoken",
+    "passport",
+    "express-session",
+    "firebase",
+    "firebase-admin",
+    "@kinde-oss/kinde-auth-nextjs",
+    "@auth0/nextjs-auth0",
+    "@workos-inc/authkit-nextjs",
+    "better-auth",
+];
+function detectAuth(appDir, pkg, sourceDir) {
+    const libraries = pkg ? AUTH_LIBRARIES.filter((name) => hasDep(pkg, name)) : [];
+    const middlewareCandidates = ["proxy.ts", "proxy.js", "middleware.ts", "middleware.js"].flatMap((name) => [
+        join(appDir, name),
+        join(appDir, sourceDir, name),
+    ]);
+    const middlewareFile = middlewareCandidates.find((path) => isFile(path)) ?? null;
+    const notes = [];
+    if (libraries.length === 0) {
+        notes.push("No authentication library detected. The generated password login (refino/editor-auth) is the default.");
+    }
+    else {
+        notes.push(`Existing authentication: ${libraries.join(", ")}. Prefer gating edit mode with it (an "is this the owner?" check) instead of adding a second login.`);
+    }
+    if (middlewareFile)
+        notes.push(`Request middleware exists at ${rel(appDir, middlewareFile)}; do not put edit-mode authorization there alone, every privileged route must re-check.`);
+    return { libraries, middlewareFile: middlewareFile ? rel(appDir, middlewareFile) : null, notes };
+}
+const NEXT_CONFIG_FILES = ["next.config.js", "next.config.mjs", "next.config.cjs", "next.config.ts", "next.config.mts"];
+/** Read the facts we need from next.config.* without executing it. */
+function detectNextConfig(appDir) {
+    const file = NEXT_CONFIG_FILES.find((name) => isFile(join(appDir, name)));
+    if (!file)
+        return { file: null, output: null };
+    const text = readText(join(appDir, file)) ?? "";
+    const output = text.match(/\boutput\s*:\s*["'`](export|standalone)["'`]/)?.[1] ?? null;
+    return { file, output: output === "export" || output === "standalone" ? output : null };
+}
+/** Directories where the host's serverless functions live, when present. */
+function detectServerlessDir(appDir) {
+    return ["functions", "netlify/functions"].find((dir) => isDirectory(join(appDir, dir))) ?? null;
+}
+function detectServer(appDir, framework, router, sourceDir, pkg, nextConfig) {
+    if (framework === "next") {
+        if (nextConfig.output === "export") {
+            const serverlessDir = detectServerlessDir(appDir);
+            return {
+                capable: false,
+                kind: "static",
+                apiDir: serverlessDir,
+                notes: [`${nextConfig.file} sets output: "export": the site is exported as static HTML. Route handlers, cookies() and dynamic rendering are not available.`],
+                selfHosted: [
+                    "The copy endpoint must be a serverless function of the host, and edit mode must be detected in the browser via GET /api/edit-session.",
+                    serverlessDir ? `A ${serverlessDir}/ directory exists; the serverless endpoint belongs there.` : "No serverless functions directory exists yet.",
+                ],
+            };
+        }
+        const appApi = [join(appDir, "app/api"), join(appDir, "src/app/api")].find((p) => isDirectory(p));
+        const pagesApi = [join(appDir, "pages/api"), join(appDir, "src/pages/api")].find((p) => isDirectory(p));
+        if (router === "next-app") {
+            return { capable: true, kind: "next-route-handlers", apiDir: appApi ? rel(appDir, appApi) : null, notes: ["The app router supports route handlers (app/api), cookies() and per-request rendering."], selfHosted: ["Route handlers under app/api can host the copy endpoint."] };
+        }
+        return { capable: true, kind: "next-api-routes", apiDir: pagesApi ? rel(appDir, pagesApi) : null, notes: ["The pages router supports API routes (pages/api) and per-request rendering."], selfHosted: ["API routes under pages/api can host the copy endpoint."] };
+    }
+    const serverLibs = ["express", "hono", "fastify", "koa", "@hono/node-server", "h3", "nitropack"].filter((name) => pkg && hasDep(pkg, name));
+    const serverDirs = ["server", "api", "functions", "netlify/functions", join(sourceDir, "server")].filter((dir) => isDirectory(join(appDir, dir)));
+    if (serverLibs.length > 0 || serverDirs.length > 0) {
+        return {
+            capable: true,
+            kind: "custom-server",
+            apiDir: serverDirs[0] ?? null,
+            notes: [`Server code detected (${[...serverLibs, ...serverDirs].join(", ")}).`],
+            selfHosted: ["The copy endpoint must live there."],
+        };
+    }
+    return {
+        capable: false,
+        kind: "static",
+        apiDir: null,
+        notes: ["No server code detected."],
+        selfHosted: ["Saving copy needs one authenticated endpoint; add a serverless function (Vercel/Netlify/Cloudflare) or a small Node server."],
+    };
+}
+function detectHosting(root, appDir, pkg) {
+    const evidence = [];
+    let provider = null;
+    const check = (file, name) => {
+        for (const base of [appDir, root]) {
+            if (exists(join(base, file))) {
+                evidence.push(rel(root, join(base, file)));
+                provider ??= name;
+                return;
+            }
+        }
+    };
+    check("vercel.json", "vercel");
+    check("netlify.toml", "netlify");
+    check("wrangler.toml", "cloudflare");
+    check("wrangler.jsonc", "cloudflare");
+    check("wrangler.json", "cloudflare");
+    check("fly.toml", "fly");
+    check("render.yaml", "render");
+    check("amplify.yml", "aws-amplify");
+    check("firebase.json", "firebase");
+    check("Dockerfile", "docker");
+    // Project links written by the hosts' CLIs (git-ignored in most repositories, present on a linked checkout).
+    check(".vercel/project.json", "vercel");
+    check(".netlify/state.json", "netlify");
+    // Cloudflare Pages needs no config file: a functions/ directory is its Functions convention.
+    if (isDirectory(join(appDir, "functions")) && !isDirectory(join(appDir, "netlify"))) {
+        evidence.push("functions/ (Cloudflare Pages Functions directory)");
+        provider ??= "cloudflare";
+    }
+    for (const name of ["_headers", "_redirects"]) {
+        const publicDir = isDirectory(join(appDir, "public")) ? "public" : "static";
+        if (isFile(join(appDir, publicDir, name)))
+            evidence.push(`${publicDir}/${name} (Cloudflare Pages or Netlify static hosting)`);
+    }
+    if (pkg) {
+        for (const [name, host] of [["@opennextjs/cloudflare", "cloudflare"], ["@cloudflare/next-on-pages", "cloudflare"], ["@netlify/plugin-nextjs", "netlify"], ["@vercel/analytics", "vercel"]]) {
+            if (hasDep(pkg, name)) {
+                evidence.push(`dependency ${name}`);
+                provider ??= host;
+            }
+        }
+    }
+    return { provider, evidence };
+}
+function detectGit(root) {
+    const gitDir = join(root, ".git");
+    if (!exists(gitDir))
+        return { isRepository: false, branch: null, clean: null, remote: null, github: null };
+    const run = (args) => {
+        const result = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+        return result.status === 0 ? result.stdout.trim() : null;
+    };
+    const branch = run(["rev-parse", "--abbrev-ref", "HEAD"]);
+    const status = run(["status", "--porcelain"]);
+    const remote = run(["remote", "get-url", "origin"]);
+    const match = remote?.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+    return {
+        isRepository: true,
+        branch,
+        clean: status === null ? null : status.length === 0,
+        remote,
+        github: match ? { owner: match[1], repo: match[2] } : null,
+    };
+}
+/** The runtime packages a migrated site depends on, and the names they had before the Refino rename. */
+export const REFINO_PACKAGES = ["@getrefino/core", "@getrefino/react", "@getrefino/github"];
+export const LEGACY_PACKAGES = ["@inline-copy/core", "@inline-copy/react", "@inline-copy/github"];
+export const CONFIG_FILE_NAME = "refino.config.json";
+export const LEGACY_CONFIG_FILE_NAME = "inline-copy.config.json";
+function detectContentDirs(appDir) {
+    return ["content", "src/content", "data", "src/data", "copy", "src/copy", "locales", "src/locales"].filter((dir) => isDirectory(join(appDir, dir)));
+}
+function detectExistingIntegration(appDir, pkg) {
+    // Legacy names are still recognised so a site onboarded before the Refino
+    // rename is inspected correctly and can be told what to upgrade.
+    const packages = pkg
+        ? [...REFINO_PACKAGES, ...LEGACY_PACKAGES].map((name) => dep(pkg, name)).filter((d) => d !== null)
+        : [];
+    const configFile = [CONFIG_FILE_NAME, LEGACY_CONFIG_FILE_NAME].map((name) => join(appDir, name)).find((path) => isFile(path)) ?? null;
+    const config = configFile ? readJson(configFile) : null;
+    const contentCandidates = [config?.contentFile, "content/copy.json", "src/content/copy.json", "copy.json", "src/copy.json"].filter((p) => typeof p === "string");
+    const contentFile = contentCandidates.map((p) => join(appDir, p)).find((path) => isFile(path)) ?? null;
+    const providerFiles = [];
+    const endpointFiles = [];
+    const editableTextFiles = [];
+    for (const file of walkFiles(appDir)) {
+        const text = readText(file);
+        if (!text || !(text.includes("refino") || text.includes("inline-copy")))
+            continue;
+        const relative = rel(appDir, file);
+        if (text.includes("RefinoProvider") || text.includes("InlineCopyProvider"))
+            providerFiles.push(relative);
+        if (text.includes("createContentApi"))
+            endpointFiles.push(relative);
+        if (text.includes("EditableText"))
+            editableTextFiles.push(relative);
+    }
+    return {
+        packages,
+        contentFile: contentFile ? rel(appDir, contentFile) : null,
+        configFile: configFile ? rel(appDir, configFile) : null,
+        providerFiles,
+        endpointFiles,
+        editableTextFiles,
+    };
+}
+export function inspectRepository(rootPath, options = {}) {
+    const root = resolve(rootPath);
+    const rootPkg = readJson(join(root, "package.json"));
+    const monorepo = detectMonorepo(root, rootPkg);
+    const appRoot = options.app ? toPosix(options.app).replace(/\/+$/, "") || "." : chooseAppRoot(root, monorepo, rootPkg);
+    const appDir = resolve(root, appRoot);
+    const packageJsonPath = join(appDir, "package.json");
+    const pkg = readJson(packageJsonPath);
+    const effectivePkg = pkg ?? rootPkg;
+    const react = effectivePkg ? dep(effectivePkg, "react") : null;
+    const next = effectivePkg ? dep(effectivePkg, "next") : null;
+    const vite = effectivePkg ? dep(effectivePkg, "vite") : null;
+    const typescriptDep = effectivePkg ? dep(effectivePkg, "typescript") : null;
+    const hasTsconfig = exists(join(appDir, "tsconfig.json"));
+    const language = typescriptDep || hasTsconfig ? "typescript" : "javascript";
+    const sourceDir = isDirectory(join(appDir, "src")) && !isDirectory(join(appDir, "app")) && !isDirectory(join(appDir, "pages")) ? "src" : ".";
+    let framework = "unsupported";
+    const unsupportedReasons = [];
+    if (!effectivePkg)
+        unsupportedReasons.push(`No package.json found at ${rel(root, packageJsonPath)}.`);
+    if (next && react)
+        framework = "next";
+    else if (vite && react && (effectivePkg && hasDep(effectivePkg, "@vitejs/plugin-react")) !== false)
+        framework = "vite-react";
+    else if (react)
+        framework = "react";
+    else if (effectivePkg)
+        unsupportedReasons.push("React is not a dependency; Refino v1 supports React-based sites only.");
+    const routing = discoverRoutes(appDir, framework, sourceDir);
+    const router = routing.router;
+    if (framework === "next" && router === "unknown")
+        unsupportedReasons.push("Next.js detected but neither an app/ nor a pages/ directory was found.");
+    if ((framework === "react" || framework === "vite-react") && !routing.entry)
+        unsupportedReasons.push("Could not find the React entry file (expected src/main.tsx, src/index.tsx or similar).");
+    const scripts = detectScripts(effectivePkg);
+    const auth = detectAuth(appDir, effectivePkg, sourceDir);
+    const nextConfig = framework === "next" ? detectNextConfig(appDir) : { file: null, output: null };
+    const server = detectServer(appDir, framework, router, sourceDir, effectivePkg, nextConfig);
+    const supported = framework !== "unsupported" && unsupportedReasons.length === 0;
+    return {
+        root: toPosix(root),
+        appRoot,
+        monorepo,
+        packageManager: detectPackageManager(root, rootPkg ?? pkg),
+        packageJson: pkg ? rel(root, packageJsonPath) : rootPkg ? "package.json" : null,
+        packageName: effectivePkg?.name ?? null,
+        framework,
+        router,
+        language,
+        react,
+        next,
+        nextConfig,
+        vite,
+        typescript: typescriptDep,
+        sourceDir,
+        routesDir: routing.routesDir,
+        routes: routing.routes,
+        layouts: routing.layouts,
+        entry: routing.entry,
+        scripts,
+        contentDirs: detectContentDirs(appDir),
+        refino: detectExistingIntegration(appDir, effectivePkg),
+        auth,
+        server,
+        hosting: detectHosting(root, appDir, effectivePkg),
+        git: detectGit(root),
+        supported,
+        unsupportedReasons,
+    };
+}
+/** Absolute path of the app directory for an inspection. */
+export function appDirectory(inspection) {
+    return resolve(inspection.root, inspection.appRoot);
+}
+export function packageManagerRun(pm, script) {
+    switch (pm) {
+        case "pnpm":
+            return `pnpm ${script}`;
+        case "yarn":
+            return `yarn ${script}`;
+        case "bun":
+            return `bun run ${script}`;
+        default:
+            return `npm run ${script}`;
+    }
+}
+/** Run a binary from node_modules through the package manager. */
+export function packageManagerExec(pm, command) {
+    switch (pm) {
+        case "pnpm":
+            return `pnpm exec ${command}`;
+        case "yarn":
+            return `yarn ${command}`;
+        case "bun":
+            return `bunx ${command}`;
+        default:
+            return `npx ${command}`;
+    }
+}
+export function packageManagerInstall(pm) {
+    switch (pm) {
+        case "pnpm":
+            return "pnpm install";
+        case "yarn":
+            return "yarn install";
+        case "bun":
+            return "bun install";
+        default:
+            return "npm install";
+    }
+}

package/dist/plan.d.ts

@@ -0,0 +1,43 @@
+import type { HostIntegration, HostKind, MigrationPlan, PlanOptions, RefinoSite, RepositoryInspection, ScanResult } from "./types.js";
+export declare 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 declare const TOOL_VERSION: string;
+/**
+ * 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 declare function dependencyRange(version?: string): string;
+export declare const PLAN_DIR = ".refino";
+export declare const PLAN_FILE = ".refino/plan.json";
+export declare const INSTRUCTIONS_FILE = ".refino/AGENT_INSTRUCTIONS.md";
+export declare const CONFIG_FILE = "refino.config.json";
+export declare const BOILERPLATE_DIR = "refino";
+export declare function defaultContentFile(inspection: RepositoryInspection): string;
+/** Validate and normalize the Refino connection given on the command line. */
+export declare function resolveRefinoSite(option: PlanOptions["refino"]): RefinoSite | null;
+export declare function hostLabel(kind: HostKind): string;
+/**
+ * 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 declare function hostIntegration(inspection: RepositoryInspection, refino?: RefinoSite | null): HostIntegration;
+/** Where a serverless copy endpoint lives for the detected host. */
+export declare function serverlessEndpointPath(inspection: RepositoryInspection, _ext: string): {
+    path: string;
+    note: string;
+};
+export declare function integrationPoints(inspection: RepositoryInspection, refino?: RefinoSite | null): MigrationPlan["integration"];
+export declare function verificationCommands(inspection: RepositoryInspection): string[];
+export declare function buildPlan(inspection: RepositoryInspection, scan: ScanResult, options?: PlanOptions): MigrationPlan;
+/** Convenience: inspect + scan + plan in one call. */
+export declare function planMigration(inspection: RepositoryInspection, options?: PlanOptions): MigrationPlan;
+/** The copy-file content a plan would create: selected candidates only, in scan order. */
+export declare function planContent(plan: MigrationPlan): Record<string, string>;