@maycombhq/sdk 2.0.0-beta.26 → 2.0.0-beta.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,86 @@
1
+ import { type ChildProcess } from "node:child_process";
2
+ /**
3
+ * Beta.27 review: the processes Atticus starts in a process group of their own (a build, a git
4
+ * the app may stop), kept so none outlives Atticus. A process in its own group no longer gets the
5
+ * terminal's signals (Ctrl+C, the terminal closed), so while any runs, or a task run holds on to a
6
+ * stop (holdStop), one handler per signal (SIGINT, SIGTERM, SIGHUP) stops them all, tells each
7
+ * listener (onStopping: taskrun aborts its model call), and lets the signal end Atticus once nothing
8
+ * holds on (or after TREE_SIGNAL_GRACE_MS). When Atticus exits, every tree still running is killed
9
+ * outright. Shared by taskrun's builds and workspace's git (it was taskrun's own).
10
+ */
11
+ /** How a tracked tree is stopped: its own way (git's tree, a build's group), by the signal. */
12
+ export type StopTree = (signal: NodeJS.Signals) => void;
13
+ /** However long the runs take to record themselves, Atticus ends by the signal within this. */
14
+ export declare const TREE_SIGNAL_GRACE_MS = 10000;
15
+ /**
16
+ * Stop every tracked tree (SIGTERM, each its own way) and tell each listener: Atticus is
17
+ * stopping (atticus ui on its way out, or a signal).
18
+ */
19
+ export declare function stopTrackedTrees(): void;
20
+ /** Hear Atticus stopping (stopTrackedTrees, a signal). Gives back the way to stop hearing. */
21
+ export declare function onStopping(fn: () => void): () => void;
22
+ /**
23
+ * Beta.27 re-review: Atticus's own handlers of a signal, the ones that end (or stop) Atticus
24
+ * themselves: atticus ui's, map --all's Ctrl+C. Counting the process's listeners took any
25
+ * library's for one (signal-exit, which @inquirer/core loads through OpenSpec, listens to every
26
+ * signal and ends the process only when it alone listens), so neither ended it and Ctrl+C did
27
+ * nothing. A `once` handler that has heard the signal still counts until that signal's listeners
28
+ * have all run. A `fallback` one (a terminal run's record) ends Atticus only when nobody else
29
+ * does, nor these trees (stopPending): it never counts here.
30
+ */
31
+ type SignalFn = (sig: NodeJS.Signals) => void;
32
+ /**
33
+ * Hear a signal as Atticus's own handler: one that ends or stops Atticus (process-trees and the
34
+ * run log then leave the ending to it), or with `fallback`, one that ends it only when nothing
35
+ * else does. Gives back the way to stop hearing it.
36
+ */
37
+ export declare function onAtticusSignal(sig: NodeJS.Signals, fn: SignalFn, o?: {
38
+ once?: boolean;
39
+ fallback?: boolean;
40
+ }): () => void;
41
+ /**
42
+ * Whether Atticus has a handler of its own for `sig` (other than `except`, never a fallback one)
43
+ * that ends it.
44
+ */
45
+ export declare function atticusHandles(sig: NodeJS.Signals, except?: SignalFn): boolean;
46
+ /**
47
+ * Whether these trees hold a signal that ends Atticus once they have ended and the runs recorded
48
+ * the stop (it is raised again then): a fallback handler leaves the end to it until then.
49
+ */
50
+ export declare const stopPending: () => boolean;
51
+ /**
52
+ * Keep a child in its own process group until it ends: stopped with Atticus (a signal,
53
+ * stopTrackedTrees) by `stop`, killed by it with SIGKILL when Atticus exits. Gives back the way
54
+ * to let go of it (when it has ended).
55
+ */
56
+ export declare function trackTree(child: ChildProcess, stop?: StopTree): () => void;
57
+ /**
58
+ * Hold a stop for a task run, from its start until its record is saved: a signal meanwhile
59
+ * stops its trees, and Atticus ends only once it is released.
60
+ */
61
+ export declare function holdStop(): () => void;
62
+ /** How many trees are tracked now (tests). */
63
+ export declare const trackedTrees: () => number;
64
+ /**
65
+ * The child and everything it started: on Windows its whole tree (taskkill /T /F), elsewhere its
66
+ * process group (it was started detached), else the child alone.
67
+ */
68
+ export declare function stopProcessGroup(child: ChildProcess, signal?: NodeJS.Signals): void;
69
+ /**
70
+ * Every process below `pid` (POSIX `ps`, read without blocking), each with when it started (as
71
+ * ps says), deepest last; none when ps can't be run. When it started tells a process from another
72
+ * given the same pid later.
73
+ */
74
+ export declare function processDescendants(pid: number): Promise<Map<number, string>>;
75
+ /** How long a stopped tree gets to end before it is killed outright. */
76
+ export declare const TREE_KILL_AFTER_MS = 5000;
77
+ /**
78
+ * Kill a process and everything it started (git clone runs git-remote-https and index-pack). On
79
+ * Windows, taskkill /T takes the tree; elsewhere the process ran in its own group, which is
80
+ * signalled whole, with each process found below it (where a new group can't be made, a sandbox,
81
+ * the group alone would miss them); what hasn't ended a moment later is killed outright. The
82
+ * second pass reads the processes again and kills only those still there with the same start, so
83
+ * a pid given to another process meanwhile is never signalled. `ps` is read without blocking.
84
+ */
85
+ export declare function killProcessTree(child: ChildProcess, signal?: NodeJS.Signals): void;
86
+ export {};
@@ -58,6 +58,14 @@ export declare function routeQuestion(root: string, id: string, o: {
58
58
  by: string;
59
59
  at: string;
60
60
  }): Promise<Question>;
61
+ /**
62
+ * Write a question's file. With `before` (the text it was read as), only when the file still
63
+ * holds that text: a change made meanwhile (a person's answer in the app, another command) is
64
+ * never overwritten, and FileChangedError says so instead (round 46).
65
+ */
66
+ /** A question's file, and the text `writeQuestion` writes there (a rename computes it first, ADR 0195). */
67
+ export declare const questionFileOf: (root: string, id: string) => string;
68
+ export declare const questionFileText: (q: Question) => string;
61
69
  /**
62
70
  * Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
63
71
  * is a question they answered as they asked it). Every other writer goes through
@@ -7,8 +7,11 @@
7
7
  * (ADR 0050's redactText: no secrets, tokens, credentials in URLs or home folder), with no
8
8
  * colour codes; bounded (its last lines are kept past RUN_LOG_MAX_BYTES).
9
9
  * - `.atticus/logs/running/<runId>.json`: who and what — the command words, the ids it was given
10
- * (repo, change, run and task ids: words that look like an id and nothing else), the names of
11
- * its flags (never their values), the process and a hash of the machine's name, when it
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
12
15
  * started, and how it ended (its exit code), written again when it ends. While it runs it is
13
16
  * written again every RUN_HEARTBEAT_MS (`beatAt`), and on Linux it keeps when its process
14
17
  * started (`procStart`, from /proc): a process id used again by another process, or a run
@@ -33,7 +36,11 @@ export declare const RUN_SILENT_MS: number;
33
36
  export declare const TERMINAL_RUN_ID: RegExp;
34
37
  export declare const runLogsDirOf: (root: string) => string;
35
38
  export declare const runningDirOf: (root: string) => string;
36
- export type StartedBy = "terminal" | "vscode" | "intellij" | "copilot";
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";
37
44
  export type TerminalRunState = "running" | "done" | "failed" | "cancelled";
38
45
  export interface TerminalRunRecord {
39
46
  schemaVersion: 1;
@@ -57,17 +64,128 @@ export interface TerminalRunRecord {
57
64
  procStart?: string;
58
65
  /** When a running command last wrote its record (every RUN_HEARTBEAT_MS). */
59
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;
60
78
  }
61
79
  /** A record as read: `stale` when its process is gone though it never said it ended. */
62
80
  export type TerminalRunView = TerminalRunRecord & {
63
81
  stale?: true;
64
82
  };
65
83
  export declare function recordedCommand(positionals: readonly string[], flags: readonly string[]): boolean;
66
- /** The command words, ids and flag names of a run, and its title. */
67
- export declare function runTitle(positionals: readonly string[], flags: readonly string[]): {
84
+ type Redaction = {
85
+ home?: string;
86
+ user?: string;
87
+ };
88
+ /**
89
+ * Beta.27 review: the flags whose value a run's title keeps — an allow-list, never a deny-list.
90
+ * Each is a string option the command line declares (cli-options' OPTIONS; a test holds the two
91
+ * together) whose value, by its name and what it means, is an id, a name, a handle, a date or a
92
+ * small number: a repo, a change, a run, a stage's kind, a lens, a person (`--by @bao`). Free text
93
+ * (`--note`, `--answer`, `--with`, `--value`), a file, a folder, a host or a URL (`--from`,
94
+ * `--path`, `--host`), a key (`--key`), anything an organisation's secret could be typed into and
95
+ * every flag the command line doesn't know (`--pass=hunter2`) keep their name only.
96
+ */
97
+ export declare const TITLE_VALUE_FLAGS: ReadonlySet<string>;
98
+ /** A value kept is cut to this many characters. */
99
+ export declare const TITLE_VALUE_MAX = 48;
100
+ /**
101
+ * Beta.27 re-review: a work item's reference, by the trackers C1's ExternalRef names (a test
102
+ * holds the two together) and nothing else: `pin:1234`, `pass:1234` or `otp:123456` is no id.
103
+ */
104
+ export declare const WORK_ITEM_SYSTEMS: readonly ["ado", "jira"];
105
+ /**
106
+ * Beta.27 review: whether a word may show in a run's title, as a positional word or as one item
107
+ * of an allowed flag's value (titleValue). Never: a word with an `@` but a leading handle's, a
108
+ * `\`, a `//`, a space, one of core's token prefixes (cite.ts's TOKEN_PREFIXES) or shapes
109
+ * (hasSecretShape), or anything the log's redaction (with this machine's home folder and user
110
+ * name) would change. Then one of the ids it knows by their form (ID_FORMS, a link's), or no `:`,
111
+ * no long run of hex or digits, no key-like shape (keyIsSecret) and an id's strict shape
112
+ * (idShaped). The word as given, or undefined.
113
+ */
114
+ export declare function titleWord(word: string | undefined, redact?: Redaction): string | undefined;
115
+ /**
116
+ * Beta.27: a flag's value kept in a title, as typed (`--target 2027-03-31`, `--by @bao`,
117
+ * `--repos forge-ledger,forge-teller`). Beta.27 review: only for a flag of TITLE_VALUE_FLAGS;
118
+ * never a value with a `:` (a host's path, a user and password, a reference to a variable) or
119
+ * starting with `-` (the next flag, read as this one's value); a list (`a,b`) only when each of
120
+ * its items is a title's word (titleWord); one kept is cut to TITLE_VALUE_MAX.
121
+ */
122
+ export declare function titleValue(flag: string, value: string | undefined, redact?: Redaction): string | undefined;
123
+ /**
124
+ * The command words, ids and flag names of a run, and its title. Beta.27: with the flags'
125
+ * values (`values`, by flag name; a boolean flag has none), each kept when titleValue keeps it, so
126
+ * the title reads as the command was typed; beta.26 dropped them all ("--target --by"). Beta.27
127
+ * review: each word is a title's word (titleWord) or `…` (words dropped one after another are one
128
+ * `…`); the command line gives only the words a command declares (its words and its arguments'
129
+ * places, by the help), the rest as `…`. The words and values are redacted as the log is
130
+ * (`redact`: this machine's home folder and user name by default; a test gives its own).
131
+ */
132
+ export declare function runTitle(positionals: readonly string[], flags: readonly string[], values?: Readonly<Record<string, string | undefined>>, redact?: Redaction): {
68
133
  command: string[];
69
134
  title: string;
70
135
  };
136
+ /**
137
+ * Beta.27 re-review: the words an app's job is named by in the run log, by its kind (the
138
+ * server's job kinds). Never the job's own title, which may carry what a person typed.
139
+ */
140
+ export declare const APP_JOB_WORDS: Readonly<Record<string, string>>;
141
+ /**
142
+ * Beta.27 re-review: an app job's title in the run log, by the rules a command's title follows:
143
+ * its kind's words (APP_JOB_WORDS), then the ids it names (a repo, a change, a run), each kept
144
+ * when it is a title's word (titleWord: an id's strict shape, no secret's) and `…` otherwise.
145
+ * The app's titles (`Reconcile <diagram>`, `A question for <team>`, the words a request sent)
146
+ * went to the record as they were, past every rule a terminal's run is held to.
147
+ */
148
+ export declare function appRunTitle(kind: string, ids?: readonly string[], redact?: Redaction): {
149
+ title: string;
150
+ ids: string[];
151
+ };
152
+ /**
153
+ * Beta.27 re-review: whether a run log is kept at `root`: a metarepo (its org pack at the root
154
+ * or, adopted in place, in `.atticus/`) where ATTICUS_RUN_LOG isn't `off`. The command line and
155
+ * the app's jobs ask the same: `atticus ui` in a bare folder makes nothing there.
156
+ */
157
+ export declare function runLogKept(root: string, env?: NodeJS.ProcessEnv): boolean;
158
+ /** A metarepo, or a repo adopted in place: where Atticus keeps its logs (never a bare folder). */
159
+ export declare function isMetarepoRoot(root: string): boolean;
160
+ /** Beside the records: the first run of beta.27 re-titled the runs kept before it. */
161
+ export declare const RETITLED_MARK = ".retitled-beta27";
162
+ /** A record bigger than this is no record beta.26 wrote: left as it is, never read. */
163
+ export declare const RETITLE_MAX_BYTES: number;
164
+ /**
165
+ * Beta.27 review: beta.26 kept every word that looked like an id in a run's title and words, a
166
+ * key typed after `secret set` among them. The first command of beta.27 at a metarepo writes each
167
+ * record kept again with the title, words and flag names the new rules give (`retitle`, the
168
+ * command line's: it knows each command's arguments and options), and nothing else of it (its
169
+ * log, state and times stay); RETITLED_MARK says it was done. How many it wrote again or removed.
170
+ *
171
+ * Beta.27 re-review: a run of `secret` is removed, record and log (beta.26 printed a mistyped
172
+ * key back into its log). Only a regular file of at most RETITLE_MAX_BYTES is read (never a link,
173
+ * a FIFO or a folder), a record whose process is still running is left to it (and the mark
174
+ * waits, so the next command tries again; a run killed under beta.26 is titled again), a removal
175
+ * that fails is tried again the same way, so is a record that can't be read or parsed while it
176
+ * was written within 7 days of now, either way (half-written in place by a live run), and a record is written
177
+ * beside itself and put in place, never through a link. A folder that can't be written is left
178
+ * alone (nothing could change), and one whose mark can't be written isn't tried again by this
179
+ * process. Never throws: a record that can't be read or written is left as it is.
180
+ */
181
+ export declare function retitleTerminalRuns(root: string, retitle: (r: {
182
+ command: string[];
183
+ flags: string[];
184
+ }) => {
185
+ command: string[];
186
+ title: string;
187
+ flags?: string[];
188
+ }): number;
71
189
  /** Where the run was started, as its environment says. */
72
190
  export declare function startedByOf(env?: NodeJS.ProcessEnv): StartedBy;
73
191
  /**
@@ -75,7 +193,12 @@ export declare function startedByOf(env?: NodeJS.ProcessEnv): StartedBy;
75
193
  * one file read, no command run. Undefined elsewhere, or when it can't be read.
76
194
  */
77
195
  export declare function procStartOf(pid: number): string | undefined;
78
- /** A printed text as the lines the log keeps: no colour codes, no \r, each redacted and cut. */
196
+ /**
197
+ * A printed text as the lines the log keeps: no colour codes, no \r, each redacted and cut.
198
+ * Beta.27 re-review: a token by its shape alone (hasSecretShape: an access key id, a Git host's
199
+ * token, a JWT, a URL's password) is masked too, wherever it is on the line (an echoed path), for
200
+ * a terminal's run and an app's job alike.
201
+ */
79
202
  export declare function runLogLines(text: string, o?: {
80
203
  home?: string;
81
204
  user?: string;
@@ -85,11 +208,13 @@ export interface TerminalRunRecorder {
85
208
  /** Print a line (or several, split at newlines) to the run's log. */
86
209
  line(text: string): void;
87
210
  /** Record how it ended: 0 done, 130 or 143 (Ctrl+C, a stop) cancelled, else failed. */
88
- end(code: number, how?: "crash"): void;
211
+ end(code: number, how?: "crash" | "app-closed"): void;
89
212
  }
90
213
  export interface StartRunOptions {
91
214
  positionals: readonly string[];
92
215
  flags: readonly string[];
216
+ /** Beta.27: the flags' values, by name, for the title (runTitle keeps the safe ones). */
217
+ values?: Readonly<Record<string, string | undefined>>;
93
218
  env?: NodeJS.ProcessEnv;
94
219
  now?: () => Date;
95
220
  pid?: number;
@@ -110,12 +235,52 @@ export interface StartRunOptions {
110
235
  procStart?: () => string | undefined;
111
236
  /** Whether a process is there (pidAlive), for the runs pruned as this one starts. */
112
237
  alive?: (pid: number) => boolean;
238
+ /**
239
+ * Beta.27 review: a job the app started (startAppRun): its job, and `app` as where it started.
240
+ * Beta.27 re-review: titled by the rules a command's title follows (never the app's own words):
241
+ * by the command it runs (`command`: the positionals, flags and values given), else by its kind
242
+ * and the ids it names (appRunTitle).
243
+ */
244
+ app?: {
245
+ job: {
246
+ id: string;
247
+ kind: string;
248
+ };
249
+ ids?: readonly string[];
250
+ command?: true;
251
+ };
113
252
  }
114
253
  /**
115
254
  * Start a run's files. Undefined when they can't be written (the run goes on without them).
116
255
  * The caller checks `recordedCommand` first.
117
256
  */
118
257
  export declare function startTerminalRun(root: string, o: StartRunOptions): TerminalRunRecorder | undefined;
258
+ /**
259
+ * Beta.27 review: a job the app started, kept in the run log as a command run is (ADR 0187), so
260
+ * the Console, Runs and Problems still have it after the app restarts; it beats while it runs,
261
+ * so one left running by an app that crashed reads as ended. Beta.27 re-review: its title follows
262
+ * a command's rules: the command it runs (`command`, the words the command line's title rules
263
+ * kept: titleInputsOf), else its kind and the ids it names (`ids`, each checked: appRunTitle).
264
+ * The caller checks runLogKept first.
265
+ */
266
+ export declare function startAppRun(root: string, o: {
267
+ job: {
268
+ id: string;
269
+ kind: string;
270
+ };
271
+ ids?: readonly string[];
272
+ command?: {
273
+ positionals: string[];
274
+ flags: string[];
275
+ values?: Readonly<Record<string, string | undefined>>;
276
+ };
277
+ now?: () => Date;
278
+ redact?: {
279
+ home?: string;
280
+ user?: string;
281
+ };
282
+ heartbeatMs?: number;
283
+ }): TerminalRunRecorder | undefined;
119
284
  /** Whether a process is there: signal 0 asks without sending anything. */
120
285
  export declare function pidAlive(pid: number): boolean;
121
286
  /**
@@ -163,3 +328,4 @@ export declare function tailTerminalRunLines(root: string, runId: string, at: Ru
163
328
  at: RunLogTail;
164
329
  more: boolean;
165
330
  } | undefined;
331
+ export {};