@vaultcompass/conductor 0.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.
@@ -0,0 +1,54 @@
1
+ export interface BaseResolution {
2
+ ref: string;
3
+ /** Which input named it, so the report can say. */
4
+ source: 'flag' | 'github';
5
+ }
6
+ export type ChangedPaths = {
7
+ ok: true;
8
+ paths: string[];
9
+ } | {
10
+ ok: false;
11
+ detail: string;
12
+ };
13
+ /**
14
+ * The ref to diff against, or null for a run that is not a pull request.
15
+ *
16
+ * `GITHUB_BASE_REF` is a BRANCH NAME, not a ref anything local can resolve:
17
+ * a CI checkout has no local branch for it, so it is prefixed with `origin/`.
18
+ * Actions defines the variable and leaves it EMPTY outside a pull request, so
19
+ * an empty value has to mean "no pull request" rather than "origin/", which
20
+ * would fail every push build closed.
21
+ */
22
+ export declare function resolveBaseRef(options: {
23
+ base?: string;
24
+ env: NodeJS.ProcessEnv;
25
+ }): BaseResolution | null;
26
+ /**
27
+ * The branch this run is about.
28
+ *
29
+ * `GITHUB_HEAD_REF` first, and it is not an optimization: `actions/checkout`
30
+ * leaves a pull request build on a DETACHED HEAD, so asking git for the
31
+ * branch name there answers "HEAD" and matches no spec at all. Outside CI the
32
+ * variable is absent and git is the only answer.
33
+ */
34
+ export declare function currentBranch(repoRoot: string, env: NodeJS.ProcessEnv): string | null;
35
+ /**
36
+ * The paths the branch changed since it forked from `base`.
37
+ *
38
+ * Three flags, each of which is a decision:
39
+ *
40
+ * - `-c core.quotePath=false`, or git escapes any byte outside ASCII and
41
+ * wraps the line in quotes, and the gate is handed a path that matches no
42
+ * glob and no file on disk.
43
+ * - `--no-renames`, so a rename lists BOTH its old and its new path. Moving
44
+ * a file out of a protected directory still has to block, which it cannot
45
+ * if only the destination is listed. The cost is that a rename counts as
46
+ * two paths against a max_files budget, which is the same cost
47
+ * intent-guard's own `--base` pays.
48
+ * - the three-dot range, which asks what the branch changed since it forked
49
+ * rather than how it differs from the base branch right now.
50
+ *
51
+ * Fails closed. There is deliberately no fallback to an empty path set on a
52
+ * git error, because an empty path set is indistinguishable from a clean run.
53
+ */
54
+ export declare function changedPathsSince(repoRoot: string, base: string): ChangedPaths;
@@ -0,0 +1,135 @@
1
+ // What the branch changed, and what to measure it against.
2
+ //
3
+ // The intent gate's pre-commit view is the index. Its pull-request view is
4
+ // the set of paths the branch changed since it forked, which is a different
5
+ // question with a different answer, and getting it wrong is not a small
6
+ // error: a two-dot diff attributes every commit that landed on the base
7
+ // branch after this branch forked to this branch, so somebody else's merge
8
+ // breaches this pull request's change budget.
9
+ //
10
+ // The umbrella computes the path set ITSELF rather than handing intent-guard
11
+ // its own `--base`, and that is a deliberate cost. The contract for a run may
12
+ // live in a temporary directory (see intent-prepare.ts), and `--base` inside
13
+ // the gate resolves git relative to `--project`, where there is no
14
+ // repository. Computing the set here and passing `--paths` is the one
15
+ // arrangement that works for both the native and the imported contract, and
16
+ // the flags below are copied from intent-guard 1.2.1 so the two agree on what
17
+ // "changed" means rather than agreeing by coincidence.
18
+ import { spawnSync } from 'node:child_process';
19
+ /**
20
+ * The ref to diff against, or null for a run that is not a pull request.
21
+ *
22
+ * `GITHUB_BASE_REF` is a BRANCH NAME, not a ref anything local can resolve:
23
+ * a CI checkout has no local branch for it, so it is prefixed with `origin/`.
24
+ * Actions defines the variable and leaves it EMPTY outside a pull request, so
25
+ * an empty value has to mean "no pull request" rather than "origin/", which
26
+ * would fail every push build closed.
27
+ */
28
+ export function resolveBaseRef(options) {
29
+ if (options.base !== undefined && options.base !== '') {
30
+ return { ref: options.base, source: 'flag' };
31
+ }
32
+ const fromGithub = options.env.GITHUB_BASE_REF;
33
+ if (fromGithub !== undefined && fromGithub !== '') {
34
+ return { ref: `origin/${fromGithub}`, source: 'github' };
35
+ }
36
+ return null;
37
+ }
38
+ /**
39
+ * The branch this run is about.
40
+ *
41
+ * `GITHUB_HEAD_REF` first, and it is not an optimization: `actions/checkout`
42
+ * leaves a pull request build on a DETACHED HEAD, so asking git for the
43
+ * branch name there answers "HEAD" and matches no spec at all. Outside CI the
44
+ * variable is absent and git is the only answer.
45
+ */
46
+ export function currentBranch(repoRoot, env) {
47
+ const fromGithub = env.GITHUB_HEAD_REF;
48
+ if (fromGithub !== undefined && fromGithub !== '') {
49
+ return fromGithub;
50
+ }
51
+ const child = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
52
+ cwd: repoRoot,
53
+ encoding: 'utf8',
54
+ });
55
+ const value = (child.stdout ?? '').trim();
56
+ if (child.status !== 0 || value === '' || value === 'HEAD') {
57
+ return null;
58
+ }
59
+ return value;
60
+ }
61
+ /**
62
+ * The paths the branch changed since it forked from `base`.
63
+ *
64
+ * Three flags, each of which is a decision:
65
+ *
66
+ * - `-c core.quotePath=false`, or git escapes any byte outside ASCII and
67
+ * wraps the line in quotes, and the gate is handed a path that matches no
68
+ * glob and no file on disk.
69
+ * - `--no-renames`, so a rename lists BOTH its old and its new path. Moving
70
+ * a file out of a protected directory still has to block, which it cannot
71
+ * if only the destination is listed. The cost is that a rename counts as
72
+ * two paths against a max_files budget, which is the same cost
73
+ * intent-guard's own `--base` pays.
74
+ * - the three-dot range, which asks what the branch changed since it forked
75
+ * rather than how it differs from the base branch right now.
76
+ *
77
+ * Fails closed. There is deliberately no fallback to an empty path set on a
78
+ * git error, because an empty path set is indistinguishable from a clean run.
79
+ */
80
+ export function changedPathsSince(repoRoot, base) {
81
+ const child = spawnSync('git', [
82
+ '-c',
83
+ 'core.quotePath=false',
84
+ 'diff',
85
+ '--name-only',
86
+ '--no-renames',
87
+ `${base}...HEAD`,
88
+ ], { cwd: repoRoot, encoding: 'utf8' });
89
+ if (child.error !== undefined) {
90
+ return { ok: false, detail: `git could not be run: ${child.error.message}` };
91
+ }
92
+ if (child.status !== 0) {
93
+ // git's own first line usually ends in a full stop, and this message
94
+ // continues after it. Two in a row reads as a typo in a message somebody
95
+ // is already reading because something went wrong.
96
+ const stderr = ((child.stderr ?? '').trim().split('\n')[0] ?? '').replace(/\.+$/, '');
97
+ return {
98
+ ok: false,
99
+ detail: `git could not resolve "${base}...HEAD" (exit ${child.status ?? -1})` +
100
+ `${stderr === '' ? '' : `: ${stderr}`}. ` +
101
+ 'In Actions this is usually a shallow checkout with no merge base; ' +
102
+ 'check out with fetch-depth: 0, or fetch the base ref before the run.',
103
+ };
104
+ }
105
+ // Split on newlines and NOTHING else. Trimming each line was corrupting a
106
+ // filename with leading or trailing whitespace into a different filename,
107
+ // which is worse than refusing it: the gate would then check a path that
108
+ // does not exist and never check the one that changed.
109
+ const paths = (child.stdout ?? '').split('\n').filter((line) => line.length > 0);
110
+ for (const entry of paths) {
111
+ // Fail closed rather than hand over a path the encoding cannot carry.
112
+ // `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
113
+ // accepts, so a comma in a filename arrives as two paths: a phantom that
114
+ // can be reported as outside allowed_paths, and a real path that quietly
115
+ // stops being measured against a protected one. It invents a breach and
116
+ // hides one, and neither half is visible in the report.
117
+ if (entry.includes(',')) {
118
+ return {
119
+ ok: false,
120
+ detail: `the changed path "${entry}" contains a comma, and the intent gate takes its ` +
121
+ 'path list comma-joined, so it cannot be passed without splitting into two paths. ' +
122
+ 'Nothing was checked, rather than checking a path that does not exist.',
123
+ };
124
+ }
125
+ if (entry !== entry.trim()) {
126
+ return {
127
+ ok: false,
128
+ detail: `the changed path "${entry}" has leading or trailing whitespace, which cannot ` +
129
+ 'survive the gate path list intact. Nothing was checked, rather than checking a ' +
130
+ 'path that does not exist. A space inside a path is fine.',
131
+ };
132
+ }
133
+ }
134
+ return { ok: true, paths };
135
+ }
@@ -0,0 +1,57 @@
1
+ import type { ResolvedBinary } from './resolve.js';
2
+ /** Prefix of the per-run directory, exported so a test can count leaks. */
3
+ export declare const TEMP_PREFIX = "conductor-intent-";
4
+ export declare const NATIVE_CONTRACT_PATH = ".conductor/intent-contract.yaml";
5
+ export type ContractSource =
6
+ /** The repository's own frozen contract, used untouched. */
7
+ {
8
+ kind: 'native';
9
+ path: string;
10
+ }
11
+ /** A spec imported and frozen for this run only. Repository-relative paths. */
12
+ | {
13
+ kind: 'imported';
14
+ spec: string;
15
+ plan: string | null;
16
+ } | {
17
+ kind: 'none';
18
+ };
19
+ export interface IntentPreparation {
20
+ contractSource: ContractSource;
21
+ /** The ref the change set was measured against, or null for a staged run. */
22
+ baseRef: string | null;
23
+ /** Whether that ref was asked for or inferred from the CI environment. */
24
+ baseSource: 'flag' | 'github' | null;
25
+ /** What to hand the gate as --project: "." or an absolute temporary path. */
26
+ projectDir: string;
27
+ /** The changed paths, or null to leave v0.1's staged behaviour alone. */
28
+ paths: string[] | null;
29
+ /** Removes anything written outside the repository. Safe to call twice. */
30
+ cleanup: () => void;
31
+ }
32
+ /** Which link of the chain broke. Carried into the report verbatim. */
33
+ export type PrepareStep = 'spec' | 'base' | 'import-spec' | 'write-contract' | 'freeze';
34
+ export type IntentPrepareResult = {
35
+ kind: 'ready';
36
+ preparation: IntentPreparation;
37
+ }
38
+ /** No contract and no spec: an advisory, never an exit code. */
39
+ | {
40
+ kind: 'skip';
41
+ reason: 'no-contract';
42
+ detail: string;
43
+ } | {
44
+ kind: 'failed';
45
+ step: PrepareStep;
46
+ detail: string;
47
+ };
48
+ export interface IntentPrepareOptions {
49
+ repoRoot: string;
50
+ /** The resolved intent-guard binary, or null when none is installed. */
51
+ binary: ResolvedBinary | null;
52
+ env: NodeJS.ProcessEnv;
53
+ base?: string;
54
+ spec?: string;
55
+ timeoutMs?: number;
56
+ }
57
+ export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
@@ -0,0 +1,297 @@
1
+ // Giving the intent gate a frozen contract for one run, without writing one
2
+ // into the repository.
3
+ //
4
+ // The gate refuses to check anything against a contract nobody approved, and
5
+ // approving one is a per-task human step. That step is the ceremony the
6
+ // stopping-points design exists to keep out of a pull request, so this file
7
+ // stands in for it: it takes the document the work was actually approved
8
+ // from, hands it to intent-guard's own importer, freezes the draft in a
9
+ // TEMPORARY directory, and points the gate at that directory for the length
10
+ // of one run.
11
+ //
12
+ // Two rules keep that from being a lie:
13
+ //
14
+ // - NOTHING IS EVER WRITTEN UNDER <repo>/.conductor. A contract is a
15
+ // committed artifact with an approver's name on it. A pull-request run
16
+ // that dropped one into the working tree would either be committed by
17
+ // accident or picked up by the next run as though a person had approved
18
+ // it, and the second failure is silent.
19
+ //
20
+ // - THE REPOSITORY'S OWN FROZEN CONTRACT ALWAYS WINS. Where a team has done
21
+ // the native flow, the native flow is what runs; the import is the
22
+ // fallback for a repository that has not, not a replacement for one that
23
+ // has. "Exists" is not the test, though: an unfrozen contract is a draft
24
+ // somebody left behind, and running the gate against it fails every pull
25
+ // request on "not frozen by user" without checking anything.
26
+ //
27
+ // Every step can fail, and every failure NAMES ITS STEP. The gate is
28
+ // could-not-run for the whole run either way, so the only thing that
29
+ // distinguishes a shallow checkout from a spec the importer choked on is the
30
+ // sentence in the report.
31
+ import { spawnSync } from 'node:child_process';
32
+ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
33
+ import os from 'node:os';
34
+ import path from 'node:path';
35
+ import { parse as parseYaml } from 'yaml';
36
+ import { changedPathsSince, currentBranch, resolveBaseRef } from './intent-base.js';
37
+ import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
38
+ /** Prefix of the per-run directory, exported so a test can count leaks. */
39
+ export const TEMP_PREFIX = 'conductor-intent-';
40
+ export const NATIVE_CONTRACT_PATH = '.conductor/intent-contract.yaml';
41
+ /**
42
+ * Whether a contract on disk has been approved.
43
+ *
44
+ * `frozen_by: user` and nothing else, because that is the marker THE GATE
45
+ * ITSELF reads. Accepting an `approval` block as an alternative was a guess
46
+ * dressed up as tolerance: a real 1.2.1 freeze writes both, so the only
47
+ * contracts the second test admitted were hand-edited or half-written ones,
48
+ * and admitting those skipped the import and then let the gate block every
49
+ * pull request with "exists but is not frozen by user" -- the exact failure
50
+ * this function exists to prevent.
51
+ *
52
+ * A file that cannot be parsed is treated as not frozen, which sends the run
53
+ * down the import path rather than handing the gate something it will reject.
54
+ */
55
+ function nativeContractIsFrozen(repoRoot) {
56
+ let parsed;
57
+ try {
58
+ parsed = parseYaml(readFileSync(path.join(repoRoot, NATIVE_CONTRACT_PATH), 'utf8'));
59
+ }
60
+ catch {
61
+ return false;
62
+ }
63
+ if (parsed === null || typeof parsed !== 'object') {
64
+ return false;
65
+ }
66
+ return parsed.frozen_by === 'user';
67
+ }
68
+ /**
69
+ * The command line for one intent-guard subcommand.
70
+ *
71
+ * The resolved binary already carries `check` as its argument prefix, since
72
+ * running the gate is what every other caller wants. The chain needs two
73
+ * other subcommands off the same binary, so the trailing `check` is replaced.
74
+ * A binary whose prefix does not end in `check` is one the candidate table
75
+ * did not choose (the per-command `intent-guard-check`, or a `command:`
76
+ * override with its own `args:`), and neither can run `import-spec` at all.
77
+ */
78
+ function subcommand(binary, name) {
79
+ const prefix = binary.argvPrefix;
80
+ if (prefix[prefix.length - 1] !== 'check') {
81
+ return null;
82
+ }
83
+ return { command: binary.command, argv: [...prefix.slice(0, -1), name] };
84
+ }
85
+ function run(command, argv, cwd, timeoutMs) {
86
+ const child = spawnSync(command, argv, {
87
+ cwd,
88
+ encoding: 'utf8',
89
+ timeout: timeoutMs,
90
+ maxBuffer: 64 * 1024 * 1024,
91
+ });
92
+ return {
93
+ status: child.status,
94
+ stdout: child.stdout ?? '',
95
+ stderr: child.stderr ?? '',
96
+ errorMessage: child.error === undefined ? null : child.error.message,
97
+ };
98
+ }
99
+ /** The first line of whatever the child complained with, for a one-line report. */
100
+ function complaint(result) {
101
+ const text = (result.stderr.trim() === '' ? result.stdout : result.stderr).trim();
102
+ return text.split('\n')[0] ?? '';
103
+ }
104
+ /** The short commit the contract is attributed to, or a placeholder. */
105
+ function shortHead(repoRoot) {
106
+ const child = spawnSync('git', ['rev-parse', '--short', 'HEAD'], {
107
+ cwd: repoRoot,
108
+ encoding: 'utf8',
109
+ });
110
+ const value = (child.stdout ?? '').trim();
111
+ return child.status === 0 && value !== '' ? value : 'an unknown commit';
112
+ }
113
+ export function prepareIntent(options) {
114
+ const { repoRoot, env } = options;
115
+ const timeoutMs = options.timeoutMs ?? 120_000;
116
+ // The contract source is decided FIRST, before git is touched. A repository
117
+ // with no spec is never blocked by this gate, and that promise has to hold
118
+ // on a shallow checkout too: resolving the base ref first would turn a
119
+ // fetch-depth of 1 into exit 2 on a repository the gate was never going to
120
+ // check anything in.
121
+ const eventPath = env.GITHUB_EVENT_PATH;
122
+ const prBody = eventPath === undefined ? null : prBodyFromEvent(eventPath);
123
+ const branch = currentBranch(repoRoot, env);
124
+ const discovery = discoverSpec({
125
+ repoRoot,
126
+ ...(options.spec === undefined ? {} : { spec: options.spec }),
127
+ ...(prBody === null ? {} : { prBody }),
128
+ ...(branch === null ? {} : { branch }),
129
+ });
130
+ if (discovery.kind === 'missing-flag') {
131
+ return {
132
+ kind: 'failed',
133
+ step: 'spec',
134
+ detail: `--spec named "${discovery.spec}", which is not in this repository. ` +
135
+ 'A spec asked for by name is never replaced by a discovered one.',
136
+ };
137
+ }
138
+ let source;
139
+ if (discovery.kind === 'flag') {
140
+ source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
141
+ }
142
+ else if (nativeContractIsFrozen(repoRoot)) {
143
+ source = { kind: 'native', path: NATIVE_CONTRACT_PATH };
144
+ }
145
+ else if (discovery.kind === 'none') {
146
+ source = { kind: 'none' };
147
+ }
148
+ else {
149
+ source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
150
+ }
151
+ if (source.kind === 'none') {
152
+ return {
153
+ kind: 'skip',
154
+ reason: 'no-contract',
155
+ detail: `No frozen ${NATIVE_CONTRACT_PATH} and no spec under ${SPEC_DIR} matching ` +
156
+ `${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
157
+ 'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
158
+ };
159
+ }
160
+ const base = resolveBaseRef({
161
+ ...(options.base === undefined ? {} : { base: options.base }),
162
+ env,
163
+ });
164
+ let paths = null;
165
+ if (base !== null) {
166
+ const changed = changedPathsSince(repoRoot, base.ref);
167
+ if (!changed.ok) {
168
+ return { kind: 'failed', step: 'base', detail: changed.detail };
169
+ }
170
+ paths = changed.paths;
171
+ }
172
+ const common = {
173
+ baseRef: base === null ? null : base.ref,
174
+ baseSource: base === null ? null : base.source,
175
+ paths,
176
+ };
177
+ if (source.kind === 'native') {
178
+ return {
179
+ kind: 'ready',
180
+ preparation: {
181
+ ...common,
182
+ contractSource: source,
183
+ // The repository itself, spelled the way every other gate is spelled:
184
+ // the child already runs with the repository root as its working
185
+ // directory.
186
+ projectDir: '.',
187
+ cleanup: () => undefined,
188
+ },
189
+ };
190
+ }
191
+ if (options.binary === null) {
192
+ // Nothing to run the chain with. The caller reports the missing binary
193
+ // through the ordinary gate-missing path, so this never becomes a second
194
+ // way of saying the same thing.
195
+ return {
196
+ kind: 'failed',
197
+ step: 'import-spec',
198
+ detail: 'no intent-guard binary was resolved, so the spec could not be imported.',
199
+ };
200
+ }
201
+ const importCommand = subcommand(options.binary, 'import-spec');
202
+ if (importCommand === null) {
203
+ return {
204
+ kind: 'failed',
205
+ step: 'import-spec',
206
+ detail: `the resolved binary is ${options.binary.candidate}, which has no import-spec ` +
207
+ 'subcommand. Importing a spec needs the unified intent-guard binary.',
208
+ };
209
+ }
210
+ const importResult = run(importCommand.command, [
211
+ ...importCommand.argv,
212
+ '--project',
213
+ '.',
214
+ '--from',
215
+ 'superpowers',
216
+ '--spec',
217
+ path.join(repoRoot, source.spec),
218
+ ...(source.plan === null ? [] : ['--plan', path.join(repoRoot, source.plan)]),
219
+ '--dry-run',
220
+ ], repoRoot, timeoutMs);
221
+ if (importResult.errorMessage !== null) {
222
+ return { kind: 'failed', step: 'import-spec', detail: importResult.errorMessage };
223
+ }
224
+ if (importResult.status !== 0) {
225
+ return {
226
+ kind: 'failed',
227
+ step: 'import-spec',
228
+ detail: `import-spec exited ${importResult.status ?? -1}: ${complaint(importResult)}`,
229
+ };
230
+ }
231
+ let contractYaml;
232
+ try {
233
+ const parsed = JSON.parse(importResult.stdout);
234
+ if (typeof parsed.contract_yaml !== 'string' || parsed.contract_yaml === '') {
235
+ return {
236
+ kind: 'failed',
237
+ step: 'import-spec',
238
+ detail: 'import-spec printed no contract_yaml, so there is nothing to freeze.',
239
+ };
240
+ }
241
+ contractYaml = parsed.contract_yaml;
242
+ }
243
+ catch {
244
+ return {
245
+ kind: 'failed',
246
+ step: 'import-spec',
247
+ detail: 'import-spec printed something that is not JSON, so no draft could be read.',
248
+ };
249
+ }
250
+ const projectDir = mkdtempSync(path.join(os.tmpdir(), TEMP_PREFIX));
251
+ const cleanup = () => {
252
+ rmSync(projectDir, { recursive: true, force: true });
253
+ };
254
+ try {
255
+ mkdirSync(path.join(projectDir, '.conductor'), { recursive: true });
256
+ writeFileSync(path.join(projectDir, NATIVE_CONTRACT_PATH), contractYaml);
257
+ }
258
+ catch (err) {
259
+ cleanup();
260
+ return {
261
+ kind: 'failed',
262
+ step: 'write-contract',
263
+ detail: `the drafted contract could not be written: ${err.message}`,
264
+ };
265
+ }
266
+ const freezeCommand = subcommand(options.binary, 'freeze');
267
+ if (freezeCommand === null) {
268
+ cleanup();
269
+ return { kind: 'failed', step: 'freeze', detail: 'no freeze subcommand on this binary.' };
270
+ }
271
+ const freezeResult = run(freezeCommand.command, [
272
+ ...freezeCommand.argv,
273
+ '--project',
274
+ projectDir,
275
+ '--approved-by',
276
+ // Says what approved it and against which commit, so the approval is
277
+ // never mistaken for a person's. The spec path is repository-relative,
278
+ // because this string ends up in a contract and a machine path in a
279
+ // contract is exactly what intent-guard's own docs warn about.
280
+ `conductor: ${source.spec} at ${shortHead(repoRoot)}`,
281
+ '--yes',
282
+ '--json',
283
+ ], repoRoot, timeoutMs);
284
+ if (freezeResult.errorMessage !== null || freezeResult.status !== 0) {
285
+ cleanup();
286
+ return {
287
+ kind: 'failed',
288
+ step: 'freeze',
289
+ detail: freezeResult.errorMessage ??
290
+ `freeze exited ${freezeResult.status ?? -1}: ${complaint(freezeResult)}`,
291
+ };
292
+ }
293
+ return {
294
+ kind: 'ready',
295
+ preparation: { ...common, contractSource: source, projectDir, cleanup },
296
+ };
297
+ }
@@ -0,0 +1,62 @@
1
+ export declare const SPEC_DIR = "docs/superpowers/specs";
2
+ export declare const PLAN_DIR = "docs/superpowers/plans";
3
+ export type SpecDiscovery =
4
+ /** Found, with the source that won. Paths are repository-relative. */
5
+ {
6
+ kind: 'flag' | 'pr-body' | 'convention';
7
+ spec: string;
8
+ plan: string | null;
9
+ }
10
+ /** `--spec` named a file that is not there. Never silently replaced. */
11
+ | {
12
+ kind: 'missing-flag';
13
+ spec: string;
14
+ } | {
15
+ kind: 'none';
16
+ };
17
+ export interface SpecDiscoveryOptions {
18
+ repoRoot: string;
19
+ /** `--spec` on the umbrella's command line, repository-relative or absolute. */
20
+ spec?: string;
21
+ /** The pull request body, when this run has one. */
22
+ prBody?: string;
23
+ /** The branch name the slug is derived from. */
24
+ branch?: string;
25
+ }
26
+ /**
27
+ * The branch name with its prefix removed.
28
+ *
29
+ * Only the FIRST segment goes. Dropping everything but the last would turn
30
+ * `feat/online/widget-cache` into `widget-cache` and match a spec about a
31
+ * different feature, and the prefix convention (`feat/`, `fix/`) is exactly
32
+ * one segment deep.
33
+ */
34
+ export declare function branchSlug(branch: string): string;
35
+ /**
36
+ * A spec or plan filename reduced to the part that identifies the feature.
37
+ *
38
+ * The date prefix and the `-design` suffix are the two pieces of the
39
+ * superpowers naming convention that carry no identity: the same feature's
40
+ * spec and plan differ by exactly those, which is how intent-guard's own
41
+ * importer pairs them.
42
+ */
43
+ export declare function normalizeStem(fileName: string): string;
44
+ /** Whether a normalized stem and a slug name the same work. */
45
+ export declare function stemMatches(stem: string, slug: string): boolean;
46
+ /**
47
+ * The path named by a `Spec:` line in a pull request body.
48
+ *
49
+ * Anchored to the start of a line on purpose: a sentence that happens to
50
+ * contain "the Spec: value" in prose is not somebody naming a file, and
51
+ * treating it as one would silently swap the contract a pull request is
52
+ * checked against.
53
+ *
54
+ * The FIRST such line wins when a body carries two. Not a deep decision, but
55
+ * it has to be a decision rather than whatever the regex happened to do: a
56
+ * pull request edited to add a second line above the first would otherwise
57
+ * change contract without the diff showing it.
58
+ */
59
+ export declare function specFromPrBody(body: string): string | null;
60
+ /** `pull_request.body` out of a GitHub event payload, or null. */
61
+ export declare function prBodyFromEvent(eventPath: string): string | null;
62
+ export declare function discoverSpec(options: SpecDiscoveryOptions): SpecDiscovery;