robisie 0.1.4 → 0.2.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.
Files changed (47) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +39 -11
  3. package/dist/agents.d.ts +1 -1
  4. package/dist/agents.js +1 -1
  5. package/dist/ci-failure-result.js +1 -1
  6. package/dist/cli.d.ts +2 -0
  7. package/dist/cli.js +45 -8
  8. package/dist/codex-env.d.ts +9 -0
  9. package/dist/codex-env.js +60 -0
  10. package/dist/commands.js +140 -16
  11. package/dist/constants.d.ts +1 -1
  12. package/dist/constants.js +1 -1
  13. package/dist/delivery-local.d.ts +124 -0
  14. package/dist/delivery-local.js +286 -0
  15. package/dist/done-evidence.d.ts +25 -1
  16. package/dist/done-evidence.js +59 -1
  17. package/dist/engine/bundle-report.json +1687 -0
  18. package/dist/engine/tick.cjs +324704 -0
  19. package/dist/engine-config.d.ts +3 -1
  20. package/dist/engine-config.js +3 -3
  21. package/dist/factory-run.d.ts +17 -0
  22. package/dist/factory-run.js +262 -0
  23. package/dist/helpers.js +1 -1
  24. package/dist/k3-codex-job.d.ts +49 -0
  25. package/dist/k3-codex-job.js +324 -0
  26. package/dist/k3-helper-cli.d.ts +5 -0
  27. package/dist/k3-helper-cli.js +167 -0
  28. package/dist/local-usage.d.ts +47 -0
  29. package/dist/local-usage.js +230 -0
  30. package/dist/manifest.d.ts +5 -2
  31. package/dist/manifest.js +6 -6
  32. package/dist/planer-client.d.ts +45 -4
  33. package/dist/planer-client.js +120 -14
  34. package/dist/roles.d.ts +1 -1
  35. package/dist/select-fingerprint.d.ts +19 -0
  36. package/dist/select-fingerprint.js +46 -0
  37. package/dist/test-report.d.ts +9 -0
  38. package/dist/test-report.js +139 -0
  39. package/dist/tester-result-reader.d.ts +87 -0
  40. package/dist/tester-result-reader.js +122 -0
  41. package/docs/ENGINE-API.md +9 -1
  42. package/docs/README.en.md +55 -16
  43. package/docs/README.md +53 -16
  44. package/docs/RELEASE-0.1.0.md +27 -5
  45. package/helpers/ceo-client-launcher-mcp.mjs +76 -5
  46. package/package.json +6 -2
  47. package/roles/ceo-client.md +10 -8
package/dist/commands.js CHANGED
@@ -1,15 +1,40 @@
1
1
  import { lstatSync, readdirSync, rmdirSync, rmSync } from "node:fs";
2
+ import { parse } from "smol-toml";
2
3
  import { AGENT_IDS, AGENT_LABELS, SHELL_EXPORT, agentPaths, agentOnPath, detectAgents, planAgent, removeCodexTables, shellProfile } from "./agents.js";
3
4
  import { HELPER_SERVERS, KEY_ENV, KEY_PATTERN, PACKAGE_NAME, PACKAGE_VERSION } from "./constants.js";
4
5
  import { RobisieError, errorMessage } from "./context.js";
6
+ import { assertCodexEnvironment } from "./codex-env.js";
5
7
  import { applyOp, assertCodexChange, checkRecovery, preserveFileStep, capture, entryPresent, fingerprint, prepareBlock, refusePrivateSymlink, renderBlock, restore, undoEntry } from "./fsops.js";
6
8
  import { HELPER_TOOLS, probeHelper } from "./helpers.js";
7
9
  import { clientPaths, ensurePrivateDir, readKey, readManifest, writeKey, writeManifest, roleProviders, ROLE_IDS, ROLE_STEP } from "./manifest.js";
8
10
  import { assertCompatible, checkConnection, fetchContractVersion } from "./mcp.js";
9
- import { loadRoles, rolesDir } from "./roles.js";
11
+ import { loadRoles, MANAGED_LINE, rolesDir } from "./roles.js";
10
12
  const NO_KEY_STEP = "Wygeneruj klucz worker na https://robisie.app/dashboard/connect; w zsh/bash wykonaj `unset ROBISIE_KEY`, potem lokalne `npx robisie init` i wklej klucz w ukrytym pytaniu (poza rozmową).";
11
- const KEY_FORMAT_STEP = `Skopiuj klucz jeszcze raz z https://robisie.app/dashboard/connect; uruchom lokalne \`npx robisie init\` i wklej klucz w ukrytym pytaniu (poza rozmową). Alternatywnie przekaż klucz przez stdin z jawną flagą: \`npx robisie init --key-stdin\` (poza rozmową i historią poleceń). Następnie wczytaj zapisany klucz do bieżącej sesji POSIX z tym samym XDG_CONFIG_HOME: \`${SHELL_EXPORT}\`, potem uruchom \`npx robisie doctor\`.`;
13
+ const KEY_FORMAT_STEP = `Skopiuj klucz jeszcze raz z https://robisie.app/dashboard/connect; ustaw poprawny ROBISIE_KEY w środowisku lokalnego init (poza rozmową i historią poleceń) albo przekaż klucz przez stdin z jawną flagą: \`npx robisie init --key-stdin\` (poza rozmową i historią poleceń). Następnie wczytaj zapisany klucz do bieżącej sesji POSIX z tym samym XDG_CONFIG_HOME: \`${SHELL_EXPORT}\`, potem uruchom \`npx robisie doctor\`.`;
12
14
  const ENV_KEY_FORMAT_STEP = `W zsh/bash wykonaj \`unset ROBISIE_KEY\` — ENV ma pierwszeństwo przed pytaniem, stdin i plikiem. ${KEY_FORMAT_STEP}`;
15
+ const REVIEW_KEY_STEP = "Sprawdź dostęp do https://robisie.app/dashboard/connect; wygeneruj NOWY klucz owner_validator z etykietą inną niż A (powtórzenie etykiety A rotuje A). Ustaw ROBISIE_REVIEW_KEY w środowisku lokalnego init poza rozmową i historią poleceń, potem `npx robisie init` i `npx robisie doctor`.";
16
+ function validateReviewKey(reviewKey, key) {
17
+ if (!reviewKey)
18
+ throw new RobisieError("Brak klucza odbioru ROBISIE_REVIEW_KEY.", REVIEW_KEY_STEP);
19
+ if (!KEY_PATTERN.test(reviewKey))
20
+ throw new RobisieError("ROBISIE_REVIEW_KEY ma niepoprawny format.", REVIEW_KEY_STEP);
21
+ if (reviewKey === key)
22
+ throw new RobisieError("Klucz odbioru B jest tym samym tokenem co klucz A.", REVIEW_KEY_STEP);
23
+ }
24
+ async function obtainReviewKey(ctx, prior) {
25
+ let key = ctx.env.ROBISIE_REVIEW_KEY || (prior ? readKey(agentPaths(ctx).clientDir, "review-key") : null);
26
+ if (!key && ctx.askSecret)
27
+ key = (await ctx.askSecret("Wklej klucz odbioru ROBISIE_REVIEW_KEY (ukryty): ")).trim();
28
+ return key;
29
+ }
30
+ async function checkReviewKey(ctx, key) {
31
+ try {
32
+ await checkConnection(ctx, key);
33
+ }
34
+ catch {
35
+ throw new RobisieError("Nie potwierdzono dostępu B do tablicy.", REVIEW_KEY_STEP);
36
+ }
37
+ }
13
38
  /** Advice chooses an executable CLI, not merely a leftover configuration directory. */
14
39
  export function initRecoveryStep(ctx, preferred) {
15
40
  let prior;
@@ -27,6 +52,8 @@ export function initRecoveryStep(ctx, preferred) {
27
52
  return `${historyStep ? `${historyStep} Zachowana historia instalacji nadal wymaga tych programów. Potem: ` : ""}Uruchom \`npx robisie init --agent ${provider} --role ceo=${provider} --role builder=${provider} --role quality=${provider}\` (role: ceo, builder, quality; dostawcy: claude, codex, opencode).`;
28
53
  }
29
54
  export function recoveryStep(ctx, step) {
55
+ // Transport auth advice must request fresh input when init can reuse a saved key.
56
+ step = step.replace("`npx robisie init` z ukrytym pytaniem.", "`npx robisie init --key-stdin` z ukrytym pytaniem lub stdin (poza rozmową i historią poleceń).");
30
57
  return step.includes(ROLE_STEP) ? step.replace(ROLE_STEP, initRecoveryStep(ctx)) : step;
31
58
  }
32
59
  function ceoProjectStep(count) {
@@ -38,9 +65,13 @@ function ceoProjectStep(count) {
38
65
  function entryId(entry) {
39
66
  return `${entry.kind}:${entry.path}:${entry.keyPath?.join(".") ?? ""}`;
40
67
  }
41
- async function obtainKey(ctx, keyStdin) {
68
+ async function obtainKey(ctx, keyStdin, prior) {
42
69
  let key = ctx.env[KEY_ENV]?.trim() ?? "";
43
70
  let source = KEY_ENV;
71
+ if (!key && !keyStdin && prior) {
72
+ source = "pliku";
73
+ key = readKey(clientPaths(agentPaths(ctx).clientDir).dir) ?? "";
74
+ }
44
75
  if (!key && ctx.askSecret) {
45
76
  source = "ukrytego pytania";
46
77
  key = (await ctx.askSecret("Wklej klucz robisie (rob_…, nie będzie widoczny): ")).trim();
@@ -60,7 +91,7 @@ async function obtainKey(ctx, keyStdin) {
60
91
  export async function init(ctx, options) {
61
92
  const paths = clientPaths(agentPaths(ctx).clientDir);
62
93
  const prior = readManifest(paths.manifest);
63
- const detected = options.agents ?? detectAgents(ctx);
94
+ const detected = options.agents ?? prior?.agents ?? detectAgents(ctx);
64
95
  const previousMap = prior ? roleProviders(prior) : roleProviders({ agents: detected });
65
96
  let map = previousMap;
66
97
  if (options.roles && Object.keys(options.roles).length > 0) {
@@ -74,12 +105,15 @@ export async function init(ctx, options) {
74
105
  if (selected.length === 0) {
75
106
  throw new RobisieError("Nie znalazłem na tym komputerze Claude Code, Codex CLI ani OpenCode.", initRecoveryStep(ctx));
76
107
  }
77
- const key = await obtainKey(ctx, options.keyStdin);
108
+ const key = await obtainKey(ctx, options.keyStdin, prior);
109
+ const reviewKey = await obtainReviewKey(ctx, prior);
110
+ validateReviewKey(reviewKey, key);
78
111
  // Refuse before writing anything: incompatible server, or a key that does not open the board.
79
112
  assertCompatible(await fetchContractVersion(ctx));
80
113
  const connection = await checkConnection(ctx, key);
81
114
  if (connection.contractVersion)
82
115
  assertCompatible(connection.contractVersion);
116
+ await checkReviewKey(ctx, reviewKey);
83
117
  const roles = loadRoles(options.rolesDir ?? rolesDir());
84
118
  const planned = [];
85
119
  for (const id of selected)
@@ -104,6 +138,7 @@ export async function init(ctx, options) {
104
138
  // The record first, then the key and the changes: a disk that fills up cannot leave a key or a change uninstall does not know about.
105
139
  writeManifest(paths.dir, { agents, roleProviders: map, entries: [...done.values()] });
106
140
  writeKey(paths.dir, key);
141
+ writeKey(paths.dir, reviewKey, "review-key");
107
142
  for (const { owner, op } of planned) {
108
143
  const id = entryId(op);
109
144
  const before = capture(op.path);
@@ -142,16 +177,77 @@ export async function init(ctx, options) {
142
177
  ctx.out(`✓ ${AGENT_LABELS[id]}: serwer MCP robisie i role klienta (CEO, Builder, Quality Officer) zainstalowane.`);
143
178
  ctx.out(changed === 0 ? (mapChanged ? "✓ mapa ról zmieniona; konfiguracja agentów bez zmian." : "Nic się nie zmieniło — wszystko było już zainstalowane.") : `Zmienione pliki: ${changed} (kopie zapasowe: ${paths.backups}).`);
144
179
  if (profile)
145
- ctx.out(`✓ Klucz będzie dostępny jako ${KEY_ENV} w nowych terminalach (wpis w ${profile}).`);
180
+ ctx.out(`✓ Klucze będą dostępne jako ${KEY_ENV} i ROBISIE_REVIEW_KEY w nowych terminalach (wpis w ${profile}).`);
146
181
  else {
147
182
  const reason = !options.shell ? "--no-shell" : !ctx.env.SHELL ? "brak SHELL" : "niewspierana powłoka/platforma";
148
183
  ctx.out(`! Pominięto profil: ${reason}. Ustaw sam zmienną ${KEY_ENV} dla agenta, np.: ${SHELL_EXPORT}`);
149
184
  }
150
185
  ctx.out(`Następny krok: ${!map || map.ceo !== map.builder || map.ceo !== map.quality ? initRecoveryStep(ctx, map?.ceo) : "otwórz nowy terminal i uruchom `npx robisie doctor`."}`);
151
186
  }
187
+ /** Only exact pins in our planned entries and the role's first content line count as versions. */
188
+ function installedVersions(op, text) {
189
+ const version = (value) => typeof value === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value) ? value : null;
190
+ const pin = (args, name) => {
191
+ if (!Array.isArray(args) || args.length !== 4 || args[0] !== "-y" || args[2] !== "mcp" || args[3] !== name || typeof args[1] !== "string" || !args[1].startsWith(`${PACKAGE_NAME}@`))
192
+ return null;
193
+ return version(args[1].slice(PACKAGE_NAME.length + 1));
194
+ };
195
+ const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
196
+ text = text.replace(/\r\n/g, "\n");
197
+ if (op.kind === "file" && op.content.includes(MANAGED_LINE)) {
198
+ const body = text.replace(/^---\n[\s\S]*?\n---\n/, "");
199
+ const marker = body.split("\n")[0] ?? "";
200
+ const actual = version(/^<!-- robisie:managed (\S+) —/.exec(marker)?.[1]);
201
+ const versions = [actual && marker === MANAGED_LINE.replace(PACKAGE_VERSION, actual) ? actual : null];
202
+ // Claude's generated YAML uses JSON arrays. Read only named helper entries in its frontmatter.
203
+ const header = text.startsWith("---\n") ? text.slice(4, text.indexOf("\n---\n", 4)) : "";
204
+ for (const name of HELPER_SERVERS) {
205
+ if (!op.content.includes(` - ${name}:\n`))
206
+ continue;
207
+ const args = new RegExp(`^ - ${name}:\n type: stdio\n command: npx\n args: ([^\n]+)$`, "m").exec(header)?.[1];
208
+ try {
209
+ versions.push(pin(args ? JSON.parse(args) : null, name));
210
+ }
211
+ catch {
212
+ versions.push(null);
213
+ }
214
+ }
215
+ return versions;
216
+ }
217
+ if (op.kind === "block" && op.clean) {
218
+ const [begin, , end] = renderBlock(op.comment, "").trimEnd().split("\n");
219
+ const lines = text.split("\n");
220
+ const start = lines.indexOf(begin ?? "");
221
+ const stop = lines.indexOf(end ?? "", start + 1);
222
+ if (start < 0 || stop < 0)
223
+ return [];
224
+ try {
225
+ const servers = object(parse(lines.slice(start + 1, stop).join("\n")).mcp_servers);
226
+ return HELPER_SERVERS.map(name => {
227
+ const helper = object(servers[name]);
228
+ return helper.command === "npx" ? pin(helper.args, name) : null;
229
+ });
230
+ }
231
+ catch {
232
+ return [];
233
+ }
234
+ }
235
+ if (op.kind === "json" && HELPER_SERVERS.some(name => op.keyPath[1] === name)) {
236
+ try {
237
+ const helper = object(object(object(JSON.parse(text))[op.keyPath[0]])[op.keyPath[1]]);
238
+ const args = helper.command;
239
+ return [Array.isArray(args) && args[0] === "npx" ? pin(args.slice(1), op.keyPath[1]) : null];
240
+ }
241
+ catch {
242
+ return [];
243
+ }
244
+ }
245
+ return [];
246
+ }
152
247
  // ── doctor ───────────────────────────────────────────────────────────────────
153
248
  /** Returns the process exit code: 0 = all good, 1 = something needs one action. */
154
249
  export async function doctor(ctx) {
250
+ ctx.out("! Polityka enforced: NIE SPRAWDZONO — klient nie ma API jej odczytu.");
155
251
  const problems = [];
156
252
  const fail = (line, nextStep) => {
157
253
  ctx.out(`✗ ${line}`);
@@ -206,6 +302,16 @@ export async function doctor(ctx) {
206
302
  fail(`CEO wymaga dokładnie 1 projektu (projektów: ${connection.projectCount}).`, ceoProjectStep(connection.projectCount));
207
303
  });
208
304
  }
305
+ await guard(async () => {
306
+ if (!usableKey || !KEY_PATTERN.test(usableKey))
307
+ return;
308
+ const reviewKey = ctx.env.ROBISIE_REVIEW_KEY || readKey(paths.dir, "review-key");
309
+ validateReviewKey(reviewKey, usableKey);
310
+ await checkReviewKey(ctx, reviewKey);
311
+ ctx.out("✓ Klucz B uwierzytelnia odczyt projektów.");
312
+ if (!ctx.env.ROBISIE_REVIEW_KEY)
313
+ fail("Zmienna ROBISIE_REVIEW_KEY nie jest ustawiona — silnik jej potrzebuje.", `Wczytaj oba klucze w bieżącej sesji POSIX: ${SHELL_EXPORT}. Potem uruchom \`npx robisie doctor\`.`);
314
+ });
209
315
  const installed = manifest;
210
316
  let map = null;
211
317
  if (installed)
@@ -222,7 +328,9 @@ export async function doctor(ctx) {
222
328
  const assigned = assignment ? ROLE_IDS.filter((role) => assignment[role] === id).join(", ") : "nie przypisano";
223
329
  fail(`${assigned} → ${id}: ${detectAgents(ctx).includes(id) ? "katalog jest, programu nie ma w PATH" : "brak programu w PATH i katalogu dostawcy"}.`, `Zainstaluj program ${id} lub dodaj go do PATH i ponów \`npx robisie doctor\`.`);
224
330
  }
331
+ await guard(async () => { assertCodexEnvironment(id, ctx.platform); });
225
332
  }
333
+ const versions = new Set();
226
334
  const byId = new Map(installed.entries.map((entry) => [entryId(entry), entry]));
227
335
  for (const id of new Set([...installed.agents, ...Object.values(assignment ?? {})])) {
228
336
  const repair = `Uruchom \`npx robisie init --agent ${id}\`${id === "claude" ? " z właściwym ROBISIE_KEY w środowisku" : ""} — uzupełni braki.`;
@@ -240,7 +348,17 @@ export async function doctor(ctx) {
240
348
  const detail = assignment ? ROLE_IDS.filter((role) => assignment[role] === id).map((role) => `${role} → ${id}: niepełna instalacja`).join(", ") : "";
241
349
  throw new RobisieError(`${AGENT_LABELS[id]}: ${error.message}${detail ? ` Role: ${detail}.` : ""}`, error.nextStep);
242
350
  }
243
- if (!entry || entry.owner !== id || !entryPresent(entry))
351
+ if (!entry || entry.owner !== id)
352
+ return true;
353
+ const actual = installedVersions(op, capture(op.path).bytes?.toString("utf8") ?? "");
354
+ for (const value of actual)
355
+ if (value)
356
+ versions.add(value);
357
+ if (actual.some(value => value === null))
358
+ return true;
359
+ if (actual.some(value => value !== PACKAGE_VERSION))
360
+ return false;
361
+ if (!entryPresent(entry))
244
362
  return true;
245
363
  if (op.kind === "file" && capture(op.path).bytes?.toString("utf8") !== op.content)
246
364
  return true;
@@ -277,6 +395,9 @@ export async function doctor(ctx) {
277
395
  }
278
396
  });
279
397
  }
398
+ if ([...versions].some(version => version !== PACKAGE_VERSION)) {
399
+ fail(`Nieaktualna instalacja — zainstalowane wersje: ${[...versions].sort().join(", ")}; wersja paczki: ${PACKAGE_VERSION}.`, "Uruchom `npx robisie init` — odświeży instalację z zapisanym kluczem, bez ponownego wpisywania.");
400
+ }
280
401
  if (!assignment) {
281
402
  const provider = installed.agents[0];
282
403
  fail("Role: nie przypisano dostawców.", `Uruchom \`npx robisie init --agent ${provider} --role ceo=${provider} --role builder=${provider} --role quality=${provider}\`. Aby wybrać innego zainstalowanego dostawcę (${installed.agents.join(", ")}), zastąp ${provider} jego nazwą we wszystkich czterech miejscach.`);
@@ -365,6 +486,7 @@ export function uninstall(ctx) {
365
486
  }
366
487
  // The key is not needed to finish an uninstall, even after a warning or a failure.
367
488
  rmSync(paths.key, { force: true });
489
+ rmSync(paths.reviewKey, { force: true });
368
490
  for (const entry of [...manifest.entries].reverse()) {
369
491
  const warning = undoEntry(entry, codexConfigs.has(entry.path) ? (text) => removeCodexTables(text, true) : undefined);
370
492
  if (warning)
@@ -408,18 +530,20 @@ export function uninstall(ctx) {
408
530
  ctx.out(backupNotice);
409
531
  if (leftovers.length > 0)
410
532
  ctx.out(`Zostawiłem niepuste katalogi: ${leftovers.join(", ")}.`);
411
- ctx.out("Następny krok: otwórz nowy terminal, żeby zmienna ROBISIE_KEY zniknęła z sesji.");
533
+ ctx.out("Następny krok: otwórz nowy terminal, żeby zmienne ROBISIE_KEY i ROBISIE_REVIEW_KEY zniknęły z sesji.");
412
534
  return 0;
413
535
  }
414
536
  finally {
415
- let state = "pozostaje";
416
- try {
417
- lstatSync(paths.key);
418
- }
419
- catch (error) {
420
- const code = error.code;
421
- state = code === "ENOENT" ? "nie istnieje" : `nie można ustalić (${typeof code === "string" && /^E[A-Z0-9_]{1,39}$/.test(code) ? code : "błąd metadanych"})`;
537
+ for (const [path, label] of [[paths.key, "klucza"], [paths.reviewKey, "klucza odbioru"]]) {
538
+ let state = "pozostaje";
539
+ try {
540
+ lstatSync(path);
541
+ }
542
+ catch (error) {
543
+ const code = error.code;
544
+ state = code === "ENOENT" ? "nie istnieje" : `nie można ustalić (${typeof code === "string" && /^E[A-Z0-9_]{1,39}$/.test(code) ? code : "błąd metadanych"})`;
545
+ }
546
+ ctx.out(`Lokalny plik ${label}: ${state} — ${path}.`);
422
547
  }
423
- ctx.out(`Lokalny plik klucza: ${state} — ${paths.key}.`);
424
548
  }
425
549
  }
@@ -1,6 +1,6 @@
1
1
  /** Package identity and the server contract it speaks. */
2
2
  export declare const PACKAGE_NAME = "robisie";
3
- export declare const PACKAGE_VERSION = "0.1.4";
3
+ export declare const PACKAGE_VERSION = "0.2.0";
4
4
  /**
5
5
  * MAJOR of the agent-API contract this package understands.
6
6
  * PARITY: src/lib/mcp/contract-version.ts (AGENT_API_CONTRACT_VERSION) on the server.
package/dist/constants.js CHANGED
@@ -1,6 +1,6 @@
1
1
  /** Package identity and the server contract it speaks. */
2
2
  export const PACKAGE_NAME = "robisie";
3
- export const PACKAGE_VERSION = "0.1.4"; // x-release-please-version
3
+ export const PACKAGE_VERSION = "0.2.0"; // x-release-please-version
4
4
  /**
5
5
  * MAJOR of the agent-API contract this package understands.
6
6
  * PARITY: src/lib/mcp/contract-version.ts (AGENT_API_CONTRACT_VERSION) on the server.
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Dostawa lokalna (P4-a): scalenie karty do gałęzi celu bez GitHuba.
3
+ * Kolejność: prepare (merge-tree --write-tree, bez dotykania drzewa roboczego) → check (komendy wywołującego)
4
+ * → deliver (tylko fast-forward, `update-ref` z oczekiwaną starą wartością = CAS) → attachEvidence (notatki git).
5
+ * Żadna funkcja nie rzuca wyjątku z powodu gita ani komend — każdy wynik jest jawną wartością.
6
+ * check uruchamia komendy w tymczasowym, odłączonym worktree na `taskSha` (poza repo klienta), sprzątanym zawsze w `finally`;
7
+ * porażka sprzątania daje `cleanup-failed` (z zachowanymi wynikami komend), nigdy ukryte `ok: true`.
8
+ *
9
+ * Założenia współbieżności (świadomie nieobsłużone): deliver zakłada, że nikt nie wyewidencjonuje gałęzi celu
10
+ * między `git worktree list` a `git update-ref`; attachEvidence zakłada brak równoległych zapisów dowodu
11
+ * tego samego rodzaju (odczyt–dopisanie–zapis notatki nie jest atomowy).
12
+ */
13
+ export type EvidenceKind = "review" | "test" | "deliver";
14
+ export declare const EVIDENCE_KINDS: readonly EvidenceKind[];
15
+ export declare const DEFAULT_DELIVERY_ADAPTER = "local-ff";
16
+ export interface PrepareInput {
17
+ target: string;
18
+ taskSha: string;
19
+ }
20
+ export type Prepared = {
21
+ ok: true;
22
+ target: string;
23
+ /** Pełna nazwa refa celu, np. refs/heads/main. */
24
+ ref: string;
25
+ targetSha: string;
26
+ taskSha: string;
27
+ /** Drzewo wyniku scalenia z `merge-tree --write-tree`. */
28
+ tree: string;
29
+ /** fast-forward: cel jest przodkiem zadania; up-to-date: zadanie już jest w celu; merge: potrzebne scalenie (nie-FF). */
30
+ mode: "fast-forward" | "up-to-date" | "merge";
31
+ };
32
+ export type PrepareResult = Prepared | {
33
+ ok: false;
34
+ reason: "invalid-target" | "invalid-task" | "error";
35
+ message: string;
36
+ } | {
37
+ ok: false;
38
+ reason: "conflict";
39
+ message: string;
40
+ conflicts: string[];
41
+ };
42
+ export interface CheckCommand {
43
+ command: string;
44
+ args?: readonly string[];
45
+ }
46
+ export interface CheckOutcome {
47
+ command: string;
48
+ args: string[];
49
+ status: number | null;
50
+ signal: string | null;
51
+ output: string;
52
+ }
53
+ export type CleanupStep = "worktree-remove" | "rm-tmp" | "worktree-prune";
54
+ export interface CleanupFailure {
55
+ /** Kroki sprzątania, które padły (kod wyjścia ≠ 0 / wyjątek), z komunikatem. */
56
+ failed: {
57
+ step: CleanupStep;
58
+ message: string;
59
+ }[];
60
+ /** Ścieżka worktree, który mógł zostać w repo klienta (i jego katalog tymczasowy). */
61
+ worktree: string;
62
+ tmp: string;
63
+ /** Wynik komend, gdy same komendy też się nie powiodły — oba fakty widoczne. */
64
+ checkFailed?: {
65
+ reason: "check-failed" | "error";
66
+ message: string;
67
+ };
68
+ }
69
+ export type CheckResult = {
70
+ ok: true;
71
+ results: CheckOutcome[];
72
+ } | {
73
+ ok: false;
74
+ reason: "check-failed" | "error";
75
+ message: string;
76
+ results: CheckOutcome[];
77
+ } | {
78
+ ok: false;
79
+ reason: "cleanup-failed";
80
+ message: string;
81
+ results: CheckOutcome[];
82
+ detail: CleanupFailure;
83
+ };
84
+ export type DeliverResult = {
85
+ ok: true;
86
+ moved: boolean;
87
+ ref: string;
88
+ from: string;
89
+ to: string;
90
+ } | {
91
+ ok: false;
92
+ reason: "not-fast-forward" | "target-moved" | "target-checked-out" | "target-is-symbolic-ref" | "error";
93
+ message: string;
94
+ };
95
+ export type EvidenceResult = {
96
+ ok: true;
97
+ ref: string;
98
+ sha: string;
99
+ written: boolean;
100
+ } | {
101
+ ok: false;
102
+ reason: "invalid-kind" | "invalid-sha" | "evidence-read-failed" | "error";
103
+ message: string;
104
+ };
105
+ export interface Delivery {
106
+ prepare(input: PrepareInput): PrepareResult;
107
+ /** Komendy biegną w izolowanym worktree na `prepared.taskSha` (cwd = ten worktree), nie w repo klienta. */
108
+ check(prepared: Prepared, commands: readonly CheckCommand[], options?: {
109
+ timeoutMs?: number;
110
+ }): CheckResult;
111
+ deliver(prepared: Prepared): DeliverResult;
112
+ attachEvidence(sha: string, kind: EvidenceKind, evidence: unknown): EvidenceResult;
113
+ }
114
+ /** Odczyt dowodów (wiersze JSON) z refs/notes/robisie/<kind> przy SHA. */
115
+ export declare function readEvidence(repo: string, kind: EvidenceKind, sha: string): {
116
+ ok: true;
117
+ entries: unknown[];
118
+ } | {
119
+ ok: false;
120
+ reason: "invalid-kind" | "evidence-read-failed" | "error";
121
+ message: string;
122
+ };
123
+ /** Adapter `local-ff` (domyślny): scalenie lokalne wyłącznie przez fast-forward z CAS. */
124
+ export declare function createLocalFfDelivery(repo: string): Delivery;