@gurulu/cli 0.4.6 → 1.0.0

package/scripts/tenant-pivot-phase-3-cleanup.lib.cjs

@@ -1,258 +0,0 @@
-// tenant-pivot-phase-3-cleanup.lib.cjs — destructive-cleanup logic for the
-// Phase 18 A4 tenant pivot phase 3 migration (drop `site_id` column).
-//
-// CommonJS so it can be `require()`-d by both the ESM CLI wrapper
-// (`scripts/tenant-pivot-phase-3-cleanup.mjs`) and the ts-jest test
-// (`tests/scripts-tenant-pivot-phase-3-cleanup.test.ts`). See the README
-// header in the .mjs wrapper for the operator-facing contract.
-//
-// IMPORTANT: This module exposes pure helpers and a CLI orchestrator. None of
-// it self-executes. The `.mjs` wrapper is the only thing with a top-level
-// `runCli()` call, gated on `import.meta.url === process.argv[1]`.
-
-'use strict';
-
-const fs = require('node:fs').promises;
-const path = require('node:path');
-const readline = require('node:readline');
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-// Every analytics table that still carries `site_id` after Phase 18 A4. See
-// docker/clickhouse/init/01_schema.sql for the canonical column definitions.
-// ORDER MATTERS for the dry-run output but not for execution.
-const AFFECTED_TABLES = [
-  'events_raw',
-  'flow_session_events',
-  'journey_events',
-  'cross_property_journeys',
-  'inferred_events',
-];
-
-const LOG_PATH_DEFAULT = path.resolve(process.cwd(), 'logs', 'tenant-pivot-phase-3.log');
-
-// ---------------------------------------------------------------------------
-// Pure helpers
-// ---------------------------------------------------------------------------
-
-function buildDropColumnSql(table) {
-  if (!table || typeof table !== 'string') {
-    throw new Error('buildDropColumnSql: table is required');
-  }
-  // ClickHouse ALTER TABLE DROP COLUMN is implemented as a mutation on the
-  // affected parts. Destructive and irreversible without a backup.
-  return `ALTER TABLE ${table} DROP COLUMN IF EXISTS site_id`;
-}
-
-function buildRowCountSql(table) {
-  return `SELECT count() AS c FROM ${table}`;
-}
-
-function parseArgs(argv) {
-  const args = { apply: false, help: false, noConfirm: false };
-  for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--apply') args.apply = true;
-    else if (a === '--no-confirm') args.noConfirm = true;
-    else if (a === '--help' || a === '-h') args.help = true;
-  }
-  return args;
-}
-
-function printHelp(out) {
-  const log = out || console.log;
-  log(
-    [
-      '',
-      'Usage: node scripts/tenant-pivot-phase-3-cleanup.mjs [--apply] [--no-confirm]',
-      '',
-      '  (default)    DRY-RUN. Prints SQL + row counts. Touches nothing.',
-      '  --apply      Actually execute ALTER TABLE DROP COLUMN. Requires',
-      '               an interactive `yes` confirmation from a human operator.',
-      '  --no-confirm Skip the readline prompt (still requires --apply). For',
-      '               automated test harnesses only — do NOT use in prod.',
-      '',
-      '⚠ This is a DESTRUCTIVE migration. Take a ClickHouse backup first.',
-      '',
-    ].join('\n'),
-  );
-}
-
-// Real ClickHouse HTTP client — unit tests inject a stub via the runCli
-// `queryFn` parameter so this is never actually invoked under jest.
-async function clickhouseQuery(query, params = {}) {
-  const CLICKHOUSE_URL = process.env.CLICKHOUSE_URL || 'http://localhost:8123';
-  const CLICKHOUSE_DB = process.env.CLICKHOUSE_DATABASE || 'gurulu';
-  const url = new URL(CLICKHOUSE_URL);
-  url.searchParams.set('database', CLICKHOUSE_DB);
-  url.searchParams.set('default_format', 'JSON');
-  for (const [k, v] of Object.entries(params)) {
-    url.searchParams.set(`param_${k}`, String(v));
-  }
-  const res = await fetch(url.toString(), {
-    method: 'POST',
-    body: query,
-    headers: { 'Content-Type': 'text/plain' },
-  });
-  if (!res.ok) {
-    throw new Error(`ClickHouse error ${res.status}: ${await res.text()}`);
-  }
-  return res.json();
-}
-
-async function safeRowCount(table, queryFn) {
-  const fn = queryFn || clickhouseQuery;
-  try {
-    const res = await fn(buildRowCountSql(table));
-    const row = (res && res.data && res.data[0]) || {};
-    return Number(row.c != null ? row.c : (row.count != null ? row.count : 0));
-  } catch (_err) {
-    return null;
-  }
-}
-
-async function buildPlan(queryFn) {
-  const plan = [];
-  for (const table of AFFECTED_TABLES) {
-    const rowCount = await safeRowCount(table, queryFn);
-    plan.push({ table, rowCount, sql: buildDropColumnSql(table) });
-  }
-  return plan;
-}
-
-function renderPlan(plan, mode) {
-  const lines = [];
-  lines.push(`# tenant-pivot-phase-3-cleanup mode=${mode} ts=${new Date().toISOString()}`);
-  lines.push('');
-  lines.push('Affected tables:');
-  for (const step of plan) {
-    const rc =
-      step.rowCount === null || step.rowCount === undefined
-        ? '(unknown)'
-        : Number(step.rowCount).toLocaleString();
-    lines.push(`  • ${step.table}  rows=${rc}`);
-    lines.push(`      ${step.sql}`);
-  }
-  lines.push('');
-  return lines.join('\n');
-}
-
-async function appendLog(block, logPath) {
-  const target = logPath || LOG_PATH_DEFAULT;
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  await fs.appendFile(target, block + '\n', 'utf8');
-}
-
-// Interactive confirmation prompt. Defaults to a real readline interface;
-// tests inject `promptFn` to avoid touching stdin.
-async function confirmDestructive(promptFn) {
-  const ask =
-    promptFn ||
-    function defaultAsk(q) {
-      return new Promise((resolve) => {
-        const rl = readline.createInterface({
-          input: process.stdin,
-          output: process.stdout,
-        });
-        rl.question(q, (ans) => {
-          rl.close();
-          resolve(ans);
-        });
-      });
-    };
-  const answer = await ask(
-    '\n⚠  About to DROP COLUMN site_id from production analytics tables. Type "yes" to proceed: ',
-  );
-  return String(answer || '').trim().toLowerCase() === 'yes';
-}
-
-// ---------------------------------------------------------------------------
-// CLI orchestrator
-// ---------------------------------------------------------------------------
-
-async function runCli(opts) {
-  const o = opts || {};
-  const argv = o.argv || process.argv;
-  const queryFn = o.queryFn || clickhouseQuery;
-  const promptFn = o.promptFn;
-  const log = o.log || console.log;
-  const errorLog = o.errorLog || console.error;
-  const logPath = o.logPath || LOG_PATH_DEFAULT;
-
-  const args = parseArgs(argv);
-  if (args.help) {
-    printHelp(log);
-    return { ok: true, mode: 'help' };
-  }
-
-  const mode = args.apply ? 'APPLY' : 'DRY-RUN';
-  log(`[phase-3-cleanup] mode=${mode}`);
-  log('[phase-3-cleanup] ⚠ This script is destructive. See the README header.');
-
-  const plan = await buildPlan(queryFn);
-  const rendered = renderPlan(plan, mode);
-  log(rendered);
-  try {
-    await appendLog(rendered, logPath);
-  } catch (err) {
-    errorLog('[phase-3-cleanup] WARNING: failed to write migration log:', err);
-  }
-
-  if (!args.apply) {
-    log('[phase-3-cleanup] dry-run complete. Re-run with --apply to actually drop columns.');
-    return { ok: true, mode: 'dry-run', plan };
-  }
-
-  // --apply path: require either an interactive `yes` or the explicit
-  // --no-confirm test-only flag.
-  if (!args.noConfirm) {
-    const confirmed = await confirmDestructive(promptFn);
-    if (!confirmed) {
-      errorLog('[phase-3-cleanup] confirmation declined; nothing was changed.');
-      return { ok: false, mode: 'apply', reason: 'declined' };
-    }
-  } else {
-    log('[phase-3-cleanup] --no-confirm set: skipping interactive prompt (test mode).');
-  }
-
-  const executed = [];
-  for (const step of plan) {
-    log(`[phase-3-cleanup] APPLY ${step.table}`);
-    log(`           ${step.sql}`);
-    try {
-      await queryFn(step.sql);
-      executed.push(Object.assign({}, step, { status: 'ok' }));
-    } catch (err) {
-      errorLog(`[phase-3-cleanup] FAILED on ${step.table}:`, err);
-      executed.push(Object.assign({}, step, { status: 'error', error: String(err) }));
-      break;
-    }
-  }
-
-  await appendLog(
-    `# applied ts=${new Date().toISOString()}\n` +
-      executed.map((s) => `  ${s.status} ${s.table} :: ${s.sql}`).join('\n') +
-      '\n',
-    logPath,
-  );
-
-  return { ok: executed.every((s) => s.status === 'ok'), mode: 'apply', executed };
-}
-
-module.exports = {
-  AFFECTED_TABLES,
-  LOG_PATH_DEFAULT,
-  buildDropColumnSql,
-  buildRowCountSql,
-  parseArgs,
-  printHelp,
-  clickhouseQuery,
-  safeRowCount,
-  buildPlan,
-  renderPlan,
-  appendLog,
-  confirmDestructive,
-  runCli,
-};

package/scripts/tenant-pivot-phase-3-cleanup.mjs

@@ -1,98 +0,0 @@
-#!/usr/bin/env node
-/**
- * ============================================================================
- *  README — DO NOT RUN AUTOMATICALLY. EVER.
- * ============================================================================
- *
- *  Phase 18 A4 — Tenant pivot phase 3 cleanup script.
- *
- *  This is a DESTRUCTIVE migration tool. It exists so an operator can, when
- *  they are ready, drop the obsolete `site_id` column from the ClickHouse
- *  analytics tables now that the tenant-first read path (Phase 18 A4) and
- *  the tenant-first write path (Phase 17 B1) are both in production.
- *
- *  ⚠  This script must NEVER be invoked by CI, pre-commit, deploy hooks,
- *  ⚠  cron, AI agents, or anything other than a human operator who has
- *  ⚠  taken a verified ClickHouse backup and read PHASE-18-ROADMAP.md §A4.
- *
- *  Default behaviour (no flags) is a SAFE DRY-RUN: it prints exactly the
- *  ALTER TABLE statements it would execute, fetches a current row count for
- *  every affected table, and writes a markdown-friendly migration log to
- *  `logs/tenant-pivot-phase-3.log`. It does NOT touch ClickHouse beyond the
- *  read-only `SELECT count()` queries.
- *
- *  Passing `--apply` is the only way to actually run the destructive ALTER
- *  TABLE DROP COLUMN statements. The `--apply` path additionally requires an
- *  interactive `yes` typed at a confirmation prompt so an operator cannot
- *  fat-finger it from shell history.
- *
- *  Affected tables (every analytics table that still carries `site_id` after
- *  Phase 18 A4 — see docker/clickhouse/init/01_schema.sql for the canonical
- *  list):
- *
- *    • events_raw                 — primary fact table
- *    • flow_session_events        — per-session ordered event tape
- *    • journey_events             — cross-property event timeline (Phase 13)
- *    • cross_property_journeys    — aggregated journey rollup (Phase 13)
- *    • inferred_events            — server-derived event sink
- *
- *  Usage:
- *
- *    node scripts/tenant-pivot-phase-3-cleanup.mjs                 # dry-run (default)
- *    node scripts/tenant-pivot-phase-3-cleanup.mjs --apply         # interactive destructive run
- *    node scripts/tenant-pivot-phase-3-cleanup.mjs --apply --no-confirm  # test harness only
- *
- *  Env:
- *    CLICKHOUSE_URL       (default http://localhost:8123)
- *    CLICKHOUSE_DATABASE  (default gurulu)
- *
- *  The detection / orchestration logic lives in
- *  `scripts/tenant-pivot-phase-3-cleanup.lib.cjs` so it can be reused by the
- *  ts-jest test suite via `require()`. This wrapper exposes the same API as
- *  an ESM module and, when invoked directly, runs the CLI.
- *
- *  IMPORTANT: Do not modify this script to auto-run. Do not add it to any
- *  workflow. The whole point of the human-in-the-loop confirmation is to
- *  guarantee an operator chose to drop the column.
- * ============================================================================
- */
-
-import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-
-const require = createRequire(import.meta.url);
-const lib = require('./tenant-pivot-phase-3-cleanup.lib.cjs');
-
-export const AFFECTED_TABLES = lib.AFFECTED_TABLES;
-export const buildDropColumnSql = lib.buildDropColumnSql;
-export const buildRowCountSql = lib.buildRowCountSql;
-export const parseArgs = lib.parseArgs;
-export const printHelp = lib.printHelp;
-export const safeRowCount = lib.safeRowCount;
-export const buildPlan = lib.buildPlan;
-export const renderPlan = lib.renderPlan;
-export const appendLog = lib.appendLog;
-export const confirmDestructive = lib.confirmDestructive;
-export const runCli = lib.runCli;
-
-// CLI entry — only auto-runs when invoked directly via `node ...mjs`, not
-// when imported by another module.
-const isMain = (() => {
-  try {
-    return fileURLToPath(import.meta.url) === process.argv[1];
-  } catch {
-    return false;
-  }
-})();
-
-if (isMain) {
-  lib.runCli().then(
-    (r) => {
-      if (!r.ok) process.exitCode = 1;
-    },
-    (err) => {
-      console.error('[phase-3-cleanup] fatal:', err);
-      process.exitCode = 1;
-    },
-  );
-}