opencode-completion-gate 1.1.1 → 1.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
+ ## [1.2.0](https://github.com/PauloDevelo/opencode-completion-gate/compare/v1.1.1...v1.2.0) (2026-09-06)
4
+
5
+
6
+ ### Features
7
+
8
+ * add completion-gate command creator skill ([#6](https://github.com/PauloDevelo/opencode-completion-gate/issues/6)) ([843c9ec](https://github.com/PauloDevelo/opencode-completion-gate/commit/843c9ec80498bb233631ea241bee976e5573d7d9))
9
+
3
10
  ## [1.1.1](https://github.com/PauloDevelo/opencode-completion-gate/compare/v1.1.0...v1.1.1) (2026-09-06)
4
11
 
5
12
 
@@ -0,0 +1,34 @@
1
+ import type { AdoPrAssertion, AdoPrPollOptions, AssertionOutcome, BuildLogArtifact, BuildLogArtifactRunner, BuildLogDownloadOptions, PolicyEvaluationMinimal, ShellFn, TerminalBuildFailure } from './types.js';
2
+ export type PickPrResult = {
3
+ ok: true;
4
+ prId: number;
5
+ } | {
6
+ ok: false;
7
+ reason: 'none' | 'multiple' | 'unparsable';
8
+ detail: string;
9
+ };
10
+ export type PickPrDetailsResult = {
11
+ ok: true;
12
+ prId: number;
13
+ projectName?: string;
14
+ } | {
15
+ ok: false;
16
+ reason: 'none' | 'multiple' | 'unparsable';
17
+ detail: string;
18
+ };
19
+ export declare function pickActivePrDetails(prListJson: string): PickPrDetailsResult;
20
+ export declare function pickActivePr(prListJson: string): PickPrResult;
21
+ export declare function isHumanReviewPolicy(e: PolicyEvaluationMinimal): boolean;
22
+ export declare function extractTerminalBuildFailures(policyListJson: string, opts?: {
23
+ ignoreHumanPolicies?: boolean;
24
+ }): TerminalBuildFailure[];
25
+ export declare function requiredPoliciesGreen(policyListJson: string, opts?: {
26
+ ignoreHumanPolicies?: boolean;
27
+ }): {
28
+ green: boolean;
29
+ retryable: boolean;
30
+ detail: string;
31
+ };
32
+ export declare function downloadBuildLogs(projectName: string, buildId: number, cwd: string, options?: BuildLogDownloadOptions): Promise<BuildLogArtifact>;
33
+ export declare const defaultBuildLogArtifact: BuildLogArtifactRunner;
34
+ export declare function runAdoPrAssertion(a: AdoPrAssertion, cwd: string, shell: ShellFn, opts?: AdoPrPollOptions): Promise<AssertionOutcome>;
@@ -0,0 +1,35 @@
1
+ import type { AssertionOutcome, GateConfig } from './types.js';
2
+ export type GateMode = 'combined' | 'command-only';
3
+ export declare class GateAborted extends Error {
4
+ }
5
+ export declare function pass(name: string): AssertionOutcome;
6
+ export declare function fail(name: string, evidence: string): AssertionOutcome;
7
+ export declare function findGateConfigPath(startDir: string): string | null;
8
+ export declare function loadGateConfig(startDir: string): {
9
+ path: string;
10
+ projectRoot: string;
11
+ config: GateConfig;
12
+ } | null;
13
+ export declare function readBootstrapGateCommand(): {
14
+ command: string;
15
+ mode: GateMode;
16
+ maxRetries?: number;
17
+ } | null;
18
+ export declare function consumeBootstrapGateCommand(): void;
19
+ export declare function parseOnlyCommand(remainder: string): {
20
+ command: string;
21
+ maxRetries?: number;
22
+ invalidRetry: boolean;
23
+ };
24
+ export declare function effectiveMaxRetries(state: {
25
+ gateMode: GateMode;
26
+ sessionMaxRetries: number | null;
27
+ }, configMaxRetries: number): {
28
+ value: number;
29
+ source: 'session' | 'config';
30
+ };
31
+ export interface ValidatedSessionMetadata {
32
+ sessionID: string;
33
+ directory: string;
34
+ }
35
+ export declare function validateTopLevelSessionMetadata(info: unknown, expectedSessionID?: string): ValidatedSessionMetadata | null;
package/dist/core.d.ts CHANGED
@@ -1,246 +1,15 @@
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
- type GateMode = 'combined' | 'command-only';
54
- interface GateSessionState {
55
- sessionID: string;
56
- directory: string;
57
- gateEnabled: boolean;
58
- extraCommand?: string;
59
- gateMode: GateMode;
60
- /** Per-session retry cap for command-only mode (`/gate --only ... --retries N`).
61
- * Null/absent = fall back to the project config (or the default 3). */
62
- sessionMaxRetries: number | null;
63
- retries: number;
64
- lastOutcome: 'pass' | 'fail' | null;
65
- escalated: boolean;
66
- busy: boolean;
67
- deleted: boolean;
68
- }
69
1
  /**
70
- * Splits a `--only` remainder into the session command plus an optional
71
- * `--retries N` (alias `--max-retries N`) override. The flag is recognized
72
- * only as a leading or trailing token sequence so a command that merely
73
- * mentions `--retries` mid-line stays untouched; when both ends carry the
74
- * flag the leading value wins.
75
- */
76
- export declare function parseOnlyCommand(remainder: string): {
77
- command: string;
78
- maxRetries?: number;
79
- invalidRetry: boolean;
80
- };
81
- /** Effective retry cap for a session: session override wins in command-only
82
- * mode, otherwise the project config (or the default 3). */
83
- export declare function effectiveMaxRetries(state: Pick<GateSessionState, 'gateMode' | 'sessionMaxRetries'>, configMaxRetries: number): {
84
- value: number;
85
- source: 'session' | 'config';
86
- };
87
- export type PickPrResult = {
88
- ok: true;
89
- prId: number;
90
- } | {
91
- ok: false;
92
- reason: 'none' | 'multiple' | 'unparsable';
93
- detail: string;
94
- };
95
- export type PickPrDetailsResult = {
96
- ok: true;
97
- prId: number;
98
- projectName?: string;
99
- } | {
100
- ok: false;
101
- reason: 'none' | 'multiple' | 'unparsable';
102
- detail: string;
103
- };
104
- export declare function pickActivePrDetails(prListJson: string): PickPrDetailsResult;
105
- export declare function pickActivePr(prListJson: string): PickPrResult;
106
- export interface PolicyEvaluationMinimal {
107
- configuration?: {
108
- isBlocking?: boolean;
109
- isRequired?: boolean;
110
- type?: {
111
- displayName?: string;
112
- };
113
- };
114
- status?: string;
115
- context?: {
116
- buildId?: number | string | null;
117
- buildDefinitionName?: string;
118
- buildOutputPreview?: {
119
- jobName?: string;
120
- taskName?: string;
121
- errors?: Array<{
122
- message?: string | null;
123
- }>;
124
- } | null;
125
- } | null;
126
- }
127
- export declare function isHumanReviewPolicy(e: PolicyEvaluationMinimal): boolean;
128
- export interface TerminalBuildFailure {
129
- buildId: number | null;
130
- status: string;
131
- definitionName?: string;
132
- jobName?: string;
133
- taskName?: string;
134
- previewErrors: string[];
135
- }
136
- export declare function extractTerminalBuildFailures(policyListJson: string, opts?: {
137
- ignoreHumanPolicies?: boolean;
138
- }): TerminalBuildFailure[];
139
- export declare function requiredPoliciesGreen(policyListJson: string, opts?: {
140
- ignoreHumanPolicies?: boolean;
141
- }): {
142
- green: boolean;
143
- retryable: boolean;
144
- detail: string;
145
- };
146
- export type ShellFn = (args: string[], cwd: string, timeoutMs: number) => Promise<string>;
147
- /**
148
- * Quote a single token for a cmd.exe command line (Windows only).
149
- * Tokens containing whitespace, double quotes or cmd metacharacters are wrapped
150
- * in double quotes with inner quotes doubled (cmd's "" convention).
151
- */
152
- export declare function quoteWin(s: string): string;
153
- export interface ShellInvocation {
154
- file: string;
155
- args: string[];
156
- }
157
- /**
158
- * Build the execFile invocation for a shell command.
159
- * - win32: route through cmd.exe (/d /s /c) because `az` is az.cmd and git/npm
160
- * shims are batch files that Node refuses to spawn without a shell
161
- * (CVE-2024-27980 hardening). The caller must pass the result to execFileOut
162
- * with windowsVerbatimArguments so our quoting reaches cmd untouched; /s makes
163
- * cmd strip exactly the outer quotes we add around the joined command line.
164
- * - other platforms: direct argv passthrough.
165
- */
166
- export declare function buildShellInvocation(args: string[]): ShellInvocation;
167
- /**
168
- * Production ShellFn built on execFileOut; rejects with actionable stderr.
169
- *
170
- * CONSTRAINT: every element of `args` must be an operator-controlled token
171
- * (fixed CLI flags, branch names, numeric PR ids, repo paths) — never raw,
172
- * untrusted user input. On Windows the tokens are re-quoted onto a single
173
- * cmd.exe command line, which is safe ONLY under that constraint.
174
- *
175
- * Tree-kill semantics: execFileOut's timeout kills the DIRECT child. On win32
176
- * that child is cmd.exe — its /c grandchildren may linger past a timeout.
177
- */
178
- export declare const execShell: ShellFn;
179
- export interface BuildLogArtifact {
180
- buildId: number;
181
- archivePath?: string;
182
- extractedPath?: string;
183
- error?: string;
184
- }
185
- export type BuildLogExtractor = (archivePath: string, destination: string, cwd: string, timeoutMs: number) => Promise<void>;
186
- export interface BuildLogDownloadOptions {
187
- /** Parent directory for the per-download work dir; defaults to <tmpdir>/opencode. */
188
- tempRoot?: string;
189
- /** Timeout for both the az download and the extraction; defaults to 120s. */
190
- timeoutMs?: number;
191
- shell?: ShellFn;
192
- extract?: BuildLogExtractor;
193
- isAborted?: () => boolean;
194
- }
195
- export type BuildLogArtifactRunner = (projectName: string, buildId: number, cwd: string, isAborted?: () => boolean) => Promise<BuildLogArtifact>;
196
- /**
197
- * Download one build's complete log bundle via `az devops invoke` (Build Logs
198
- * REST endpoint, application/zip) and extract it beside the archive.
199
- *
200
- * CONSTRAINT: projectName/buildId come from parsed Azure DevOps payloads and
201
- * are passed as single operator-controlled tokens through the Windows shell
202
- * adapter — same safety model as the rest of the ado-pr assertion.
203
- *
204
- * Best-effort by design: download/extraction failures return `{ error }` and
205
- * never throw (except GateAborted), so the original CI failure evidence is
206
- * always preserved by the caller.
207
- */
208
- export declare function downloadBuildLogs(projectName: string, buildId: number, cwd: string, options?: BuildLogDownloadOptions): Promise<BuildLogArtifact>;
209
- export declare const defaultBuildLogArtifact: BuildLogArtifactRunner;
210
- export interface AdoPrPollOptions {
211
- /** Waits between poll rounds; defaults to a real setTimeout. */
212
- sleep?: (ms: number) => Promise<void>;
213
- /** Clock used for the polling deadline baseline and checks; defaults to Date.now. */
214
- now?: () => number;
215
- /** Checked at each poll-round boundary; when it fires the assertion aborts. */
216
- isAborted?: () => boolean;
217
- /**
218
- * Downloads + extracts failed Build logs on terminal Build-policy failures.
219
- * Defaults to {@link defaultBuildLogArtifact} (az devops invoke + tar);
220
- * tests inject fakes here.
221
- */
222
- buildLogArtifact?: BuildLogArtifactRunner;
223
- }
224
- export declare function runAdoPrAssertion(a: AdoPrAssertion, cwd: string, shell: ShellFn, opts?: AdoPrPollOptions): Promise<AssertionOutcome>;
225
- export declare function parseVerdict(output: string): 'PASS' | 'FAIL' | null;
226
- export interface ReviewSessionClient {
227
- session: {
228
- create(options?: unknown): Promise<unknown>;
229
- prompt(options: unknown): Promise<unknown>;
230
- abort?(options: unknown): Promise<unknown>;
231
- };
232
- }
233
- /**
234
- * Runs the review assertion through an isolated reviewer SESSION on the same
235
- * opencode server (via the plugin's SDK `client`) instead of spawning the
236
- * `opencode` CLI — which cannot be started without a shell on win32 (npm
237
- * installs .cmd/.ps1 shims that Node refuses to execute directly).
2
+ * Compatibility facade for the programmatic utilities entry point.
238
3
  *
239
- * NOTE: this reviewer session is top-level, so it lands in this gate instance's
240
- * own sessions registry via session.created — but it stays gateEnabled=false,
241
- * keeping the gate inert for it (review prompts can never trigger gating).
4
+ * The plugin implementation lives in ./gate. Keep this module's public API
5
+ * stable for existing imports from the package's ./utils subpath.
242
6
  */
243
- export declare function runReviewAssertion(a: ReviewAssertion, cwd: string, client?: ReviewSessionClient, isAborted?: () => boolean): Promise<AssertionOutcome>;
244
- export declare function evaluateAssertions(assertions: GateAssertion[], projectRoot: string, client?: ReviewSessionClient, isAborted?: () => boolean, adoOpts?: AdoPrPollOptions): Promise<AssertionOutcome[] | null>;
245
- declare const plugin: Plugin;
246
- export default plugin;
7
+ export { default } from './gate.js';
8
+ export { evaluateAssertions, runCommandAssertion } from './gate.js';
9
+ export { buildShellInvocation, execFileOut, execShell, quoteWin, runCommand, truncateTail, } from './process.js';
10
+ export { findGateConfigPath, loadGateConfig, parseOnlyCommand, effectiveMaxRetries, } from './config.js';
11
+ export { defaultBuildLogArtifact, downloadBuildLogs, extractTerminalBuildFailures, isHumanReviewPolicy, pickActivePr, pickActivePrDetails, requiredPoliciesGreen, runAdoPrAssertion, } from './ado-pr.js';
12
+ export { parseVerdict, runReviewAssertion } from './review.js';
13
+ export type { AdoPrAssertion, AdoPrPollOptions, AssertionOutcome, BuildLogArtifact, BuildLogArtifactRunner, BuildLogDownloadOptions, BuildLogExtractor, CommandAssertion, GateAssertion, GateConfig, PolicyEvaluationMinimal, ProcessOutcome, ReviewAssertion, ReviewSessionClient, ShellFn, ShellInvocation, TerminalBuildFailure, } from './types.js';
14
+ export type { PickPrDetailsResult, PickPrResult } from './ado-pr.js';
15
+ export type { GateMode } from './config.js';
package/dist/gate.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ import type { Plugin } from '@opencode-ai/plugin';
2
+ import type { AdoPrPollOptions, AssertionOutcome, CommandAssertion, GateAssertion, ReviewSessionClient } from './types.js';
3
+ export declare function runCommandAssertion(a: CommandAssertion, cwd: string, isAborted?: () => boolean): Promise<AssertionOutcome>;
4
+ export declare function evaluateAssertions(assertions: GateAssertion[], projectRoot: string, client?: ReviewSessionClient, isAborted?: () => boolean, adoOpts?: AdoPrPollOptions): Promise<AssertionOutcome[] | null>;
5
+ declare const plugin: Plugin;
6
+ export default plugin;