@itphx/synth-shared 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -110,6 +110,54 @@ export const defaultConfig = {
110
110
  maxArgumentsLength: 10_000,
111
111
  maxRenderedBytes: 200_000,
112
112
  },
113
+ events: {
114
+ enabled: true,
115
+ defaultMode: 'bound',
116
+ ephemeralTtl: '24h',
117
+ journalRetentionDays: 30,
118
+ allowedSources: [],
119
+ // Default OFF: дедуп in-process, поведение single-process не меняется (AD-051/AD-089).
120
+ dedupStore: 'memory',
121
+ // Неизвестный agentTemplate → drop с аудитом (fail-safe, AD-089).
122
+ unknownAgentTemplate: 'drop',
123
+ // Глобальный дефолт лимита запросов/мин на API-ключ привязки (0 — без лимита).
124
+ keyRateLimitPerMinute: 0,
125
+ // AD-084 × AD-089: decision-маршрутизация событий выключена по умолчанию (opt-in).
126
+ decisionRouting: false,
127
+ // AD-089 (auto-bind): фоллбек-закрепление события с chatKey/threadKey за сессией — по умолчанию выключено.
128
+ autoBind: false,
129
+ autoBindAgentTemplate: '',
130
+ // AD-089: маппинг идентичности отправителя события на владельца сессии (пусто — не переопределяется).
131
+ identityMap: {},
132
+ },
133
+ scheduler: {
134
+ enabled: true,
135
+ tickSec: 60,
136
+ catchUp: 'skip',
137
+ jobRetentionDays: 30,
138
+ // Default OFF: leader election и межпроцессные локи выключены (AD-051/AD-089).
139
+ leaderElection: 'none',
140
+ crossProcessLocks: false,
141
+ },
142
+ decision: {
143
+ // AD-084: decision-слой выключен по умолчанию (провайдер задаёт админ).
144
+ enabled: false,
145
+ provider: '',
146
+ model: '',
147
+ confidenceThreshold: 0.6,
148
+ // AD-084: тир эскалации не задан (пусто — эскалации нет).
149
+ escalationProvider: '',
150
+ escalationModel: '',
151
+ },
152
+ webhooks: {
153
+ // AD-052 (этап II): доставка webhooks выключена по умолчанию (opt-in).
154
+ enabled: false,
155
+ maxAttempts: 5,
156
+ timeoutMs: 10_000,
157
+ // Только https и публичные адреса; приватные/loopback — запрещены (SSRF).
158
+ allowPrivateTargets: false,
159
+ deliveryRetentionDays: 30,
160
+ },
113
161
  instructions: {
114
162
  enabled: true,
115
163
  claudeCompat: true,
@@ -213,5 +261,7 @@ export const defaultConfig = {
213
261
  },
214
262
  // Пусто — core использует файл {dataDir}/secrets/master.key (AD-076).
215
263
  secretKey: '',
264
+ // AD-052/O1: installer service-key'и из env/Secret (по умолчанию нет).
265
+ bootstrapServiceKeys: [],
216
266
  },
217
267
  };
@@ -0,0 +1,68 @@
1
+ export type EnvOverrideType = 'boolean' | 'number' | 'string';
2
+ export interface EnvOverrideDefinition {
3
+ /** Секция верхнего уровня конфига (`events`, `scheduler`, `webhooks`, `decision`). */
4
+ section: string;
5
+ /** Ключ внутри секции (camelCase, как в `types.ts`). */
6
+ key: string;
7
+ /** Тип значения для парсинга env-строки. */
8
+ type: EnvOverrideType;
9
+ }
10
+ /**
11
+ * Реестр env-оверрайдов скалярных ключей вложенных секций (AD-023).
12
+ *
13
+ * Объектные/нескалярные ключи (`events.allowedSources`, `events.identityMap`,
14
+ * `events.dedupStore`, `events.unknownAgentTemplate`, `scheduler.leaderElection`,
15
+ * `scheduler.crossProcessLocks`, `mcp.servers`, …) намеренно не входят: у них нет
16
+ * плоского строкового представления — они остаются в config.yaml.
17
+ */
18
+ export declare const ENV_OVERRIDES: readonly EnvOverrideDefinition[];
19
+ /** camelCase → SNAKE_CASE (`autoBind` → `AUTO_BIND`, `ephemeralTtl` → `EPHEMERAL_TTL`). */
20
+ export declare function toSnakeCase(value: string): string;
21
+ /** Полное env-имя определения: `SYNTH_<SECTION>_<KEY>`. */
22
+ export declare function envOverrideName(def: EnvOverrideDefinition): string;
23
+ export type ParsedEnvValue = {
24
+ ok: true;
25
+ value: boolean | number | string;
26
+ } | {
27
+ ok: false;
28
+ };
29
+ /**
30
+ * Парсинг env-строки по типу ключа:
31
+ * - `boolean` — `true`/`1`/`false`/`0` (регистронезависимо);
32
+ * - `number` — `Number()` с проверкой `Number.isFinite`;
33
+ * - `string` — как есть.
34
+ *
35
+ * Пустая строка (переменная задана, но пуста) → `{ok:false}` — трактуется как
36
+ * «не задано» (как `resolveDataDir`/`resolveDecisionProvider` с `if (envVal)`).
37
+ * Нераспознанное значение → `{ok:false}`: потребитель логирует warn и игнорирует.
38
+ */
39
+ export declare function parseEnvValue(raw: string, type: EnvOverrideType): ParsedEnvValue;
40
+ /**
41
+ * Применяет env-оверрайды к уже слитому конфигу (defaults + config.yaml).
42
+ *
43
+ * Мутирует переданный объект (в `loadConfig` это свежий результат `deepMerge`) и
44
+ * возвращает его. Секции клонируются, чтобы не мутировать `defaultConfig`.
45
+ * Неизвестные env игнорируются молча; невалидное значение — warn в console и
46
+ * игнор (как `resolvePort`/`resolveIgnoreRules`, без падения).
47
+ */
48
+ export declare function applyEnvOverrides<T extends Record<string, unknown>>(config: T, env?: NodeJS.ProcessEnv): T;
49
+ /**
50
+ * AD-052/O1: env-имя JSON-списка installer service-key'ев
51
+ * (`security.bootstrapServiceKeys`). Значение — JSON-массив объектов
52
+ * `{ label, secret, scopes, roles?, description? }`. Приоритет — как у
53
+ * скалярных env-оверрайдов: env > config.yaml (AD-023), но выше CLI-overrides.
54
+ * Нужен, чтобы секрет installer-ключа не попадал в файл конфигурации
55
+ * (передаётся из env/Secret).
56
+ */
57
+ export declare const BOOTSTRAP_SERVICE_KEYS_ENV = "SYNTH_BOOTSTRAP_SERVICE_KEYS";
58
+ /**
59
+ * Применяет объектные env-оверрайды, у которых нет плоского строкового
60
+ * представления (сейчас — `security.bootstrapServiceKeys`). Значение парсится
61
+ * как JSON и валидируется схемой; при ошибке парсинга/валидации — warn в console
62
+ * и игнор (fail-soft: кривой installer-ключ не должен ронять старт инстанса —
63
+ * ensure-логика приложения просто ничего не бутстрапит, оператор видит warn).
64
+ *
65
+ * Мутирует переданный объект (в `loadConfig` — свежий результат `deepMerge`) и
66
+ * возвращает его; секция `security` клонируется, чтобы не мутировать `defaultConfig`.
67
+ */
68
+ export declare function applyObjectEnvOverrides<T extends Record<string, unknown>>(config: T, env?: NodeJS.ProcessEnv): T;
@@ -0,0 +1,165 @@
1
+ /**
2
+ * AD-023: декларативные env-оверрайды скалярных ключей конфигурации.
3
+ *
4
+ * Имя переменной собирается по правилу `SYNTH_<SECTION>_<KEY>`, где camelCase
5
+ * ключа переводится в SNAKE_CASE (`autoBind` → `SYNTH_EVENTS_AUTO_BIND`,
6
+ * `ephemeralTtl` → `SYNTH_EVENTS_EPHEMERAL_TTL`). Реестр `ENV_OVERRIDES` —
7
+ * единственный источник истины; применяется **в одном месте** (`loadConfig`,
8
+ * после слияния defaults + config.yaml и до CLI-overrides), поэтому все
9
+ * потребители `@itphx/synth-shared/config` получают поддержку автоматически.
10
+ *
11
+ * Приоритет (AD-023): CLI-флаги (`overrides`) > env (`SYNTH_*`) > config.yaml > defaults.
12
+ */
13
+ import { bootstrapServiceKeysSchema } from './types.js';
14
+ /**
15
+ * Реестр env-оверрайдов скалярных ключей вложенных секций (AD-023).
16
+ *
17
+ * Объектные/нескалярные ключи (`events.allowedSources`, `events.identityMap`,
18
+ * `events.dedupStore`, `events.unknownAgentTemplate`, `scheduler.leaderElection`,
19
+ * `scheduler.crossProcessLocks`, `mcp.servers`, …) намеренно не входят: у них нет
20
+ * плоского строкового представления — они остаются в config.yaml.
21
+ */
22
+ export const ENV_OVERRIDES = [
23
+ // events (AD-089)
24
+ { section: 'events', key: 'enabled', type: 'boolean' },
25
+ { section: 'events', key: 'defaultMode', type: 'string' },
26
+ { section: 'events', key: 'ephemeralTtl', type: 'string' },
27
+ { section: 'events', key: 'journalRetentionDays', type: 'number' },
28
+ { section: 'events', key: 'keyRateLimitPerMinute', type: 'number' },
29
+ { section: 'events', key: 'decisionRouting', type: 'boolean' },
30
+ { section: 'events', key: 'autoBind', type: 'boolean' },
31
+ { section: 'events', key: 'autoBindAgentTemplate', type: 'string' },
32
+ // scheduler (AD-051 срез / AD-089)
33
+ { section: 'scheduler', key: 'enabled', type: 'boolean' },
34
+ { section: 'scheduler', key: 'tickSec', type: 'number' },
35
+ { section: 'scheduler', key: 'catchUp', type: 'string' },
36
+ { section: 'scheduler', key: 'jobRetentionDays', type: 'number' },
37
+ // webhooks (AD-052, этап II)
38
+ { section: 'webhooks', key: 'enabled', type: 'boolean' },
39
+ { section: 'webhooks', key: 'maxAttempts', type: 'number' },
40
+ { section: 'webhooks', key: 'timeoutMs', type: 'number' },
41
+ { section: 'webhooks', key: 'allowPrivateTargets', type: 'boolean' },
42
+ { section: 'webhooks', key: 'deliveryRetentionDays', type: 'number' },
43
+ // decision (AD-084)
44
+ { section: 'decision', key: 'enabled', type: 'boolean' },
45
+ { section: 'decision', key: 'provider', type: 'string' },
46
+ { section: 'decision', key: 'model', type: 'string' },
47
+ { section: 'decision', key: 'confidenceThreshold', type: 'number' },
48
+ { section: 'decision', key: 'escalationProvider', type: 'string' },
49
+ { section: 'decision', key: 'escalationModel', type: 'string' },
50
+ ];
51
+ /** camelCase → SNAKE_CASE (`autoBind` → `AUTO_BIND`, `ephemeralTtl` → `EPHEMERAL_TTL`). */
52
+ export function toSnakeCase(value) {
53
+ return value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
54
+ }
55
+ /** Полное env-имя определения: `SYNTH_<SECTION>_<KEY>`. */
56
+ export function envOverrideName(def) {
57
+ return `SYNTH_${toSnakeCase(def.section)}_${toSnakeCase(def.key)}`;
58
+ }
59
+ /**
60
+ * Парсинг env-строки по типу ключа:
61
+ * - `boolean` — `true`/`1`/`false`/`0` (регистронезависимо);
62
+ * - `number` — `Number()` с проверкой `Number.isFinite`;
63
+ * - `string` — как есть.
64
+ *
65
+ * Пустая строка (переменная задана, но пуста) → `{ok:false}` — трактуется как
66
+ * «не задано» (как `resolveDataDir`/`resolveDecisionProvider` с `if (envVal)`).
67
+ * Нераспознанное значение → `{ok:false}`: потребитель логирует warn и игнорирует.
68
+ */
69
+ export function parseEnvValue(raw, type) {
70
+ if (raw === '')
71
+ return { ok: false };
72
+ switch (type) {
73
+ case 'boolean': {
74
+ const v = raw.toLowerCase();
75
+ if (v === 'true' || v === '1')
76
+ return { ok: true, value: true };
77
+ if (v === 'false' || v === '0')
78
+ return { ok: true, value: false };
79
+ return { ok: false };
80
+ }
81
+ case 'number': {
82
+ const n = Number(raw);
83
+ if (!Number.isFinite(n))
84
+ return { ok: false };
85
+ return { ok: true, value: n };
86
+ }
87
+ case 'string':
88
+ return { ok: true, value: raw };
89
+ }
90
+ }
91
+ /**
92
+ * Применяет env-оверрайды к уже слитому конфигу (defaults + config.yaml).
93
+ *
94
+ * Мутирует переданный объект (в `loadConfig` это свежий результат `deepMerge`) и
95
+ * возвращает его. Секции клонируются, чтобы не мутировать `defaultConfig`.
96
+ * Неизвестные env игнорируются молча; невалидное значение — warn в console и
97
+ * игнор (как `resolvePort`/`resolveIgnoreRules`, без падения).
98
+ */
99
+ export function applyEnvOverrides(config, env = process.env) {
100
+ for (const def of ENV_OVERRIDES) {
101
+ const name = envOverrideName(def);
102
+ const raw = env[name];
103
+ if (raw === undefined)
104
+ continue;
105
+ const parsed = parseEnvValue(raw, def.type);
106
+ if (!parsed.ok) {
107
+ // Пустая строка — «не задано» (тихий игнор). Нераспознанное значение — warn.
108
+ if (raw !== '') {
109
+ console.warn(`[config] невалидное значение ${name}="${raw}" (ожидается ${def.type}) — игнорируется`);
110
+ }
111
+ continue;
112
+ }
113
+ const current = config[def.section];
114
+ const section = current !== null && typeof current === 'object' && !Array.isArray(current)
115
+ ? { ...current }
116
+ : {};
117
+ section[def.key] = parsed.value;
118
+ config[def.section] = section;
119
+ }
120
+ return config;
121
+ }
122
+ /**
123
+ * AD-052/O1: env-имя JSON-списка installer service-key'ев
124
+ * (`security.bootstrapServiceKeys`). Значение — JSON-массив объектов
125
+ * `{ label, secret, scopes, roles?, description? }`. Приоритет — как у
126
+ * скалярных env-оверрайдов: env > config.yaml (AD-023), но выше CLI-overrides.
127
+ * Нужен, чтобы секрет installer-ключа не попадал в файл конфигурации
128
+ * (передаётся из env/Secret).
129
+ */
130
+ export const BOOTSTRAP_SERVICE_KEYS_ENV = 'SYNTH_BOOTSTRAP_SERVICE_KEYS';
131
+ /**
132
+ * Применяет объектные env-оверрайды, у которых нет плоского строкового
133
+ * представления (сейчас — `security.bootstrapServiceKeys`). Значение парсится
134
+ * как JSON и валидируется схемой; при ошибке парсинга/валидации — warn в console
135
+ * и игнор (fail-soft: кривой installer-ключ не должен ронять старт инстанса —
136
+ * ensure-логика приложения просто ничего не бутстрапит, оператор видит warn).
137
+ *
138
+ * Мутирует переданный объект (в `loadConfig` — свежий результат `deepMerge`) и
139
+ * возвращает его; секция `security` клонируется, чтобы не мутировать `defaultConfig`.
140
+ */
141
+ export function applyObjectEnvOverrides(config, env = process.env) {
142
+ const raw = env[BOOTSTRAP_SERVICE_KEYS_ENV];
143
+ if (raw === undefined || raw === '')
144
+ return config;
145
+ let parsed;
146
+ try {
147
+ parsed = JSON.parse(raw);
148
+ }
149
+ catch {
150
+ console.warn(`[config] невалидный JSON ${BOOTSTRAP_SERVICE_KEYS_ENV} — игнорируется`);
151
+ return config;
152
+ }
153
+ const validated = bootstrapServiceKeysSchema.safeParse(parsed);
154
+ if (!validated.success) {
155
+ console.warn(`[config] ${BOOTSTRAP_SERVICE_KEYS_ENV} не прошёл валидацию — игнорируется`);
156
+ return config;
157
+ }
158
+ const current = config.security;
159
+ const security = current !== null && typeof current === 'object' && !Array.isArray(current)
160
+ ? { ...current }
161
+ : {};
162
+ security.bootstrapServiceKeys = validated.data;
163
+ config.security = security;
164
+ return config;
165
+ }
@@ -1,5 +1,6 @@
1
1
  export * from './types.js';
2
2
  export * from './defaults.js';
3
3
  export * from './loader.js';
4
+ export * from './env-overrides.js';
4
5
  export * from './merge.js';
5
6
  export * from './resolve.js';
@@ -1,5 +1,6 @@
1
1
  export * from './types.js';
2
2
  export * from './defaults.js';
3
3
  export * from './loader.js';
4
+ export * from './env-overrides.js';
4
5
  export * from './merge.js';
5
6
  export * from './resolve.js';
@@ -4,5 +4,7 @@ export interface LoadConfigOptions {
4
4
  /** AD-079: home-каталог — конфиг резолвится как `<home>/config.yaml`, если path не задан. */
5
5
  home?: string;
6
6
  overrides?: Partial<SynthConfig>;
7
+ /** AD-023: источник env для оверрайдов; по умолчанию `process.env` (в тестах — свой env). */
8
+ env?: NodeJS.ProcessEnv;
7
9
  }
8
10
  export declare function loadConfig(options?: LoadConfigOptions): Promise<SynthConfig>;
@@ -4,6 +4,7 @@ import { load as parseYaml } from 'js-yaml';
4
4
  import { synthConfigSchema } from './types.js';
5
5
  import { defaultConfig } from './defaults.js';
6
6
  import { deepMerge } from './merge.js';
7
+ import { applyEnvOverrides, applyObjectEnvOverrides } from './env-overrides.js';
7
8
  const CONFIG_SEARCH_PATHS = [
8
9
  'synth.config.yaml',
9
10
  'config.yaml',
@@ -55,9 +56,16 @@ export async function loadConfig(options = {}) {
55
56
  }
56
57
  }
57
58
  const merged = deepMerge(defaultConfig, fileConfig);
59
+ // AD-023: env-оверрайды скалярных ключей вложенных секций применяются одним
60
+ // местом — поверх defaults + config.yaml и ниже CLI-overrides
61
+ // (приоритет: CLI > env > config.yaml > defaults).
62
+ const withEnv = applyEnvOverrides(merged, options.env ?? process.env);
63
+ // AD-052/O1: объектный env-оверрайд installer service-key'ев
64
+ // (`SYNTH_BOOTSTRAP_SERVICE_KEYS`, JSON) — там же, до CLI-overrides.
65
+ applyObjectEnvOverrides(withEnv, options.env ?? process.env);
58
66
  const finalConfig = options.overrides
59
- ? deepMerge(merged, options.overrides)
60
- : merged;
67
+ ? deepMerge(withEnv, options.overrides)
68
+ : withEnv;
61
69
  const parsed = synthConfigSchema.safeParse(finalConfig);
62
70
  if (!parsed.success) {
63
71
  throw new Error(`Невалидная конфигурация: ${parsed.error.message}`);
@@ -49,5 +49,22 @@ export declare function resolveSecretKey(config: SynthConfig, env?: NodeJS.Proce
49
49
  * `instructions.enabled=false`.
50
50
  */
51
51
  export declare function resolveIgnoreRules(explicit?: boolean, env?: NodeJS.ProcessEnv): boolean;
52
+ /**
53
+ * AD-084: имя decision-провайдера. Приоритет: env `SYNTH_DECISION_PROVIDER` >
54
+ * `config.decision.provider`.
55
+ *
56
+ * Примечание: тот же env применяется и общим реестром `ENV_OVERRIDES` в
57
+ * `loadConfig` (AD-023, ключ `decision.provider`); резолвер сохранён для
58
+ * потребителей, читающих конфиг не через `loadConfig`.
59
+ */
60
+ export declare function resolveDecisionProvider(config: SynthConfig, env?: NodeJS.ProcessEnv): string;
61
+ /**
62
+ * AD-084: модель decision-слоя. Приоритет: env `SYNTH_DECISION_MODEL` >
63
+ * `config.decision.model`.
64
+ *
65
+ * См. примечание к `resolveDecisionProvider` — env дублируется реестром
66
+ * `ENV_OVERRIDES` (AD-023).
67
+ */
68
+ export declare function resolveDecisionModel(config: SynthConfig, env?: NodeJS.ProcessEnv): string;
52
69
  export declare function ensureDataDir(dataDir: string): Promise<void>;
53
70
  export declare function createDefaultConfig(targetPath: string): Promise<void>;
@@ -240,6 +240,27 @@ export function resolveIgnoreRules(explicit, env) {
240
240
  const envVal = (env ?? process.env).SYNTH_IGNORE_RULES;
241
241
  return envVal === '1' || envVal?.toLowerCase() === 'true';
242
242
  }
243
+ /**
244
+ * AD-084: имя decision-провайдера. Приоритет: env `SYNTH_DECISION_PROVIDER` >
245
+ * `config.decision.provider`.
246
+ *
247
+ * Примечание: тот же env применяется и общим реестром `ENV_OVERRIDES` в
248
+ * `loadConfig` (AD-023, ключ `decision.provider`); резолвер сохранён для
249
+ * потребителей, читающих конфиг не через `loadConfig`.
250
+ */
251
+ export function resolveDecisionProvider(config, env) {
252
+ return (env ?? process.env).SYNTH_DECISION_PROVIDER || config.decision.provider;
253
+ }
254
+ /**
255
+ * AD-084: модель decision-слоя. Приоритет: env `SYNTH_DECISION_MODEL` >
256
+ * `config.decision.model`.
257
+ *
258
+ * См. примечание к `resolveDecisionProvider` — env дублируется реестром
259
+ * `ENV_OVERRIDES` (AD-023).
260
+ */
261
+ export function resolveDecisionModel(config, env) {
262
+ return (env ?? process.env).SYNTH_DECISION_MODEL || config.decision.model;
263
+ }
243
264
  export async function ensureDataDir(dataDir) {
244
265
  await mkdir(dataDir, { recursive: true });
245
266
  for (const subdir of DATA_SUBDIRS) {