@xylex-group/athena 1.6.0 → 1.6.2

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.6.0`
+current version: `1.6.2`
 `@xylex-group/athena` is a database driver and API gateway SDK that lets you interact with SQL backends over HTTP through a fluent builder API. It ships a typed query builder for Node.js / server environments plus Athena-native React hooks for client-side use.
 
 ## Install
@@ -83,22 +83,45 @@ await typed
 
 For full details, see [`docs/typed-schema-registry.md`](./docs/typed-schema-registry.md).
 
-### Typed schema generator (phase 2 scaffolding)
+### Typed schema generator
 
-The SDK now includes a project-root generator config system (`athena.config.ts`) and CLI command:
+Schema generation is additive. Existing `createClient(...).from<T>(...)` usage remains valid while teams migrate to generated registry files.
+
+CLI:
 
 ```bash
 athena-js generate
 athena-js generate --dry-run
 athena-js generate --config ./athena.config.ts
+athena-js generate --help
+athena-js help generate
 ```
 
-Generator output paths support placeholder tokens (database/schema/model + case variants), feature flags, and experimental provider contracts.
-PostgreSQL introspection works both via direct `pg_url` and gateway-only `/gateway/query` execution.
+Generator supports:
+
+- PostgreSQL direct introspection (`provider.mode = "direct"`, `provider.connectionString` from your `PG_URL`/`DATABASE_URL`)
+- PostgreSQL gateway-only introspection (`provider.mode = "gateway"` via Athena `POST /gateway/query`)
+- Placeholder-driven output paths
+- Feature flags (`features.emitRegistry`, `features.emitRelations`)
 
-For full generator configuration, see [`docs/generator-config.md`](./docs/generator-config.md).
+For full generator configuration and troubleshooting, see [`docs/generator-config.md`](./docs/generator-config.md).
+For full CLI commands, help behavior, and troubleshooting, see [`docs/cli-command-reference.md`](./docs/cli-command-reference.md).
+For CI/CD pipelines and generated-file branch policy, see [`docs/generator-cicd.md`](./docs/generator-cicd.md).
 For prompt-ready documentation handoff text, see [`docs/generator-codex-handoff-prompt-pack.md`](./docs/generator-codex-handoff-prompt-pack.md).
 
+### Athena JS and Athena RS
+
+`athena-js` is designed to be standalone for TypeScript/Node and React-native workflows:
+
+- query builder + hooks
+- typed registry and generator pipeline
+- CLI-driven codegen in JS/TS projects
+
+`athena-rs` remains the faster fit for Rust service execution paths. Teams can run both in parallel:
+
+- `athena-rs` for Rust backend throughput
+- `athena-js` for app/tooling layers that need TypeScript contracts and frontend-facing ergonomics
+
 Every query resolves to `{ data, error, errorDetails?, status, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
 
 For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
@@ -666,6 +689,8 @@ CI and publish workflows run `typecheck` before build/publish.
 
 - [Documentation index](docs/index.md) — complete documentation map
 - [Getting started](docs/getting-started.md) — step-by-step walkthrough
+- [CLI command reference](docs/cli-command-reference.md) — all `athena-js` commands, help flows, and troubleshooting
 - [Typed schema registry](docs/typed-schema-registry.md) — typed contracts and migration path
 - [Generator config](docs/generator-config.md) — generator provider and output pipeline
+- [Generator CI/CD](docs/generator-cicd.md) — pipeline patterns, secret mapping, retries, and branch policy
 - [API reference](docs/api-reference.md) — complete method and type reference

package/bin/athena-js.js

@@ -1,8 +1,76 @@
 #!/usr/bin/env node
 
-import('../dist/cli/index.js')
-  .then(({ runCLI }) => runCLI(process.argv.slice(2)))
-  .catch(err => {
-    console.error('Failed to start athena-js CLI:', err)
-    process.exit(1)
-  })
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const binPath = fileURLToPath(import.meta.url)
+const packageRoot = path.resolve(path.dirname(binPath), '..')
+const cliEntrypointPath = path.resolve(packageRoot, 'dist', 'cli', 'index.js')
+const packageJsonPath = path.resolve(packageRoot, 'package.json')
+
+function getInstalledVersion() {
+  try {
+    const packageJsonRaw = readFileSync(packageJsonPath, 'utf8')
+    const packageJson = JSON.parse(packageJsonRaw)
+    return typeof packageJson.version === 'string' ? packageJson.version : 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function printMissingEntrypointError() {
+  const installedVersion = getInstalledVersion()
+  console.error(
+    [
+      'Failed to start athena-js CLI: package install is missing the generated CLI entrypoint.',
+      `Expected file: ${cliEntrypointPath}`,
+      `Installed package version: ${installedVersion}`,
+      '',
+      'Fix by reinstalling the latest package:',
+      '  pnpm add -g @xylex-group/athena@latest',
+    ].join('\n'),
+  )
+}
+
+function formatRuntimeError(error) {
+  if (error instanceof Error) {
+    if (process.env.ATHENA_JS_DEBUG === '1') {
+      return error.stack ?? error.message;
+    }
+    return error.message;
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  return 'Unknown error.';
+}
+
+async function main() {
+  if (!existsSync(cliEntrypointPath)) {
+    printMissingEntrypointError();
+    process.exit(1);
+    return;
+  }
+
+  try {
+    const cliEntrypointUrl = pathToFileURL(cliEntrypointPath).href;
+    const cliModule = await import(cliEntrypointUrl);
+    if (typeof cliModule.runCLI !== 'function') {
+      throw new Error('CLI module does not export runCLI.');
+    }
+    await cliModule.runCLI(process.argv.slice(2));
+  } catch (err) {
+    const errorDetail = formatRuntimeError(err);
+    if (errorDetail.includes('\n')) {
+      console.error(`Failed to start athena-js CLI:\n${errorDetail}`);
+    } else {
+      console.error(`Failed to start athena-js CLI: ${errorDetail}`);
+    }
+    process.exit(1);
+  }
+}
+
+void main()

package/dist/cli/index.cjs

@@ -300,10 +300,10 @@ var DEFAULT_CONFIG_CANDIDATES = [
   ".athena.config.js"
 ];
 var DEFAULT_TARGETS = {
-  model: "src/generated/{database_kebab}/{schema_kebab}/{model_kebab}.model.ts",
-  schema: "src/generated/{database_kebab}/{schema_kebab}/index.ts",
-  database: "src/generated/{database_kebab}/index.ts",
-  registry: "src/generated/index.ts"
+  model: "athena/models/{model_kebab}.ts",
+  schema: "athena/schema.ts",
+  database: "athena/relations.ts",
+  registry: "athena/config.ts"
 };
 var DEFAULT_NAMING = {
   modelType: "pascal",
@@ -331,6 +331,13 @@ function normalizeOutputConfig(output) {
     }
   };
 }
+function isAthenaGeneratorConfig(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const record = value;
+  return Boolean(record.provider && typeof record.provider === "object") && Boolean(record.output && typeof record.output === "object");
+}
 function normalizeGeneratorConfig(input) {
   return {
     provider: input.provider,
@@ -359,18 +366,41 @@ function findGeneratorConfigPath(cwd = process.cwd()) {
   return void 0;
 }
 function extractConfigExport(module) {
-  if (module && typeof module === "object") {
-    const record = module;
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [module];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || typeof current !== "object" || visited.has(current)) {
+      continue;
+    }
+    visited.add(current);
+    const record = current;
+    if (isAthenaGeneratorConfig(record)) {
+      return record;
+    }
     const defaultExport = record.default;
     if (defaultExport && typeof defaultExport === "object") {
-      return defaultExport;
+      queue.push(defaultExport);
     }
     const namedConfigExport = record.config;
     if (namedConfigExport && typeof namedConfigExport === "object") {
-      return namedConfigExport;
+      queue.push(namedConfigExport);
+    }
+    const moduleExports = record["module.exports"];
+    if (moduleExports && typeof moduleExports === "object") {
+      queue.push(moduleExports);
     }
   }
-  throw new Error("Generator config file must export a config object as default export or `config`.");
+  throw new Error(
+    "Generator config file must export a config object as default export or `config`."
+  );
+}
+function importConfigModule(moduleSpecifier) {
+  const runtimeImport = new Function(
+    "moduleSpecifier",
+    "return import(moduleSpecifier)"
+  );
+  return runtimeImport(moduleSpecifier);
 }
 async function loadGeneratorConfig(options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -381,7 +411,7 @@ async function loadGeneratorConfig(options = {}) {
     );
   }
   const moduleUrl = url.pathToFileURL(resolvedPath);
-  const module = await import(`${moduleUrl.href}?cacheBust=${Date.now()}`);
+  const module = await importConfigModule(`${moduleUrl.href}?cacheBust=${Date.now()}`);
   const rawConfig = extractConfigExport(module);
   return {
     configPath: resolvedPath,
@@ -2029,6 +2059,58 @@ function toTypeKind(code) {
 function escapeSqlLiteral(value) {
   return value.replace(/'/g, "''");
 }
+function parsePostgresArrayLiteral(text) {
+  const body = text.slice(1, -1).trim();
+  if (!body) return [];
+  const values = [];
+  let current = "";
+  let inQuotes = false;
+  let escaped = false;
+  for (const char of body) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (char === "," && !inQuotes) {
+      values.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  values.push(current);
+  return values.map((value) => value.trim()).filter((value) => value.length > 0);
+}
+function coerceStringArray(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => typeof item === "string" ? item : String(item)).map((item) => item.trim()).filter((item) => item.length > 0);
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) return [];
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return coerceStringArray(parsed);
+      } catch {
+      }
+    }
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+      return parsePostgresArrayLiteral(trimmed);
+    }
+    return trimmed.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+  }
+  return [];
+}
 function buildSchemaArrayLiteral(schemas) {
   const normalized = schemas.length > 0 ? schemas : ["public"];
   const literals = normalized.map((schema) => `'${escapeSqlLiteral(schema)}'`).join(", ");
@@ -2068,8 +2150,10 @@ var PostgresCatalogSnapshotAssembler = class {
   addPrimaryKeyRows(primaryKeyRows) {
     for (const row of primaryKeyRows) {
       const table = this.ensureTable(row.schema_name, row.table_name);
-      table.primaryKey = row.columns;
-      for (const columnName of row.columns) {
+      const primaryKeyColumns = coerceStringArray(row.columns);
+      row.columns = primaryKeyColumns;
+      table.primaryKey = primaryKeyColumns;
+      for (const columnName of primaryKeyColumns) {
         const column = table.columns[columnName];
         if (column) {
           column.isPrimaryKey = true;
@@ -2081,23 +2165,27 @@ var PostgresCatalogSnapshotAssembler = class {
     for (const row of foreignKeyRows) {
       const sourceTable = this.ensureTable(row.source_schema, row.source_table);
       const targetTable = this.ensureTable(row.target_schema, row.target_table);
+      const sourceColumns = coerceStringArray(row.source_columns);
+      const targetColumns = coerceStringArray(row.target_columns);
+      row.source_columns = sourceColumns;
+      row.target_columns = targetColumns;
       const sourceRelationKind = row.source_is_unique ? "one-to-one" : "many-to-one";
       this.upsertRelation(sourceTable, relationKey(row.constraint_name, row.target_table), {
         name: row.constraint_name,
         kind: sourceRelationKind,
-        sourceColumns: row.source_columns,
+        sourceColumns,
         targetSchema: row.target_schema,
         targetModel: row.target_table,
-        targetColumns: row.target_columns
+        targetColumns
       });
       const targetRelationKind = row.source_is_unique ? "one-to-one" : "one-to-many";
       this.upsertRelation(targetTable, relationKey(row.source_table), {
         name: relationKey(row.source_table, row.constraint_name),
         kind: targetRelationKind,
-        sourceColumns: row.target_columns,
+        sourceColumns: targetColumns,
         targetSchema: row.source_schema,
         targetModel: row.source_table,
-        targetColumns: row.source_columns
+        targetColumns: sourceColumns
       });
     }
   }
@@ -2399,7 +2487,7 @@ async function runSchemaGenerator(options = {}) {
 }
 
 // src/cli/index.ts
-function usage() {
+function rootUsage() {
   return [
     "athena-js CLI",
     "",
@@ -2408,12 +2496,42 @@ function usage() {
     "",
     "Examples:",
     "  athena-js generate",
+    "  athena-js generate --config ./athena.config.ts --dry-run",
+    "  athena-js generate --help"
+  ].join("\n");
+}
+function generateUsage() {
+  return [
+    "athena-js generate",
+    "",
+    "Usage:",
+    "  athena-js generate [--config <path>] [--dry-run]",
+    "",
+    "Options:",
+    "  --config <path>  Explicit path to athena.config.ts or athena-js.config.ts",
+    "  --dry-run        Build generated files in memory without writing them to disk",
+    "  -h, --help       Show help for generate",
+    "",
+    "Examples:",
+    "  athena-js generate",
     "  athena-js generate --config ./athena.config.ts --dry-run"
   ].join("\n");
 }
+function usage(topic = "root") {
+  return topic === "generate" ? generateUsage() : rootUsage();
+}
 function parseCommand(argv) {
-  if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
-    return { command: "help" };
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    return { command: "help", topic: "root" };
+  }
+  if (argv[0] === "help") {
+    if (argv.length === 1) {
+      return { command: "help", topic: "root" };
+    }
+    if (argv[1] === "generate") {
+      return { command: "help", topic: "generate" };
+    }
+    throw new Error(`Unknown command "${argv[1]}".`);
   }
   const [command, ...rest] = argv;
   if (command !== "generate") {
@@ -2423,13 +2541,16 @@ function parseCommand(argv) {
   let dryRun = false;
   for (let index = 0; index < rest.length; index += 1) {
     const token = rest[index];
+    if (token === "--help" || token === "-h") {
+      return { command: "help", topic: "generate" };
+    }
     if (token === "--dry-run") {
       dryRun = true;
       continue;
     }
     if (token === "--config") {
       const nextValue = rest[index + 1];
-      if (!nextValue) {
+      if (!nextValue || nextValue.startsWith("-")) {
         throw new Error("Missing value for --config option.");
       }
       configPath = nextValue;
@@ -2444,29 +2565,72 @@ function parseCommand(argv) {
     dryRun
   };
 }
-async function runCLI(argv) {
+function normalizeErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return "Unknown generator error.";
+}
+function extractMissingDatabaseName(message) {
+  const match = message.match(/database "([^"]+)" does not exist/i);
+  return match?.[1];
+}
+function isErrorWithCode(error) {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+function formatGeneratorError(error, configPath) {
+  if (isErrorWithCode(error) && error.code === "3D000") {
+    const message = normalizeErrorMessage(error);
+    const databaseName = extractMissingDatabaseName(message);
+    const databaseLabel = databaseName ? `PostgreSQL database "${databaseName}" does not exist` : "The target PostgreSQL database does not exist";
+    const configLabel = configPath ? `config "${configPath}"` : "the resolved athena config";
+    return new Error(
+      [
+        `${databaseLabel} (code 3D000).`,
+        `Update provider.connectionString (and provider.database, if set) in ${configLabel}, or create that database before running generate.`
+      ].join("\n")
+    );
+  }
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(normalizeErrorMessage(error));
+}
+async function runCLI(argv, runtime = {}) {
+  const log = runtime.log ?? console.log;
+  const runGenerator = runtime.runGenerator ?? runSchemaGenerator;
   const parsed = parseCommand(argv);
   if (parsed.command === "help") {
-    console.log(usage());
+    log(usage(parsed.topic));
     return;
   }
-  const result = await runSchemaGenerator({
-    configPath: parsed.configPath,
-    dryRun: parsed.dryRun
-  });
+  let result;
+  try {
+    result = await runGenerator({
+      configPath: parsed.configPath,
+      dryRun: parsed.dryRun
+    });
+  } catch (error) {
+    throw formatGeneratorError(error, parsed.configPath);
+  }
   if (parsed.dryRun) {
-    console.log(`[dry-run] Generated ${result.files.length} files from ${result.configPath}`);
+    log(`[dry-run] Generated ${result.files.length} files from ${result.configPath}`);
     for (const file of result.files) {
-      console.log(` - ${file.path}`);
+      log(` - ${file.path}`);
     }
     return;
   }
-  console.log(`Generated ${result.writtenFiles.length} files from ${result.configPath}`);
+  log(`Generated ${result.writtenFiles.length} files from ${result.configPath}`);
   for (const filePath of result.writtenFiles) {
-    console.log(` - ${filePath}`);
+    log(` - ${filePath}`);
   }
 }
 
+exports.parseCommand = parseCommand;
 exports.runCLI = runCLI;
+exports.usage = usage;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map