opencode-completion-gate 1.0.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 +18 -0
- package/LICENSE +21 -0
- package/README.md +56 -0
- package/dist/core.d.ts +212 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +697 -0
- package/dist/plugin.d.ts +11 -0
- package/dist/plugin.js +1061 -0
- package/package.json +81 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0 (2026-09-06)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* standard npm layout for opencode-completion-gate ([221f69c](https://github.com/PauloDevelo/opencode-completion-gate/commit/221f69c41a680fe6143a383252396e69ba27518e))
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
* create tmp opencode dir in test helper for fresh CI runners ([36be834](https://github.com/PauloDevelo/opencode-completion-gate/commit/36be834ed69becee4b2fa4690f695d32827ae877))
|
|
14
|
+
|
|
15
|
+
## 1.0.0
|
|
16
|
+
|
|
17
|
+
- Initial public release of `opencode-completion-gate`.
|
|
18
|
+
- Per-session quality gate (`/gate`) with `command`, `ado-pr`, and `opencode-review` assertions.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 OpenCode Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# opencode-completion-gate
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/opencode-completion-gate)
|
|
4
|
+
[](https://github.com/PauloDevelo/opencode-completion-gate/actions/workflows/ci.yml)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
|
|
7
|
+
Per-session quality gate that blocks an agent from declaring a task "done" until configured assertions pass (build green, unit tests green, PR policies green, LLM self-review…).
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install opencode-completion-gate
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Add the plugin to your OpenCode configuration:
|
|
16
|
+
|
|
17
|
+
**opencode.json:**
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"$schema": "https://opencode.ai/config.json",
|
|
22
|
+
"plugin": ["opencode-completion-gate"]
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Quick start
|
|
27
|
+
|
|
28
|
+
1. Instruct the agent: *"Fix X until completion."*
|
|
29
|
+
2. Type `/gate` (enables the gate for this session).
|
|
30
|
+
3. The agent works; each time it goes idle the gate runs your assertions.
|
|
31
|
+
4. All pass → `✅ Completion gate passed (...)` appears once and the agent may report done.
|
|
32
|
+
5. Something fails → the agent is re-prompted with the failure evidence and keeps fixing until it passes or hits the retry cap.
|
|
33
|
+
6. `/gate off` when you're done.
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
/gate # enable (same as /gate on)
|
|
37
|
+
/gate status # e.g. "[completion-gate] status: ENABLED · retries=1 · lastOutcome=fail"
|
|
38
|
+
/gate off # disable for this session
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Configuration
|
|
42
|
+
|
|
43
|
+
Config lives per project at `<project-root>/.opencode/completion-gate.json` (re-read on every gated turn end):
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"enabled": true,
|
|
48
|
+
"maxRetries": 3,
|
|
49
|
+
"assertions": [
|
|
50
|
+
{ "type": "command", "name": "build", "run": "dotnet build --nologo -v q", "timeoutSeconds": 300 },
|
|
51
|
+
{ "type": "command", "name": "unit-tests", "run": "dotnet test --no-build --nologo -v q", "timeoutSeconds": 600 }
|
|
52
|
+
]
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Assertion types: `command`, `ado-pr`, `opencode-review`. See [completion-gate-plugin.md](completion-gate-plugin.md) for the full schema, ADO PR polling, review sessions, diagnostics (`gate-diag.log`), and troubleshooting.
|
package/dist/core.d.ts
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
import type { Plugin } from '@opencode-ai/plugin';
|
|
2
|
+
import type { SpawnOptions } from 'child_process';
|
|
3
|
+
export interface CommandAssertion {
|
|
4
|
+
type: 'command';
|
|
5
|
+
name: string;
|
|
6
|
+
run: string;
|
|
7
|
+
timeoutSeconds: number;
|
|
8
|
+
}
|
|
9
|
+
export interface AdoPrAssertion {
|
|
10
|
+
type: 'ado-pr';
|
|
11
|
+
name: string;
|
|
12
|
+
pollTimeoutMinutes: number;
|
|
13
|
+
pollIntervalSeconds: number;
|
|
14
|
+
skipIfNoPr: boolean;
|
|
15
|
+
/** When true, blocking human-review policies (reviewer approvals, comment
|
|
16
|
+
* requirements) no longer hold the gate — only automated policies do. */
|
|
17
|
+
ignoreHumanPolicies?: boolean;
|
|
18
|
+
}
|
|
19
|
+
export interface ReviewAssertion {
|
|
20
|
+
type: 'opencode-review';
|
|
21
|
+
name: string;
|
|
22
|
+
agent: string;
|
|
23
|
+
prompt?: string;
|
|
24
|
+
timeoutSeconds: number;
|
|
25
|
+
}
|
|
26
|
+
export type GateAssertion = CommandAssertion | AdoPrAssertion | ReviewAssertion;
|
|
27
|
+
export interface GateConfig {
|
|
28
|
+
enabled: boolean;
|
|
29
|
+
maxRetries: number;
|
|
30
|
+
assertions: GateAssertion[];
|
|
31
|
+
}
|
|
32
|
+
export declare function truncateTail(text: string, maxLines?: number): string;
|
|
33
|
+
export declare function findGateConfigPath(startDir: string): string | null;
|
|
34
|
+
export declare function loadGateConfig(startDir: string): {
|
|
35
|
+
path: string;
|
|
36
|
+
projectRoot: string;
|
|
37
|
+
config: GateConfig;
|
|
38
|
+
} | null;
|
|
39
|
+
export interface ProcessOutcome {
|
|
40
|
+
code: number | null;
|
|
41
|
+
timedOut: boolean;
|
|
42
|
+
stdout: string;
|
|
43
|
+
stderr: string;
|
|
44
|
+
}
|
|
45
|
+
export declare function runCommand(cmd: string, cwd: string, timeoutMs: number): Promise<ProcessOutcome>;
|
|
46
|
+
export declare function execFileOut(file: string, args: string[], cwd: string, timeoutMs: number, spawnOpts?: SpawnOptions): Promise<ProcessOutcome>;
|
|
47
|
+
export interface AssertionOutcome {
|
|
48
|
+
name: string;
|
|
49
|
+
passed: boolean;
|
|
50
|
+
evidence: string;
|
|
51
|
+
}
|
|
52
|
+
export declare function runCommandAssertion(a: CommandAssertion, cwd: string, isAborted?: () => boolean): Promise<AssertionOutcome>;
|
|
53
|
+
export type PickPrResult = {
|
|
54
|
+
ok: true;
|
|
55
|
+
prId: number;
|
|
56
|
+
} | {
|
|
57
|
+
ok: false;
|
|
58
|
+
reason: 'none' | 'multiple' | 'unparsable';
|
|
59
|
+
detail: string;
|
|
60
|
+
};
|
|
61
|
+
export type PickPrDetailsResult = {
|
|
62
|
+
ok: true;
|
|
63
|
+
prId: number;
|
|
64
|
+
projectName?: string;
|
|
65
|
+
} | {
|
|
66
|
+
ok: false;
|
|
67
|
+
reason: 'none' | 'multiple' | 'unparsable';
|
|
68
|
+
detail: string;
|
|
69
|
+
};
|
|
70
|
+
export declare function pickActivePrDetails(prListJson: string): PickPrDetailsResult;
|
|
71
|
+
export declare function pickActivePr(prListJson: string): PickPrResult;
|
|
72
|
+
export interface PolicyEvaluationMinimal {
|
|
73
|
+
configuration?: {
|
|
74
|
+
isBlocking?: boolean;
|
|
75
|
+
isRequired?: boolean;
|
|
76
|
+
type?: {
|
|
77
|
+
displayName?: string;
|
|
78
|
+
};
|
|
79
|
+
};
|
|
80
|
+
status?: string;
|
|
81
|
+
context?: {
|
|
82
|
+
buildId?: number | string | null;
|
|
83
|
+
buildDefinitionName?: string;
|
|
84
|
+
buildOutputPreview?: {
|
|
85
|
+
jobName?: string;
|
|
86
|
+
taskName?: string;
|
|
87
|
+
errors?: Array<{
|
|
88
|
+
message?: string | null;
|
|
89
|
+
}>;
|
|
90
|
+
} | null;
|
|
91
|
+
} | null;
|
|
92
|
+
}
|
|
93
|
+
export declare function isHumanReviewPolicy(e: PolicyEvaluationMinimal): boolean;
|
|
94
|
+
export interface TerminalBuildFailure {
|
|
95
|
+
buildId: number | null;
|
|
96
|
+
status: string;
|
|
97
|
+
definitionName?: string;
|
|
98
|
+
jobName?: string;
|
|
99
|
+
taskName?: string;
|
|
100
|
+
previewErrors: string[];
|
|
101
|
+
}
|
|
102
|
+
export declare function extractTerminalBuildFailures(policyListJson: string, opts?: {
|
|
103
|
+
ignoreHumanPolicies?: boolean;
|
|
104
|
+
}): TerminalBuildFailure[];
|
|
105
|
+
export declare function requiredPoliciesGreen(policyListJson: string, opts?: {
|
|
106
|
+
ignoreHumanPolicies?: boolean;
|
|
107
|
+
}): {
|
|
108
|
+
green: boolean;
|
|
109
|
+
retryable: boolean;
|
|
110
|
+
detail: string;
|
|
111
|
+
};
|
|
112
|
+
export type ShellFn = (args: string[], cwd: string, timeoutMs: number) => Promise<string>;
|
|
113
|
+
/**
|
|
114
|
+
* Quote a single token for a cmd.exe command line (Windows only).
|
|
115
|
+
* Tokens containing whitespace, double quotes or cmd metacharacters are wrapped
|
|
116
|
+
* in double quotes with inner quotes doubled (cmd's "" convention).
|
|
117
|
+
*/
|
|
118
|
+
export declare function quoteWin(s: string): string;
|
|
119
|
+
export interface ShellInvocation {
|
|
120
|
+
file: string;
|
|
121
|
+
args: string[];
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Build the execFile invocation for a shell command.
|
|
125
|
+
* - win32: route through cmd.exe (/d /s /c) because `az` is az.cmd and git/npm
|
|
126
|
+
* shims are batch files that Node refuses to spawn without a shell
|
|
127
|
+
* (CVE-2024-27980 hardening). The caller must pass the result to execFileOut
|
|
128
|
+
* with windowsVerbatimArguments so our quoting reaches cmd untouched; /s makes
|
|
129
|
+
* cmd strip exactly the outer quotes we add around the joined command line.
|
|
130
|
+
* - other platforms: direct argv passthrough.
|
|
131
|
+
*/
|
|
132
|
+
export declare function buildShellInvocation(args: string[]): ShellInvocation;
|
|
133
|
+
/**
|
|
134
|
+
* Production ShellFn built on execFileOut; rejects with actionable stderr.
|
|
135
|
+
*
|
|
136
|
+
* CONSTRAINT: every element of `args` must be an operator-controlled token
|
|
137
|
+
* (fixed CLI flags, branch names, numeric PR ids, repo paths) — never raw,
|
|
138
|
+
* untrusted user input. On Windows the tokens are re-quoted onto a single
|
|
139
|
+
* cmd.exe command line, which is safe ONLY under that constraint.
|
|
140
|
+
*
|
|
141
|
+
* Tree-kill semantics: execFileOut's timeout kills the DIRECT child. On win32
|
|
142
|
+
* that child is cmd.exe — its /c grandchildren may linger past a timeout.
|
|
143
|
+
*/
|
|
144
|
+
export declare const execShell: ShellFn;
|
|
145
|
+
export interface BuildLogArtifact {
|
|
146
|
+
buildId: number;
|
|
147
|
+
archivePath?: string;
|
|
148
|
+
extractedPath?: string;
|
|
149
|
+
error?: string;
|
|
150
|
+
}
|
|
151
|
+
export type BuildLogExtractor = (archivePath: string, destination: string, cwd: string, timeoutMs: number) => Promise<void>;
|
|
152
|
+
export interface BuildLogDownloadOptions {
|
|
153
|
+
/** Parent directory for the per-download work dir; defaults to <tmpdir>/opencode. */
|
|
154
|
+
tempRoot?: string;
|
|
155
|
+
/** Timeout for both the az download and the extraction; defaults to 120s. */
|
|
156
|
+
timeoutMs?: number;
|
|
157
|
+
shell?: ShellFn;
|
|
158
|
+
extract?: BuildLogExtractor;
|
|
159
|
+
isAborted?: () => boolean;
|
|
160
|
+
}
|
|
161
|
+
export type BuildLogArtifactRunner = (projectName: string, buildId: number, cwd: string, isAborted?: () => boolean) => Promise<BuildLogArtifact>;
|
|
162
|
+
/**
|
|
163
|
+
* Download one build's complete log bundle via `az devops invoke` (Build Logs
|
|
164
|
+
* REST endpoint, application/zip) and extract it beside the archive.
|
|
165
|
+
*
|
|
166
|
+
* CONSTRAINT: projectName/buildId come from parsed Azure DevOps payloads and
|
|
167
|
+
* are passed as single operator-controlled tokens through the Windows shell
|
|
168
|
+
* adapter — same safety model as the rest of the ado-pr assertion.
|
|
169
|
+
*
|
|
170
|
+
* Best-effort by design: download/extraction failures return `{ error }` and
|
|
171
|
+
* never throw (except GateAborted), so the original CI failure evidence is
|
|
172
|
+
* always preserved by the caller.
|
|
173
|
+
*/
|
|
174
|
+
export declare function downloadBuildLogs(projectName: string, buildId: number, cwd: string, options?: BuildLogDownloadOptions): Promise<BuildLogArtifact>;
|
|
175
|
+
export declare const defaultBuildLogArtifact: BuildLogArtifactRunner;
|
|
176
|
+
export interface AdoPrPollOptions {
|
|
177
|
+
/** Waits between poll rounds; defaults to a real setTimeout. */
|
|
178
|
+
sleep?: (ms: number) => Promise<void>;
|
|
179
|
+
/** Clock used for the polling deadline baseline and checks; defaults to Date.now. */
|
|
180
|
+
now?: () => number;
|
|
181
|
+
/** Checked at each poll-round boundary; when it fires the assertion aborts. */
|
|
182
|
+
isAborted?: () => boolean;
|
|
183
|
+
/**
|
|
184
|
+
* Downloads + extracts failed Build logs on terminal Build-policy failures.
|
|
185
|
+
* Defaults to {@link defaultBuildLogArtifact} (az devops invoke + tar);
|
|
186
|
+
* tests inject fakes here.
|
|
187
|
+
*/
|
|
188
|
+
buildLogArtifact?: BuildLogArtifactRunner;
|
|
189
|
+
}
|
|
190
|
+
export declare function runAdoPrAssertion(a: AdoPrAssertion, cwd: string, shell: ShellFn, opts?: AdoPrPollOptions): Promise<AssertionOutcome>;
|
|
191
|
+
export declare function parseVerdict(output: string): 'PASS' | 'FAIL' | null;
|
|
192
|
+
export interface ReviewSessionClient {
|
|
193
|
+
session: {
|
|
194
|
+
create(options?: unknown): Promise<unknown>;
|
|
195
|
+
prompt(options: unknown): Promise<unknown>;
|
|
196
|
+
abort?(options: unknown): Promise<unknown>;
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* Runs the review assertion through an isolated reviewer SESSION on the same
|
|
201
|
+
* opencode server (via the plugin's SDK `client`) instead of spawning the
|
|
202
|
+
* `opencode` CLI — which cannot be started without a shell on win32 (npm
|
|
203
|
+
* installs .cmd/.ps1 shims that Node refuses to execute directly).
|
|
204
|
+
*
|
|
205
|
+
* NOTE: this reviewer session is top-level, so it lands in this gate instance's
|
|
206
|
+
* own sessions registry via session.created — but it stays gateEnabled=false,
|
|
207
|
+
* keeping the gate inert for it (review prompts can never trigger gating).
|
|
208
|
+
*/
|
|
209
|
+
export declare function runReviewAssertion(a: ReviewAssertion, cwd: string, client?: ReviewSessionClient, isAborted?: () => boolean): Promise<AssertionOutcome>;
|
|
210
|
+
export declare function evaluateAssertions(assertions: GateAssertion[], projectRoot: string, client?: ReviewSessionClient, isAborted?: () => boolean, adoOpts?: AdoPrPollOptions): Promise<AssertionOutcome[] | null>;
|
|
211
|
+
declare const plugin: Plugin;
|
|
212
|
+
export default plugin;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* opencode-completion-gate — programmatic utils entry (`./utils` subpath).
|
|
3
|
+
* The plugin entry (`src/plugin.ts`) stays default-export-only for OpenCode.
|
|
4
|
+
*/
|
|
5
|
+
export * from './core.js';
|
|
6
|
+
export declare const VERSION = "1.0.0";
|
|
7
|
+
export declare const pluginMeta: {
|
|
8
|
+
readonly name: "opencode-completion-gate";
|
|
9
|
+
readonly version: "1.0.0";
|
|
10
|
+
readonly description: "Per-session quality gate that blocks declaring done until configured assertions pass";
|
|
11
|
+
};
|