@omnifyjp/ts 5.0.5 → 5.1.0

package/dist/php/audit-config-generator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generates `config/omnify.php` — Laravel runtime config for the audit-log
+ * feature.
+ *
+ * The trait reads `config('omnify.audit.logExclude')`, `config('omnify.audit.logQueue')`,
+ * and `config('omnify.audit.logRetention')` at request time. We emit those
+ * values from the resolved schemas.json so the trait + Audit model stay in
+ * sync with whatever the user declared in `omnify.yaml`.
+ *
+ * Each value is wrapped in `env(...)` so operators can override per
+ * environment without re-running codegen — production might use a longer
+ * retention than dev, or a dedicated audits queue, without touching YAML.
+ */
+import { SchemaReader } from './schema-reader.js';
+import type { GeneratedFile, PhpConfig } from './types.js';
+/** Generate config/omnify.php with audit-log settings. */
+export declare function generateAuditConfig(reader: SchemaReader, config: PhpConfig): GeneratedFile[];

package/dist/php/audit-config-generator.js

@@ -0,0 +1,70 @@
+/**
+ * Generates `config/omnify.php` — Laravel runtime config for the audit-log
+ * feature.
+ *
+ * The trait reads `config('omnify.audit.logExclude')`, `config('omnify.audit.logQueue')`,
+ * and `config('omnify.audit.logRetention')` at request time. We emit those
+ * values from the resolved schemas.json so the trait + Audit model stay in
+ * sync with whatever the user declared in `omnify.yaml`.
+ *
+ * Each value is wrapped in `env(...)` so operators can override per
+ * environment without re-running codegen — production might use a longer
+ * retention than dev, or a dedicated audits queue, without touching YAML.
+ */
+import { baseFile } from './types.js';
+/** Render a JS string as a single-quoted PHP string literal. PHP accepts
+ *  both quoting styles, but single quotes are the idiomatic choice for
+ *  plain strings (no variable interpolation, no escape processing) and
+ *  match the rest of the generator's output. Embedded single quotes and
+ *  backslashes are escaped per PHP single-quoted-string rules. */
+function phpStr(s) {
+    return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/** Generate config/omnify.php with audit-log settings. */
+export function generateAuditConfig(reader, config) {
+    if (!reader.hasAuditLog())
+        return [];
+    const auditCfg = reader.getAuditConfig();
+    const excludes = auditCfg?.logExclude ?? [];
+    const retention = auditCfg?.logRetention ?? '';
+    const queue = auditCfg?.logQueue ?? '';
+    const excludeLines = excludes.length > 0
+        ? excludes.map((c) => `            ${phpStr(c)},`).join('\n')
+        : '';
+    const configPath = config.rootPath
+        ? `${config.rootPath}/config/omnify.php`
+        : 'config/omnify.php';
+    const content = `<?php
+
+// Auto-generated by Omnify. DO NOT EDIT.
+//
+// This file mirrors the \`audit:\` block from omnify.yaml so the
+// HasOmnifyAuditLog trait, WriteAuditLog job, and Audit model can read
+// runtime settings via Laravel's config(). Each value can be overridden
+// per environment via the env() variables below.
+
+return [
+    'audit' => [
+        // Sensitive columns scrubbed from old_values / new_values BEFORE
+        // any audit row is written. Per-schema \`options.audit.logExclude\`
+        // adds to this list at runtime — they are NOT a replacement.
+        'logExclude' => [
+${excludeLines}
+        ],
+
+        // Prunable retention period (e.g. "90d", "12w", "6m", "1y").
+        // Empty string keeps audits forever (no scheduled prune).
+        // Override per environment with OMNIFY_AUDIT_RETENTION.
+        'logRetention' => env('OMNIFY_AUDIT_RETENTION', ${phpStr(retention)}),
+
+        // Laravel queue name for WriteAuditLog dispatch. Empty string
+        // forces synchronous dispatch — only acceptable in dev or for
+        // very low-traffic apps. Production should set this to a queue
+        // name backed by a real driver (redis, sqs, etc.).
+        // Override per environment with OMNIFY_AUDIT_QUEUE.
+        'logQueue' => env('OMNIFY_AUDIT_QUEUE', ${phpStr(queue)}),
+    ],
+];
+`;
+    return [baseFile(configPath, content)];
+}

package/dist/php/audit-observer-generator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generates the audit-log persistence layer:
+ *   - app/Jobs/WriteAuditLog.php — queued (or sync) job that inserts a
+ *     prepared audit payload into the audits table.
+ *   - app/Models/Audit.php — Eloquent model with polymorphic auditable +
+ *     user relations and Prunable retention support.
+ *
+ * The trait (HasOmnifyAuditLog) does ALL Auth + Request + scrub work on
+ * the request thread, so the job's only responsibility is the insert.
+ * That's deliberate: workers run with no Auth context, no Request facade,
+ * and no session — anything captured at job HANDLE time would be wrong.
+ *
+ * The Audit model uses Laravel's Prunable trait so `php artisan model:prune`
+ * (scheduled hourly / daily by the consumer) deletes rows older than the
+ * configured retention. When `omnify.audit.retention` is empty the
+ * `prunable()` query matches no rows (audits are kept forever).
+ */
+import { SchemaReader } from './schema-reader.js';
+import type { GeneratedFile, PhpConfig } from './types.js';
+/** Generate the WriteAuditLog job + Audit model. */
+export declare function generateAuditObserver(reader: SchemaReader, config: PhpConfig): GeneratedFile[];

package/dist/php/audit-observer-generator.js

@@ -0,0 +1,226 @@
+/**
+ * Generates the audit-log persistence layer:
+ *   - app/Jobs/WriteAuditLog.php — queued (or sync) job that inserts a
+ *     prepared audit payload into the audits table.
+ *   - app/Models/Audit.php — Eloquent model with polymorphic auditable +
+ *     user relations and Prunable retention support.
+ *
+ * The trait (HasOmnifyAuditLog) does ALL Auth + Request + scrub work on
+ * the request thread, so the job's only responsibility is the insert.
+ * That's deliberate: workers run with no Auth context, no Request facade,
+ * and no session — anything captured at job HANDLE time would be wrong.
+ *
+ * The Audit model uses Laravel's Prunable trait so `php artisan model:prune`
+ * (scheduled hourly / daily by the consumer) deletes rows older than the
+ * configured retention. When `omnify.audit.retention` is empty the
+ * `prunable()` query matches no rows (audits are kept forever).
+ */
+import { baseFile } from './types.js';
+/** Generate the WriteAuditLog job + Audit model. */
+export function generateAuditObserver(reader, config) {
+    // Generation is gated by index.ts; defensively no-op if called when the
+    // feature is off so callers can't accidentally emit dead infra.
+    if (!reader.hasAuditLog())
+        return [];
+    const files = [];
+    files.push(generateWriteAuditLogJob(config));
+    files.push(generateAuditModel(reader, config));
+    return files;
+}
+function generateWriteAuditLogJob(config) {
+    const modelNamespace = config.models.namespace;
+    // Jobs always live at the conventional `app/Jobs/...` location. The
+    // path is rooted under `config.rootPath` so monorepo setups (Laravel
+    // in a subdir) still write to the right place.
+    const jobsPath = config.rootPath
+        ? `${config.rootPath}/app/Jobs`
+        : 'app/Jobs';
+    const jobsNamespace = 'App\\Jobs';
+    const content = `<?php
+
+namespace ${jobsNamespace};
+
+/**
+ * Persists a single audit-log row to the audits table.
+ *
+ * The trait builds the payload on the request thread (so Auth + Request
+ * data is captured correctly) and dispatches this job. The handler does
+ * nothing but the insert — it is intentionally trivial so it can run on
+ * cheap workers and survive retries cleanly.
+ *
+ * DO NOT EDIT — auto-generated by Omnify.
+ *
+ * @generated by omnify
+ */
+
+use ${modelNamespace}\\Audit;
+use Illuminate\\Bus\\Queueable;
+use Illuminate\\Contracts\\Queue\\ShouldQueue;
+use Illuminate\\Foundation\\Bus\\Dispatchable;
+use Illuminate\\Queue\\InteractsWithQueue;
+use Illuminate\\Queue\\SerializesModels;
+
+class WriteAuditLog implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    /**
+     * @param  array<string, mixed>  $payload  Pre-scrubbed insert row
+     *                                         (auditable_type, auditable_id,
+     *                                         event, old_values, new_values,
+     *                                         user_type, user_id, url,
+     *                                         ip_address, user_agent, tags,
+     *                                         created_at).
+     */
+    public function __construct(public array $payload)
+    {
+    }
+
+    /**
+     * Default retry behaviour: try 3 times with 5-second backoff between
+     * attempts. Audit rows are append-only and idempotent at the row
+     * level (no unique constraint trips on retry), so retries are safe.
+     *
+     * @return array<int, int>
+     */
+    public function backoff(): array
+    {
+        return [5, 30, 120];
+    }
+
+    public int $tries = 3;
+
+    public function handle(): void
+    {
+        Audit::create($this->payload);
+    }
+}
+`;
+    return baseFile(`${jobsPath}/WriteAuditLog.php`, content);
+}
+function generateAuditModel(reader, config) {
+    const modelNamespace = config.models.namespace;
+    const retention = reader.getAuditRetention();
+    // The retention parser is embedded in the model so the consumer can
+    // change `omnify.audit.retention` (or its environment variable) without
+    // re-generating. Empty retention = keep forever (prunable matches nothing).
+    const content = `<?php
+
+namespace ${modelNamespace};
+
+/**
+ * Audit history row.
+ *
+ * Polymorphic on both \`auditable_*\` (the model whose state changed) and
+ * \`user_*\` (the actor who triggered the change). No FK constraints on
+ * either side so records survive when the source row is hard-deleted —
+ * which is the whole point of an audit trail. Append-only: \`updated_at\`
+ * is NOT present on this table.
+ *
+ * Uses Laravel's Prunable trait. Wire it up in your scheduler:
+ *
+ *     // app/Console/Kernel.php
+ *     \\$schedule->command('model:prune', ['--model' => [\\App\\Models\\Audit::class]])->daily();
+ *
+ * Set retention via the \`omnify.audit.logRetention\` config key
+ * (e.g. \`90d\`, \`12w\`, \`6m\`, \`1y\`). An empty string disables prune
+ * (audits are kept forever).
+ *
+ * DO NOT EDIT — auto-generated by Omnify.
+ *
+ * @generated by omnify
+ */
+
+use Illuminate\\Database\\Eloquent\\Builder;
+use Illuminate\\Database\\Eloquent\\Model;
+use Illuminate\\Database\\Eloquent\\Prunable;
+use Illuminate\\Database\\Eloquent\\Relations\\MorphTo;
+
+class Audit extends Model
+{
+    use Prunable;
+
+    /** Audits are append-only — no \`updated_at\` column on this table. */
+    public $timestamps = false;
+
+    /** @var list<string> */
+    protected $fillable = [
+        'auditable_type',
+        'auditable_id',
+        'event',
+        'old_values',
+        'new_values',
+        'user_type',
+        'user_id',
+        'url',
+        'ip_address',
+        'user_agent',
+        'tags',
+        'created_at',
+    ];
+
+    /** @var array<string, string> */
+    protected $casts = [
+        'old_values' => 'array',
+        'new_values' => 'array',
+        'created_at' => 'datetime',
+    ];
+
+    /**
+     * The audited record. \`auditable_id\` is unconstrained so the audit
+     * row survives a hard-delete of the source row.
+     */
+    public function auditable(): MorphTo
+    {
+        return $this->morphTo();
+    }
+
+    /**
+     * The actor who triggered the change. Null \`user_*\` columns
+     * indicate a system-driven write (CLI, scheduled job, internal API).
+     */
+    public function user(): MorphTo
+    {
+        return $this->morphTo();
+    }
+
+    /**
+     * Prunable scope. Reads \`omnify.audit.logRetention\` at runtime so the
+     * consumer can change retention without regenerating code.
+     *
+     *   - \`90d\` → 90 days
+     *   - \`12w\` → 12 weeks
+     *   - \`6m\`  → 6 months
+     *   - \`1y\`  → 1 year
+     *
+     * Empty / unparseable retention → matches no rows (kept forever).
+     */
+    public function prunable(): Builder
+    {
+        $retention = (string) config('omnify.audit.logRetention', ${JSON.stringify(retention)});
+        if ($retention === '') {
+            return static::query()->whereRaw('1 = 0');
+        }
+
+        if (!preg_match('/^(\\\\d+)([dwmy])$/', $retention, $m)) {
+            // Misconfigured retention — fail safe by keeping all rows
+            // rather than silently deleting based on a guessed period.
+            return static::query()->whereRaw('1 = 0');
+        }
+
+        $n = (int) $m[1];
+        $cutoff = match ($m[2]) {
+            'd' => now()->subDays($n),
+            'w' => now()->subWeeks($n),
+            'm' => now()->subMonths($n),
+            'y' => now()->subYears($n),
+        };
+
+        return static::query()->where('created_at', '<', $cutoff);
+    }
+}
+`;
+    // Audit model lives next to the rest of the generated models so
+    // morphTo's class resolution finds it via the standard namespace.
+    return baseFile(`${config.models.path}/Audit.php`, content);
+}

package/dist/php/audit-trait-generator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generates the HasOmnifyAuditLog trait for models with audit-log opt-in.
+ *
+ * The trait is the single hook point that connects every audited Eloquent
+ * model to the central `audits` history table. Adding `use HasOmnifyAuditLog;`
+ * to a model makes it record `created` / `updated` / `deleted` / `restored`
+ * events, with dirty-only diffing on update and sensitive-column scrubbing
+ * before serialization.
+ *
+ * Performance design (audit-log is a hot path on every write):
+ *   - WriteAuditLog is dispatched as a queued job when `omnify.audit.queue`
+ *     is non-empty. The web request returns immediately; the audit row is
+ *     inserted by a worker. Sync fallback is only used in dev / low-traffic
+ *     mode (queue == "").
+ *   - Auth, URL, IP, and User-Agent are captured at DISPATCH time, not at
+ *     job HANDLE time — workers have no Auth context and no Request facade.
+ *   - Updated events skip dispatch entirely when `getDirty()` is empty
+ *     (re-saves with no real changes don't emit phantom audit rows).
+ *   - Sensitive columns listed in `$auditExclude` are stripped from
+ *     `old_values` / `new_values` BEFORE the JSON payload is built, so a
+ *     stolen audits dump can't leak passwords or two-factor secrets.
+ *   - String columns are truncated to fit the table schema (`url` 2048,
+ *     `user_agent` 1023, `tags` 255) so a hostile UA header can't blow up
+ *     the insert with a row-too-large error.
+ *   - `Model::withoutAudit(fn() => ...)` lets seeders / migrations / batch
+ *     imports temporarily disable auditing for bulk writes that would
+ *     otherwise dispatch hundreds of thousands of jobs.
+ */
+import type { GeneratedFile, PhpConfig } from './types.js';
+/** Generate the HasOmnifyAuditLog trait. */
+export declare function generateAuditTrait(config: PhpConfig): GeneratedFile[];

package/dist/php/audit-trait-generator.js

@@ -0,0 +1,197 @@
+/**
+ * Generates the HasOmnifyAuditLog trait for models with audit-log opt-in.
+ *
+ * The trait is the single hook point that connects every audited Eloquent
+ * model to the central `audits` history table. Adding `use HasOmnifyAuditLog;`
+ * to a model makes it record `created` / `updated` / `deleted` / `restored`
+ * events, with dirty-only diffing on update and sensitive-column scrubbing
+ * before serialization.
+ *
+ * Performance design (audit-log is a hot path on every write):
+ *   - WriteAuditLog is dispatched as a queued job when `omnify.audit.queue`
+ *     is non-empty. The web request returns immediately; the audit row is
+ *     inserted by a worker. Sync fallback is only used in dev / low-traffic
+ *     mode (queue == "").
+ *   - Auth, URL, IP, and User-Agent are captured at DISPATCH time, not at
+ *     job HANDLE time — workers have no Auth context and no Request facade.
+ *   - Updated events skip dispatch entirely when `getDirty()` is empty
+ *     (re-saves with no real changes don't emit phantom audit rows).
+ *   - Sensitive columns listed in `$auditExclude` are stripped from
+ *     `old_values` / `new_values` BEFORE the JSON payload is built, so a
+ *     stolen audits dump can't leak passwords or two-factor secrets.
+ *   - String columns are truncated to fit the table schema (`url` 2048,
+ *     `user_agent` 1023, `tags` 255) so a hostile UA header can't blow up
+ *     the insert with a row-too-large error.
+ *   - `Model::withoutAudit(fn() => ...)` lets seeders / migrations / batch
+ *     imports temporarily disable auditing for bulk writes that would
+ *     otherwise dispatch hundreds of thousands of jobs.
+ */
+import { baseFile, resolveGlobalTraitPath, resolveGlobalTraitNamespace, } from './types.js';
+/** Generate the HasOmnifyAuditLog trait. */
+export function generateAuditTrait(config) {
+    const traitsNamespace = resolveGlobalTraitNamespace(config, config.models.baseNamespace + '\\Traits');
+    const modelNamespace = config.models.namespace;
+    const content = `<?php
+
+namespace ${traitsNamespace};
+
+/**
+ * Trait that records every Eloquent lifecycle event into the central
+ * audits history table. Apply via \`use HasOmnifyAuditLog;\` on any model
+ * whose schema has \`options.audit.log: true\` (or when the global
+ * \`audit.log\` flag is enabled).
+ *
+ * DO NOT EDIT — auto-generated by Omnify. Any manual changes are lost on
+ * the next \`omnify generate\` run.
+ *
+ * @generated by omnify
+ */
+
+use ${modelNamespace}\\Audit;
+use Illuminate\\Support\\Facades\\Auth;
+use Illuminate\\Support\\Str;
+
+trait HasOmnifyAuditLog
+{
+    /**
+     * Per-class kill switch flipped by withoutAudit(). Keyed by class so
+     * disabling on one model doesn't accidentally silence another running
+     * inside the same callback.
+     *
+     * @var array<class-string, bool>
+     */
+    protected static array $omnifyAuditingDisabled = [];
+
+    /**
+     * Eloquent boot hook. Wires the four model events into the audit
+     * recorder. Restored is gated on a softDelete-capable model; calling
+     * \`static::restored\` on a non-softDelete model is a no-op so this is
+     * safe across the board.
+     */
+    public static function bootHasOmnifyAuditLog(): void
+    {
+        static::created(function ($model) {
+            $model->writeOmnifyAudit('created', null, $model->getAttributes());
+        });
+        static::updated(function ($model) {
+            $dirty = $model->getDirty();
+            if (empty($dirty)) {
+                return;
+            }
+            $old = array_intersect_key($model->getOriginal(), $dirty);
+            $model->writeOmnifyAudit('updated', $old, $dirty);
+        });
+        static::deleted(function ($model) {
+            $event = method_exists($model, 'isForceDeleting') && $model->isForceDeleting()
+                ? 'deleted'
+                : (method_exists($model, 'trashed') ? 'soft_deleted' : 'deleted');
+            $model->writeOmnifyAudit($event, $model->getOriginal(), null);
+        });
+        if (method_exists(static::class, 'restored')) {
+            static::restored(function ($model) {
+                $model->writeOmnifyAudit('restored', null, $model->getAttributes());
+            });
+        }
+    }
+
+    /**
+     * Build the audit payload and dispatch it. All Auth / Request capture
+     * happens here on the request thread, so the worker only needs to
+     * persist the row.
+     *
+     * @param  array<string, mixed>|null  $oldValues
+     * @param  array<string, mixed>|null  $newValues
+     */
+    protected function writeOmnifyAudit(string $event, ?array $oldValues, ?array $newValues): void
+    {
+        if (static::$omnifyAuditingDisabled[static::class] ?? false) {
+            return;
+        }
+
+        $exclude = array_unique(array_merge(
+            (array) config('omnify.audit.logExclude', []),
+            (array) (static::$auditExclude ?? [])
+        ));
+        if (!empty($exclude)) {
+            $flip = array_flip($exclude);
+            if ($oldValues !== null) {
+                $oldValues = array_diff_key($oldValues, $flip);
+            }
+            if ($newValues !== null) {
+                $newValues = array_diff_key($newValues, $flip);
+            }
+        }
+
+        $request = function_exists('request') ? request() : null;
+        $user = Auth::user();
+        $tags = static::$auditTags ?? [];
+
+        $payload = [
+            'auditable_type' => $this->getMorphClass(),
+            'auditable_id' => $this->getKey(),
+            'event' => $event,
+            'old_values' => $oldValues,
+            'new_values' => $newValues,
+            'user_type' => $user ? $user->getMorphClass() : null,
+            'user_id' => $user ? $user->getKey() : null,
+            'url' => $request ? Str::limit($request->fullUrl(), 2048, '') : null,
+            'ip_address' => $request ? $request->ip() : null,
+            'user_agent' => $request ? Str::limit((string) $request->userAgent(), 1023, '') : null,
+            'tags' => !empty($tags) ? Str::limit(implode(',', (array) $tags), 255, '') : null,
+            'created_at' => now(),
+        ];
+
+        $queue = (string) config('omnify.audit.logQueue', '');
+        if ($queue !== '') {
+            \\App\\Jobs\\WriteAuditLog::dispatch($payload)->onQueue($queue);
+        } else {
+            \\App\\Jobs\\WriteAuditLog::dispatchSync($payload);
+        }
+    }
+
+    /**
+     * Run \`$callback\` with audit-log dispatch suppressed for THIS model
+     * class. Use for seeders, bulk imports, and migration data fixups
+     * where you don't want hundreds of thousands of audit rows. Always
+     * restores the previous state, even on exception.
+     *
+     * @template T
+     * @param  callable(): T  $callback
+     * @return T
+     */
+    public static function withoutAudit(callable $callback): mixed
+    {
+        $prev = static::$omnifyAuditingDisabled[static::class] ?? false;
+        static::$omnifyAuditingDisabled[static::class] = true;
+        try {
+            return $callback();
+        } finally {
+            static::$omnifyAuditingDisabled[static::class] = $prev;
+        }
+    }
+
+    /**
+     * Direct helper so external code can persist an audit row without
+     * going through Eloquent events (e.g. recording a sensitive admin
+     * action that's not a model write). Routed through the same job
+     * pipeline so retention + queue config still apply.
+     *
+     * @param  array<string, mixed>|null  $oldValues
+     * @param  array<string, mixed>|null  $newValues
+     */
+    public function recordAudit(string $event, ?array $oldValues = null, ?array $newValues = null): void
+    {
+        $this->writeOmnifyAudit($event, $oldValues, $newValues);
+    }
+
+    /** Eloquent relation back to every audit row that targets this model. */
+    public function audits(): \\Illuminate\\Database\\Eloquent\\Relations\\MorphMany
+    {
+        return $this->morphMany(Audit::class, 'auditable');
+    }
+}
+`;
+    return [
+        baseFile(resolveGlobalTraitPath(config, 'HasOmnifyAuditLog.php', config.models.basePath + '/Traits'), content),
+    ];
+}

package/dist/php/index.js

@@ -25,6 +25,9 @@ import { generatePolicies } from './policy-generator.js';
 import { generateFileModels } from './file-model-generator.js';
 import { generateFileTrait } from './file-trait-generator.js';
 import { generateFileCleanup } from './file-cleanup-generator.js';
+import { generateAuditTrait } from './audit-trait-generator.js';
+import { generateAuditObserver } from './audit-observer-generator.js';
+import { generateAuditConfig } from './audit-config-generator.js';
 import { generateSchemaConfig } from './schema-config-generator.js';
 import { generateTranslatableConfig } from './translatable-config-generator.js';
 import { baseFile } from './types.js';
@@ -57,6 +60,17 @@ export function generatePhp(data, overrides) {
         files.push(...generateFileFactory(reader, config));
         files.push(...generateFileCleanup(reader, config));
     }
+    // Audit-log infrastructure (only when at least one schema opts in,
+    // either via global `audit.log: true` or per-schema override).
+    // Emits the trait, the queued WriteAuditLog job, the Audit model,
+    // and the runtime config that powers them. The audits TABLE itself
+    // is emitted by omnify-go (synthesized once globally) — this layer
+    // is purely the application-level codegen.
+    if (reader.hasAuditLog()) {
+        files.push(...generateAuditTrait(config));
+        files.push(...generateAuditObserver(reader, config));
+        files.push(...generateAuditConfig(reader, config));
+    }
     // CRUD API files (only for schemas with options.api)
     if (reader.hasApiSchemas()) {
         files.push(...generateSchemaConfig(reader, config));

package/dist/php/model-generator.js

@@ -64,11 +64,17 @@ function generateBaseModel(name, schema, reader, config) {
         const prop = properties[p];
         return prop && prop['type'] === 'File';
     });
-    const imports = buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable, hasTranslatable, properties, needsUuidTrait, needsUlidTrait, hasNestedSet, config.nestedset.namespace, hasFiles, modelNamespace, localesNamespace, traitsNamespace, sharedModelsNamespace, config);
+    // Audit-log opt-in (folded global default + per-schema override).
+    // Drives the `use HasOmnifyAuditLog;` import + trait declaration AND
+    // the per-schema `$auditExclude` / `$auditTags` static properties on
+    // the generated base model.
+    const hasAuditLog = reader.isAuditLogEnabled(name);
+    const imports = buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable, hasTranslatable, properties, needsUuidTrait, needsUlidTrait, hasNestedSet, config.nestedset.namespace, hasFiles, modelNamespace, localesNamespace, traitsNamespace, sharedModelsNamespace, config, hasAuditLog);
     const docProperties = buildDocProperties(properties, expandedProperties, propertyOrder);
     const baseClass = isAuthenticatable ? 'Authenticatable' : 'BaseModel';
     const implementsClause = hasTranslatable ? ' implements TranslatableContract' : '';
-    const traits = buildTraits(hasSoftDelete, isAuthenticatable, hasTranslatable, needsUuidTrait, needsUlidTrait, hasNestedSet, hasFiles);
+    const traits = buildTraits(hasSoftDelete, isAuthenticatable, hasTranslatable, needsUuidTrait, needsUlidTrait, hasNestedSet, hasFiles, hasAuditLog);
+    const auditLogProperties = buildAuditLogProperties(name, reader);
     const fillable = buildFillable(properties, expandedProperties, propertyOrder);
     const hidden = buildHidden(properties, expandedProperties, propertyOrder);
     const appends = buildAppends(expandedProperties);
@@ -174,7 +180,7 @@ ${appends}    ];
         return [
 ${casts}        ];
     }
-${relations}${accessors}${fileAccessors}${auditSection}${nestedSetMethod}
+${auditLogProperties}${relations}${accessors}${fileAccessors}${auditSection}${nestedSetMethod}
 }
 `;
     return baseFile(resolveModularBasePath(config, name, 'Models', `${modelName}BaseModel.php`, config.models.basePath), content);
@@ -229,7 +235,7 @@ ${traits.join('\n')}
 `;
     return userFile(`${config.models.path}/${modelName}.php`, content);
 }
-function buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable, hasTranslatable, properties, needsUuidTrait = false, needsUlidTrait = false, hasNestedSet = false, nestedSetNamespace = 'Aimeos\\Nestedset', hasFiles = false, modelNamespace = '', localesNamespace = '', traitsNamespace = '', sharedModelsNamespace = '', config) {
+function buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable, hasTranslatable, properties, needsUuidTrait = false, needsUlidTrait = false, hasNestedSet = false, nestedSetNamespace = 'Aimeos\\Nestedset', hasFiles = false, modelNamespace = '', localesNamespace = '', traitsNamespace = '', sharedModelsNamespace = '', config, hasAuditLog = false) {
     const lines = [];
     // Import BaseModel from shared namespace when in modular mode
     if (sharedModelsNamespace && sharedModelsNamespace !== baseNamespace && !isAuthenticatable) {
@@ -268,6 +274,16 @@ function buildImports(baseNamespace, modelName, hasSoftDelete, isAuthenticatable
             lines.push(`use ${modelNamespace}\\File;`);
         }
     }
+    if (hasAuditLog) {
+        // HasOmnifyAuditLog is a global Omnify trait emitted by
+        // audit-trait-generator.ts. Same global-traits placement as HasFiles
+        // so consumers can update the trait in place without per-schema
+        // duplication.
+        const auditTraitsNs = config
+            ? resolveGlobalTraitNamespace(config, baseNamespace + '\\Traits')
+            : (traitsNamespace || baseNamespace + '\\Traits');
+        lines.push(`use ${auditTraitsNs}\\HasOmnifyAuditLog;`);
+    }
     if (hasSoftDelete) {
         lines.push('use Illuminate\\Database\\Eloquent\\SoftDeletes;');
     }
@@ -321,11 +337,13 @@ function buildDocProperties(properties, expandedProperties, propertyOrder) {
     }
     return lines.length === 0 ? '' : lines.join('\n') + '\n';
 }
-function buildTraits(hasSoftDelete, isAuthenticatable, hasTranslatable, needsUuidTrait = false, needsUlidTrait = false, hasNestedSet = false, hasFiles = false) {
+function buildTraits(hasSoftDelete, isAuthenticatable, hasTranslatable, needsUuidTrait = false, needsUlidTrait = false, hasNestedSet = false, hasFiles = false, hasAuditLog = false) {
     const lines = [];
     lines.push('    use HasLocalizedDisplayName;');
     if (hasFiles)
         lines.push('    use HasFiles;');
+    if (hasAuditLog)
+        lines.push('    use HasOmnifyAuditLog;');
     if (needsUuidTrait)
         lines.push('    use HasUuids;');
     if (needsUlidTrait)
@@ -730,6 +748,54 @@ function buildNestedSetParentIdMethod(parentColumn) {
     }
 `;
 }
+/**
+ * Emits per-schema audit-log static properties on the base model:
+ *   - `$auditExclude` is the merged scrub list (global defaults +
+ *     per-schema additions) — read by HasOmnifyAuditLog at write time
+ *     so sensitive columns are stripped from old_values / new_values
+ *     BEFORE serialization.
+ *   - `$auditTags` is the static tag list applied to every audit row
+ *     from this model; useful for grouping (e.g. ["billing"]).
+ *
+ * Empty arrays are omitted entirely so the trait falls through to its
+ * own static defaults — keeps the generated PHP minimal.
+ */
+function buildAuditLogProperties(schemaName, reader) {
+    if (!reader.isAuditLogEnabled(schemaName))
+        return '';
+    const excludes = reader.getAuditExcludesFor(schemaName);
+    const tags = reader.getAuditTagsFor(schemaName);
+    const parts = [];
+    if (excludes.length > 0) {
+        const lines = excludes.map((c) => `        ${JSON.stringify(c).replace(/"/g, "'")},`).join('\n');
+        parts.push(`
+    /**
+     * Columns scrubbed from old_values / new_values BEFORE the audit row
+     * is built. Merged at runtime with the global \`config('omnify.audit.logExclude')\`
+     * defaults — they are NOT a replacement.
+     *
+     * @var array<int, string>
+     */
+    protected static array $auditExclude = [
+${lines}
+    ];`);
+    }
+    if (tags.length > 0) {
+        const lines = tags.map((t) => `        ${JSON.stringify(t).replace(/"/g, "'")},`).join('\n');
+        parts.push(`
+    /**
+     * Static tags applied to every audit row from this model. Surfaces
+     * in the audits table's \`tags\` column for grouping in the activity
+     * feed.
+     *
+     * @var array<int, string>
+     */
+    protected static array $auditTags = [
+${lines}
+    ];`);
+    }
+    return parts.length === 0 ? '' : parts.join('\n') + '\n';
+}
 function buildAuditSection(options, reader, modelNamespace) {
     const opts = options;
     const audit = opts?.['audit'];
@@ -741,7 +807,7 @@ function buildAuditSection(options, reader, modelNamespace) {
     if (!hasCreatedBy && !hasUpdatedBy && !hasDeletedBy && !hasDefaultOrder)
         return '';
     // Get audit model name from schemas.json auditConfig
-    const auditModel = reader.data?.auditConfig?.model ?? 'User';
+    const auditModel = reader.getAuditConfig()?.model ?? 'User';
     const fqcn = `\\${modelNamespace}\\${auditModel}`;
     const parts = [];
     // Model events (booted)

package/dist/php/schema-reader.d.ts

@@ -1,7 +1,7 @@
 /**
  * Port of SchemaReader.php — reads schemas.json data.
  */
-import type { SchemasJson, SchemaDefinition, ExpandedProperty, PackageExportInfo } from '../types.js';
+import type { SchemasJson, SchemaDefinition, ExpandedProperty, PackageExportInfo, AuditConfigExport } from '../types.js';
 export declare class SchemaReader {
     private data;
     constructor(data: SchemasJson);
@@ -64,12 +64,32 @@ export declare class SchemaReader {
     /** Get all schemas that have File-type properties. */
     getSchemasWithFileProperties(): Record<string, SchemaDefinition>;
     /** Get global audit config from schemas.json. */
-    getAuditConfig(): {
-        model?: string;
-        createdBy?: boolean;
-        updatedBy?: boolean;
-        deletedBy?: boolean;
-    } | null;
+    getAuditConfig(): AuditConfigExport | null;
+    /** True when ANY schema (project or package) is audited — the audits
+     *  table + supporting infra (trait, job, model) are emitted as a unit. */
+    hasAuditLog(): boolean;
+    /** Resolve per-schema audit-log enablement: per-schema override wins
+     *  over the global default. Returns false for non-object schemas. */
+    isAuditLogEnabled(schemaName: string): boolean;
+    /** Object schemas with audit-log enabled (folded global + per-schema). */
+    getSchemasWithAuditLog(): Record<string, SchemaDefinition>;
+    /** Merged scrub list for a schema (global defaults + per-schema overrides).
+     *  Duplicates are de-duplicated; order is global-first then per-schema. */
+    getAuditExcludesFor(schemaName: string): string[];
+    /** Static tag list configured for a schema (or empty). Used by the
+     *  trait to populate the `tags` column on every audit row. */
+    getAuditTagsFor(schemaName: string): string[];
+    /** Audit user-model schema name (typically `User`). Required when the
+     *  feature is enabled — the omnify-go validator already rejects
+     *  `audit.log: true` without a model, so this returns "" only when the
+     *  feature is itself off. */
+    getAuditUserModel(): string;
+    /** Laravel queue name for WriteAuditLog dispatch. Empty string means
+     *  sync fallback (low-traffic / dev mode). */
+    getAuditQueue(): string;
+    /** Prunable retention period (e.g. `90d`). Empty string means audits
+     *  are kept forever — no Prunable scope is registered. */
+    getAuditRetention(): string;
     /** Get schemas that have service options configured (options.service). */
     getSchemasWithService(): Record<string, import('../types.js').SchemaDefinition>;
     /** Check if any schema has service options. */

package/dist/php/schema-reader.js

@@ -214,6 +214,102 @@ export class SchemaReader {
     getAuditConfig() {
         return this.data.auditConfig ?? null;
     }
+    // ---------------------------------------------------------------------------
+    // Audit-log feature helpers (audits-table history)
+    //
+    // The audit-log feature is OFF unless either (a) the global flag
+    // `auditConfig.log === true` is set, or (b) at least one schema has
+    // `options.audit.log === true`. The trait, observer job, and Audit model
+    // are emitted as a unit — gated by `hasAuditLog()`. Per-schema state is
+    // resolved by `isAuditLogEnabled(name)` which folds the global flag and
+    // the per-schema override into a single boolean.
+    // ---------------------------------------------------------------------------
+    /** True when ANY schema (project or package) is audited — the audits
+     *  table + supporting infra (trait, job, model) are emitted as a unit. */
+    hasAuditLog() {
+        const cfg = this.getAuditConfig();
+        if (cfg?.log === true) {
+            // Global on, but the feature still requires at least one auditable
+            // OBJECT schema (no point emitting infra for a project that has only
+            // enums / partials).
+            for (const schema of Object.values(this.getObjectSchemas())) {
+                if (schema.options?.audit?.log !== false)
+                    return true;
+            }
+            // Global on but every schema explicitly opts out — feature is dead.
+            return false;
+        }
+        for (const schema of Object.values(this.getObjectSchemas())) {
+            if (schema.options?.audit?.log === true)
+                return true;
+        }
+        return false;
+    }
+    /** Resolve per-schema audit-log enablement: per-schema override wins
+     *  over the global default. Returns false for non-object schemas. */
+    isAuditLogEnabled(schemaName) {
+        const schema = this.getSchema(schemaName);
+        if (!schema)
+            return false;
+        const kind = schema.kind ?? 'object';
+        if (kind !== 'object')
+            return false;
+        const perSchema = schema.options?.audit?.log;
+        if (perSchema === true)
+            return true;
+        if (perSchema === false)
+            return false;
+        return this.getAuditConfig()?.log === true;
+    }
+    /** Object schemas with audit-log enabled (folded global + per-schema). */
+    getSchemasWithAuditLog() {
+        const result = {};
+        for (const [name, schema] of Object.entries(this.getObjectSchemas())) {
+            if (this.isAuditLogEnabled(name)) {
+                result[name] = schema;
+            }
+        }
+        return result;
+    }
+    /** Merged scrub list for a schema (global defaults + per-schema overrides).
+     *  Duplicates are de-duplicated; order is global-first then per-schema. */
+    getAuditExcludesFor(schemaName) {
+        const schema = this.getSchema(schemaName);
+        const global = this.getAuditConfig()?.logExclude ?? [];
+        const local = schema?.options?.audit?.logExclude ?? [];
+        const seen = new Set();
+        const out = [];
+        for (const c of [...global, ...local]) {
+            if (!seen.has(c)) {
+                seen.add(c);
+                out.push(c);
+            }
+        }
+        return out;
+    }
+    /** Static tag list configured for a schema (or empty). Used by the
+     *  trait to populate the `tags` column on every audit row. */
+    getAuditTagsFor(schemaName) {
+        const schema = this.getSchema(schemaName);
+        return [...(schema?.options?.audit?.logTags ?? [])];
+    }
+    /** Audit user-model schema name (typically `User`). Required when the
+     *  feature is enabled — the omnify-go validator already rejects
+     *  `audit.log: true` without a model, so this returns "" only when the
+     *  feature is itself off. */
+    getAuditUserModel() {
+        return this.getAuditConfig()?.model ?? '';
+    }
+    /** Laravel queue name for WriteAuditLog dispatch. Empty string means
+     *  sync fallback (low-traffic / dev mode). */
+    getAuditQueue() {
+        return this.getAuditConfig()?.logQueue ?? '';
+    }
+    /** Prunable retention period (e.g. `90d`). Empty string means audits
+     *  are kept forever — no Prunable scope is registered. */
+    getAuditRetention() {
+        return this.getAuditConfig()?.logRetention ?? '';
+    }
     /** Get schemas that have service options configured (options.service). */
     getSchemasWithService() {
         const result = {};

package/dist/types.d.ts

@@ -14,6 +14,36 @@ export interface FileConfigExport {
     readonly purgeSchedule?: string;
     readonly defaultDisk?: string;
 }
+/**
+ * Global audit configuration surfaced from the Go core.
+ *
+ * `model` is the FQ schema name of the user / actor (typically `User`)
+ * — the audits table records `(user_type, user_id)` polymorphically so
+ * any model can be the actor, but the trait needs a default to capture
+ * `Auth::user()` correctly.
+ *
+ * `log` toggles the `audits` history table feature globally; per-schema
+ * `options.audit.log` overrides per-schema. Sensitive columns listed in
+ * `logExclude` are scrubbed from `old_values` / `new_values` BEFORE the
+ * row is written, so a stolen audits dump cannot leak passwords.
+ *
+ * `logRetention` is the Prunable retention period (`90d`, `12w`, `6m`,
+ * `1y`); empty means audits are kept forever (no scheduled prune).
+ *
+ * `logQueue` is the Laravel queue connection name. Empty string means
+ * sync dispatch (low-traffic / dev fallback) — audited writes still
+ * complete immediately, just on the request thread.
+ */
+export interface AuditConfigExport {
+    readonly model?: string;
+    readonly createdBy?: boolean;
+    readonly updatedBy?: boolean;
+    readonly deletedBy?: boolean;
+    readonly log?: boolean;
+    readonly logExclude?: readonly string[];
+    readonly logRetention?: string;
+    readonly logQueue?: string;
+}
 /** Top-level schemas.json structure. */
 export interface SchemasJson {
     /**
@@ -39,12 +69,7 @@ export interface SchemasJson {
         readonly enums: Record<string, string[]>;
     };
     readonly fileConfig?: FileConfigExport;
-    readonly auditConfig?: {
-        readonly model?: string;
-        readonly createdBy?: boolean;
-        readonly updatedBy?: boolean;
-        readonly deletedBy?: boolean;
-    };
+    readonly auditConfig?: AuditConfigExport;
     readonly packages?: Record<string, PackageExportInfo>;
     readonly schemas: Record<string, SchemaDefinition>;
 }
@@ -158,9 +183,18 @@ export interface SchemaOptions {
     readonly unique?: readonly unknown[];
     readonly api?: ApiOptions;
     readonly audit?: {
+        readonly model?: string;
         readonly createdBy?: boolean;
         readonly updatedBy?: boolean;
         readonly deletedBy?: boolean;
+        /** Per-schema opt-in to the audits history feature. Pointer-tristate
+         *  semantics: undefined = inherit global; true/false = explicit. */
+        readonly log?: boolean;
+        /** Per-schema scrub list. Merged with the global `auditConfig.logExclude`
+         *  before any audit row is written. */
+        readonly logExclude?: readonly string[];
+        /** Static tag list applied to every audit row from this schema. */
+        readonly logTags?: readonly string[];
     };
     /**
      * Service layer codegen options (issue #57).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/ts",
-  "version": "5.0.5",
+  "version": "5.1.0",
   "description": "TypeScript model type generator from Omnify schemas.json",
   "type": "module",
   "main": "dist/index.js",