@fro.bot/systematic 3.31.5 → 3.32.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/HARNESSES.md +18 -0
- package/README.md +1 -1
- package/agents/research/connections-researcher.md +101 -0
- package/dist/ce-connect-helper.d.ts +76 -0
- package/dist/cli.js +1 -1
- package/dist/{index-c95n6n53.js → index-nrbdgp4m.js} +277 -228
- package/dist/index.js +68 -3
- package/dist/lib/bundled-names.d.ts +3 -3
- package/dist/lib/config-protected-fields.d.ts +1 -1
- package/dist/lib/config-schema.d.ts +6 -0
- package/dist/lib/config.d.ts +10 -0
- package/dist/lib/connect-config.d.ts +197 -0
- package/dist/lib/connect-evidence.d.ts +312 -0
- package/dist/lib/connect-helper-core.d.ts +399 -0
- package/dist/lib/connect-state.d.ts +427 -0
- package/dist/lib/opencode-v2-tool-guard.d.ts +40 -0
- package/dist/lib/opencode-v2.d.ts +3 -1
- package/dist/lib/pi-subagents-personas.d.ts +1 -0
- package/dist/lib/validation.d.ts +1 -0
- package/dist/pi.js +53 -6
- package/package.json +6 -4
- package/skills/ce-compound/SKILL.md +39 -2
- package/skills/ce-compound/references/candidate-input.md +91 -0
- package/skills/ce-compound-refresh/SKILL.md +48 -2
- package/skills/ce-connect/SKILL.md +201 -0
- package/skills/ce-connect/references/candidate-contract.md +97 -0
- package/skills/ce-connect/references/headless-and-outcomes.md +86 -0
- package/skills/ce-connect/scripts/connect.mjs +9739 -0
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The evidence boundary for `ce:connect`: what the helper may read from an
|
|
3
|
+
* allowed project and how it reads it. A bounded, hashed inventory of tracked
|
|
4
|
+
* files; a hardened, allow-listed git runner; contained reads; and a citation
|
|
5
|
+
* checker that says which `path:line` citations still hold.
|
|
6
|
+
*
|
|
7
|
+
* Import rule: node builtins and `connect-config.ts` only. The `ce:connect`
|
|
8
|
+
* helper bundles this module, so it must never import zod, `config.ts` or
|
|
9
|
+
* `config-schema.ts`.
|
|
10
|
+
*
|
|
11
|
+
* Trust: an allowed project is untrusted input. Its git config, its file names
|
|
12
|
+
* and its working tree all come from other people, so:
|
|
13
|
+
* - git runs only the subcommands in `GIT_SUBCOMMANDS`, with the hardening
|
|
14
|
+
* flags before the subcommand, a scrubbed environment, `GIT_OPTIONAL_LOCKS=0`
|
|
15
|
+
* so a read never takes a lock or rewrites the index, literal pathspecs for
|
|
16
|
+
* path arguments, and `--` before every one of them (or paths on stdin,
|
|
17
|
+
* NUL-separated, where the subcommand takes them there);
|
|
18
|
+
* - only the listing's regular files (mode 100644 or 100755) become evidence;
|
|
19
|
+
* symlinks (120000) and submodules (160000) are dropped before any open;
|
|
20
|
+
* - a file is read only through `readContainedFile`, which refuses a path that
|
|
21
|
+
* leaves the root, `lstat`s every ancestor and the final component, opens
|
|
22
|
+
* with `O_NOFOLLOW`, and compares the opened descriptor's device and inode
|
|
23
|
+
* with the `lstat` result, then re-checks the ancestors;
|
|
24
|
+
* - only the main checkout is read; a subdirectory or a linked worktree is
|
|
25
|
+
* refused by the allow-entry resolver.
|
|
26
|
+
*
|
|
27
|
+
* Nothing here writes to a project, runs a project command or reads history.
|
|
28
|
+
*/
|
|
29
|
+
import { type AllowEntryMissReason } from './connect-config.js';
|
|
30
|
+
/**
|
|
31
|
+
* The bounds of a run. A run that reaches one is degraded and says so.
|
|
32
|
+
*
|
|
33
|
+
* `maxRulesPerFamily` follows from the Pi delegate's 20-turn cap: a researcher
|
|
34
|
+
* that makes one call per turn needs about three turns to orient and answer,
|
|
35
|
+
* and at most two (a search and a read) per rule, so eight rules fit. A model
|
|
36
|
+
* that batches its calls uses far fewer turns. `maxCandidatesPerBatch` keeps
|
|
37
|
+
* one answer short enough to copy exactly, and `maxFamiliesPerRun` keeps the
|
|
38
|
+
* skill's own context bounded. A test pins every value.
|
|
39
|
+
*/
|
|
40
|
+
export declare const CONNECT_BOUNDS: Readonly<{
|
|
41
|
+
/** Eligible files kept per project, corpus files first. */
|
|
42
|
+
maxFilesPerProject: 4000;
|
|
43
|
+
/** Largest file read, hashed or cited. A larger file is skipped. */
|
|
44
|
+
maxFileBytes: number;
|
|
45
|
+
/** Total bytes hashed per project. Reaching it stops the inventory. */
|
|
46
|
+
maxHashedBytesPerProject: number;
|
|
47
|
+
/** Largest `git ls-files` output accepted. */
|
|
48
|
+
maxListingBytes: number;
|
|
49
|
+
/** Path-and-line citations checked per project. */
|
|
50
|
+
maxCitationsPerProject: 500;
|
|
51
|
+
/** Rules a single rule family may hold. */
|
|
52
|
+
maxRulesPerFamily: 8;
|
|
53
|
+
/** Candidates accepted in one family batch. */
|
|
54
|
+
maxCandidatesPerBatch: 5;
|
|
55
|
+
/** Rule families examined in one run. */
|
|
56
|
+
maxFamiliesPerRun: 6;
|
|
57
|
+
}>;
|
|
58
|
+
export type ConnectBounds = {
|
|
59
|
+
readonly [K in keyof typeof CONNECT_BOUNDS]: number;
|
|
60
|
+
};
|
|
61
|
+
/** The only git subcommands the helper runs. */
|
|
62
|
+
export declare const GIT_SUBCOMMANDS: readonly ['ls-files', 'cat-file', 'check-ignore'];
|
|
63
|
+
export type GitSubcommand = (typeof GIT_SUBCOMMANDS)[number];
|
|
64
|
+
/**
|
|
65
|
+
* Config overrides placed before the subcommand. A repository's own config can
|
|
66
|
+
* name an fsmonitor command or a hooks directory that git would run on its
|
|
67
|
+
* behalf; these three settings turn that off for the helper's calls.
|
|
68
|
+
*/
|
|
69
|
+
export declare const GIT_HARDENING_ARGS: readonly ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-c', 'core.untrackedCache=false'];
|
|
70
|
+
/**
|
|
71
|
+
* The full argv after `git`: hardening flags, the subcommand, its options, and
|
|
72
|
+
* then `--` followed by any path arguments. A path that starts with `-` can
|
|
73
|
+
* therefore never be read as an option.
|
|
74
|
+
*/
|
|
75
|
+
export declare function buildGitArgv(subcommand: GitSubcommand, args: readonly string[], paths?: readonly string[]): string[];
|
|
76
|
+
/**
|
|
77
|
+
* A fresh environment for git. Nothing the caller exported reaches it except
|
|
78
|
+
* `PATH` and the home and temp locations, so a stray `GIT_DIR`,
|
|
79
|
+
* `GIT_WORK_TREE` or `GIT_EXTERNAL_DIFF` cannot redirect a read.
|
|
80
|
+
* `literalPathspecs` makes git read path arguments as plain names.
|
|
81
|
+
*/
|
|
82
|
+
export declare function gitEnvironment(base?: Readonly<Record<string, string | undefined>>, literalPathspecs?: boolean): Record<string, string>;
|
|
83
|
+
export type GitRun = {
|
|
84
|
+
readonly status: 'ok';
|
|
85
|
+
readonly exitCode: number;
|
|
86
|
+
readonly stdout: Buffer;
|
|
87
|
+
}
|
|
88
|
+
/** The subcommand is not in `GIT_SUBCOMMANDS`; git was not started. */
|
|
89
|
+
| {
|
|
90
|
+
readonly status: 'refused';
|
|
91
|
+
} | {
|
|
92
|
+
readonly status: 'failed';
|
|
93
|
+
readonly reason: 'git-unavailable' | 'git-failed' | 'output-too-large';
|
|
94
|
+
};
|
|
95
|
+
export interface GitRunOptions {
|
|
96
|
+
/** The git executable. Defaults to `git` on `PATH`. */
|
|
97
|
+
readonly gitBinary?: string;
|
|
98
|
+
/** Largest stdout accepted, in bytes. */
|
|
99
|
+
readonly maxBytes?: number;
|
|
100
|
+
/** Path arguments, passed after `--`. */
|
|
101
|
+
readonly paths?: readonly string[];
|
|
102
|
+
/** Bytes written to git's stdin. */
|
|
103
|
+
readonly input?: Buffer;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Run one allow-listed git subcommand in `cwd`. The exit code is returned for
|
|
107
|
+
* the caller to read: `check-ignore` exits 1 when nothing matched. Never throws.
|
|
108
|
+
*/
|
|
109
|
+
export declare function runGit(cwd: string, subcommand: string, args: readonly string[], options?: GitRunOptions): GitRun;
|
|
110
|
+
/** Why a file was not read. */
|
|
111
|
+
export type ReadFailure =
|
|
112
|
+
/** The path is absolute, empty, malformed or climbs out of the root. */
|
|
113
|
+
'outside-root'
|
|
114
|
+
/** An ancestor or the final component is a symlink. */
|
|
115
|
+
| 'symlink'
|
|
116
|
+
/** The final component is a directory, FIFO, device or socket. */
|
|
117
|
+
| 'not-regular' | 'missing' | 'too-large' | 'unreadable'
|
|
118
|
+
/** The path changed between the check and the open. */
|
|
119
|
+
| 'changed';
|
|
120
|
+
export type ContainedRead = {
|
|
121
|
+
readonly kind: 'bytes';
|
|
122
|
+
readonly bytes: Buffer;
|
|
123
|
+
readonly sha256: string;
|
|
124
|
+
} | {
|
|
125
|
+
readonly kind: 'refused';
|
|
126
|
+
readonly reason: ReadFailure;
|
|
127
|
+
};
|
|
128
|
+
export interface ContainedReadOptions {
|
|
129
|
+
/** Largest file accepted. Defaults to `CONNECT_BOUNDS.maxFileBytes`. */
|
|
130
|
+
readonly maxBytes?: number;
|
|
131
|
+
/** Runs between the last `lstat` and the open. A test seam for races. */
|
|
132
|
+
readonly beforeOpen?: () => void;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Read a regular file at a root-relative path without following a symlink.
|
|
136
|
+
*
|
|
137
|
+
* 1. The path must be plain and relative, so `..` and absolute paths are
|
|
138
|
+
* refused before the filesystem is touched.
|
|
139
|
+
* 2. Every ancestor and the final component are `lstat`ed. A symlink anywhere,
|
|
140
|
+
* or a final component that is not a regular file, is refused, so a FIFO
|
|
141
|
+
* is never opened.
|
|
142
|
+
* 3. The open uses `O_NOFOLLOW` and `O_NONBLOCK`, and the opened descriptor's
|
|
143
|
+
* device and inode must equal the `lstat` result, so a path swapped after
|
|
144
|
+
* the check fails instead of being read.
|
|
145
|
+
* 4. The ancestors are checked once more after the open, which catches a
|
|
146
|
+
* directory swapped for a symlink to the same file.
|
|
147
|
+
* 5. The read stops one byte past `maxBytes`; the size is never trusted from a
|
|
148
|
+
* `stat`.
|
|
149
|
+
*
|
|
150
|
+
* `root` must be a trusted real path. Never throws.
|
|
151
|
+
*/
|
|
152
|
+
export declare function readContainedFile(root: string, rel: string, options?: ContainedReadOptions): ContainedRead;
|
|
153
|
+
export interface CitationInput {
|
|
154
|
+
/** Root-relative path. */
|
|
155
|
+
readonly path: string;
|
|
156
|
+
/** First cited line, 1-based. */
|
|
157
|
+
readonly start: number;
|
|
158
|
+
/** Last cited line, inclusive. */
|
|
159
|
+
readonly end: number;
|
|
160
|
+
/** The name the citing claim says is in the span. */
|
|
161
|
+
readonly symbol?: string;
|
|
162
|
+
}
|
|
163
|
+
export type CitationUncheckedReason = 'no-symbol' | 'invalid-span' | ReadFailure;
|
|
164
|
+
/**
|
|
165
|
+
* What a check established:
|
|
166
|
+
* - `passed`: the symbol is in the cited lines.
|
|
167
|
+
* - `not-in-span`: it is not; `foundElsewhere` says whether it still occurs
|
|
168
|
+
* somewhere else in the file (the code moved) or nowhere (it is gone).
|
|
169
|
+
* - `unchecked`: the check could not run, and the reason says why.
|
|
170
|
+
*
|
|
171
|
+
* A verdict reports whether the citation still holds, not whether the code has
|
|
172
|
+
* stayed put.
|
|
173
|
+
*/
|
|
174
|
+
export type CitationVerdict = {
|
|
175
|
+
readonly verdict: 'passed';
|
|
176
|
+
} | {
|
|
177
|
+
readonly verdict: 'not-in-span';
|
|
178
|
+
readonly foundElsewhere: boolean;
|
|
179
|
+
} | {
|
|
180
|
+
readonly verdict: 'unchecked';
|
|
181
|
+
readonly reason: CitationUncheckedReason;
|
|
182
|
+
};
|
|
183
|
+
export interface CheckCitationOptions {
|
|
184
|
+
/** Largest cited file accepted. Defaults to `CONNECT_BOUNDS.maxFileBytes`. */
|
|
185
|
+
readonly maxBytes?: number;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Whether `identifier` occurs in `text` as a whole name: no identifier
|
|
189
|
+
* character directly before or after the match. A dotted chain is matched as
|
|
190
|
+
* one name. `alphaBeta` is not found in `alphaBetaAsync` or `myalphaBeta`.
|
|
191
|
+
*/
|
|
192
|
+
export declare function containsIdentifier(text: string, identifier: string): boolean;
|
|
193
|
+
/**
|
|
194
|
+
* Check one citation. The file is read through `readContainedFile`, so a path
|
|
195
|
+
* outside the root, through a symlink, to a FIFO or over the size cap is
|
|
196
|
+
* `unchecked` with the reason, and the file is never opened unsafely.
|
|
197
|
+
*/
|
|
198
|
+
export declare function checkCitation(root: string, citation: CitationInput, options?: CheckCitationOptions): CitationVerdict;
|
|
199
|
+
export interface ExtractedCitation {
|
|
200
|
+
readonly path: string;
|
|
201
|
+
readonly start: number;
|
|
202
|
+
readonly end: number;
|
|
203
|
+
/** The first identifier the citing sentence names in backticks. */
|
|
204
|
+
readonly symbol?: string;
|
|
205
|
+
/** 1-based line of the citation in the text. */
|
|
206
|
+
readonly line: number;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* The `path.ext:N[-M]` citations in markdown prose, each with the first
|
|
210
|
+
* identifier its sentence names in backticks. Lexical, not a parser. Known
|
|
211
|
+
* limits: URLs, `path:N:M` stack frames, paths with `.`/`..` segments and
|
|
212
|
+
* absolute paths are not citations; fenced blocks are skipped; a comma list of
|
|
213
|
+
* lines reads as its first span; a sentence ends at `.`, `!`, `?` or `;`
|
|
214
|
+
* followed by whitespace, outside backticks.
|
|
215
|
+
*/
|
|
216
|
+
export declare function extractCitations(text: string): ExtractedCitation[];
|
|
217
|
+
export interface CitedDocument {
|
|
218
|
+
readonly path: string;
|
|
219
|
+
readonly text: string;
|
|
220
|
+
}
|
|
221
|
+
export interface ProjectCitation {
|
|
222
|
+
readonly document: string;
|
|
223
|
+
readonly line: number;
|
|
224
|
+
readonly citation: Omit<ExtractedCitation, 'line'>;
|
|
225
|
+
readonly result: CitationVerdict;
|
|
226
|
+
}
|
|
227
|
+
export interface ProjectCitationReport {
|
|
228
|
+
/** True when no document holds a path-and-line citation, so none could be checked. */
|
|
229
|
+
readonly unsupported: boolean;
|
|
230
|
+
readonly citations: readonly ProjectCitation[];
|
|
231
|
+
/** True when the citation cap stopped the check. */
|
|
232
|
+
readonly truncated: boolean;
|
|
233
|
+
}
|
|
234
|
+
export interface ProjectCitationOptions {
|
|
235
|
+
readonly bounds?: Partial<ConnectBounds>;
|
|
236
|
+
readonly maxBytes?: number;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* Check every `path:line` citation in a project's documents against the
|
|
240
|
+
* project's files. A project whose documents hold none is `unsupported`: the
|
|
241
|
+
* check has nothing to say about it, which is not the same as every citation
|
|
242
|
+
* holding.
|
|
243
|
+
*/
|
|
244
|
+
export declare function reportProjectCitations(root: string, documents: readonly CitedDocument[], options?: ProjectCitationOptions): ProjectCitationReport;
|
|
245
|
+
/** What a file is evidence of. The order is the inventory order. */
|
|
246
|
+
export declare const INVENTORY_ROLES: readonly ['learning', 'plan', 'brainstorm', 'workflow', 'config', 'code'];
|
|
247
|
+
export type InventoryRole = (typeof INVENTORY_ROLES)[number];
|
|
248
|
+
export interface InventoryFile {
|
|
249
|
+
readonly path: string;
|
|
250
|
+
readonly role: InventoryRole;
|
|
251
|
+
readonly bytes: number;
|
|
252
|
+
readonly sha256: string;
|
|
253
|
+
}
|
|
254
|
+
export interface SkippedFile {
|
|
255
|
+
readonly path: string;
|
|
256
|
+
readonly reason: ReadFailure | 'unsafe-path-character';
|
|
257
|
+
}
|
|
258
|
+
/**
|
|
259
|
+
* A single quote, a dollar sign or a backtick. The promotion step puts a path
|
|
260
|
+
* in a single-quoted shell word, so a file with one in its name cannot be cited.
|
|
261
|
+
*/
|
|
262
|
+
export declare const UNSAFE_PATH_CHARACTER: RegExp;
|
|
263
|
+
export type InventoryResult = {
|
|
264
|
+
readonly status: 'ok';
|
|
265
|
+
/** The verified main repository root, as a realpath. */
|
|
266
|
+
readonly mainRoot: string;
|
|
267
|
+
readonly files: readonly InventoryFile[];
|
|
268
|
+
/** Files listed but not hashed. At most `MAX_LISTED_SKIPS` are named. */
|
|
269
|
+
readonly skipped: readonly SkippedFile[];
|
|
270
|
+
readonly skippedCount: number;
|
|
271
|
+
readonly excluded: {
|
|
272
|
+
readonly symlinks: number;
|
|
273
|
+
readonly submodules: number;
|
|
274
|
+
/** Unmerged entries and modes other than a regular file. */
|
|
275
|
+
readonly unmerged: number;
|
|
276
|
+
/** Tracked files that an ignore rule matches. */
|
|
277
|
+
readonly ignored: number;
|
|
278
|
+
/** Tracked regular files that are not evidence. */
|
|
279
|
+
readonly ineligible: number;
|
|
280
|
+
};
|
|
281
|
+
readonly truncated: {
|
|
282
|
+
/** The file-count cap dropped eligible files. */
|
|
283
|
+
readonly files: boolean;
|
|
284
|
+
/** The hashing cap stopped the inventory. */
|
|
285
|
+
readonly hashCap: boolean;
|
|
286
|
+
};
|
|
287
|
+
}
|
|
288
|
+
/** The entry is not an allowed main checkout; `reason` is the allow-entry reason. */
|
|
289
|
+
| {
|
|
290
|
+
readonly status: 'unmatched';
|
|
291
|
+
readonly reason: AllowEntryMissReason;
|
|
292
|
+
} | {
|
|
293
|
+
readonly status: 'failed';
|
|
294
|
+
readonly reason: 'git-unavailable' | 'git-failed' | 'listing-too-large' | 'listing-malformed';
|
|
295
|
+
};
|
|
296
|
+
export interface InventoryOptions {
|
|
297
|
+
readonly bounds?: Partial<ConnectBounds>;
|
|
298
|
+
readonly gitBinary?: string;
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* Inventory the tracked, regular, eligible files of one allowed project.
|
|
302
|
+
*
|
|
303
|
+
* `entry` goes through `resolveAllowEntry`, so only a main checkout is read.
|
|
304
|
+
* Git lists the index once (`ls-files -z --cached --stage`); symlinks and
|
|
305
|
+
* submodules are dropped from the listing before any file is opened. Eligible
|
|
306
|
+
* files are corpus documents, workflows, config and code, kept in role order
|
|
307
|
+
* up to the file cap, then filtered through `check-ignore`. Each file is read
|
|
308
|
+
* through `readContainedFile` and hashed until the hashing cap. A cap sets its
|
|
309
|
+
* `truncated` flag; a file that cannot be read is named in `skipped`. Nothing
|
|
310
|
+
* is written to the project. Never throws.
|
|
311
|
+
*/
|
|
312
|
+
export declare function inventoryProject(entry: string, options?: InventoryOptions): InventoryResult;
|