@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.
Files changed (88) hide show
  1. package/npm/core/ai-decisions.d.ts +373 -0
  2. package/npm/core/api.d.ts +15888 -3797
  3. package/npm/core/app-memory.d.ts +69 -0
  4. package/npm/core/assistant-actor.d.ts +28 -7
  5. package/npm/core/audit.d.ts +174 -0
  6. package/npm/core/canary.d.ts +369 -0
  7. package/npm/core/cancel.d.ts +20 -0
  8. package/npm/core/catalog.d.ts +220 -66
  9. package/npm/core/change-types-migrate.d.ts +14 -0
  10. package/npm/core/cite.d.ts +88 -6
  11. package/npm/core/contract-check.d.ts +276 -0
  12. package/npm/core/curated.d.ts +10 -0
  13. package/npm/core/decision-batches.d.ts +29 -0
  14. package/npm/core/declarable-routes.d.ts +52 -0
  15. package/npm/core/declared-links.d.ts +210 -0
  16. package/npm/core/eol.d.ts +5 -0
  17. package/npm/core/fact-paths.d.ts +14 -0
  18. package/npm/core/facts-callers.d.ts +23 -1
  19. package/npm/core/facts-carry.d.ts +8 -2
  20. package/npm/core/facts-deps.d.ts +85 -0
  21. package/npm/core/facts-join-prototype.d.ts +66 -4
  22. package/npm/core/facts-join-vendor.d.ts +67 -7
  23. package/npm/core/facts-join.d.ts +476 -2
  24. package/npm/core/facts-terms.d.ts +108 -0
  25. package/npm/core/facts.d.ts +155 -1
  26. package/npm/core/field-places.d.ts +109 -0
  27. package/npm/core/file-pool.d.ts +84 -0
  28. package/npm/core/fs.d.ts +205 -7
  29. package/npm/core/glob-plain.d.ts +34 -0
  30. package/npm/core/glob.d.ts +14 -0
  31. package/npm/core/hash-cache.d.ts +53 -0
  32. package/npm/core/host-questions.d.ts +273 -1
  33. package/npm/core/identity.d.ts +20 -8
  34. package/npm/core/index.d.ts +38 -0
  35. package/npm/core/initialisms.d.ts +62 -0
  36. package/npm/core/kept-files.d.ts +17 -0
  37. package/npm/core/light.d.ts +5 -0
  38. package/npm/core/link-candidates.d.ts +224 -0
  39. package/npm/core/link-evidence.d.ts +212 -0
  40. package/npm/core/log.d.ts +2 -0
  41. package/npm/core/manifest-edit.d.ts +83 -6
  42. package/npm/core/merge.d.ts +28 -0
  43. package/npm/core/metarepo.d.ts +26 -1
  44. package/npm/core/migrate.d.ts +3 -2
  45. package/npm/core/org-notes.d.ts +180 -0
  46. package/npm/core/orgpack-defaults.d.ts +30 -6
  47. package/npm/core/orgpack-load.d.ts +24 -0
  48. package/npm/core/paths.d.ts +23 -0
  49. package/npm/core/printer.d.ts +18 -0
  50. package/npm/core/process-trees.d.ts +109 -0
  51. package/npm/core/profile-migrate.d.ts +13 -0
  52. package/npm/core/question-order.d.ts +23 -0
  53. package/npm/core/question-owners.d.ts +57 -0
  54. package/npm/core/question-proposals.d.ts +77 -0
  55. package/npm/core/question-roles.d.ts +84 -0
  56. package/npm/core/questions.d.ts +123 -6
  57. package/npm/core/record-cache.d.ts +122 -2
  58. package/npm/core/repo-files.d.ts +66 -0
  59. package/npm/core/repo-reads.d.ts +44 -0
  60. package/npm/core/roles-migrate.d.ts +10 -0
  61. package/npm/core/run-log.d.ts +341 -0
  62. package/npm/core/runtime-migrate.d.ts +18 -0
  63. package/npm/core/schema/ai.d.ts +61 -13
  64. package/npm/core/schema/common.d.ts +32 -8
  65. package/npm/core/schema/component-type.d.ts +193 -0
  66. package/npm/core/schema/conventions.d.ts +80 -0
  67. package/npm/core/schema/dialect.d.ts +12 -12
  68. package/npm/core/schema/fact-corrections.d.ts +112 -2
  69. package/npm/core/schema/facts.d.ts +743 -23
  70. package/npm/core/schema/frameworks.d.ts +12 -12
  71. package/npm/core/schema/kinds.d.ts +230 -66
  72. package/npm/core/schema/orgpack.d.ts +248 -24
  73. package/npm/core/schema/question.d.ts +281 -5
  74. package/npm/core/schema/reading-rules.d.ts +51 -0
  75. package/npm/core/schema/repo-type.d.ts +20 -2
  76. package/npm/core/schema/review.d.ts +30 -9
  77. package/npm/core/schema/scan-verify.d.ts +77 -0
  78. package/npm/core/schema/version.d.ts +4 -1
  79. package/npm/core/schema/workspace.d.ts +29 -11
  80. package/npm/core/setup-edit.d.ts +107 -0
  81. package/npm/core/shared-maps.d.ts +146 -0
  82. package/npm/core/stack-helpers.d.ts +32 -0
  83. package/npm/core/version-order.d.ts +14 -0
  84. package/npm/fs-repo.d.ts +2 -1
  85. package/npm/index.js +14248 -6710
  86. package/npm/listing.d.ts +14 -0
  87. package/npm/sandbox.d.ts +2 -1
  88. 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
- /** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
36
- export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
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
+ };