@xylex-group/athena 3.0.2 → 3.1.0

package/dist/{types-BBm-kEBL.d.cts → types-1ztXDgPa.d.cts}

@@ -54,6 +54,21 @@ interface GeneratorOutputTargets {
 }
 type GeneratorOutputPreset = 'legacy' | 'athena-direct';
 type GeneratorOutputFormat = 'define-model' | 'table-builder';
+/**
+ * How existing database/registry artifacts are handled on regenerate.
+ *
+ * - `merge` (default): additive smart merge — append missing imports/keys, preserve custom code
+ * - `skip`: never rewrite existing files (legacy protect behavior)
+ * - `overwrite`: always replace with pure generated content
+ */
+type GeneratorArtifactWritePolicy = 'merge' | 'skip' | 'overwrite';
+/**
+ * Per-kind write policy for protected generator artifacts.
+ */
+interface GeneratorArtifactWriteConfig {
+    database?: GeneratorArtifactWritePolicy;
+    registry?: GeneratorArtifactWritePolicy;
+}
 /**
  * Output configuration including dynamic placeholder aliases.
  */
@@ -62,6 +77,7 @@ interface GeneratorOutputConfig {
     preset?: GeneratorOutputPreset;
     targets?: Partial<GeneratorOutputTargets>;
     placeholderMap?: Record<string, string>;
+    artifactWrite?: GeneratorArtifactWriteConfig;
 }
 /**
  * Normalized output configuration with defaults applied.
@@ -71,6 +87,10 @@ interface NormalizedGeneratorOutputConfig {
     preset: GeneratorOutputPreset;
     targets: GeneratorOutputTargets;
     placeholderMap: Record<string, string>;
+    artifactWrite: {
+        database: GeneratorArtifactWritePolicy;
+        registry: GeneratorArtifactWritePolicy;
+    };
 }
 /**
  * Schemas selected for PostgreSQL introspection. Strings may be comma-separated
@@ -207,6 +227,29 @@ interface RunGeneratorOptions {
     configPath?: string;
     dryRun?: boolean;
     provider?: SchemaIntrospectionProvider;
+    /**
+     * When true (default), ensure/update `athena.config.ts` intelligently:
+     * create when missing, auto-fill schemas when discovery finds more,
+     * skip writes when nothing changed.
+     *
+     * Pass false for pure env-only CI runs that must not touch the config file.
+     */
+    writeConfig?: boolean;
+    /**
+     * Discover live PostgreSQL schemas and expand the effective schema list
+     * used for introspection. Defaults to true.
+     */
+    discoverSchemas?: boolean;
+}
+/**
+ * Summary of intelligent config-file ensure work performed during generate.
+ */
+interface GeneratorConfigEnsureSummary {
+    action: 'created' | 'updated' | 'unchanged' | 'skipped';
+    path: string;
+    schemas: string[];
+    changes: string[];
+    reason?: string;
 }
 /**
  * Generator execution result including files written to disk.
@@ -215,13 +258,30 @@ interface RunGeneratorResult extends GeneratedArtifacts {
     configPath: string;
     config: NormalizedAthenaGeneratorConfig;
     writtenFiles: string[];
+    writtenDetails: WrittenGeneratedArtifact[];
     skippedFiles: SkippedGeneratedArtifact[];
+    /**
+     * Present when generate ran config ensure/sync (even if action is unchanged).
+     */
+    configEnsure?: GeneratorConfigEnsureSummary;
 }
-type SkippedGeneratedArtifactReason = 'protected-existing-file';
+type SkippedGeneratedArtifactReason = 'protected-existing-file' | 'merge-conflict' | 'merge-lint-failed' | 'merge-unparseable' | 'already-current';
+type WrittenGeneratedArtifactReason = 'created' | 'overwritten' | 'merged';
 interface SkippedGeneratedArtifact {
     kind: GeneratorArtifactKind;
     path: string;
     reason: SkippedGeneratedArtifactReason;
+    detail?: string;
+    preservedCustom?: string[];
+    conflicts?: string[];
+    lintErrors?: string[];
+}
+interface WrittenGeneratedArtifact {
+    kind: GeneratorArtifactKind;
+    path: string;
+    reason: WrittenGeneratedArtifactReason;
+    added?: string[];
+    preservedCustom?: string[];
 }
 
-export type { AthenaGeneratorConfig as A, GeneratedArtifacts as G, LoadGeneratorConfigOptions as L, NormalizedAthenaGeneratorConfig as N, RunGeneratorOptions as R, SkippedGeneratedArtifact as S, LoadedGeneratorConfig as a, GeneratorProviderConfig as b, GeneratorExperimentalFlags as c, RunGeneratorResult as d, GeneratedArtifact as e, GeneratorArtifactKind as f, GeneratorFeatureFlags as g, GeneratorFilterConfig as h, GeneratorInternalConfig as i, GeneratorNamingConfig as j, GeneratorOutputConfig as k, GeneratorOutputFormat as l, GeneratorOutputPreset as m, GeneratorOutputTargets as n, GeneratorSchemaSelection as o, GeneratorTableSelection as p, NamingStyle as q, NormalizedGeneratorFilterConfig as r, NormalizedGeneratorOutputConfig as s, SkippedGeneratedArtifactReason as t };
+export type { AthenaGeneratorConfig as A, GeneratedArtifacts as G, LoadGeneratorConfigOptions as L, NormalizedAthenaGeneratorConfig as N, RunGeneratorOptions as R, SkippedGeneratedArtifact as S, LoadedGeneratorConfig as a, GeneratorProviderConfig as b, GeneratorExperimentalFlags as c, RunGeneratorResult as d, GeneratedArtifact as e, GeneratorArtifactKind as f, GeneratorFeatureFlags as g, GeneratorFilterConfig as h, GeneratorInternalConfig as i, GeneratorNamingConfig as j, GeneratorOutputConfig as k, GeneratorOutputFormat as l, GeneratorOutputPreset as m, GeneratorOutputTargets as n, GeneratorSchemaSelection as o, GeneratorTableSelection as p, NamingStyle as q, NormalizedGeneratorFilterConfig as r, NormalizedGeneratorOutputConfig as s, SkippedGeneratedArtifactReason as t, GeneratorConfigEnsureSummary as u };

package/dist/{types-BaAMXCqK.d.ts → types-CccOiXPo.d.ts}

@@ -54,6 +54,21 @@ interface GeneratorOutputTargets {
 }
 type GeneratorOutputPreset = 'legacy' | 'athena-direct';
 type GeneratorOutputFormat = 'define-model' | 'table-builder';
+/**
+ * How existing database/registry artifacts are handled on regenerate.
+ *
+ * - `merge` (default): additive smart merge — append missing imports/keys, preserve custom code
+ * - `skip`: never rewrite existing files (legacy protect behavior)
+ * - `overwrite`: always replace with pure generated content
+ */
+type GeneratorArtifactWritePolicy = 'merge' | 'skip' | 'overwrite';
+/**
+ * Per-kind write policy for protected generator artifacts.
+ */
+interface GeneratorArtifactWriteConfig {
+    database?: GeneratorArtifactWritePolicy;
+    registry?: GeneratorArtifactWritePolicy;
+}
 /**
  * Output configuration including dynamic placeholder aliases.
  */
@@ -62,6 +77,7 @@ interface GeneratorOutputConfig {
     preset?: GeneratorOutputPreset;
     targets?: Partial<GeneratorOutputTargets>;
     placeholderMap?: Record<string, string>;
+    artifactWrite?: GeneratorArtifactWriteConfig;
 }
 /**
  * Normalized output configuration with defaults applied.
@@ -71,6 +87,10 @@ interface NormalizedGeneratorOutputConfig {
     preset: GeneratorOutputPreset;
     targets: GeneratorOutputTargets;
     placeholderMap: Record<string, string>;
+    artifactWrite: {
+        database: GeneratorArtifactWritePolicy;
+        registry: GeneratorArtifactWritePolicy;
+    };
 }
 /**
  * Schemas selected for PostgreSQL introspection. Strings may be comma-separated
@@ -207,6 +227,29 @@ interface RunGeneratorOptions {
     configPath?: string;
     dryRun?: boolean;
     provider?: SchemaIntrospectionProvider;
+    /**
+     * When true (default), ensure/update `athena.config.ts` intelligently:
+     * create when missing, auto-fill schemas when discovery finds more,
+     * skip writes when nothing changed.
+     *
+     * Pass false for pure env-only CI runs that must not touch the config file.
+     */
+    writeConfig?: boolean;
+    /**
+     * Discover live PostgreSQL schemas and expand the effective schema list
+     * used for introspection. Defaults to true.
+     */
+    discoverSchemas?: boolean;
+}
+/**
+ * Summary of intelligent config-file ensure work performed during generate.
+ */
+interface GeneratorConfigEnsureSummary {
+    action: 'created' | 'updated' | 'unchanged' | 'skipped';
+    path: string;
+    schemas: string[];
+    changes: string[];
+    reason?: string;
 }
 /**
  * Generator execution result including files written to disk.
@@ -215,13 +258,30 @@ interface RunGeneratorResult extends GeneratedArtifacts {
     configPath: string;
     config: NormalizedAthenaGeneratorConfig;
     writtenFiles: string[];
+    writtenDetails: WrittenGeneratedArtifact[];
     skippedFiles: SkippedGeneratedArtifact[];
+    /**
+     * Present when generate ran config ensure/sync (even if action is unchanged).
+     */
+    configEnsure?: GeneratorConfigEnsureSummary;
 }
-type SkippedGeneratedArtifactReason = 'protected-existing-file';
+type SkippedGeneratedArtifactReason = 'protected-existing-file' | 'merge-conflict' | 'merge-lint-failed' | 'merge-unparseable' | 'already-current';
+type WrittenGeneratedArtifactReason = 'created' | 'overwritten' | 'merged';
 interface SkippedGeneratedArtifact {
     kind: GeneratorArtifactKind;
     path: string;
     reason: SkippedGeneratedArtifactReason;
+    detail?: string;
+    preservedCustom?: string[];
+    conflicts?: string[];
+    lintErrors?: string[];
+}
+interface WrittenGeneratedArtifact {
+    kind: GeneratorArtifactKind;
+    path: string;
+    reason: WrittenGeneratedArtifactReason;
+    added?: string[];
+    preservedCustom?: string[];
 }
 
-export type { AthenaGeneratorConfig as A, GeneratedArtifacts as G, LoadGeneratorConfigOptions as L, NormalizedAthenaGeneratorConfig as N, RunGeneratorOptions as R, SkippedGeneratedArtifact as S, LoadedGeneratorConfig as a, GeneratorProviderConfig as b, GeneratorExperimentalFlags as c, RunGeneratorResult as d, GeneratedArtifact as e, GeneratorArtifactKind as f, GeneratorFeatureFlags as g, GeneratorFilterConfig as h, GeneratorInternalConfig as i, GeneratorNamingConfig as j, GeneratorOutputConfig as k, GeneratorOutputFormat as l, GeneratorOutputPreset as m, GeneratorOutputTargets as n, GeneratorSchemaSelection as o, GeneratorTableSelection as p, NamingStyle as q, NormalizedGeneratorFilterConfig as r, NormalizedGeneratorOutputConfig as s, SkippedGeneratedArtifactReason as t };
+export type { AthenaGeneratorConfig as A, GeneratedArtifacts as G, LoadGeneratorConfigOptions as L, NormalizedAthenaGeneratorConfig as N, RunGeneratorOptions as R, SkippedGeneratedArtifact as S, LoadedGeneratorConfig as a, GeneratorProviderConfig as b, GeneratorExperimentalFlags as c, RunGeneratorResult as d, GeneratedArtifact as e, GeneratorArtifactKind as f, GeneratorFeatureFlags as g, GeneratorFilterConfig as h, GeneratorInternalConfig as i, GeneratorNamingConfig as j, GeneratorOutputConfig as k, GeneratorOutputFormat as l, GeneratorOutputPreset as m, GeneratorOutputTargets as n, GeneratorSchemaSelection as o, GeneratorTableSelection as p, NamingStyle as q, NormalizedGeneratorFilterConfig as r, NormalizedGeneratorOutputConfig as s, SkippedGeneratedArtifactReason as t, GeneratorConfigEnsureSummary as u };

package/package.json

@@ -218,5 +218,5 @@
       ]
     }
   },
-  "version": "3.0.2"
+  "version": "3.1.0"
 }

package/dist/model-form-Dh0sisdL.d.ts

@@ -1,97 +0,0 @@
-import { d as AthenaGatewayErrorCode, q as AthenaGatewayEndpointPath, r as AthenaGatewayMethod, e as AthenaGatewayErrorDetails, s as AthenaGatewayResponse } from './types-Bltx6iL6.js';
-import { s as AnyModelDef, a as InsertOf, n as RowOf, U as UpdateOf } from './types-B75PdABb.js';
-
-interface AthenaGatewayErrorInput {
-    code: AthenaGatewayErrorCode;
-    message: string;
-    status?: number;
-    endpoint?: AthenaGatewayEndpointPath;
-    method?: AthenaGatewayMethod;
-    requestId?: string;
-    hint?: string;
-    cause?: string;
-}
-/**
- * Canonical error for gateway failures.
- * Holds request context and machine-readable classification.
- */
-declare class AthenaGatewayError extends Error {
-    readonly code: AthenaGatewayErrorCode;
-    readonly status: number;
-    readonly endpoint?: AthenaGatewayEndpointPath;
-    readonly method?: AthenaGatewayMethod;
-    readonly requestId?: string;
-    readonly hint?: string;
-    readonly causeDetail?: string;
-    constructor(input: AthenaGatewayErrorInput);
-    toDetails(): AthenaGatewayErrorDetails;
-    static fromResponse<T>(response: AthenaGatewayResponse<T>, fallback: Omit<AthenaGatewayErrorInput, 'code' | 'message' | 'status'>): AthenaGatewayError;
-}
-declare function isAthenaGatewayError(error: unknown): error is AthenaGatewayError;
-
-type ModelFormNullishMode = 'empty-string' | 'undefined' | 'null';
-type NullishValueByMode = {
-    'empty-string': '';
-    undefined: undefined;
-    null: null;
-};
-type MapNullableToFormValue<TField, TMode extends ModelFormNullishMode> = null extends TField ? Exclude<TField, null> | NullishValueByMode[TMode] : TField;
-/**
- * Form value shape derived from a model insert payload.
- * Nullable fields are remapped to the selected nullish representation.
- */
-type ModelFormValues<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'> = {
-    [K in keyof InsertOf<TModel>]: MapNullableToFormValue<InsertOf<TModel>[K], TMode>;
-};
-/**
- * Alias for deriving form value types from any model contract.
- */
-type FormValuesOf<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'> = ModelFormValues<TModel, TMode>;
-/**
- * Default value shape for form initialization.
- */
-type ModelFormDefaults<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'> = Partial<ModelFormValues<TModel, TMode>>;
-interface ToModelFormDefaultsOptions<TMode extends ModelFormNullishMode = 'empty-string'> {
-    /**
-     * Controls how nullable model values are represented in form defaults.
-     * - `empty-string` (default): `null -> ""`
-     * - `undefined`: `null -> undefined`
-     * - `null`: keeps `null`
-     */
-    nullishMode?: TMode;
-}
-interface ToModelPayloadOptions {
-    /**
-     * Converts `""` into `null` for nullable model fields.
-     * Defaults to `true`.
-     */
-    emptyStringAsNull?: boolean;
-    /**
-     * Omits `undefined` keys from the outgoing payload.
-     * Defaults to `true`.
-     */
-    stripUndefined?: boolean;
-}
-/**
- * Normalizes model data into form-safe defaults using model nullability metadata.
- */
-declare function toModelFormDefaults<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'>(model: TModel, values?: Partial<RowOf<TModel>> | Partial<InsertOf<TModel>> | null, options?: ToModelFormDefaultsOptions<TMode>): ModelFormDefaults<TModel, TMode>;
-/**
- * Normalizes form values back into model-compatible insert/update payloads.
- */
-declare function toModelPayload<TModel extends AnyModelDef>(model: TModel, formValues: Partial<ModelFormValues<TModel, 'empty-string' | 'undefined' | 'null'>>, options?: ToModelPayloadOptions): Partial<InsertOf<TModel>>;
-/**
- * Runtime form adapter bound to a model contract.
- */
-interface ModelFormAdapter<TModel extends AnyModelDef> {
-    model: TModel;
-    toDefaults<TMode extends ModelFormNullishMode = 'empty-string'>(values?: Partial<RowOf<TModel>> | Partial<InsertOf<TModel>> | null, options?: ToModelFormDefaultsOptions<TMode>): ModelFormDefaults<TModel, TMode>;
-    toInsert(values: Partial<ModelFormValues<TModel, 'empty-string' | 'undefined' | 'null'>>, options?: ToModelPayloadOptions): Partial<InsertOf<TModel>>;
-    toUpdate(values: Partial<ModelFormValues<TModel, 'empty-string' | 'undefined' | 'null'>>, options?: ToModelPayloadOptions): Partial<UpdateOf<TModel>>;
-}
-/**
- * Creates a small model-aware adapter for form defaults and payload normalization.
- */
-declare function createModelFormAdapter<TModel extends AnyModelDef>(model: TModel): ModelFormAdapter<TModel>;
-
-export { AthenaGatewayError as A, type FormValuesOf as F, type ModelFormAdapter as M, type ToModelFormDefaultsOptions as T, type ModelFormDefaults as a, type ModelFormNullishMode as b, type ModelFormValues as c, type ToModelPayloadOptions as d, createModelFormAdapter as e, toModelPayload as f, isAthenaGatewayError as i, toModelFormDefaults as t };

package/dist/model-form-oOAJUVd4.d.cts

@@ -1,97 +0,0 @@
-import { d as AthenaGatewayErrorCode, q as AthenaGatewayEndpointPath, r as AthenaGatewayMethod, e as AthenaGatewayErrorDetails, s as AthenaGatewayResponse } from './types-Bltx6iL6.cjs';
-import { s as AnyModelDef, a as InsertOf, n as RowOf, U as UpdateOf } from './types-CgCv5o6R.cjs';
-
-interface AthenaGatewayErrorInput {
-    code: AthenaGatewayErrorCode;
-    message: string;
-    status?: number;
-    endpoint?: AthenaGatewayEndpointPath;
-    method?: AthenaGatewayMethod;
-    requestId?: string;
-    hint?: string;
-    cause?: string;
-}
-/**
- * Canonical error for gateway failures.
- * Holds request context and machine-readable classification.
- */
-declare class AthenaGatewayError extends Error {
-    readonly code: AthenaGatewayErrorCode;
-    readonly status: number;
-    readonly endpoint?: AthenaGatewayEndpointPath;
-    readonly method?: AthenaGatewayMethod;
-    readonly requestId?: string;
-    readonly hint?: string;
-    readonly causeDetail?: string;
-    constructor(input: AthenaGatewayErrorInput);
-    toDetails(): AthenaGatewayErrorDetails;
-    static fromResponse<T>(response: AthenaGatewayResponse<T>, fallback: Omit<AthenaGatewayErrorInput, 'code' | 'message' | 'status'>): AthenaGatewayError;
-}
-declare function isAthenaGatewayError(error: unknown): error is AthenaGatewayError;
-
-type ModelFormNullishMode = 'empty-string' | 'undefined' | 'null';
-type NullishValueByMode = {
-    'empty-string': '';
-    undefined: undefined;
-    null: null;
-};
-type MapNullableToFormValue<TField, TMode extends ModelFormNullishMode> = null extends TField ? Exclude<TField, null> | NullishValueByMode[TMode] : TField;
-/**
- * Form value shape derived from a model insert payload.
- * Nullable fields are remapped to the selected nullish representation.
- */
-type ModelFormValues<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'> = {
-    [K in keyof InsertOf<TModel>]: MapNullableToFormValue<InsertOf<TModel>[K], TMode>;
-};
-/**
- * Alias for deriving form value types from any model contract.
- */
-type FormValuesOf<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'> = ModelFormValues<TModel, TMode>;
-/**
- * Default value shape for form initialization.
- */
-type ModelFormDefaults<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'> = Partial<ModelFormValues<TModel, TMode>>;
-interface ToModelFormDefaultsOptions<TMode extends ModelFormNullishMode = 'empty-string'> {
-    /**
-     * Controls how nullable model values are represented in form defaults.
-     * - `empty-string` (default): `null -> ""`
-     * - `undefined`: `null -> undefined`
-     * - `null`: keeps `null`
-     */
-    nullishMode?: TMode;
-}
-interface ToModelPayloadOptions {
-    /**
-     * Converts `""` into `null` for nullable model fields.
-     * Defaults to `true`.
-     */
-    emptyStringAsNull?: boolean;
-    /**
-     * Omits `undefined` keys from the outgoing payload.
-     * Defaults to `true`.
-     */
-    stripUndefined?: boolean;
-}
-/**
- * Normalizes model data into form-safe defaults using model nullability metadata.
- */
-declare function toModelFormDefaults<TModel extends AnyModelDef, TMode extends ModelFormNullishMode = 'empty-string'>(model: TModel, values?: Partial<RowOf<TModel>> | Partial<InsertOf<TModel>> | null, options?: ToModelFormDefaultsOptions<TMode>): ModelFormDefaults<TModel, TMode>;
-/**
- * Normalizes form values back into model-compatible insert/update payloads.
- */
-declare function toModelPayload<TModel extends AnyModelDef>(model: TModel, formValues: Partial<ModelFormValues<TModel, 'empty-string' | 'undefined' | 'null'>>, options?: ToModelPayloadOptions): Partial<InsertOf<TModel>>;
-/**
- * Runtime form adapter bound to a model contract.
- */
-interface ModelFormAdapter<TModel extends AnyModelDef> {
-    model: TModel;
-    toDefaults<TMode extends ModelFormNullishMode = 'empty-string'>(values?: Partial<RowOf<TModel>> | Partial<InsertOf<TModel>> | null, options?: ToModelFormDefaultsOptions<TMode>): ModelFormDefaults<TModel, TMode>;
-    toInsert(values: Partial<ModelFormValues<TModel, 'empty-string' | 'undefined' | 'null'>>, options?: ToModelPayloadOptions): Partial<InsertOf<TModel>>;
-    toUpdate(values: Partial<ModelFormValues<TModel, 'empty-string' | 'undefined' | 'null'>>, options?: ToModelPayloadOptions): Partial<UpdateOf<TModel>>;
-}
-/**
- * Creates a small model-aware adapter for form defaults and payload normalization.
- */
-declare function createModelFormAdapter<TModel extends AnyModelDef>(model: TModel): ModelFormAdapter<TModel>;
-
-export { AthenaGatewayError as A, type FormValuesOf as F, type ModelFormAdapter as M, type ToModelFormDefaultsOptions as T, type ModelFormDefaults as a, type ModelFormNullishMode as b, type ModelFormValues as c, type ToModelPayloadOptions as d, createModelFormAdapter as e, toModelPayload as f, isAthenaGatewayError as i, toModelFormDefaults as t };

package/dist/pipeline-B8aN2EHe.d.ts

@@ -1,8 +0,0 @@
-import { R as RunGeneratorOptions, d as RunGeneratorResult } from './types-BaAMXCqK.js';
-
-/**
- * End-to-end generator execution: load config, introspect, render, and optionally write files.
- */
-declare function runSchemaGenerator(options?: RunGeneratorOptions): Promise<RunGeneratorResult>;
-
-export { runSchemaGenerator as r };

package/dist/pipeline-D4W-Cc-A.d.cts

@@ -1,8 +0,0 @@
-import { R as RunGeneratorOptions, d as RunGeneratorResult } from './types-BBm-kEBL.cjs';
-
-/**
- * End-to-end generator execution: load config, introspect, render, and optionally write files.
- */
-declare function runSchemaGenerator(options?: RunGeneratorOptions): Promise<RunGeneratorResult>;
-
-export { runSchemaGenerator as r };