letopis 2.0.0 → 3.0.0

package/dist/cli.js

@@ -13,6 +13,8 @@
  *   letopis maintain --dsn … --schema v2.x [--token … | --api-key …]
  *   letopis mcp --dsn … --schema v2.x --token … [--write]   — сервер MCP по stdio (план 1.1, §2.5); dsn, schema и
  *     token — ещё из LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; только токен пользователя: --api-key — отказ
+ *   --log[=уровень] — у любой команды (логирование 3.0): события JSON-строками в stderr, уровень debug|info|warn|error|off,
+ *     без значения — info; без флага действует LETOPIS_LOG
  *   справка — USAGE (её же читает справочник сайта, guide/scripts/gen-api.ts)
  */
 import { parseArgs } from 'node:util';
@@ -23,13 +25,15 @@ import { resolve } from 'node:path';
 import { connect } from './index.js';
 import { syncModels, generateTypes } from './sync.js';
 import { lerr, lmsg } from './errors.js';
+import { stderrLog } from './log.js';
 const USAGE = `letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply | --check]
 letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>] [--system]
 letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--class <Класс>]
   [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--initial]
 letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>]
 letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
-  (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)`;
+  (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
+у любой команды: --log[=debug|info|warn|error|off] — события JSON-строками в stderr (без значения — info)`;
 /** Команды CLI: остальное — USAGE с кодом 2 ещё до подключения. */
 const COMMANDS = new Set(['sync', 'types', 'load', 'maintain', 'mcp']);
 const isModel = (v) => typeof v === 'object' && v !== null && typeof v.describe === 'function' && typeof v.name === 'string';
@@ -38,9 +42,27 @@ async function loadModels(path) {
     const mod = await import(pathToFileURL(resolve(path)).href);
     return [...new Set(Object.values(mod).flatMap((v) => (Array.isArray(v) ? v : [v])).filter(isModel))];
 }
+/**
+ * Флаг --log[=уровень] (логирование 3.0): вынимается из аргументов до parseArgs — у строкового флага parseArgs требует
+ * значение, а --log без него значит info.
+ */
+function logFlag(argv) {
+    let level;
+    const args = [];
+    for (const a of argv) {
+        if (a === '--log')
+            level = 'info';
+        else if (a.startsWith('--log='))
+            level = (a.slice('--log='.length) || 'info');
+        else
+            args.push(a);
+    }
+    return { args, log: level === undefined ? {} : { log: stderrLog, logLevel: level } };
+}
 export async function main(argv) {
+    const { args, log } = logFlag(argv);
     const { values, positionals } = parseArgs({
-        args: argv,
+        args,
         allowPositionals: true,
         options: {
             dsn: { type: 'string' }, schema: { type: 'string' }, token: { type: 'string' }, 'api-key': { type: 'string' },
@@ -67,9 +89,9 @@ export async function main(argv) {
         return cmd ? 2 : 0;
     }
     if (cmd === 'mcp')
-        return mcp(values);
+        return mcp(values, log);
     // загрузчику нужно администраторское подключение (§2.6, п. 1)
-    const db = await connect({ dsn: values.dsn, schema: values.schema, token: values.token, apiKey: values['api-key'], max: 2,
+    const db = await connect({ dsn: values.dsn, schema: values.schema, token: values.token, apiKey: values['api-key'], max: 2, ...log,
         // maintain работает и на администраторском подключении без сессии; классы со строками синхронизирует
         // администраторское подключение с сессией арендатора
         ...(cmd === 'load' || cmd === 'maintain' || cmd === 'sync' ? { allowBypassRls: true } : {}) });
@@ -145,7 +167,7 @@ export async function main(argv) {
  * грузятся только здесь: letopis --help и прочие команды работают без SDK. В stdout — только протокол (предупреждения
  * connect() идут в stderr); процесс живёт, пока клиент не закроет stdin.
  */
-async function mcp(v) {
+async function mcp(v, log = {}) {
     if (v['api-key'] !== undefined) {
         console.error(lerr('model.mcp_api_key_refused').message);
         return 2;
@@ -155,7 +177,7 @@ async function mcp(v) {
         return 2;
     }
     const { createMcpServer } = await import('./mcp.js');
-    const db = await connect({ dsn: v.dsn, schema: v.schema, token: v.token, max: 4 });
+    const db = await connect({ dsn: v.dsn, schema: v.schema, token: v.token, max: 4, ...log });
     try {
         const opts = { write: v.write === true };
         // учётные данные — до начала протокола: отказ виден кодом выхода и текстом в stderr

package/dist/errors.d.ts

@@ -8,13 +8,26 @@ export interface Issue {
 }
 /** Текст записи каталога с параметрами (params.similar — «— похожие: …»): сообщения нарушений, описания, отчёты CLI. */
 export declare function lmsg(key: MsgKey, params?: Params): string;
+/** Логгер, в который уходит предупреждение (lib/src/log.ts, Log): только то, что нужно lwarn. */
+interface WarnSink {
+    readonly active: boolean;
+    warning(key: string | undefined, msg: string, detail?: Record<string, unknown>): void;
+}
+export declare function setEnvWarnSink(fn: () => WarnSink): void;
 /**
  * Предупреждение по записи каталога — «letopis: <текст>» в console.warn; once — ключ «один раз на процесс». Неизвестное
  * поле фильтра, sort() и агрегата с 2.0 — уже не предупреждение, а отказ query.unknown_field (sql.ts, checkField).
+ * Логирование 3.0: задан логгер (opts.log подключения или LETOPIS_LOG) — событие warning в него вместо console.warn.
  */
 export declare function lwarn(key: MsgKey, params?: Params, opts?: {
     once?: string;
+    log?: WarnSink;
 }): void;
+/**
+ * Готовый текст предупреждения: в логгер (событие warning с ключом и параметрами), если он задан, иначе console.warn.
+ * Ошибка логгера предупреждение не теряет и операцию не прерывает.
+ */
+export declare function warnText(text: string, key?: string, log?: WarnSink, params?: Params): void;
 export declare class LetopisError extends Error {
     readonly code: string;
     readonly detail: unknown;
@@ -46,7 +59,12 @@ export declare function similar(name: string, candidates: Iterable<string>, n?:
  * 7.9 №6). known — все ключи опций: объект `satisfies Record<keyof Опции, true>`, пропуск ключа — ошибка типов.
  */
 export declare function checkOptions(where: string, opts: unknown, known: Readonly<Record<string, true>>): void;
-/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed). */
+/**
+ * Первое нарушение для текста ошибки (план 2.1, A8): «: <путь> — <сообщение>», при нескольких — ещё их число. Полный
+ * список — err.issues.
+ */
+export declare function issuesSuffix(issues: readonly Issue[]): string;
+/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed) и первое нарушение. */
 export declare class ValidationError extends LetopisError {
     readonly issues: Issue[];
     constructor(cls: string, issues: Issue[], msg?: {

package/dist/errors.js

@@ -30,9 +30,15 @@ export function lmsg(key, params) {
     return textOf(key, params);
 }
 const warned = new Set();
+/** Логгер по LETOPIS_LOG для предупреждений без подключения — ставит log.ts (без цикла импорта значений). */
+let envSink = null;
+export function setEnvWarnSink(fn) {
+    envSink = fn;
+}
 /**
  * Предупреждение по записи каталога — «letopis: <текст>» в console.warn; once — ключ «один раз на процесс». Неизвестное
  * поле фильтра, sort() и агрегата с 2.0 — уже не предупреждение, а отказ query.unknown_field (sql.ts, checkField).
+ * Логирование 3.0: задан логгер (opts.log подключения или LETOPIS_LOG) — событие warning в него вместо console.warn.
  */
 export function lwarn(key, params, opts = {}) {
     if (opts.once !== undefined) {
@@ -42,7 +48,24 @@ export function lwarn(key, params, opts = {}) {
             warned.clear();
         warned.add(opts.once);
     }
-    console.warn(`letopis: ${textOf(key, params)}`);
+    warnText(`letopis: ${textOf(key, params)}`, key, opts.log, params);
+}
+/**
+ * Готовый текст предупреждения: в логгер (событие warning с ключом и параметрами), если он задан, иначе console.warn.
+ * Ошибка логгера предупреждение не теряет и операцию не прерывает.
+ */
+export function warnText(text, key, log, params) {
+    const sink = log?.active ? log : envSink?.();
+    if (sink?.active) {
+        try {
+            sink.warning(key, text, params && Object.keys(params).length ? { ...params } : undefined);
+            return;
+        }
+        catch {
+            // логгер не принял — как без него
+        }
+    }
+    console.warn(text);
 }
 export class LetopisError extends Error {
     code;
@@ -120,12 +143,24 @@ export function checkOptions(where, opts, known) {
             throw lerr('api.unknown_option', { where, name: k, similar: similar(k, Object.keys(known)) });
     }
 }
-/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed). */
+/**
+ * Первое нарушение для текста ошибки (план 2.1, A8): «: <путь> — <сообщение>», при нескольких — ещё их число. Полный
+ * список — err.issues.
+ */
+export function issuesSuffix(issues) {
+    const first = issues[0];
+    if (!first)
+        return '';
+    const path = Array.isArray(first.path) && first.path.length ? first.path.join('.') : textOf('api.validation_root', undefined);
+    const more = issues.length > 1 ? textOf('api.validation_more', { n: issues.length }) : '';
+    return `: ${textOf('api.validation_issue', { path, issue: first.message })}${more}`;
+}
+/** Данные не проходят описание класса (`invalid_data`); текст — по ключу (по умолчанию api.validation_failed) и первое нарушение. */
 export class ValidationError extends LetopisError {
     issues;
     constructor(cls, issues, msg) {
         const m = msg ?? { key: 'api.validation_failed', params: { cls } };
-        super('invalid_data', textOf(m.key, m.params), { issues }, m);
+        super('invalid_data', textOf(m.key, m.params) + issuesSuffix(issues), { issues }, m);
         this.name = 'ValidationError';
         this.issues = issues;
     }
@@ -192,6 +227,10 @@ export function fromDbError(e) {
     if (err.code === '42501' && err.routine === 'ExecWithCheckOptions' && !/USING/.test(err.message ?? '')) {
         return lerr('api.row_check_denied', undefined, { cause: e });
     }
+    // значение не того типа (22P02: «invalid input syntax for type uuid» и т. п.), которое не поймала проверка до запроса,
+    // — ошибка letopis, а не сырая ошибка PostgreSQL (план 2.1, A7); 40001 и 40P01 остаются как есть — на них держатся повторы
+    if (err.code === '22P02')
+        return lerr('api.db_bad_value', { text: err.message ?? '' }, { cause: e });
     let name;
     let detail;
     if (err.code === 'XX000') {
@@ -225,9 +264,10 @@ export function fromDbError(e) {
     const issues = detail?.issues;
     if (name === 'invalid_data' && Array.isArray(issues)) {
         const cls = msg ? String(msg.params.cls ?? '?') : /класса (\S+)/.exec(text)?.[1] ?? '?';
-        const v = new ValidationError(cls, issuesFromDb(issues), msg);
-        // текст целиком — тот, что собрала база по шаблону записи
-        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}` } : {}) });
+        const list = issuesFromDb(issues);
+        const v = new ValidationError(cls, list, msg);
+        // текст — тот, что собрала база по шаблону записи, и первое нарушение (план 2.1, A8)
+        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}${issuesSuffix(list)}` } : {}) });
     }
     return Object.assign(new LetopisError(name, text, detail, msg), { cause: e });
 }

package/dist/index.d.ts

@@ -14,7 +14,7 @@ import { type AuthApi } from './auth.js';
 import { type AclApi } from './acl.js';
 import { type LoadInput, type LoadOptions, type LoadReport } from './load.js';
 import { type Batch, type Chain, type ChainRef, type StepFn } from './chain.js';
-import type { QueryEvent, Row } from './types.js';
+import type { LogOptions, QueryEvent, Row } from './types.js';
 import { type CacheOptions, type CacheStats } from './cache.js';
 import { Subscription, type WatchOptions } from './watch.js';
 import { type MaintainReport } from './admin.js';
@@ -34,7 +34,7 @@ export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has,
  */
 export declare const or: <F extends object>(...filters: NoInfer<F>[]) => OrOp<F>;
 export { cursorOf } from './sql.js';
-export { inc, isInc, type IncMarker, type WriteRow } from './write.js';
+export { inc, isInc, type DeleteOptions, type Expected, type IncMarker, type RestoreOptions, type WriteRow } from './write.js';
 export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential, type SessionInfo } from './auth.js';
 export type { AclApi, AclDecision, AclDataDecision, AclOp, AclRule, AclRuleSpec, AclTarget } from './acl.js';
 export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
@@ -47,11 +47,13 @@ export type { WatchOptions, WatchEvent, Subscription } from './watch.js';
 export type { MaintainReport } from './admin.js';
 export { up, createTenant, type UpOptions, type UpResult, type TenantOptions, type TenantResult, type LoginOptions } from './up.js';
 export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
-export interface ConnectOptions {
+export type { LogEvent, LogFn, LogLevel, LogObject, LogOptions, Logger } from './types.js';
+export { LOG_EVENTS, type LogEventName } from './messages/index.js';
+export interface ConnectOptions extends LogOptions {
     /** Строка подключения; либо готовый пул postgres.js в `sql`. */
     dsn?: string;
     sql?: postgres.Sql;
-    /** Схема установки, например `v2.salon`. */
+    /** Схема установки, например `v2.salon`; имя без точки (`salon`) — как у `up()`: `v2.salon`. */
     schema: string;
     /** Токен сессии; либо ключ `APIKEY` в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
     token?: string;
@@ -178,6 +180,10 @@ export interface DbCore {
     commit(tr?: DbTx): Promise<void>;
     /** Откатить транзакцию `tr` (то же, что `tr.rollback()`). */
     rollback(tr?: DbTx): Promise<void>;
+    /**
+     * Закрыть подключение: у корня — пул и подписки, в `db.begin()` — откат транзакции; у фасада `db.as()` ничего не делает
+     * (пул общий с корнем).
+     */
     close(): Promise<void>;
 }
 /** Подключение: служебные методы и классы как стартовые шаги цепочек — `db.Класс(фильтр)`. */