@itphx/synth-storage-postgres 0.0.0-stage → 0.12.4

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.
Files changed (150) hide show
  1. package/LICENSE +18 -0
  2. package/LICENSE.ru.md +31 -0
  3. package/dist/errors.d.ts +71 -0
  4. package/dist/errors.js +126 -0
  5. package/dist/index.d.ts +51 -0
  6. package/dist/index.js +56 -0
  7. package/dist/json-param.d.ts +14 -0
  8. package/dist/json-param.js +22 -0
  9. package/dist/locks.d.ts +104 -0
  10. package/dist/locks.js +201 -0
  11. package/dist/migrate.d.ts +58 -0
  12. package/dist/migrate.js +125 -0
  13. package/dist/migrations/001-init.d.ts +15 -0
  14. package/dist/migrations/001-init.js +457 -0
  15. package/dist/migrations/002-egress-audit.d.ts +12 -0
  16. package/dist/migrations/002-egress-audit.js +52 -0
  17. package/dist/migrations/003-analytics-rollups.d.ts +12 -0
  18. package/dist/migrations/003-analytics-rollups.js +21 -0
  19. package/dist/migrations/004-pipeline-engine.d.ts +19 -0
  20. package/dist/migrations/004-pipeline-engine.js +74 -0
  21. package/dist/migrations/005-pipeline-provenance.d.ts +12 -0
  22. package/dist/migrations/005-pipeline-provenance.js +15 -0
  23. package/dist/migrations/006-plugin-audit.d.ts +13 -0
  24. package/dist/migrations/006-plugin-audit.js +34 -0
  25. package/dist/migrations/007-plugin-lock.d.ts +10 -0
  26. package/dist/migrations/007-plugin-lock.js +25 -0
  27. package/dist/migrations/008-plugin-audit-scan.d.ts +11 -0
  28. package/dist/migrations/008-plugin-audit-scan.js +15 -0
  29. package/dist/migrations/009-plugin-lock-previous.d.ts +13 -0
  30. package/dist/migrations/009-plugin-lock-previous.js +16 -0
  31. package/dist/migrations/010-plugin-lock-mode.d.ts +16 -0
  32. package/dist/migrations/010-plugin-lock-mode.js +20 -0
  33. package/dist/migrations/011-session-steer-inbox.d.ts +11 -0
  34. package/dist/migrations/011-session-steer-inbox.js +14 -0
  35. package/dist/migrations/012-external-credentials.d.ts +15 -0
  36. package/dist/migrations/012-external-credentials.js +40 -0
  37. package/dist/migrations/013-service-key-plugin-id.d.ts +17 -0
  38. package/dist/migrations/013-service-key-plugin-id.js +20 -0
  39. package/dist/migrations/014-session-mode-by-principal.d.ts +12 -0
  40. package/dist/migrations/014-session-mode-by-principal.js +15 -0
  41. package/dist/migrations/015-authority.d.ts +17 -0
  42. package/dist/migrations/015-authority.js +43 -0
  43. package/dist/migrations/016-credential-audit.d.ts +17 -0
  44. package/dist/migrations/016-credential-audit.js +32 -0
  45. package/dist/migrations/017-memory.d.ts +29 -0
  46. package/dist/migrations/017-memory.js +95 -0
  47. package/dist/migrations/018-memory-index-scope.d.ts +14 -0
  48. package/dist/migrations/018-memory-index-scope.js +18 -0
  49. package/dist/migrations/019-memory-index-enabled.d.ts +11 -0
  50. package/dist/migrations/019-memory-index-enabled.js +14 -0
  51. package/dist/migrations/020-project-memory.d.ts +11 -0
  52. package/dist/migrations/020-project-memory.js +13 -0
  53. package/dist/migrations/021-background-runs.d.ts +17 -0
  54. package/dist/migrations/021-background-runs.js +67 -0
  55. package/dist/migrations/022-background-run-process-id.d.ts +14 -0
  56. package/dist/migrations/022-background-run-process-id.js +18 -0
  57. package/dist/migrations/023-session-worktree.d.ts +12 -0
  58. package/dist/migrations/023-session-worktree.js +16 -0
  59. package/dist/migrations/024-blob-refs.d.ts +15 -0
  60. package/dist/migrations/024-blob-refs.js +26 -0
  61. package/dist/migrations/025-packs-pipelines.d.ts +28 -0
  62. package/dist/migrations/025-packs-pipelines.js +82 -0
  63. package/dist/migrations/026-instance-skills.d.ts +17 -0
  64. package/dist/migrations/026-instance-skills.js +25 -0
  65. package/dist/migrations/027-context-files.d.ts +20 -0
  66. package/dist/migrations/027-context-files.js +30 -0
  67. package/dist/migrations/index.d.ts +23 -0
  68. package/dist/migrations/index.js +71 -0
  69. package/dist/pool.d.ts +178 -0
  70. package/dist/pool.js +382 -0
  71. package/dist/ports/analytics.d.ts +26 -0
  72. package/dist/ports/analytics.js +243 -0
  73. package/dist/ports/audit.d.ts +15 -0
  74. package/dist/ports/audit.js +192 -0
  75. package/dist/ports/authority.d.ts +27 -0
  76. package/dist/ports/authority.js +148 -0
  77. package/dist/ports/background-runs.d.ts +41 -0
  78. package/dist/ports/background-runs.js +179 -0
  79. package/dist/ports/blob-refs.d.ts +36 -0
  80. package/dist/ports/blob-refs.js +55 -0
  81. package/dist/ports/content.d.ts +41 -0
  82. package/dist/ports/content.js +1553 -0
  83. package/dist/ports/context-files.d.ts +145 -0
  84. package/dist/ports/context-files.js +279 -0
  85. package/dist/ports/core-sync.d.ts +31 -0
  86. package/dist/ports/core-sync.js +34 -0
  87. package/dist/ports/credential-audit.d.ts +19 -0
  88. package/dist/ports/credential-audit.js +96 -0
  89. package/dist/ports/deps.d.ts +63 -0
  90. package/dist/ports/deps.js +19 -0
  91. package/dist/ports/events-bindings.d.ts +77 -0
  92. package/dist/ports/events-bindings.js +356 -0
  93. package/dist/ports/events-core.d.ts +35 -0
  94. package/dist/ports/events-core.js +71 -0
  95. package/dist/ports/events-journal.d.ts +68 -0
  96. package/dist/ports/events-journal.js +211 -0
  97. package/dist/ports/events-scheduler.d.ts +49 -0
  98. package/dist/ports/events-scheduler.js +231 -0
  99. package/dist/ports/events-webhooks.d.ts +64 -0
  100. package/dist/ports/events-webhooks.js +268 -0
  101. package/dist/ports/events.d.ts +20 -0
  102. package/dist/ports/events.js +27 -0
  103. package/dist/ports/external-credentials.d.ts +6 -0
  104. package/dist/ports/external-credentials.js +363 -0
  105. package/dist/ports/legacy-pipelines.d.ts +50 -0
  106. package/dist/ports/legacy-pipelines.js +202 -0
  107. package/dist/ports/memory.d.ts +65 -0
  108. package/dist/ports/memory.js +471 -0
  109. package/dist/ports/packs.d.ts +32 -0
  110. package/dist/ports/packs.js +117 -0
  111. package/dist/ports/pipelines.d.ts +67 -0
  112. package/dist/ports/pipelines.js +297 -0
  113. package/dist/ports/plugin-audit.d.ts +14 -0
  114. package/dist/ports/plugin-audit.js +110 -0
  115. package/dist/ports/plugin-lock.d.ts +27 -0
  116. package/dist/ports/plugin-lock.js +145 -0
  117. package/dist/ports/principals-defaults.d.ts +21 -0
  118. package/dist/ports/principals-defaults.js +68 -0
  119. package/dist/ports/principals-documents.d.ts +23 -0
  120. package/dist/ports/principals-documents.js +38 -0
  121. package/dist/ports/principals-profiles.d.ts +21 -0
  122. package/dist/ports/principals-profiles.js +263 -0
  123. package/dist/ports/principals-projects.d.ts +19 -0
  124. package/dist/ports/principals-projects.js +161 -0
  125. package/dist/ports/principals-settings.d.ts +25 -0
  126. package/dist/ports/principals-settings.js +295 -0
  127. package/dist/ports/principals-shared.d.ts +33 -0
  128. package/dist/ports/principals-shared.js +44 -0
  129. package/dist/ports/principals.d.ts +27 -0
  130. package/dist/ports/principals.js +39 -0
  131. package/dist/ports/questions.d.ts +40 -0
  132. package/dist/ports/questions.js +135 -0
  133. package/dist/ports/sessions-mapping.d.ts +254 -0
  134. package/dist/ports/sessions-mapping.js +449 -0
  135. package/dist/ports/sessions.d.ts +143 -0
  136. package/dist/ports/sessions.js +517 -0
  137. package/dist/ports/skills.d.ts +59 -0
  138. package/dist/ports/skills.js +205 -0
  139. package/dist/ports/stub.d.ts +14 -0
  140. package/dist/ports/stub.js +32 -0
  141. package/dist/ports/worktrees.d.ts +41 -0
  142. package/dist/ports/worktrees.js +85 -0
  143. package/dist/postgres-storage.d.ts +58 -0
  144. package/dist/postgres-storage.js +110 -0
  145. package/dist/schema.d.ts +13 -0
  146. package/dist/schema.js +22 -0
  147. package/dist/storage-context.d.ts +80 -0
  148. package/dist/storage-context.js +238 -0
  149. package/package.json +40 -3
  150. package/README.md +0 -3
@@ -0,0 +1,205 @@
1
+ /**
2
+ * PG-реализация порта **instance-скиллов** (ADR-046 §4, ADR-116, ADR-097).
3
+ *
4
+ * Разделение хранения (ADR-116 §«Что переводится»):
5
+ * - **метаданные** (заголовок `SKILL.md` — `name`/`description`/прочие ключи) —
6
+ * таблица `instance_skills` (миграция `026_instance_skills`): имя — ключ,
7
+ * `frontmatter` jsonb, `updated_at` — служебная метка записи;
8
+ * - **содержимое** (`SKILL.md` и supporting-файлы) — blob-стор под
9
+ * `skills/<name>/SKILL.md` и `skills/<name>/<relPath>` (`BlobStore` остаётся
10
+ * файловым по конструкции, ADR-116 §2).
11
+ *
12
+ * Порт не отдаёт путей (ADR-116): домен работает через `listFiles`/`readFile`/
13
+ * `writeFile`, раскладка blob-стора — деталь этой реализации.
14
+ *
15
+ * Семантика повторяет файловую реализацию core (`SkillStore`) и in-memory
16
+ * (`MemorySkillRepository`):
17
+ * - `create` — ошибка на дубль имени; `frontmatter` входа сохраняется, ключи
18
+ * `name`/`description` берутся из входа;
19
+ * - `updateMarkdown` — перезапись заголовка с сохранением прочих ключей;
20
+ * - `remove` — удаление записи и **всех** объектов скилла в blob-сторе;
21
+ * - `listFiles` — supporting-файлы (без `SKILL.md`), относительные пути, размеры
22
+ * в байтах, порядок по пути;
23
+ * - небезопасные относительные пути (`..`, абсолютные, `\`) не читаются и не
24
+ * пишутся.
25
+ *
26
+ * Порядок записи: сначала содержимое (`BlobStore`), затем метаданные — при сбое
27
+ * второй записи «висящих» записей в таблице не остаётся (лишние объекты
28
+ * blob-стора безвредны: их видно только через `listFiles` существующего скилла).
29
+ */
30
+ import { SKILL_NAME_MAX, SKILL_NAME_REGEX, parseFrontmatter, stringifyFrontmatter, } from '@itphx/synth-shared';
31
+ import { jsonbParam } from '../json-param.js';
32
+ /** Корневой префикс скиллов в blob-сторе. */
33
+ const SKILLS_BLOB_PREFIX = 'skills';
34
+ /** Имя файла заголовка внутри каталога скилла. */
35
+ const SKILL_MARKDOWN_FILE = 'SKILL.md';
36
+ /** Проверка имени скилла (1–64, `^[a-z0-9]+(-[a-z0-9]+)*$`). */
37
+ function assertSkillName(name) {
38
+ if (!name || name.length > SKILL_NAME_MAX || !SKILL_NAME_REGEX.test(name)) {
39
+ throw new Error(`Недопустимое имя скилла: ${name}`);
40
+ }
41
+ }
42
+ /**
43
+ * Нормализованный относительный путь внутри скилла; `null` — путь небезопасен
44
+ * (абсолютный, с `..`, обратным слешем или NUL). Семантика — как у
45
+ * `MemorySkillRepository.safeRelPath`.
46
+ */
47
+ function safeRelPath(relPath) {
48
+ if (!relPath ||
49
+ relPath.startsWith('/') ||
50
+ relPath.includes('..') ||
51
+ relPath.includes('\\') ||
52
+ relPath.includes('\0')) {
53
+ return null;
54
+ }
55
+ const normalized = relPath.replace(/^\.\/+/, '').replace(/\/+$/, '');
56
+ if (!normalized)
57
+ return null;
58
+ return normalized;
59
+ }
60
+ /** Префикс каталога скилла в blob-сторе (`skills/<name>/`). */
61
+ function skillPrefix(name) {
62
+ return `${SKILLS_BLOB_PREFIX}/${name}/`;
63
+ }
64
+ /** Путь `SKILL.md` скилла в blob-сторе. */
65
+ function markdownPath(name) {
66
+ return `${skillPrefix(name)}${SKILL_MARKDOWN_FILE}`;
67
+ }
68
+ /**
69
+ * ADR-116: instance-скиллы — метаданные в `instance_skills`, содержимое в
70
+ * `BlobStore`.
71
+ */
72
+ export class PgSkillRepository {
73
+ _deps;
74
+ _blobs;
75
+ constructor(_deps, _blobs) {
76
+ this._deps = _deps;
77
+ this._blobs = _blobs;
78
+ }
79
+ async exists(name) {
80
+ // Невалидное имя не может быть в таблице — отвечаем `false`, а не ошибкой
81
+ // (паритет с file/memory: `exists` не бросает).
82
+ try {
83
+ assertSkillName(name);
84
+ }
85
+ catch {
86
+ return false;
87
+ }
88
+ const rows = await this._deps.connection.query('SELECT name FROM instance_skills WHERE name = $1 LIMIT 1', [name]);
89
+ return rows.length > 0;
90
+ }
91
+ async listNames() {
92
+ const rows = await this._deps.connection.query('SELECT name FROM instance_skills ORDER BY name ASC');
93
+ return rows.map((row) => row.name);
94
+ }
95
+ async readMarkdown(name) {
96
+ try {
97
+ assertSkillName(name);
98
+ }
99
+ catch {
100
+ return null;
101
+ }
102
+ const buffer = await this._blobs.read(markdownPath(name));
103
+ return buffer ? buffer.toString('utf-8') : null;
104
+ }
105
+ async create(input) {
106
+ assertSkillName(input.name);
107
+ if (await this.exists(input.name)) {
108
+ throw new Error(`Скилл "${input.name}" уже существует`);
109
+ }
110
+ const frontmatter = { ...(input.frontmatter ?? {}) };
111
+ frontmatter.name = input.name;
112
+ frontmatter.description = input.description;
113
+ const markdown = stringifyFrontmatter(frontmatter, input.body ?? '');
114
+ await this._blobs.write(markdownPath(input.name), markdown);
115
+ for (const [rel, content] of Object.entries(input.files ?? {})) {
116
+ const target = safeRelPath(rel);
117
+ if (!target)
118
+ throw new Error(`Небезопасный путь supporting-файла: ${rel}`);
119
+ await this._blobs.write(`${skillPrefix(input.name)}${target}`, content);
120
+ }
121
+ await this._upsertMetadata(input.name, frontmatter);
122
+ }
123
+ async updateMarkdown(name, patch) {
124
+ assertSkillName(name);
125
+ const raw = await this.readMarkdown(name);
126
+ if (raw === null) {
127
+ throw new Error(`Скилл "${name}" не найден`);
128
+ }
129
+ const frontmatter = parseFrontmatter(raw);
130
+ const data = { ...frontmatter.data, name };
131
+ if (patch.description !== undefined)
132
+ data.description = patch.description;
133
+ if (patch.metadata !== undefined) {
134
+ const existing = typeof data.metadata === 'object' && data.metadata !== null && !Array.isArray(data.metadata)
135
+ ? data.metadata
136
+ : {};
137
+ data.metadata = { ...existing, ...patch.metadata };
138
+ }
139
+ const body = patch.body !== undefined ? patch.body : frontmatter.body;
140
+ await this._blobs.write(markdownPath(name), stringifyFrontmatter(data, body));
141
+ await this._upsertMetadata(name, data);
142
+ }
143
+ async remove(name) {
144
+ assertSkillName(name);
145
+ if (!(await this.exists(name)))
146
+ return false;
147
+ // Содержимое: все объекты каталога скилла (`SKILL.md` + supporting).
148
+ const objects = await this._blobs.list(skillPrefix(name));
149
+ for (const object of objects) {
150
+ await this._blobs.delete(object.path);
151
+ }
152
+ await this._deps.connection.query('DELETE FROM instance_skills WHERE name = $1', [name]);
153
+ return true;
154
+ }
155
+ async readFile(name, relPath) {
156
+ const target = safeRelPath(relPath);
157
+ if (!target)
158
+ return null;
159
+ const buffer = await this._blobs.read(`${skillPrefix(name)}${target}`);
160
+ return buffer ? buffer.toString('utf-8') : null;
161
+ }
162
+ async writeFile(name, relPath, content) {
163
+ assertSkillName(name);
164
+ const target = safeRelPath(relPath);
165
+ if (!target)
166
+ throw new Error(`Небезопасный путь supporting-файла: ${relPath}`);
167
+ await this._blobs.write(`${skillPrefix(name)}${target}`, content);
168
+ }
169
+ async deleteFile(name, relPath) {
170
+ const target = safeRelPath(relPath);
171
+ if (!target)
172
+ return false;
173
+ // Удаление отсутствующего файла — не ошибка (паритет с file/memory).
174
+ await this._blobs.delete(`${skillPrefix(name)}${target}`);
175
+ return true;
176
+ }
177
+ async listFiles(name) {
178
+ const prefix = skillPrefix(name);
179
+ const objects = await this._blobs.list(prefix);
180
+ const files = [];
181
+ for (const object of objects) {
182
+ if (!object.path.startsWith(prefix))
183
+ continue;
184
+ const rel = object.path.slice(prefix.length);
185
+ if (!rel || rel === SKILL_MARKDOWN_FILE)
186
+ continue;
187
+ files.push({ path: rel, size: object.size });
188
+ }
189
+ return files.sort((a, b) => a.path.localeCompare(b.path));
190
+ }
191
+ /** Upsert метаданных: заголовок скилла и служебная метка записи. */
192
+ async _upsertMetadata(name, frontmatter) {
193
+ await this._deps.connection.query(`INSERT INTO instance_skills (name, frontmatter, updated_at)
194
+ VALUES ($1, $2::jsonb, now())
195
+ ON CONFLICT (name) DO UPDATE SET
196
+ frontmatter = EXCLUDED.frontmatter,
197
+ updated_at = now()`, [name, jsonbParam(frontmatter)]);
198
+ }
199
+ }
200
+ /** Собрать порт instance-скиллов (ADR-046 §4, ADR-116). */
201
+ export function buildSkillPorts(deps, blobs) {
202
+ return {
203
+ skills: new PgSkillRepository(deps, blobs),
204
+ };
205
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Общая заглушка портов PostgreSQL-драйвера (ADR-097, волна 3b).
3
+ *
4
+ * Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
5
+ * (прокси, любой доступ к методу которого бросает
6
+ * `PostgresStorageNotImplementedError` с именем порта). Это даёт:
7
+ * - контрактную поверхность `StorageContext` целиком (прокси отдаёт любой метод);
8
+ * - понятную ошибку вместо `undefined is not a function`;
9
+ * - один общий элемент для всех четырёх групп портов (`sessions`/`principals`/
10
+ * `events`/`content`), который волна реализации заменяет по мере готовности.
11
+ *
12
+ * Методы кэшируются (стабильные ссылки на функцию), символьные ключи не трогаем.
13
+ */
14
+ export declare function notImplementedPort<T>(port: string): T;
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Общая заглушка портов PostgreSQL-драйвера (ADR-097, волна 3b).
3
+ *
4
+ * Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
5
+ * (прокси, любой доступ к методу которого бросает
6
+ * `PostgresStorageNotImplementedError` с именем порта). Это даёт:
7
+ * - контрактную поверхность `StorageContext` целиком (прокси отдаёт любой метод);
8
+ * - понятную ошибку вместо `undefined is not a function`;
9
+ * - один общий элемент для всех четырёх групп портов (`sessions`/`principals`/
10
+ * `events`/`content`), который волна реализации заменяет по мере готовности.
11
+ *
12
+ * Методы кэшируются (стабильные ссылки на функцию), символьные ключи не трогаем.
13
+ */
14
+ import { PostgresStorageNotImplementedError } from '../errors.js';
15
+ export function notImplementedPort(port) {
16
+ const methods = new Map();
17
+ const proxy = new Proxy({}, {
18
+ get(_target, prop) {
19
+ if (typeof prop === 'symbol')
20
+ return undefined;
21
+ let method = methods.get(prop);
22
+ if (!method) {
23
+ method = () => {
24
+ throw new PostgresStorageNotImplementedError(`Порт '${port}' ещё не реализован в PostgreSQL-драйвере (ADR-097, волна реализации портов).`);
25
+ };
26
+ methods.set(prop, method);
27
+ }
28
+ return method;
29
+ },
30
+ });
31
+ return proxy;
32
+ }
@@ -0,0 +1,41 @@
1
+ /**
2
+ * PG-реализация порта **инвентаря git-worktree'ов** (ADR-114, ADR-097).
3
+ *
4
+ * Хранение — **существующий** generic-слой `documents(kind, key, value jsonb)`
5
+ * (миграция `001-init`): `kind = 'worktree'`, ключ документа — `id` записи,
6
+ * значение — сама запись (`WorktreeRecord`) целиком. Новая таблица и новая
7
+ * миграция **не нужны**: `kind` — свободный текст без CHECK-ограничений
8
+ * (ADR-114 §2.2), расширяется лишь список `kind` в драйвере.
9
+ *
10
+ * Семантика повторяет файловые реализации core (`FileWorktreeStore`) и
11
+ * in-memory (`MemoryWorktreeRepository`):
12
+ * - upsert по `id`: `createdAt` не перезаписывается (сохранённое значение
13
+ * приоритетно), `updatedAt` — метка вызывающего (драйвер не подставляет
14
+ * «сейчас»);
15
+ * - `list` — «свежие первыми» (`createdAt` убыв., тайбрейкер `id`), фильтр по
16
+ * проекту (поле записи);
17
+ * - `delete` — идемпотентно, `deleteByProject` — число удалённых записей.
18
+ *
19
+ * Порядок сортировки и фильтр считаются в драйвере (объём коллекции мал), а
20
+ * не SQL'ем: так семантика совпадает с файловым/в-памяти backend'ами
21
+ * байт-в-байт (сортировка по ISO-8601-метке, а не по тексту jsonb).
22
+ */
23
+ import type { StorageContext, WorktreeRepository } from '@itphx/synth-core';
24
+ import type { WorktreeRecord } from '@itphx/synth-shared';
25
+ import type { PortDeps } from './deps.js';
26
+ /** Часть `StorageContext`, которой владеет группа «worktrees». */
27
+ export type WorktreePorts = Pick<StorageContext, 'worktrees'>;
28
+ /** Порт инвентаря worktree'ов поверх таблицы `documents`. */
29
+ export declare class PgWorktreeRepository implements WorktreeRepository {
30
+ private readonly _deps;
31
+ constructor(_deps: PortDeps);
32
+ save(record: WorktreeRecord): Promise<void>;
33
+ get(id: string): Promise<WorktreeRecord | null>;
34
+ list(filter?: {
35
+ projectId?: string;
36
+ }): Promise<WorktreeRecord[]>;
37
+ delete(id: string): Promise<void>;
38
+ deleteByProject(projectId: string): Promise<number>;
39
+ }
40
+ /** Собрать порт инвентаря worktree'ов (ADR-114). */
41
+ export declare function buildWorktreePorts(deps: PortDeps): WorktreePorts;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * PG-реализация порта **инвентаря git-worktree'ов** (ADR-114, ADR-097).
3
+ *
4
+ * Хранение — **существующий** generic-слой `documents(kind, key, value jsonb)`
5
+ * (миграция `001-init`): `kind = 'worktree'`, ключ документа — `id` записи,
6
+ * значение — сама запись (`WorktreeRecord`) целиком. Новая таблица и новая
7
+ * миграция **не нужны**: `kind` — свободный текст без CHECK-ограничений
8
+ * (ADR-114 §2.2), расширяется лишь список `kind` в драйвере.
9
+ *
10
+ * Семантика повторяет файловые реализации core (`FileWorktreeStore`) и
11
+ * in-memory (`MemoryWorktreeRepository`):
12
+ * - upsert по `id`: `createdAt` не перезаписывается (сохранённое значение
13
+ * приоритетно), `updatedAt` — метка вызывающего (драйвер не подставляет
14
+ * «сейчас»);
15
+ * - `list` — «свежие первыми» (`createdAt` убыв., тайбрейкер `id`), фильтр по
16
+ * проекту (поле записи);
17
+ * - `delete` — идемпотентно, `deleteByProject` — число удалённых записей.
18
+ *
19
+ * Порядок сортировки и фильтр считаются в драйвере (объём коллекции мал), а
20
+ * не SQL'ем: так семантика совпадает с файловым/в-памяти backend'ами
21
+ * байт-в-байт (сортировка по ISO-8601-метке, а не по тексту jsonb).
22
+ */
23
+ import { jsonbParam } from '../json-param.js';
24
+ /** `kind` generic-таблицы `documents` для записей worktree. */
25
+ const WORKTREE_KIND = 'worktree';
26
+ /** Порт инвентаря worktree'ов поверх таблицы `documents`. */
27
+ export class PgWorktreeRepository {
28
+ _deps;
29
+ constructor(_deps) {
30
+ this._deps = _deps;
31
+ }
32
+ async save(record) {
33
+ await this._deps.connection.query(`INSERT INTO documents (kind, key, value, updated_at)
34
+ VALUES ($1, $2, $3::jsonb, now())
35
+ ON CONFLICT (kind, key) DO UPDATE SET
36
+ value = CASE
37
+ WHEN documents.value ? 'createdAt'
38
+ THEN jsonb_set(EXCLUDED.value, '{createdAt}', documents.value->'createdAt')
39
+ ELSE EXCLUDED.value
40
+ END,
41
+ updated_at = now()`, [WORKTREE_KIND, record.id, jsonbParam(record)]);
42
+ }
43
+ async get(id) {
44
+ const rows = await this._deps.connection.query('SELECT value FROM documents WHERE kind = $1 AND key = $2 LIMIT 1', [WORKTREE_KIND, id]);
45
+ const row = rows[0];
46
+ return row ? row.value : null;
47
+ }
48
+ async list(filter) {
49
+ const params = [WORKTREE_KIND];
50
+ let sql = 'SELECT value FROM documents WHERE kind = $1';
51
+ if (filter?.projectId !== undefined) {
52
+ params.push(filter.projectId);
53
+ sql += ` AND value->>'projectId' = $${params.length}`;
54
+ }
55
+ const rows = await this._deps.connection.query(sql, params);
56
+ const records = rows.map((row) => row.value);
57
+ // Свежие первыми (`createdAt` убыв.), тайбрейкер — `id`.
58
+ return [...records].sort(byCreatedAtDesc);
59
+ }
60
+ async delete(id) {
61
+ await this._deps.connection.query('DELETE FROM documents WHERE kind = $1 AND key = $2', [
62
+ WORKTREE_KIND,
63
+ id,
64
+ ]);
65
+ }
66
+ async deleteByProject(projectId) {
67
+ const rows = await this._deps.connection.query(`DELETE FROM documents
68
+ WHERE kind = $1 AND value->>'projectId' = $2
69
+ RETURNING key`, [WORKTREE_KIND, projectId]);
70
+ return rows.length;
71
+ }
72
+ }
73
+ /** Сортировка «свежие первыми» (`createdAt` убыв.), тайбрейкер — `id`. */
74
+ function byCreatedAtDesc(a, b) {
75
+ const diff = Date.parse(b.createdAt) - Date.parse(a.createdAt);
76
+ if (diff !== 0 && !Number.isNaN(diff))
77
+ return diff;
78
+ return a.id.localeCompare(b.id);
79
+ }
80
+ /** Собрать порт инвентаря worktree'ов (ADR-114). */
81
+ export function buildWorktreePorts(deps) {
82
+ return {
83
+ worktrees: new PgWorktreeRepository(deps),
84
+ };
85
+ }
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Драйвер слоя хранения Synth на PostgreSQL — публичная фабрика (ADR-097).
3
+ *
4
+ * Пакет `@itphx/synth-storage-postgres` — in-tree **опциональный** драйвер: он
5
+ * реализует доменные порты `StorageContext` и подключается из
6
+ * `createStorageContext` динамическим `import()` при `storage.backend === 'postgres'`.
7
+ *
8
+ * Волна 3a — **инфраструктура**: пул/подключение, схема БД и миграции
9
+ * (`migrate.ts` + `migrations/*`), сборка контекста (`storage-context.ts`).
10
+ * Доменные порты реализуются следующей волной, поэтому `createPostgresStorage`
11
+ * применяет (или проверяет) схему и возвращает контекст с файловыми FS-портами
12
+ * и заглушками PG-портов.
13
+ *
14
+ * `pg` — `optionalDependencies` пакета и подключается **лениво** (`pool.ts`):
15
+ * импорт модуля драйвера не требует установленного `pg`.
16
+ */
17
+ import type { StorageContext, StorageContextConfig } from '@itphx/synth-core';
18
+ import { type PostgresConnectionConfig } from './pool.js';
19
+ import type { CoreSyncDeps } from './ports/deps.js';
20
+ export * from './errors.js';
21
+ export type { PostgresPoolConfig, PostgresConnectionConfig } from './pool.js';
22
+ export type { PostgresExecutor } from './pool.js';
23
+ /** Конфиг драйвера: параметры подключения к БД + общие параметры слоя хранения. */
24
+ export interface PostgresStorageConfig extends StorageContextConfig, PostgresConnectionConfig {
25
+ /** Схема БД (по умолчанию — `public`). */
26
+ schema?: string;
27
+ /** Применять миграции схемы при сборке контекста (по умолчанию — `true`). */
28
+ migrate?: boolean;
29
+ /**
30
+ * ADR-097: режим работы со схемой при сборке (`apply`/`assert`/`skip`);
31
+ * приоритетнее `migrate`. `skip` — только подключение (диагностика/CLI,
32
+ * управляющие миграциями сами). Не задан — выводится из `migrate`
33
+ * (`false` → `assert`, иначе `apply`).
34
+ */
35
+ schemaMode?: 'apply' | 'assert' | 'skip';
36
+ /**
37
+ * ADR-097: синхронные данные/хелперы core (`secretPatterns`/
38
+ * `protectedPaths`/`dictionaries`), инъектируемые core'ом
39
+ * (`packages/core/src/storage/storage-context.ts`). Не заданы (прямой вызов
40
+ * фабрики) — драйвер собирает их ленивым `import('@itphx/synth-core')`.
41
+ */
42
+ coreSync?: CoreSyncDeps;
43
+ }
44
+ /**
45
+ * Валидация конфига **до** любого обращения к БД: нужен либо
46
+ * `connectionString`, либо пара `pool.host` + `pool.database`; схема — безопасный
47
+ * идентификатор.
48
+ */
49
+ export declare function validatePostgresConfig(config: PostgresStorageConfig): void;
50
+ /**
51
+ * Собрать `StorageContext` на PostgreSQL (форма — ADR-097).
52
+ *
53
+ * Валидирует конфиг, лениво подключается к БД, применяет миграции (или, при
54
+ * `migrate:false`, проверяет актуальность схемы — fail-closed) и возвращает
55
+ * контекст: FS/package-bound порты (`skills`/`contextFiles`/`blobs`) — файловые,
56
+ * остальные — заглушки PG (порты реализуются следующей волной).
57
+ */
58
+ export declare function createPostgresStorage(config: PostgresStorageConfig): Promise<StorageContext>;
@@ -0,0 +1,110 @@
1
+ /**
2
+ * Драйвер слоя хранения Synth на PostgreSQL — публичная фабрика (ADR-097).
3
+ *
4
+ * Пакет `@itphx/synth-storage-postgres` — in-tree **опциональный** драйвер: он
5
+ * реализует доменные порты `StorageContext` и подключается из
6
+ * `createStorageContext` динамическим `import()` при `storage.backend === 'postgres'`.
7
+ *
8
+ * Волна 3a — **инфраструктура**: пул/подключение, схема БД и миграции
9
+ * (`migrate.ts` + `migrations/*`), сборка контекста (`storage-context.ts`).
10
+ * Доменные порты реализуются следующей волной, поэтому `createPostgresStorage`
11
+ * применяет (или проверяет) схему и возвращает контекст с файловыми FS-портами
12
+ * и заглушками PG-портов.
13
+ *
14
+ * `pg` — `optionalDependencies` пакета и подключается **лениво** (`pool.ts`):
15
+ * импорт модуля драйвера не требует установленного `pg`.
16
+ */
17
+ import { PostgresStorageConfigError } from './errors.js';
18
+ import { assertSchemaCurrent, runMigrations } from './migrate.js';
19
+ import { createPostgresConnection, assertNoDsnTlsParams, } from './pool.js';
20
+ import { DEFAULT_SCHEMA, assertValidSchema } from './schema.js';
21
+ import { resolveCoreSyncDeps } from './ports/core-sync.js';
22
+ import { buildPostgresStorageContext } from './storage-context.js';
23
+ // Реэкспорт ошибок драйвера (в т.ч. для обратной совместимости импортов).
24
+ export * from './errors.js';
25
+ function isNonEmptyString(value) {
26
+ return typeof value === 'string' && value.trim().length > 0;
27
+ }
28
+ /**
29
+ * Валидация конфига **до** любого обращения к БД: нужен либо
30
+ * `connectionString`, либо пара `pool.host` + `pool.database`; схема — безопасный
31
+ * идентификатор.
32
+ */
33
+ export function validatePostgresConfig(config) {
34
+ if (!isNonEmptyString(config.dataDir)) {
35
+ throw new PostgresStorageConfigError('Не задан `dataDir` (базовый каталог инстанса).');
36
+ }
37
+ const pool = config.pool;
38
+ if (pool !== undefined) {
39
+ const port = pool.port;
40
+ if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65535)) {
41
+ throw new PostgresStorageConfigError(`Некорректный \`pool.port\`: ${String(port)} (ожидается целое 1–65535).`);
42
+ }
43
+ }
44
+ if (config.schema !== undefined)
45
+ assertValidSchema(config.schema);
46
+ // ADR-099/ADR-097: fail-closed до обращения к БД — TLS-параметры в DSN
47
+ // молча перекрываются конфигом (`pg` накладывает DSN поверх `ssl`).
48
+ assertNoDsnTlsParams(config.connectionString);
49
+ const hasConnectionString = isNonEmptyString(config.connectionString);
50
+ const hasPoolFields = !!pool && isNonEmptyString(pool.host) && isNonEmptyString(pool.database);
51
+ if (!hasConnectionString && !hasPoolFields) {
52
+ throw new PostgresStorageConfigError('Не задан способ подключения: укажите `connectionString` либо `pool.host` + `pool.database`.');
53
+ }
54
+ }
55
+ /**
56
+ * Собрать `StorageContext` на PostgreSQL (форма — ADR-097).
57
+ *
58
+ * Валидирует конфиг, лениво подключается к БД, применяет миграции (или, при
59
+ * `migrate:false`, проверяет актуальность схемы — fail-closed) и возвращает
60
+ * контекст: FS/package-bound порты (`skills`/`contextFiles`/`blobs`) — файловые,
61
+ * остальные — заглушки PG (порты реализуются следующей волной).
62
+ */
63
+ export async function createPostgresStorage(config) {
64
+ validatePostgresConfig(config);
65
+ const schema = config.schema ?? DEFAULT_SCHEMA;
66
+ const conn = createPostgresConnection({
67
+ connectionString: config.connectionString,
68
+ pool: config.pool,
69
+ // ADR-099: доверие TLS/CA (`security.tls`) и env для резолва — единый источник.
70
+ tls: config.tls,
71
+ env: config.env,
72
+ password: config.password,
73
+ schema,
74
+ statementTimeoutMillis: config.statementTimeoutMillis,
75
+ idleInTransactionTimeoutMillis: config.idleInTransactionTimeoutMillis,
76
+ applicationName: config.applicationName,
77
+ });
78
+ try {
79
+ // ADR-097: режим схемы — `apply` (дефолт), `assert` (DBA), `skip` (диагностика).
80
+ const schemaMode = config.schemaMode ?? config.postgresSchemaMode
81
+ ?? (config.migrate === false ? 'assert' : 'apply');
82
+ if (schemaMode === 'assert') {
83
+ await assertSchemaCurrent(conn, { schema });
84
+ }
85
+ else if (schemaMode === 'apply') {
86
+ await runMigrations(conn, { schema });
87
+ }
88
+ }
89
+ catch (err) {
90
+ await conn.end().catch(() => undefined);
91
+ throw err;
92
+ }
93
+ // ADR-097: соединение удерживается в контексте (порты БД ходят через него),
94
+ // `ctx.close()` закрывает пул. Незанятые соединения не удерживают event loop
95
+ // (`allowExitOnIdle` в `pool.ts`), поэтому CLI-команды завершаются.
96
+ return buildPostgresStorageContext({
97
+ dataDir: config.dataDir,
98
+ secretKey: config.secretKey,
99
+ env: config.env,
100
+ systemDictionariesDir: config.systemDictionariesDir,
101
+ contextUserDataDir: config.contextUserDataDir,
102
+ connection: conn,
103
+ // Инъекция из core (штатный путь) либо ленивый `import()` (прямой вызов).
104
+ coreSync: config.coreSync ??
105
+ (await resolveCoreSyncDeps({
106
+ dataDir: config.dataDir,
107
+ systemDictionariesDir: config.systemDictionariesDir,
108
+ })),
109
+ });
110
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Работа с идентификатором схемы PostgreSQL (namespace таблиц драйвера).
3
+ *
4
+ * Имена схем подставляются в DDL/`search_path`, поэтому принимаются только
5
+ * безопасные идентификаторы (буква/`_`, далее буквы/цифры/`_`) — параметризовать
6
+ * идентификаторы нельзя, а `quoteIdent` оборачивает имя в кавычки.
7
+ */
8
+ /** Схема по умолчанию (`public`), если в конфиге не задано иное. */
9
+ export declare const DEFAULT_SCHEMA = "public";
10
+ /** Проверяет, что имя схемы — безопасный идентификатор (иначе конфиг-ошибка). */
11
+ export declare function assertValidSchema(schema: string): string;
12
+ /** Экранирование идентификатора (двойные кавычки) для подстановки в SQL. */
13
+ export declare function quoteIdent(ident: string): string;
package/dist/schema.js ADDED
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Работа с идентификатором схемы PostgreSQL (namespace таблиц драйвера).
3
+ *
4
+ * Имена схем подставляются в DDL/`search_path`, поэтому принимаются только
5
+ * безопасные идентификаторы (буква/`_`, далее буквы/цифры/`_`) — параметризовать
6
+ * идентификаторы нельзя, а `quoteIdent` оборачивает имя в кавычки.
7
+ */
8
+ import { PostgresStorageConfigError } from './errors.js';
9
+ const SCHEMA_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
10
+ /** Схема по умолчанию (`public`), если в конфиге не задано иное. */
11
+ export const DEFAULT_SCHEMA = 'public';
12
+ /** Проверяет, что имя схемы — безопасный идентификатор (иначе конфиг-ошибка). */
13
+ export function assertValidSchema(schema) {
14
+ if (!SCHEMA_RE.test(schema)) {
15
+ throw new PostgresStorageConfigError(`Некорректное имя схемы \`${schema}\`: допустимы буквы/цифры/подчёркивание, первым символом — не цифра.`);
16
+ }
17
+ return schema;
18
+ }
19
+ /** Экранирование идентификатора (двойные кавычки) для подстановки в SQL. */
20
+ export function quoteIdent(ident) {
21
+ return `"${ident.replace(/"/g, '""')}"`;
22
+ }