@usebetterdev/audit-cli 0.5.0-beta.1 → 0.5.0

package/dist/chunk-WVH5TQ2O.js

@@ -0,0 +1,101 @@
+import {
+  generateMigrationSql
+} from "./chunk-O5LHE2AC.js";
+import {
+  detectAdapter,
+  detectDialect,
+  findMigrationDirectory,
+  formatTimestamp
+} from "./chunk-HDO5P6X7.js";
+
+// src/migrate.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import pc from "picocolors";
+var AUDIT_TABLE_REGEX = /create\s+table\b[^;]*\baudit_logs\b/i;
+var MAX_SCAN_DEPTH = 3;
+function migrationAlreadyExists(directory, depth = 0) {
+  if (depth > MAX_SCAN_DEPTH) {
+    return false;
+  }
+  if (!existsSync(directory)) {
+    return false;
+  }
+  try {
+    const entries = readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      const fullPath = join(directory, entry.name);
+      if (entry.isFile() && entry.name.endsWith(".sql")) {
+        const content = readFileSync(fullPath, "utf-8");
+        if (AUDIT_TABLE_REGEX.test(content)) {
+          return true;
+        }
+      }
+      if (entry.isDirectory()) {
+        if (migrationAlreadyExists(fullPath, depth + 1)) {
+          return true;
+        }
+      }
+    }
+  } catch {
+  }
+  return false;
+}
+async function migrate(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const dialect = options.dialect ?? detectDialect(options.databaseUrl ?? process.env["DATABASE_URL"]);
+  const sql = generateMigrationSql(dialect);
+  if (options.dryRun === true) {
+    process.stdout.write(sql);
+    return;
+  }
+  const adapter = options.adapter ?? detectAdapter(cwd);
+  if (adapter === void 0) {
+    throw new Error(
+      "Could not detect ORM adapter. Install drizzle-orm or @prisma/client, or pass --adapter drizzle|prisma."
+    );
+  }
+  let outputPath;
+  let filePath;
+  if (options.output !== void 0) {
+    if (options.output.endsWith(".sql")) {
+      filePath = options.output;
+      outputPath = dirname(filePath);
+    } else {
+      outputPath = options.output;
+      filePath = adapter === "prisma" ? join(outputPath, "migration.sql") : join(outputPath, `${formatTimestamp(/* @__PURE__ */ new Date())}_audit_logs.sql`);
+    }
+  } else {
+    const migrationDir = findMigrationDirectory(cwd, adapter);
+    outputPath = migrationDir;
+    filePath = adapter === "prisma" ? join(migrationDir, "migration.sql") : join(migrationDir, `${formatTimestamp(/* @__PURE__ */ new Date())}_audit_logs.sql`);
+  }
+  const scanDir = adapter === "prisma" ? join(cwd, "prisma", "migrations") : outputPath;
+  if (migrationAlreadyExists(scanDir)) {
+    console.log(
+      pc.green("\u2713") + " audit_logs migration already exists \u2014 up to date."
+    );
+    return;
+  }
+  if (options.output !== void 0 && existsSync(filePath)) {
+    console.warn(pc.yellow(`Warning: overwriting existing file ${filePath}`));
+  }
+  mkdirSync(outputPath, { recursive: true });
+  writeFileSync(filePath, sql, "utf-8");
+  console.log(`${pc.green("\u2713")} Wrote migration: ${pc.dim(filePath)}`);
+  console.log("");
+  console.log(pc.bold("Next steps:"));
+  if (adapter === "drizzle") {
+    console.log(`  ${pc.yellow("$")} npx drizzle-kit migrate`);
+  } else {
+    console.log(`  ${pc.yellow("$")} npx prisma migrate dev`);
+  }
+}
+
+export {
+  migrate
+};
+//# sourceMappingURL=chunk-WVH5TQ2O.js.map

package/dist/chunk-WVH5TQ2O.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/migrate.ts"],"sourcesContent":["/**\n * `better-audit migrate` — Generate the audit_logs table migration.\n *\n * Generates appropriate DDL for the configured database:\n *   - Postgres: JSONB columns, TIMESTAMPTZ, gen_random_uuid()\n *   - MySQL:    JSON columns, DATETIME(6), UUID() default\n *   - SQLite:   TEXT columns for JSON, no UUID default\n *\n * Writes the migration file into the appropriate ORM directory,\n * or prints to stdout with --dry-run.\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport pc from \"picocolors\";\nimport { generateMigrationSql, type DatabaseDialect } from \"./generate-sql.js\";\nimport {\n  detectAdapter,\n  detectDialect,\n  findMigrationDirectory,\n  type AdapterType,\n} from \"./detect-adapter.js\";\nimport { formatTimestamp } from \"./utils.js\";\n\nexport interface MigrateOptions {\n  /** Output SQL to stdout instead of writing a file */\n  dryRun?: boolean | undefined;\n  /** Override ORM auto-detection */\n  adapter?: AdapterType | undefined;\n  /** Override database dialect detection */\n  dialect?: DatabaseDialect | undefined;\n  /** Override output directory/file */\n  output?: string | undefined;\n  /** Working directory (defaults to process.cwd()) */\n  cwd?: string | undefined;\n  /** Database connection URL for dialect detection (defaults to DATABASE_URL env) */\n  databaseUrl?: string | undefined;\n}\n\n/** Regex to detect an existing audit_logs CREATE TABLE statement (case-insensitive). */\nconst AUDIT_TABLE_REGEX = /create\\s+table\\b[^;]*\\baudit_logs\\b/i;\n\n/** Maximum directory depth for the idempotency scan. */\nconst MAX_SCAN_DEPTH = 3;\n\n/**\n * Check if a migration for `audit_logs` already exists in the given directory.\n * Scans `.sql` files up to `MAX_SCAN_DEPTH` levels deep, skipping symlinks.\n */\nfunction migrationAlreadyExists(directory: string, depth: number = 0): boolean {\n  if (depth > MAX_SCAN_DEPTH) {\n    return false;\n  }\n  if (!existsSync(directory)) {\n    return false;\n  }\n\n  try {\n    const entries = readdirSync(directory, { withFileTypes: true });\n    for (const entry of entries) {\n      if (entry.isSymbolicLink()) {\n        continue;\n      }\n      const fullPath = join(directory, entry.name);\n      if (entry.isFile() && entry.name.endsWith(\".sql\")) {\n        const content = readFileSync(fullPath, \"utf-8\");\n        if (AUDIT_TABLE_REGEX.test(content)) {\n          return true;\n        }\n      }\n      if (entry.isDirectory()) {\n        if (migrationAlreadyExists(fullPath, depth + 1)) {\n          return true;\n        }\n      }\n    }\n  } catch {\n    // Read error — treat as no existing migration\n  }\n\n  return false;\n}\n\nexport async function migrate(options: MigrateOptions = {}): Promise<void> {\n  const cwd = options.cwd ?? process.cwd();\n\n  // 1. Resolve dialect\n  const dialect: DatabaseDialect =\n    options.dialect ?? detectDialect(options.databaseUrl ?? process.env[\"DATABASE_URL\"]);\n\n  // 2. Generate SQL\n  const sql = generateMigrationSql(dialect);\n\n  // 3. Dry-run: print to stdout and return\n  if (options.dryRun === true) {\n    process.stdout.write(sql);\n    return;\n  }\n\n  // 4. Resolve adapter\n  const adapter: AdapterType | undefined =\n    options.adapter ?? detectAdapter(cwd);\n\n  if (adapter === undefined) {\n    throw new Error(\n      \"Could not detect ORM adapter. Install drizzle-orm or @prisma/client, \" +\n      \"or pass --adapter drizzle|prisma.\",\n    );\n  }\n\n  // 5. Resolve output directory\n  let outputPath: string;\n  let filePath: string;\n\n  if (options.output !== undefined) {\n    if (options.output.endsWith(\".sql\")) {\n      filePath = options.output;\n      outputPath = dirname(filePath);\n    } else {\n      outputPath = options.output;\n      filePath =\n        adapter === \"prisma\"\n          ? join(outputPath, \"migration.sql\")\n          : join(outputPath, `${formatTimestamp(new Date())}_audit_logs.sql`);\n    }\n  } else {\n    const migrationDir = findMigrationDirectory(cwd, adapter);\n    outputPath = migrationDir;\n    filePath =\n      adapter === \"prisma\"\n        ? join(migrationDir, \"migration.sql\")\n        : join(migrationDir, `${formatTimestamp(new Date())}_audit_logs.sql`);\n  }\n\n  // 6. Check idempotency — scan parent migration directory\n  const scanDir =\n    adapter === \"prisma\"\n      ? join(cwd, \"prisma\", \"migrations\")\n      : outputPath;\n\n  if (migrationAlreadyExists(scanDir)) {\n    console.log(\n      pc.green(\"✓\") + \" audit_logs migration already exists — up to date.\",\n    );\n    return;\n  }\n\n  // 7. Warn if output file already exists (explicit --output path)\n  if (options.output !== undefined && existsSync(filePath)) {\n    console.warn(pc.yellow(`Warning: overwriting existing file ${filePath}`));\n  }\n\n  // 8. Write migration file\n  mkdirSync(outputPath, { recursive: true });\n  writeFileSync(filePath, sql, \"utf-8\");\n\n  console.log(`${pc.green(\"✓\")} Wrote migration: ${pc.dim(filePath)}`);\n  console.log(\"\");\n  console.log(pc.bold(\"Next steps:\"));\n\n  if (adapter === \"drizzle\") {\n    console.log(`  ${pc.yellow(\"$\")} npx drizzle-kit migrate`);\n  } else {\n    console.log(`  ${pc.yellow(\"$\")} npx prisma migrate dev`);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -1 +1,156 @@
 #!/usr/bin/env node
+import {
+  CheckFailedError,
+  check
+} from "./chunk-55KKYFKR.js";
+import {
+  exportLogs
+} from "./chunk-M46VJ3FO.js";
+import {
+  migrate
+} from "./chunk-WVH5TQ2O.js";
+import "./chunk-O5LHE2AC.js";
+import {
+  purge
+} from "./chunk-SJSGTCG4.js";
+import "./chunk-7GSN73TA.js";
+import "./chunk-HDO5P6X7.js";
+import {
+  stats
+} from "./chunk-AGFBL646.js";
+
+// src/cli.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { Command } from "commander";
+import pc from "picocolors";
+var cliDir = dirname(fileURLToPath(import.meta.url));
+var pkgRaw = JSON.parse(
+  readFileSync(join(cliDir, "..", "package.json"), "utf-8")
+);
+var cliVersion = typeof pkgRaw === "object" && pkgRaw !== null && "version" in pkgRaw && typeof pkgRaw.version === "string" ? pkgRaw.version : "0.0.0";
+function parseAdapter(value) {
+  if (value === "drizzle" || value === "prisma" || value === void 0) {
+    return value;
+  }
+  throw new Error("--adapter must be 'drizzle' or 'prisma'");
+}
+function parseDialect(value) {
+  if (value === "postgres" || value === "mysql" || value === "sqlite" || value === void 0) {
+    return value;
+  }
+  throw new Error("--dialect must be 'postgres', 'mysql', or 'sqlite'");
+}
+function formatErrorMessage(err) {
+  if (err instanceof AggregateError && err.errors.length > 0) {
+    const nested = err.errors.map((e) => e instanceof Error ? e.message : String(e)).join("; ");
+    return err.message !== "" ? `${err.message}: ${nested}` : nested;
+  }
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}
+async function runAction(fn) {
+  try {
+    await fn();
+  } catch (err) {
+    if (err instanceof CheckFailedError) {
+      process.exit(1);
+    }
+    const message = formatErrorMessage(err);
+    console.error(pc.red(message));
+    process.exit(1);
+  }
+}
+var program = new Command().name("@usebetterdev/audit-cli").description("CLI for @usebetterdev/audit \u2014 compliance-ready audit logging").version(cliVersion);
+program.command("migrate").description("Generate the audit_logs table migration").option(
+  "--dry-run",
+  "Print SQL to stdout without writing a file"
+).option(
+  "--adapter <adapter>",
+  "ORM adapter: drizzle or prisma (auto-detected from package.json)"
+).option(
+  "--dialect <dialect>",
+  "Database dialect: postgres, mysql, or sqlite (auto-detected from DATABASE_URL)"
+).option("-o, --output <path>", "Output directory or .sql file path").action(
+  async (opts) => {
+    await runAction(
+      () => migrate({
+        dryRun: opts.dryRun,
+        adapter: parseAdapter(opts.adapter),
+        dialect: parseDialect(opts.dialect),
+        output: opts.output
+      })
+    );
+  }
+);
+program.command("check").description("Verify the audit_logs table and ORM adapter are working").option("--verbose", "Show detailed results for each check").option(
+  "--database-url <url>",
+  "Database URL (default: DATABASE_URL env)"
+).action(async (opts) => {
+  await runAction(
+    () => check({ verbose: opts.verbose, databaseUrl: opts.databaseUrl })
+  );
+});
+program.command("stats").description("Show audit log statistics").option("-c, --config <path>", "Config file path", "better-audit.config.ts").option("--since <period>", "Time window (e.g. 30d)", "30d").action(async (opts) => {
+  await runAction(() => stats({ config: opts.config, since: opts.since }));
+});
+program.command("purge").description("Delete audit logs older than the retention period").option("-c, --config <path>", "Config file path", "better-audit.config.ts").option("--dry-run", "Preview rows to be deleted without deleting them").option(
+  "--since <value>",
+  'ISO date (e.g. "2025-01-01") or duration shorthand (e.g. "90d") \u2014 overrides config'
+).option("--batch-size <n>", "Rows per DELETE batch (default: 1000)").option(
+  "--database-url <url>",
+  "Database URL (default: DATABASE_URL env)"
+).option("-y, --yes", "Skip confirmation prompt (required for live deletion)").action(
+  async (opts) => {
+    await runAction(async () => {
+      const purgeOpts = { config: opts.config };
+      if (opts.dryRun !== void 0) {
+        purgeOpts.dryRun = opts.dryRun;
+      }
+      if (opts.since !== void 0) {
+        purgeOpts.since = opts.since;
+      }
+      if (opts.batchSize !== void 0) {
+        const n = Number(opts.batchSize);
+        if (!Number.isInteger(n) || n <= 0) {
+          throw new Error(
+            `Invalid --batch-size "${opts.batchSize}". Expected a positive integer.`
+          );
+        }
+        purgeOpts.batchSize = n;
+      }
+      if (opts.databaseUrl !== void 0) {
+        purgeOpts.databaseUrl = opts.databaseUrl;
+      }
+      if (opts.yes !== void 0) {
+        purgeOpts.yes = opts.yes;
+      }
+      await purge(purgeOpts);
+    });
+  }
+);
+program.command("export").description("Export audit log entries as CSV or JSON").option("--format <format>", "Output format: csv or json (default: csv)").option("-o, --output <path>", "Output file path (default: stdout)").option(
+  "--since <value>",
+  'Duration (e.g. "90d") or ISO date (e.g. "2025-01-01")'
+).option(
+  "--severity <level>",
+  "Filter by severity: low, medium, high, or critical"
+).option(
+  "--compliance <tags>",
+  'Comma-separated compliance tags (e.g. "soc2:access-control,gdpr")'
+).option("--actor <id>", "Filter by actor ID").option("--limit <n>", "Maximum number of rows to export").option(
+  "--database-url <url>",
+  "Database URL (default: DATABASE_URL env)"
+).action(
+  async (opts) => {
+    await runAction(() => exportLogs(opts));
+  }
+);
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Command } from \"commander\";\nimport pc from \"picocolors\";\nimport { migrate } from \"./migrate.js\";\nimport { check, CheckFailedError } from \"./check.js\";\nimport { stats } from \"./stats.js\";\nimport { purge } from \"./purge.js\";\nimport { exportLogs } from \"./export.js\";\n\n// Read version from package.json at the package root\nconst cliDir = dirname(fileURLToPath(import.meta.url));\nconst pkgRaw: unknown = JSON.parse(\n  readFileSync(join(cliDir, \"..\", \"package.json\"), \"utf-8\"),\n);\nconst cliVersion =\n  typeof pkgRaw === \"object\" &&\n  pkgRaw !== null &&\n  \"version\" in pkgRaw &&\n  typeof pkgRaw.version === \"string\"\n    ? pkgRaw.version\n    : \"0.0.0\";\n\n/** Validate and narrow the --adapter flag value. */\nfunction parseAdapter(\n  value: string | undefined,\n): \"drizzle\" | \"prisma\" | undefined {\n  if (value === \"drizzle\" || value === \"prisma\" || value === undefined) {\n    return value;\n  }\n  throw new Error(\"--adapter must be 'drizzle' or 'prisma'\");\n}\n\n/** Validate and narrow the --dialect flag value. */\nfunction parseDialect(\n  value: string | undefined,\n): \"postgres\" | \"mysql\" | \"sqlite\" | undefined {\n  if (\n    value === \"postgres\" ||\n    value === \"mysql\" ||\n    value === \"sqlite\" ||\n    value === undefined\n  ) {\n    return value;\n  }\n  throw new Error(\"--dialect must be 'postgres', 'mysql', or 'sqlite'\");\n}\n\n/** Extract a human-readable message from an error, including AggregateError nested errors. */\nfunction formatErrorMessage(err: unknown): string {\n  if (err instanceof AggregateError && err.errors.length > 0) {\n    // AggregateError (e.g. from pg connection failure) has an empty .message\n    // but contains nested errors with the actual details\n    const nested = err.errors\n      .map((e: unknown) => (e instanceof Error ? e.message : String(e)))\n      .join(\"; \");\n    return err.message !== \"\" ? `${err.message}: ${nested}` : nested;\n  }\n  if (err instanceof Error) {\n    return err.message;\n  }\n  return String(err);\n}\n\n/** Wrap a subcommand action with consistent error handling. */\nasync function runAction(fn: () => Promise<void>): Promise<void> {\n  try {\n    await fn();\n  } catch (err) {\n    // CheckFailedError already printed its output — just exit\n    if (err instanceof CheckFailedError) {\n      process.exit(1);\n    }\n    const message = formatErrorMessage(err);\n    console.error(pc.red(message));\n    process.exit(1);\n  }\n}\n\nconst program = new Command()\n  .name(\"@usebetterdev/audit-cli\")\n  .description(\"CLI for @usebetterdev/audit — compliance-ready audit logging\")\n  .version(cliVersion);\n\nprogram\n  .command(\"migrate\")\n  .description(\"Generate the audit_logs table migration\")\n  .option(\n    \"--dry-run\",\n    \"Print SQL to stdout without writing a file\",\n  )\n  .option(\n    \"--adapter <adapter>\",\n    \"ORM adapter: drizzle or prisma (auto-detected from package.json)\",\n  )\n  .option(\n    \"--dialect <dialect>\",\n    \"Database dialect: postgres, mysql, or sqlite (auto-detected from DATABASE_URL)\",\n  )\n  .option(\"-o, --output <path>\", \"Output directory or .sql file path\")\n  .action(\n    async (opts: {\n      dryRun?: boolean;\n      adapter?: string;\n      dialect?: string;\n      output?: string;\n    }) => {\n      await runAction(() =>\n        migrate({\n          dryRun: opts.dryRun,\n          adapter: parseAdapter(opts.adapter),\n          dialect: parseDialect(opts.dialect),\n          output: opts.output,\n        }),\n      );\n    },\n  );\n\nprogram\n  .command(\"check\")\n  .description(\"Verify the audit_logs table and ORM adapter are working\")\n  .option(\"--verbose\", \"Show detailed results for each check\")\n  .option(\n    \"--database-url <url>\",\n    \"Database URL (default: DATABASE_URL env)\",\n  )\n  .action(async (opts: { verbose?: boolean; databaseUrl?: string }) => {\n    await runAction(() =>\n      check({ verbose: opts.verbose, databaseUrl: opts.databaseUrl }),\n    );\n  });\n\nprogram\n  .command(\"stats\")\n  .description(\"Show audit log statistics\")\n  .option(\"-c, --config <path>\", \"Config file path\", \"better-audit.config.ts\")\n  .option(\"--since <period>\", \"Time window (e.g. 30d)\", \"30d\")\n  .action(async (opts: { config: string; since: string }) => {\n    await runAction(() => stats({ config: opts.config, since: opts.since }));\n  });\n\nprogram\n  .command(\"purge\")\n  .description(\"Delete audit logs older than the retention period\")\n  .option(\"-c, --config <path>\", \"Config file path\", \"better-audit.config.ts\")\n  .option(\"--dry-run\", \"Preview rows to be deleted without deleting them\")\n  .option(\n    \"--since <value>\",\n    'ISO date (e.g. \"2025-01-01\") or duration shorthand (e.g. \"90d\") — overrides config',\n  )\n  .option(\"--batch-size <n>\", \"Rows per DELETE batch (default: 1000)\")\n  .option(\n    \"--database-url <url>\",\n    \"Database URL (default: DATABASE_URL env)\",\n  )\n  .option(\"-y, --yes\", \"Skip confirmation prompt (required for live deletion)\")\n  .action(\n    async (opts: {\n      config: string;\n      dryRun?: boolean;\n      since?: string;\n      batchSize?: string;\n      databaseUrl?: string;\n      yes?: boolean;\n    }) => {\n      await runAction(async () => {\n        const purgeOpts: Parameters<typeof purge>[0] = { config: opts.config };\n        if (opts.dryRun !== undefined) {\n          purgeOpts.dryRun = opts.dryRun;\n        }\n        if (opts.since !== undefined) {\n          purgeOpts.since = opts.since;\n        }\n        if (opts.batchSize !== undefined) {\n          const n = Number(opts.batchSize);\n          if (!Number.isInteger(n) || n <= 0) {\n            throw new Error(\n              `Invalid --batch-size \"${opts.batchSize}\". Expected a positive integer.`,\n            );\n          }\n          purgeOpts.batchSize = n;\n        }\n        if (opts.databaseUrl !== undefined) {\n          purgeOpts.databaseUrl = opts.databaseUrl;\n        }\n        if (opts.yes !== undefined) {\n          purgeOpts.yes = opts.yes;\n        }\n        await purge(purgeOpts);\n      });\n    },\n  );\n\nprogram\n  .command(\"export\")\n  .description(\"Export audit log entries as CSV or JSON\")\n  .option(\"--format <format>\", \"Output format: csv or json (default: csv)\")\n  .option(\"-o, --output <path>\", \"Output file path (default: stdout)\")\n  .option(\n    \"--since <value>\",\n    'Duration (e.g. \"90d\") or ISO date (e.g. \"2025-01-01\")',\n  )\n  .option(\n    \"--severity <level>\",\n    \"Filter by severity: low, medium, high, or critical\",\n  )\n  .option(\n    \"--compliance <tags>\",\n    'Comma-separated compliance tags (e.g. \"soc2:access-control,gdpr\")',\n  )\n  .option(\"--actor <id>\", \"Filter by actor ID\")\n  .option(\"--limit <n>\", \"Maximum number of rows to export\")\n  .option(\n    \"--database-url <url>\",\n    \"Database URL (default: DATABASE_URL env)\",\n  )\n  .action(\n    async (opts: {\n      format?: string;\n      output?: string;\n      since?: string;\n      severity?: string;\n      compliance?: string;\n      actor?: string;\n      limit?: string;\n      databaseUrl?: string;\n    }) => {\n      await runAction(() => exportLogs(opts));\n    },\n  );\n\nprogram.parseAsync(process.argv).catch((err: unknown) => {\n  console.error(err);\n  process.exit(1);\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AACA,SAAS,oBAAoB;AAC7B,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;AAC9B,SAAS,eAAe;AACxB,OAAO,QAAQ;AAQf,IAAM,SAAS,QAAQ,cAAc,YAAY,GAAG,CAAC;AACrD,IAAM,SAAkB,KAAK;AAAA,EAC3B,aAAa,KAAK,QAAQ,MAAM,cAAc,GAAG,OAAO;AAC1D;AACA,IAAM,aACJ,OAAO,WAAW,YAClB,WAAW,QACX,aAAa,UACb,OAAO,OAAO,YAAY,WACtB,OAAO,UACP;AAGN,SAAS,aACP,OACkC;AAClC,MAAI,UAAU,aAAa,UAAU,YAAY,UAAU,QAAW;AACpE,WAAO;AAAA,EACT;AACA,QAAM,IAAI,MAAM,yCAAyC;AAC3D;AAGA,SAAS,aACP,OAC6C;AAC7C,MACE,UAAU,cACV,UAAU,WACV,UAAU,YACV,UAAU,QACV;AACA,WAAO;AAAA,EACT;AACA,QAAM,IAAI,MAAM,oDAAoD;AACtE;AAGA,SAAS,mBAAmB,KAAsB;AAChD,MAAI,eAAe,kBAAkB,IAAI,OAAO,SAAS,GAAG;AAG1D,UAAM,SAAS,IAAI,OAChB,IAAI,CAAC,MAAgB,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAE,EAChE,KAAK,IAAI;AACZ,WAAO,IAAI,YAAY,KAAK,GAAG,IAAI,OAAO,KAAK,MAAM,KAAK;AAAA,EAC5D;AACA,MAAI,eAAe,OAAO;AACxB,WAAO,IAAI;AAAA,EACb;AACA,SAAO,OAAO,GAAG;AACnB;AAGA,eAAe,UAAU,IAAwC;AAC/D,MAAI;AACF,UAAM,GAAG;AAAA,EACX,SAAS,KAAK;AAEZ,QAAI,eAAe,kBAAkB;AACnC,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,UAAM,UAAU,mBAAmB,GAAG;AACtC,YAAQ,MAAM,GAAG,IAAI,OAAO,CAAC;AAC7B,YAAQ,KAAK,CAAC;AAAA,EAChB;AACF;AAEA,IAAM,UAAU,IAAI,QAAQ,EACzB,KAAK,yBAAyB,EAC9B,YAAY,mEAA8D,EAC1E,QAAQ,UAAU;AAErB,QACG,QAAQ,SAAS,EACjB,YAAY,yCAAyC,EACrD;AAAA,EACC;AAAA,EACA;AACF,EACC;AAAA,EACC;AAAA,EACA;AACF,EACC;AAAA,EACC;AAAA,EACA;AACF,EACC,OAAO,uBAAuB,oCAAoC,EAClE;AAAA,EACC,OAAO,SAKD;AACJ,UAAM;AAAA,MAAU,MACd,QAAQ;AAAA,QACN,QAAQ,KAAK;AAAA,QACb,SAAS,aAAa,KAAK,OAAO;AAAA,QAClC,SAAS,aAAa,KAAK,OAAO;AAAA,QAClC,QAAQ,KAAK;AAAA,MACf,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEF,QACG,QAAQ,OAAO,EACf,YAAY,yDAAyD,EACrE,OAAO,aAAa,sCAAsC,EAC1D;AAAA,EACC;AAAA,EACA;AACF,EACC,OAAO,OAAO,SAAsD;AACnE,QAAM;AAAA,IAAU,MACd,MAAM,EAAE,SAAS,KAAK,SAAS,aAAa,KAAK,YAAY,CAAC;AAAA,EAChE;AACF,CAAC;AAEH,QACG,QAAQ,OAAO,EACf,YAAY,2BAA2B,EACvC,OAAO,uBAAuB,oBAAoB,wBAAwB,EAC1E,OAAO,oBAAoB,0BAA0B,KAAK,EAC1D,OAAO,OAAO,SAA4C;AACzD,QAAM,UAAU,MAAM,MAAM,EAAE,QAAQ,KAAK,QAAQ,OAAO,KAAK,MAAM,CAAC,CAAC;AACzE,CAAC;AAEH,QACG,QAAQ,OAAO,EACf,YAAY,mDAAmD,EAC/D,OAAO,uBAAuB,oBAAoB,wBAAwB,EAC1E,OAAO,aAAa,kDAAkD,EACtE;AAAA,EACC;AAAA,EACA;AACF,EACC,OAAO,oBAAoB,uCAAuC,EAClE;AAAA,EACC;AAAA,EACA;AACF,EACC,OAAO,aAAa,uDAAuD,EAC3E;AAAA,EACC,OAAO,SAOD;AACJ,UAAM,UAAU,YAAY;AAC1B,YAAM,YAAyC,EAAE,QAAQ,KAAK,OAAO;AACrE,UAAI,KAAK,WAAW,QAAW;AAC7B,kBAAU,SAAS,KAAK;AAAA,MAC1B;AACA,UAAI,KAAK,UAAU,QAAW;AAC5B,kBAAU,QAAQ,KAAK;AAAA,MACzB;AACA,UAAI,KAAK,cAAc,QAAW;AAChC,cAAM,IAAI,OAAO,KAAK,SAAS;AAC/B,YAAI,CAAC,OAAO,UAAU,CAAC,KAAK,KAAK,GAAG;AAClC,gBAAM,IAAI;AAAA,YACR,yBAAyB,KAAK,SAAS;AAAA,UACzC;AAAA,QACF;AACA,kBAAU,YAAY;AAAA,MACxB;AACA,UAAI,KAAK,gBAAgB,QAAW;AAClC,kBAAU,cAAc,KAAK;AAAA,MAC/B;AACA,UAAI,KAAK,QAAQ,QAAW;AAC1B,kBAAU,MAAM,KAAK;AAAA,MACvB;AACA,YAAM,MAAM,SAAS;AAAA,IACvB,CAAC;AAAA,EACH;AACF;AAEF,QACG,QAAQ,QAAQ,EAChB,YAAY,yCAAyC,EACrD,OAAO,qBAAqB,2CAA2C,EACvE,OAAO,uBAAuB,oCAAoC,EAClE;AAAA,EACC;AAAA,EACA;AACF,EACC;AAAA,EACC;AAAA,EACA;AACF,EACC;AAAA,EACC;AAAA,EACA;AACF,EACC,OAAO,gBAAgB,oBAAoB,EAC3C,OAAO,eAAe,kCAAkC,EACxD;AAAA,EACC;AAAA,EACA;AACF,EACC;AAAA,EACC,OAAO,SASD;AACJ,UAAM,UAAU,MAAM,WAAW,IAAI,CAAC;AAAA,EACxC;AACF;AAEF,QAAQ,WAAW,QAAQ,IAAI,EAAE,MAAM,CAAC,QAAiB;AACvD,UAAQ,MAAM,GAAG;AACjB,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/dist/detect-adapter-DNHcPCKz.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auto-detection utilities for ORM adapter, database dialect, and migration directories.
+ */
+type DatabaseDialect = "postgres" | "mysql" | "sqlite";
+type AdapterType = "drizzle" | "prisma";
+
+export type { AdapterType as A, DatabaseDialect as D };

package/dist/export.d.ts

@@ -0,0 +1,38 @@
+import { AuditSeverity } from '@usebetterdev/audit-core';
+
+/**
+ * `better-audit export` — Export audit log entries as CSV or JSON.
+ *
+ * Connects to the database via Kysely (multi-dialect), builds query filters
+ * from CLI flags, and streams results to a file or stdout.
+ */
+
+interface ExportCommandOptions {
+    format?: string;
+    output?: string;
+    since?: string;
+    severity?: string;
+    compliance?: string;
+    actor?: string;
+    limit?: string;
+    databaseUrl?: string;
+}
+/** Parse `--format` flag, validate and default to "csv". */
+declare function parseFormat(value: string | undefined): "csv" | "json";
+/** Parse `--severity` flag, validate against known values. */
+declare function parseSeverity(value: string): AuditSeverity;
+/**
+ * Parse `--since` flag. ISO date strings (e.g. "2025-01-01") become Date objects.
+ * Duration strings (e.g. "90d") are returned as-is for the query builder.
+ */
+declare function parseSinceValue(value: string): Date | string;
+/**
+ * Create a WHATWG WritableStream<string> that writes to a Node.js file.
+ * Handles backpressure by awaiting the drain event.
+ */
+declare function createFileWritableStream(path: string): WritableStream<string>;
+/** Create a WHATWG WritableStream<string> that writes to process.stdout. */
+declare function createStdoutWritableStream(): WritableStream<string>;
+declare function exportLogs(options: ExportCommandOptions): Promise<void>;
+
+export { type ExportCommandOptions, createFileWritableStream, createStdoutWritableStream, exportLogs, parseFormat, parseSeverity, parseSinceValue };

package/dist/export.js

@@ -0,0 +1,19 @@
+import {
+  createFileWritableStream,
+  createStdoutWritableStream,
+  exportLogs,
+  parseFormat,
+  parseSeverity,
+  parseSinceValue
+} from "./chunk-M46VJ3FO.js";
+import "./chunk-7GSN73TA.js";
+import "./chunk-HDO5P6X7.js";
+export {
+  createFileWritableStream,
+  createStdoutWritableStream,
+  exportLogs,
+  parseFormat,
+  parseSeverity,
+  parseSinceValue
+};
+//# sourceMappingURL=export.js.map

package/dist/export.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/migrate.d.ts

@@ -0,0 +1,31 @@
+import { A as AdapterType, D as DatabaseDialect } from './detect-adapter-DNHcPCKz.js';
+
+/**
+ * `better-audit migrate` — Generate the audit_logs table migration.
+ *
+ * Generates appropriate DDL for the configured database:
+ *   - Postgres: JSONB columns, TIMESTAMPTZ, gen_random_uuid()
+ *   - MySQL:    JSON columns, DATETIME(6), UUID() default
+ *   - SQLite:   TEXT columns for JSON, no UUID default
+ *
+ * Writes the migration file into the appropriate ORM directory,
+ * or prints to stdout with --dry-run.
+ */
+
+interface MigrateOptions {
+    /** Output SQL to stdout instead of writing a file */
+    dryRun?: boolean | undefined;
+    /** Override ORM auto-detection */
+    adapter?: AdapterType | undefined;
+    /** Override database dialect detection */
+    dialect?: DatabaseDialect | undefined;
+    /** Override output directory/file */
+    output?: string | undefined;
+    /** Working directory (defaults to process.cwd()) */
+    cwd?: string | undefined;
+    /** Database connection URL for dialect detection (defaults to DATABASE_URL env) */
+    databaseUrl?: string | undefined;
+}
+declare function migrate(options?: MigrateOptions): Promise<void>;
+
+export { type MigrateOptions, migrate };

package/dist/migrate.js

@@ -0,0 +1,9 @@
+import {
+  migrate
+} from "./chunk-WVH5TQ2O.js";
+import "./chunk-O5LHE2AC.js";
+import "./chunk-HDO5P6X7.js";
+export {
+  migrate
+};
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/purge.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `better-audit purge` — Delete audit logs older than the configured retention period.
+ *
+ * Connects to the database directly via Kysely (no ORM adapter needed).
+ * Executes batched DELETEs to avoid holding long row-level locks on large tables.
+ *
+ * Always run with --dry-run first to preview what will be deleted.
+ */
+interface PurgeOptions {
+    config?: string;
+    /** Preview rows to be deleted without deleting them. */
+    dryRun?: boolean;
+    /** ISO date string (e.g. "2025-01-01") or duration shorthand (e.g. "90d", "1y"). */
+    since?: string;
+    /** Rows per DELETE batch. Default: 1000. */
+    batchSize?: number;
+    /** Database URL (default: DATABASE_URL env). */
+    databaseUrl?: string;
+    /** Skip confirmation prompt (required for live deletion). */
+    yes?: boolean;
+}
+/**
+ * Parse a `--since` value to an absolute cutoff `Date`.
+ *
+ * Accepts:
+ * - ISO-8601 date strings: "2025-01-01" or "2025-01-01T00:00:00Z"
+ * - Duration shorthands: "90d", "4w", "3m", "1y"
+ *
+ * Exported for testing.
+ */
+declare function parseSinceValue(value: string): Date;
+/**
+ * Resolve the cutoff date from options.
+ *
+ * Priority: `--since` flag > config `retention.days`.
+ * Throws if neither is available.
+ *
+ * Exported for testing.
+ */
+declare function resolveCutoffDate(options: {
+    since?: string;
+    config?: string;
+}): Promise<Date>;
+/**
+ * Format elapsed milliseconds to a human-readable string.
+ *
+ * Exported for testing.
+ */
+declare function formatDuration(ms: number): string;
+declare function purge(options?: PurgeOptions): Promise<void>;
+
+export { type PurgeOptions, formatDuration, parseSinceValue, purge, resolveCutoffDate };

package/dist/purge.js

@@ -0,0 +1,15 @@
+import {
+  formatDuration,
+  parseSinceValue,
+  purge,
+  resolveCutoffDate
+} from "./chunk-SJSGTCG4.js";
+import "./chunk-7GSN73TA.js";
+import "./chunk-HDO5P6X7.js";
+export {
+  formatDuration,
+  parseSinceValue,
+  purge,
+  resolveCutoffDate
+};
+//# sourceMappingURL=purge.js.map

package/dist/purge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/stats.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `better-audit stats` — Show audit log statistics.
+ *
+ * Outputs:
+ *   - Total log count
+ *   - Events per day (last 7 / 30 days)
+ *   - Top actors (by event count)
+ *   - Top tables (by event count)
+ *   - Severity distribution
+ *
+ * TODO: Connect to DB and run aggregation queries.
+ */
+interface StatsOptions {
+    config?: string;
+    since?: string;
+}
+declare function stats(options?: StatsOptions): Promise<void>;
+
+export { type StatsOptions, stats };

package/dist/stats.js

@@ -0,0 +1,7 @@
+import {
+  stats
+} from "./chunk-AGFBL646.js";
+export {
+  stats
+};
+//# sourceMappingURL=stats.js.map

package/dist/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usebetterdev/audit-cli",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0",
   "repository": "github:usebetter-dev/usebetter",
   "bugs": "https://github.com/usebetter-dev/usebetter/issues",
   "homepage": "https://github.com/usebetter-dev/usebetter#readme",
@@ -20,8 +20,25 @@
   "dependencies": {
     "@clack/prompts": "^0.10.0",
     "commander": "^12.1.0",
+    "kysely": "^0.28.11",
     "picocolors": "^1.1.0",
-    "@usebetterdev/audit-core": "0.5.0-beta.1"
+    "@usebetterdev/audit-core": "0.5.0"
+  },
+  "peerDependencies": {
+    "pg": ">=8.0.0",
+    "mysql2": ">=3.0.0",
+    "better-sqlite3": ">=11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
@@ -34,6 +51,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "build:types": "tsc --build tsconfig.build.json",
     "test": "vitest run",
     "test:integration": "vitest run -c vitest.integration.config.ts",
     "typecheck": "tsc --noEmit"