@fluixi/cli 0.1.0-alpha.82 → 0.1.0-alpha.84

package/dist/index.cjs

@@ -1,4 +1,4 @@
-/*! @fluixi/cli v0.1.0-alpha.82 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/cli v0.1.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-/*! @fluixi/cli v0.1.0-alpha.82 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/cli v0.1.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 
 // src/index.ts
 import { defineConfig } from "@fluixi/start";

package/dist/report.cjs

@@ -0,0 +1,54 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/report.ts
+var report_exports = {};
+__export(report_exports, {
+  report: () => report,
+  reportAuth: () => reportAuth
+});
+module.exports = __toCommonJS(report_exports);
+var import_node_path = require("node:path");
+var import_ui = require("@fluixi/start/ui");
+var rel = (file) => (0, import_node_path.relative)(process.cwd(), file) || ".";
+function report(steps) {
+  for (const s of steps) {
+    if (s.kind === "hint") {
+      console.log(`  ${import_ui.c.yellow("!")} ${import_ui.c.gray("add to")} ${import_ui.c.cyan(rel(s.file))}${import_ui.c.gray(":")}`);
+      for (const l of s.lines) console.log(`    ${l}`);
+    } else if (s.kind === "kept") {
+      console.log(`  ${import_ui.c.gray("-")} ${import_ui.c.cyan(rel(s.file))} ${import_ui.c.gray("exists, kept")}`);
+    } else if (s.kind === "listed") {
+      console.log(`  ${import_ui.c.gray("-")} ${import_ui.c.cyan(rel(s.file))} ${import_ui.c.gray("already lists it")}`);
+    } else {
+      console.log(`  ${import_ui.c.green("✓")} ${import_ui.c.gray(s.kind)} ${import_ui.c.cyan(rel(s.file))}${s.detail ? import_ui.c.gray(`: ${s.detail}`) : ""}`);
+    }
+  }
+}
+function reportAuth(result, installHint) {
+  for (const n of result.notes) console.log(`  ${import_ui.c.gray(n)}`);
+  report(result.steps);
+  const next = [...installHint ? [installHint] : [], ...result.next];
+  if (next.length) console.log(`  ${import_ui.c.gray("next:")} ${next.map((n) => import_ui.c.gray(n)).join(import_ui.c.gray("; "))}`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  report,
+  reportAuth
+});

package/dist/report.d.ts

@@ -0,0 +1,5 @@
+import type { AuthResult, Step } from './scaffold/index.js';
+export declare function report(steps: Step[]): void;
+/** Steps, then notes and what is left, for an auth setup. */
+export declare function reportAuth(result: AuthResult, installHint?: string): void;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAI5D,wBAAgB,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAa1C;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAKzE"}

package/dist/report.js

@@ -0,0 +1,31 @@
+/** How the CLI shows what a scaffold step did. */
+import { relative } from 'node:path';
+import { c } from '@fluixi/start/ui';
+const rel = (file) => relative(process.cwd(), file) || '.';
+export function report(steps) {
+    for (const s of steps) {
+        if (s.kind === 'hint') {
+            console.log(`  ${c.yellow('!')} ${c.gray('add to')} ${c.cyan(rel(s.file))}${c.gray(':')}`);
+            for (const l of s.lines)
+                console.log(`    ${l}`);
+        }
+        else if (s.kind === 'kept') {
+            console.log(`  ${c.gray('-')} ${c.cyan(rel(s.file))} ${c.gray('exists, kept')}`);
+        }
+        else if (s.kind === 'listed') {
+            console.log(`  ${c.gray('-')} ${c.cyan(rel(s.file))} ${c.gray('already lists it')}`);
+        }
+        else {
+            console.log(`  ${c.green('✓')} ${c.gray(s.kind)} ${c.cyan(rel(s.file))}${s.detail ? c.gray(`: ${s.detail}`) : ''}`);
+        }
+    }
+}
+/** Steps, then notes and what is left, for an auth setup. */
+export function reportAuth(result, installHint) {
+    for (const n of result.notes)
+        console.log(`  ${c.gray(n)}`);
+    report(result.steps);
+    const next = [...(installHint ? [installHint] : []), ...result.next];
+    if (next.length)
+        console.log(`  ${c.gray('next:')} ${next.map((n) => c.gray(n)).join(c.gray('; '))}`);
+}

package/dist/report.mjs

@@ -0,0 +1,28 @@
+// src/report.ts
+import { relative } from "node:path";
+import { c } from "@fluixi/start/ui";
+var rel = (file) => relative(process.cwd(), file) || ".";
+function report(steps) {
+  for (const s of steps) {
+    if (s.kind === "hint") {
+      console.log(`  ${c.yellow("!")} ${c.gray("add to")} ${c.cyan(rel(s.file))}${c.gray(":")}`);
+      for (const l of s.lines) console.log(`    ${l}`);
+    } else if (s.kind === "kept") {
+      console.log(`  ${c.gray("-")} ${c.cyan(rel(s.file))} ${c.gray("exists, kept")}`);
+    } else if (s.kind === "listed") {
+      console.log(`  ${c.gray("-")} ${c.cyan(rel(s.file))} ${c.gray("already lists it")}`);
+    } else {
+      console.log(`  ${c.green("✓")} ${c.gray(s.kind)} ${c.cyan(rel(s.file))}${s.detail ? c.gray(`: ${s.detail}`) : ""}`);
+    }
+  }
+}
+function reportAuth(result, installHint) {
+  for (const n of result.notes) console.log(`  ${c.gray(n)}`);
+  report(result.steps);
+  const next = [...installHint ? [installHint] : [], ...result.next];
+  if (next.length) console.log(`  ${c.gray("next:")} ${next.map((n) => c.gray(n)).join(c.gray("; "))}`);
+}
+export {
+  report,
+  reportAuth
+};

package/dist/scaffold/auth.cjs

@@ -0,0 +1,422 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/scaffold/auth.ts
+var auth_exports = {};
+__export(auth_exports, {
+  ScaffoldError: () => ScaffoldError,
+  ensureAuthEnv: () => ensureAuthEnv,
+  importPath: () => importPath,
+  projectFormat: () => projectFormat,
+  registerModule: () => registerModule,
+  resolveTokens: () => resolveTokens,
+  setupBetterAuth: () => setupBetterAuth,
+  setupOAuth2: () => setupOAuth2,
+  writeOnce: () => writeOnce
+});
+module.exports = __toCommonJS(auth_exports);
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+
+// src/scaffold/edit.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function closing(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "/" && text[i + 1] === "/") i = text.indexOf("\n", i) === -1 ? text.length : text.indexOf("\n", i);
+    else if (ch === "/" && text[i + 1] === "*") i = text.indexOf("*/", i + 2) + 1;
+    else if (ch === "'" || ch === '"' || ch === "`") {
+      for (i++; i < text.length && text[i] !== ch; i++) if (text[i] === "\\") i++;
+    } else if ("([{".includes(ch)) depth++;
+    else if (")]}".includes(ch) && --depth === 0) return i;
+  }
+  return -1;
+}
+function appendToArray(text, open, items) {
+  const close = closing(text, open);
+  const inner = text.slice(open + 1, close);
+  if (!inner.trim()) return text.slice(0, open + 1) + items.join(", ") + text.slice(close);
+  if (inner.includes("\n")) {
+    const last = inner.trimEnd();
+    const indent = last.slice(last.lastIndexOf("\n") + 1).match(/^\s*/)[0];
+    const comma = last.endsWith(",") ? "" : ",";
+    const tail = inner.slice(last.length);
+    return text.slice(0, open + 1) + last + comma + items.map((i) => `
+${indent}${i},`).join("") + tail + text.slice(close);
+  }
+  const body = inner.replace(/,?\s*$/, "");
+  const trailing = inner.slice(body.length).replace(/^,/, "");
+  return text.slice(0, open + 1) + body + ", " + items.join(", ") + trailing + text.slice(close);
+}
+function addImport(text, line) {
+  if (text.includes(line)) return text;
+  const imports = [...text.matchAll(/^import[\s\S]*?from\s+['"][^'"]+['"];?[^\n]*\n/gm)];
+  const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
+  return text.slice(0, at) + line + "\n" + text.slice(at);
+}
+function register(log, file, header, r) {
+  const imports = [...r.extraImports ?? [], r.importLine];
+  if (!(0, import_node_fs.existsSync)(file)) {
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(file), { recursive: true });
+    (0, import_node_fs.writeFileSync)(
+      file,
+      `${header}import { defineApp } from '@fluixi/start/app';
+${imports.join("\n")}
+
+export default defineApp({ imports: [${r.entry}] });
+`
+    );
+    log.push({ kind: "created", file });
+    return true;
+  }
+  let text = (0, import_node_fs.readFileSync)(file, "utf8");
+  if (text.includes(r.importLine)) {
+    log.push({ kind: "listed", file, detail: r.entry });
+    return true;
+  }
+  const m = text.match(/\bimports\s*:\s*\[/);
+  if (!m) {
+    log.push({ kind: "hint", file, lines: [...imports, `imports: [${r.entry}]`] });
+    return false;
+  }
+  text = appendToArray(text, m.index + m[0].length - 1, [r.entry]);
+  for (const line of imports) text = addImport(text, line);
+  (0, import_node_fs.writeFileSync)(file, text);
+  log.push({ kind: "updated", file, detail: `imports ${r.entry}` });
+  return true;
+}
+function envPublicNames(configFile) {
+  if (!(0, import_node_fs.existsSync)(configFile)) return null;
+  const text = (0, import_node_fs.readFileSync)(configFile, "utf8");
+  const m = text.match(/\bpublic\s*:\s*\[/);
+  if (!m) return null;
+  const open = m.index + m[0].length - 1;
+  const list = text.slice(open, closing(text, open) + 1);
+  return [...list.matchAll(/['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g)].map((x) => x[1]);
+}
+function addEnvPublic(log, configFile, names) {
+  const list = (indent) => `${indent}public: [
+${names.map((n) => `${indent}  '${n}',
+`).join("")}${indent}],
+`;
+  const have = envPublicNames(configFile);
+  if (have === null) {
+    const text2 = (0, import_node_fs.existsSync)(configFile) ? (0, import_node_fs.readFileSync)(configFile, "utf8") : "";
+    const call = text2.match(/defineConfig\(\{\n/);
+    if (call && !/\benv\s*:/.test(text2)) {
+      const at = call.index + call[0].length;
+      (0, import_node_fs.writeFileSync)(configFile, text2.slice(0, at) + `  env: {
+${list("    ")}  },
+` + text2.slice(at));
+      log.push({ kind: "updated", file: configFile, detail: `env.public ${names.join(", ")}` });
+      return;
+    }
+    log.push({ kind: "hint", file: configFile, lines: [`env: { public: [${names.map((n) => `'${n}'`).join(", ")}] },`] });
+    return;
+  }
+  const missing = names.filter((n) => !have.includes(n));
+  if (!missing.length) return;
+  const text = (0, import_node_fs.readFileSync)(configFile, "utf8");
+  const m = text.match(/\bpublic\s*:\s*\[/);
+  (0, import_node_fs.writeFileSync)(configFile, appendToArray(text, m.index + m[0].length - 1, missing.map((n) => `'${n}'`)));
+  log.push({ kind: "updated", file: configFile, detail: `env.public + ${missing.join(", ")}` });
+}
+function addEnvExample(log, file, comment, vars) {
+  const text = (0, import_node_fs.existsSync)(file) ? (0, import_node_fs.readFileSync)(file, "utf8") : "";
+  const have = new Set([...text.matchAll(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)].map((m) => m[1]));
+  const add = Object.entries(vars).filter(([k]) => !have.has(k) && !have.has(`VITE_${k}`));
+  if (!add.length) return;
+  const block = `${comment.split("\n").map((l) => `# ${l}`).join("\n")}
+${add.map(([k, v]) => `${k}=${v}`).join("\n")}
+`;
+  (0, import_node_fs.writeFileSync)(file, text ? `${text.replace(/\n*$/, "\n")}
+${block}` : block);
+  log.push({ kind: text ? "updated" : "created", file, detail: add.map(([k]) => k).join(", ") });
+}
+
+// src/scaffold/templates.ts
+var PROVIDERS = ["oidc", "keycloak", "auth0", "okta", "google", "dex", "oauth2"];
+var SERVER_ONLY = {
+  google: "Google answers a token request without a client secret with `client_secret is missing`",
+  dex: "Dex sends no CORS headers on discovery or the token endpoint"
+};
+var PROVIDER_VARS = {
+  oidc: { AUTH_ISSUER: "https://id.example.com" },
+  keycloak: { AUTH_BASE_URL: "http://localhost:8080", AUTH_REALM: "master" },
+  auth0: { AUTH_DOMAIN: "example.eu.auth0.com", AUTH_AUDIENCE: "https://api.example.com" },
+  okta: { AUTH_DOMAIN: "example.okta.com" },
+  google: {},
+  dex: { AUTH_BASE_URL: "http://localhost:5556/dex" },
+  oauth2: {
+    AUTH_ISSUER: "https://id.example.com",
+    AUTH_AUTHORIZATION_ENDPOINT: "https://id.example.com/authorize",
+    AUTH_TOKEN_ENDPOINT: "https://id.example.com/token"
+  }
+};
+var AUTH_READER = `// Provider, issuer, client and token mode from the AUTH_* variables in env.public. Moving to
+// another provider is a change to .env.
+export const auth = authFromEnv(publicEnv(), { clientPrefix: '' });
+`;
+var authEnvConfig = () => `import { publicEnv } from '@fluixi/start/env';
+import { authFromEnv } from '@fluixi/oauth2/env';
+
+${AUTH_READER}`;
+var authServiceFile = (tokens) => `import { createAuthService, authModule } from '@fluixi/oauth2';
+import { env } from '@fluixi/start/env';
+${tokens === "browser" ? `import { auth as authEnv } from '../config/env.js';
+` : ""}
+export interface User {
+  sub: string;
+  email?: string;
+  name?: string;
+}
+
+const appUrl = env('APP_URL') ?? 'http://localhost:3000';
+
+export const auth = createAuthService<User>({
+${tokens === "browser" ? `  config: {
+    ...authEnv.client,
+    tokens: 'browser',
+    redirectUri: \`\${appUrl}/callback\`,
+    postLogoutRedirectUri: \`\${appUrl}/login\`,
+  },` : `  // The tokens stay on the server behind an httpOnly cookie. The browser calls the routes
+  // auth.server.ts mounts under basePath and never sees a token.
+  config: {
+    tokens: 'server',
+    redirectUri: \`\${appUrl}/auth/callback\`,
+    postLogoutRedirectUri: \`\${appUrl}/login\`,
+    basePath: '/auth',
+  },`}
+});
+
+export const AuthModule = authModule(auth);
+export const { protectedRoute, Protect, Can, useUser } = auth;
+`;
+var authServerFile = () => `import { authServerModule } from '@fluixi/oauth2/server';
+import { publicEnv, serverEnv } from '@fluixi/start/env';
+import { auth } from '../config/env.js';
+
+// A function: serverEnv with required throws when a secret is unset, and it is only read
+// when app.config.server.ts registers this.
+export function authServer() {
+  const appUrl = publicEnv().APP_URL ?? 'http://localhost:3000';
+  return authServerModule({
+    ...auth.client,
+    clientSecret: serverEnv('OIDC_CLIENT_SECRET', { required: true }),
+    cookieSecret: serverEnv('SESSION_SECRET', { required: true }),
+    redirectUri: \`\${appUrl}/auth/callback\`,
+    defaultReturnTo: '/',
+    secureCookie: appUrl.startsWith('https://'),
+  });
+}
+`;
+var callbackRoute = (html) => html ? `import { html } from '@fluixi/core';
+import { OAuthCallback } from '@fluixi/oauth2/callback';
+
+export default OAuthCallback({
+  pending: () => html\`<p>Signing you in</p>\`,
+  failed: (reason) => html\`<p>\${reason}</p><a href="/login">Try again</a>\`,
+});
+` : `import { OAuthCallback } from '@fluixi/oauth2/callback';
+
+export default OAuthCallback({
+  pending: () => <p>Signing you in</p>,
+  failed: (reason) => (
+    <>
+      <p>{reason}</p>
+      <a href="/login">Try again</a>
+    </>
+  ),
+});
+`;
+var loginRoute = (html) => html ? `import { html } from '@fluixi/core';
+import { auth } from '../services/auth.js';
+
+export default function Login() {
+  return html\`<button @click=\${() => auth.signIn({ returnTo: '/' })}>Sign in</button>\`;
+}
+` : `import { auth } from '../services/auth.js';
+
+export default function Login() {
+  return <button onClick={() => auth.signIn({ returnTo: '/' })}>Sign in</button>;
+}
+`;
+var betterAuthConfig = () => `import { betterAuth } from 'better-auth';
+import { defineAuth } from '@fluixi/auth/server';
+
+export type AppUser = { id: string; email: string; name?: string; role?: string };
+
+// Better Auth owns the audited primitives; defineAuth registers it with @fluixi/auth.
+export const auth = defineAuth<AppUser>(
+  betterAuth({
+    // database: <your adapter>,
+    emailAndPassword: { enabled: true },
+    // socialProviders: { google: { … }, github: { … } },
+  } as Parameters<typeof betterAuth>[0]),
+);
+`;
+var betterAuthClient = () => `import { createAuthClient } from 'better-auth/client';
+import { createAuthHooks } from '@fluixi/auth/client';
+import type { AppUser } from './auth.config.js';
+
+const client = createAuthClient({ baseURL: '/api/auth' });
+
+// Or, to reuse an existing reactive session: createAuthHooks({ session: yourSessionStore }).
+export const { useUser, useSession, useAuth, useSignIn, useSignOut, protectedRoute } =
+  createAuthHooks<AppUser>({ client, loginPath: '/login' });
+`;
+var betterAuthMiddleware = () => `import { defineMiddleware } from '@fluixi/start';
+import { authMiddleware } from '@fluixi/auth/server';
+import './auth.config.js';
+
+export default defineMiddleware([authMiddleware()]);
+`;
+var betterAuthRoute = () => `import { mountAuthRoutes } from '@fluixi/auth/server';
+import '../../auth.config.js';
+
+const handler = mountAuthRoutes();
+export const GET = handler;
+export const POST = handler;
+export default handler;
+`;
+
+// src/scaffold/auth.ts
+var ScaffoldError = class extends Error {
+};
+function projectFormat(root) {
+  try {
+    const ts = JSON.parse((0, import_node_fs2.readFileSync)((0, import_node_path2.join)(root, "tsconfig.json"), "utf8"));
+    if (ts?.compilerOptions && !ts.compilerOptions.jsx) return "html";
+  } catch {
+  }
+  return "jsx";
+}
+function importPath(from, to) {
+  const p = (0, import_node_path2.relative)((0, import_node_path2.dirname)(from), to).replace(/\\/g, "/").replace(/\.tsx?$/, ".js");
+  return p.startsWith(".") ? p : `./${p}`;
+}
+function writeOnce(log, file, content) {
+  if ((0, import_node_fs2.existsSync)(file)) {
+    log.push({ kind: "kept", file });
+    return false;
+  }
+  (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(file), { recursive: true });
+  (0, import_node_fs2.writeFileSync)(file, content);
+  log.push({ kind: "created", file });
+  return true;
+}
+var APP_HEADER = "// Registered by @fluixi/start ahead of both entries.\n";
+var APP_SERVER_HEADER = "// Only the server build imports this file, so what it lists never reaches the browser.\n";
+function registerModule(log, root, server, file, name, entry = name) {
+  const config = (0, import_node_path2.join)(root, server ? "src/app.config.server.ts" : "src/app.config.ts");
+  register(log, config, server ? APP_SERVER_HEADER : APP_HEADER, {
+    importLine: `import { ${name} } from '${importPath(config, file)}';`,
+    entry
+  });
+}
+function ensureAuthEnv(log, root) {
+  const file = (0, import_node_path2.join)(root, "src/config/env.ts");
+  if (writeOnce(log, file, authEnvConfig())) return;
+  let text = (0, import_node_fs2.readFileSync)(file, "utf8");
+  if (/export\s+const\s+auth\b/.test(text)) return;
+  if (!/\bpublicEnv\b/.test(text)) text = addImport(text, `import { publicEnv } from '@fluixi/start/env';`);
+  text = addImport(text, `import { authFromEnv } from '@fluixi/oauth2/env';`);
+  (0, import_node_fs2.writeFileSync)(file, `${text.replace(/\n*$/, "\n")}
+${AUTH_READER}`);
+  log.push({ kind: "updated", file, detail: "auth" });
+}
+function resolveTokens(provider, tokens) {
+  const refusal = SERVER_ONLY[provider];
+  if (refusal && tokens === "browser") throw new ScaffoldError(`${provider} needs server tokens: ${refusal}`);
+  return { tokens: tokens ?? (refusal ? "server" : "browser"), forced: !!refusal && !tokens };
+}
+function setupOAuth2(root, options, dependencySpec = "alpha") {
+  const provider = options.provider ?? "oidc";
+  if (!PROVIDERS.includes(provider)) throw new ScaffoldError(`unknown provider ${provider}: ${PROVIDERS.join(", ")}`);
+  const { tokens, forced } = resolveTokens(provider, options.tokens);
+  const html = options.format === "html";
+  const ext = html ? "ts" : "tsx";
+  const steps = [];
+  const at = (rel) => (0, import_node_path2.join)(root, rel);
+  ensureAuthEnv(steps, root);
+  const service = at("src/services/auth.ts");
+  if (writeOnce(steps, service, authServiceFile(tokens))) registerModule(steps, root, false, service, "AuthModule");
+  if (tokens === "browser") writeOnce(steps, at(`src/routes/callback.${ext}`), callbackRoute(html));
+  writeOnce(steps, at(`src/routes/login.${ext}`), loginRoute(html));
+  if (tokens === "server") {
+    const server = at("src/services/auth.server.ts");
+    if (writeOnce(steps, server, authServerFile())) registerModule(steps, root, true, server, "authServer", "authServer()");
+  }
+  const vars = {
+    AUTH_PROVIDER: provider,
+    AUTH_CLIENT_ID: "my-app",
+    AUTH_TOKENS: tokens,
+    ...PROVIDER_VARS[provider],
+    APP_URL: "http://localhost:3000"
+  };
+  addEnvPublic(steps, at("fluixi.config.ts"), Object.keys(vars));
+  addEnvExample(steps, at(".env.example"), `@fluixi/oauth2 (${provider}). Listed in env.public: the browser sees them.`, vars);
+  if (tokens === "server") {
+    addEnvExample(steps, at(".env.example"), "Server only, never in env.public. SESSION_SECRET: 32 bytes or more.", {
+      OIDC_CLIENT_SECRET: "",
+      SESSION_SECRET: ""
+    });
+  }
+  const redirect = tokens === "browser" ? "/callback" : "/auth/callback";
+  return {
+    steps,
+    dependencies: { "@fluixi/oauth2": dependencySpec },
+    next: ["copy .env.example to .env and fill it in", `register <APP_URL>${redirect} as the redirect URI at the provider`],
+    notes: forced ? [`${provider} refuses a public client, so the tokens stay on the server`] : []
+  };
+}
+function setupBetterAuth(root, dependencySpec = "alpha") {
+  const steps = [];
+  const at = (rel) => (0, import_node_path2.join)(root, rel);
+  writeOnce(steps, at("src/auth.config.ts"), betterAuthConfig());
+  writeOnce(steps, at("src/auth.client.ts"), betterAuthClient());
+  if (!writeOnce(steps, at("src/middleware.ts"), betterAuthMiddleware())) {
+    steps.push({
+      kind: "hint",
+      file: at("src/middleware.ts"),
+      lines: [`import { authMiddleware } from '@fluixi/auth/server';`, `import './auth.config.js';`, "authMiddleware() in the middleware list"]
+    });
+  }
+  writeOnce(steps, at("src/api/auth/[...all].ts"), betterAuthRoute());
+  return {
+    steps,
+    dependencies: { "@fluixi/auth": dependencySpec, "better-auth": "^1" },
+    next: ["set your database adapter in src/auth.config.ts"],
+    notes: []
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ScaffoldError,
+  ensureAuthEnv,
+  importPath,
+  projectFormat,
+  registerModule,
+  resolveTokens,
+  setupBetterAuth,
+  setupOAuth2,
+  writeOnce
+});

package/dist/scaffold/auth.d.ts

@@ -0,0 +1,39 @@
+import { type Step } from './edit.js';
+import * as t from './templates.js';
+export type Format = 'jsx' | 'html';
+export type Tokens = 'browser' | 'server';
+export interface OAuth2Options {
+    provider?: t.ProviderName;
+    tokens?: Tokens;
+    format: Format;
+}
+export interface AuthResult {
+    steps: Step[];
+    /** Packages the wiring imports, with the spec to install. */
+    dependencies: Record<string, string>;
+    /** What is left to the developer, one line each. */
+    next: string[];
+    /** Decided rather than asked, worth saying (a provider forcing server tokens). */
+    notes: string[];
+}
+/** A refusal the caller reports as it reports any bad input. */
+export declare class ScaffoldError extends Error {
+}
+/** `jsx` when the project's tsconfig configures it, `html` for an html``-authored one. */
+export declare function projectFormat(root: string): Format;
+/** A path for an import between two files, with the .js extension ESM needs. */
+export declare function importPath(from: string, to: string): string;
+/** Write a file the app may already have, keeping theirs. Returns whether it wrote. */
+export declare function writeOnce(log: Step[], file: string, content: string): boolean;
+/** List a module in `src/app.config.ts`, or `app.config.server.ts` for a server one. */
+export declare function registerModule(log: Step[], root: string, server: boolean, file: string, name: string, entry?: string): void;
+/** `src/config/env.ts` with the `auth` reader: created when missing, appended when not there. */
+export declare function ensureAuthEnv(log: Step[], root: string): void;
+/** The token mode for a provider: what was asked, checked, or the provider's only option. */
+export declare function resolveTokens(provider: t.ProviderName, tokens: Tokens | undefined): {
+    tokens: Tokens;
+    forced: boolean;
+};
+export declare function setupOAuth2(root: string, options: OAuth2Options, dependencySpec?: string): AuthResult;
+export declare function setupBetterAuth(root: string, dependencySpec?: string): AuthResult;
+//# sourceMappingURL=auth.d.ts.map

package/dist/scaffold/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/scaffold/auth.ts"],"names":[],"mappings":"AASA,OAAO,EAAoD,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AAEpC,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AACpC,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oDAAoD;IACpD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,gEAAgE;AAChE,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAS7E;AAKD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,SAAO,GAAG,IAAI,CAMzH;AAED,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS7D;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAIvH;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,cAAc,SAAU,GAAG,UAAU,CA0CtG;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,SAAU,GAAG,UAAU,CAmBlF"}