opencode-completion-gate 2.0.1 → 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,19 @@
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
+
10
+ ## [2.1.0](https://github.com/PauloDevelo/opencode-completion-gate/compare/v2.0.1...v2.1.0) (2026-11-19)
11
+
12
+
13
+ ### Features
14
+
15
+ * **config:** accept one command per platform for run ([#16](https://github.com/PauloDevelo/opencode-completion-gate/issues/16)) ([17299e9](https://github.com/PauloDevelo/opencode-completion-gate/commit/17299e9984b9c75beb387eea182aff05c842e240))
16
+
3
17
  ## [2.0.1](https://github.com/PauloDevelo/opencode-completion-gate/compare/v2.0.0...v2.0.1) (2026-11-18)
4
18
 
5
19
 
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
@@ -123,6 +123,29 @@ function fail(name, evidence) {
123
123
  function positiveInt(v, fallback) {
124
124
  return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
125
125
  }
126
+ function resolvePlatformCommand(run, nameOf) {
127
+ if (typeof run === "string") {
128
+ const command2 = run.trim();
129
+ if (!command2) return null;
130
+ return { run, name: nameOf(command2.split(/\s+/)[0]) };
131
+ }
132
+ if (!run || typeof run !== "object" || Array.isArray(run)) return null;
133
+ const pair = run;
134
+ const unknownKeys = Object.keys(pair).filter((key) => key !== "windows" && key !== "linux");
135
+ if (unknownKeys.length > 0) {
136
+ logDiag(`gate config: run carries unknown platform key(s): ${unknownKeys.join(", ")}`);
137
+ return null;
138
+ }
139
+ const platform = process.platform === "win32" ? "windows" : "linux";
140
+ const command = pair[platform];
141
+ if (typeof command !== "string" || !command.trim()) {
142
+ logDiag(
143
+ `gate config: run has no "${platform}" command for this host (${process.platform}); the whole config is skipped`
144
+ );
145
+ return null;
146
+ }
147
+ return { run: command, name: nameOf(command.trim().split(/\s+/)[0]) };
148
+ }
126
149
  function validateGateConfig(raw) {
127
150
  if (!raw || typeof raw !== "object") return null;
128
151
  const obj = raw;
@@ -133,15 +156,17 @@ function validateGateConfig(raw) {
133
156
  if (!a || typeof a !== "object") return null;
134
157
  const nameOf = (fb) => typeof a.name === "string" && a.name.trim() ? a.name : fb;
135
158
  switch (a.type) {
136
- case "command":
137
- if (typeof a.run !== "string" || !a.run.trim()) return null;
159
+ case "command": {
160
+ const resolved = resolvePlatformCommand(a.run, nameOf);
161
+ if (!resolved) return null;
138
162
  assertions.push({
139
163
  type: "command",
140
- name: nameOf(a.run.split(/\s+/)[0]),
141
- run: a.run,
164
+ name: resolved.name,
165
+ run: resolved.run,
142
166
  timeoutSeconds: positiveInt(a.timeoutSeconds, 300)
143
167
  });
144
168
  break;
169
+ }
145
170
  case "ado-pr":
146
171
  assertions.push({
147
172
  type: "ado-pr",
@@ -674,6 +699,62 @@ ${evidence}`);
674
699
  }
675
700
  }
676
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
+
677
758
  // src/gate.ts
678
759
  var MARKER = "[completion-gate]";
679
760
  var INTERNAL_MARKER = "[completion-gate-internal]";
@@ -967,6 +1048,7 @@ async function runGateTurnEnd(ctx, state) {
967
1048
  logDiag(
968
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})`
969
1050
  );
1051
+ const startedAt = (/* @__PURE__ */ new Date()).toISOString();
970
1052
  const results = await evaluateAssertions(
971
1053
  assertions,
972
1054
  projectRoot,
@@ -979,6 +1061,15 @@ async function runGateTurnEnd(ctx, state) {
979
1061
  );
980
1062
  return;
981
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
+ });
982
1073
  const last = results[results.length - 1];
983
1074
  if (!last) return;
984
1075
  if (last.passed) {
@@ -1212,7 +1303,9 @@ var pluginMeta = {
1212
1303
  description: "Per-session quality gate that blocks declaring done until configured assertions pass"
1213
1304
  };
1214
1305
  export {
1306
+ RUN_RECORD_DIR_ENV,
1215
1307
  VERSION,
1308
+ buildRunRecord,
1216
1309
  buildShellInvocation,
1217
1310
  defaultBuildLogArtifact,
1218
1311
  downloadBuildLogs,
@@ -1234,6 +1327,8 @@ export {
1234
1327
  runAdoPrAssertion,
1235
1328
  runCommand,
1236
1329
  runCommandAssertion,
1330
+ runRecordDir,
1237
1331
  runReviewAssertion,
1238
- truncateTail
1332
+ truncateTail,
1333
+ writeRunRecord
1239
1334
  };
package/dist/plugin.js CHANGED
@@ -123,6 +123,29 @@ function fail(name, evidence) {
123
123
  function positiveInt(v, fallback) {
124
124
  return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
125
125
  }
126
+ function resolvePlatformCommand(run, nameOf) {
127
+ if (typeof run === "string") {
128
+ const command2 = run.trim();
129
+ if (!command2) return null;
130
+ return { run, name: nameOf(command2.split(/\s+/)[0]) };
131
+ }
132
+ if (!run || typeof run !== "object" || Array.isArray(run)) return null;
133
+ const pair = run;
134
+ const unknownKeys = Object.keys(pair).filter((key) => key !== "windows" && key !== "linux");
135
+ if (unknownKeys.length > 0) {
136
+ logDiag(`gate config: run carries unknown platform key(s): ${unknownKeys.join(", ")}`);
137
+ return null;
138
+ }
139
+ const platform = process.platform === "win32" ? "windows" : "linux";
140
+ const command = pair[platform];
141
+ if (typeof command !== "string" || !command.trim()) {
142
+ logDiag(
143
+ `gate config: run has no "${platform}" command for this host (${process.platform}); the whole config is skipped`
144
+ );
145
+ return null;
146
+ }
147
+ return { run: command, name: nameOf(command.trim().split(/\s+/)[0]) };
148
+ }
126
149
  function validateGateConfig(raw) {
127
150
  if (!raw || typeof raw !== "object") return null;
128
151
  const obj = raw;
@@ -133,15 +156,17 @@ function validateGateConfig(raw) {
133
156
  if (!a || typeof a !== "object") return null;
134
157
  const nameOf = (fb) => typeof a.name === "string" && a.name.trim() ? a.name : fb;
135
158
  switch (a.type) {
136
- case "command":
137
- if (typeof a.run !== "string" || !a.run.trim()) return null;
159
+ case "command": {
160
+ const resolved = resolvePlatformCommand(a.run, nameOf);
161
+ if (!resolved) return null;
138
162
  assertions.push({
139
163
  type: "command",
140
- name: nameOf(a.run.split(/\s+/)[0]),
141
- run: a.run,
164
+ name: resolved.name,
165
+ run: resolved.run,
142
166
  timeoutSeconds: positiveInt(a.timeoutSeconds, 300)
143
167
  });
144
168
  break;
169
+ }
145
170
  case "ado-pr":
146
171
  assertions.push({
147
172
  type: "ado-pr",
@@ -670,6 +695,62 @@ ${evidence}`);
670
695
  }
671
696
  }
672
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
+
673
754
  // src/gate.ts
674
755
  var MARKER = "[completion-gate]";
675
756
  var INTERNAL_MARKER = "[completion-gate-internal]";
@@ -963,6 +1044,7 @@ async function runGateTurnEnd(ctx, state) {
963
1044
  logDiag(
964
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})`
965
1046
  );
1047
+ const startedAt = (/* @__PURE__ */ new Date()).toISOString();
966
1048
  const results = await evaluateAssertions(
967
1049
  assertions,
968
1050
  projectRoot,
@@ -975,6 +1057,15 @@ async function runGateTurnEnd(ctx, state) {
975
1057
  );
976
1058
  return;
977
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
+ });
978
1069
  const last = results[results.length - 1];
979
1070
  if (!last) return;
980
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/dist/types.d.ts CHANGED
@@ -4,6 +4,20 @@ export interface CommandAssertion {
4
4
  run: string;
5
5
  timeoutSeconds: number;
6
6
  }
7
+ /**
8
+ * The `run` field of a command assertion may be a single string (the original
9
+ * shape, still valid) or one command per platform. The config layer resolves it
10
+ * to a single string before anything reaches the runner, so `CommandAssertion.run`
11
+ * stays a string at runtime.
12
+ *
13
+ * Both keys are optional so the JSON can be authored incrementally, but a config
14
+ * that does not carry a command for the platform it is being read on is
15
+ * rejected rather than run against the other platform's shell.
16
+ */
17
+ export interface PlatformCommand {
18
+ windows?: string;
19
+ linux?: string;
20
+ }
7
21
  export interface AdoPrAssertion {
8
22
  type: 'ado-pr';
9
23
  name: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-completion-gate",
3
- "version": "2.0.1",
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",