turbine-orm 0.61.0 → 0.62.0

package/dist/cli/config.js

@@ -7,6 +7,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { PASSWORD_QUERY_PARAM_PATTERN } from './ui.js';
 /**
  * Heuristic: does a configured `schema` value actually look like a schema FILE
  * path rather than a Postgres schema name? `schema` is the Postgres namespace
@@ -190,9 +191,79 @@ export function resolveSeedFile(config, cwd = process.cwd()) {
 // ---------------------------------------------------------------------------
 // Config file template (for `turbine init`)
 // ---------------------------------------------------------------------------
+/**
+ * Does this connection string carry a password?
+ *
+ * `turbine init --url` used to inline whatever it was given straight into
+ * `turbine.config.ts`, a file projects commit, so the documented one-liner
+ * (`turbine init --url postgres://user:PASSWORD@host/db`) committed a live
+ * database password. Everything that decides between "inline the string" and
+ * "read `process.env.DATABASE_URL`" asks this function, so there is exactly one
+ * definition of "this value is a secret".
+ *
+ * Three spellings carry a password, and libpq (and `pg-connection-string`,
+ * which is what `pg` actually parses with) accepts all three:
+ *
+ *  1. URL userinfo: `postgres://user:pass@host/db`.
+ *  2. URL query parameter: `postgres://user@host/db?password=pass`, and its
+ *     siblings such as `?sslpassword=`. This one was missed, on the reasoning
+ *     that a successful `new URL` ruled out the keyword form below, which is
+ *     true and irrelevant: the secret was in the query string.
+ *  3. libpq keyword form: `host=... password=...` (also `sslpassword=`), which
+ *     is not a URL at all.
+ *
+ * The query-parameter test reuses `PASSWORD_QUERY_PARAM_PATTERN`, the very
+ * regex `redactUrl` redacts with, so a spelling the terminal output hides can
+ * never be a spelling this function calls safe to commit. `pg-connection-string`
+ * itself would be the ideal oracle, but it is only a TRANSITIVE dependency (of
+ * `pg`), and importing an undeclared package would break on any strict,
+ * non-hoisting installer. Detection stays self-contained.
+ *
+ * @internal exported for tests.
+ */
+export function connectionStringHasPassword(connectionString) {
+    const value = connectionString.trim();
+    if (!value)
+        return false;
+    try {
+        const parsed = new URL(value);
+        // An empty password ("postgres://user@host/db", "?password=") is not a
+        // secret. decodeURIComponent is deliberately NOT applied: presence is all
+        // we need, and a percent-encoded value is still a non-empty one.
+        if (parsed.password !== '')
+            return true;
+        for (const match of value.matchAll(new RegExp(PASSWORD_QUERY_PARAM_PATTERN, 'gi'))) {
+            if (match[2] !== '')
+                return true;
+        }
+        // A string libpq parses as a URI is never re-parsed as the keyword form, so
+        // the check below genuinely cannot apply here.
+        return false;
+    }
+    catch {
+        // Not a URL: fall through to the libpq keyword form.
+    }
+    // A keyword whose name ends in `password` (`password`, `sslpassword`) with a
+    // non-empty value, at the start of the string or after whitespace.
+    return /(^|\s)[^\s=]*password\s*=\s*\S/i.test(value);
+}
+/**
+ * The `turbine.config.ts` scaffold.
+ *
+ * A password-bearing `connectionString` is NEVER inlined: the emitted config
+ * reads `process.env.DATABASE_URL` instead, and `turbine init` scaffolds the
+ * `.env` that holds the real value. The refusal lives here rather than at the
+ * call site so no future caller can reintroduce the leak by passing the raw
+ * `--url` through.
+ */
 export function configTemplate(connectionString) {
-    const _url = connectionString ?? 'process.env.DATABASE_URL';
-    const urlLine = connectionString ? `  url: '${connectionString}',` : `  url: process.env.DATABASE_URL,`;
+    const inlineUrl = connectionString && !connectionStringHasPassword(connectionString) ? connectionString : undefined;
+    // Single quotes are the string delimiter in the emitted TS, so a connection
+    // string containing one would otherwise produce a config file that does not
+    // parse (a password-free URL can still carry a quote in a query parameter).
+    const urlLine = inlineUrl
+        ? `  url: '${inlineUrl.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}',`
+        : `  url: process.env.DATABASE_URL,`;
     return `import type { TurbineCliConfig } from 'turbine-orm/cli';
 
 /**

package/dist/cli/index.d.ts

@@ -67,6 +67,12 @@ export interface CliArgs {
     yes?: boolean;
     /** `init --skip-schema`: don't scaffold the schema file. */
     skipSchema?: boolean;
+    /**
+     * `init --with-schema`: scaffold the starter schema file even when the
+     * database already has tables. The escape hatch for a code-first project
+     * bootstrapping against a populated database.
+     */
+    withSchema?: boolean;
     /** `init --skip-seed`: don't scaffold the seed file or offer to run it. */
     skipSeed?: boolean;
     /** `init --skip-push`: don't offer to push the schema to the database. */
@@ -241,7 +247,9 @@ export type InitStepId = 'config' | 'schema' | 'seed-file' | 'push' | 'generate'
 /** What the planner decided to do with a step. */
 export type InitStepAction = 'run' | 'prompt' | 'skip';
 /** Why a step was skipped (only set when `action` is `skip`). */
-export type InitStepSkipReason = 'exists' | 'flag' | 'no-url' | 'unreachable' | 'no-seed-file' | 'non-interactive' | 'default-no';
+export type InitStepSkipReason = 'exists' | 'flag' | 'no-url' | 'unreachable' | 'no-seed-file' | 'non-interactive' | 'default-no'
+/** The database already has tables, so an EMPTY code-first schema file is wrong. */
+ | 'db-has-tables';
 export interface InitPlanStep {
     id: InitStepId;
     action: InitStepAction;
@@ -256,6 +264,12 @@ export interface InitPlanState {
     seedFileExists: boolean;
     hasUrl: boolean;
     dbReachable: boolean;
+    /**
+     * The reachable database already contains user tables. Optional: absent means
+     * "not probed / unknown", which keeps the pre-0.62 plan for every caller that
+     * does not supply it.
+     */
+    dbHasTables?: boolean;
 }
 /** Effective flags for the planner. */
 export interface InitPlanFlags {
@@ -263,6 +277,11 @@ export interface InitPlanFlags {
     force: boolean;
     interactive: boolean;
     skipSchema: boolean;
+    /**
+     * `--with-schema`: scaffold the schema file even against a database that
+     * already has tables. Loses to `skipSchema`, which is the explicit "don't".
+     */
+    withSchema?: boolean;
     skipSeed: boolean;
     skipPush: boolean;
     skipGenerate: boolean;
@@ -284,6 +303,63 @@ export interface InitPlanFlags {
  * skipped when there is no URL or the database is unreachable.
  */
 export declare function planInitSteps(state: InitPlanState, flags: InitPlanFlags): InitPlanStep[];
+/** What the secret-handling scaffold decided to do with one file. */
+export type EnvScaffoldAction = 'created' | 'appended' | 'unchanged';
+/** Detected state of the three files the scaffold touches (all IO by the caller). */
+export interface EnvScaffoldState {
+    envExists: boolean;
+    /** `.env` already assigns DATABASE_URL (their value wins; we never rewrite it). */
+    envHasDatabaseUrl: boolean;
+    envExampleExists: boolean;
+    gitignoreExists: boolean;
+    gitignoreIgnoresEnv: boolean;
+}
+export interface EnvScaffoldPlan {
+    env: EnvScaffoldAction;
+    envExample: EnvScaffoldAction;
+    gitignore: EnvScaffoldAction;
+}
+/**
+ * Does this `.gitignore` text already ignore `.env`?
+ *
+ * Line-based rather than a substring search: a `.gitignore` mentioning
+ * `.env.example` (a very common line, since the example file is the one you DO
+ * commit) contains the text `.env` while ignoring nothing of the kind, and
+ * treating that as covered is how the password would stay committable.
+ * Negations (`!.env`) are honored as a later line overriding an earlier one,
+ * exactly as git resolves them.
+ *
+ * @internal exported for tests.
+ */
+export declare function gitignoreIgnoresEnv(content: string): boolean;
+/**
+ * Decide what the `--url`-carries-a-password scaffold writes. Pure, so the whole
+ * matrix (fresh project, existing `.env`, existing `.gitignore`, re-run) is
+ * testable without a filesystem.
+ *
+ * An existing `DATABASE_URL` in `.env` is NEVER rewritten: it is the value the
+ * project already runs against, and silently repointing it at the `--url` from
+ * one command line is a worse failure than printing a notice.
+ *
+ * @internal exported for tests.
+ */
+export declare function planEnvScaffold(state: EnvScaffoldState): EnvScaffoldPlan;
+/**
+ * Move a password-bearing `--url` out of `turbine.config.ts` and into `.env`.
+ *
+ * `turbine init --url postgres://user:PASSWORD@host/db` is the documented
+ * one-liner, and it used to inline that string verbatim into a file projects
+ * commit, with no `.gitignore` written at all. The config template now refuses
+ * to inline a secret (see `configTemplate`), so the real value has to land
+ * somewhere the config can read it from: this writes `.env`, scaffolds the
+ * committable `.env.example` next to it, and makes sure `.gitignore` covers
+ * `.env` BEFORE the secret is on disk long enough to be staged.
+ *
+ * Paths are cwd-relative, exactly like the rest of the init scaffold.
+ *
+ * @internal exported for tests.
+ */
+export declare function scaffoldEnvForUrl(url: string): EnvScaffoldPlan;
 /**
  * The one-line connection heads-up `turbine init` opens with.
  *
@@ -366,3 +442,11 @@ export declare function getSeedExecutionPlan(seedFile: string): SeedExecutionPla
  * `--allow-remote`. Accepts IPv4, IPv6, and the common bracket form.
  */
 export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Print `<command> --help` for a command that has real help, returning whether
+ * one existed. Falling through to the GLOBAL help is the failure mode this map
+ * guards against, and it is silent, so the coverage is asserted in tests.
+ *
+ * @internal exported for tests.
+ */
+export declare function showSubcommandHelp(command: string): boolean;