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

package/dist/cli.mjs

@@ -1,22 +1,595 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/cli.ts
 import { loadConfig } from "@fluixi/start/config";
-import { dev, build, start } from "@fluixi/start/commands";
-import { wordmark, c as c2 } from "@fluixi/start/ui";
+import { dev, build, start, env as env2, envReport, info } from "@fluixi/start/commands";
+import { wordmark, c as c6 } from "@fluixi/start/ui";
 
 // src/generate.ts
-import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { resolve, dirname, relative, basename } from "node:path";
-import { c } from "@fluixi/start/ui";
-var GEN_USAGE = `Usage: fluixi generate <kind> <name>
+import { writeFileSync as writeFileSync3, readFileSync as readFileSync3, existsSync as existsSync3, mkdirSync as mkdirSync3 } from "node:fs";
+import { resolve, dirname as dirname3, relative as relative3, basename } from "node:path";
+import { c as c3 } from "@fluixi/start/ui";
+
+// src/scaffold/auth.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, join, relative } from "node:path";
+
+// src/scaffold/edit.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "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 (!existsSync(file)) {
+    mkdirSync(dirname(file), { recursive: true });
+    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 = 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);
+  writeFileSync(file, text);
+  log.push({ kind: "updated", file, detail: `imports ${r.entry}` });
+  return true;
+}
+function envPublicNames(configFile) {
+  if (!existsSync(configFile)) return null;
+  const text = 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 = existsSync(configFile) ? readFileSync(configFile, "utf8") : "";
+    const call = text2.match(/defineConfig\(\{\n/);
+    if (call && !/\benv\s*:/.test(text2)) {
+      const at = call.index + call[0].length;
+      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 = readFileSync(configFile, "utf8");
+  const m = text.match(/\bpublic\s*:\s*\[/);
+  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 = existsSync(file) ? 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 add2 = Object.entries(vars).filter(([k]) => !have.has(k) && !have.has(`VITE_${k}`));
+  if (!add2.length) return;
+  const block = `${comment.split("\n").map((l) => `# ${l}`).join("\n")}
+${add2.map(([k, v]) => `${k}=${v}`).join("\n")}
+`;
+  writeFileSync(file, text ? `${text.replace(/\n*$/, "\n")}
+${block}` : block);
+  log.push({ kind: text ? "updated" : "created", file, detail: add2.map(([k]) => k).join(", ") });
+}
+
+// src/scaffold/templates.ts
+var templates_exports = {};
+__export(templates_exports, {
+  AUTH_READER: () => AUTH_READER,
+  PROVIDERS: () => PROVIDERS,
+  PROVIDER_VARS: () => PROVIDER_VARS,
+  SERVER_ONLY: () => SERVER_ONLY,
+  apiRoute: () => apiRoute,
+  authEnvConfig: () => authEnvConfig,
+  authServerFile: () => authServerFile,
+  authServiceFile: () => authServiceFile,
+  betterAuthClient: () => betterAuthClient,
+  betterAuthConfig: () => betterAuthConfig,
+  betterAuthMiddleware: () => betterAuthMiddleware,
+  betterAuthRoute: () => betterAuthRoute,
+  callbackRoute: () => callbackRoute,
+  camel: () => camel,
+  envConfig: () => envConfig,
+  guardedApiRoute: () => guardedApiRoute,
+  loginRoute: () => loginRoute,
+  moduleFile: () => moduleFile,
+  serverFn: () => serverFn,
+  serviceFile: () => serviceFile,
+  verifyServer: () => verifyServer
+});
+var camel = (name) => name.toLowerCase().replace(/_+([a-z0-9])/g, (_, ch) => ch.toUpperCase());
+var envConfig = (names) => {
+  const fields = names.length ? names.map((n) => `  ${camel(n)}: '${n}',`).join("\n") : `  // apiUrl: 'API_URL',`;
+  return `import { pickEnv } from '@fluixi/start/env';
+
+// Every missing variable is reported at once, when this module loads. A field that may be
+// unset takes { key, optional: true } or { key, default }; parse: asNumber and friends convert.
+export const config = pickEnv({
+${fields}
+});
+`;
+};
+var moduleFile = (Name, name) => `import { defineModule } from '@fluixi/start/app';
+
+export const ${Name}Module = defineModule({
+  name: '${name}',
+  imports: [],
+  providers: [],
+});
+`;
+var serviceFile = (Name, name, server) => `${server ? `// Server only: the browser build refuses a page that imports this file.
+` : ""}import { injectionToken } from '@fluixi/start/di';
+import { defineModule } from '@fluixi/start/app';
+
+export class ${Name}Service {}
+
+export const ${Name}Token = injectionToken<${Name}Service>('${Name}');
+
+export const ${Name}Module = defineModule({
+  name: '${name}',
+  providers: [{ provide: ${Name}Token, useFactory: () => new ${Name}Service() }],
+});
+`;
+var apiRoute = () => `export function GET(request: Request) {
+  return Response.json({ path: new URL(request.url).pathname });
+}
+`;
+var guardedApiRoute = (guardImport, role) => `import { guard } from '${guardImport}';
+
+export const GET = guard(
+  async (request, claims) => {
+    return Response.json({ sub: claims.sub });
+  },
+  { role: '${role}' },
+);
+`;
+var verifyServer = () => `import { createTokenVerifier, createApiGuard } from '@fluixi/oauth2/verify';
+import { auth } from '../config/env.js';
+
+// Checks a bearer token's signature, issuer, audience and expiry against the provider.
+export const verify = createTokenVerifier(auth.provider.verifier(auth.clientId));
+
+// Answers 401 without a valid token and 403 without the role.
+export const guard = createApiGuard({ verify, roles: auth.provider.roles });
+`;
+var serverFn = (name) => `export async function ${name}(input: { id: string }) {
+  'use server';
+  // Runs on the server only. The browser calls it over RPC, so input and result are plain data.
+  return { id: input.id };
+}
+`;
+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(readFileSync2(join(root, "tsconfig.json"), "utf8"));
+    if (ts?.compilerOptions && !ts.compilerOptions.jsx) return "html";
+  } catch {
+  }
+  return "jsx";
+}
+function importPath(from, to) {
+  const p = relative(dirname2(from), to).replace(/\\/g, "/").replace(/\.tsx?$/, ".js");
+  return p.startsWith(".") ? p : `./${p}`;
+}
+function writeOnce(log, file, content) {
+  if (existsSync2(file)) {
+    log.push({ kind: "kept", file });
+    return false;
+  }
+  mkdirSync2(dirname2(file), { recursive: true });
+  writeFileSync2(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 = 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 = join(root, "src/config/env.ts");
+  if (writeOnce(log, file, authEnvConfig())) return;
+  let text = readFileSync2(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';`);
+  writeFileSync2(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 = (rel2) => join(root, rel2);
+  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 = (rel2) => join(root, rel2);
+  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: []
+  };
+}
+
+// src/scaffold/prompt.ts
+import { createInterface } from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
+import { stdin as input, stdout as output, exit, env } from "node:process";
+var COLOR = env.NO_COLOR || env.FORCE_COLOR === "0" ? false : (!!output.isTTY || !!env.FORCE_COLOR) && env.TERM !== "dumb";
+var sgr = (o, x) => (s) => COLOR ? `\x1B[${o}m${s}\x1B[${x}m` : `${s}`;
+var c = { bold: sgr(1, 22), green: sgr(32, 39), cyan: sgr(36, 39), gray: sgr(90, 39) };
+var BAR = c.gray("│");
+function askSelect(label, choices) {
+  return new Promise((done) => {
+    let idx = 0;
+    output.write(`${c.green("◆")}  ${c.bold(label)}
+`);
+    const draw = (first) => {
+      if (!first) output.write(`\x1B[${choices.length}A`);
+      for (let i = 0; i < choices.length; i++) {
+        const on = i === idx;
+        const dot = on ? c.green("●") : c.gray("○");
+        const name = on ? c.cyan(c.bold(choices[i].label)) : choices[i].label;
+        output.write(`\x1B[2K${BAR}  ${dot} ${name}  ${c.gray(choices[i].hint)}
+`);
+      }
+    };
+    draw(true);
+    emitKeypressEvents(input);
+    if (input.isTTY) input.setRawMode(true);
+    const onKey = (_s, k) => {
+      if (k.name === "up" || k.name === "k") {
+        idx = (idx - 1 + choices.length) % choices.length;
+        draw(false);
+      } else if (k.name === "down" || k.name === "j") {
+        idx = (idx + 1) % choices.length;
+        draw(false);
+      } else if (k.name === "return" || k.name === "enter") {
+        finish();
+        done(choices[idx].value);
+      } else if (k.name === "c" && k.ctrl) {
+        finish();
+        output.write("\n");
+        exit(1);
+      }
+    };
+    const onEnd = () => {
+      finish();
+      done(choices[idx].value);
+    };
+    const finish = () => {
+      input.off("keypress", onKey);
+      input.off("end", onEnd);
+      input.off("close", onEnd);
+      if (input.isTTY) input.setRawMode(false);
+      input.pause();
+      output.write(`${BAR}
+`);
+    };
+    if (input.readableEnded) {
+      finish();
+      done(choices[idx].value);
+      return;
+    }
+    input.on("keypress", onKey);
+    input.on("end", onEnd);
+    input.on("close", onEnd);
+    input.resume();
+  });
+}
+
+// src/report.ts
+import { relative as relative2 } from "node:path";
+import { c as c2 } from "@fluixi/start/ui";
+var rel = (file) => relative2(process.cwd(), file) || ".";
+function report(steps) {
+  for (const s of steps) {
+    if (s.kind === "hint") {
+      console.log(`  ${c2.yellow("!")} ${c2.gray("add to")} ${c2.cyan(rel(s.file))}${c2.gray(":")}`);
+      for (const l of s.lines) console.log(`    ${l}`);
+    } else if (s.kind === "kept") {
+      console.log(`  ${c2.gray("-")} ${c2.cyan(rel(s.file))} ${c2.gray("exists, kept")}`);
+    } else if (s.kind === "listed") {
+      console.log(`  ${c2.gray("-")} ${c2.cyan(rel(s.file))} ${c2.gray("already lists it")}`);
+    } else {
+      console.log(`  ${c2.green("✓")} ${c2.gray(s.kind)} ${c2.cyan(rel(s.file))}${s.detail ? c2.gray(`: ${s.detail}`) : ""}`);
+    }
+  }
+}
+function reportAuth(result, installHint) {
+  for (const n of result.notes) console.log(`  ${c2.gray(n)}`);
+  report(result.steps);
+  const next = [...installHint ? [installHint] : [], ...result.next];
+  if (next.length) console.log(`  ${c2.gray("next:")} ${next.map((n) => c2.gray(n)).join(c2.gray("; "))}`);
+}
+
+// src/generate.ts
+var GEN_USAGE = `Usage: fluixi generate <kind> [name] [options]
 
 Kinds:
-  component <Name>      a reusable component        → src/components/<Name>.{tsx,ts}
-  route <path>          a file-based route page     → src/routes/<path>.{tsx,ts}
-  middleware            the request middleware file → src/middleware.ts
-  auth                  @fluixi/auth wiring         → auth.config + auth.client + middleware + /api/auth route
+  component <Name>            a reusable component         → src/components/<Name>.{tsx,ts}
+  route <path>                a file-based route page      → src/routes/<path>.{tsx,ts}
+  middleware                  the request middleware file  → src/middleware.ts
+  env                         typed config from env.public → src/config/env.ts
+  module <name>               an app module                → src/services/<name>/<name>.module.ts
+  service <Name> [--server]   a service, token and module  → src/services/<name>.ts (.server.ts)
+  api <path> [--role <role>]  an API route, guarded by role → src/api/<path>.ts
+  server-fn <name>            a "use server" function      → src/server/<name>.ts
+  auth oauth2 [--provider <p>] [--tokens browser|server]
+                              @fluixi/oauth2 wiring: env config, service, routes, .env.example
+                              (fluixi add auth does the same, asks, and installs)
+  auth better-auth            @fluixi/auth wiring          → auth.config + auth.client + middleware + /api/auth
 
+Modules and services are listed in src/app.config.ts, or app.config.server.ts for --server,
+which is created when missing. Providers: ${templates_exports.PROVIDERS.join(", ")}.
 Component/route syntax follows the project (JSX → .tsx, html\`\` → .ts); override with --jsx / --html.
 `;
 function detectFormat() {
@@ -24,7 +597,7 @@ function detectFormat() {
   if (args.includes("--html")) return "html";
   if (args.includes("--jsx")) return "jsx";
   try {
-    const ts = JSON.parse(readFileSync(resolve("tsconfig.json"), "utf8"));
+    const ts = JSON.parse(readFileSync3(resolve("tsconfig.json"), "utf8"));
     if (ts?.compilerOptions && !ts.compilerOptions.jsx) return "html";
   } catch {
   }
@@ -35,28 +608,46 @@ function pascal(s) {
 }
 function resolveHint(Name, ext) {
   const configs = ["vite.config.ts", "vite.config.js", "fluixi.config.ts", "fluixi.config.js"];
-  const found = configs.map((f) => resolve(f)).find((f) => existsSync(f));
+  const found = configs.map((f) => resolve(f)).find((f) => existsSync3(f));
   if (!found) return;
   try {
-    if (/\bresolve\s*:\s*\[/.test(readFileSync(found, "utf8"))) return;
+    if (/\bresolve\s*:\s*\[/.test(readFileSync3(found, "utf8"))) return;
   } catch {
     return;
   }
   console.log(
-    `  ${c.gray("to use")} ${c.cyan(`<${Name} />`)} ${c.gray("without importing it, add to")} ${c.cyan(relative(process.cwd(), found))}:`
+    `  ${c3.gray("to use")} ${c3.cyan(`<${Name} />`)} ${c3.gray("without importing it, add to")} ${c3.cyan(relative3(process.cwd(), found))}:`
   );
-  console.log(`    ${c.gray(`resolve: [{ match: /^([A-Z]\\w+)$/, module: '/src/components/$1.${ext}' }]`)}`);
-  console.log(`  ${c.gray("one pattern covers the whole folder. Importing it works too — including with")} ${c.cyan("load:")}`);
+  console.log(`    ${c3.gray(`resolve: [{ match: /^([A-Z]\\w+)$/, module: '/src/components/$1.${ext}' }]`)}`);
+  console.log(`  ${c3.gray("one pattern covers the whole folder. Importing it works too — including with")} ${c3.cyan("load:")}`);
+}
+function option(name) {
+  const args = process.argv;
+  const i = args.indexOf(`--${name}`);
+  if (i !== -1 && args[i + 1] && !args[i + 1].startsWith("--")) return args[i + 1];
+  return args.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+var kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+function writeOnce2(file, content) {
+  const steps = [];
+  const wrote = writeOnce(steps, file, content);
+  report(steps);
+  return wrote;
+}
+function registerIn(server, file, name, entry = name) {
+  const steps = [];
+  registerModule(steps, process.cwd(), server, file, name, entry);
+  report(steps);
 }
 function write(file, content) {
-  const rel = relative(process.cwd(), file);
-  if (existsSync(file)) {
-    console.error(`  ${c.red("✗")} ${rel} ${c.gray("already exists")}`);
+  const rel2 = relative3(process.cwd(), file);
+  if (existsSync3(file)) {
+    console.error(`  ${c3.red("✗")} ${rel2} ${c3.gray("already exists")}`);
     process.exit(1);
   }
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, content);
-  console.log(`  ${c.green("✓")} ${c.gray("created")} ${c.cyan(rel)}`);
+  mkdirSync3(dirname3(file), { recursive: true });
+  writeFileSync3(file, content);
+  console.log(`  ${c3.green("✓")} ${c3.gray("created")} ${c3.cyan(rel2)}`);
 }
 var component = (Name) => `import type { Component, ComponentChild } from '@fluixi/core';
 
@@ -110,44 +701,6 @@ export default defineMiddleware([
   },
 ]);
 `;
-var authConfig = () => `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 authClient = () => `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 authMiddleware = () => `import { defineMiddleware } from '@fluixi/start';
-import { authMiddleware } from '@fluixi/auth/server';
-import './auth.config.js';
-
-export default defineMiddleware([authMiddleware()]);
-`;
-var authRoute = () => `import { mountAuthRoutes } from '@fluixi/auth/server';
-import '../../../auth.config.js';
-
-const handler = mountAuthRoutes();
-export const GET = handler;
-export const POST = handler;
-export default handler;
-`;
 function generate(kind, name) {
   switch (kind) {
     case "component":
@@ -172,58 +725,376 @@ function generate(kind, name) {
     case "m":
       write(resolve("src/middleware.ts"), middleware());
       break;
+    case "env": {
+      const names = (envPublicNames(resolve("fluixi.config.ts")) ?? []).filter((n) => !n.startsWith("AUTH_"));
+      write(resolve("src/config/env.ts"), templates_exports.envConfig(names));
+      break;
+    }
+    case "module": {
+      if (!name) return fail("module name required, e.g. `fluixi g module billing`");
+      const slug = kebab(name);
+      const file = resolve("src/services", slug, `${slug}.module.ts`);
+      write(file, templates_exports.moduleFile(pascal(name), slug));
+      registerIn(false, file, `${pascal(name)}Module`);
+      break;
+    }
+    case "service":
+    case "s": {
+      if (!name) return fail("service name required, e.g. `fluixi g service Orders`");
+      const Name = pascal(name).replace(/Service$/, "") || "App";
+      const server = process.argv.includes("--server");
+      const file = resolve("src/services", `${kebab(Name)}${server ? ".server" : ""}.ts`);
+      write(file, templates_exports.serviceFile(Name, kebab(Name), server));
+      registerIn(server, file, `${Name}Module`);
+      break;
+    }
+    case "api": {
+      if (!name) return fail("api path required, e.g. `fluixi g api users/[id]`");
+      const file = resolve("src/api", `${name.replace(/\.ts$/, "")}.ts`);
+      const role = option("role");
+      if (!role) {
+        write(file, templates_exports.apiRoute());
+        break;
+      }
+      const verify = resolve("src/services/verify.server.ts");
+      write(file, templates_exports.guardedApiRoute(importPath(file, verify), role));
+      writeOnce2(verify, templates_exports.verifyServer());
+      {
+        const steps = [];
+        ensureAuthEnv(steps, process.cwd());
+        report(steps);
+      }
+      break;
+    }
+    case "server-fn": {
+      if (!name) return fail("function name required, e.g. `fluixi g server-fn getUser`");
+      const fn = name.replace(/[^a-zA-Z0-9]+(.)/g, (_, ch) => ch.toUpperCase());
+      write(resolve("src/server", `${fn}.ts`), templates_exports.serverFn(fn));
+      break;
+    }
     case "auth":
-      write(resolve("src/auth.config.ts"), authConfig());
-      write(resolve("src/auth.client.ts"), authClient());
-      write(resolve("src/middleware.ts"), authMiddleware());
-      write(resolve("src/routes/api/auth/[...all].ts"), authRoute());
-      console.log(`  ${c.gray("next: install")} ${c.cyan("better-auth")}${c.gray(", set your DB adapter in auth.config.ts, and forward `request` in entry-server")}`);
+      try {
+        if (name === "oauth2") {
+          reportAuth(
+            setupOAuth2(process.cwd(), {
+              provider: option("provider"),
+              tokens: tokensOption(),
+              format: detectFormat()
+            }),
+            "install @fluixi/oauth2"
+          );
+        } else if (!name || name === "better-auth") {
+          reportAuth(setupBetterAuth(process.cwd()), "install @fluixi/auth and better-auth");
+        } else {
+          return fail(`unknown auth kind ${name}: oauth2 or better-auth`);
+        }
+      } catch (error) {
+        if (error instanceof ScaffoldError) return fail(error.message);
+        throw error;
+      }
       break;
     default:
       console.error(GEN_USAGE);
       process.exit(1);
   }
 }
+function tokensOption() {
+  const tokens = option("tokens");
+  if (tokens !== void 0 && tokens !== "browser" && tokens !== "server") {
+    fail("--tokens is browser or server");
+  }
+  return tokens;
+}
 function fail(msg) {
-  console.error(`  ${c.red("✗")} ${msg}`);
+  console.error(`  ${c3.red("✗")} ${msg}`);
   process.exit(1);
 }
 
+// src/add.ts
+import { execFileSync } from "node:child_process";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
+import { join as join2 } from "node:path";
+import { stdin } from "node:process";
+import { c as c4 } from "@fluixi/start/ui";
+var ADD_USAGE = `Usage: fluixi add <feature> [options]
+
+Features:
+  auth [oauth2|better-auth]   authentication, asked for when not given
+    --provider <p>            ${PROVIDERS.join(", ")}
+    --tokens browser|server   where an OAuth2 app keeps its tokens
+    --no-install              write the files, leave the packages to you
+`;
+function option2(args, name) {
+  const i = args.indexOf(`--${name}`);
+  if (i !== -1 && args[i + 1] && !args[i + 1].startsWith("-")) return args[i + 1];
+  return args.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+function installCommand(root, specs) {
+  if (existsSync4(join2(root, "pnpm-lock.yaml"))) return ["pnpm", ["add", ...specs]];
+  if (existsSync4(join2(root, "yarn.lock"))) return ["yarn", ["add", ...specs]];
+  if (existsSync4(join2(root, "bun.lockb")) || existsSync4(join2(root, "bun.lock"))) return ["bun", ["add", ...specs]];
+  return ["npm", ["install", ...specs]];
+}
+function channelOf(root) {
+  try {
+    const version = JSON.parse(readFileSync4(join2(root, "node_modules/@fluixi/start/package.json"), "utf8")).version;
+    return version.match(/-([a-z]+)\./)?.[1] ?? "latest";
+  } catch {
+    return "alpha";
+  }
+}
+async function addAuth(root, args) {
+  const ask = stdin.isTTY;
+  let kind = args[1] && !args[1].startsWith("-") ? args[1] : void 0;
+  let provider = option2(args, "provider");
+  let tokens = option2(args, "tokens");
+  if (kind && kind !== "oauth2" && kind !== "better-auth") throw new ScaffoldError(`unknown auth kind ${kind}: oauth2 or better-auth`);
+  if (tokens && tokens !== "browser" && tokens !== "server") throw new ScaffoldError("--tokens is browser or server");
+  if (provider && !PROVIDERS.includes(provider)) throw new ScaffoldError(`unknown provider ${provider}: ${PROVIDERS.join(", ")}`);
+  if (!kind && ask) {
+    kind = await askSelect("Authentication", [
+      { value: "oauth2", label: "OAuth2 / OIDC", hint: "@fluixi/oauth2 · Keycloak, Auth0, Okta, Google…" },
+      { value: "better-auth", label: "Better Auth", hint: "@fluixi/auth · your own user table" }
+    ]);
+  }
+  kind ??= "oauth2";
+  if (kind === "oauth2" && !provider && ask) {
+    provider = await askSelect("Identity provider", PROVIDERS.map((p) => ({ value: p, label: p, hint: "" })));
+  }
+  if (kind === "oauth2" && !tokens && ask && !SERVER_ONLY[provider ?? "oidc"]) {
+    tokens = await askSelect("Where the tokens live", [
+      { value: "browser", label: "Browser", hint: "public client · PKCE" },
+      { value: "server", label: "Server", hint: "httpOnly cookie · client secret" }
+    ]);
+  }
+  const channel = channelOf(root);
+  const result = kind === "oauth2" ? setupOAuth2(root, { provider, tokens, format: projectFormat(root) }, channel) : setupBetterAuth(root, channel);
+  const specs = Object.entries(result.dependencies).map(([name, spec]) => `${name}@${spec}`);
+  if (args.includes("--no-install")) {
+    reportAuth(result, `install ${specs.join(" ")}`);
+    return;
+  }
+  reportAuth(result);
+  const [bin, binArgs] = installCommand(root, specs);
+  console.log(`  ${c4.gray("›")} ${c4.cyan([bin, ...binArgs].join(" "))}`);
+  execFileSync(bin, binArgs, { cwd: root, stdio: "inherit" });
+}
+async function add(feature, args, root = process.cwd()) {
+  if (feature !== "auth") {
+    console.error(ADD_USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    await addAuth(root, args);
+  } catch (error) {
+    if (!(error instanceof ScaffoldError)) throw error;
+    console.error(`  ${c4.red("✗")} ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
 // src/start-copy.ts
 import { realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname as dirname2, join } from "node:path";
+import { dirname as dirname4, join as join3 } from "node:path";
 function locate(from) {
   try {
     const file = createRequire(from).resolve("@fluixi/start/package.json");
-    return { dir: dirname2(realpathSync(file)), version: createRequire(from)(file).version };
+    return { dir: dirname4(realpathSync(file)), version: createRequire(from)(file).version };
   } catch {
     return null;
   }
 }
 function startMismatch(appRoot, cliFile) {
-  const app = locate(join(appRoot, "package.json"));
+  const app = locate(join3(appRoot, "package.json"));
   const cli = locate(cliFile);
   if (!app || !cli || app.dir === cli.dir) return null;
   return { app, cli };
 }
 
+// src/check.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { dirname as dirname5, join as join4, relative as relative4, resolve as resolve2 } from "node:path";
+import { envAuthDiagnostics } from "@fluixi/ts-plugin/rules";
+import { c as c5 } from "@fluixi/start/ui";
+function loadTypeScript(root) {
+  try {
+    return createRequire2(join4(root, "package.json"))("typescript");
+  } catch {
+    throw new Error("fluixi check needs typescript in the app: npm install -D typescript");
+  }
+}
+function rootFiles(ts, configPath, seen = /* @__PURE__ */ new Set()) {
+  seen.add(configPath);
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (read.error) throw new Error(ts.flattenDiagnosticMessageText(read.error.messageText, "\n"));
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname5(configPath));
+  const files = [...parsed.fileNames];
+  let options = parsed.options;
+  for (const ref of parsed.projectReferences ?? []) {
+    const path = ts.resolveProjectReferencePath(ref);
+    if (seen.has(path) || !existsSync5(path)) continue;
+    const child = rootFiles(ts, path, seen);
+    files.push(...child.files);
+    if (!parsed.fileNames.length) options = child.options;
+  }
+  return { files, options };
+}
+function checkProject(root = process.cwd(), ts = loadTypeScript(root)) {
+  const configPath = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
+  if (!configPath) throw new Error(`no tsconfig.json in ${root}`);
+  const { files, options } = rootFiles(ts, configPath);
+  for (const name of ["fluixi.config.ts", "fluixi.config.mts", "fluixi.config.js"]) {
+    const path = resolve2(root, name);
+    if (existsSync5(path) && !files.includes(path)) files.push(path);
+  }
+  const compilerOptions = { ...options, noEmit: true };
+  const host = ts.createCompilerHost(compilerOptions, true);
+  const program = ts.createProgram({ rootNames: [...new Set(files)], options: compilerOptions, host });
+  const out = [];
+  for (const sf of program.getSourceFiles()) {
+    if (sf.isDeclarationFile || /[\\/]node_modules[\\/]/.test(sf.fileName)) continue;
+    for (const d of envAuthDiagnostics(ts, program, sf.fileName, ts.sys)) {
+      const at = sf.getLineAndCharacterOfPosition(d.start ?? 0);
+      out.push({
+        file: relative4(root, sf.fileName),
+        line: at.line + 1,
+        column: at.character + 1,
+        code: d.code,
+        severity: d.category === ts.DiagnosticCategory.Error ? "error" : d.category === ts.DiagnosticCategory.Warning ? "warning" : "suggestion",
+        message: ts.flattenDiagnosticMessageText(d.messageText, " ")
+      });
+    }
+  }
+  return out.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+}
+function check(root = process.cwd(), strict = false) {
+  const found = checkProject(root);
+  const shown = found.filter((f) => f.severity !== "suggestion");
+  const mark = { error: c5.red("error"), warning: c5.yellow("warning"), suggestion: c5.gray("note") };
+  const lines = shown.map(
+    (f) => `  ${c5.cyan(`${f.file}:${f.line}:${f.column}`)}  ${mark[f.severity]}  ${c5.gray(`FX${f.code}`)}  ${f.message}`
+  );
+  const errors = shown.filter((f) => f.severity === "error").length;
+  const warnings = shown.length - errors;
+  const notes = found.length - shown.length;
+  const tally = [`${errors} error${errors === 1 ? "" : "s"}`, `${warnings} warning${warnings === 1 ? "" : "s"}`];
+  if (notes) tally.push(`${notes} note${notes === 1 ? "" : "s"}`);
+  console.log(["", ...lines, ...lines.length ? [""] : [], `  ${shown.length ? c5.bold(tally.join(", ")) : `${c5.green("✓")} no env or auth findings`}`, ""].join("\n"));
+  return errors || strict && warnings ? 1 : 0;
+}
+
+// src/doctor.ts
+import { existsSync as existsSync6, readdirSync, readFileSync as readFileSync5, realpathSync as realpathSync2 } from "node:fs";
+import { createRequire as createRequire3 } from "node:module";
+import { join as join5 } from "node:path";
+var readJson = (file) => JSON.parse(readFileSync5(file, "utf8"));
+function resolvedVersions(root) {
+  const out = {};
+  const scope = join5(root, "node_modules/@fluixi");
+  if (!existsSync6(scope)) return out;
+  for (const name of readdirSync(scope).sort()) {
+    const file = join5(scope, name, "package.json");
+    if (existsSync6(file)) out[`@fluixi/${name}`] = readJson(file).version;
+  }
+  return out;
+}
+function installedCopies(root) {
+  const found = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  const add2 = (dir) => {
+    const file = join5(dir, "package.json");
+    if (!existsSync6(file)) return;
+    const real = realpathSync2(dir);
+    if (seen.has(real)) return;
+    seen.add(real);
+    const { name, version } = readJson(file);
+    if (!found.has(name)) found.set(name, /* @__PURE__ */ new Set());
+    found.get(name).add(version);
+  };
+  const scan = (modules, depth) => {
+    const scope = join5(modules, "@fluixi");
+    if (existsSync6(scope)) {
+      for (const name of readdirSync(scope)) {
+        add2(join5(scope, name));
+        if (depth > 0) scan(join5(scope, name, "node_modules"), depth - 1);
+      }
+    }
+  };
+  const top = join5(root, "node_modules");
+  scan(top, 2);
+  const store = join5(top, ".pnpm");
+  if (existsSync6(store)) {
+    for (const entry of readdirSync(store)) {
+      if (entry.startsWith("@fluixi+")) scan(join5(store, entry, "node_modules"), 0);
+    }
+  }
+  return Object.fromEntries([...found].map(([k, v]) => [k, [...v].sort()]));
+}
+function pluginConfigured(root) {
+  const file = join5(root, "tsconfig.json");
+  if (!existsSync6(file)) return null;
+  let config;
+  try {
+    const ts = createRequire3(join5(root, "package.json"))("typescript");
+    config = ts.readConfigFile(file, ts.sys.readFile).config;
+  } catch {
+    try {
+      config = readJson(file);
+    } catch {
+      return null;
+    }
+  }
+  return (config?.compilerOptions?.plugins ?? []).some((p) => p.name === "@fluixi/ts-plugin");
+}
+function diagnose(root) {
+  const problems = [];
+  for (const [name, versions] of Object.entries(installedCopies(root))) {
+    if (versions.length > 1) {
+      problems.push({ severity: "error", message: `${name} is installed ${versions.length} times (${versions.join(", ")}); each copy keeps its own state` });
+    }
+  }
+  const pkg = existsSync6(join5(root, "package.json")) ? readJson(join5(root, "package.json")) : {};
+  const declared = { ...pkg.dependencies, ...pkg.devDependencies };
+  const prerelease = Object.entries(declared).filter(([n]) => n.startsWith("@fluixi/")).map(([, v]) => v.match(/-(alpha|beta|rc)\.\d+/)?.[1]).filter(Boolean);
+  if (new Set(prerelease).size > 1) {
+    problems.push({ severity: "warning", message: `@fluixi/* dependencies mix prerelease tags (${[...new Set(prerelease)].join(", ")})` });
+  }
+  const plugin = pluginConfigured(root);
+  if (plugin === false) {
+    problems.push({
+      severity: "warning",
+      message: 'tsconfig.json does not load @fluixi/ts-plugin: the editor shows no env or auth warnings. Add { "name": "@fluixi/ts-plugin" } to compilerOptions.plugins'
+    });
+  } else if (plugin && !existsSync6(join5(root, "node_modules/@fluixi/ts-plugin"))) {
+    problems.push({ severity: "warning", message: "tsconfig.json names @fluixi/ts-plugin, which is not installed" });
+  }
+  return problems;
+}
+
 // src/cli.ts
 function usage() {
-  const cmd = (name, desc) => `  ${c2.cyan(name.padEnd(25))}${c2.gray(desc)}`;
+  const cmd = (name, desc) => `  ${c6.cyan(name.padEnd(25))}${c6.gray(desc)}`;
   return [
     "",
-    `  ${wordmark()}  ${c2.gray("the Fluixi command-line tool")}`,
+    `  ${wordmark()}  ${c6.gray("the Fluixi command-line tool")}`,
     "",
-    `  ${c2.bold("Usage")}  ${c2.gray("fluixi <command>")}`,
+    `  ${c6.bold("Usage")}  ${c6.gray("fluixi <command>")}`,
     "",
     cmd("dev", "start the SSR dev server (Vite middleware + HMR)"),
     cmd("build", "build the client + server bundles for production"),
     cmd("build --format=web-component", "build custom elements as portable files"),
     cmd("start", "run the production SSR server (after build)"),
-    cmd("generate <kind> <name>", "scaffold a component / route / middleware / auth  " + c2.dim("(alias: g)")),
+    cmd("generate <kind> <name>", "scaffold code, see fluixi g --help  " + c6.dim("(alias: g)")),
+    cmd("add auth", "set up authentication: asks, writes, installs"),
+    cmd("check [--strict]", "env and auth rules over the project, for CI"),
+    cmd("env", "declared and set variables, secrets that would ship, env types"),
+    cmd("doctor", "duplicate packages, editor plugin, env problems"),
+    cmd("info", "versions, adapter, modules, page and API routes"),
     "",
-    `  ${c2.gray("New project:")}  ${c2.cyan("npm create fluixi")} ${c2.gray("<dir>")}`,
+    `  ${c6.gray("New project:")}  ${c6.cyan("npm create fluixi")} ${c6.gray("<dir>")}`,
     ""
   ].join("\n");
 }
@@ -237,13 +1108,21 @@ async function main() {
     generate(process.argv[3], process.argv[4]);
     return;
   }
+  if (cmd === "add") {
+    await add(process.argv[3], process.argv.slice(3));
+    return;
+  }
+  if (cmd === "check") {
+    process.exitCode = check(process.cwd(), process.argv.includes("--strict"));
+    return;
+  }
   const config = await loadConfig();
   const mismatch = startMismatch(process.cwd(), import.meta.url);
   if (mismatch) {
     const { app, cli } = mismatch;
     console.warn(
       `
-  ${c2.yellow("!")} fluixi is running @fluixi/start ${cli.version} from ${cli.dir}
+  ${c6.yellow("!")} fluixi is running @fluixi/start ${cli.version} from ${cli.dir}
     but this app resolves ${app.version} from ${app.dir}.
     Changes to the app's copy will not take effect. With npm, add
     "overrides": { "@fluixi/start": "$@fluixi/start" } to package.json and reinstall.
@@ -263,16 +1142,36 @@ async function main() {
     case "start":
       await start(config);
       break;
+    case "env":
+      process.exitCode = await env2(config);
+      break;
+    case "info":
+      await info(config, resolvedVersions(config.root ?? process.cwd()));
+      break;
+    case "doctor":
+      process.exitCode = await doctor(config);
+      break;
     default:
       console.error(`
-  ${c2.red("✗")} Unknown command: ${c2.bold(cmd)}`);
+  ${c6.red("✗")} Unknown command: ${c6.bold(cmd)}`);
       console.log(usage());
       process.exit(1);
   }
 }
+async function doctor(config) {
+  const problems = diagnose(config.root ?? process.cwd());
+  const r = await envReport(config);
+  for (const n of r.secretPublic) problems.push({ severity: "error", message: `${n} is in env.public and reads like a secret` });
+  for (const e of r.exposed) problems.push({ severity: "error", message: `${e.name} in ${e.file} carries the client prefix, so Vite ships it` });
+  for (const p of r.public.filter((p2) => !p2.set)) problems.push({ severity: "warning", message: `${p.name} is in env.public and not set` });
+  for (const n of r.missing) problems.push({ severity: "warning", message: `${n} is in .env.example and not set locally` });
+  const lines = problems.map((p) => `  ${p.severity === "error" ? c6.red("✗") : c6.yellow("!")} ${p.message}`);
+  console.log(["", ...lines.length ? lines : [`  ${c6.green("✓")} nothing to report`], ""].join("\n"));
+  return problems.some((p) => p.severity === "error") ? 1 : 0;
+}
 main().catch((e) => {
   console.error(`
-  ${c2.red("✗")} ${e?.message ?? e}
+  ${c6.red("✗")} ${e?.message ?? e}
 `);
   process.exit(1);
 });