opencode-completion-gate 2.1.0 → 2.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.2.0](https://github.com/PauloDevelo/opencode-completion-gate/compare/v2.1.0...v2.2.0) (2026-11-19)
4
+
5
+
6
+ ### Features
7
+
8
+ * **gate:** write a structured run record for every evaluation ([#18](https://github.com/PauloDevelo/opencode-completion-gate/issues/18)) ([625c650](https://github.com/PauloDevelo/opencode-completion-gate/commit/625c65066df57deda09802860ab3811a3f6a1c15))
9
+
3
10
  ## [2.1.0](https://github.com/PauloDevelo/opencode-completion-gate/compare/v2.0.1...v2.1.0) (2026-11-19)
4
11
 
5
12
 
package/dist/core.d.ts CHANGED
@@ -10,6 +10,8 @@ export { buildShellInvocation, execFileOut, execShell, quoteWin, runCommand, tru
10
10
  export { findGateConfigPath, loadGateConfig, parseOnlyCommand, effectiveMaxRetries, } from './config.js';
11
11
  export { defaultBuildLogArtifact, downloadBuildLogs, extractTerminalBuildFailures, isHumanReviewPolicy, pickActivePr, pickActivePrDetails, requiredPoliciesGreen, runAdoPrAssertion, } from './ado-pr.js';
12
12
  export { parseVerdict, runReviewAssertion } from './review.js';
13
+ export { RUN_RECORD_DIR_ENV, buildRunRecord, runRecordDir, writeRunRecord } from './run-record.js';
14
+ export type { RunRecord, RunRecordAssertion, RunRecordInput } from './run-record.js';
13
15
  export type { AdoPrAssertion, AdoPrPollOptions, AssertionOutcome, BuildLogArtifact, BuildLogArtifactRunner, BuildLogDownloadOptions, BuildLogExtractor, CommandAssertion, GateAssertion, GateConfig, PolicyEvaluationMinimal, ProcessOutcome, ReviewAssertion, ReviewSessionClient, ShellFn, ShellInvocation, TerminalBuildFailure, } from './types.js';
14
16
  export type { PickPrDetailsResult, PickPrResult } from './ado-pr.js';
15
17
  export type { GateMode } from './config.js';
package/dist/index.js CHANGED
@@ -699,6 +699,62 @@ ${evidence}`);
699
699
  }
700
700
  }
701
701
 
702
+ // src/run-record.ts
703
+ import { mkdirSync as mkdirSync2, writeFileSync } from "fs";
704
+ import { homedir as homedir2 } from "os";
705
+ import { join as join4 } from "path";
706
+ var RUN_RECORD_DIR_ENV = "OPENCODE_GATE_RUN_DIR";
707
+ var EVIDENCE_LIMIT = 200;
708
+ function firstLine(text) {
709
+ const line = text.split("\n").map((l) => l.trim()).find((l) => l !== "") ?? "";
710
+ return line.length > EVIDENCE_LIMIT ? `${line.slice(0, EVIDENCE_LIMIT - 3)}...` : line;
711
+ }
712
+ function buildRunRecord(input) {
713
+ const assertions = input.results.map(
714
+ (result) => result.passed ? { name: result.name, passed: true } : { name: result.name, passed: false, evidence: firstLine(result.evidence) }
715
+ );
716
+ const byName = new Map(assertions.map((a) => [a.name, a]));
717
+ const everyExpectedPassed = input.expectedAssertions.length > 0 && input.expectedAssertions.every((name) => byName.get(name)?.passed === true);
718
+ return {
719
+ version: 1,
720
+ sessionId: input.sessionId,
721
+ configPath: input.configPath,
722
+ projectRoot: input.projectRoot,
723
+ platform: process.platform,
724
+ startedAt: input.startedAt,
725
+ finishedAt: input.finishedAt,
726
+ expected: input.expectedAssertions.length,
727
+ evaluated: assertions.length,
728
+ outcome: everyExpectedPassed ? "passed" : "failed",
729
+ assertions
730
+ };
731
+ }
732
+ function runRecordDir() {
733
+ const configured = process.env[RUN_RECORD_DIR_ENV]?.trim();
734
+ if (configured) return configured;
735
+ return join4(homedir2(), ".config", "opencode", "gate-runs");
736
+ }
737
+ function fileNameFor(sessionId) {
738
+ const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
739
+ return `${safe || "session"}.json`;
740
+ }
741
+ function writeRunRecord(input) {
742
+ const record = buildRunRecord(input);
743
+ const path = join4(runRecordDir(), fileNameFor(input.sessionId));
744
+ try {
745
+ mkdirSync2(runRecordDir(), { recursive: true });
746
+ writeFileSync(path, `${JSON.stringify(record, null, 2)}
747
+ `, "utf8");
748
+ } catch (err) {
749
+ logDiag(
750
+ `run record: could not write ${path}: ${err instanceof Error ? err.message : String(err)}`
751
+ );
752
+ return null;
753
+ }
754
+ logDiag(`run record: ${record.outcome} for ${input.sessionId} at ${path}`);
755
+ return { path, record };
756
+ }
757
+
702
758
  // src/gate.ts
703
759
  var MARKER = "[completion-gate]";
704
760
  var INTERNAL_MARKER = "[completion-gate-internal]";
@@ -992,6 +1048,7 @@ async function runGateTurnEnd(ctx, state) {
992
1048
  logDiag(
993
1049
  `gate turn-end on ${state.sessionID}: ${loaded ? `config ${loaded.path}` : "command-only without project config"} (${assertions.length} assertion(s), maxRetries=${cap.value} (${cap.source}), retries so far=${state.retries})`
994
1050
  );
1051
+ const startedAt = (/* @__PURE__ */ new Date()).toISOString();
995
1052
  const results = await evaluateAssertions(
996
1053
  assertions,
997
1054
  projectRoot,
@@ -1004,6 +1061,15 @@ async function runGateTurnEnd(ctx, state) {
1004
1061
  );
1005
1062
  return;
1006
1063
  }
1064
+ writeRunRecord({
1065
+ sessionId: state.sessionID,
1066
+ configPath: loaded?.path ?? null,
1067
+ projectRoot,
1068
+ startedAt,
1069
+ finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
1070
+ expectedAssertions: assertions.map((a) => a.name),
1071
+ results
1072
+ });
1007
1073
  const last = results[results.length - 1];
1008
1074
  if (!last) return;
1009
1075
  if (last.passed) {
@@ -1237,7 +1303,9 @@ var pluginMeta = {
1237
1303
  description: "Per-session quality gate that blocks declaring done until configured assertions pass"
1238
1304
  };
1239
1305
  export {
1306
+ RUN_RECORD_DIR_ENV,
1240
1307
  VERSION,
1308
+ buildRunRecord,
1241
1309
  buildShellInvocation,
1242
1310
  defaultBuildLogArtifact,
1243
1311
  downloadBuildLogs,
@@ -1259,6 +1327,8 @@ export {
1259
1327
  runAdoPrAssertion,
1260
1328
  runCommand,
1261
1329
  runCommandAssertion,
1330
+ runRecordDir,
1262
1331
  runReviewAssertion,
1263
- truncateTail
1332
+ truncateTail,
1333
+ writeRunRecord
1264
1334
  };
package/dist/plugin.js CHANGED
@@ -695,6 +695,62 @@ ${evidence}`);
695
695
  }
696
696
  }
697
697
 
698
+ // src/run-record.ts
699
+ import { mkdirSync as mkdirSync2, writeFileSync } from "fs";
700
+ import { homedir as homedir2 } from "os";
701
+ import { join as join4 } from "path";
702
+ var RUN_RECORD_DIR_ENV = "OPENCODE_GATE_RUN_DIR";
703
+ var EVIDENCE_LIMIT = 200;
704
+ function firstLine(text) {
705
+ const line = text.split("\n").map((l) => l.trim()).find((l) => l !== "") ?? "";
706
+ return line.length > EVIDENCE_LIMIT ? `${line.slice(0, EVIDENCE_LIMIT - 3)}...` : line;
707
+ }
708
+ function buildRunRecord(input) {
709
+ const assertions = input.results.map(
710
+ (result) => result.passed ? { name: result.name, passed: true } : { name: result.name, passed: false, evidence: firstLine(result.evidence) }
711
+ );
712
+ const byName = new Map(assertions.map((a) => [a.name, a]));
713
+ const everyExpectedPassed = input.expectedAssertions.length > 0 && input.expectedAssertions.every((name) => byName.get(name)?.passed === true);
714
+ return {
715
+ version: 1,
716
+ sessionId: input.sessionId,
717
+ configPath: input.configPath,
718
+ projectRoot: input.projectRoot,
719
+ platform: process.platform,
720
+ startedAt: input.startedAt,
721
+ finishedAt: input.finishedAt,
722
+ expected: input.expectedAssertions.length,
723
+ evaluated: assertions.length,
724
+ outcome: everyExpectedPassed ? "passed" : "failed",
725
+ assertions
726
+ };
727
+ }
728
+ function runRecordDir() {
729
+ const configured = process.env[RUN_RECORD_DIR_ENV]?.trim();
730
+ if (configured) return configured;
731
+ return join4(homedir2(), ".config", "opencode", "gate-runs");
732
+ }
733
+ function fileNameFor(sessionId) {
734
+ const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
735
+ return `${safe || "session"}.json`;
736
+ }
737
+ function writeRunRecord(input) {
738
+ const record = buildRunRecord(input);
739
+ const path = join4(runRecordDir(), fileNameFor(input.sessionId));
740
+ try {
741
+ mkdirSync2(runRecordDir(), { recursive: true });
742
+ writeFileSync(path, `${JSON.stringify(record, null, 2)}
743
+ `, "utf8");
744
+ } catch (err) {
745
+ logDiag(
746
+ `run record: could not write ${path}: ${err instanceof Error ? err.message : String(err)}`
747
+ );
748
+ return null;
749
+ }
750
+ logDiag(`run record: ${record.outcome} for ${input.sessionId} at ${path}`);
751
+ return { path, record };
752
+ }
753
+
698
754
  // src/gate.ts
699
755
  var MARKER = "[completion-gate]";
700
756
  var INTERNAL_MARKER = "[completion-gate-internal]";
@@ -988,6 +1044,7 @@ async function runGateTurnEnd(ctx, state) {
988
1044
  logDiag(
989
1045
  `gate turn-end on ${state.sessionID}: ${loaded ? `config ${loaded.path}` : "command-only without project config"} (${assertions.length} assertion(s), maxRetries=${cap.value} (${cap.source}), retries so far=${state.retries})`
990
1046
  );
1047
+ const startedAt = (/* @__PURE__ */ new Date()).toISOString();
991
1048
  const results = await evaluateAssertions(
992
1049
  assertions,
993
1050
  projectRoot,
@@ -1000,6 +1057,15 @@ async function runGateTurnEnd(ctx, state) {
1000
1057
  );
1001
1058
  return;
1002
1059
  }
1060
+ writeRunRecord({
1061
+ sessionId: state.sessionID,
1062
+ configPath: loaded?.path ?? null,
1063
+ projectRoot,
1064
+ startedAt,
1065
+ finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
1066
+ expectedAssertions: assertions.map((a) => a.name),
1067
+ results
1068
+ });
1003
1069
  const last = results[results.length - 1];
1004
1070
  if (!last) return;
1005
1071
  if (last.passed) {
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Structured evidence that a gate evaluation actually ran.
3
+ *
4
+ * The orchestrator (branch-sync `syncd`) refuses to call a hop green unless it
5
+ * can see what the gate evaluated. `gate-diag.log` is not usable for that: it is
6
+ * shared by every concurrent session, it records verdicts only, and it is a log
7
+ * rather than a contract. Every evaluation writes one JSON record instead:
8
+ *
9
+ * { "version": 1, "sessionId": "...", "configPath": "...", "platform": "linux",
10
+ * "startedAt": "...", "finishedAt": "...", "expected": 3, "evaluated": 3,
11
+ * "outcome": "passed", "assertions": [{ "name": "build", "passed": true }] }
12
+ *
13
+ * Two rules make the record trustworthy:
14
+ *
15
+ * - `outcome` is `passed` only when every EXPECTED assertion produced a passing
16
+ * result. Short-circuiting means the tail assertions never ran, and "verified 1
17
+ * of 3" must never read as a pass.
18
+ * - an evaluation that expected nothing is `failed`, because zero observations is
19
+ * not a pass.
20
+ *
21
+ * Writing is best effort: a record that cannot be written must not break the gate,
22
+ * so the failure is logged and the caller carries on.
23
+ */
24
+ import type { AssertionOutcome } from './types.js';
25
+ export declare const RUN_RECORD_DIR_ENV = "OPENCODE_GATE_RUN_DIR";
26
+ export interface RunRecordInput {
27
+ sessionId: string;
28
+ configPath: string | null;
29
+ projectRoot: string;
30
+ startedAt: string;
31
+ finishedAt: string;
32
+ expectedAssertions: string[];
33
+ results: AssertionOutcome[];
34
+ }
35
+ export interface RunRecordAssertion {
36
+ name: string;
37
+ passed: boolean;
38
+ evidence?: string;
39
+ }
40
+ export interface RunRecord {
41
+ version: 1;
42
+ sessionId: string;
43
+ configPath: string | null;
44
+ projectRoot: string;
45
+ platform: string;
46
+ startedAt: string;
47
+ finishedAt: string;
48
+ expected: number;
49
+ evaluated: number;
50
+ outcome: 'passed' | 'failed';
51
+ assertions: RunRecordAssertion[];
52
+ }
53
+ export declare function buildRunRecord(input: RunRecordInput): RunRecord;
54
+ export declare function runRecordDir(): string;
55
+ export declare function writeRunRecord(input: RunRecordInput): {
56
+ path: string;
57
+ record: RunRecord;
58
+ } | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-completion-gate",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "description": "OpenCode plugin: per-session quality gate that blocks declaring done until configured assertions pass",
5
5
  "type": "module",
6
6
  "main": "dist/plugin.js",