@agilesyndrome/cf-genai-base 5.0.0 → 5.0.2

package/src/cli/cli.js

@@ -0,0 +1,133 @@
+import { backupD1, checkConfig, checkD1, migrateD1, refreshLocalD1, refreshStagingD1, restoreD1, statusD1 } from "./d1.js";
+import { runUserCommand } from "./users.js";
+import { runTenantCommand } from "./tenants.js";
+import { runOperationalCommand } from "./operations.js";
+import { runProjectCommand } from "./project.js";
+import { runVersionCommand } from "./version.js";
+import { siteStatus } from "./status.js";
+
+const usage = `Usage:
+  cf-genai check|test|build|ci|ci:lint
+  cf-genai lint data-access
+  cf-genai dev [options]
+  cf-genai upgrade <base|auth|llm|messaging> <latest|VERSION>
+  cf-genai release [--confirm] [--first] [--add-trust] [--dry-run] [--bypass-lint] [--type patch|minor|major] [--version MAJOR.MINOR]
+  cf-genai release-status [--wait MINUTES] [--json]
+    cf-genai status [--env local|staging|production] [--json]
+  cf-genai version
+  cf-genai d1 refresh|backup|restore|migrate|status|check local|staging|production [options]
+  cf-genai admin status|features|users|tenants|scopes|groups|healthchecks|circuit-breakers [options]
+  cf-genai config check [options]
+  cf-genai user list|get|update [username] [options]
+  cf-genai tenant list|get|create|update [tenant-id] [options]
+
+Options:
+  --database NAME             D1 binding or database name (default: DB)
+  --production-database NAME  Production D1 binding or database name
+  --production-env NAME       Wrangler production environment (default: none)
+  --staging-env NAME          Wrangler staging environment (default: staging)
+  --config PATH               Wrangler config path (default: wrangler.jsonc)
+  --env VALUE                 Environment alias: local, staging, or prod
+  --output PATH               Backup output file
+  --file PATH                 Restore input file
+  --wrangler COMMAND          Wrangler command (default: npx wrangler)
+  --yes                       Confirm a remote staging refresh
+  --confirm-production        Explicitly permit production migration or breaker changes
+  --confirm                    Confirm a destructive or release operation
+  --dry-run                    Show release checks without changing Git or npm
+  --version MAJOR.MINOR        Explicit release target; patch is assigned as .0
+  --bypass-lint                Skip the release preflight lint (use sparingly)
+  --json                      Return machine-readable output
+  --help                      Show this help
+`;
+
+function splitCommand(value = "npx wrangler") {
+  return value.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((part) => part.replace(/^(["'])(.*)\1$/, "$2")) ?? ["npx", "wrangler"];
+}
+
+function parseOptions(args, env = process.env) {
+  const options = {
+    config: env.CF_GENAI_WRANGLER_CONFIG || "wrangler.jsonc",
+    database: env.CF_GENAI_DATABASE || "DB",
+    productionEnv: env.CF_GENAI_PRODUCTION_ENV || "",
+    stagingEnv: env.CF_GENAI_STAGING_ENV || "staging",
+    wranglerCommand: splitCommand(env.CF_GENAI_WRANGLER || "npx wrangler"),
+    yes: false,
+    confirmProduction: false,
+    target: env.CF_GENAI_TARGET || "local",
+    roles: undefined,
+    scopes: undefined,
+    groups: undefined,
+    tenants: undefined,
+    name: undefined,
+    json: false,
+  };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") return { ...options, help: true, positional };
+    if (arg === "--yes") options.yes = true;
+    else if (arg === "--json") options.json = true
+    else if (arg === "--confirm-production") options.confirmProduction = true;
+    else if (arg.startsWith("--")) {
+      const [key, inline] = arg.slice(2).split("=", 2);
+      const names = {
+        database: "database", "production-database": "productionDatabase",
+        "production-env": "productionEnv", "staging-env": "stagingEnv",
+        config: "config", wrangler: "wrangler", target: "target", env: "target", roles: "roles", scopes: "scopes", groups: "groups", tenants: "tenants", name: "name", output: "output", file: "file",
+      };
+      const optionName = names[key];
+      if (!optionName) throw new Error(`Unknown option: ${arg}`);
+      const value = inline ?? args[++index];
+      if (value === undefined) throw new Error(`Missing value for ${arg}.`);
+      if (optionName === "wrangler") options.wranglerCommand = splitCommand(value);
+      else options[optionName] = value;
+    } else positional.push(arg);
+  }
+  return { ...options, positional, productionDatabase: options.productionDatabase || options.database };
+}
+
+export async function main(args = process.argv.slice(2), env = process.env) {
+  if (args[0]?.includes(":")) { const [domain, action] = args[0].split(":", 2); if (["user", "tenant", "healthcheck", "healthchecks", "circuit-breaker", "circuit-breakers", "circuit"].includes(domain)) args = [domain, action, ...args.slice(1)]; }
+  if (args[0] === "version") return runVersionCommand();
+  const projectCommand = args[0];
+  if (["check", "test", "build", "ci", "ci:lint", "lint", "dev", "upgrade", "release", "release-status"].includes(projectCommand)) {
+    const result = runProjectCommand(projectCommand, args.slice(1));
+    if (result === null) throw new Error(`Unknown command.\n\n${usage}`);
+    return result;
+  }
+  const options = parseOptions(args, env);
+  if (options.positional[0] === "status") return siteStatus(options);
+  if (options.help || options.positional.length === 0) {
+    console.log(usage);
+    return;
+  }
+  let [domain, action, target] = options.positional;
+  if (domain === "admin") { const adminAction = { user: "users", tenant: "tenants", healthcheck: "healthchecks", "circuit-breaker": "circuit-breakers", circuit: "circuit-breakers" }[action] || action; if (["local", "staging", "prod", "production"].includes(target)) options.target = target === "prod" ? "production" : target; if (adminAction === "tenants") return runTenantCommand({ action: options.positional[2] || "list", identifier: options.positional[3], name: options.name, options }); if (["healthchecks", "circuit-breakers"].includes(adminAction)) return runOperationalCommand({ domain: adminAction, action: options.positional[2] || "list", identifier: options.positional[3], value: options.positional[4], options }); return runOperationalCommand({ domain: "admin", action: adminAction, identifier: options.positional[3], value: options.positional[4], options }); }
+  if (domain === "backup" || domain === "restore") { target = action || options.target; action = domain; return runD1FileCommand(action, target, options); }
+  if (domain === "user") return runUserCommand({ action, username: target, options });
+  if (domain === "tenant") return runTenantCommand({ action, identifier: target, name: options.name, options });
+  if (["healthcheck", "healthchecks", "circuit-breaker", "circuit-breakers", "circuit"].includes(domain)) return runOperationalCommand({ domain, action, identifier: target, value: options.positional[3], options });
+  if (domain === "config" && action === "check") return checkConfig(options);
+  if (domain !== "d1" || !["refresh", "backup", "restore", "migrate", "status", "check"].includes(action)) throw new Error(`Unknown command.\n\n${usage}`);
+  target = target === "prod" ? "production" : target;
+  if (!["local", "staging", "production"].includes(target)) throw new Error("Target must be local, staging, or production.");
+  if (action === "backup" || action === "restore") return runD1FileCommand(action, target, options);
+  if (action === "refresh") {
+    if (target === "staging" && !options.yes) throw new Error("Staging refresh replaces remote data; rerun with --yes.");
+    if (target === "local") return refreshLocalD1({ database: options.database, productionDatabase: options.productionDatabase, options });
+    if (target === "staging") return refreshStagingD1({ database: options.database, productionDatabase: options.productionDatabase, options });
+    throw new Error(`Unknown command.\n\n${usage}`);
+  }
+  if (action === "migrate" && target === "production" && !options.confirmProduction) throw new Error("Production migration requires --confirm-production.");
+  if (action === "migrate") return migrateD1({ target, database: options.database, options });
+  if (action === "status") return statusD1({ target, database: options.database, options });
+  return checkD1({ target, database: options.database, options });
+}
+
+function runD1FileCommand(action, target, options) {
+  if (action === "backup") return backupD1({ target, database: options.database, options });
+  return restoreD1({ target, database: options.database, options });
+}
+
+export { parseOptions, usage };

package/src/cli/d1.js

@@ -0,0 +1,165 @@
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const INTERNAL_TABLE_SQL = `
+SELECT name
+FROM sqlite_schema
+WHERE type = 'table'
+  AND name NOT LIKE 'sqlite_%'
+  AND name NOT LIKE '_cf_%'
+  AND name <> 'd1_migrations'
+ORDER BY name;
+`;
+
+export function shellCommand(value = "npx wrangler") {
+  return value.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((part) => part.replace(/^(["'])(.*)\1$/, "$2")) ?? ["npx", "wrangler"];
+}
+
+export function targetArgs(target, options = {}) {
+  if (target === "local") return ["--local"];
+  const args = ["--remote"];
+  const environment = target === "staging" ? options.stagingEnv : options.productionEnv;
+  if (environment) args.push("--env", environment);
+  return args;
+}
+
+export function extractRows(value) {
+  if (Array.isArray(value)) return value.flatMap(extractRows);
+  if (!value || typeof value !== "object") return [];
+  const rows = [];
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "results" && Array.isArray(child)) rows.push(...child);
+    rows.push(...extractRows(child));
+  }
+  return rows;
+}
+
+export function parseJsonRows(output) {
+  try {
+    return extractRows(JSON.parse(output));
+  } catch {
+    throw new Error("Wrangler returned invalid JSON while inspecting D1.");
+  }
+}
+
+export function tableNamesFromJson(output) {
+  return parseJsonRows(output)
+    .map((row) => row?.name)
+    .filter((name) => typeof name === "string" && name.length > 0);
+}
+
+export function clearSql(tableNames) {
+  const identifiers = tableNames.map((name) => `"${name.replaceAll('"', '""')}"`);
+  return [
+    "PRAGMA defer_foreign_keys = ON;",
+    ...identifiers.map((name) => `DELETE FROM ${name};`),
+    "PRAGMA defer_foreign_keys = OFF;",
+    "",
+  ].join("\n");
+}
+
+export function stripInternalRows(sql) {
+  return sql
+    .split("\n")
+    .filter((line) => !/^\s*INSERT\s+INTO\s+["`]?((d1_migrations)|(sqlite_[^"`\s]*)|(_cf_[^"`\s]*))["`]?/i.test(line))
+    .join("\n");
+}
+
+function run(wrangler, args, options = {}) {
+  const result = spawnSync(wrangler[0], [...wrangler.slice(1), ...args], {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: "utf8",
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${wrangler.join(" ")} exited with status ${result.status ?? "unknown"}.`);
+  return result.stdout ?? "";
+}
+
+function execute(wrangler, database, target, sqlFile, options) {
+  run(wrangler, ["d1", "execute", database, ...targetArgs(target, options), "--file", sqlFile, "--yes", "--config", options.config], options);
+}
+
+export function executeJson(wrangler, database, target, command, options) {
+  return run(wrangler, ["d1", "execute", database, ...targetArgs(target, options), "--command", command, "--json", "--config", options.config], { ...options, capture: true });
+}
+
+function migrations(wrangler, database, target, options) {
+  run(wrangler, ["d1", "migrations", "apply", database, ...targetArgs(target, options), "--config", options.config], options);
+}
+
+async function refreshD1(target, { database, productionDatabase, options }) {
+  const directory = await mkdtemp(join(tmpdir(), "cf-genai-d1-refresh-"));
+  const exportPath = join(directory, "production-data.sql");
+  const importPath = join(directory, "application-data.sql");
+  try {
+    run(options.wranglerCommand, [
+      "d1", "export", productionDatabase, "--remote",
+      ...(options.productionEnv ? ["--env", options.productionEnv] : []),
+      "--no-schema", "--output", exportPath, "--skip-confirmation", "--config", options.config,
+    ], options);
+    migrations(options.wranglerCommand, database, target, options);
+    const tableOutput = executeJson(options.wranglerCommand, database, target, INTERNAL_TABLE_SQL, options);
+    const tables = tableNamesFromJson(tableOutput);
+    if (tables.length === 0) throw new Error(`No application tables found in ${target} D1 database.`);
+    const exported = await readFile(exportPath, "utf8");
+    await writeFile(importPath, `${clearSql(tables)}${stripInternalRows(exported)}`);
+    execute(options.wranglerCommand, database, target, importPath, options);
+    await mkdir(options.cwd || process.cwd(), { recursive: true });
+    await writeFile(join(options.cwd || process.cwd(), ".cf-genai-last-prod-refresh"), new Date().toISOString() + "\n");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+export function refreshLocalD1(args) {
+  return refreshD1("local", args);
+}
+
+export function refreshStagingD1(args) {
+  return refreshD1("staging", args);
+}
+
+export function migrateD1({ target, database, options }) {
+  migrations(options.wranglerCommand, database, target, options);
+}
+
+export function statusD1({ target, database, options }) {
+  if (target !== "local") {
+    run(options.wranglerCommand, ["d1", "info", database, ...(target === "staging" && options.stagingEnv ? ["--env", options.stagingEnv] : []), ...(target === "production" && options.productionEnv ? ["--env", options.productionEnv] : []), "--config", options.config], options);
+    return;
+  }
+  const output = executeJson(options.wranglerCommand, database, target, "SELECT name, type FROM sqlite_schema WHERE type IN ('table', 'index') ORDER BY type, name;", options);
+  console.log(output);
+}
+
+export function checkD1({ target, database, options }) {
+  const output = executeJson(options.wranglerCommand, database, target, "PRAGMA foreign_key_check; PRAGMA integrity_check;", options);
+  const rows = parseJsonRows(output);
+  const failures = rows.filter((row) => !(Object.values(row ?? {}).length === 1 && Object.values(row)[0] === "ok"));
+  if (failures.length > 0) throw new Error(`D1 integrity checks failed: ${JSON.stringify(failures)}`);
+  console.log(`${target} D1 integrity checks passed.`);
+}
+
+export function backupD1({ target, database, options }) {
+  if (!options.output) throw new Error("Backup requires --output PATH.");
+  if (target === "production" && !options.confirmProduction) throw new Error("Production backup requires --confirm-production.");
+  run(options.wranglerCommand, ["d1", "export", database, ...targetArgs(target, options), "--output", options.output, "--skip-confirmation", "--config", options.config], options);
+  console.log("Backed up " + database + " (" + target + ") to " + options.output);
+}
+
+export async function restoreD1({ target, database, options }) {
+  if (!options.file) throw new Error("Restore requires --file PATH.");
+  try { await readFile(options.file); } catch { throw new Error("Restore file not found: " + options.file); }
+  if (target !== "local" && !options.yes) throw new Error("Remote restore replaces data; rerun with --yes.");
+  if (target === "production" && !options.confirmProduction) throw new Error("Production restore requires --confirm-production.");
+  execute(options.wranglerCommand, database, target, options.file, options);
+  console.log("Restored " + database + " (" + target + ") from " + options.file);
+}
+
+export function checkConfig(options) {
+  run(options.wranglerCommand, ["deploy", "--dry-run", "--config", options.config], options);
+}

package/src/cli/operations.js

@@ -0,0 +1,34 @@
+import { executeJson, parseJsonRows } from "./d1.js";
+
+function query(sql, options) { return parseJsonRows(executeJson(options.wranglerCommand, options.database, normalizeTarget(options.target), sql, options)); }
+function normalizeTarget(target) { return target === "prod" ? "production" : target || "local"; }
+function output(value) { console.log(JSON.stringify(value, null, 2)); }
+
+export function runOperationalCommand({ domain, action, identifier, value, options }) {
+  const target = normalizeTarget(options.target);
+  if (!["local", "staging", "production"].includes(target)) throw new Error("Environment must be local, staging, or prod/production.");
+  if (domain === "admin" && action === "status") return output(query("SELECT feature,MAX(CASE state WHEN 'red' THEN 2 WHEN 'yellow' THEN 1 ELSE 0 END) AS severity,COUNT(*) AS healthchecks FROM core_healthchecks GROUP BY feature ORDER BY feature;", { ...options, target }));
+  if (domain === "admin" && action === "features") return output(query("SELECT feature,COUNT(*) AS healthchecks FROM core_healthchecks GROUP BY feature ORDER BY feature;", { ...options, target }));
+  if (domain === "admin" && action === "users") return output(query("SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM auth_users ORDER BY email COLLATE NOCASE;", { ...options, target }));
+  if (domain === "admin" && action === "scopes") return output(query("SELECT name,label,description,system FROM auth_scopes ORDER BY name;", { ...options, target }));
+  if (domain === "admin" && action === "groups") return output(query("SELECT name,display_name,description,created_at,updated_at FROM auth_groups ORDER BY display_name COLLATE NOCASE;", { ...options, target }));
+  if ((domain === "healthcheck" || domain === "healthchecks" || (domain === "admin" && action === "healthchecks")) && action === "list") return output(query("SELECT id,feature,component,display_name,state,metadata_json,created_at,updated_at FROM core_healthchecks ORDER BY feature,component;", { ...options, target }));
+  if ((domain === "healthcheck" || domain === "healthchecks" || (domain === "admin" && action === "healthchecks")) && action === "get") { if (!identifier) throw new Error("A healthcheck id is required."); return output(query("SELECT id,feature,component,display_name,state,metadata_json,created_at,updated_at FROM core_healthchecks WHERE id=" + sql(identifier) + " LIMIT 1;", { ...options, target })); }
+  if ((domain === "healthcheck" || domain === "healthchecks" || (domain === "admin" && action === "healthchecks")) && ["set", "update"].includes(action)) { if (!identifier || !value) throw new Error("healthcheck:set requires an id and state (red, yellow, or green)."); if (!["red", "yellow", "green"].includes(value)) throw new Error("Healthcheck state must be red, yellow, or green."); query("UPDATE core_healthchecks SET state=" + sql(value) + ",updated_at=CURRENT_TIMESTAMP WHERE id=" + sql(identifier) + ";", { ...options, target }); return output({ id: identifier, state: value, environment: target, changed_by: "human:cli" }); }
+  if ((domain === "circuit-breaker" || domain === "circuit-breakers" || domain === "circuit" || (domain === "admin" && action === "circuit-breakers")) && action === "list") return output(query("SELECT id,feature,name,display_name,state,healthcheck_mode,allow_self_healing,metadata_json,created_at,updated_at FROM core_circuit_breakers ORDER BY feature,name;", { ...options, target }));
+  if ((domain === "circuit-breaker" || domain === "circuit-breakers" || domain === "circuit" || (domain === "admin" && action === "circuit-breakers")) && action === "get") {
+    if (!identifier) throw new Error("A circuit-breaker id is required.");
+    return output(query("SELECT id,feature,name,display_name,state,healthcheck_mode,allow_self_healing,metadata_json,created_at,updated_at FROM core_circuit_breakers WHERE id=" + sql(identifier) + " LIMIT 1;", { ...options, target }));
+  }
+  if ((domain === "circuit-breaker" || domain === "circuit-breakers" || domain === "circuit" || (domain === "admin" && action === "circuit-breakers")) && (action === "set" || action === "update")) {
+    if (!identifier || !value) throw new Error("circuit-breaker:set requires an id and state (off, tripped, or on).");
+    if (!["off", "tripped", "on"].includes(value)) throw new Error("Circuit-breaker state must be off, tripped, or on.");
+    if (target === "production" && !options.confirmProduction) throw new Error("Production circuit-breaker changes require --confirm-production.");
+    const rows = query("SELECT id,state FROM core_circuit_breakers WHERE id=" + sql(identifier) + " LIMIT 1;", { ...options, target });
+    if (!rows[0]) throw new Error("Circuit breaker not found: " + identifier);
+    query("UPDATE core_circuit_breakers SET state=" + sql(value) + ",updated_at=CURRENT_TIMESTAMP WHERE id=" + sql(identifier) + ";", { ...options, target });
+    return output({ id: identifier, state: value, environment: target, changed_by: "human:cli" });
+  }
+  throw new Error("Unknown operational command.");
+}
+function sql(value) { return "'" + String(value).replaceAll("'", "''") + "'"; }