@itphx/synth-storage-postgres 0.11.3 → 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 (141) hide show
  1. package/dist/errors.d.ts +1 -1
  2. package/dist/errors.js +2 -2
  3. package/dist/index.d.ts +15 -1
  4. package/dist/index.js +24 -2
  5. package/dist/locks.d.ts +4 -4
  6. package/dist/locks.js +4 -4
  7. package/dist/migrate.d.ts +1 -1
  8. package/dist/migrate.js +1 -1
  9. package/dist/migrations/001-init.d.ts +2 -2
  10. package/dist/migrations/001-init.js +2 -2
  11. package/dist/migrations/003-analytics-rollups.d.ts +1 -1
  12. package/dist/migrations/003-analytics-rollups.js +1 -1
  13. package/dist/migrations/004-pipeline-engine.d.ts +19 -0
  14. package/dist/migrations/004-pipeline-engine.js +74 -0
  15. package/dist/migrations/005-pipeline-provenance.d.ts +12 -0
  16. package/dist/migrations/005-pipeline-provenance.js +15 -0
  17. package/dist/migrations/006-plugin-audit.d.ts +13 -0
  18. package/dist/migrations/006-plugin-audit.js +34 -0
  19. package/dist/migrations/007-plugin-lock.d.ts +10 -0
  20. package/dist/migrations/007-plugin-lock.js +25 -0
  21. package/dist/migrations/008-plugin-audit-scan.d.ts +11 -0
  22. package/dist/migrations/008-plugin-audit-scan.js +15 -0
  23. package/dist/migrations/009-plugin-lock-previous.d.ts +13 -0
  24. package/dist/migrations/009-plugin-lock-previous.js +16 -0
  25. package/dist/migrations/010-plugin-lock-mode.d.ts +16 -0
  26. package/dist/migrations/010-plugin-lock-mode.js +20 -0
  27. package/dist/migrations/011-session-steer-inbox.d.ts +11 -0
  28. package/dist/migrations/011-session-steer-inbox.js +14 -0
  29. package/dist/migrations/012-external-credentials.d.ts +15 -0
  30. package/dist/migrations/012-external-credentials.js +40 -0
  31. package/dist/migrations/013-service-key-plugin-id.d.ts +17 -0
  32. package/dist/migrations/013-service-key-plugin-id.js +20 -0
  33. package/dist/migrations/014-session-mode-by-principal.d.ts +12 -0
  34. package/dist/migrations/014-session-mode-by-principal.js +15 -0
  35. package/dist/migrations/015-authority.d.ts +17 -0
  36. package/dist/migrations/015-authority.js +43 -0
  37. package/dist/migrations/016-credential-audit.d.ts +17 -0
  38. package/dist/migrations/016-credential-audit.js +32 -0
  39. package/dist/migrations/017-memory.d.ts +29 -0
  40. package/dist/migrations/017-memory.js +95 -0
  41. package/dist/migrations/018-memory-index-scope.d.ts +14 -0
  42. package/dist/migrations/018-memory-index-scope.js +18 -0
  43. package/dist/migrations/019-memory-index-enabled.d.ts +11 -0
  44. package/dist/migrations/019-memory-index-enabled.js +14 -0
  45. package/dist/migrations/020-project-memory.d.ts +11 -0
  46. package/dist/migrations/020-project-memory.js +13 -0
  47. package/dist/migrations/021-background-runs.d.ts +17 -0
  48. package/dist/migrations/021-background-runs.js +67 -0
  49. package/dist/migrations/022-background-run-process-id.d.ts +14 -0
  50. package/dist/migrations/022-background-run-process-id.js +18 -0
  51. package/dist/migrations/023-session-worktree.d.ts +12 -0
  52. package/dist/migrations/023-session-worktree.js +16 -0
  53. package/dist/migrations/024-blob-refs.d.ts +15 -0
  54. package/dist/migrations/024-blob-refs.js +26 -0
  55. package/dist/migrations/025-packs-pipelines.d.ts +28 -0
  56. package/dist/migrations/025-packs-pipelines.js +82 -0
  57. package/dist/migrations/026-instance-skills.d.ts +17 -0
  58. package/dist/migrations/026-instance-skills.js +25 -0
  59. package/dist/migrations/027-context-files.d.ts +20 -0
  60. package/dist/migrations/027-context-files.js +30 -0
  61. package/dist/migrations/index.d.ts +1 -1
  62. package/dist/migrations/index.js +49 -1
  63. package/dist/pool.d.ts +6 -6
  64. package/dist/pool.js +8 -8
  65. package/dist/ports/analytics.d.ts +1 -1
  66. package/dist/ports/analytics.js +1 -1
  67. package/dist/ports/audit.d.ts +1 -1
  68. package/dist/ports/audit.js +3 -0
  69. package/dist/ports/authority.d.ts +27 -0
  70. package/dist/ports/authority.js +148 -0
  71. package/dist/ports/background-runs.d.ts +41 -0
  72. package/dist/ports/background-runs.js +179 -0
  73. package/dist/ports/blob-refs.d.ts +36 -0
  74. package/dist/ports/blob-refs.js +55 -0
  75. package/dist/ports/content.d.ts +1 -1
  76. package/dist/ports/content.js +21 -7
  77. package/dist/ports/context-files.d.ts +145 -0
  78. package/dist/ports/context-files.js +279 -0
  79. package/dist/ports/core-sync.d.ts +1 -1
  80. package/dist/ports/core-sync.js +1 -1
  81. package/dist/ports/credential-audit.d.ts +19 -0
  82. package/dist/ports/credential-audit.js +96 -0
  83. package/dist/ports/deps.d.ts +2 -2
  84. package/dist/ports/deps.js +1 -1
  85. package/dist/ports/events-bindings.d.ts +2 -2
  86. package/dist/ports/events-bindings.js +2 -2
  87. package/dist/ports/events-core.d.ts +1 -1
  88. package/dist/ports/events-core.js +1 -1
  89. package/dist/ports/events-journal.d.ts +1 -1
  90. package/dist/ports/events-journal.js +1 -1
  91. package/dist/ports/events-scheduler.d.ts +1 -1
  92. package/dist/ports/events-scheduler.js +1 -1
  93. package/dist/ports/events-webhooks.d.ts +1 -1
  94. package/dist/ports/events-webhooks.js +1 -1
  95. package/dist/ports/events.d.ts +1 -1
  96. package/dist/ports/events.js +1 -1
  97. package/dist/ports/external-credentials.d.ts +6 -0
  98. package/dist/ports/external-credentials.js +363 -0
  99. package/dist/ports/legacy-pipelines.d.ts +50 -0
  100. package/dist/ports/legacy-pipelines.js +202 -0
  101. package/dist/ports/memory.d.ts +65 -0
  102. package/dist/ports/memory.js +471 -0
  103. package/dist/ports/packs.d.ts +32 -0
  104. package/dist/ports/packs.js +117 -0
  105. package/dist/ports/pipelines.d.ts +67 -0
  106. package/dist/ports/pipelines.js +297 -0
  107. package/dist/ports/plugin-audit.d.ts +14 -0
  108. package/dist/ports/plugin-audit.js +110 -0
  109. package/dist/ports/plugin-lock.d.ts +27 -0
  110. package/dist/ports/plugin-lock.js +145 -0
  111. package/dist/ports/principals-defaults.d.ts +1 -1
  112. package/dist/ports/principals-defaults.js +1 -1
  113. package/dist/ports/principals-documents.d.ts +1 -1
  114. package/dist/ports/principals-documents.js +1 -1
  115. package/dist/ports/principals-profiles.d.ts +1 -1
  116. package/dist/ports/principals-profiles.js +1 -1
  117. package/dist/ports/principals-projects.d.ts +1 -1
  118. package/dist/ports/principals-projects.js +6 -3
  119. package/dist/ports/principals-settings.d.ts +1 -1
  120. package/dist/ports/principals-settings.js +21 -1
  121. package/dist/ports/principals-shared.d.ts +1 -1
  122. package/dist/ports/principals-shared.js +1 -1
  123. package/dist/ports/principals.d.ts +1 -1
  124. package/dist/ports/principals.js +1 -1
  125. package/dist/ports/questions.d.ts +40 -0
  126. package/dist/ports/questions.js +135 -0
  127. package/dist/ports/sessions-mapping.d.ts +20 -3
  128. package/dist/ports/sessions-mapping.js +46 -2
  129. package/dist/ports/sessions.d.ts +13 -3
  130. package/dist/ports/sessions.js +20 -5
  131. package/dist/ports/skills.d.ts +59 -0
  132. package/dist/ports/skills.js +205 -0
  133. package/dist/ports/stub.d.ts +1 -1
  134. package/dist/ports/stub.js +2 -2
  135. package/dist/ports/worktrees.d.ts +41 -0
  136. package/dist/ports/worktrees.js +85 -0
  137. package/dist/postgres-storage.d.ts +4 -5
  138. package/dist/postgres-storage.js +5 -6
  139. package/dist/storage-context.d.ts +44 -15
  140. package/dist/storage-context.js +139 -31
  141. package/package.json +4 -4
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Отображение строк PostgreSQL ↔ доменных объектов порта `SessionRepository`
3
- * (PROP-032, волна 3b).
3
+ * (ADR-097, волна 3b).
4
4
  *
5
5
  * Эталон семантики — файловая реализация (`core/src/storage/file-store.ts`):
6
6
  * `serializeSession`/`serializeMessage` и `deserializeSession`/`deserializeMessage`
@@ -225,9 +225,20 @@ export function serializeSession(session) {
225
225
  branch_point: session.branchPoint ?? null,
226
226
  plan_approved: session.planApproved ?? null,
227
227
  mode: session.mode ?? null,
228
+ mode_by_principal: session.modeByPrincipal ?? null,
228
229
  user_id: session.userId ?? null,
229
230
  owner_id: session.ownerId ?? null,
230
231
  project_id: session.projectId ?? null,
232
+ // ADR-114: привязка к worktree (объект в snake_case — как в JSON-файле).
233
+ worktree: session.worktree
234
+ ? {
235
+ worktree_id: session.worktree.worktreeId,
236
+ project_id: session.worktree.projectId,
237
+ ...(session.worktree.repoPath !== undefined ? { repo_path: session.worktree.repoPath } : {}),
238
+ directory: session.worktree.directory,
239
+ branch: session.worktree.branch,
240
+ }
241
+ : null,
231
242
  todos: session.todos ?? null,
232
243
  prompt_states: session.promptStates ?? null,
233
244
  obfuscation_map: session.obfuscationMap ?? null,
@@ -235,6 +246,7 @@ export function serializeSession(session) {
235
246
  settings: session.settings ?? {},
236
247
  mcp_servers: session.mcpServers ?? null,
237
248
  pending_messages: (session.pendingMessages ?? []).map((msg) => serializeMessage(msg)),
249
+ steer_inbox: (session.steerInbox ?? []).map((msg) => serializeMessage(msg)),
238
250
  current_stream: session.currentStream
239
251
  ? {
240
252
  stream_id: session.currentStream.streamId,
@@ -330,6 +342,29 @@ export function deserializeStickyNote(row) {
330
342
  disabled: row.disabled,
331
343
  };
332
344
  }
345
+ /**
346
+ * ADR-114: привязка сессии к worktree из jsonb-колонки `sessions.worktree`.
347
+ *
348
+ * Терпима к отсутствию поля (записи до миграции `023`) и к частичным
349
+ * значениям: привязка без `worktree_id`/`directory` бессмысленна — она
350
+ * игнорируется, сессия работает как прежде.
351
+ */
352
+ export function deserializeSessionWorktree(data) {
353
+ if (typeof data !== 'object' || data === null)
354
+ return undefined;
355
+ const raw = data;
356
+ const worktreeId = typeof raw.worktree_id === 'string' ? raw.worktree_id : '';
357
+ const directory = typeof raw.directory === 'string' ? raw.directory : '';
358
+ if (!worktreeId || !directory)
359
+ return undefined;
360
+ return {
361
+ worktreeId,
362
+ projectId: typeof raw.project_id === 'string' ? raw.project_id : '',
363
+ ...(typeof raw.repo_path === 'string' ? { repoPath: raw.repo_path } : {}),
364
+ directory,
365
+ branch: typeof raw.branch === 'string' ? raw.branch : '',
366
+ };
367
+ }
333
368
  /**
334
369
  * Строка `sessions` + child-данные → доменная сессия: дословный
335
370
  * `deserializeSession` файловой реализации (нормализация иконки/цвета,
@@ -338,6 +373,8 @@ export function deserializeStickyNote(row) {
338
373
  */
339
374
  export function deserializeSession(row, children) {
340
375
  const currentStream = row.current_stream;
376
+ // ADR-114: привязка к worktree (legacy-записи без поля → undefined).
377
+ const worktree = deserializeSessionWorktree(row.worktree);
341
378
  return {
342
379
  id: row.id,
343
380
  title: row.title ?? undefined,
@@ -347,6 +384,10 @@ export function deserializeSession(row, children) {
347
384
  branchPoint: row.branch_point ?? undefined,
348
385
  planApproved: row.plan_approved ?? undefined,
349
386
  mode: (row.mode ?? undefined),
387
+ // ADR-106 Ф4 (шаг C): режим по принципалу.
388
+ ...(row.mode_by_principal && Object.keys(row.mode_by_principal).length > 0
389
+ ? { modeByPrincipal: row.mode_by_principal }
390
+ : {}),
350
391
  todos: (row.todos ?? undefined),
351
392
  promptStates: (row.prompt_states ?? undefined),
352
393
  obfuscationMap: (row.obfuscation_map ?? undefined),
@@ -354,8 +395,11 @@ export function deserializeSession(row, children) {
354
395
  userId: row.user_id ?? undefined,
355
396
  ownerId: row.owner_id ?? undefined,
356
397
  projectId: row.project_id ?? undefined,
398
+ // ADR-114: привязка к worktree (legacy-записи без поля → undefined).
399
+ ...(worktree ? { worktree } : {}),
357
400
  messages: children.messages.map(deserializeMessage),
358
401
  pendingMessages: (row.pending_messages ?? []).map(deserializeMessage),
402
+ steerInbox: (row.steer_inbox ?? []).map(deserializeMessage),
359
403
  status: (row.status ?? {}),
360
404
  settings: (row.settings ?? {}),
361
405
  mcpServers: (row.mcp_servers ?? undefined),
@@ -392,7 +436,7 @@ export function deserializeSession(row, children) {
392
436
  }
393
437
  /**
394
438
  * Строка `sessions` → доменная сессия **без истории** (`SessionRepository.listLight`,
395
- * PROP-032): `messages`/`pendingMessages`/`checkpoints` пусты, child-таблицы не
439
+ * ADR-097): `messages`/`pendingMessages`/`checkpoints` пусты, child-таблицы не
396
440
  * читаются. Метаданные (id/статус/settings/projectId/expiresAt/…) идентичны
397
441
  * `deserializeSession` — механика переиспользуется.
398
442
  */
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Порт `SessionRepository` поверх PostgreSQL (PROP-032, волна 3b).
2
+ * Порт `SessionRepository` поверх PostgreSQL (ADR-097, волна 3b).
3
3
  *
4
4
  * Группа портов **сессий** PostgreSQL-драйвера: единственная фабрика
5
5
  * `buildSessionPorts(deps)` собирает `StorageContext['sessions']`.
@@ -50,13 +50,23 @@ import type { SessionFilter, SessionRepository, StorageContext } from '@itphx/sy
50
50
  import type { PortDeps } from './deps.js';
51
51
  /** Часть `StorageContext`, которой владеет группа `sessions`. */
52
52
  export type SessionPorts = Pick<StorageContext, 'sessions'>;
53
+ /**
54
+ * Колонки `sessions` (порядок — как в `001_init`).
55
+ *
56
+ * Экспортируется для unit-тестов сериализации (как `MESSAGE_MUTABLE_FIELDS`):
57
+ * тест проверяет, что новая колонка (`worktree`, ADR-114) реально попадает в
58
+ * `INSERT` и читается обратно.
59
+ */
60
+ export declare const SESSION_FIELDS: readonly ["id", "title", "icon", "color", "session_origin", "parent_id", "branch_point", "plan_approved", "mode", "mode_by_principal", "user_id", "owner_id", "project_id", "worktree", "todos", "prompt_states", "obfuscation_map", "status", "settings", "mcp_servers", "pending_messages", "steer_inbox", "current_stream", "summarization_pending", "can_summarize", "created_at", "updated_at", "expires_at", "archived_at", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "cache_write_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_read_cost", "cache_write_cost", "cache_hit_rate"];
61
+ /** jsonb-колонки `sessions` (экспортируется для unit-тестов сериализации). */
62
+ export declare const SESSION_JSON_FIELDS: ReadonlySet<string>;
53
63
  /**
54
64
  * Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
55
65
  * суррогатный `message_uid` (PK), доменный `id`, `session_id`, позиционный
56
66
  * `seq` и `created_at`: они сохраняются от исходной строки (цель ищется по
57
67
  * `seq`, fallback по `id`).
58
68
  */
59
- export declare const MESSAGE_MUTABLE_FIELDS: ("origin" | "author" | "source" | "usage" | "model" | "provider" | "ephemeral" | "role" | "reasoning" | "content" | "disabled" | "pinned" | "hidden" | "metadata" | "agent_role" | "source_msg_id" | "parts" | "tool_calls" | "tool_call_id" | "prompt_meta" | "debug_data" | "summary_of" | "provider_type" | "qa_pass" | "qa_reason")[];
69
+ export declare const MESSAGE_MUTABLE_FIELDS: ("origin" | "author" | "source" | "usage" | "model" | "provider" | "metadata" | "ephemeral" | "disabled" | "content" | "role" | "reasoning" | "pinned" | "hidden" | "agent_role" | "source_msg_id" | "parts" | "tool_calls" | "tool_call_id" | "prompt_meta" | "debug_data" | "summary_of" | "provider_type" | "qa_pass" | "qa_reason")[];
60
70
  /** Значение для jsonb-колонки: нативный объект/массив → JSON-строка (NUL — вычищены). */
61
71
  export declare function jsonParam(value: unknown): string | null;
62
72
  /**
@@ -124,7 +134,7 @@ export declare class PostgresSessionRepository implements SessionRepository {
124
134
  * первая по `seq, created_at, id`), затем fallback по доменному `id`.
125
135
  */
126
136
  private _findMessageUid;
127
- /** PROP-032: per-session сериализация записи — транзакционный advisory-лок. */
137
+ /** ADR-097: per-session сериализация записи — транзакционный advisory-лок. */
128
138
  private _lockSession;
129
139
  /** `addReference`/`removeReference` отсутствующей сессии → ошибка (как в file/memory). */
130
140
  private _assertSessionExists;
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Порт `SessionRepository` поверх PostgreSQL (PROP-032, волна 3b).
2
+ * Порт `SessionRepository` поверх PostgreSQL (ADR-097, волна 3b).
3
3
  *
4
4
  * Группа портов **сессий** PostgreSQL-драйвера: единственная фабрика
5
5
  * `buildSessionPorts(deps)` собирает `StorageContext['sessions']`.
@@ -47,8 +47,14 @@
47
47
  import { jsonbParam } from '../json-param.js';
48
48
  import { generateId, makeTextPart, nowISO } from '@itphx/synth-shared';
49
49
  import { checkpointRow, deserializeMessage, deserializeReference, deserializeSession, deserializeSessionLight, emptySessionChildren, messageRow, referenceRow, serializeSession, stickyNoteRow, } from './sessions-mapping.js';
50
- /** Колонки `sessions` (порядок — как в `001_init`). */
51
- const SESSION_FIELDS = [
50
+ /**
51
+ * Колонки `sessions` (порядок — как в `001_init`).
52
+ *
53
+ * Экспортируется для unit-тестов сериализации (как `MESSAGE_MUTABLE_FIELDS`):
54
+ * тест проверяет, что новая колонка (`worktree`, ADR-114) реально попадает в
55
+ * `INSERT` и читается обратно.
56
+ */
57
+ export const SESSION_FIELDS = [
52
58
  'id',
53
59
  'title',
54
60
  'icon',
@@ -58,9 +64,12 @@ const SESSION_FIELDS = [
58
64
  'branch_point',
59
65
  'plan_approved',
60
66
  'mode',
67
+ 'mode_by_principal',
61
68
  'user_id',
62
69
  'owner_id',
63
70
  'project_id',
71
+ // ADR-114: привязка сессии к worktree (jsonb, миграция 023).
72
+ 'worktree',
64
73
  'todos',
65
74
  'prompt_states',
66
75
  'obfuscation_map',
@@ -68,6 +77,7 @@ const SESSION_FIELDS = [
68
77
  'settings',
69
78
  'mcp_servers',
70
79
  'pending_messages',
80
+ 'steer_inbox',
71
81
  'current_stream',
72
82
  'summarization_pending',
73
83
  'can_summarize',
@@ -87,7 +97,11 @@ const SESSION_FIELDS = [
87
97
  'cache_write_cost',
88
98
  'cache_hit_rate',
89
99
  ];
90
- const SESSION_JSON_FIELDS = new Set([
100
+ /** jsonb-колонки `sessions` (экспортируется для unit-тестов сериализации). */
101
+ export const SESSION_JSON_FIELDS = new Set([
102
+ 'mode_by_principal',
103
+ // ADR-114: привязка сессии к worktree (jsonb, миграция 023).
104
+ 'worktree',
91
105
  'todos',
92
106
  'prompt_states',
93
107
  'obfuscation_map',
@@ -95,6 +109,7 @@ const SESSION_JSON_FIELDS = new Set([
95
109
  'settings',
96
110
  'mcp_servers',
97
111
  'pending_messages',
112
+ 'steer_inbox',
98
113
  'current_stream',
99
114
  ]);
100
115
  /** Колонки `messages` (порядок — как в `001_init`). */
@@ -483,7 +498,7 @@ export class PostgresSessionRepository {
483
498
  }
484
499
  return null;
485
500
  }
486
- /** PROP-032: per-session сериализация записи — транзакционный advisory-лок. */
501
+ /** ADR-097: per-session сериализация записи — транзакционный advisory-лок. */
487
502
  async _lockSession(tx, sessionId) {
488
503
  await tx.query('SELECT pg_advisory_xact_lock(hashtext($1::text)::bigint)', [sessionId]);
489
504
  }
@@ -0,0 +1,59 @@
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 type { BlobStore, CreateSkillInput, SkillRepository, StorageContext, UpdateSkillMarkdownInput } from '@itphx/synth-core';
31
+ import type { PortDeps } from './deps.js';
32
+ /** Часть `StorageContext`, которой владеет группа «skills». */
33
+ export type SkillPorts = Pick<StorageContext, 'skills'>;
34
+ /**
35
+ * ADR-116: instance-скиллы — метаданные в `instance_skills`, содержимое в
36
+ * `BlobStore`.
37
+ */
38
+ export declare class PgSkillRepository implements SkillRepository {
39
+ private readonly _deps;
40
+ private readonly _blobs;
41
+ constructor(_deps: PortDeps, _blobs: BlobStore);
42
+ exists(name: string): Promise<boolean>;
43
+ listNames(): Promise<string[]>;
44
+ readMarkdown(name: string): Promise<string | null>;
45
+ create(input: CreateSkillInput): Promise<void>;
46
+ updateMarkdown(name: string, patch: UpdateSkillMarkdownInput): Promise<void>;
47
+ remove(name: string): Promise<boolean>;
48
+ readFile(name: string, relPath: string): Promise<string | null>;
49
+ writeFile(name: string, relPath: string, content: string): Promise<void>;
50
+ deleteFile(name: string, relPath: string): Promise<boolean>;
51
+ listFiles(name: string): Promise<Array<{
52
+ path: string;
53
+ size: number;
54
+ }>>;
55
+ /** Upsert метаданных: заголовок скилла и служебная метка записи. */
56
+ private _upsertMetadata;
57
+ }
58
+ /** Собрать порт instance-скиллов (ADR-046 §4, ADR-116). */
59
+ export declare function buildSkillPorts(deps: PortDeps, blobs: BlobStore): SkillPorts;
@@ -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
+ }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Общая заглушка портов PostgreSQL-драйвера (PROP-032, волна 3b).
2
+ * Общая заглушка портов PostgreSQL-драйвера (ADR-097, волна 3b).
3
3
  *
4
4
  * Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
5
5
  * (прокси, любой доступ к методу которого бросает
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Общая заглушка портов PostgreSQL-драйвера (PROP-032, волна 3b).
2
+ * Общая заглушка портов PostgreSQL-драйвера (ADR-097, волна 3b).
3
3
  *
4
4
  * Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
5
5
  * (прокси, любой доступ к методу которого бросает
@@ -21,7 +21,7 @@ export function notImplementedPort(port) {
21
21
  let method = methods.get(prop);
22
22
  if (!method) {
23
23
  method = () => {
24
- throw new PostgresStorageNotImplementedError(`Порт '${port}' ещё не реализован в PostgreSQL-драйвере (PROP-032, волна реализации портов).`);
24
+ throw new PostgresStorageNotImplementedError(`Порт '${port}' ещё не реализован в PostgreSQL-драйвере (ADR-097, волна реализации портов).`);
25
25
  };
26
26
  methods.set(prop, method);
27
27
  }
@@ -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
+ }