@xylex-group/athena 1.6.1 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.6.1`
+current version: `1.7.0`
 `@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
@@ -43,6 +43,51 @@ if (error) {
 }
 ```
 
+### Auth client (Athena Auth server)
+
+If your auth backend is now Athena Auth, you can keep core login/session flows in this SDK:
+
+```ts
+import { createAuthClient } from "@xylex-group/athena";
+
+const auth = createAuthClient({
+  baseUrl: "http://localhost:3001/api/auth",
+  // optional: bearer token if you are not using cookie-based sessions
+  bearerToken: process.env.AUTH_BEARER_TOKEN,
+});
+
+const login = await auth.signIn.email({
+  email: "demo@example.com",
+  password: "super-secret",
+  rememberMe: true,
+});
+
+const session = await auth.getSession();
+const sessions = await auth.listSessions();
+
+// clear one session
+await auth.revokeSession({ token: "session_token_here" });
+// or clear all sessions
+await auth.revokeSessions();
+
+await auth.signOut();
+
+// additional core flows
+await auth.forgetPassword({ email: "demo@example.com", redirectTo: "https://app/reset-password" });
+await auth.resetPassword({ newPassword: "new-secret", token: "reset_token" });
+await auth.verifyEmail({ token: "verify_token", callbackURL: "https://app/verified" });
+await auth.changePassword({ currentPassword: "old-secret", newPassword: "new-secret" });
+await auth.updateUser({ name: "Demo User" });
+
+// escape hatch for any endpoint on your Athena Auth instance
+await auth.request({
+  endpoint: "/ok",
+  query: { ping: "pong" },
+});
+```
+
+Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
+
 ### Typed schema registry (model-first)
 
 You can keep `createClient(...).from<T>(...)` as-is, or opt into a typed registry:
@@ -83,22 +128,46 @@ 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
+
+Schema generation is additive. Existing `createClient(...).from<T>(...)` usage remains valid while teams migrate to generated registry files.
 
-The SDK now includes a project-root generator config system (`athena.config.ts`) and CLI command:
+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`)
+- Multiple schema syncs such as `public` plus `athena`, with schema-safe default output paths
+- 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 +735,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

@@ -291,6 +291,37 @@ function resolvePostgresColumnType(column) {
   }
   return wrapArrayType(baseType, column.arrayDimensions);
 }
+
+// src/generator/schema-selection.ts
+var DEFAULT_POSTGRES_SCHEMAS = ["public"];
+function collectSchemaNames(input) {
+  if (!input) {
+    return [];
+  }
+  const values = typeof input === "string" ? [input] : input;
+  return values.flatMap((value) => String(value).split(","));
+}
+function normalizeSchemaSelection(input) {
+  const schemas = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of collectSchemaNames(input)) {
+    const schema = value.trim();
+    if (!schema || seen.has(schema)) {
+      continue;
+    }
+    seen.add(schema);
+    schemas.push(schema);
+  }
+  return schemas.length > 0 ? schemas : [...DEFAULT_POSTGRES_SCHEMAS];
+}
+function resolveProviderSchemas(providerConfig) {
+  if (providerConfig.kind === "postgres") {
+    return normalizeSchemaSelection(providerConfig.schemas);
+  }
+  return [...DEFAULT_POSTGRES_SCHEMAS];
+}
+
+// src/generator/config.ts
 var DEFAULT_CONFIG_CANDIDATES = [
   "athena.config.ts",
   "athena.config.js",
@@ -300,10 +331,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/{schema_kebab}/{model_kebab}.ts",
+  schema: "athena/schemas/{schema_kebab}.ts",
+  database: "athena/relations.ts",
+  registry: "athena/config.ts"
 };
 var DEFAULT_NAMING = {
   modelType: "pascal",
@@ -331,6 +362,15 @@ function normalizeOutputConfig(output) {
     }
   };
 }
+function normalizeProviderConfig(provider) {
+  if (provider.kind === "postgres") {
+    return {
+      ...provider,
+      schemas: normalizeSchemaSelection(provider.schemas)
+    };
+  }
+  return provider;
+}
 function isAthenaGeneratorConfig(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -340,7 +380,7 @@ function isAthenaGeneratorConfig(value) {
 }
 function normalizeGeneratorConfig(input) {
   return {
-    provider: input.provider,
+    provider: normalizeProviderConfig(input.provider),
     output: normalizeOutputConfig(input.output),
     naming: {
       ...DEFAULT_NAMING,
@@ -550,12 +590,19 @@ export const ${registryConstName} = defineRegistry({
   };
 }
 function assertNoDuplicatePaths(files) {
-  const seen = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Map();
   for (const file of files) {
-    if (seen.has(file.path)) {
-      throw new Error(`Generator output collision detected for path: ${file.path}`);
+    const existing = seen.get(file.path);
+    if (existing) {
+      throw new Error(
+        [
+          `Generator output collision detected for path: ${file.path}`,
+          `Collision: ${existing.kind} and ${file.kind}.`,
+          "When syncing multiple schemas, include a schema placeholder such as {schema} or {schema_kebab} in model/schema output targets."
+        ].join(" ")
+      );
     }
-    seen.add(file.path);
+    seen.set(file.path, file);
   }
 }
 var ArtifactComposer = class {
@@ -2059,8 +2106,73 @@ 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 normalizePostgresCatalogSchemas(schemas) {
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of schemas ?? []) {
+    const schema = value.trim();
+    if (!schema || seen.has(schema)) {
+      continue;
+    }
+    seen.add(schema);
+    normalized.push(schema);
+  }
+  return normalized.length > 0 ? normalized : ["public"];
+}
 function buildSchemaArrayLiteral(schemas) {
-  const normalized = schemas.length > 0 ? schemas : ["public"];
+  const normalized = normalizePostgresCatalogSchemas(schemas);
   const literals = normalized.map((schema) => `'${escapeSqlLiteral(schema)}'`).join(", ");
   return `ARRAY[${literals}]`;
 }
@@ -2098,8 +2210,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;
@@ -2111,23 +2225,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
       });
     }
   }
@@ -2253,12 +2371,14 @@ var PostgresIntrospectionProvider = class {
   backend = "postgresql";
   connectionString;
   database;
+  schemas;
   constructor(options) {
     this.connectionString = options.connectionString;
     this.database = options.database ?? "postgres";
+    this.schemas = normalizePostgresCatalogSchemas(options.schemas);
   }
   async inspect(options) {
-    const schemas = options?.schemas && options.schemas.length > 0 ? options.schemas : ["public"];
+    const schemas = options?.schemas && options.schemas.length > 0 ? normalizePostgresCatalogSchemas(options.schemas) : this.schemas;
     const pool = new pg.Pool({
       connectionString: this.connectionString
     });
@@ -2330,11 +2450,13 @@ var AthenaGatewayPostgresIntrospectionProvider = class {
         type: this.config.backend ?? "postgresql"
       }
     });
+    this.schemas = normalizeSchemaSelection(this.config.schemas);
   }
   backend = "postgresql";
   client;
+  schemas;
   async inspect(options) {
-    const schemas = options?.schemas && options.schemas.length > 0 ? options.schemas : this.config.schemas && this.config.schemas.length > 0 ? this.config.schemas : ["public"];
+    const schemas = options?.schemas && options.schemas.length > 0 ? normalizeSchemaSelection(options.schemas) : this.schemas;
     const catalogClient = new AthenaGatewayCatalogClient(this.client);
     const queries = buildGatewayCatalogQueries(schemas);
     const [columnRows, enumMap, primaryKeyRows, foreignKeyRows] = await Promise.all([
@@ -2370,7 +2492,8 @@ var ScyllaIntrospectionProvider = class {
 function createPostgresProvider(config) {
   return createPostgresIntrospectionProvider({
     connectionString: config.connectionString,
-    database: config.database
+    database: config.database,
+    schemas: normalizeSchemaSelection(config.schemas)
   });
 }
 function resolveGeneratorProvider(providerConfig, experimentalFlags) {
@@ -2392,12 +2515,6 @@ function resolveGeneratorProvider(providerConfig, experimentalFlags) {
 }
 
 // src/generator/pipeline.ts
-function extractProviderSchemas(providerConfig) {
-  if (!("schemas" in providerConfig) || !providerConfig.schemas || providerConfig.schemas.length === 0) {
-    return void 0;
-  }
-  return providerConfig.schemas;
-}
 async function writeArtifacts(files, cwd) {
   const writtenFiles = [];
   for (const file of files) {
@@ -2417,7 +2534,7 @@ async function runSchemaGenerator(options = {}) {
   const { configPath, config } = await loadGeneratorConfig(configOptions);
   const provider = options.provider ?? resolveGeneratorProvider(config.provider, config.experimental);
   const snapshot = await provider.inspect({
-    schemas: extractProviderSchemas(config.provider)
+    schemas: resolveProviderSchemas(config.provider)
   });
   const generated = generateArtifactsFromSnapshot(snapshot, config);
   const writtenFiles = options.dryRun ? [] : await writeArtifacts(generated.files, cwd);
@@ -2429,7 +2546,7 @@ async function runSchemaGenerator(options = {}) {
 }
 
 // src/cli/index.ts
-function usage() {
+function rootUsage() {
   return [
     "athena-js CLI",
     "",
@@ -2438,12 +2555,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") {
@@ -2453,13 +2600,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;
@@ -2474,29 +2624,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