robisie 0.1.4 → 0.2.1

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 (50) hide show
  1. package/CHANGELOG.md +29 -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 +145 -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/disk-guard.d.ts +20 -0
  16. package/dist/disk-guard.js +63 -0
  17. package/dist/done-evidence.d.ts +25 -1
  18. package/dist/done-evidence.js +59 -1
  19. package/dist/engine/bundle-report.json +1687 -0
  20. package/dist/engine/tick.cjs +324787 -0
  21. package/dist/engine-config.d.ts +3 -1
  22. package/dist/engine-config.js +3 -3
  23. package/dist/factory-run.d.ts +17 -0
  24. package/dist/factory-run.js +262 -0
  25. package/dist/helpers.js +1 -1
  26. package/dist/k3-codex-job.d.ts +49 -0
  27. package/dist/k3-codex-job.js +324 -0
  28. package/dist/k3-codex-role.js +4 -1
  29. package/dist/k3-helper-cli.d.ts +5 -0
  30. package/dist/k3-helper-cli.js +193 -0
  31. package/dist/local-usage.d.ts +47 -0
  32. package/dist/local-usage.js +230 -0
  33. package/dist/manifest.d.ts +5 -2
  34. package/dist/manifest.js +6 -6
  35. package/dist/planer-client.d.ts +45 -4
  36. package/dist/planer-client.js +120 -14
  37. package/dist/roles.d.ts +1 -1
  38. package/dist/select-fingerprint.d.ts +19 -0
  39. package/dist/select-fingerprint.js +46 -0
  40. package/dist/test-report.d.ts +9 -0
  41. package/dist/test-report.js +139 -0
  42. package/dist/tester-result-reader.d.ts +87 -0
  43. package/dist/tester-result-reader.js +122 -0
  44. package/docs/ENGINE-API.md +9 -1
  45. package/docs/README.en.md +58 -17
  46. package/docs/README.md +56 -17
  47. package/docs/RELEASE-0.1.0.md +28 -5
  48. package/helpers/ceo-client-launcher-mcp.mjs +76 -5
  49. package/package.json +6 -2
  50. package/roles/ceo-client.md +10 -8
package/dist/commands.js CHANGED
@@ -1,15 +1,41 @@
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";
7
+ import { reportDoctorDisk } from "./disk-guard.js";
5
8
  import { applyOp, assertCodexChange, checkRecovery, preserveFileStep, capture, entryPresent, fingerprint, prepareBlock, refusePrivateSymlink, renderBlock, restore, undoEntry } from "./fsops.js";
6
9
  import { HELPER_TOOLS, probeHelper } from "./helpers.js";
7
10
  import { clientPaths, ensurePrivateDir, readKey, readManifest, writeKey, writeManifest, roleProviders, ROLE_IDS, ROLE_STEP } from "./manifest.js";
8
11
  import { assertCompatible, checkConnection, fetchContractVersion } from "./mcp.js";
9
- import { loadRoles, rolesDir } from "./roles.js";
12
+ import { loadRoles, MANAGED_LINE, rolesDir } from "./roles.js";
10
13
  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\`.`;
14
+ 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
15
  const ENV_KEY_FORMAT_STEP = `W zsh/bash wykonaj \`unset ROBISIE_KEY\` — ENV ma pierwszeństwo przed pytaniem, stdin i plikiem. ${KEY_FORMAT_STEP}`;
16
+ 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`.";
17
+ function validateReviewKey(reviewKey, key) {
18
+ if (!reviewKey)
19
+ throw new RobisieError("Brak klucza odbioru ROBISIE_REVIEW_KEY.", REVIEW_KEY_STEP);
20
+ if (!KEY_PATTERN.test(reviewKey))
21
+ throw new RobisieError("ROBISIE_REVIEW_KEY ma niepoprawny format.", REVIEW_KEY_STEP);
22
+ if (reviewKey === key)
23
+ throw new RobisieError("Klucz odbioru B jest tym samym tokenem co klucz A.", REVIEW_KEY_STEP);
24
+ }
25
+ async function obtainReviewKey(ctx, prior) {
26
+ let key = ctx.env.ROBISIE_REVIEW_KEY || (prior ? readKey(agentPaths(ctx).clientDir, "review-key") : null);
27
+ if (!key && ctx.askSecret)
28
+ key = (await ctx.askSecret("Wklej klucz odbioru ROBISIE_REVIEW_KEY (ukryty): ")).trim();
29
+ return key;
30
+ }
31
+ async function checkReviewKey(ctx, key) {
32
+ try {
33
+ await checkConnection(ctx, key);
34
+ }
35
+ catch {
36
+ throw new RobisieError("Nie potwierdzono dostępu B do tablicy.", REVIEW_KEY_STEP);
37
+ }
38
+ }
13
39
  /** Advice chooses an executable CLI, not merely a leftover configuration directory. */
14
40
  export function initRecoveryStep(ctx, preferred) {
15
41
  let prior;
@@ -27,6 +53,8 @@ export function initRecoveryStep(ctx, preferred) {
27
53
  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
54
  }
29
55
  export function recoveryStep(ctx, step) {
56
+ // Transport auth advice must request fresh input when init can reuse a saved key.
57
+ 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
58
  return step.includes(ROLE_STEP) ? step.replace(ROLE_STEP, initRecoveryStep(ctx)) : step;
31
59
  }
32
60
  function ceoProjectStep(count) {
@@ -38,9 +66,13 @@ function ceoProjectStep(count) {
38
66
  function entryId(entry) {
39
67
  return `${entry.kind}:${entry.path}:${entry.keyPath?.join(".") ?? ""}`;
40
68
  }
41
- async function obtainKey(ctx, keyStdin) {
69
+ async function obtainKey(ctx, keyStdin, prior) {
42
70
  let key = ctx.env[KEY_ENV]?.trim() ?? "";
43
71
  let source = KEY_ENV;
72
+ if (!key && !keyStdin && prior) {
73
+ source = "pliku";
74
+ key = readKey(clientPaths(agentPaths(ctx).clientDir).dir) ?? "";
75
+ }
44
76
  if (!key && ctx.askSecret) {
45
77
  source = "ukrytego pytania";
46
78
  key = (await ctx.askSecret("Wklej klucz robisie (rob_…, nie będzie widoczny): ")).trim();
@@ -60,7 +92,7 @@ async function obtainKey(ctx, keyStdin) {
60
92
  export async function init(ctx, options) {
61
93
  const paths = clientPaths(agentPaths(ctx).clientDir);
62
94
  const prior = readManifest(paths.manifest);
63
- const detected = options.agents ?? detectAgents(ctx);
95
+ const detected = options.agents ?? prior?.agents ?? detectAgents(ctx);
64
96
  const previousMap = prior ? roleProviders(prior) : roleProviders({ agents: detected });
65
97
  let map = previousMap;
66
98
  if (options.roles && Object.keys(options.roles).length > 0) {
@@ -74,12 +106,15 @@ export async function init(ctx, options) {
74
106
  if (selected.length === 0) {
75
107
  throw new RobisieError("Nie znalazłem na tym komputerze Claude Code, Codex CLI ani OpenCode.", initRecoveryStep(ctx));
76
108
  }
77
- const key = await obtainKey(ctx, options.keyStdin);
109
+ const key = await obtainKey(ctx, options.keyStdin, prior);
110
+ const reviewKey = await obtainReviewKey(ctx, prior);
111
+ validateReviewKey(reviewKey, key);
78
112
  // Refuse before writing anything: incompatible server, or a key that does not open the board.
79
113
  assertCompatible(await fetchContractVersion(ctx));
80
114
  const connection = await checkConnection(ctx, key);
81
115
  if (connection.contractVersion)
82
116
  assertCompatible(connection.contractVersion);
117
+ await checkReviewKey(ctx, reviewKey);
83
118
  const roles = loadRoles(options.rolesDir ?? rolesDir());
84
119
  const planned = [];
85
120
  for (const id of selected)
@@ -104,6 +139,7 @@ export async function init(ctx, options) {
104
139
  // 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
140
  writeManifest(paths.dir, { agents, roleProviders: map, entries: [...done.values()] });
106
141
  writeKey(paths.dir, key);
142
+ writeKey(paths.dir, reviewKey, "review-key");
107
143
  for (const { owner, op } of planned) {
108
144
  const id = entryId(op);
109
145
  const before = capture(op.path);
@@ -142,16 +178,77 @@ export async function init(ctx, options) {
142
178
  ctx.out(`✓ ${AGENT_LABELS[id]}: serwer MCP robisie i role klienta (CEO, Builder, Quality Officer) zainstalowane.`);
143
179
  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
180
  if (profile)
145
- ctx.out(`✓ Klucz będzie dostępny jako ${KEY_ENV} w nowych terminalach (wpis w ${profile}).`);
181
+ ctx.out(`✓ Klucze będą dostępne jako ${KEY_ENV} i ROBISIE_REVIEW_KEY w nowych terminalach (wpis w ${profile}).`);
146
182
  else {
147
183
  const reason = !options.shell ? "--no-shell" : !ctx.env.SHELL ? "brak SHELL" : "niewspierana powłoka/platforma";
148
184
  ctx.out(`! Pominięto profil: ${reason}. Ustaw sam zmienną ${KEY_ENV} dla agenta, np.: ${SHELL_EXPORT}`);
149
185
  }
150
186
  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
187
  }
188
+ /** Only exact pins in our planned entries and the role's first content line count as versions. */
189
+ function installedVersions(op, text) {
190
+ const version = (value) => typeof value === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value) ? value : null;
191
+ const pin = (args, name) => {
192
+ 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}@`))
193
+ return null;
194
+ return version(args[1].slice(PACKAGE_NAME.length + 1));
195
+ };
196
+ const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
197
+ text = text.replace(/\r\n/g, "\n");
198
+ if (op.kind === "file" && op.content.includes(MANAGED_LINE)) {
199
+ const body = text.replace(/^---\n[\s\S]*?\n---\n/, "");
200
+ const marker = body.split("\n")[0] ?? "";
201
+ const actual = version(/^<!-- robisie:managed (\S+) —/.exec(marker)?.[1]);
202
+ const versions = [actual && marker === MANAGED_LINE.replace(PACKAGE_VERSION, actual) ? actual : null];
203
+ // Claude's generated YAML uses JSON arrays. Read only named helper entries in its frontmatter.
204
+ const header = text.startsWith("---\n") ? text.slice(4, text.indexOf("\n---\n", 4)) : "";
205
+ for (const name of HELPER_SERVERS) {
206
+ if (!op.content.includes(` - ${name}:\n`))
207
+ continue;
208
+ const args = new RegExp(`^ - ${name}:\n type: stdio\n command: npx\n args: ([^\n]+)$`, "m").exec(header)?.[1];
209
+ try {
210
+ versions.push(pin(args ? JSON.parse(args) : null, name));
211
+ }
212
+ catch {
213
+ versions.push(null);
214
+ }
215
+ }
216
+ return versions;
217
+ }
218
+ if (op.kind === "block" && op.clean) {
219
+ const [begin, , end] = renderBlock(op.comment, "").trimEnd().split("\n");
220
+ const lines = text.split("\n");
221
+ const start = lines.indexOf(begin ?? "");
222
+ const stop = lines.indexOf(end ?? "", start + 1);
223
+ if (start < 0 || stop < 0)
224
+ return [];
225
+ try {
226
+ const servers = object(parse(lines.slice(start + 1, stop).join("\n")).mcp_servers);
227
+ return HELPER_SERVERS.map(name => {
228
+ const helper = object(servers[name]);
229
+ return helper.command === "npx" ? pin(helper.args, name) : null;
230
+ });
231
+ }
232
+ catch {
233
+ return [];
234
+ }
235
+ }
236
+ if (op.kind === "json" && HELPER_SERVERS.some(name => op.keyPath[1] === name)) {
237
+ try {
238
+ const helper = object(object(object(JSON.parse(text))[op.keyPath[0]])[op.keyPath[1]]);
239
+ const args = helper.command;
240
+ return [Array.isArray(args) && args[0] === "npx" ? pin(args.slice(1), op.keyPath[1]) : null];
241
+ }
242
+ catch {
243
+ return [];
244
+ }
245
+ }
246
+ return [];
247
+ }
152
248
  // ── doctor ───────────────────────────────────────────────────────────────────
153
249
  /** Returns the process exit code: 0 = all good, 1 = something needs one action. */
154
250
  export async function doctor(ctx) {
251
+ ctx.out("! Polityka enforced: NIE SPRAWDZONO — klient nie ma API jej odczytu.");
155
252
  const problems = [];
156
253
  const fail = (line, nextStep) => {
157
254
  ctx.out(`✗ ${line}`);
@@ -170,6 +267,10 @@ export async function doctor(ctx) {
170
267
  };
171
268
  ctx.out(`Paczka ${PACKAGE_NAME} ${PACKAGE_VERSION}`);
172
269
  const paths = clientPaths(agentPaths(ctx).clientDir);
270
+ // Same 15 HOLD / 18 unblock thresholds as the packaged engine (engine-context disk()).
271
+ const disk = reportDoctorDisk(ctx.out, ctx.cwd);
272
+ if (!disk.ok && disk.nextStep)
273
+ problems.push(recoveryStep(ctx, disk.nextStep));
173
274
  // Ledger recovery must remain the next step even when network checks fail.
174
275
  let manifest = null;
175
276
  await guard(async () => {
@@ -206,6 +307,16 @@ export async function doctor(ctx) {
206
307
  fail(`CEO wymaga dokładnie 1 projektu (projektów: ${connection.projectCount}).`, ceoProjectStep(connection.projectCount));
207
308
  });
208
309
  }
310
+ await guard(async () => {
311
+ if (!usableKey || !KEY_PATTERN.test(usableKey))
312
+ return;
313
+ const reviewKey = ctx.env.ROBISIE_REVIEW_KEY || readKey(paths.dir, "review-key");
314
+ validateReviewKey(reviewKey, usableKey);
315
+ await checkReviewKey(ctx, reviewKey);
316
+ ctx.out("✓ Klucz B uwierzytelnia odczyt projektów.");
317
+ if (!ctx.env.ROBISIE_REVIEW_KEY)
318
+ 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\`.`);
319
+ });
209
320
  const installed = manifest;
210
321
  let map = null;
211
322
  if (installed)
@@ -222,7 +333,9 @@ export async function doctor(ctx) {
222
333
  const assigned = assignment ? ROLE_IDS.filter((role) => assignment[role] === id).join(", ") : "nie przypisano";
223
334
  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
335
  }
336
+ await guard(async () => { assertCodexEnvironment(id, ctx.platform); });
225
337
  }
338
+ const versions = new Set();
226
339
  const byId = new Map(installed.entries.map((entry) => [entryId(entry), entry]));
227
340
  for (const id of new Set([...installed.agents, ...Object.values(assignment ?? {})])) {
228
341
  const repair = `Uruchom \`npx robisie init --agent ${id}\`${id === "claude" ? " z właściwym ROBISIE_KEY w środowisku" : ""} — uzupełni braki.`;
@@ -240,7 +353,17 @@ export async function doctor(ctx) {
240
353
  const detail = assignment ? ROLE_IDS.filter((role) => assignment[role] === id).map((role) => `${role} → ${id}: niepełna instalacja`).join(", ") : "";
241
354
  throw new RobisieError(`${AGENT_LABELS[id]}: ${error.message}${detail ? ` Role: ${detail}.` : ""}`, error.nextStep);
242
355
  }
243
- if (!entry || entry.owner !== id || !entryPresent(entry))
356
+ if (!entry || entry.owner !== id)
357
+ return true;
358
+ const actual = installedVersions(op, capture(op.path).bytes?.toString("utf8") ?? "");
359
+ for (const value of actual)
360
+ if (value)
361
+ versions.add(value);
362
+ if (actual.some(value => value === null))
363
+ return true;
364
+ if (actual.some(value => value !== PACKAGE_VERSION))
365
+ return false;
366
+ if (!entryPresent(entry))
244
367
  return true;
245
368
  if (op.kind === "file" && capture(op.path).bytes?.toString("utf8") !== op.content)
246
369
  return true;
@@ -277,6 +400,9 @@ export async function doctor(ctx) {
277
400
  }
278
401
  });
279
402
  }
403
+ if ([...versions].some(version => version !== PACKAGE_VERSION)) {
404
+ 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.");
405
+ }
280
406
  if (!assignment) {
281
407
  const provider = installed.agents[0];
282
408
  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 +491,7 @@ export function uninstall(ctx) {
365
491
  }
366
492
  // The key is not needed to finish an uninstall, even after a warning or a failure.
367
493
  rmSync(paths.key, { force: true });
494
+ rmSync(paths.reviewKey, { force: true });
368
495
  for (const entry of [...manifest.entries].reverse()) {
369
496
  const warning = undoEntry(entry, codexConfigs.has(entry.path) ? (text) => removeCodexTables(text, true) : undefined);
370
497
  if (warning)
@@ -408,18 +535,20 @@ export function uninstall(ctx) {
408
535
  ctx.out(backupNotice);
409
536
  if (leftovers.length > 0)
410
537
  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.");
538
+ ctx.out("Następny krok: otwórz nowy terminal, żeby zmienne ROBISIE_KEY i ROBISIE_REVIEW_KEY zniknęły z sesji.");
412
539
  return 0;
413
540
  }
414
541
  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"})`;
542
+ for (const [path, label] of [[paths.key, "klucza"], [paths.reviewKey, "klucza odbioru"]]) {
543
+ let state = "pozostaje";
544
+ try {
545
+ lstatSync(path);
546
+ }
547
+ catch (error) {
548
+ const code = error.code;
549
+ state = code === "ENOENT" ? "nie istnieje" : `nie można ustalić (${typeof code === "string" && /^E[A-Z0-9_]{1,39}$/.test(code) ? code : "błąd metadanych"})`;
550
+ }
551
+ ctx.out(`Lokalny plik ${label}: ${state} — ${path}.`);
422
552
  }
423
- ctx.out(`Lokalny plik klucza: ${state} — ${paths.key}.`);
424
553
  }
425
554
  }
@@ -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.1";
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.1"; // 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;