tina4-nodejs 3.13.124 → 3.13.130

package/packages/cli/src/bin.ts

@@ -6,6 +6,7 @@ import { migrateStatus } from "./commands/migrateStatus.js";
 import { migrateRollback } from "./commands/migrateRollback.js";
 import { listRoutes } from "./commands/routes.js";
 import { runTests } from "./commands/test.js";
+import { runLint } from "./commands/lint.js";
 import { generate, GENERATORS, RESOLUTION_ENVELOPE_VERSION } from "./commands/generate.js";
 import { runSeeds } from "./commands/seed.js";
 import { queueCommand, QUEUE_SUBCOMMAND_NAMES } from "./commands/queue.js";
@@ -370,6 +371,11 @@ export const COMMANDS: Record<string, CommandSpec> = {
     usage: "[file]",
     summary: "Run project tests",
   },
+  lint: {
+    handler: (a) => { runLint(a); },
+    usage: "[--fix] [--no-install]",
+    summary: "Lint the project (eslint, installed dev-only on demand; else tsc/node --check baseline)",
+  },
   queue: {
     handler: async (a) => { await queueCommand(a); },
     usage: "<work|stats|retry|clear> [topic]",

package/packages/cli/src/commands/generate.ts

@@ -37,8 +37,8 @@ import { join, relative, resolve, sep } from "node:path";
 
 // ── Field type mapping ──────────────────────────────────────────────
 const FIELD_TYPE_MAP: Record<string, { orm: string; sql: string; defaultVal: string }> = {
-  string:   { orm: '"string"',   sql: "TEXT",    defaultVal: "''" },
-  str:      { orm: '"string"',   sql: "TEXT",    defaultVal: "''" },
+  string:   { orm: '"string"',   sql: "VARCHAR(255)", defaultVal: "''" },
+  str:      { orm: '"string"',   sql: "VARCHAR(255)", defaultVal: "''" },
   int:      { orm: '"integer"',  sql: "INTEGER", defaultVal: "0" },
   integer:  { orm: '"integer"',  sql: "INTEGER", defaultVal: "0" },
   float:    { orm: '"number"',   sql: "REAL",    defaultVal: "0" },
@@ -48,7 +48,7 @@ const FIELD_TYPE_MAP: Record<string, { orm: string; sql: string; defaultVal: str
   bool:     { orm: '"boolean"',  sql: "INTEGER", defaultVal: "0" },
   boolean:  { orm: '"boolean"',  sql: "INTEGER", defaultVal: "0" },
   text:     { orm: '"string"',   sql: "TEXT",    defaultVal: "''" },
-  datetime: { orm: '"datetime"', sql: "TEXT",    defaultVal: "NULL" },
+  datetime: { orm: '"datetime"', sql: "TIMESTAMP", defaultVal: "NULL" },
   blob:     { orm: '"string"',   sql: "BLOB",    defaultVal: "NULL" },
 };
 
@@ -131,13 +131,78 @@ export function toTableName(name: string): string {
       from: raw,
       to: safe,
       reason: `SQL reserved word '${raw}' would break CREATE TABLE`,
-      override: `--table ${raw} --quote (requires quoted-identifier mode, not yet implemented)`,
+      override: `--table-name <name> (table names interpolate unquoted; forcing a reserved name is yours to quote in raw SQL)`,
     });
     return safe;
   }
   return raw;
 }
 
+/**
+ * The table name a generator uses (issue #123) — honours `--table-name` and
+ * speaks up instead of renaming SILENTLY. Mirrors the Python master's
+ * `_resolve_table` (tina4-python/tina4_python/cli/__init__.py).
+ *
+ * `announce` prints the note/warning; it is TRUE only for `generateModel` (where
+ * the table is born). Composite generators (crud) let the model sub-call
+ * announce, and generators that target an EXISTING table (route/seeder/form/view/
+ * migration) still honour `--table-name` but stay quiet so the note is not
+ * repeated — the note prints exactly once per `generate`.
+ *
+ *  • `--table-name <name>` wins verbatim. If that name is ITSELF a reserved word,
+ *    warn loudly (when announcing): Tina4 interpolates table names UNQUOTED, so
+ *    the ORM's generated SQL will fail on it — quoting it in raw SQL + migrations
+ *    is now the developer's job (we do NOT silently quote; identifier quoting is a
+ *    global storage invariant, not a local fix).
+ *  • Otherwise fall back to `toTableName` (snake + reserved-word pluralise). When
+ *    that auto-pluralises a reserved-word class name (`Order` -> `orders`), print a
+ *    one-line NOTE (when announcing) naming the rename and the `--table-name`
+ *    escape hatch, so the developer is informed rather than surprised.
+ *
+ * The note/warning goes to STDERR (console.error) so a `generate … --json` run
+ * keeps its stdout envelope pristine for a downstream `| jq`. `toTableName`'s
+ * `reserved_word_pluralize` envelope transformation is UNCHANGED (this ADDS the
+ * announce path; it does not touch the envelope contract).
+ */
+export function resolveTable(
+  name: string,
+  flags: Record<string, string | boolean> | undefined,
+  opts: { announce?: boolean } = {},
+): string {
+  const announce = opts.announce ?? false;
+  const override = (flags ?? {})["table-name"];
+
+  // `--table-name <name>` wins verbatim. A bare `--table-name` (no value) parses
+  // to `true` — ignore it, exactly like the Python master (falls through to the
+  // pluralise path), rather than letting the boolean become the table name.
+  if (typeof override === "string" && override) {
+    if (announce && SQL_RESERVED_TABLE_NAMES.has(toSnake(override))) {
+      console.error(
+        `  ! table_name '${override}' is a SQL reserved word. Tina4 interpolates ` +
+          `table names UNQUOTED, so the ORM's generated SQL will fail on it -- ` +
+          `quote it yourself in raw SQL and migrations.`,
+      );
+    }
+    return override;
+  }
+
+  const bare = toSnake(name);
+  if (!SQL_RESERVED_TABLE_NAMES.has(bare)) {
+    return bare; // non-reserved: singular, silent, no envelope transformation
+  }
+
+  // Reserved: pluralise via toTableName (which records the envelope
+  // transformation), then announce the rename so it is never a surprise.
+  const table = toTableName(name);
+  if (announce) {
+    console.error(
+      `  · '${bare}' is a SQL reserved word; using table_name '${table}' ` +
+        `(Tina4 interpolates table names unquoted). Override with --table-name <name>.`,
+    );
+  }
+  return table;
+}
+
 // ── Resolution surface — the machine-readable envelope every generator ─
 // populates so `--json` can print it and a human run can print the same
 // facts to stderr. See the JSDoc on `printResolution` below for the envelope
@@ -385,10 +450,11 @@ function printResolution(): void {
     lines.push(`  migration  ${b.migration_path}`);
   }
   const reserved = b.transformations.find((t) => t.kind === "reserved_word_pluralize");
-  if (reserved && reserved.from && reserved.override) {
+  if (reserved && reserved.from) {
     lines.push("");
-    lines.push(`  To keep the raw name '${reserved.from}' as the table:`);
-    lines.push(`    tina4nodejs generate ${__resolution.target} ${__resolution.input.name} ${reserved.override}`);
+    lines.push(`  To set the table name yourself:`);
+    lines.push(`    tina4nodejs generate ${__resolution.target} ${__resolution.input.name} --table-name <name>`);
+    lines.push(`  Tina4 interpolates table names unquoted; if you force the reserved '${reserved.from}', you own the quoting in raw SQL.`);
   }
   // v1.1 (ADR-0063): surface the already-populated test_paths[], and the two
   // new arrays (edit_hints, next) when either is non-empty. Sections stay
@@ -591,7 +657,7 @@ export interface GeneratorSpec {
 }
 
 export const GENERATORS: Record<string, GeneratorSpec> = {
-  model:      { handler: generateModel,                     usage: '<Name> [--fields "name:string,price:float"]', summary: "ORM model + matching migration" },
+  model:      { handler: generateModel,                     usage: '<Name> [--fields "name:string,price:float"] [--table-name <name>]', summary: "ORM model + matching migration" },
   route:      { handler: generateRoute,                     usage: "<name> [--model Name] [--public]",            summary: "CRUD route file, secure by default (--public opens writes)" },
   crud:       { handler: generateCrud,                      usage: '<Name> [--fields "..."] [--public]',          summary: "Model + migration + routes + form + view + test" },
   migration:  { handler: (n, f) => generateMigration(n, f, undefined, undefined, !f["no-test"]), usage: "<description>",                                summary: "Timestamped migration file (UP/DOWN)" },
@@ -717,6 +783,7 @@ export async function generate(what: string, name: string, extraArgs: string[] =
     console.error("  Usage: tina4nodejs generate <what> <name> [options]");
     console.error(`  Generators: ${GENERATOR_LIST}`);
     console.error('  Options:    --fields "name:string,price:float"  --model ModelName');
+    console.error("              --table-name <name>       force the model's table name (else derived; reserved words auto-pluralise)");
     console.error("              --public                 open a route's writes (default: secure)");
     console.error('              --every 5m | --cron "…"   service schedule');
     console.error("              --json                    emit machine-readable resolution envelope on stdout");
@@ -833,7 +900,9 @@ export async function generateProgrammatic(
 
 function generateModel(name: string, flags: Record<string, string | boolean>, emitTest = true): void {
   const fields = fieldsOrDefault((flags.fields as string) || "");
-  const table = toTableName(name);
+  // The table is BORN here — announce=true, so a reserved-word rename (Order ->
+  // orders) or a forced-reserved --table-name is said out loud, not silent (#123).
+  const table = resolveTable(name, flags, { announce: true });
   const dir = resolve("src/models");
   ensureDir(dir);
   const path = join(dir, `${name}.ts`);
@@ -922,7 +991,8 @@ function generateRoute(name: string, flags: Record<string, string | boolean>, em
     setResolutionField("file_path", `src/routes/api/${routePath}/get.ts`);
   }
 
-  const table = model ? toTableName(model) : "";
+  // Route targets an EXISTING table — honour --table-name, stay quiet (announce=false).
+  const table = model ? resolveTable(model, flags, { announce: false }) : "";
   // Model import path is RELATIVE to the route file's directory. Files directly
   // under src/routes/api/<name>/ are 3 levels above src/models/; the [id]/ files
   // are one deeper (4 levels).
@@ -1161,7 +1231,9 @@ ${aiFill(`delete_${singular}`, {
 // ── CRUD ────────────────────────────────────────────────────────────
 
 function generateCrud(name: string, flags: Record<string, string | boolean>): void {
-  const table = toTableName(name);
+  // Composite: quiet here (announce=false); the generateModel sub-call below is
+  // the one that announces, so the reserved-word note prints exactly once.
+  const table = resolveTable(name, flags, { announce: false });
   const routeName = toPlural(table);
   const isPublic = Boolean(flags.public);
 
@@ -1221,9 +1293,11 @@ export function generateMigration(
       .replace(/^create_/, "")
       .replace(/^add_/, "")
       .replace(/^drop_/, "");
-    // toTableName also records a `reserved_word_pluralize` transformation
-    // on the resolution when the raw form collides with a SQL reserved word.
-    table = toTableName(raw);
+    // resolveTable honours --table-name and (via toTableName) records the
+    // `reserved_word_pluralize` transformation when the raw form collides with a
+    // SQL reserved word. Quiet (announce=false): a direct migration targets an
+    // existing table, so it does not repeat the model's note.
+    table = resolveTable(raw, flags, { announce: false });
   }
   // Only set table_name / migration_path when THIS is the top-level target.
   // A migration produced by generateModel is a side effect of `generate model`,
@@ -1269,7 +1343,7 @@ export function generateMigration(
       const defaultClause = info.defaultVal !== "NULL" ? ` DEFAULT ${info.defaultVal}` : "";
       colLines.push(`    ${fname} ${info.sql}${defaultClause}`);
     }
-    colLines.push("    created_at TEXT DEFAULT CURRENT_TIMESTAMP");
+    colLines.push("    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP");
 
     upSql =
       `CREATE TABLE IF NOT EXISTS ${table} (\n` +
@@ -1508,7 +1582,7 @@ void test${titleName};
 
 function generateForm(name: string, flags: Record<string, string | boolean>): void {
   const fields = fieldsOrDefault((flags.fields as string) || "");
-  const table = toTableName(name);
+  const table = resolveTable(name, flags, { announce: false });
   const routeName = toPlural(table);
 
   const inputTypes: Record<string, string> = {
@@ -1586,7 +1660,7 @@ function generateForm(name: string, flags: Record<string, string | boolean>): vo
 
 function generateView(name: string, flags: Record<string, string | boolean>): void {
   const fields = fieldsOrDefault((flags.fields as string) || "");
-  const table = toTableName(name);
+  const table = resolveTable(name, flags, { announce: false });
   const routeName = toPlural(table);
 
   const cols = fields.map(([f]) => f);
@@ -2025,8 +2099,8 @@ ${rules}  validator.required("name");   // starter rule (matches the model's def
 // overrides may be static values OR (fake) => value callables) and
 // packages/cli/src/commands/seed.ts (runs each src/seeds/*.ts as a script).
 
-function generateSeeder(name: string, _flags: Record<string, string | boolean>): void {
-  const table = toTableName(name);
+function generateSeeder(name: string, flags: Record<string, string | boolean>): void {
+  const table = resolveTable(name, flags, { announce: false });
   const dir = resolve("src/seeds");
   ensureDir(dir);
   const path = join(dir, `${table}_seeder.ts`);

package/packages/cli/src/commands/lint.ts

@@ -0,0 +1,360 @@
+/**
+ * CLI command: lint — lint the project's source. The FRAMEWORK ships no linter
+ * (a Tina4 app stays zero-dependency); `tina4nodejs lint` uses the project's own
+ * eslint and INSTALLS it as a DEV dependency of the PROJECT on demand when it is
+ * absent — running the command is the consent. Layers, in order:
+ *
+ *   • eslint present (resolvable from the project's node_modules) AND a flat
+ *     config present (`eslint.config.{js,mjs,cjs,ts,mts,cts}`): run it. `--fix`
+ *     runs `eslint --fix` (safe autofixes). eslint reports syntax too, so it is
+ *     the whole pass when present.
+ *   • eslint absent (and NOT `--no-install`): silently `npm i -D eslint
+ *     @eslint/js typescript-eslint` into the PROJECT (dev-only, never the app's
+ *     runtime deps — typescript-eslint pulls its own `typescript` peer), and
+ *     scaffold a minimal flat config at `eslint.config.js` when none exists that
+ *     lints BOTH `.js` and `.ts`, then run eslint. A one-line `  · installing
+ *     eslint...` notice is printed. If npm is missing or the install fails, a
+ *     one-line notice is printed and the command falls through to the baseline.
+ *   • Baseline (zero new dependency): `tsc --noEmit` when a `tsconfig.json`
+ *     exists (the type+syntax check every tina4-nodejs project already owns,
+ *     forced to emit nothing); otherwise stdlib `node --check` over `.js`/`.mjs`/
+ *     `.cjs` files. Used with `--no-install`, or when the install cannot run.
+ *
+ * Contract (identical across all four frameworks): exit 0 = clean, non-zero =
+ * findings; the summary names the tool that ran in `[...]`; `--fix` only
+ * autofixes on the eslint path. Scope is the user's app (`src/` + the entrypoint
+ * `app.ts`/`app.js`), mirroring how `tina4nodejs test` runs the project's own
+ * tests — not the framework's code.
+ *
+ *     tina4nodejs lint             # eslint (installed dev-only on demand), else baseline
+ *     tina4nodejs lint --fix       # eslint --fix
+ *     tina4nodejs lint --no-install # eslint if already present, else the baseline
+ *
+ * Mirrors the Python master's _lint (tina4_python/cli/__init__.py) — ruff there,
+ * eslint here.
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// Source extensions we count as lintable app code. `.d.ts` declaration files are
+// deliberately excluded — they carry no runnable code for `node --check` and are
+// covered by the tsconfig for `tsc`.
+const LINT_EXTENSIONS = [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
+// The subset `node --check` can parse (it does not understand TypeScript).
+const JS_EXTENSIONS = [".js", ".mjs", ".cjs"];
+// Directories a source walk must never descend into.
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+/** True for a lintable source filename (excludes `.d.ts`). */
+function isLintFile(name: string): boolean {
+  if (name.endsWith(".d.ts")) return false;
+  return LINT_EXTENSIONS.some((ext) => name.endsWith(ext));
+}
+
+/** Recursively collect lintable source files under `dir`. */
+function walkSource(dir: string, out: string[]): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (SKIP_DIRS.has(name)) continue;
+    const full = join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      walkSource(full, out);
+    } else if (isLintFile(name)) {
+      out.push(full);
+    }
+  }
+}
+
+/**
+ * The user's app source in lint scope: everything under `src/` plus the
+ * entrypoint (`app.ts`/`app.js`, with `.mts`/`.mjs` variants). Mirrors how the
+ * Python master lints `src/` + `app.py` — the developer's code, never the
+ * framework's.
+ */
+function collectAppFiles(cwd: string): string[] {
+  const files: string[] = [];
+  const srcDir = join(cwd, "src");
+  try {
+    if (statSync(srcDir).isDirectory()) walkSource(srcDir, files);
+  } catch {
+    // no src/ — fall through to the entrypoint check
+  }
+  for (const entry of ["app.ts", "app.mts", "app.js", "app.mjs"]) {
+    const p = join(cwd, entry);
+    try {
+      if (statSync(p).isFile()) files.push(p);
+    } catch {
+      // not present
+    }
+  }
+  return files;
+}
+
+/**
+ * Flat-config filenames to DETECT (any one means the project already configured
+ * eslint, so we never scaffold over it). Legacy `.eslintrc*` is deliberately NOT
+ * detected: eslint 9 ignores it under flat config, so treating it as "configured"
+ * would make eslint run and then error "no flat config found". Flat config only.
+ */
+const ESLINT_FLAT_CONFIGS = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "eslint.config.mts",
+  "eslint.config.cts",
+];
+
+// The filename we SCAFFOLD when a project has no flat config. `.js` (not `.mjs`)
+// per the shared design; every tina4-nodejs project is `"type": "module"`, so a
+// `.js` flat config is ESM and loads as written.
+const ESLINT_SCAFFOLD_FILE = "eslint.config.js";
+
+// The minimal flat config we scaffold — eslint's own recommended rule set PLUS
+// typescript-eslint's recommended (the non-type-checked / syntactic preset, so no
+// tsconfig or parserOptions.project wiring is needed) so BOTH `.js` and `.ts` are
+// linted. Without the typescript-eslint half, eslint reports every `.ts` file
+// "File ignored" and a TS project lints vacuously. IDENTICAL content across the
+// shared design.
+const ESLINT_SCAFFOLD = `import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+export default [js.configs.recommended, ...tseslint.configs.recommended];
+`;
+
+/** Absolute path of an eslint flat config in `cwd`, or null when none exists. */
+function findEslintConfig(cwd: string): string | null {
+  for (const name of ESLINT_FLAT_CONFIGS) {
+    const p = join(cwd, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Resolve a package's bin script FROM the user's project, or null when the
+ * package is not installed there.
+ *
+ * The DIRECT `node_modules/<pkg>/<bin>` path is checked FIRST because it is
+ * immune to the CJS resolver's caches: `runLint` calls this both BEFORE and
+ * AFTER an in-process `npm install`, and Node can negatively-cache the pre-install
+ * "not found" so a post-install `require.resolve` still misses (the same
+ * dir-listing-cache footgun Python's importlib has). `existsSync` hits the real
+ * filesystem every call, so it sees the just-installed bin. The resolver is the
+ * fallback for hoisted / workspace layouts where the package is not a direct
+ * child of `cwd/node_modules`.
+ */
+function resolvePackageBin(cwd: string, pkg: string, binRelative: string): string | null {
+  const direct = join(cwd, "node_modules", pkg, binRelative);
+  if (existsSync(direct)) return direct;
+
+  const require = createRequire(join(cwd, "package.json"));
+  let entry: string;
+  try {
+    entry = require.resolve(pkg);
+  } catch {
+    return null; // not installed / not resolvable from the project
+  }
+  let dir = dirname(entry);
+  for (let i = 0; i < 8; i++) {
+    const pkgJson = join(dir, "package.json");
+    if (existsSync(pkgJson)) {
+      try {
+        if (JSON.parse(readFileSync(pkgJson, "utf-8")).name === pkg) {
+          const bin = join(dir, binRelative);
+          return existsSync(bin) ? bin : null;
+        }
+      } catch {
+        // malformed package.json — keep walking up
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** eslint's runnable bin from the project (`bin/eslint.js`), or null. */
+function resolveEslintBin(cwd: string): string | null {
+  return resolvePackageBin(cwd, "eslint", "bin/eslint.js");
+}
+
+/**
+ * True when `pkg` is installed directly under the project's node_modules (a
+ * `package.json` at `node_modules/<pkg>/`). Direct filesystem check, immune to
+ * the module-resolver cache — the scaffold imports `@eslint/js` and
+ * `typescript-eslint`, so it must not be written until both are on disk.
+ */
+function hasPackage(cwd: string, pkg: string): boolean {
+  return existsSync(join(cwd, "node_modules", ...pkg.split("/"), "package.json"));
+}
+
+/**
+ * Absolute path of `npm` on PATH, or null. Scanned directly (no `which` shell-out)
+ * so it behaves the same on every platform — mirrors bin.ts's findClient().
+ */
+function resolveNpm(): string | null {
+  const windows = process.platform === "win32";
+  const names = windows ? ["npm.cmd", "npm.exe", "npm"] : ["npm"];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = join(dir, name);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        // not there — keep looking
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Lint the project's source. Exits 0 = clean, 1 = findings (parity with the
+ * Python master and with `tina4nodejs test`'s exit-code contract).
+ */
+export function runLint(args: string[]): void {
+  const fix = args.includes("--fix");
+  const noInstall = args.includes("--no-install");
+  const cwd = process.cwd();
+
+  const files = collectAppFiles(cwd);
+  if (files.length === 0) {
+    console.log("  lint: nothing to lint (no src/ or app.ts).");
+    process.exit(0);
+  }
+
+  let eslintBin = resolveEslintBin(cwd);
+  let eslintConfig = findEslintConfig(cwd);
+
+  // ── Silent on-demand bootstrap ──────────────────────────────────────
+  // Running `tina4 lint` is the consent to add eslint as a DEV dependency of the
+  // PROJECT and scaffold a minimal flat config. --no-install opts out (CI /
+  // offline) and falls through to the zero-dependency baseline. We only bootstrap
+  // what is missing, and only scaffold a config once eslint is actually available
+  // to use it (so a failed install never leaves a stray eslint.config.js).
+  if (!noInstall && (!eslintBin || !eslintConfig)) {
+    const npm = resolveNpm();
+    if (!npm) {
+      console.log("  · npm not found — using the zero-dependency baseline.");
+    } else {
+      if (!eslintBin) {
+        console.log("  · installing eslint (npm i -D eslint @eslint/js typescript-eslint)...");
+        const rc = spawnSync(npm, ["install", "-D", "eslint", "@eslint/js", "typescript-eslint"], {
+          cwd,
+          stdio: "inherit",
+        }).status;
+        if (rc === 0) {
+          eslintBin = resolveEslintBin(cwd);
+        } else {
+          console.log("  · could not install eslint — using the zero-dependency baseline.");
+        }
+      }
+      // Scaffold ONLY once all three the config imports are on disk (eslint bin +
+      // @eslint/js + typescript-eslint), so a partial/failed install never leaves
+      // an eslint.config.js that cannot load.
+      if (
+        eslintBin && !eslintConfig &&
+        hasPackage(cwd, "@eslint/js") && hasPackage(cwd, "typescript-eslint")
+      ) {
+        const scaffold = join(cwd, ESLINT_SCAFFOLD_FILE);
+        try {
+          writeFileSync(scaffold, ESLINT_SCAFFOLD, "utf-8");
+          eslintConfig = scaffold;
+          console.log(`  · scaffolded ${ESLINT_SCAFFOLD_FILE} (@eslint/js + typescript-eslint recommended).`);
+        } catch (err) {
+          console.log(
+            `  · could not scaffold ${ESLINT_SCAFFOLD_FILE} (${err instanceof Error ? err.message : String(err)}).`,
+          );
+        }
+      }
+    }
+  }
+
+  // ── eslint: the project's own linter (installed dev-only on demand) ──
+  // Only when a config exists AND eslint resolves from the project. eslint reports
+  // syntax errors too, so when present it is the entire pass.
+  if (eslintBin && eslintConfig) {
+    const label = fix ? "eslint --fix" : "eslint";
+    const eslintArgs = [eslintBin, ...files, ...(fix ? ["--fix"] : [])];
+    const code = spawnSync(process.execPath, eslintArgs, { cwd, stdio: "inherit" }).status ?? 1;
+    if (code !== 0) {
+      console.log(`  ✗ lint failed — ${files.length} file(s) [${label}]`);
+      process.exit(1);
+    }
+    console.log(`  ✓ lint clean — ${files.length} file(s) [${label}]`);
+    process.exit(0);
+  }
+
+  // From here on nothing can autofix — say so once when --fix was asked for.
+  if (fix) {
+    console.log("  · --fix needs eslint — the baseline check has no autofix.");
+  }
+
+  // ── Baseline (TypeScript): the project's own `tsc --noEmit` ──────────
+  // Every tina4-nodejs project ships tsconfig.json + typescript. `--noEmit` forces
+  // a type+syntax check that writes NOTHING (the project's tsconfig may set outDir,
+  // so this must never emit). tsc reports syntax errors too. Run from cwd so tsc
+  // reads THIS tsconfig.json; diagnostics stream straight through.
+  const hasTsconfig = existsSync(join(cwd, "tsconfig.json"));
+  const tscBin = hasTsconfig ? resolvePackageBin(cwd, "typescript", "bin/tsc") : null;
+  if (tscBin) {
+    const code = spawnSync(process.execPath, [tscBin, "--noEmit"], { cwd, stdio: "inherit" }).status ?? 1;
+    if (code !== 0) {
+      console.log(`  ✗ lint failed — ${files.length} file(s) [tsc]`);
+      process.exit(1);
+    }
+    console.log(`  ✓ lint clean — ${files.length} file(s) [tsc]`);
+    process.exit(0);
+  }
+
+  // ── Baseline (plain JS): stdlib `node --check` over .js/.mjs/.cjs ────
+  // Ships with node — zero dependency. A full syntax parse that never runs the
+  // code. TypeScript files are out of its reach (they belong to the tsc path).
+  const jsFiles = files.filter((f) => JS_EXTENSIONS.some((ext) => f.endsWith(ext)));
+  if (jsFiles.length === 0) {
+    console.log(
+      "  lint: no JavaScript files to check — add tsconfig.json + typescript to type-check .ts files.",
+    );
+    process.exit(0);
+  }
+
+  let syntaxErrors = 0;
+  for (const file of jsFiles) {
+    const result = spawnSync(process.execPath, ["--check", file], { cwd, encoding: "utf-8" });
+    if ((result.status ?? 1) !== 0) {
+      const stderr = (result.stderr || "").trim();
+      // node --check ends its stderr with a `SyntaxError: ...` line — surface it.
+      const detail =
+        stderr
+          .split("\n")
+          .reverse()
+          .find((line) => line.includes("Error:")) || "syntax error";
+      console.log(`  ✗ ${relative(cwd, file)}: ${detail.trim()}`);
+      syntaxErrors++;
+    }
+  }
+
+  if (syntaxErrors > 0) {
+    console.log(
+      `  ✗ lint failed — ${syntaxErrors} syntax error(s) in ${jsFiles.length} file(s) [node --check]`,
+    );
+    process.exit(1);
+  }
+  console.log(`  ✓ lint clean — ${jsFiles.length} file(s) [node --check]`);
+  process.exit(0);
+}