@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.
- package/npm/core/api.d.ts +2693 -336
- package/npm/core/facts-join.d.ts +73 -1
- package/npm/core/fs.d.ts +8 -0
- package/npm/core/index.d.ts +4 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +2 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +21 -3
- package/npm/core/metarepo.d.ts +8 -0
- package/npm/core/orgpack-defaults.d.ts +3 -1
- package/npm/core/printer.d.ts +4 -0
- package/npm/core/question-owners.d.ts +4 -0
- package/npm/core/question-roles.d.ts +64 -4
- package/npm/core/questions.d.ts +14 -3
- package/npm/core/roles-migrate.d.ts +4 -3
- package/npm/core/run-log.d.ts +165 -0
- package/npm/core/schema/fact-corrections.d.ts +5 -0
- package/npm/core/schema/orgpack.d.ts +22 -6
- package/npm/core/schema/question.d.ts +55 -2
- package/npm/core/schema/scan-verify.d.ts +35 -0
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/index.js +1043 -43
- package/package.json +1 -1
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -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">
|
|
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
|
package/npm/core/index.d.ts
CHANGED
|
@@ -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;
|
package/npm/core/light.d.ts
CHANGED
|
@@ -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
|
-
}
|
|
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,
|
|
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;
|
package/npm/core/metarepo.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
10
|
-
|
|
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
|
-
|
|
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 {};
|
package/npm/core/questions.d.ts
CHANGED
|
@@ -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 (
|
|
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
|
|
3
|
-
*
|
|
4
|
-
*
|
|
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
|