@maycombhq/sdk 2.0.0-beta.22 → 2.0.0-beta.23

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.
@@ -41,6 +41,14 @@ import type { Fact, FactOf } from "./schema/facts.js";
41
41
  * gateway-walk): without it a call is joined to the route it lands on, and each route's
42
42
  * forwarding call to its service on its own, so the chain is there in two links, not one.
43
43
  *
44
+ * The path suffix (an Apigee proxy to its service): a forwarding call cited in a bundle whose
45
+ * path no entry serves in the same shape is joined per route of its proxy (the route it is from,
46
+ * else the proxy's flows, else its `<BasePath>/**`) at the target's path with the route's suffix
47
+ * after it (none when `target.copy.pathsuffix` is false; everything under it for a pass-through),
48
+ * matched against the service's entries with its base path taken off: the manifest's, an
49
+ * exposure's, its context and servlet path settings, else the longest overlap, a guess
50
+ * (`joined-by-path-overlap`). Each such join cites the route (`forRoute`) and the base (`base`).
51
+ *
44
52
  * Placeholders (J0): a base URL, host or topic written as `${X}`, `${X:default}` or `env:X` is
45
53
  * each value the config facts setting `X` give it, read in the caller's repo and in any repo of
46
54
  * the estate whose setting is for the caller's component (its folder, its deployment, its
@@ -115,6 +123,27 @@ export interface GatewayHop {
115
123
  scopes?: string[];
116
124
  /** Which side this gateway faces, when the manifest or the proxy's virtual host says. */
117
125
  facing?: GatewayFacing;
126
+ /** The base path the service behind this hop serves under, as `FactJoin.base`. */
127
+ base?: JoinBase;
128
+ }
129
+ /**
130
+ * The base path a service's entries sit under that the join took off the path an Apigee proxy
131
+ * forwards before matching them (the path suffix): the manifest's `basePath`, an exposure's
132
+ * (`deploy`: an OpenShift Route's or an Ingress's path), the service's own context path and
133
+ * servlet path settings (`config`), or, with none of those, the longest run of the target's path
134
+ * that starts the entry's (`overlap`, a guess: `joined-by-path-overlap`). `by` is the facts it
135
+ * came from (none for the manifest or an overlap).
136
+ */
137
+ export interface JoinBase {
138
+ path: string;
139
+ /**
140
+ * `url`: nothing names the base, and one route's whole URL (the target's path and the flow's
141
+ * suffix) ends in exactly one entry's whole path, at least one of the target's own segments
142
+ * included: code at both ends, not a guess. `overlap` is that for a pass-through (every entry
143
+ * under a guessed base), a guess.
144
+ */
145
+ from: "manifest" | "deploy" | "config" | "url" | "overlap";
146
+ by?: FactEnd[];
118
147
  }
119
148
  /** One end of a join: a fact, its repo and component, and the line it cites. */
120
149
  export interface FactEnd {
@@ -197,6 +226,16 @@ export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
197
226
  export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
198
227
  /** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
199
228
  export declare const JOINED_BY_PERSON = "joined-by-person";
229
+ /**
230
+ * An Apigee proxy's forwarding call matched the service's entry only by taking off the front of
231
+ * the target's path that nothing names as the service's base path (no manifest `basePath`, no
232
+ * Route or Ingress path, no context path setting): `/forge-limits/v3/limits` and the suffix
233
+ * `/check` against `/limits/check`. A guess, so the link is inferred; the Interface's flag only,
234
+ * not one of `JOIN_GUESS_FLAGS` (the local API's guesses), and its how is the host's.
235
+ */
236
+ export declare const JOINED_BY_PATH_OVERLAP = "joined-by-path-overlap";
237
+ /** How many entries a `<BasePath>/**` pass-through links to at most, in path order. */
238
+ export declare const MAX_PASS_THROUGH_LINKS = 50;
200
239
  /**
201
240
  * ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
202
241
  * run without a person. A how, never a person's word: the Interface is inferred, its evidence is
@@ -304,6 +343,20 @@ export interface FactJoin {
304
343
  aiHop?: JoinAi & {
305
344
  call: FactEnd;
306
345
  };
346
+ /**
347
+ * An Apigee proxy's forwarding call (the path suffix): the proxy's route whose requests it
348
+ * carries, when the path the target receives is the target's path and this route's suffix (or,
349
+ * for a `<BasePath>/**` pass-through, everything under the target's path). A call that serves
350
+ * several routes has a join per route.
351
+ */
352
+ forRoute?: FactEnd;
353
+ /** The service's base path the join took off before matching its entry (the path suffix). */
354
+ base?: JoinBase;
355
+ /**
356
+ * The setting that keeps the proxy's path suffix off (`target.copy.pathsuffix` false, in a
357
+ * JavaScript or AssignMessage policy), so the target receives its own path as it is.
358
+ */
359
+ suffixOff?: FactEnd;
307
360
  }
308
361
  /** ADR 0181: the AI run a decision came from. */
309
362
  export interface JoinAi {
@@ -547,8 +600,23 @@ export declare function basePathOf(e: Entry): string;
547
600
  * by a Service's short name (J1). Empty for a join nobody had to guess.
548
601
  */
549
602
  export declare function joinGuessesOf(j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">): JoinGuessFlag[];
603
+ /**
604
+ * Whether an Apigee forwarding call on the way matched its entry only by a guessed base path
605
+ * (`joined-by-path-overlap`): the join's own, or a gateway hop's.
606
+ */
607
+ export declare const isOverlapJoin: (j: {
608
+ base?: JoinBase | undefined;
609
+ gateway?: readonly {
610
+ base?: JoinBase | undefined;
611
+ }[] | undefined;
612
+ }) => boolean;
550
613
  /** Whether a join guessed its callee anywhere on the way (`joinGuessesOf` gives how). */
551
- export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses">) => boolean;
614
+ export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" | "guesses"> & {
615
+ base?: JoinBase | undefined;
616
+ gateway?: readonly {
617
+ base?: JoinBase | undefined;
618
+ }[] | undefined;
619
+ }) => boolean;
552
620
  /**
553
621
  * How a join found its callee, as its Interface's flags (C1, ADR 0135): a guess by its own F2
554
622
  * flags alone (`JOIN_GUESS_FLAGS`: by path or label, F2; by a platform setting or a folder name,
@@ -562,6 +630,10 @@ export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
562
630
  export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
563
631
  aiAnswer?: JoinAi | undefined;
564
632
  aiHop?: JoinAi | undefined;
633
+ base?: JoinBase | undefined;
634
+ gateway?: readonly {
635
+ base?: JoinBase | undefined;
636
+ }[] | undefined;
565
637
  }): string[];
566
638
  /**
567
639
  * A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
package/npm/core/fs.d.ts CHANGED
@@ -53,6 +53,13 @@ o?: {
53
53
  }>;
54
54
  /** The lock file beside a file two processes write (`<file>.lock`): no facts-folder reader takes it for a file of its own. */
55
55
  export declare const sharedLockFileOf: (path: string) => string;
56
+ /**
57
+ * Review of beta.23: the options of a lock that guards only a quick write (a stage's loop file,
58
+ * its thread, the stories' numbers): older than two minutes, it is stale whoever holds it.
59
+ */
60
+ export declare const QUICK_WRITE_LOCK: {
61
+ readonly maxAgeMs: 120000;
62
+ };
56
63
  /**
57
64
  * Review round 46: run `work` holding a file that another process may append to or rewrite at
58
65
  * the same time (a repo's corrections: the app server appends, a CLI command rewrites it), so a
@@ -67,6 +74,7 @@ export declare function withSharedFileLock<T>(path: string, work: () => Promise<
67
74
  staleMs?: number;
68
75
  waitMs?: number;
69
76
  what?: string;
77
+ maxAgeMs?: number;
70
78
  }): Promise<T>;
71
79
  /**
72
80
  * What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
@@ -58,7 +58,10 @@ export * from "./fs.js";
58
58
  export * from "./glob.js";
59
59
  export * from "./repo-files.js";
60
60
  export * from "./record-cache.js";
61
+ export * from "./kept-files.js";
61
62
  export * from "./log.js";
63
+ export * from "./run-log.js";
64
+ export * from "./printer.js";
62
65
  export * from "./zip.js";
63
66
  export * from "./words.js";
64
67
  export * from "./zip-read.js";
@@ -75,6 +78,7 @@ export * from "./question-roles.js";
75
78
  export * from "./question-proposals.js";
76
79
  export * from "./repo-description.js";
77
80
  export * from "./manifest-edit.js";
81
+ export * from "./setup-edit.js";
78
82
  export * from "./schema/spec.js";
79
83
  export * from "./specs.js";
80
84
  export * from "./cancel.js";
@@ -0,0 +1,17 @@
1
+ /** While `isQuiet()` says so, files checked since the last change aren't checked again; none to stop. */
2
+ export declare function trustKeptFiles(isQuiet?: () => boolean): void;
3
+ /**
4
+ * A file may have changed: each kept file is checked again when next asked; with `path` (a
5
+ * file or a folder), only those at or under it.
6
+ */
7
+ export declare function keptFilesMayHaveChanged(path?: string): void;
8
+ /**
9
+ * What `parse` makes of the file's text, from the last read while the file is unchanged.
10
+ * Undefined when there is no such file. A parse that throws is not kept: the error goes to the
11
+ * caller, as a fresh read's would.
12
+ */
13
+ export declare function keptParse<T>(path: string, kind: string, parse: (text: string) => T, o?: {
14
+ copy?: boolean;
15
+ }): Promise<T | undefined>;
16
+ /** For tests: forget every file kept. */
17
+ export declare function forgetKeptFiles(): void;
@@ -6,3 +6,5 @@
6
6
  */
7
7
  export { SCHEMA_VERSION } from "./schema/version.js";
8
8
  export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
9
+ export { recordedCommand, startTerminalRun, type TerminalRunRecorder } from "./run-log.js";
10
+ export { printToCurrent, withPrinter } from "./printer.js";
package/npm/core/log.d.ts CHANGED
@@ -45,5 +45,7 @@ export declare function createLog(root: string, o?: {
45
45
  maxBytes?: number;
46
46
  keep?: number;
47
47
  }): Log;
48
+ /** ensureLocalIgnore, for the log's synchronous writes (and a terminal run's, ADR 0187). */
49
+ export declare function ignoreLocalSync(root: string): void;
48
50
  /** A log that writes nothing (tests, and commands run with no metarepo). */
49
51
  export declare const NO_LOG: Log;
@@ -28,7 +28,9 @@ export declare function setManifestDescription(root: string, repo: string, descr
28
28
  * are in. The entry is written with the fields that are set and no more, and the whole manifest
29
29
  * is checked before it is written, so a duplicate id or a password in the URL is refused here.
30
30
  */
31
- export declare function addManifestRepo(root: string, platform: string, entry: {
31
+ export declare function addManifestRepo(root: string, platform: string, entry: NewManifestRepo): Promise<ManifestFile>;
32
+ /** One repo to add to a manifest: the fields that are set, and no more. */
33
+ export interface NewManifestRepo {
32
34
  id: string;
33
35
  url: string;
34
36
  type: string;
@@ -38,7 +40,21 @@ export declare function addManifestRepo(root: string, platform: string, entry: {
38
40
  system?: string;
39
41
  component?: string;
40
42
  description?: RepoDescription;
41
- }): Promise<ManifestFile>;
43
+ }
44
+ /**
45
+ * ADR 0190: many repos into a platform's manifest at once (the app's paste of ~40 clone URLs),
46
+ * as addManifestRepo adds one: appended in order, comments and order kept, the file's own line
47
+ * endings, the whole manifest checked before anything is written. An id another manifest (or
48
+ * an earlier entry of the batch) lists is refused, naming it. With `preview`, nothing is
49
+ * written: the lines it would change come back, for the app's diff before the write.
50
+ */
51
+ export declare function addManifestRepos(root: string, platform: string, entries: readonly NewManifestRepo[], o?: {
52
+ preview?: boolean;
53
+ }): Promise<{
54
+ file: ManifestFile;
55
+ changes: LineChange[];
56
+ written: boolean;
57
+ }>;
42
58
  /**
43
59
  * F5: move a repo's id in the manifest that lists it, in place (comments and order kept). Refused
44
60
  * when no manifest lists the repo, or any lists the new id already (ids are unique across every
@@ -74,7 +90,9 @@ export declare function changedLines(before: string, after: string): LineChange[
74
90
  * file's comments and order; checked before it is written. With `preview`, nothing is written:
75
91
  * the lines it would change come back.
76
92
  */
77
- export declare function setManifestField(root: string, repo: string, field: "owner" | "system", value: string, o?: {
93
+ export declare function setManifestField(root: string, repo: string,
94
+ /** ADR 0190: `type` too, from the app's Detect the type (atticus repo-type detect). */
95
+ field: "owner" | "system" | "type", value: string, o?: {
78
96
  preview?: boolean;
79
97
  }): Promise<{
80
98
  file: ManifestFile;
@@ -88,6 +88,14 @@ export declare function layoutOf(root: string): {
88
88
  };
89
89
  /** The catalog folder (holding generated/ and curated/). */
90
90
  export declare function catalogDirOf(root: string): string;
91
+ /**
92
+ * Whether a changed file (root-relative, "/"-separated, as the server's live events name it) can
93
+ * change the catalog: a file in the catalog folder the layout names, that folder or one above it
94
+ * (the watcher names top folders when many files change), or the org pack, whose sources.yaml
95
+ * says where the catalog is. The server reads the catalog again only then, and tags each
96
+ * `file.changed` event with it (`catalog`), so a page follows the layout too.
97
+ */
98
+ export declare function catalogMayHaveChangedAt(root: string, path: string): boolean;
91
99
  /**
92
100
  * Where OpenSpec keeps changes, relative to the root with forward slashes: `changes/` under
93
101
  * `layout.openspec` (`openspec/changes` by default, `.atticus/openspec/changes` in a repo
@@ -30,11 +30,12 @@ export declare const DEFAULT_GATES: {
30
30
  }[];
31
31
  };
32
32
  export declare const DEFAULT_ROLES: {
33
- schemaVersion: 1 | 2;
33
+ schemaVersion: 1 | 2 | 3;
34
34
  teams: {
35
35
  id: string;
36
36
  people: string[];
37
37
  name?: string | undefined;
38
+ roles?: Record<string, string[]> | undefined;
38
39
  }[];
39
40
  custom: {
40
41
  id: string;
@@ -55,6 +56,7 @@ export declare const DEFAULT_ROLES: {
55
56
  actions: [string, string];
56
57
  reason: string;
57
58
  }[];
59
+ defaults?: Record<string, string[]> | undefined;
58
60
  };
59
61
  export declare const DEFAULT_RUNTIME: {
60
62
  schemaVersion: 1 | 2 | 3 | 4;
@@ -0,0 +1,4 @@
1
+ /** Run `work` with every line printed inside it (at any depth, across awaits) going to `print`. */
2
+ export declare function withPrinter<T>(print: (line: string) => void, work: () => T): T;
3
+ /** Print a line to the job this code runs in, if any. */
4
+ export declare function printToCurrent(line: string): void;
@@ -17,8 +17,12 @@ export type QuestionOwner = {
17
17
  /** The teams roles.yaml names, and why they couldn't be read when they couldn't. */
18
18
  export declare function readTeams(root: string): Promise<{
19
19
  teams: Team[];
20
+ /** Version 3 (ADR 0191): the organisation's person for each role, when no team names one. */
21
+ defaults?: Record<string, string[]>;
20
22
  problem?: string;
21
23
  }>;
24
+ /** A handle as compared: no leading @, lower case (Git hosts' handles are case-insensitive). */
25
+ export declare const handleKey: (h: string) => string;
22
26
  /** The teams a person is on, by their Git handle. */
23
27
  export declare function teamsOfPerson(handle: string, teams: readonly Team[]): Team[];
24
28
  /**
@@ -1,15 +1,74 @@
1
1
  import { BUILT_IN_ROLES } from "./schema/orgpack.js";
2
- import { type Question, type QuestionRole } from "./schema/question.js";
2
+ import { type Question, type QuestionAsks, type QuestionRole } from "./schema/question.js";
3
3
  /**
4
4
  * The role that owns what a step asks: the stage's own for a change's stage (`change-feature`,
5
5
  * `change-stories`, a task's run), else, for a step that serves every stage (a context gap, a
6
6
  * knowledge conflict), the stage its rerun command names. Undefined outside a change's phases.
7
7
  */
8
8
  export declare function roleOfStep(step: string, rerun?: string): QuestionRole | undefined;
9
- /** A question's role: its own (version 5), else derived from the step that asked and its rerun. */
10
- export declare function roleOfQuestion(q: Pick<Question, "askedBy" | "rerun"> & {
9
+ /**
10
+ * ADR 0191: the role that owns what a question asks. Design is the architect's and delivery the
11
+ * tech lead's, whichever stage asked. Business is the product owner's, or the business analyst's
12
+ * once the stories are being written (a question the stories or tasks stage raises about what the
13
+ * change must do is the analyst's to answer at that level).
14
+ */
15
+ export declare function roleOfAsks(asks: QuestionAsks, stageRole?: QuestionRole): QuestionRole;
16
+ /** ADR 0191: what a role's questions ask, for a question that has no `asks` of its own. */
17
+ export declare function asksOfRole(role: QuestionRole): QuestionAsks;
18
+ type RoutedQuestion = Pick<Question, "askedBy" | "rerun"> & {
11
19
  role?: QuestionRole | undefined;
12
- }): QuestionRole | undefined;
20
+ asks?: QuestionAsks | undefined;
21
+ };
22
+ /**
23
+ * A question's role: a person's re-routing or the one it was raised with (versions 5 and 6), else
24
+ * what it asks (version 6), else derived from the step that asked and its rerun.
25
+ */
26
+ export declare function roleOfQuestion(q: RoutedQuestion): QuestionRole | undefined;
27
+ /** What a question asks: its own tag (version 6), else its role's level; undefined with neither. */
28
+ export declare function asksOfQuestion(q: RoutedQuestion): QuestionAsks | undefined;
29
+ /**
30
+ * ADR 0191: what a critic finding asks of people, by the same three levels, so a product owner's
31
+ * Home shows only the business ones (the audit: running the critic from the brief made findings
32
+ * about circuit breakers and alerts, and Home showed the product owner a change blocked by them).
33
+ * A finding on the design's files is design; on tasks.md, the build or the release, delivery; one
34
+ * on the brief, the proposal, the UX or the stories is business unless its rule, lens or words are
35
+ * about how the estate does it (resilience, timeouts, alerts, interfaces). On the brief, only the
36
+ * architecture lens or words no business sentence uses (a timeout, a retry, a circuit breaker)
37
+ * make it design: an alert, a queue or an interface there may be the business's own.
38
+ */
39
+ export declare function asksOfFinding(f: {
40
+ artifact: string;
41
+ rule?: string | undefined;
42
+ lens?: string | undefined;
43
+ summary?: string | undefined;
44
+ }): QuestionAsks;
45
+ /**
46
+ * ADR 0191: the levels a change's phase is decided at. In Define only the business level holds
47
+ * the change (a design finding waits for the architect); in Design, business and design; from
48
+ * Plan on, all three.
49
+ */
50
+ export declare function asksOfPhase(state: string): QuestionAsks[];
51
+ /** The change.yaml owner key of each phase's role, in the order a change goes. */
52
+ export declare const OWNER_OF_ROLE: Readonly<Record<QuestionRole, string>>;
53
+ /**
54
+ * ADR 0191: whose turn a phase's hand-off is: the next role's owner key (define → the architect,
55
+ * design → the business analyst, plan → the tech lead), so the hand-off names its
56
+ * reviewers and At a glance says who it waits on.
57
+ */
58
+ export declare function nextOwnerOf(phase: string): string | undefined;
59
+ /** The people a phase's hand-off waits on: the next role's owners on the change (handles, no @). */
60
+ export declare function nextOwnersOf(phase: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): {
61
+ role: string;
62
+ people: string[];
63
+ } | undefined;
64
+ /**
65
+ * ADR 0191 review: the people a built-in owner key names on a change, its keys read as
66
+ * rolesOfPerson reads them: any case, the words people write for it (`tech-lead`, `developer`
67
+ * and `delivery-lead` for the team lead), or a custom role of roles.yaml based on it, the key
68
+ * itself first. Another built-in role (a security reviewer beside the architect) is its own.
69
+ * Handles, no @, once each as handles compare; a team (`forge/platform`) is not a person.
70
+ */
71
+ export declare function ownersOfRole(key: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): string[];
13
72
  /** A custom role of roles.yaml (`custom`): its id and the built-in role it is based on. */
14
73
  export interface CustomRole {
15
74
  id: string;
@@ -22,3 +81,4 @@ export declare function roleOfOwner(key: string, custom?: readonly CustomRole[])
22
81
  * question role, once each, in the order of the phases.
23
82
  */
24
83
  export declare function rolesOfPerson(handle: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): QuestionRole[];
84
+ export {};
@@ -1,5 +1,5 @@
1
1
  import { type JudgmentStore } from "./judgments.js";
2
- import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
2
+ import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionRole, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
3
3
  /**
4
4
  * Questions as files (ADR 0078): raise, list, read and answer questions/<id>.yaml. The CLI
5
5
  * (atticus questions) and the local API (/api/questions) both call these, so the app and the
@@ -47,6 +47,17 @@ export interface AskedBy {
47
47
  }
48
48
  /** An open question from what an AI step raised. */
49
49
  export declare function questionFromDraft(d: QuestionDraft, by: AskedBy): Question;
50
+ /**
51
+ * ADR 0191: a person re-routes a question to another role (a business question the architect was
52
+ * given goes to the product owner). `role` becomes the new one and `routed` says from which, by
53
+ * whom and when; what it asks follows the role unless the AI tagged it. Open or answered alike:
54
+ * the answer, if any, stays. Written only if the file is as it was read.
55
+ */
56
+ export declare function routeQuestion(root: string, id: string, o: {
57
+ role: QuestionRole;
58
+ by: string;
59
+ at: string;
60
+ }): Promise<Question>;
50
61
  /**
51
62
  * Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
52
63
  * is a question they answered as they asked it). Every other writer goes through
@@ -227,8 +238,8 @@ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by
227
238
  }>;
228
239
  /**
229
240
  * Rewrite questions/<id>.yaml files written at an older question schema version (1, ADR 0078;
230
- * 2, ADR 0117) at the current one (3, ADR 0153): only the version changes, since what each
231
- * version adds is optional. Returns the files, relative to the root; with dryRun, the files it
241
+ * 2, ADR 0117; 3, ADR 0153; 4, ADR 0162; 5, ADR 0181) at the current one (6, ADR 0191): only the
242
+ * version changes, since what each version adds is optional. Returns the files, relative to the root; with dryRun, the files it
232
243
  * would rewrite.
233
244
  */
234
245
  export declare function migrateQuestions(root: string, o?: {
@@ -1,7 +1,8 @@
1
1
  /**
2
- * roles.yaml version 1 → 2 (ADR 0140). Version 2 adds `teams`; a file without them names no
3
- * team, as version 1 did, so the step writes the new number only and keeps the file's comments,
4
- * order and line layout (`atticus upgrade`'s roles-v2).
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).
5
6
  */
6
7
  export declare function migrateRolesText(text: string): {
7
8
  text: string;
@@ -0,0 +1,165 @@
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: 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
12
+ * started, and how it ended (its exit code), written again when it ends. While it runs it is
13
+ * written again every RUN_HEARTBEAT_MS (`beatAt`), and on Linux it keeps when its process
14
+ * started (`procStart`, from /proc): a process id used again by another process, or a run
15
+ * silent past RUN_SILENT_MS, is a run that ended without saying.
16
+ *
17
+ * Only the last RUN_LOG_KEEP runs are kept. `.atticus/logs/` is this machine's own (never
18
+ * committed). The names have no `:` (Windows). Nothing here loads a schema: the command line
19
+ * starts a run before it knows anything else. Writing never throws: a run log that can't be
20
+ * written is skipped, never failing the command it describes.
21
+ */
22
+ export declare const RUN_LOG_KEEP = 50;
23
+ export declare const RUN_LOG_MAX_BYTES: number;
24
+ /** A line longer than this is cut (a minified file printed whole). */
25
+ export declare const RUN_LOG_LINE_MAX = 4000;
26
+ /** The lines a read gives at most. */
27
+ export declare const RUN_LOG_READ_MAX = 5000;
28
+ /** A running command writes its record again this often. */
29
+ export declare const RUN_HEARTBEAT_MS = 30000;
30
+ /** A running record that beats, silent (record and log) for longer than this, has ended. */
31
+ export declare const RUN_SILENT_MS: number;
32
+ /** `20261109-101530-4242-ab12`: when (UTC), the process, and a little randomness. */
33
+ export declare const TERMINAL_RUN_ID: RegExp;
34
+ export declare const runLogsDirOf: (root: string) => string;
35
+ export declare const runningDirOf: (root: string) => string;
36
+ export type StartedBy = "terminal" | "vscode" | "intellij" | "copilot";
37
+ export type TerminalRunState = "running" | "done" | "failed" | "cancelled";
38
+ export interface TerminalRunRecord {
39
+ schemaVersion: 1;
40
+ runId: string;
41
+ pid: number;
42
+ /** A hash of the machine's name: whether the process can be looked for here. */
43
+ host: string;
44
+ title: string;
45
+ command: string[];
46
+ flags: string[];
47
+ startedBy: StartedBy;
48
+ startedAt: string;
49
+ state: TerminalRunState;
50
+ finishedAt?: string;
51
+ exitCode?: number;
52
+ /** Lines printed so far (as of the last write of the record; the log has them all). */
53
+ lines: number;
54
+ /** Lines no longer in the log (the log keeps its last lines). */
55
+ dropped: number;
56
+ /** When the process started, as the system says (Linux: /proc), to tell a reused pid. */
57
+ procStart?: string;
58
+ /** When a running command last wrote its record (every RUN_HEARTBEAT_MS). */
59
+ beatAt?: string;
60
+ }
61
+ /** A record as read: `stale` when its process is gone though it never said it ended. */
62
+ export type TerminalRunView = TerminalRunRecord & {
63
+ stale?: true;
64
+ };
65
+ 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[]): {
68
+ command: string[];
69
+ title: string;
70
+ };
71
+ /** Where the run was started, as its environment says. */
72
+ export declare function startedByOf(env?: NodeJS.ProcessEnv): StartedBy;
73
+ /**
74
+ * When a process started, as Linux keeps it (/proc/<pid>/stat's starttime, in ticks since boot):
75
+ * one file read, no command run. Undefined elsewhere, or when it can't be read.
76
+ */
77
+ 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. */
79
+ export declare function runLogLines(text: string, o?: {
80
+ home?: string;
81
+ user?: string;
82
+ }): string[];
83
+ export interface TerminalRunRecorder {
84
+ readonly runId: string;
85
+ /** Print a line (or several, split at newlines) to the run's log. */
86
+ line(text: string): void;
87
+ /** Record how it ended: 0 done, 130 or 143 (Ctrl+C, a stop) cancelled, else failed. */
88
+ end(code: number, how?: "crash"): void;
89
+ }
90
+ export interface StartRunOptions {
91
+ positionals: readonly string[];
92
+ flags: readonly string[];
93
+ env?: NodeJS.ProcessEnv;
94
+ now?: () => Date;
95
+ pid?: number;
96
+ keep?: number;
97
+ maxBytes?: number;
98
+ redact?: {
99
+ home?: string;
100
+ user?: string;
101
+ };
102
+ /**
103
+ * Record the end on the process's exit, Ctrl+C and SIGTERM too, when nothing else did (the
104
+ * command line passes true; a test doesn't).
105
+ */
106
+ hookProcess?: boolean;
107
+ /** Write the record again this often while it runs. Default RUN_HEARTBEAT_MS with hookProcess. */
108
+ heartbeatMs?: number;
109
+ /** When this process started (procStartOf, for its own pid only). */
110
+ procStart?: () => string | undefined;
111
+ /** Whether a process is there (pidAlive), for the runs pruned as this one starts. */
112
+ alive?: (pid: number) => boolean;
113
+ }
114
+ /**
115
+ * Start a run's files. Undefined when they can't be written (the run goes on without them).
116
+ * The caller checks `recordedCommand` first.
117
+ */
118
+ export declare function startTerminalRun(root: string, o: StartRunOptions): TerminalRunRecorder | undefined;
119
+ /** Whether a process is there: signal 0 asks without sending anything. */
120
+ export declare function pidAlive(pid: number): boolean;
121
+ /**
122
+ * The runs kept, newest first. A run still `running` whose process is gone on this machine (or
123
+ * that started days ago elsewhere) is `stale`: it ended without saying (closed terminal, a crash).
124
+ */
125
+ export declare function readTerminalRuns(root: string, o?: {
126
+ alive?: (pid: number) => boolean;
127
+ now?: () => Date;
128
+ /** When a process started (procStartOf). */
129
+ startOf?: (pid: number) => string | undefined;
130
+ }): TerminalRunView[];
131
+ /** One run as read now, or undefined. */
132
+ export declare const readTerminalRun: (root: string, runId: string, o?: {
133
+ alive?: (pid: number) => boolean;
134
+ now?: () => Date;
135
+ startOf?: (pid: number) => string | undefined;
136
+ }) => TerminalRunView | undefined;
137
+ /**
138
+ * A run's lines from a line on (`from`, counted from its first line ever), at most `max`; without
139
+ * `from`, its last `max`. `total` is how many it has printed. Undefined for no such run.
140
+ */
141
+ export declare function readTerminalRunLines(root: string, runId: string, from?: number, max?: number): {
142
+ from: number;
143
+ lines: string[];
144
+ total: number;
145
+ } | undefined;
146
+ /** Where a tail of a run's log has read to: the next line's number and its byte in the file. */
147
+ export interface RunLogTail {
148
+ line: number;
149
+ bytes: number;
150
+ /** The record's dropped count and the file (its inode) when read: either changing is a cut. */
151
+ dropped: number;
152
+ ino: number;
153
+ }
154
+ /**
155
+ * A run's new lines since `at` (where the last tail read to), at most `max`: only the bytes
156
+ * added are read. Without `at`, or when the log was cut meanwhile, the whole log is read once:
157
+ * its last `max` lines without `at`, else from `at.line` (or the first line kept, when those were
158
+ * dropped). `more` says lines past `max` wait for the next read. Undefined for no such run.
159
+ */
160
+ export declare function tailTerminalRunLines(root: string, runId: string, at: RunLogTail | undefined, max?: number): {
161
+ from: number;
162
+ lines: string[];
163
+ at: RunLogTail;
164
+ more: boolean;
165
+ } | undefined;
@@ -128,6 +128,11 @@ type CallLike = {
128
128
  value: string;
129
129
  };
130
130
  };
131
+ /**
132
+ * Review round 2 (beta.23): a person's newest edit of where a call goes (an `edit` setting `to`,
133
+ * not the AI's), or none.
134
+ */
135
+ export declare function personEditOfTo(f: CallLike, corrections: readonly FactCorrection[]): FactCorrection | undefined;
131
136
  /**
132
137
  * G1 (ADR 0174): every pairing (`link`) that meets a call, newest first: on its cited line by its
133
138
  * id or by what it cites, or by its id where an edit of the same fact moved it to the line it is