@hasna/shortlinks 0.1.21 → 0.1.23

package/README.md

@@ -2,7 +2,7 @@
 
 CLI-only shortlink management for custom domains.
 
-`shortlinks` creates Bitly-style short URLs, supports multiple domains, records click analytics, can run a tiny redirect server, and includes helper commands for Cloudflare DNS/Workers, `@hasna/domains`, and `@hasna/cloud` sync. Production serving can run directly against the shared RDS database with `--cloud`; local SQLite is only for explicit local/offline use.
+`shortlinks` creates Bitly-style short URLs, supports multiple domains, records click analytics, can run a tiny redirect server, and includes helper commands for Cloudflare DNS/Workers and `@hasna/domains`. It defaults to local SQLite and can serve from an app-owned PostgreSQL database when `HASNA_SHORTLINKS_STORE=postgres` and `HASNA_SHORTLINKS_DATABASE_URL` are configured.
 
 [![npm](https://img.shields.io/npm/v/@hasna/shortlinks)](https://www.npmjs.com/package/@hasna/shortlinks)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -64,7 +64,6 @@ shortlinks link enable home --domain has.na
 shortlinks stats home --domain has.na
 
 shortlinks serve --port 8787
-shortlinks serve --cloud --port 8787
 shortlinks doctor
 ```
 
@@ -125,36 +124,32 @@ shortlinks domain buy new-short-domain.ai --dry-run
 
 This package does not install or call any removed `connect-*` packages.
 
-## Cloud Sync
+## PostgreSQL Runtime
 
-`shortlinks` is compatible with `@hasna/cloud` conventions:
+Production serving can use a shortlinks-owned PostgreSQL database without any shared table-sync package:
 
 ```bash
-cloud setup
-shortlinks cloud migrate
-shortlinks cloud push
-shortlinks cloud pull
-shortlinks cloud sync
-```
-
-The cloud database service name is `shortlinks`.
-Use direct RDS mode for production and live management:
+export HASNA_SHORTLINKS_STORE=postgres
+export HASNA_SHORTLINKS_DATABASE_URL=postgres://shortlinks:password@db.example.com:5432/shortlinks
+export HASNA_SHORTLINKS_DATABASE_SSL=true
 
-```bash
-shortlinks --cloud create https://example.com
-shortlinks --cloud link list
-shortlinks serve --cloud --host 127.0.0.1 --port 8787
+shortlinks postgres status
+shortlinks postgres plan --schema-sql
+shortlinks postgres migrate
+shortlinks --store postgres serve --host 127.0.0.1 --port 8787 --default-host has.na
 ```
 
+The canonical production runtime secret path is `hasna/xyz/opensource/shortlinks/prod/postgres`. Use the URL environment variables above rather than writing shared runtime config files into the shortlinks data directory.
+
 ## AWS Origin
 
 For an apex domain that needs stable A records, `infra/aws-ec2-user-data.sh` bootstraps a small EC2 redirect origin with:
 
 - `@hasna/shortlinks` installed through Bun
-- direct reads and click writes against the `shortlinks` RDS database through `@hasna/cloud`
+- direct reads and click writes against the app-owned `shortlinks` PostgreSQL database
 - Caddy terminating HTTPS and proxying to `shortlinks serve`
 
-The script reads the RDS password from AWS Secrets Manager through the instance role; it does not contain secret values.
+The script reads the connection settings from AWS Secrets Manager through the instance role; it does not contain secret values.
 
 ## Development
 

package/dist/cli/index.js

@@ -3271,7 +3271,8 @@ import { mkdirSync as mkdirSync2 } from "fs";
 import { dirname as dirname2 } from "path";
 
 // src/config.ts
-import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync as existsSync2, linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { randomBytes } from "crypto";
 import { homedir as homedir2 } from "os";
 import { dirname, join as join2, resolve } from "path";
 var SERVICE_NAME = "shortlinks";
@@ -3287,6 +3288,9 @@ function ensureDataDir() {
 function getConfigPath() {
   return join2(ensureDataDir(), "config.json");
 }
+function getClickSaltPath() {
+  return join2(ensureDataDir(), "click-salt");
+}
 function getDatabasePath(explicitPath) {
   if (explicitPath)
     return resolve(explicitPath);
@@ -3294,6 +3298,51 @@ function getDatabasePath(explicitPath) {
     return resolve(process.env.SHORTLINKS_DB);
   return join2(ensureDataDir(), `${SERVICE_NAME}.db`);
 }
+function readClickSaltFile(path) {
+  try {
+    const saved = readFileSync(path, "utf-8").trim();
+    return saved || null;
+  } catch {
+    return null;
+  }
+}
+function clickSaltError(path, error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  return new Error(`Could not initialize click salt at ${path}. Set SHORTLINKS_CLICK_SALT or fix data directory permissions. ${detail}`);
+}
+function getClickSalt() {
+  const explicit = process.env.SHORTLINKS_CLICK_SALT?.trim();
+  if (explicit)
+    return explicit;
+  const path = getClickSaltPath();
+  const saved = readClickSaltFile(path);
+  if (saved)
+    return saved;
+  const generated = randomBytes(32).toString("hex");
+  const tempPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tempPath, `${generated}
+`, { flag: "wx", mode: 384 });
+    try {
+      linkSync(tempPath, path);
+      return generated;
+    } catch (error) {
+      const winner = readClickSaltFile(path);
+      if (winner)
+        return winner;
+      throw clickSaltError(path, error);
+    } finally {
+      try {
+        unlinkSync(tempPath);
+      } catch {}
+    }
+  } catch (error) {
+    const winner = readClickSaltFile(path);
+    if (winner)
+      return winner;
+    throw clickSaltError(path, error);
+  }
+}
 function loadConfig() {
   const path = getConfigPath();
   if (!existsSync2(path))
@@ -3465,13 +3514,13 @@ import { hostname } from "os";
 import { join as join3 } from "path";
 
 // src/slug.ts
-import { randomBytes } from "crypto";
+import { randomBytes as randomBytes2 } from "crypto";
 var SLUG_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
 var DEFAULT_SLUG_LENGTH = 7;
 function randomToken(length = DEFAULT_SLUG_LENGTH) {
   if (length < 1 || length > 128)
     throw new Error("Token length must be between 1 and 128.");
-  const bytes = randomBytes(length);
+  const bytes = randomBytes2(length);
   let out = "";
   for (let i = 0;i < length; i += 1) {
     out += SLUG_ALPHABET[bytes[i] % SLUG_ALPHABET.length];
@@ -3791,13 +3840,178 @@ class ShortlinksStore {
     throw new Error("Could not generate an unused slug after 32 attempts.");
   }
   hashIp(ip) {
-    const salt = process.env.SHORTLINKS_CLICK_SALT || "shortlinks-local";
-    return createHash("sha256").update(`${salt}:${ip}`).digest("hex");
+    return createHash("sha256").update(`${getClickSalt()}:${ip}`).digest("hex");
   }
 }
 
 // src/pg-store.ts
 import { createHash as createHash2 } from "crypto";
+
+// src/runtime.ts
+var SHORTLINKS_RUNTIME_ENV = {
+  store: "HASNA_SHORTLINKS_STORE",
+  databaseUrl: "HASNA_SHORTLINKS_DATABASE_URL",
+  databaseSsl: "HASNA_SHORTLINKS_DATABASE_SSL"
+};
+var SHORTLINKS_RUNTIME_FALLBACK_ENV = {
+  store: "SHORTLINKS_STORE",
+  databaseUrl: "SHORTLINKS_DATABASE_URL",
+  databaseSsl: "SHORTLINKS_DATABASE_SSL"
+};
+var CANONICAL_SHORTLINKS_POSTGRES_CLUSTER = "hasna-xyz-infra-apps-prod-postgres";
+var CANONICAL_SHORTLINKS_POSTGRES_DATABASE = "shortlinks";
+var CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH = "hasna/xyz/opensource/shortlinks/prod/postgres";
+function getCanonicalShortlinksPostgresConfig() {
+  return {
+    cluster: CANONICAL_SHORTLINKS_POSTGRES_CLUSTER,
+    database: CANONICAL_SHORTLINKS_POSTGRES_DATABASE,
+    runtimeSecretPath: CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH,
+    primaryEnv: SHORTLINKS_RUNTIME_ENV.databaseUrl,
+    fallbackEnv: SHORTLINKS_RUNTIME_FALLBACK_ENV.databaseUrl
+  };
+}
+function parseShortlinksStoreMode(value) {
+  const normalized = clean(value)?.toLowerCase();
+  if (!normalized)
+    return "local";
+  if (normalized === "local" || normalized === "postgres")
+    return normalized;
+  if (normalized === "pg")
+    return "postgres";
+  throw new Error(`${SHORTLINKS_RUNTIME_ENV.store} must be local or postgres`);
+}
+function getShortlinksStoreMode(env2 = process.env) {
+  return parseShortlinksStoreMode(readRuntimeEnv(env2, "store").value);
+}
+function getShortlinksDatabaseUrl(env2 = process.env) {
+  return readRuntimeEnv(env2, "databaseUrl").value;
+}
+function getShortlinksDatabaseSsl(env2 = process.env) {
+  return parseBoolean(readRuntimeEnv(env2, "databaseSsl").value, true);
+}
+function getShortlinksRuntimeEnvName(env2, key) {
+  const primary = SHORTLINKS_RUNTIME_ENV[key];
+  if (clean(env2[primary]))
+    return primary;
+  return SHORTLINKS_RUNTIME_FALLBACK_ENV[key];
+}
+function loadShortlinksRuntimeConfig(env2 = process.env) {
+  const mode = getShortlinksStoreMode(env2);
+  const databaseUrl = getShortlinksDatabaseUrl(env2);
+  return {
+    service: "shortlinks",
+    mode,
+    ...databaseUrl ? {
+      database: {
+        provider: "postgres",
+        url: databaseUrl,
+        ssl: getShortlinksDatabaseSsl(env2)
+      }
+    } : {}
+  };
+}
+function assertShortlinksPostgresConfig(config) {
+  if (config.mode !== "postgres")
+    return;
+  if (!config.database?.url) {
+    throw new Error(`${SHORTLINKS_RUNTIME_ENV.databaseUrl} is required when ${SHORTLINKS_RUNTIME_ENV.store}=postgres`);
+  }
+}
+function getShortlinksRuntimeStatus(env2 = process.env) {
+  const issues = [];
+  const warnings = [];
+  let config;
+  try {
+    config = loadShortlinksRuntimeConfig(env2);
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+    config = { service: "shortlinks", mode: "local" };
+  }
+  try {
+    assertShortlinksPostgresConfig(config);
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+  }
+  if (config.mode === "local" && config.database?.url) {
+    warnings.push(`${SHORTLINKS_RUNTIME_ENV.store}=local ignores configured Postgres database settings`);
+  }
+  return {
+    ok: issues.length === 0,
+    service: "shortlinks",
+    mode: config.mode,
+    local_default: config.mode === "local",
+    postgres_enabled: config.mode === "postgres",
+    database: {
+      configured: Boolean(config.database?.url),
+      provider: config.database?.provider ?? null,
+      redacted_url: redactDatabaseUrl(config.database?.url),
+      ssl: config.database?.ssl ?? null
+    },
+    env: runtimeEnvStatus(env2),
+    canonical: getCanonicalShortlinksPostgresConfig(),
+    issues,
+    warnings,
+    no_network: true
+  };
+}
+function redactDatabaseUrl(value) {
+  if (!value)
+    return null;
+  try {
+    const url = new URL(value);
+    if (url.username)
+      url.username = "***";
+    if (url.password)
+      url.password = "***";
+    for (const key of Array.from(url.searchParams.keys())) {
+      if (isSensitiveQueryKey(key))
+        url.searchParams.set(key, "***");
+    }
+    return url.toString();
+  } catch {
+    return "(redacted)";
+  }
+}
+function runtimeEnvStatus(env2) {
+  return Object.fromEntries(Object.entries(SHORTLINKS_RUNTIME_ENV).map(([key, name]) => {
+    const activeName = getShortlinksRuntimeEnvName(env2, key);
+    return [
+      key,
+      {
+        name,
+        active_name: activeName,
+        configured: Boolean(clean(env2[activeName]))
+      }
+    ];
+  }));
+}
+function readRuntimeEnv(env2, key) {
+  const primary = SHORTLINKS_RUNTIME_ENV[key];
+  const primaryValue = clean(env2[primary]);
+  if (primaryValue)
+    return { name: primary, value: primaryValue };
+  const fallback = SHORTLINKS_RUNTIME_FALLBACK_ENV[key];
+  return { name: fallback, value: clean(env2[fallback]) };
+}
+function parseBoolean(value, fallback) {
+  const normalized = clean(value)?.toLowerCase();
+  if (!normalized)
+    return fallback;
+  if (["1", "true", "yes", "on"].includes(normalized))
+    return true;
+  if (["0", "false", "no", "off"].includes(normalized))
+    return false;
+  throw new Error(`${SHORTLINKS_RUNTIME_ENV.databaseSsl} must be true or false`);
+}
+function isSensitiveQueryKey(key) {
+  return /(?:^|[_-])(pass(?:word)?|pwd|secret|token|credential|auth|api[_-]?key|access[_-]?key)(?:$|[_-])/i.test(key);
+}
+function clean(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+// src/pg-store.ts
 function parseJsonObject3(value) {
   if (!value)
     return {};
@@ -3810,6 +4024,47 @@ function parseJsonObject3(value) {
     return {};
   }
 }
+async function loadPgPool() {
+  const importer = new Function("specifier", "return import(specifier)");
+  const module = await importer("pg");
+  return module.Pool;
+}
+function toPostgresSql(sql) {
+  let index = 0;
+  return sql.replace(/\?/g, () => `$${++index}`);
+}
+function createPgPoolConfig(connectionString, options = {}) {
+  const ssl = options.ssl ?? true;
+  return {
+    connectionString,
+    ...ssl ? { ssl: { rejectUnauthorized: true } } : { ssl: false }
+  };
+}
+
+class PgPoolAdapter {
+  pool;
+  constructor(pool) {
+    this.pool = pool;
+  }
+  static async create(connectionString, options = {}) {
+    const Pool = await loadPgPool();
+    return new PgPoolAdapter(new Pool(createPgPoolConfig(connectionString, options)));
+  }
+  async get(sql, ...params) {
+    const result = await this.pool.query(toPostgresSql(sql), params);
+    return result.rows[0] ?? null;
+  }
+  async all(sql, ...params) {
+    const result = await this.pool.query(toPostgresSql(sql), params);
+    return result.rows;
+  }
+  async run(sql, ...params) {
+    return this.pool.query(toPostgresSql(sql), params);
+  }
+  async close() {
+    await this.pool.end();
+  }
+}
 function toIsoString(value) {
   if (value instanceof Date)
     return value.toISOString();
@@ -3878,13 +4133,15 @@ class PgShortlinksStore {
   constructor(pg) {
     this.pg = pg;
   }
-  static async fromConnectionString(connectionString) {
-    const { PgAdapterAsync } = await import("@hasna/cloud");
-    return new PgShortlinksStore(new PgAdapterAsync(connectionString));
+  static async fromConnectionString(connectionString, options = {}) {
+    return new PgShortlinksStore(await PgPoolAdapter.create(connectionString, options));
   }
-  static async fromCloud(service = "shortlinks") {
-    const { getConnectionString } = await import("@hasna/cloud");
-    return PgShortlinksStore.fromConnectionString(getConnectionString(service));
+  static async fromEnv(env2 = process.env) {
+    const connectionString = getShortlinksDatabaseUrl(env2);
+    if (!connectionString) {
+      throw new Error("HASNA_SHORTLINKS_DATABASE_URL is required when shortlinks uses the postgres store");
+    }
+    return PgShortlinksStore.fromConnectionString(connectionString, { ssl: getShortlinksDatabaseSsl(env2) });
   }
   async close() {
     await this.pg.close?.();
@@ -4100,8 +4357,7 @@ class PgShortlinksStore {
     };
   }
   hashIp(ip) {
-    const salt = process.env.SHORTLINKS_CLICK_SALT || "shortlinks-cloud";
-    return createHash2("sha256").update(`${salt}:${ip}`).digest("hex");
+    return createHash2("sha256").update(`${getClickSalt()}:${ip}`).digest("hex");
   }
   async generateAvailableSlug(domainId, length) {
     for (let attempt = 0;attempt < 32; attempt += 1) {
@@ -4115,6 +4371,52 @@ class PgShortlinksStore {
     throw new Error("Could not generate an unused slug after 32 attempts.");
   }
 }
+async function applyPostgresMigrations(connectionString, migrations, options = {}) {
+  const Pool = await loadPgPool();
+  const pool = new Pool(createPgPoolConfig(connectionString, options));
+  const client = await pool.connect();
+  const run = (sql, ...params) => client.query(toPostgresSql(sql), params);
+  const get = async (sql, ...params) => {
+    const result = await run(sql, ...params);
+    return result.rows[0] ?? null;
+  };
+  const applied = [];
+  const skipped = [];
+  try {
+    await run("BEGIN");
+    await run(`
+      SELECT pg_advisory_xact_lock(hashtext(?))
+    `, "shortlinks:migrations");
+    await run(`
+      CREATE TABLE IF NOT EXISTS _shortlinks_migrations (
+        id INTEGER PRIMARY KEY,
+        service TEXT NOT NULL DEFAULT 'shortlinks',
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )
+    `);
+    for (let i = 0;i < migrations.length; i += 1) {
+      const id = i + 1;
+      const existing = await get("SELECT id FROM _shortlinks_migrations WHERE id = ? LIMIT 1", id);
+      if (existing) {
+        skipped.push(id);
+        continue;
+      }
+      await run(migrations[i]);
+      await run("INSERT INTO _shortlinks_migrations (id, service, applied_at) VALUES (?, ?, now())", id, "shortlinks");
+      applied.push(id);
+    }
+    await run("COMMIT");
+    return { service: "shortlinks", applied, skipped };
+  } catch (error) {
+    try {
+      await run("ROLLBACK");
+    } catch {}
+    throw error;
+  } finally {
+    client.release();
+    await pool.end();
+  }
+}
 
 // src/server.ts
 var REDIRECT_ALLOW_HEADER = "GET, HEAD";
@@ -4531,14 +4833,20 @@ function withStore(fn) {
 }
 function storeMode() {
   const opts = program2.opts();
-  const value = String(opts.cloud ? "cloud" : opts.store || process.env.SHORTLINKS_STORE || "local").toLowerCase();
-  if (value !== "local" && value !== "cloud")
-    throw new Error(`Unknown store mode: ${value}`);
-  return value;
+  return parseShortlinksStoreMode(opts.store || process.env.HASNA_SHORTLINKS_STORE || process.env.SHORTLINKS_STORE || "local");
+}
+function runtimeEnv() {
+  const opts = program2.opts();
+  return opts.store ? { ...process.env, HASNA_SHORTLINKS_STORE: opts.store } : process.env;
+}
+function localStatsIfDatabaseExists(dbPath) {
+  if (!existsSync4(dbPath))
+    return null;
+  return withStore((store) => store.totalStats());
 }
 async function withRuntimeStore(fn) {
-  if (storeMode() === "cloud") {
-    const store2 = await PgShortlinksStore.fromCloud("shortlinks");
+  if (storeMode() === "postgres") {
+    const store2 = await PgShortlinksStore.fromEnv();
     try {
       return await fn(store2);
     } finally {
@@ -4559,7 +4867,7 @@ function commandExists(command) {
   const result = spawnSync3("which", [command], { encoding: "utf-8" });
   return result.status === 0;
 }
-program2.name("shortlinks").description("CLI-only shortlink manager with custom domains, click tracking, Cloudflare helpers, and cloud sync").version(getPackageVersion()).option("--db <path>", "SQLite database path").option("--store <mode>", "Data store mode: cloud or local", process.env.SHORTLINKS_STORE || "local").option("--cloud", "Use the shortlinks PostgreSQL database directly").option("-j, --json", "Output JSON for agents and scripts");
+program2.name("shortlinks").description("CLI-only shortlink manager with custom domains, click tracking, Cloudflare helpers, and app-owned Postgres runtime support").version(getPackageVersion()).option("--db <path>", "SQLite database path").option("--store <mode>", "Data store mode: local or postgres", process.env.HASNA_SHORTLINKS_STORE || process.env.SHORTLINKS_STORE || "local").option("-j, --json", "Output JSON for agents and scripts");
 program2.command("init").description("Initialize local shortlinks storage").option("--domain <hostname>", "Add a default shortlink domain").option("--public-base-url <url>", "Public URL base for generated links").option("-j, --json", "Output JSON").action(async (opts) => {
   try {
     const result = await withRuntimeStore(async (store) => {
@@ -4819,9 +5127,9 @@ program2.command("stats [slug]").description("Show overall stats or stats for a
     handleError(error);
   }
 });
-program2.command("serve").description("Run the redirect server that records clicks").option("--host <host>", "Bind host", "127.0.0.1").option("--port <port>", "Port", "8787").option("--default-host <hostname>", "Fallback host if the request has no Host header").option("--cloud", "Serve directly from the shortlinks PostgreSQL database").action(async (opts) => {
+program2.command("serve").description("Run the redirect server that records clicks").option("--host <host>", "Bind host", "127.0.0.1").option("--port <port>", "Port", "8787").option("--default-host <hostname>", "Fallback host if the request has no Host header").action(async (opts) => {
   try {
-    const store = opts.cloud || storeMode() === "cloud" ? await PgShortlinksStore.fromCloud("shortlinks") : undefined;
+    const store = storeMode() === "postgres" ? await PgShortlinksStore.fromEnv() : undefined;
     const server = serveShortlinks({
       store,
       dbPath: program2.opts().db,
@@ -4829,7 +5137,7 @@ program2.command("serve").description("Run the redirect server that records clic
       port: Number(opts.port),
       defaultHost: opts.defaultHost
     });
-    const mode = store ? "cloud" : "local";
+    const mode = store ? "postgres" : "local";
     console.log(source_default.green(`shortlinks redirect server listening on http://${server.hostname}:${server.port} (${mode})`));
   } catch (error) {
     handleError(error);
@@ -4875,65 +5183,68 @@ cfCmd.command("dns <hostname>").description("Create or update the Cloudflare CNA
     handleError(error);
   }
 });
-var cloudCmd = program2.command("cloud").description("@hasna/cloud sync helpers");
-cloudCmd.command("migrate").description("Apply shortlinks PostgreSQL migrations").option("--connection-string <url>", "PostgreSQL connection string").option("-j, --json", "Output JSON").action(async (opts) => {
+var postgresCmd = program2.command("postgres").description("Shortlinks-owned PostgreSQL runtime helpers");
+postgresCmd.command("migrate").description("Apply shortlinks PostgreSQL migrations").option("--connection-string <url>", "PostgreSQL connection string").option("--no-ssl", "Disable PostgreSQL TLS only for local development").option("--dry-run", "Show migration settings without opening a network connection").option("-j, --json", "Output JSON").action(async (opts) => {
   try {
-    const { getConnectionString, applyPgMigrations } = await import("@hasna/cloud");
-    const conn = opts.connectionString || getConnectionString("shortlinks");
-    const result = await applyPgMigrations(conn, PG_MIGRATIONS, "shortlinks");
+    const conn = opts.connectionString || getShortlinksDatabaseUrl();
+    if (!conn)
+      throw new Error("HASNA_SHORTLINKS_DATABASE_URL or --connection-string is required.");
+    const ssl = opts.ssl === false ? false : getShortlinksDatabaseSsl();
+    if (opts.dryRun) {
+      const result2 = {
+        service: "shortlinks",
+        dry_run: true,
+        no_network: true,
+        database: {
+          configured: true,
+          redacted_url: redactDatabaseUrl(conn),
+          ssl
+        },
+        migrations: PG_MIGRATIONS.length
+      };
+      print2(result2, opts, () => console.log(JSON.stringify(result2, null, 2)));
+      return;
+    }
+    const result = await applyPostgresMigrations(conn, PG_MIGRATIONS, { ssl });
     print2(result, opts, () => console.log(JSON.stringify(result, null, 2)));
   } catch (error) {
     handleError(error);
   }
 });
-async function syncCloud(direction, opts) {
-  const {
-    getCloudConfig,
-    getConnectionString,
-    SqliteAdapter,
-    PgAdapterAsync,
-    listSqliteTables,
-    listPgTables,
-    syncPush,
-    syncPull
-  } = await import("@hasna/cloud");
-  const config = getCloudConfig();
-  if (config.mode === "local")
-    throw new Error("Cloud mode is local. Run `cloud setup` first.");
-  const local = new SqliteAdapter(getDatabasePath(program2.opts().db));
-  const remote = new PgAdapterAsync(getConnectionString("shortlinks"));
+postgresCmd.command("status").description("Show local and PostgreSQL runtime configuration health without opening network connections").option("-j, --json", "Output JSON").action((opts) => {
   try {
-    const requestedTables = opts.tables ? opts.tables.split(",").map((t) => t.trim()).filter(Boolean) : null;
-    const localTables = requestedTables || listSqliteTables(local).filter((t) => !t.startsWith("_"));
-    const remoteTables = requestedTables || await listPgTables(remote).catch(() => localTables);
-    const tables = [...new Set(direction === "pull" ? remoteTables : direction === "push" ? localTables : [...localTables, ...remoteTables])];
-    const results = [];
-    if (direction === "pull" || direction === "sync") {
-      results.push({ direction: "pull", tables: await syncPull(remote, local, { tables }) });
-    }
-    if (direction === "push" || direction === "sync") {
-      results.push({ direction: "push", tables: await syncPush(local, remote, { tables }) });
-    }
-    print2({ service: "shortlinks", results }, opts, () => console.log(JSON.stringify({ service: "shortlinks", results }, null, 2)));
-  } finally {
-    local.close?.();
-    await remote.close?.();
+    const dbPath = getDatabasePath(program2.opts().db);
+    const data = {
+      ...getShortlinksRuntimeStatus(runtimeEnv()),
+      service: "shortlinks",
+      db_path: dbPath,
+      db_exists: existsSync4(dbPath)
+    };
+    print2(data, opts, () => console.log(JSON.stringify(data, null, 2)));
+  } catch (error) {
+    handleError(error);
   }
-}
-for (const direction of ["push", "pull", "sync"]) {
-  cloudCmd.command(direction).description(`${direction === "sync" ? "Bidirectionally sync" : direction === "push" ? "Push" : "Pull"} shortlinks data ${direction === "pull" ? "from" : "to"} PostgreSQL`).option("--tables <tables>", "Comma-separated table names").option("-j, --json", "Output JSON").action((opts) => syncCloud(direction, opts).catch(handleError));
-}
-cloudCmd.command("status").description("Show local and cloud configuration health").option("-j, --json", "Output JSON").action(async (opts) => {
+});
+postgresCmd.command("plan").description("Render a dry-run PostgreSQL setup plan").option("--schema-sql", "Include migration SQL").option("-j, --json", "Output JSON").action((opts) => {
   try {
-    const { getCloudConfig } = await import("@hasna/cloud");
-    const stats = withStore((store) => store.totalStats());
-    const config = getCloudConfig();
+    const status = getShortlinksRuntimeStatus(runtimeEnv());
     const data = {
+      ok: status.ok,
       service: "shortlinks",
-      db_path: getDatabasePath(program2.opts().db),
-      local: stats,
-      cloud_mode: config.mode,
-      rds_host: config.rds?.host || null
+      dry_run: true,
+      no_network: true,
+      status,
+      postgres: {
+        required: status.mode === "postgres",
+        configured: status.database.configured,
+        schema_sql: opts.schemaSql ? PG_MIGRATIONS : []
+      },
+      steps: [
+        "Read local SQLite state",
+        status.mode === "postgres" ? "Prepare direct shortlinks Postgres runtime" : "Keep serving from local SQLite",
+        "Run migrations with shortlinks postgres migrate before serving from Postgres",
+        "Report planned changes without opening network connections"
+      ]
     };
     print2(data, opts, () => console.log(JSON.stringify(data, null, 2)));
   } catch (error) {
@@ -4978,23 +5289,26 @@ localCmd.command("setup <domain>").description("Record local domain mapping with
 });
 program2.command("doctor").description("Check local shortlinks tooling and integration readiness").option("-j, --json", "Output JSON").action(async (opts) => {
   try {
-    const mode = storeMode();
-    const stats = await withRuntimeStore((store) => store.totalStats());
+    const runtime = getShortlinksRuntimeStatus(runtimeEnv());
+    const dbPath = getDatabasePath(program2.opts().db);
     const data = {
       service: "shortlinks",
-      store: mode,
+      ok: runtime.ok,
+      store: runtime.mode,
       data_dir: getDataDir(),
       config_path: getConfigPath(),
-      db_path: getDatabasePath(program2.opts().db),
-      db_exists: existsSync4(getDatabasePath(program2.opts().db)),
-      stats,
+      db_path: dbPath,
+      db_exists: existsSync4(dbPath),
+      stats: localStatsIfDatabaseExists(dbPath),
+      runtime,
+      no_network: true,
       commands: {
         domains: commandExists("domains"),
-        cloud: commandExists("cloud"),
         wrangler: commandExists("wrangler"),
         secrets: commandExists("secrets")
       },
       environment: {
+        shortlinks_database_url_present: Boolean(getShortlinksDatabaseUrl(runtimeEnv())),
         cloudflare_api_token_present: Boolean(process.env.CLOUDFLARE_API_TOKEN),
         cloudflare_api_key_present: Boolean(process.env.CLOUDFLARE_API_KEY),
         cloudflare_email_present: Boolean(process.env.CLOUDFLARE_EMAIL),