@maycombhq/sdk 2.0.0-beta.3 → 2.0.0-beta.30
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/npm/core/ai-decisions.d.ts +373 -0
- package/npm/core/api.d.ts +15888 -3797
- package/npm/core/app-memory.d.ts +69 -0
- package/npm/core/assistant-actor.d.ts +28 -7
- package/npm/core/audit.d.ts +174 -0
- package/npm/core/canary.d.ts +369 -0
- package/npm/core/cancel.d.ts +20 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/change-types-migrate.d.ts +14 -0
- package/npm/core/cite.d.ts +88 -6
- package/npm/core/contract-check.d.ts +276 -0
- package/npm/core/curated.d.ts +10 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declarable-routes.d.ts +52 -0
- package/npm/core/declared-links.d.ts +210 -0
- package/npm/core/eol.d.ts +5 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +23 -1
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-deps.d.ts +85 -0
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +67 -7
- package/npm/core/facts-join.d.ts +476 -2
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +155 -1
- package/npm/core/field-places.d.ts +109 -0
- package/npm/core/file-pool.d.ts +84 -0
- package/npm/core/fs.d.ts +205 -7
- package/npm/core/glob-plain.d.ts +34 -0
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/hash-cache.d.ts +53 -0
- package/npm/core/host-questions.d.ts +273 -1
- package/npm/core/identity.d.ts +20 -8
- package/npm/core/index.d.ts +38 -0
- package/npm/core/initialisms.d.ts +62 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +5 -0
- package/npm/core/link-candidates.d.ts +224 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +83 -6
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +26 -1
- package/npm/core/migrate.d.ts +3 -2
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +30 -6
- package/npm/core/orgpack-load.d.ts +24 -0
- package/npm/core/paths.d.ts +23 -0
- package/npm/core/printer.d.ts +18 -0
- package/npm/core/process-trees.d.ts +109 -0
- package/npm/core/profile-migrate.d.ts +13 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +57 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +84 -0
- package/npm/core/questions.d.ts +123 -6
- package/npm/core/record-cache.d.ts +122 -2
- package/npm/core/repo-files.d.ts +66 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +10 -0
- package/npm/core/run-log.d.ts +341 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +61 -13
- package/npm/core/schema/common.d.ts +32 -8
- package/npm/core/schema/component-type.d.ts +193 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +12 -12
- package/npm/core/schema/fact-corrections.d.ts +112 -2
- package/npm/core/schema/facts.d.ts +743 -23
- package/npm/core/schema/frameworks.d.ts +12 -12
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +248 -24
- package/npm/core/schema/question.d.ts +281 -5
- package/npm/core/schema/reading-rules.d.ts +51 -0
- package/npm/core/schema/repo-type.d.ts +20 -2
- package/npm/core/schema/review.d.ts +30 -9
- package/npm/core/schema/scan-verify.d.ts +77 -0
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/version-order.d.ts +14 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +14248 -6710
- package/npm/listing.d.ts +14 -0
- package/npm/sandbox.d.ts +2 -1
- package/package.json +1 -1
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type FileStat } from "./file-pool.js";
|
|
1
2
|
/**
|
|
2
3
|
* Record files read and parsed once, then kept between runs (ADR 0119, with its addendum of
|
|
3
4
|
* 2026-10-26). A metarepo's catalog is about 1,500 files and its specs 400 more; reading and
|
|
@@ -16,13 +17,47 @@
|
|
|
16
17
|
*
|
|
17
18
|
* Nothing here decides what a file means: the caller's `parse` does, and only its output (the
|
|
18
19
|
* record, or the problem with the file) is kept.
|
|
20
|
+
*
|
|
21
|
+
* Racily clean files (the final review of beta.28.2, Git's rule of the same name). A file system
|
|
22
|
+
* keeps a file's time to a grain (FAT 2 s, HFS+ 1 s, some SMB and NFS mounts 1 s or more), so a
|
|
23
|
+
* same-size edit made within that grain of a read or a write can keep the time the parse was kept
|
|
24
|
+
* by, and size and time alone would serve the old text. So each parse is kept with the clock as
|
|
25
|
+
* it was taken (`at`: before the bytes parsed were read, or before a writer wrote them), and one
|
|
26
|
+
* whose file's time is no more than `RACY_MS` before `at` is "racy": it keeps the sha256 of the
|
|
27
|
+
* bytes parsed, and is reused only when the file still hashes to them (read in the file pool's
|
|
28
|
+
* workers; cheaper than a parse), then kept again as of the hash's read when by then it is no
|
|
29
|
+
* longer racy (the next command, seconds on: from then on its stat alone decides). A parse whose
|
|
30
|
+
* file's time is more than `RACY_MS` before `at` is trusted by size and time, as before: any edit
|
|
31
|
+
* after `at` has a time after `at` less the grain, so it can't keep that time. A parse kept with no `at` (an older cache) is racy, and with no hash it is
|
|
32
|
+
* parsed again. The rule takes this machine's clock and the file system's to agree to within the
|
|
33
|
+
* grain (a mount whose server runs more than `RACY_MS` behind can still serve a stale parse, as
|
|
34
|
+
* Git can).
|
|
35
|
+
*/
|
|
36
|
+
/**
|
|
37
|
+
* The widest timestamp grain allowed for (FAT's 2 s): a parse kept of a file whose time was
|
|
38
|
+
* within this of the moment it was kept is checked by its hash before it is reused.
|
|
19
39
|
*/
|
|
40
|
+
export declare const RACY_MS = 2000;
|
|
41
|
+
/** Tests set the clock a parse is kept at (ms; default `Date.now`). */
|
|
42
|
+
export declare const recordCacheHooks: {
|
|
43
|
+
now?: () => number;
|
|
44
|
+
/** The tests: the size limit of the parses kept in memory, in place of `MEMORY_MAX`. */
|
|
45
|
+
memoryMaxBytes?: number;
|
|
46
|
+
/**
|
|
47
|
+
* ADR 0205's proof: each parse a read takes from memory is checked against the parse of its
|
|
48
|
+
* file as the cache on disk would give it (its JSON), or a throw.
|
|
49
|
+
*/
|
|
50
|
+
checkMemory?: boolean;
|
|
51
|
+
};
|
|
20
52
|
/** One file's parse: the value, or why the file isn't valid. Never both. */
|
|
21
53
|
export interface Parsed<T> {
|
|
22
54
|
/** The file, relative to the folder, with forward slashes. */
|
|
23
55
|
rel: string;
|
|
24
56
|
value?: T;
|
|
25
57
|
problem?: string;
|
|
58
|
+
/** With `withStats`: the file's size and time (ms, floored) as this read found them (-1: none). */
|
|
59
|
+
size?: number;
|
|
60
|
+
mtimeMs?: number;
|
|
26
61
|
}
|
|
27
62
|
/** What a caller's parse says about one file. */
|
|
28
63
|
export type ParseOutcome<T> = {
|
|
@@ -32,8 +67,25 @@ export type ParseOutcome<T> = {
|
|
|
32
67
|
ok: false;
|
|
33
68
|
message: string;
|
|
34
69
|
};
|
|
35
|
-
|
|
36
|
-
|
|
70
|
+
interface Entry {
|
|
71
|
+
size: number;
|
|
72
|
+
mtimeMs: number;
|
|
73
|
+
/** The clock (ms) as the parse was kept: before its bytes were read, or written. None: racy. */
|
|
74
|
+
at?: number;
|
|
75
|
+
/** A racy entry's sha256 of the bytes parsed (none once it isn't racy). */
|
|
76
|
+
sha?: string;
|
|
77
|
+
value?: unknown;
|
|
78
|
+
problem?: string;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. With `signal`, a stop
|
|
82
|
+
* ends it between two lots with CancelledError (beta.28.3).
|
|
83
|
+
*/
|
|
84
|
+
export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>, signal?: AbortSignal): Promise<O[]>;
|
|
85
|
+
/** How many reads took their parses from memory (the tests). */
|
|
86
|
+
export declare const recordCacheStats: {
|
|
87
|
+
fromMemory: number;
|
|
88
|
+
};
|
|
37
89
|
/**
|
|
38
90
|
* Read and parse every named file of a folder, reusing the parses kept from an earlier run for
|
|
39
91
|
* the files that haven't changed. `name` names the kind of file (`catalog`, `spec`), `version`
|
|
@@ -49,4 +101,72 @@ export declare function readParsedFiles<T>(o: {
|
|
|
49
101
|
parse: (text: string, rel: string) => ParseOutcome<T>;
|
|
50
102
|
/** The root of the metarepo this run is working in; none means no cache (read-only). */
|
|
51
103
|
cacheRoot?: string;
|
|
104
|
+
/**
|
|
105
|
+
* False: the parses kept under `cacheRoot` are read, and nothing is written there (a preview,
|
|
106
|
+
* which writes nothing: beta.28.1, it parsed a 100,000-record catalog from its files).
|
|
107
|
+
*/
|
|
108
|
+
keep?: boolean;
|
|
109
|
+
/** Each file's size and time with its parse (beta.28.1: a write matches them to its own read). */
|
|
110
|
+
withStats?: boolean;
|
|
111
|
+
/**
|
|
112
|
+
* Told what this read keeps under `cacheRoot` (not called when it keeps nothing): a writer that
|
|
113
|
+
* then writes some of the files adds their parses with `keepParses` (beta.28.2).
|
|
114
|
+
*/
|
|
115
|
+
kept?: (k: KeptParses<T>) => void;
|
|
116
|
+
/**
|
|
117
|
+
* Beta.28.3: a job's Stop. A stop while the files' sizes and times are read, their bytes
|
|
118
|
+
* hashed, or the files read and parsed (a first read of a large catalog) ends the read with
|
|
119
|
+
* CancelledError; nothing is kept of a stopped read.
|
|
120
|
+
*/
|
|
121
|
+
signal?: AbortSignal;
|
|
122
|
+
/**
|
|
123
|
+
* ADR 0205 step 4: a writer's read, in the app's server: its parses kept in memory between
|
|
124
|
+
* reads too (frozen, handed out without a copy), and taken from there. Outside a server, or
|
|
125
|
+
* with `keep: false`, nothing changes.
|
|
126
|
+
*/
|
|
127
|
+
memory?: boolean;
|
|
52
128
|
}): Promise<Parsed<T>[]>;
|
|
129
|
+
/** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
|
|
130
|
+
export interface KeptParses<T> {
|
|
131
|
+
readonly memo: {
|
|
132
|
+
root: string;
|
|
133
|
+
file: string;
|
|
134
|
+
};
|
|
135
|
+
readonly version: string;
|
|
136
|
+
readonly dir: string;
|
|
137
|
+
/** The kept parses by path, as that read left them. */
|
|
138
|
+
readonly entries: ReadonlyMap<string, Entry>;
|
|
139
|
+
/** Only to tie the type to the parse's value. */
|
|
140
|
+
readonly _value?: T;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Add the parses of files a writer wrote since its read (`k`) to what that read kept, and forget
|
|
144
|
+
* the files it removed (beta.28.2: a catalog write rewrites its features and glossary terms,
|
|
145
|
+
* megabytes of YAML, and the next read parsed them again). Each file is kept by the size and time
|
|
146
|
+
* it had as it was written, with the parse of the text the writer wrote there, which is what a
|
|
147
|
+
* read of it would parse; a file whose size or time is another now (changed since), or gone, isn't
|
|
148
|
+
* kept. A file written moments ago is racy (its time is within `RACY_MS` of the write): it is kept
|
|
149
|
+
* with the hash of the bytes written (`writeFileAtomic`'s `stat` gives it, and the clock as the
|
|
150
|
+
* write began), so the next read reuses it only when the file still hashes to them; one with no
|
|
151
|
+
* hash is parsed again by the next read. A cache that can't be written costs the next read its
|
|
152
|
+
* parses.
|
|
153
|
+
*/
|
|
154
|
+
export declare function keepParses<T>(k: KeptParses<T>, o: {
|
|
155
|
+
/**
|
|
156
|
+
* Each file written, with the size and time it had as it was written (`writeFileAtomic`'s
|
|
157
|
+
* `stat`): it is kept only while it still has exactly those, so an edit made since (of the
|
|
158
|
+
* same size too: its time differs, or within the grain its hash does) is parsed by the next
|
|
159
|
+
* read, never served the writer's text. `sha` and `writtenAt` as `writeFileAtomic` gives them.
|
|
160
|
+
*/
|
|
161
|
+
files: readonly {
|
|
162
|
+
rel: string;
|
|
163
|
+
value?: T;
|
|
164
|
+
problem?: string;
|
|
165
|
+
at: FileStat & {
|
|
166
|
+
sha?: string;
|
|
167
|
+
writtenAt?: number;
|
|
168
|
+
};
|
|
169
|
+
}[];
|
|
170
|
+
removed: readonly string[];
|
|
171
|
+
}): Promise<void>;
|
|
172
|
+
export {};
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { type GlobMatcher } from "./glob.js";
|
|
2
|
+
import { type PlainGlob } from "./glob-plain.js";
|
|
3
|
+
/**
|
|
4
|
+
* A file's bytes as text, the same way for every reader: UTF-16 (LE or BE) when it starts with
|
|
5
|
+
* that byte-order mark (SQL Server Management Studio saves .sql files so), else UTF-8 with any
|
|
6
|
+
* byte-order mark dropped, else, when the bytes aren't valid UTF-8, windows-1252 (a Latin-1 file
|
|
7
|
+
* from an older editor). Line numbers and quotes then agree between the read, the scan and the
|
|
8
|
+
* check.
|
|
9
|
+
*/
|
|
10
|
+
export declare function decodeText(bytes: Uint8Array): string;
|
|
11
|
+
/** Whether a file's bytes are binary: a NUL in the first 8,000, unless it is marked UTF-16. */
|
|
12
|
+
export declare function isBinaryBytes(bytes: Uint8Array): boolean;
|
|
13
|
+
/** The same, for text `decodeText` made: a NUL is left only where the bytes were binary. */
|
|
14
|
+
export declare function isBinaryText(text: string): boolean;
|
|
15
|
+
/** A Git LFS pointer a checkout wasn't smudged with: three lines that stand for the real file. */
|
|
16
|
+
export declare function isLfsPointer(text: string): boolean;
|
|
17
|
+
/**
|
|
18
|
+
* Tokens a text costs, as every budget counts them (ADR 0112): four ASCII characters a token,
|
|
19
|
+
* and each character outside ASCII a token of its own. Characters / 4 alone counted Japanese,
|
|
20
|
+
* Chinese or Cyrillic at a quarter of what a tokenizer gives, so prompts over the model's limit
|
|
21
|
+
* were planned as fitting. `tokenUnits` is the same count in quarters, to sum over parts.
|
|
22
|
+
*/
|
|
23
|
+
export declare function estimateTokens(text: string): number;
|
|
24
|
+
/** Quarter tokens: 1 for each ASCII character, 4 for each other (an astral one counted once). */
|
|
25
|
+
export declare function tokenUnits(text: string): number;
|
|
26
|
+
export interface IgnoreRule {
|
|
27
|
+
/** The folder of the .gitignore, repo-relative ("" for the root). */
|
|
28
|
+
base: string;
|
|
29
|
+
/** Matched in linear time (glob.ts): a scanned repo's .gitignore can't stall the scan. */
|
|
30
|
+
re: GlobMatcher;
|
|
31
|
+
negate: boolean;
|
|
32
|
+
dirOnly: boolean;
|
|
33
|
+
/**
|
|
34
|
+
* The line as a test of the path's own text, when it is one (`node_modules`, `*.class`): what
|
|
35
|
+
* most lines are, so a large clone's files are told without the automaton. Same answer as `re`.
|
|
36
|
+
*/
|
|
37
|
+
plain?: PlainGlob;
|
|
38
|
+
}
|
|
39
|
+
/** The rules of one .gitignore file (git's syntax: #, !, a trailing /, a leading or inner /). */
|
|
40
|
+
export declare function ignoreRules(text: string, base: string): IgnoreRule[];
|
|
41
|
+
/** Whether git would ignore a path by these rules: the last rule that matches decides. */
|
|
42
|
+
export declare function ignoredBy(rules: readonly IgnoreRule[], path: string, isDir: boolean): boolean;
|
|
43
|
+
export interface WalkOptions {
|
|
44
|
+
/**
|
|
45
|
+
* Whether a folder is left out: `above` are the folders it is in (repo-relative parts), `name`
|
|
46
|
+
* its own, `siblings` every name beside it. Asked after .git, links and .gitignore.
|
|
47
|
+
*/
|
|
48
|
+
skipFolder?: (above: readonly string[], name: string, siblings: readonly string[]) => boolean;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* A checkout's files, repo-relative with `/`, in the order a walk by name meets them: never a
|
|
52
|
+
* symbolic link (so no loop, no file outside the repo and no secret under another name), never
|
|
53
|
+
* `.git`, and nothing a .gitignore in the repo ignores (an ignored folder isn't walked). Only the
|
|
54
|
+
* repo's own .gitignore files are read. Deterministic: the same tree gives the same list.
|
|
55
|
+
*/
|
|
56
|
+
export declare function listRepoFilesSync(root: string, o?: WalkOptions): string[];
|
|
57
|
+
/**
|
|
58
|
+
* The same walk, a file at a time: `visit` returns false to stop. Stops after `max` files and
|
|
59
|
+
* says it was cut.
|
|
60
|
+
*/
|
|
61
|
+
export declare function walkRepo(root: string, visit: (path: string) => Promise<boolean | void>, o?: WalkOptions & {
|
|
62
|
+
max?: number;
|
|
63
|
+
}): Promise<{
|
|
64
|
+
files: number;
|
|
65
|
+
cut: boolean;
|
|
66
|
+
}>;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { Fact, FactOf } from "./schema/facts.js";
|
|
2
|
+
import type { Question } from "./schema/question.js";
|
|
3
|
+
/**
|
|
4
|
+
* The commit a checkout is at, read from its `.git` files: HEAD, a loose ref or packed-refs,
|
|
5
|
+
* following a worktree's `gitdir:` and `commondir`. Undefined when there is no checkout.
|
|
6
|
+
*/
|
|
7
|
+
export declare function headFromFiles(dir: string): Promise<string | undefined>;
|
|
8
|
+
/** Where a repo is checked out: the metarepo's workspace/<repo>, or the repo itself when adopted. */
|
|
9
|
+
export declare const checkoutDirOf: (root: string, repo: string) => string;
|
|
10
|
+
/**
|
|
11
|
+
* not-read: no facts and no verifier's report (a repo the readers alone mapped, or none);
|
|
12
|
+
* stale: the facts were read at another commit than the checkout is at; incomplete: facts were
|
|
13
|
+
* rejected, some aren't verified, there is no verifier's report, or files went unread; read: none
|
|
14
|
+
* of these.
|
|
15
|
+
*/
|
|
16
|
+
export type RepoReadState = "not-read" | "stale" | "incomplete" | "read";
|
|
17
|
+
export interface RepoRead {
|
|
18
|
+
repo: string;
|
|
19
|
+
state: RepoReadState;
|
|
20
|
+
/** Why it is stale or incomplete, in words a person reads; empty when it is read. */
|
|
21
|
+
why: string[];
|
|
22
|
+
/** The command that reads it again or checks it. */
|
|
23
|
+
next?: string;
|
|
24
|
+
/** The commit its facts were read at, and the checkout's. */
|
|
25
|
+
commit?: string;
|
|
26
|
+
head?: string;
|
|
27
|
+
/** Its facts, for the questions that cite their lines. */
|
|
28
|
+
facts: Fact[];
|
|
29
|
+
}
|
|
30
|
+
/** The read of one repo (see `RepoRead`). Never throws: an unreadable file is a reason. */
|
|
31
|
+
export declare function repoReadOf(root: string, repo: string): Promise<RepoRead>;
|
|
32
|
+
/**
|
|
33
|
+
* The steps whose questions are about a link (ADR 0140): which repo or system answers a call
|
|
34
|
+
* (`facts-targets`, scanner's TARGETS_STEP; `estate-targets`, the estate join's) and which repo
|
|
35
|
+
* answers on a host (`scan-hosts`). Their answers join calls.
|
|
36
|
+
*/
|
|
37
|
+
export declare const LINK_QUESTION_STEPS: ReadonlySet<string>;
|
|
38
|
+
export declare const isLinkQuestion: (q: Pick<Question, "askedBy">) => boolean;
|
|
39
|
+
/**
|
|
40
|
+
* The calls a link question asks about: a targets question's are the call facts of its repo on
|
|
41
|
+
* the lines it cites (one per call, a group's every call, Q1); a hosts question's are every call
|
|
42
|
+
* to its host, in any repo (its evidence cites only the first few). `facts` are the facts by repo.
|
|
43
|
+
*/
|
|
44
|
+
export declare function callsOfQuestion(q: Pick<Question, "askedBy" | "repo" | "evidence" | "question">, facts: ReadonlyMap<string, readonly Fact[]>): FactOf<"call">[];
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* roles.yaml version 1 → 2 (ADR 0140) → 3 (ADR 0191). Version 2 adds `teams`, version 3 who
|
|
3
|
+
* takes each role (`defaults`, a team's `roles`); a file without them names none, as before, so
|
|
4
|
+
* the step writes the new number only and keeps the file's comments, order and line layout
|
|
5
|
+
* (`atticus upgrade`'s roles-v2, which writes the current version).
|
|
6
|
+
*/
|
|
7
|
+
export declare function migrateRolesText(text: string): {
|
|
8
|
+
text: string;
|
|
9
|
+
changed: boolean;
|
|
10
|
+
};
|
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR 0187: what a command run outside the app prints, for the app's Console. A long command
|
|
3
|
+
* (`atticus map`, `verify`, `scan`, `workspace sync`, a task run, ...) run in a terminal, by an
|
|
4
|
+
* editor or by a Copilot session keeps:
|
|
5
|
+
*
|
|
6
|
+
* - `.atticus/logs/runs/<runId>.log`: the lines it printed, each redacted as the local log is
|
|
7
|
+
* (ADR 0050's redactText: no secrets, tokens, credentials in URLs or home folder), with no
|
|
8
|
+
* colour codes; bounded (its last lines are kept past RUN_LOG_MAX_BYTES).
|
|
9
|
+
* - `.atticus/logs/running/<runId>.json`: who and what — the command words, the ids it was given
|
|
10
|
+
* (repo, change, run and task ids; beta.27 review: only in the places the command declares for
|
|
11
|
+
* them, each an id's strict shape and no secret's, titleWord; the rest `…`), the names of
|
|
12
|
+
* its flags (in `flags`, never their values; beta.27: the title keeps the value of a flag on
|
|
13
|
+
* an allow-list, TITLE_VALUE_FLAGS, when it is an id, a name or a date: titleValue), the process and a hash of the
|
|
14
|
+
* machine's name, when it
|
|
15
|
+
* started, and how it ended (its exit code), written again when it ends. While it runs it is
|
|
16
|
+
* written again every RUN_HEARTBEAT_MS (`beatAt`), and on Linux it keeps when its process
|
|
17
|
+
* started (`procStart`, from /proc): a process id used again by another process, or a run
|
|
18
|
+
* silent past RUN_SILENT_MS, is a run that ended without saying.
|
|
19
|
+
*
|
|
20
|
+
* Only the last RUN_LOG_KEEP runs are kept. `.atticus/logs/` is this machine's own (never
|
|
21
|
+
* committed). The names have no `:` (Windows). Nothing here loads a schema: the command line
|
|
22
|
+
* starts a run before it knows anything else. Writing never throws: a run log that can't be
|
|
23
|
+
* written is skipped, never failing the command it describes.
|
|
24
|
+
*/
|
|
25
|
+
export declare const RUN_LOG_KEEP = 50;
|
|
26
|
+
export declare const RUN_LOG_MAX_BYTES: number;
|
|
27
|
+
/** A line longer than this is cut (a minified file printed whole). */
|
|
28
|
+
export declare const RUN_LOG_LINE_MAX = 4000;
|
|
29
|
+
/** The lines a read gives at most. */
|
|
30
|
+
export declare const RUN_LOG_READ_MAX = 5000;
|
|
31
|
+
/** A running command writes its record again this often. */
|
|
32
|
+
export declare const RUN_HEARTBEAT_MS = 30000;
|
|
33
|
+
/** A running record that beats, silent (record and log) for longer than this, has ended. */
|
|
34
|
+
export declare const RUN_SILENT_MS: number;
|
|
35
|
+
/** `20261109-101530-4242-ab12`: when (UTC), the process, and a little randomness. */
|
|
36
|
+
export declare const TERMINAL_RUN_ID: RegExp;
|
|
37
|
+
export declare const runLogsDirOf: (root: string) => string;
|
|
38
|
+
export declare const runningDirOf: (root: string) => string;
|
|
39
|
+
/**
|
|
40
|
+
* `app` (beta.27 review): a job the app started (a sync, a scan, an AI step), kept here too, so
|
|
41
|
+
* it is still in the Console after the app restarts; its `job` says which.
|
|
42
|
+
*/
|
|
43
|
+
export type StartedBy = "terminal" | "vscode" | "intellij" | "copilot" | "app";
|
|
44
|
+
export type TerminalRunState = "running" | "done" | "failed" | "cancelled";
|
|
45
|
+
export interface TerminalRunRecord {
|
|
46
|
+
schemaVersion: 1;
|
|
47
|
+
runId: string;
|
|
48
|
+
pid: number;
|
|
49
|
+
/** A hash of the machine's name: whether the process can be looked for here. */
|
|
50
|
+
host: string;
|
|
51
|
+
title: string;
|
|
52
|
+
command: string[];
|
|
53
|
+
flags: string[];
|
|
54
|
+
startedBy: StartedBy;
|
|
55
|
+
startedAt: string;
|
|
56
|
+
state: TerminalRunState;
|
|
57
|
+
finishedAt?: string;
|
|
58
|
+
exitCode?: number;
|
|
59
|
+
/** Lines printed so far (as of the last write of the record; the log has them all). */
|
|
60
|
+
lines: number;
|
|
61
|
+
/** Lines no longer in the log (the log keeps its last lines). */
|
|
62
|
+
dropped: number;
|
|
63
|
+
/** When the process started, as the system says (Linux: /proc), to tell a reused pid. */
|
|
64
|
+
procStart?: string;
|
|
65
|
+
/** When a running command last wrote its record (every RUN_HEARTBEAT_MS). */
|
|
66
|
+
beatAt?: string;
|
|
67
|
+
/**
|
|
68
|
+
* A job the app started (startedBy `app`): its id in that app's run and its kind. Beta.27
|
|
69
|
+
* re-review: `ids`, the ids its title shows (each a title's word, else `…`: appRunTitle).
|
|
70
|
+
*/
|
|
71
|
+
job?: {
|
|
72
|
+
id: string;
|
|
73
|
+
kind: string;
|
|
74
|
+
ids?: string[];
|
|
75
|
+
};
|
|
76
|
+
/** A job the app started that was still running when the app closed. */
|
|
77
|
+
appClosed?: true;
|
|
78
|
+
/**
|
|
79
|
+
* Beta.30 (ADR 0202 point 10): the longest time, in milliseconds, the command printed
|
|
80
|
+
* nothing: between two of its lines (progress lines included), before its first and after its
|
|
81
|
+
* last. A run from before beta.30 has none.
|
|
82
|
+
*/
|
|
83
|
+
longestQuietMs?: number;
|
|
84
|
+
}
|
|
85
|
+
/** A record as read: `stale` when its process is gone though it never said it ended. */
|
|
86
|
+
export type TerminalRunView = TerminalRunRecord & {
|
|
87
|
+
stale?: true;
|
|
88
|
+
};
|
|
89
|
+
export declare function recordedCommand(positionals: readonly string[], flags: readonly string[]): boolean;
|
|
90
|
+
type Redaction = {
|
|
91
|
+
home?: string;
|
|
92
|
+
user?: string;
|
|
93
|
+
};
|
|
94
|
+
/**
|
|
95
|
+
* Beta.27 review: the flags whose value a run's title keeps — an allow-list, never a deny-list.
|
|
96
|
+
* Each is a string option the command line declares (cli-options' OPTIONS; a test holds the two
|
|
97
|
+
* together) whose value, by its name and what it means, is an id, a name, a handle, a date or a
|
|
98
|
+
* small number: a repo, a change, a run, a stage's kind, a lens, a person (`--by @bao`). Free text
|
|
99
|
+
* (`--note`, `--answer`, `--with`, `--value`), a file, a folder, a host or a URL (`--from`,
|
|
100
|
+
* `--path`, `--host`), a key (`--key`), anything an organisation's secret could be typed into and
|
|
101
|
+
* every flag the command line doesn't know (`--pass=hunter2`) keep their name only.
|
|
102
|
+
*/
|
|
103
|
+
export declare const TITLE_VALUE_FLAGS: ReadonlySet<string>;
|
|
104
|
+
/** A value kept is cut to this many characters. */
|
|
105
|
+
export declare const TITLE_VALUE_MAX = 48;
|
|
106
|
+
/**
|
|
107
|
+
* Beta.27 re-review: a work item's reference, by the trackers C1's ExternalRef names (a test
|
|
108
|
+
* holds the two together) and nothing else: `pin:1234`, `pass:1234` or `otp:123456` is no id.
|
|
109
|
+
*/
|
|
110
|
+
export declare const WORK_ITEM_SYSTEMS: readonly ["ado", "jira"];
|
|
111
|
+
/**
|
|
112
|
+
* Beta.27 review: whether a word may show in a run's title, as a positional word or as one item
|
|
113
|
+
* of an allowed flag's value (titleValue). Never: a word with an `@` but a leading handle's, a
|
|
114
|
+
* `\`, a `//`, a space, one of core's token prefixes (cite.ts's TOKEN_PREFIXES) or shapes
|
|
115
|
+
* (hasSecretShape), or anything the log's redaction (with this machine's home folder and user
|
|
116
|
+
* name) would change. Then one of the ids it knows by their form (ID_FORMS, a link's), or no `:`,
|
|
117
|
+
* no long run of hex or digits, no key-like shape (keyIsSecret) and an id's strict shape
|
|
118
|
+
* (idShaped). The word as given, or undefined.
|
|
119
|
+
*/
|
|
120
|
+
export declare function titleWord(word: string | undefined, redact?: Redaction): string | undefined;
|
|
121
|
+
/**
|
|
122
|
+
* Beta.27: a flag's value kept in a title, as typed (`--target 2027-03-31`, `--by @bao`,
|
|
123
|
+
* `--repos forge-ledger,forge-teller`). Beta.27 review: only for a flag of TITLE_VALUE_FLAGS;
|
|
124
|
+
* never a value with a `:` (a host's path, a user and password, a reference to a variable) or
|
|
125
|
+
* starting with `-` (the next flag, read as this one's value); a list (`a,b`) only when each of
|
|
126
|
+
* its items is a title's word (titleWord); one kept is cut to TITLE_VALUE_MAX.
|
|
127
|
+
*/
|
|
128
|
+
export declare function titleValue(flag: string, value: string | undefined, redact?: Redaction): string | undefined;
|
|
129
|
+
/**
|
|
130
|
+
* The command words, ids and flag names of a run, and its title. Beta.27: with the flags'
|
|
131
|
+
* values (`values`, by flag name; a boolean flag has none), each kept when titleValue keeps it, so
|
|
132
|
+
* the title reads as the command was typed; beta.26 dropped them all ("--target --by"). Beta.27
|
|
133
|
+
* review: each word is a title's word (titleWord) or `…` (words dropped one after another are one
|
|
134
|
+
* `…`); the command line gives only the words a command declares (its words and its arguments'
|
|
135
|
+
* places, by the help), the rest as `…`. The words and values are redacted as the log is
|
|
136
|
+
* (`redact`: this machine's home folder and user name by default; a test gives its own).
|
|
137
|
+
*/
|
|
138
|
+
export declare function runTitle(positionals: readonly string[], flags: readonly string[], values?: Readonly<Record<string, string | undefined>>, redact?: Redaction): {
|
|
139
|
+
command: string[];
|
|
140
|
+
title: string;
|
|
141
|
+
};
|
|
142
|
+
/**
|
|
143
|
+
* Beta.27 re-review: the words an app's job is named by in the run log, by its kind (the
|
|
144
|
+
* server's job kinds). Never the job's own title, which may carry what a person typed.
|
|
145
|
+
*/
|
|
146
|
+
export declare const APP_JOB_WORDS: Readonly<Record<string, string>>;
|
|
147
|
+
/**
|
|
148
|
+
* Beta.27 re-review: an app job's title in the run log, by the rules a command's title follows:
|
|
149
|
+
* its kind's words (APP_JOB_WORDS), then the ids it names (a repo, a change, a run), each kept
|
|
150
|
+
* when it is a title's word (titleWord: an id's strict shape, no secret's) and `…` otherwise.
|
|
151
|
+
* The app's titles (`Reconcile <diagram>`, `A question for <team>`, the words a request sent)
|
|
152
|
+
* went to the record as they were, past every rule a terminal's run is held to.
|
|
153
|
+
*/
|
|
154
|
+
export declare function appRunTitle(kind: string, ids?: readonly string[], redact?: Redaction): {
|
|
155
|
+
title: string;
|
|
156
|
+
ids: string[];
|
|
157
|
+
};
|
|
158
|
+
/**
|
|
159
|
+
* Beta.27 re-review: whether a run log is kept at `root`: a metarepo (its org pack at the root
|
|
160
|
+
* or, adopted in place, in `.atticus/`) where ATTICUS_RUN_LOG isn't `off`. The command line and
|
|
161
|
+
* the app's jobs ask the same: `atticus ui` in a bare folder makes nothing there.
|
|
162
|
+
*/
|
|
163
|
+
export declare function runLogKept(root: string, env?: NodeJS.ProcessEnv): boolean;
|
|
164
|
+
/** A metarepo, or a repo adopted in place: where Atticus keeps its logs (never a bare folder). */
|
|
165
|
+
export declare function isMetarepoRoot(root: string): boolean;
|
|
166
|
+
/** Beside the records: the first run of beta.27 re-titled the runs kept before it. */
|
|
167
|
+
export declare const RETITLED_MARK = ".retitled-beta27";
|
|
168
|
+
/** A record bigger than this is no record beta.26 wrote: left as it is, never read. */
|
|
169
|
+
export declare const RETITLE_MAX_BYTES: number;
|
|
170
|
+
/**
|
|
171
|
+
* Beta.27 review: beta.26 kept every word that looked like an id in a run's title and words, a
|
|
172
|
+
* key typed after `secret set` among them. The first command of beta.27 at a metarepo writes each
|
|
173
|
+
* record kept again with the title, words and flag names the new rules give (`retitle`, the
|
|
174
|
+
* command line's: it knows each command's arguments and options), and nothing else of it (its
|
|
175
|
+
* log, state and times stay); RETITLED_MARK says it was done. How many it wrote again or removed.
|
|
176
|
+
*
|
|
177
|
+
* Beta.27 re-review: a run of `secret` is removed, record and log (beta.26 printed a mistyped
|
|
178
|
+
* key back into its log). Only a regular file of at most RETITLE_MAX_BYTES is read (never a link,
|
|
179
|
+
* a FIFO or a folder), a record whose process is still running is left to it (and the mark
|
|
180
|
+
* waits, so the next command tries again; a run killed under beta.26 is titled again), a removal
|
|
181
|
+
* that fails is tried again the same way, so is a record that can't be read or parsed while it
|
|
182
|
+
* was written within 7 days of now, either way (half-written in place by a live run), and a record is written
|
|
183
|
+
* beside itself and put in place, never through a link. A folder that can't be written is left
|
|
184
|
+
* alone (nothing could change), and one whose mark can't be written isn't tried again by this
|
|
185
|
+
* process. Never throws: a record that can't be read or written is left as it is.
|
|
186
|
+
*/
|
|
187
|
+
export declare function retitleTerminalRuns(root: string, retitle: (r: {
|
|
188
|
+
command: string[];
|
|
189
|
+
flags: string[];
|
|
190
|
+
}) => {
|
|
191
|
+
command: string[];
|
|
192
|
+
title: string;
|
|
193
|
+
flags?: string[];
|
|
194
|
+
}): number;
|
|
195
|
+
/** Where the run was started, as its environment says. */
|
|
196
|
+
export declare function startedByOf(env?: NodeJS.ProcessEnv): StartedBy;
|
|
197
|
+
/**
|
|
198
|
+
* When a process started, as Linux keeps it (/proc/<pid>/stat's starttime, in ticks since boot):
|
|
199
|
+
* one file read, no command run. Undefined elsewhere, or when it can't be read.
|
|
200
|
+
*/
|
|
201
|
+
export declare function procStartOf(pid: number): string | undefined;
|
|
202
|
+
/**
|
|
203
|
+
* A printed text as the lines the log keeps: no colour codes, no \r, each redacted and cut.
|
|
204
|
+
* Beta.27 re-review: a token by its shape alone (hasSecretShape: an access key id, a Git host's
|
|
205
|
+
* token, a JWT, a URL's password) is masked too, wherever it is on the line (an echoed path), for
|
|
206
|
+
* a terminal's run and an app's job alike.
|
|
207
|
+
*/
|
|
208
|
+
export declare function runLogLines(text: string, o?: {
|
|
209
|
+
home?: string;
|
|
210
|
+
user?: string;
|
|
211
|
+
}): string[];
|
|
212
|
+
export interface TerminalRunRecorder {
|
|
213
|
+
readonly runId: string;
|
|
214
|
+
/** Print a line (or several, split at newlines) to the run's log. */
|
|
215
|
+
line(text: string): void;
|
|
216
|
+
/** Record how it ended: 0 done, 130 or 143 (Ctrl+C, a stop) cancelled, else failed. */
|
|
217
|
+
end(code: number, how?: "crash" | "app-closed"): void; /**
|
|
218
|
+
* ADR 0202 points 9 and 10: the command waits on a person's answer (`true`), or has it
|
|
219
|
+
* (`false`). The time between the two is the person's, never the command's silence.
|
|
220
|
+
*/
|
|
221
|
+
waits(on: boolean): void;
|
|
222
|
+
}
|
|
223
|
+
export interface StartRunOptions {
|
|
224
|
+
positionals: readonly string[];
|
|
225
|
+
flags: readonly string[];
|
|
226
|
+
/** Beta.27: the flags' values, by name, for the title (runTitle keeps the safe ones). */
|
|
227
|
+
values?: Readonly<Record<string, string | undefined>>;
|
|
228
|
+
env?: NodeJS.ProcessEnv;
|
|
229
|
+
now?: () => Date;
|
|
230
|
+
pid?: number;
|
|
231
|
+
keep?: number;
|
|
232
|
+
maxBytes?: number;
|
|
233
|
+
redact?: {
|
|
234
|
+
home?: string;
|
|
235
|
+
user?: string;
|
|
236
|
+
};
|
|
237
|
+
/**
|
|
238
|
+
* Record the end on the process's exit, Ctrl+C and SIGTERM too, when nothing else did (the
|
|
239
|
+
* command line passes true; a test doesn't).
|
|
240
|
+
*/
|
|
241
|
+
hookProcess?: boolean;
|
|
242
|
+
/** Write the record again this often while it runs. Default RUN_HEARTBEAT_MS with hookProcess. */
|
|
243
|
+
heartbeatMs?: number;
|
|
244
|
+
/** When this process started (procStartOf, for its own pid only). */
|
|
245
|
+
procStart?: () => string | undefined;
|
|
246
|
+
/** Whether a process is there (pidAlive), for the runs pruned as this one starts. */
|
|
247
|
+
alive?: (pid: number) => boolean;
|
|
248
|
+
/**
|
|
249
|
+
* Beta.27 review: a job the app started (startAppRun): its job, and `app` as where it started.
|
|
250
|
+
* Beta.27 re-review: titled by the rules a command's title follows (never the app's own words):
|
|
251
|
+
* by the command it runs (`command`: the positionals, flags and values given), else by its kind
|
|
252
|
+
* and the ids it names (appRunTitle).
|
|
253
|
+
*/
|
|
254
|
+
app?: {
|
|
255
|
+
job: {
|
|
256
|
+
id: string;
|
|
257
|
+
kind: string;
|
|
258
|
+
};
|
|
259
|
+
ids?: readonly string[];
|
|
260
|
+
command?: true;
|
|
261
|
+
};
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* Start a run's files. Undefined when they can't be written (the run goes on without them).
|
|
265
|
+
* The caller checks `recordedCommand` first.
|
|
266
|
+
*/
|
|
267
|
+
export declare function startTerminalRun(root: string, o: StartRunOptions): TerminalRunRecorder | undefined;
|
|
268
|
+
/**
|
|
269
|
+
* Beta.27 review: a job the app started, kept in the run log as a command run is (ADR 0187), so
|
|
270
|
+
* the Console, Runs and Problems still have it after the app restarts; it beats while it runs,
|
|
271
|
+
* so one left running by an app that crashed reads as ended. Beta.27 re-review: its title follows
|
|
272
|
+
* a command's rules: the command it runs (`command`, the words the command line's title rules
|
|
273
|
+
* kept: titleInputsOf), else its kind and the ids it names (`ids`, each checked: appRunTitle).
|
|
274
|
+
* The caller checks runLogKept first.
|
|
275
|
+
*/
|
|
276
|
+
export declare function startAppRun(root: string, o: {
|
|
277
|
+
job: {
|
|
278
|
+
id: string;
|
|
279
|
+
kind: string;
|
|
280
|
+
};
|
|
281
|
+
ids?: readonly string[];
|
|
282
|
+
command?: {
|
|
283
|
+
positionals: string[];
|
|
284
|
+
flags: string[];
|
|
285
|
+
values?: Readonly<Record<string, string | undefined>>;
|
|
286
|
+
};
|
|
287
|
+
now?: () => Date;
|
|
288
|
+
redact?: {
|
|
289
|
+
home?: string;
|
|
290
|
+
user?: string;
|
|
291
|
+
};
|
|
292
|
+
heartbeatMs?: number;
|
|
293
|
+
}): TerminalRunRecorder | undefined;
|
|
294
|
+
/** Whether a process is there: signal 0 asks without sending anything. */
|
|
295
|
+
export declare function pidAlive(pid: number): boolean;
|
|
296
|
+
/**
|
|
297
|
+
* The runs kept, newest first. A run still `running` whose process is gone on this machine (or
|
|
298
|
+
* that started days ago elsewhere) is `stale`: it ended without saying (closed terminal, a crash).
|
|
299
|
+
*/
|
|
300
|
+
export declare function readTerminalRuns(root: string, o?: {
|
|
301
|
+
alive?: (pid: number) => boolean;
|
|
302
|
+
now?: () => Date;
|
|
303
|
+
/** When a process started (procStartOf). */
|
|
304
|
+
startOf?: (pid: number) => string | undefined;
|
|
305
|
+
}): TerminalRunView[];
|
|
306
|
+
/** One run as read now, or undefined. */
|
|
307
|
+
export declare const readTerminalRun: (root: string, runId: string, o?: {
|
|
308
|
+
alive?: (pid: number) => boolean;
|
|
309
|
+
now?: () => Date;
|
|
310
|
+
startOf?: (pid: number) => string | undefined;
|
|
311
|
+
}) => TerminalRunView | undefined;
|
|
312
|
+
/**
|
|
313
|
+
* A run's lines from a line on (`from`, counted from its first line ever), at most `max`; without
|
|
314
|
+
* `from`, its last `max`. `total` is how many it has printed. Undefined for no such run.
|
|
315
|
+
*/
|
|
316
|
+
export declare function readTerminalRunLines(root: string, runId: string, from?: number, max?: number): {
|
|
317
|
+
from: number;
|
|
318
|
+
lines: string[];
|
|
319
|
+
total: number;
|
|
320
|
+
} | undefined;
|
|
321
|
+
/** Where a tail of a run's log has read to: the next line's number and its byte in the file. */
|
|
322
|
+
export interface RunLogTail {
|
|
323
|
+
line: number;
|
|
324
|
+
bytes: number;
|
|
325
|
+
/** The record's dropped count and the file (its inode) when read: either changing is a cut. */
|
|
326
|
+
dropped: number;
|
|
327
|
+
ino: number;
|
|
328
|
+
}
|
|
329
|
+
/**
|
|
330
|
+
* A run's new lines since `at` (where the last tail read to), at most `max`: only the bytes
|
|
331
|
+
* added are read. Without `at`, or when the log was cut meanwhile, the whole log is read once:
|
|
332
|
+
* its last `max` lines without `at`, else from `at.line` (or the first line kept, when those were
|
|
333
|
+
* dropped). `more` says lines past `max` wait for the next read. Undefined for no such run.
|
|
334
|
+
*/
|
|
335
|
+
export declare function tailTerminalRunLines(root: string, runId: string, at: RunLogTail | undefined, max?: number): {
|
|
336
|
+
from: number;
|
|
337
|
+
lines: string[];
|
|
338
|
+
at: RunLogTail;
|
|
339
|
+
more: boolean;
|
|
340
|
+
} | undefined;
|
|
341
|
+
export {};
|
|
@@ -9,3 +9,21 @@ export declare function migrateRuntimeText(text: string): {
|
|
|
9
9
|
text: string;
|
|
10
10
|
changed: boolean;
|
|
11
11
|
};
|
|
12
|
+
/**
|
|
13
|
+
* runtime.yaml to version 3 (ADR 0171), for a file that names copilot-acp (a mode, or the
|
|
14
|
+
* copilotAcp section): the number only, every other line as the person wrote it. A file that
|
|
15
|
+
* doesn't name it means the same at version 1 or 2, so it is left as it is.
|
|
16
|
+
*/
|
|
17
|
+
export declare function migrateRuntimeV3Text(text: string): {
|
|
18
|
+
text: string;
|
|
19
|
+
changed: boolean;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* runtime.yaml to version 4 (ADR 0181), for a file that sets `decide` (whether the AI decides
|
|
23
|
+
* pairings and option questions itself): the number only, every other line as the person wrote
|
|
24
|
+
* it. A file without it means the same at version 1 to 3, so it is left as it is.
|
|
25
|
+
*/
|
|
26
|
+
export declare function migrateRuntimeV4Text(text: string): {
|
|
27
|
+
text: string;
|
|
28
|
+
changed: boolean;
|
|
29
|
+
};
|