@maycombhq/sdk 2.0.0-beta.28 → 2.0.0-beta.28.2
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 +235 -1
- package/npm/core/cancel.d.ts +7 -0
- package/npm/core/declared-links.d.ts +33 -0
- package/npm/core/facts-join.d.ts +14 -0
- package/npm/core/file-pool.d.ts +59 -0
- package/npm/core/fs.d.ts +24 -1
- package/npm/core/index.d.ts +1 -0
- package/npm/core/link-candidates.d.ts +50 -1
- package/npm/core/printer.d.ts +16 -2
- package/npm/core/record-cache.d.ts +94 -0
- package/npm/index.js +113 -14
- package/package.json +1 -1
package/npm/core/api.d.ts
CHANGED
|
@@ -576,8 +576,53 @@ import { z } from "zod";
|
|
|
576
576
|
* `problems` by place, nothing written), writes them, then builds once, as one local job whose
|
|
577
577
|
* result is `MapEditsResult` (with the caller repos they touch). A problem may carry
|
|
578
578
|
* `problems`. Additive only.
|
|
579
|
+
* 3.14.0 (beta.28.1, "nothing slow runs silently"): the Connect panel's read and its preview as
|
|
580
|
+
* jobs. GET /api/links/candidates with `job=1` and POST /api/links/connect with `job: true`
|
|
581
|
+
* answer 202 JobAccepted at once; the job prints each step (its progress message is the last
|
|
582
|
+
* line it said), Stop (POST /api/jobs/{jobId}/cancel) ends it between steps, and its result's
|
|
583
|
+
* `answer` is the answer the request gives without `job` (or `problem`, refused). Without
|
|
584
|
+
* `job`, both answer as before. GET /api/facts/{repo}/preview takes `job=1` the same way (the
|
|
585
|
+
* panel after a correction). Additive only.
|
|
586
|
+
* Also in 3.14.0 (beta.28.1, field report 4): connecting two boxes never dead-ends. GET
|
|
587
|
+
* /api/links/candidates lists every call of A: one that has an arrow drawn is `joined` (with
|
|
588
|
+
* `joins`, the box it goes to), to move from the same panel; one the join ties to something no
|
|
589
|
+
* arrow is drawn for is `undrawn`, as loose as one that joins nothing; one placed outside to a
|
|
590
|
+
* target no box draws is listed `outside` with `joins`, where before it was left out; one with
|
|
591
|
+
* an arrow to this very box is `here` (`now`, its API: a pairing with that API is refused,
|
|
592
|
+
* 409); one a person paired with the box it goes to says who (`pairedBy`). POST
|
|
593
|
+
* /api/declared-links (and Edit the map's adds) from a box no System of the profiles is (a repo
|
|
594
|
+
* the manifest lists with no System) adds that System to the repo's profile first, and says so
|
|
595
|
+
* (`created`), and Undo of its last declaration takes that System away again (`removed`).
|
|
596
|
+
* Additive only.
|
|
597
|
+
* Also in 3.14.0 (beta.28.1, field report 5): Apply (POST /api/facts/{repo}/apply) writes the kept facts
|
|
598
|
+
* with the rejected ones left out (`verify --write` exit 3): its job ends done, code 0, and
|
|
599
|
+
* its result (`FactsApplyResult`) carries `leftOut`, how many facts were left out, beside the
|
|
600
|
+
* lines naming each with the file to fix it in. Additive only. Apply to every repo (POST
|
|
601
|
+
* /api/facts/apply-all) the same: a repo that wrote with facts left out is applied, and its
|
|
602
|
+
* result carries `leftOut` (all repos) and `leftOutRepos` (how many repos left some out).
|
|
603
|
+
* 3.15.0 (beta.28.2, ADR 0197 "beta.28.1 and older reading version 2"): a refused build's
|
|
604
|
+
* `reasons` (BuildRefusalView: GET /api/build's `pending.refused` and `last.refused`, a scan's
|
|
605
|
+
* and an Apply's job result) may be `newer-atticus`: catalog/sources/build.json or a slot was
|
|
606
|
+
* written by a newer Atticus, at a version of its format this one doesn't read. Its `message`
|
|
607
|
+
* says so, its `command` is `npm i -g @maycombhq/atticus@beta`, and nothing was written; it is
|
|
608
|
+
* never `not-upgraded`. The Apply preview's `confirm.refused` may list it the same way. The
|
|
609
|
+
* upgrade job (POST /api/upgrade) refuses on such a catalog with the same words; GET
|
|
610
|
+
* /api/upgrade then lists no `pending` step and says why in `newerCatalog`, and GET
|
|
611
|
+
* /api/build/undo offers no `plan` (its `problem` says why). Every route
|
|
612
|
+
* that writes one of the build's inputs (the build, scan, Apply, undo, prune, the upgrade, the
|
|
613
|
+
* map's edits and deletes, corrections, call corrections, pairings, declared links and boxes,
|
|
614
|
+
* answers, triage, the AI's decisions, the baseline, initiatives, an owner question's send,
|
|
615
|
+
* starting a run, the org pack's files, patterns, sources, adapters and AI settings, a file
|
|
616
|
+
* promoted into inputs/, repos and owners) answers 409 on such a catalog before it writes
|
|
617
|
+
* anything: a problem whose `refused` is `{ reasons: ["newer-atticus"], message, newer }`,
|
|
618
|
+
* `newer` (BuildRefusalView's, optional) naming each file a newer Atticus wrote with its
|
|
619
|
+
* version and the newest one this Atticus reads. Additive only.
|
|
620
|
+
* Also in 3.15.0 (ADR 0197 review): a `hand-edits` refusal may carry `unreadableManifest: true`,
|
|
621
|
+
* when catalog/sources/build.json is there but doesn't read (edited or merged by hand). Its
|
|
622
|
+
* `command` is the build again with `--discard-edits` of every record file, never the curate.
|
|
623
|
+
* Additive only.
|
|
579
624
|
*/
|
|
580
|
-
export declare const API_VERSION = "3.
|
|
625
|
+
export declare const API_VERSION = "3.15.0";
|
|
581
626
|
export declare const DEFAULT_PORT = 4321;
|
|
582
627
|
/** RFC 9457 problem details, used for every error. */
|
|
583
628
|
/**
|
|
@@ -3967,6 +4012,7 @@ export declare const BuildRefusalView: z.ZodObject<{
|
|
|
3967
4012
|
"large-removals": "large-removals";
|
|
3968
4013
|
"hand-edits": "hand-edits";
|
|
3969
4014
|
"not-upgraded": "not-upgraded";
|
|
4015
|
+
"newer-atticus": "newer-atticus";
|
|
3970
4016
|
}>>;
|
|
3971
4017
|
message: z.ZodString;
|
|
3972
4018
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4043,6 +4089,14 @@ export declare const BuildRefusalView: z.ZodObject<{
|
|
|
4043
4089
|
repo: z.ZodString;
|
|
4044
4090
|
why: z.ZodString;
|
|
4045
4091
|
}, z.core.$strip>>>;
|
|
4092
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4093
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4094
|
+
path: z.ZodString;
|
|
4095
|
+
name: z.ZodString;
|
|
4096
|
+
field: z.ZodString;
|
|
4097
|
+
version: z.ZodNumber;
|
|
4098
|
+
reads: z.ZodNumber;
|
|
4099
|
+
}, z.core.$strip>>>;
|
|
4046
4100
|
command: z.ZodString;
|
|
4047
4101
|
plan: z.ZodOptional<z.ZodString>;
|
|
4048
4102
|
}, z.core.$strip>;
|
|
@@ -4078,6 +4132,7 @@ export declare const BuildReportView: z.ZodObject<{
|
|
|
4078
4132
|
"large-removals": "large-removals";
|
|
4079
4133
|
"hand-edits": "hand-edits";
|
|
4080
4134
|
"not-upgraded": "not-upgraded";
|
|
4135
|
+
"newer-atticus": "newer-atticus";
|
|
4081
4136
|
}>>;
|
|
4082
4137
|
message: z.ZodString;
|
|
4083
4138
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4154,6 +4209,14 @@ export declare const BuildReportView: z.ZodObject<{
|
|
|
4154
4209
|
repo: z.ZodString;
|
|
4155
4210
|
why: z.ZodString;
|
|
4156
4211
|
}, z.core.$strip>>>;
|
|
4212
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4213
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4214
|
+
path: z.ZodString;
|
|
4215
|
+
name: z.ZodString;
|
|
4216
|
+
field: z.ZodString;
|
|
4217
|
+
version: z.ZodNumber;
|
|
4218
|
+
reads: z.ZodNumber;
|
|
4219
|
+
}, z.core.$strip>>>;
|
|
4157
4220
|
command: z.ZodString;
|
|
4158
4221
|
plan: z.ZodOptional<z.ZodString>;
|
|
4159
4222
|
}, z.core.$strip>>;
|
|
@@ -4292,6 +4355,7 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4292
4355
|
"large-removals": "large-removals";
|
|
4293
4356
|
"hand-edits": "hand-edits";
|
|
4294
4357
|
"not-upgraded": "not-upgraded";
|
|
4358
|
+
"newer-atticus": "newer-atticus";
|
|
4295
4359
|
}>>;
|
|
4296
4360
|
message: z.ZodString;
|
|
4297
4361
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4368,6 +4432,14 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4368
4432
|
repo: z.ZodString;
|
|
4369
4433
|
why: z.ZodString;
|
|
4370
4434
|
}, z.core.$strip>>>;
|
|
4435
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4436
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4437
|
+
path: z.ZodString;
|
|
4438
|
+
name: z.ZodString;
|
|
4439
|
+
field: z.ZodString;
|
|
4440
|
+
version: z.ZodNumber;
|
|
4441
|
+
reads: z.ZodNumber;
|
|
4442
|
+
}, z.core.$strip>>>;
|
|
4371
4443
|
command: z.ZodString;
|
|
4372
4444
|
plan: z.ZodOptional<z.ZodString>;
|
|
4373
4445
|
}, z.core.$strip>>;
|
|
@@ -4391,6 +4463,7 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4391
4463
|
"large-removals": "large-removals";
|
|
4392
4464
|
"hand-edits": "hand-edits";
|
|
4393
4465
|
"not-upgraded": "not-upgraded";
|
|
4466
|
+
"newer-atticus": "newer-atticus";
|
|
4394
4467
|
}>>;
|
|
4395
4468
|
message: z.ZodString;
|
|
4396
4469
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4467,6 +4540,14 @@ export declare const CatalogBuildView: z.ZodObject<{
|
|
|
4467
4540
|
repo: z.ZodString;
|
|
4468
4541
|
why: z.ZodString;
|
|
4469
4542
|
}, z.core.$strip>>>;
|
|
4543
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
4544
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
4545
|
+
path: z.ZodString;
|
|
4546
|
+
name: z.ZodString;
|
|
4547
|
+
field: z.ZodString;
|
|
4548
|
+
version: z.ZodNumber;
|
|
4549
|
+
reads: z.ZodNumber;
|
|
4550
|
+
}, z.core.$strip>>>;
|
|
4470
4551
|
command: z.ZodString;
|
|
4471
4552
|
plan: z.ZodOptional<z.ZodString>;
|
|
4472
4553
|
}, z.core.$strip>>;
|
|
@@ -4899,6 +4980,7 @@ export declare const MapEditsResult: z.ZodObject<{
|
|
|
4899
4980
|
"large-removals": "large-removals";
|
|
4900
4981
|
"hand-edits": "hand-edits";
|
|
4901
4982
|
"not-upgraded": "not-upgraded";
|
|
4983
|
+
"newer-atticus": "newer-atticus";
|
|
4902
4984
|
}>>;
|
|
4903
4985
|
message: z.ZodString;
|
|
4904
4986
|
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
@@ -4975,11 +5057,129 @@ export declare const MapEditsResult: z.ZodObject<{
|
|
|
4975
5057
|
repo: z.ZodString;
|
|
4976
5058
|
why: z.ZodString;
|
|
4977
5059
|
}, z.core.$strip>>>;
|
|
5060
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
5061
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5062
|
+
path: z.ZodString;
|
|
5063
|
+
name: z.ZodString;
|
|
5064
|
+
field: z.ZodString;
|
|
5065
|
+
version: z.ZodNumber;
|
|
5066
|
+
reads: z.ZodNumber;
|
|
5067
|
+
}, z.core.$strip>>>;
|
|
4978
5068
|
command: z.ZodString;
|
|
4979
5069
|
plan: z.ZodOptional<z.ZodString>;
|
|
4980
5070
|
}, z.core.$strip>>;
|
|
4981
5071
|
}, z.core.$strip>;
|
|
4982
5072
|
export type MapEditsResultT = z.infer<typeof MapEditsResult>;
|
|
5073
|
+
/**
|
|
5074
|
+
* 3.14.0: the result of POST /api/facts/{repo}/apply's job (GET /api/jobs/{id}'s `result`): its
|
|
5075
|
+
* code and the lines verify printed; `refused`, the listing of a build that waits for a confirm;
|
|
5076
|
+
* `leftOut` (beta.28.1), how many rejected facts the write left out (the lines name each); `next`,
|
|
5077
|
+
* a step to take first (Sync the repos).
|
|
5078
|
+
*/
|
|
5079
|
+
export declare const FactsApplyResult: z.ZodObject<{
|
|
5080
|
+
code: z.ZodNumber;
|
|
5081
|
+
lines: z.ZodArray<z.ZodString>;
|
|
5082
|
+
refused: z.ZodOptional<z.ZodObject<{
|
|
5083
|
+
reasons: z.ZodArray<z.ZodEnum<{
|
|
5084
|
+
"nothing-read": "nothing-read";
|
|
5085
|
+
empty: "empty";
|
|
5086
|
+
"unexplained-removals": "unexplained-removals";
|
|
5087
|
+
"large-removals": "large-removals";
|
|
5088
|
+
"hand-edits": "hand-edits";
|
|
5089
|
+
"not-upgraded": "not-upgraded";
|
|
5090
|
+
"newer-atticus": "newer-atticus";
|
|
5091
|
+
}>>;
|
|
5092
|
+
message: z.ZodString;
|
|
5093
|
+
removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5094
|
+
path: z.ZodString;
|
|
5095
|
+
kind: z.ZodString;
|
|
5096
|
+
id: z.ZodString;
|
|
5097
|
+
repos: z.ZodArray<z.ZodString>;
|
|
5098
|
+
explainedBy: z.ZodArray<z.ZodString>;
|
|
5099
|
+
reasons: z.ZodOptional<z.ZodArray<z.ZodEnum<{
|
|
5100
|
+
input: "input";
|
|
5101
|
+
build: "build";
|
|
5102
|
+
archived: "archived";
|
|
5103
|
+
manifest: "manifest";
|
|
5104
|
+
curated: "curated";
|
|
5105
|
+
slot: "slot";
|
|
5106
|
+
}>>>;
|
|
5107
|
+
inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5108
|
+
what: z.ZodEnum<{
|
|
5109
|
+
other: "other";
|
|
5110
|
+
inputs: "inputs";
|
|
5111
|
+
"org-pack": "org-pack";
|
|
5112
|
+
proposals: "proposals";
|
|
5113
|
+
shared: "shared";
|
|
5114
|
+
answers: "answers";
|
|
5115
|
+
pairings: "pairings";
|
|
5116
|
+
curated: "curated";
|
|
5117
|
+
traffic: "traffic";
|
|
5118
|
+
federated: "federated";
|
|
5119
|
+
}>;
|
|
5120
|
+
path: z.ZodString;
|
|
5121
|
+
}, z.core.$strip>>>;
|
|
5122
|
+
}, z.core.$strip>>>;
|
|
5123
|
+
unexplained: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5124
|
+
path: z.ZodString;
|
|
5125
|
+
kind: z.ZodString;
|
|
5126
|
+
id: z.ZodString;
|
|
5127
|
+
repos: z.ZodArray<z.ZodString>;
|
|
5128
|
+
explainedBy: z.ZodArray<z.ZodString>;
|
|
5129
|
+
reasons: z.ZodOptional<z.ZodArray<z.ZodEnum<{
|
|
5130
|
+
input: "input";
|
|
5131
|
+
build: "build";
|
|
5132
|
+
archived: "archived";
|
|
5133
|
+
manifest: "manifest";
|
|
5134
|
+
curated: "curated";
|
|
5135
|
+
slot: "slot";
|
|
5136
|
+
}>>>;
|
|
5137
|
+
inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5138
|
+
what: z.ZodEnum<{
|
|
5139
|
+
other: "other";
|
|
5140
|
+
inputs: "inputs";
|
|
5141
|
+
"org-pack": "org-pack";
|
|
5142
|
+
proposals: "proposals";
|
|
5143
|
+
shared: "shared";
|
|
5144
|
+
answers: "answers";
|
|
5145
|
+
pairings: "pairings";
|
|
5146
|
+
curated: "curated";
|
|
5147
|
+
traffic: "traffic";
|
|
5148
|
+
federated: "federated";
|
|
5149
|
+
}>;
|
|
5150
|
+
path: z.ZodString;
|
|
5151
|
+
}, z.core.$strip>>>;
|
|
5152
|
+
}, z.core.$strip>>>;
|
|
5153
|
+
allowRemovals: z.ZodOptional<z.ZodNumber>;
|
|
5154
|
+
edits: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5155
|
+
path: z.ZodString;
|
|
5156
|
+
how: z.ZodEnum<{
|
|
5157
|
+
added: "added";
|
|
5158
|
+
changed: "changed";
|
|
5159
|
+
deleted: "deleted";
|
|
5160
|
+
}>;
|
|
5161
|
+
}, z.core.$strip>>>;
|
|
5162
|
+
discardEdits: z.ZodOptional<z.ZodNumber>;
|
|
5163
|
+
unread: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5164
|
+
repo: z.ZodString;
|
|
5165
|
+
why: z.ZodString;
|
|
5166
|
+
}, z.core.$strip>>>;
|
|
5167
|
+
unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
|
|
5168
|
+
newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
5169
|
+
path: z.ZodString;
|
|
5170
|
+
name: z.ZodString;
|
|
5171
|
+
field: z.ZodString;
|
|
5172
|
+
version: z.ZodNumber;
|
|
5173
|
+
reads: z.ZodNumber;
|
|
5174
|
+
}, z.core.$strip>>>;
|
|
5175
|
+
command: z.ZodString;
|
|
5176
|
+
plan: z.ZodOptional<z.ZodString>;
|
|
5177
|
+
}, z.core.$strip>>;
|
|
5178
|
+
leftOut: z.ZodOptional<z.ZodNumber>;
|
|
5179
|
+
leftOutRepos: z.ZodOptional<z.ZodNumber>;
|
|
5180
|
+
next: z.ZodOptional<z.ZodUnknown>;
|
|
5181
|
+
}, z.core.$strip>;
|
|
5182
|
+
export type FactsApplyResultT = z.infer<typeof FactsApplyResult>;
|
|
4983
5183
|
/**
|
|
4984
5184
|
* 3.12.0 (ADR 0195 point 6): GET /api/build/upgrade, the upgrade to source slots as a dry run,
|
|
4985
5185
|
* exactly what `atticus upgrade --json` lists under `slots`: every file `atticus upgrade --yes`
|
|
@@ -6243,6 +6443,18 @@ export declare const VerifyPreviewView: z.ZodObject<{
|
|
|
6243
6443
|
head: z.ZodString;
|
|
6244
6444
|
commit: z.ZodString;
|
|
6245
6445
|
}, z.core.$strip>>;
|
|
6446
|
+
confirm: z.ZodOptional<z.ZodObject<{
|
|
6447
|
+
removals: z.ZodOptional<z.ZodNumber>;
|
|
6448
|
+
edits: z.ZodOptional<z.ZodNumber>;
|
|
6449
|
+
refused: z.ZodOptional<z.ZodArray<z.ZodEnum<{
|
|
6450
|
+
"nothing-read": "nothing-read";
|
|
6451
|
+
empty: "empty";
|
|
6452
|
+
"unexplained-removals": "unexplained-removals";
|
|
6453
|
+
"newer-atticus": "newer-atticus";
|
|
6454
|
+
}>>>;
|
|
6455
|
+
upgrade: z.ZodOptional<z.ZodLiteral<true>>;
|
|
6456
|
+
command: z.ZodOptional<z.ZodString>;
|
|
6457
|
+
}, z.core.$strip>>;
|
|
6246
6458
|
staleCorrections: z.ZodArray<z.ZodString>;
|
|
6247
6459
|
}, z.core.$strip>>;
|
|
6248
6460
|
unavailable: z.ZodOptional<z.ZodEnum<{
|
|
@@ -13484,10 +13696,16 @@ export declare const CandidateCallView: z.ZodObject<{
|
|
|
13484
13696
|
outside: "outside";
|
|
13485
13697
|
left: "left";
|
|
13486
13698
|
missed: "missed";
|
|
13699
|
+
joined: "joined";
|
|
13487
13700
|
unresolved: "unresolved";
|
|
13701
|
+
undrawn: "undrawn";
|
|
13702
|
+
here: "here";
|
|
13488
13703
|
}>;
|
|
13489
13704
|
why: z.ZodOptional<z.ZodString>;
|
|
13490
13705
|
paired: z.ZodOptional<z.ZodString>;
|
|
13706
|
+
joins: z.ZodOptional<z.ZodString>;
|
|
13707
|
+
now: z.ZodOptional<z.ZodString>;
|
|
13708
|
+
pairedBy: z.ZodOptional<z.ZodString>;
|
|
13491
13709
|
suggestion: z.ZodOptional<z.ZodObject<{
|
|
13492
13710
|
api: z.ZodString;
|
|
13493
13711
|
score: z.ZodNumber;
|
|
@@ -13548,10 +13766,16 @@ export declare const LinkCandidatesView: z.ZodObject<{
|
|
|
13548
13766
|
outside: "outside";
|
|
13549
13767
|
left: "left";
|
|
13550
13768
|
missed: "missed";
|
|
13769
|
+
joined: "joined";
|
|
13551
13770
|
unresolved: "unresolved";
|
|
13771
|
+
undrawn: "undrawn";
|
|
13772
|
+
here: "here";
|
|
13552
13773
|
}>;
|
|
13553
13774
|
why: z.ZodOptional<z.ZodString>;
|
|
13554
13775
|
paired: z.ZodOptional<z.ZodString>;
|
|
13776
|
+
joins: z.ZodOptional<z.ZodString>;
|
|
13777
|
+
now: z.ZodOptional<z.ZodString>;
|
|
13778
|
+
pairedBy: z.ZodOptional<z.ZodString>;
|
|
13555
13779
|
suggestion: z.ZodOptional<z.ZodObject<{
|
|
13556
13780
|
api: z.ZodString;
|
|
13557
13781
|
score: z.ZodNumber;
|
|
@@ -14085,6 +14309,7 @@ export declare const UpgradeView: z.ZodObject<{
|
|
|
14085
14309
|
files: z.ZodArray<z.ZodString>;
|
|
14086
14310
|
}, z.core.$strip>>;
|
|
14087
14311
|
upgraded: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
14312
|
+
newerCatalog: z.ZodOptional<z.ZodString>;
|
|
14088
14313
|
}, z.core.$strip>;
|
|
14089
14314
|
/**
|
|
14090
14315
|
* 3.5.0: what a setup edit changed, or with `preview: true` would change: the file
|
|
@@ -14292,6 +14517,7 @@ export declare const ConnectLinksRequest: z.ZodObject<{
|
|
|
14292
14517
|
}, z.core.$strip>>>;
|
|
14293
14518
|
rule: z.ZodOptional<z.ZodBoolean>;
|
|
14294
14519
|
preview: z.ZodOptional<z.ZodBoolean>;
|
|
14520
|
+
job: z.ZodOptional<z.ZodBoolean>;
|
|
14295
14521
|
}, z.core.$strip>;
|
|
14296
14522
|
export declare const ConnectLinksResult: z.ZodObject<{
|
|
14297
14523
|
written: z.ZodBoolean;
|
|
@@ -14376,6 +14602,14 @@ export declare const FileChangeResult: z.ZodObject<{
|
|
|
14376
14602
|
}, z.core.$strip>>;
|
|
14377
14603
|
verify: z.ZodString;
|
|
14378
14604
|
commit: z.ZodString;
|
|
14605
|
+
created: z.ZodOptional<z.ZodObject<{
|
|
14606
|
+
system: z.ZodString;
|
|
14607
|
+
file: z.ZodString;
|
|
14608
|
+
}, z.core.$strip>>;
|
|
14609
|
+
removed: z.ZodOptional<z.ZodObject<{
|
|
14610
|
+
system: z.ZodString;
|
|
14611
|
+
file: z.ZodString;
|
|
14612
|
+
}, z.core.$strip>>;
|
|
14379
14613
|
}, z.core.$strip>;
|
|
14380
14614
|
/**
|
|
14381
14615
|
* ADR 0179: a stroke drawn on the canvas for a change (a call, a topic, a table, a step removed
|
package/npm/core/cancel.d.ts
CHANGED
|
@@ -3,6 +3,13 @@ export declare class CancelledError extends Error {
|
|
|
3
3
|
}
|
|
4
4
|
/** Run `fn` with `signal` as the signal of everything it starts. */
|
|
5
5
|
export declare function withSignal<T>(signal: AbortSignal, fn: () => Promise<T>): Promise<T>;
|
|
6
|
+
/** Run `fn` with `commit` as what `commitCurrent()` inside it calls. */
|
|
7
|
+
export declare function withCommit<T>(commit: () => void, fn: () => Promise<T>): Promise<T>;
|
|
8
|
+
/**
|
|
9
|
+
* Say the job this code runs in has started writing: Stop is no longer heard. True when a job
|
|
10
|
+
* heard it (it says a late Stop itself); false outside one.
|
|
11
|
+
*/
|
|
12
|
+
export declare function commitCurrent(): boolean;
|
|
6
13
|
/** The signal of the job this code runs in, if it runs in one. */
|
|
7
14
|
export declare function currentSignal(): AbortSignal | undefined;
|
|
8
15
|
/** Stop here when the job was cancelled. */
|
|
@@ -31,6 +31,12 @@ export declare class DeclareError extends Error {
|
|
|
31
31
|
readonly code: "not-found" | "invalid" | "exists";
|
|
32
32
|
constructor(code: "not-found" | "invalid" | "exists", message: string);
|
|
33
33
|
}
|
|
34
|
+
/**
|
|
35
|
+
* The re-review of beta.28.1: a short hash of the System as the canvas added it, in its comment,
|
|
36
|
+
* so Undo takes it away only while it is still exactly that (no field a person changed since).
|
|
37
|
+
*/
|
|
38
|
+
export declare const addedHash: (s: Record<string, unknown>) => string;
|
|
39
|
+
export declare const addedComment: (by: string, at: string, hash: string) => string;
|
|
34
40
|
/** The comment a declaration carries: which side, who and when. */
|
|
35
41
|
export declare const declaredComment: (by: string, at: string, side?: "publishes" | "listens") => string;
|
|
36
42
|
/**
|
|
@@ -41,6 +47,17 @@ export declare function declareLink(root: string, d: Declared, o: {
|
|
|
41
47
|
by: string;
|
|
42
48
|
at: string;
|
|
43
49
|
preview?: boolean;
|
|
50
|
+
/**
|
|
51
|
+
* Beta.28.1 (field report 4): a system no profile has yet, which the canvas draws for a repo
|
|
52
|
+
* the manifest lists with no System of the profiles (the box takes the repo's id, or the
|
|
53
|
+
* manifest's `system`): added to its platform's profile in the same write, so a person
|
|
54
|
+
* declaring a link from that box never has to make the System first.
|
|
55
|
+
*/
|
|
56
|
+
create?: {
|
|
57
|
+
platform: string;
|
|
58
|
+
name?: string;
|
|
59
|
+
owner?: string;
|
|
60
|
+
};
|
|
44
61
|
}): Promise<{
|
|
45
62
|
rel: string;
|
|
46
63
|
changes: LineChange[];
|
|
@@ -49,7 +66,18 @@ export declare function declareLink(root: string, d: Declared, o: {
|
|
|
49
66
|
before: string;
|
|
50
67
|
/** The bytes it wrote (what a take-back expects to find). */
|
|
51
68
|
wrote?: string;
|
|
69
|
+
/** Beta.28.1: the system added to the profile first (`create`), when it had none. */
|
|
70
|
+
created?: string;
|
|
52
71
|
}>;
|
|
72
|
+
/**
|
|
73
|
+
* Beta.28.1 (field hunt G5): `after`, a whole document as the yaml library writes it, with every
|
|
74
|
+
* line it has unchanged from `before` (the file as written, LF) given back as `before` wrote it:
|
|
75
|
+
* a flow list's padding (`[dv, qa, prod]`), its quotes, its spacing. `before` as the library
|
|
76
|
+
* writes it is lined up with `before` line for line (the library keeps the lines and comments of
|
|
77
|
+
* a document it only reads); a line of `after` that is one of those, in order, is that line of
|
|
78
|
+
* `before`. Where the two don't line up (the library joined or split a line), `after` as it is.
|
|
79
|
+
*/
|
|
80
|
+
export declare function keepUntouchedLines(written: string, after: string): string;
|
|
53
81
|
/**
|
|
54
82
|
* Undo: remove a declared topic or call from the system's list, exactly that one. Beta.28 (the
|
|
55
83
|
* review of Edit the map): only that item's lines go (and the list's key when it was the last),
|
|
@@ -59,11 +87,16 @@ export declare function undeclareLink(root: string, d: {
|
|
|
59
87
|
kind: "topic" | "call";
|
|
60
88
|
system: string;
|
|
61
89
|
value: string;
|
|
90
|
+
}, o?: {
|
|
91
|
+
/** A pairing or an answer names the system: a System the canvas added for it stays. */
|
|
92
|
+
inUse?: boolean;
|
|
62
93
|
}): Promise<{
|
|
63
94
|
rel: string;
|
|
64
95
|
changes: LineChange[];
|
|
65
96
|
before: string;
|
|
66
97
|
wrote: string;
|
|
98
|
+
/** S3: the System the canvas added, taken away with its last declaration. */
|
|
99
|
+
removed?: string;
|
|
67
100
|
}>;
|
|
68
101
|
/** A system's declarations, with who and when where the canvas wrote them. */
|
|
69
102
|
export declare function declaredOf(root: string, system: string): Promise<{
|
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -608,6 +608,20 @@ export declare function keyRefIn(s: string | undefined): {
|
|
|
608
608
|
} | undefined;
|
|
609
609
|
/** Join every call of the estate's facts to the entry that serves it, or say why not. */
|
|
610
610
|
export declare function joinFacts(input: JoinFactsInput): FactsJoinResult;
|
|
611
|
+
/**
|
|
612
|
+
* Beta.28.1 (the review of "nothing slow runs silently"): joinFacts, giving way every
|
|
613
|
+
* JOIN_YIELD_EVERY calls, so a caller that awaits `tick` between (joinFactsAsync) lets a
|
|
614
|
+
* heartbeat, a Console line or a Stop through during a long join. The same join either way.
|
|
615
|
+
*/
|
|
616
|
+
export declare function joinFactsAsync(input: JoinFactsInput, tick: () => Promise<void>): Promise<FactsJoinResult>;
|
|
617
|
+
/** How many calls the join reads between two points where it gives way. */
|
|
618
|
+
export declare const JOIN_YIELD_EVERY = 200;
|
|
619
|
+
/** Work written as steps (a generator that yields where it may give way), run to its end. */
|
|
620
|
+
export declare function runSteps<T>(g: Generator<void, T, void>): T;
|
|
621
|
+
/** The same, awaiting `tick` at each point it may give way. */
|
|
622
|
+
export declare function runStepsAsync<T>(g: Generator<void, T, void>, tick: () => Promise<void>): Promise<T>;
|
|
623
|
+
/** joinFacts as steps: see joinFactsAsync. */
|
|
624
|
+
export declare function joinFactsSteps(input: JoinFactsInput): Generator<void, FactsJoinResult, void>;
|
|
611
625
|
/** The path a joined Interface records: the entry's, normalised (a gRPC or SOAP name as written). */
|
|
612
626
|
export declare function servedPath(e: Entry): string;
|
|
613
627
|
/** A gateway route's GatewayRoute id: `gw-<component>-<method>-<path>`, no dots (as a hop names one). */
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading and hashing many small files (beta.28.2): a catalog's 100,000 record files took 10 to
|
|
3
|
+
* 13 s to hash through the promise API, four calls each (open, stat, read, close) handed to
|
|
4
|
+
* libuv's thread pool and back, and each text decoded, its line endings replaced and encoded again
|
|
5
|
+
* to be hashed. Here a few worker threads read them with the synchronous calls, one file at a
|
|
6
|
+
* time each (so no more than one open file a worker: no EMFILE, on Windows either), and hash the
|
|
7
|
+
* bytes; the main thread stays free (a progress line, Stop between steps) and gets the results in
|
|
8
|
+
* the order of the paths, whatever the order the workers finish in. Every byte of every file is
|
|
9
|
+
* read: nothing is taken from a file's size and time. A small folder, or a process where a worker
|
|
10
|
+
* can't start, is read in this thread instead, to the same results.
|
|
11
|
+
*/
|
|
12
|
+
/** A file's size and time (ms, floored), as `stat` gives them. */
|
|
13
|
+
export interface FileStat {
|
|
14
|
+
size: number;
|
|
15
|
+
mtimeMs: number;
|
|
16
|
+
}
|
|
17
|
+
/** A file's size and time, and the hash of its text with its line endings LF (`textShaOf`). */
|
|
18
|
+
export interface FileHash extends FileStat {
|
|
19
|
+
sha: string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* How the files are read: tests force a number of workers (0: this thread) and the smallest
|
|
23
|
+
* folder read by workers. By default 2 to 4 workers (one fewer than the CPUs, at least 2), for
|
|
24
|
+
* folders of `MIN_FILES` files or more.
|
|
25
|
+
*/
|
|
26
|
+
export declare const filePoolHooks: {
|
|
27
|
+
workers?: number;
|
|
28
|
+
minFiles?: number;
|
|
29
|
+
/** A test's workers that fail as they start (as one that can't: ERR_WORKER_INIT_FAILED, OOM). */
|
|
30
|
+
failStart?: boolean;
|
|
31
|
+
/** A test's workers that start and never say they are ready (nor fail, nor exit). */
|
|
32
|
+
neverReady?: boolean;
|
|
33
|
+
/** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
|
|
34
|
+
startTimeoutMs?: number;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* How long the workers have to say they are ready before this thread reads instead (the final
|
|
38
|
+
* review of beta.28.2: a worker that neither answered nor failed hung the build). A worker starts
|
|
39
|
+
* in tens of milliseconds; 10 s is a host so loaded that this thread would be no slower.
|
|
40
|
+
*/
|
|
41
|
+
export declare const START_TIMEOUT_MS = 10000;
|
|
42
|
+
/**
|
|
43
|
+
* The hash of a file's text, read as UTF-8, with its line endings LF: `sha256Of` of that text.
|
|
44
|
+
* Bytes that are UTF-8 with no CR are that text's own bytes, so they are hashed as they are;
|
|
45
|
+
* any other (a CR, a byte that isn't UTF-8, read as U+FFFD) are decoded first, as a read gives.
|
|
46
|
+
*/
|
|
47
|
+
export declare function textShaOf(bytes: Buffer): string;
|
|
48
|
+
/**
|
|
49
|
+
* Every named file under `dir` (paths with forward slashes), read whole and hashed: its text hash
|
|
50
|
+
* (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
|
|
51
|
+
* the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
|
|
52
|
+
* hash is of the file's bytes as they are (sha256, no line endings made LF): a parse kept by it
|
|
53
|
+
* is of exactly those bytes (record-cache.ts).
|
|
54
|
+
*/
|
|
55
|
+
export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
|
|
56
|
+
raw?: boolean;
|
|
57
|
+
}): Promise<FileHash[]>;
|
|
58
|
+
/** Every named file's size and time (ms, floored), in the order of `rels`; none for one not there. */
|
|
59
|
+
export declare function statFilesIn(dir: string, rels: readonly string[]): Promise<(FileStat | undefined)[]>;
|
package/npm/core/fs.d.ts
CHANGED
|
@@ -5,7 +5,30 @@
|
|
|
5
5
|
* Windows a rename can fail for a moment while a virus scanner or indexer holds the file:
|
|
6
6
|
* it is retried a few times before giving up.
|
|
7
7
|
*/
|
|
8
|
-
export declare function writeFileAtomic(path: string, data: string | Uint8Array
|
|
8
|
+
export declare function writeFileAtomic(path: string, data: string | Uint8Array, o?: {
|
|
9
|
+
/**
|
|
10
|
+
* Told the size and time (ms, floored) of the file as written (beta.28.2: a writer keeps its
|
|
11
|
+
* parse by them): the temporary file's, taken on its handle before the rename (which keeps
|
|
12
|
+
* them), when the file has the same once renamed; not told when they differ (the file was
|
|
13
|
+
* changed meanwhile, or the system set another time on close). With them, the sha256 of the
|
|
14
|
+
* bytes written and `writtenAt`, the clock (ms) as the write began: a parse kept by them is
|
|
15
|
+
* checked by that hash while the file's time is within the timestamp's grain of `writtenAt`
|
|
16
|
+
* (record-cache.ts, `RACY_MS`).
|
|
17
|
+
*/
|
|
18
|
+
stat?: (s: {
|
|
19
|
+
size: number;
|
|
20
|
+
mtimeMs: number;
|
|
21
|
+
sha: string;
|
|
22
|
+
writtenAt: number;
|
|
23
|
+
}) => void;
|
|
24
|
+
}): Promise<void>;
|
|
25
|
+
/**
|
|
26
|
+
* Copy a file the way `writeFileAtomic` writes one: to a temporary file beside the target, then
|
|
27
|
+
* renamed over it. The copy is made by the system (a copy-on-write clone where the file system
|
|
28
|
+
* has them, APFS, Btrfs or XFS; else a copy in the kernel), so the bytes never pass through
|
|
29
|
+
* JavaScript (beta.28.1: a 60-repo estate's build.json is 180 MB).
|
|
30
|
+
*/
|
|
31
|
+
export declare function copyFileAtomic(from: string, path: string): Promise<void>;
|
|
9
32
|
/** A file changed on disk between being read and being written back: nothing was written. */
|
|
10
33
|
export declare class FileChangedError extends Error {
|
|
11
34
|
readonly path: string;
|
package/npm/core/index.d.ts
CHANGED
|
@@ -8,7 +8,23 @@ import type { Fact } from "./schema/facts.js";
|
|
|
8
8
|
*/
|
|
9
9
|
export type LooseStatus = "asked" | "missed" | "left" | "outside" | "unresolved"
|
|
10
10
|
/** Already paired by a person with an API of this box. */
|
|
11
|
-
| "paired"
|
|
11
|
+
| "paired"
|
|
12
|
+
/**
|
|
13
|
+
* Beta.28.1: the join ties it to another box (or this one) and an arrow is drawn for it:
|
|
14
|
+
* listed so it can be moved here from the same panel, never ticked unseen.
|
|
15
|
+
*/
|
|
16
|
+
| "joined"
|
|
17
|
+
/**
|
|
18
|
+
* Beta.28.1: the join ties it to something, and no arrow is drawn for it (its own component,
|
|
19
|
+
* or no Interface of it on the canvas): as loose as a call that joins nothing.
|
|
20
|
+
*/
|
|
21
|
+
| "undrawn"
|
|
22
|
+
/**
|
|
23
|
+
* The review of beta.28.1 (S2): the join ties it to this very box and an arrow is drawn for it
|
|
24
|
+
* (`now` the API it goes to): it goes here already, so nothing is suggested for it, and a
|
|
25
|
+
* pairing with the API it goes to would be a redundant line (refused).
|
|
26
|
+
*/
|
|
27
|
+
| "here";
|
|
12
28
|
export interface CandidateApi {
|
|
13
29
|
/** The entry's fact id, or the operation's id in the spec. */
|
|
14
30
|
id: string;
|
|
@@ -33,6 +49,18 @@ export interface CandidateCall {
|
|
|
33
49
|
why?: string;
|
|
34
50
|
/** For paired: the API it is paired with. */
|
|
35
51
|
paired?: string;
|
|
52
|
+
/**
|
|
53
|
+
* Beta.28.1: the box the join ties it to now (a repo, or an outside target), for a call that
|
|
54
|
+
* is joined, undrawn or outside: where it goes, or would go, before it is moved.
|
|
55
|
+
*/
|
|
56
|
+
joins?: string;
|
|
57
|
+
/** For here: the API of this box it goes to now (an entry's fact id), when the join names one. */
|
|
58
|
+
now?: string;
|
|
59
|
+
/**
|
|
60
|
+
* The review of beta.28.1 (N3): who paired it with the box it goes to now (another box): a
|
|
61
|
+
* pairing here replaces that person's word, which the panel says before it is written.
|
|
62
|
+
*/
|
|
63
|
+
pairedBy?: string;
|
|
36
64
|
suggestion?: {
|
|
37
65
|
api: string;
|
|
38
66
|
score: number;
|
|
@@ -100,4 +128,25 @@ export declare function linkCandidates(o: {
|
|
|
100
128
|
};
|
|
101
129
|
/** A's settings by key (its config facts with a value), to fill a call's `${key}` in. */
|
|
102
130
|
settings?: Readonly<Record<string, string>>;
|
|
131
|
+
/**
|
|
132
|
+
* Beta.28.1: whether the canvas draws a join's arrow (its Interface is in the catalog). A join
|
|
133
|
+
* of a call to its own component is never drawn, whatever this says. Default: every other is.
|
|
134
|
+
*/
|
|
135
|
+
drawn?: (j: FactsJoinResult["joins"][number]) => boolean;
|
|
136
|
+
/**
|
|
137
|
+
* Beta.28.1: whether the canvas draws a call placed outside the estate to this target (an
|
|
138
|
+
* outside system of the profile takes it). Default: none is, so the call is listed loose.
|
|
139
|
+
*/
|
|
140
|
+
drawnOutside?: (target: string, call: string) => boolean;
|
|
141
|
+
/**
|
|
142
|
+
* Whether a repo, a component or a system is drawn in the box connected to (a repo's own id,
|
|
143
|
+
* its components; a system's repos and their components). Default: the box's own id only.
|
|
144
|
+
*/
|
|
145
|
+
inBox?: (name: string) => boolean;
|
|
146
|
+
/**
|
|
147
|
+
* The review of beta.28.1 (S4): the box the built catalog draws a call's arrow to (an
|
|
148
|
+
* Interface current in it citing the call's line), for a call the join doesn't place: the
|
|
149
|
+
* canvas is what the person sees, so a drawn call is never listed as loose.
|
|
150
|
+
*/
|
|
151
|
+
drawnTo?: (call: string) => string | undefined;
|
|
103
152
|
}): LinkCandidates;
|
package/npm/core/printer.d.ts
CHANGED
|
@@ -1,4 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR 0187: where a line printed by a command goes besides its own output, while it runs inside
|
|
3
|
+
* the app's job. The job (in the server) sets the printer; the command line's `main`, and the
|
|
4
|
+
* app's routes that run a command's code, pass each line they print to `printToCurrent`. Outside
|
|
5
|
+
* a job there is no printer and nothing happens. No schema here: the command line loads it first.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Beta.28.1: how a line is printed. `now`: a progress line (a step of long work), sent to the
|
|
9
|
+
* Console at once rather than in the next batch of lines, so it is there before the step's work
|
|
10
|
+
* keeps the thread.
|
|
11
|
+
*/
|
|
12
|
+
export interface PrintOptions {
|
|
13
|
+
now?: boolean;
|
|
14
|
+
}
|
|
1
15
|
/** 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;
|
|
16
|
+
export declare function withPrinter<T>(print: (line: string, o?: PrintOptions) => void, work: () => T): T;
|
|
3
17
|
/** Print a line to the job this code runs in, if any. */
|
|
4
|
-
export declare function printToCurrent(line: string): void;
|
|
18
|
+
export declare function printToCurrent(line: string, o?: PrintOptions): void;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { type FileStat } from "./file-pool.js";
|
|
1
2
|
/**
|
|
2
3
|
* Record files read and parsed once, then kept between runs (ADR 0119, with its addendum of
|
|
3
4
|
* 2026-10-26). A metarepo's catalog is about 1,500 files and its specs 400 more; reading and
|
|
@@ -16,13 +17,40 @@
|
|
|
16
17
|
*
|
|
17
18
|
* Nothing here decides what a file means: the caller's `parse` does, and only its output (the
|
|
18
19
|
* record, or the problem with the file) is kept.
|
|
20
|
+
*
|
|
21
|
+
* Racily clean files (the final review of beta.28.2, Git's rule of the same name). A file system
|
|
22
|
+
* keeps a file's time to a grain (FAT 2 s, HFS+ 1 s, some SMB and NFS mounts 1 s or more), so a
|
|
23
|
+
* same-size edit made within that grain of a read or a write can keep the time the parse was kept
|
|
24
|
+
* by, and size and time alone would serve the old text. So each parse is kept with the clock as
|
|
25
|
+
* it was taken (`at`: before the bytes parsed were read, or before a writer wrote them), and one
|
|
26
|
+
* whose file's time is no more than `RACY_MS` before `at` is "racy": it keeps the sha256 of the
|
|
27
|
+
* bytes parsed, and is reused only when the file still hashes to them (read in the file pool's
|
|
28
|
+
* workers; cheaper than a parse), then kept again as of the hash's read when by then it is no
|
|
29
|
+
* longer racy (the next command, seconds on: from then on its stat alone decides). A parse whose
|
|
30
|
+
* file's time is more than `RACY_MS` before `at` is trusted by size and time, as before: any edit
|
|
31
|
+
* after `at` has a time after `at` less the grain, so it can't keep that time. A parse kept with no `at` (an older cache) is racy, and with no hash it is
|
|
32
|
+
* parsed again. The rule takes this machine's clock and the file system's to agree to within the
|
|
33
|
+
* grain (a mount whose server runs more than `RACY_MS` behind can still serve a stale parse, as
|
|
34
|
+
* Git can).
|
|
35
|
+
*/
|
|
36
|
+
/**
|
|
37
|
+
* The widest timestamp grain allowed for (FAT's 2 s): a parse kept of a file whose time was
|
|
38
|
+
* within this of the moment it was kept is checked by its hash before it is reused.
|
|
19
39
|
*/
|
|
40
|
+
export declare const RACY_MS = 2000;
|
|
41
|
+
/** Tests set the clock a parse is kept at (ms; default `Date.now`). */
|
|
42
|
+
export declare const recordCacheHooks: {
|
|
43
|
+
now?: () => number;
|
|
44
|
+
};
|
|
20
45
|
/** One file's parse: the value, or why the file isn't valid. Never both. */
|
|
21
46
|
export interface Parsed<T> {
|
|
22
47
|
/** The file, relative to the folder, with forward slashes. */
|
|
23
48
|
rel: string;
|
|
24
49
|
value?: T;
|
|
25
50
|
problem?: string;
|
|
51
|
+
/** With `withStats`: the file's size and time (ms, floored) as this read found them (-1: none). */
|
|
52
|
+
size?: number;
|
|
53
|
+
mtimeMs?: number;
|
|
26
54
|
}
|
|
27
55
|
/** What a caller's parse says about one file. */
|
|
28
56
|
export type ParseOutcome<T> = {
|
|
@@ -32,6 +60,16 @@ export type ParseOutcome<T> = {
|
|
|
32
60
|
ok: false;
|
|
33
61
|
message: string;
|
|
34
62
|
};
|
|
63
|
+
interface Entry {
|
|
64
|
+
size: number;
|
|
65
|
+
mtimeMs: number;
|
|
66
|
+
/** The clock (ms) as the parse was kept: before its bytes were read, or written. None: racy. */
|
|
67
|
+
at?: number;
|
|
68
|
+
/** A racy entry's sha256 of the bytes parsed (none once it isn't racy). */
|
|
69
|
+
sha?: string;
|
|
70
|
+
value?: unknown;
|
|
71
|
+
problem?: string;
|
|
72
|
+
}
|
|
35
73
|
/** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
|
|
36
74
|
export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
|
|
37
75
|
/**
|
|
@@ -49,4 +87,60 @@ export declare function readParsedFiles<T>(o: {
|
|
|
49
87
|
parse: (text: string, rel: string) => ParseOutcome<T>;
|
|
50
88
|
/** The root of the metarepo this run is working in; none means no cache (read-only). */
|
|
51
89
|
cacheRoot?: string;
|
|
90
|
+
/**
|
|
91
|
+
* False: the parses kept under `cacheRoot` are read, and nothing is written there (a preview,
|
|
92
|
+
* which writes nothing: beta.28.1, it parsed a 100,000-record catalog from its files).
|
|
93
|
+
*/
|
|
94
|
+
keep?: boolean;
|
|
95
|
+
/** Each file's size and time with its parse (beta.28.1: a write matches them to its own read). */
|
|
96
|
+
withStats?: boolean;
|
|
97
|
+
/**
|
|
98
|
+
* Told what this read keeps under `cacheRoot` (not called when it keeps nothing): a writer that
|
|
99
|
+
* then writes some of the files adds their parses with `keepParses` (beta.28.2).
|
|
100
|
+
*/
|
|
101
|
+
kept?: (k: KeptParses<T>) => void;
|
|
52
102
|
}): Promise<Parsed<T>[]>;
|
|
103
|
+
/** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
|
|
104
|
+
export interface KeptParses<T> {
|
|
105
|
+
readonly memo: {
|
|
106
|
+
root: string;
|
|
107
|
+
file: string;
|
|
108
|
+
};
|
|
109
|
+
readonly version: string;
|
|
110
|
+
readonly dir: string;
|
|
111
|
+
/** The kept parses by path, as that read left them. */
|
|
112
|
+
readonly entries: ReadonlyMap<string, Entry>;
|
|
113
|
+
/** Only to tie the type to the parse's value. */
|
|
114
|
+
readonly _value?: T;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Add the parses of files a writer wrote since its read (`k`) to what that read kept, and forget
|
|
118
|
+
* the files it removed (beta.28.2: a catalog write rewrites its features and glossary terms,
|
|
119
|
+
* megabytes of YAML, and the next read parsed them again). Each file is kept by the size and time
|
|
120
|
+
* it had as it was written, with the parse of the text the writer wrote there, which is what a
|
|
121
|
+
* read of it would parse; a file whose size or time is another now (changed since), or gone, isn't
|
|
122
|
+
* kept. A file written moments ago is racy (its time is within `RACY_MS` of the write): it is kept
|
|
123
|
+
* with the hash of the bytes written (`writeFileAtomic`'s `stat` gives it, and the clock as the
|
|
124
|
+
* write began), so the next read reuses it only when the file still hashes to them; one with no
|
|
125
|
+
* hash is parsed again by the next read. A cache that can't be written costs the next read its
|
|
126
|
+
* parses.
|
|
127
|
+
*/
|
|
128
|
+
export declare function keepParses<T>(k: KeptParses<T>, o: {
|
|
129
|
+
/**
|
|
130
|
+
* Each file written, with the size and time it had as it was written (`writeFileAtomic`'s
|
|
131
|
+
* `stat`): it is kept only while it still has exactly those, so an edit made since (of the
|
|
132
|
+
* same size too: its time differs, or within the grain its hash does) is parsed by the next
|
|
133
|
+
* read, never served the writer's text. `sha` and `writtenAt` as `writeFileAtomic` gives them.
|
|
134
|
+
*/
|
|
135
|
+
files: readonly {
|
|
136
|
+
rel: string;
|
|
137
|
+
value?: T;
|
|
138
|
+
problem?: string;
|
|
139
|
+
at: FileStat & {
|
|
140
|
+
sha?: string;
|
|
141
|
+
writtenAt?: number;
|
|
142
|
+
};
|
|
143
|
+
}[];
|
|
144
|
+
removed: readonly string[];
|
|
145
|
+
}): Promise<void>;
|
|
146
|
+
export {};
|
package/npm/index.js
CHANGED
|
@@ -6992,7 +6992,9 @@ var BuildRefusalView = z31.object({
|
|
|
6992
6992
|
"unexplained-removals",
|
|
6993
6993
|
"large-removals",
|
|
6994
6994
|
"hand-edits",
|
|
6995
|
-
"not-upgraded"
|
|
6995
|
+
"not-upgraded",
|
|
6996
|
+
// 3.15.0 (beta.28.2, ADR 0197): build.json or a slot a newer Atticus wrote.
|
|
6997
|
+
"newer-atticus"
|
|
6996
6998
|
])),
|
|
6997
6999
|
message: z31.string(),
|
|
6998
7000
|
removals: z31.array(BuildRemoval).optional(),
|
|
@@ -7002,6 +7004,28 @@ var BuildRefusalView = z31.object({
|
|
|
7002
7004
|
discardEdits: z31.number().int().optional(),
|
|
7003
7005
|
/** A scan that read nothing: each repo it couldn't read in full, and why. */
|
|
7004
7006
|
unread: z31.array(z31.object({ repo: z31.string(), why: z31.string() })).optional(),
|
|
7007
|
+
/**
|
|
7008
|
+
* 3.15.0 (beta.28.2, ADR 0197): a `hand-edits` refusal because build.json is there but doesn't
|
|
7009
|
+
* read (edited or merged by hand). The only way on is to build again with `discardEdits` (every
|
|
7010
|
+
* record file); its edits are not to be made curated.
|
|
7011
|
+
*/
|
|
7012
|
+
unreadableManifest: z31.literal(true).optional(),
|
|
7013
|
+
/**
|
|
7014
|
+
* 3.15.0 (beta.28.2, ADR 0197): a `newer-atticus` refusal's files a newer Atticus wrote
|
|
7015
|
+
* (build.json, a slot), each with its version field, the version it has and the newest one
|
|
7016
|
+
* this Atticus reads, as the 409 problem's `refused.newer` and the command line's --json say.
|
|
7017
|
+
*/
|
|
7018
|
+
newer: z31.array(z31.object({
|
|
7019
|
+
/** Metarepo-relative, '/'-separated. */
|
|
7020
|
+
path: z31.string(),
|
|
7021
|
+
/** What the words call it: `build.json`, or its path. */
|
|
7022
|
+
name: z31.string(),
|
|
7023
|
+
/** The version field (`version`, `slotVersion`, `factsSchemaVersion`). */
|
|
7024
|
+
field: z31.string(),
|
|
7025
|
+
version: z31.number().int(),
|
|
7026
|
+
/** The newest version of it this Atticus reads. */
|
|
7027
|
+
reads: z31.number().int()
|
|
7028
|
+
})).optional(),
|
|
7005
7029
|
/** What goes on in a terminal (the build, the hand edits' curate, or the upgrade). */
|
|
7006
7030
|
command: z31.string(),
|
|
7007
7031
|
/**
|
|
@@ -7201,6 +7225,15 @@ var MapEditsResult = z31.object({
|
|
|
7201
7225
|
*/
|
|
7202
7226
|
refused: BuildRefusalView.optional()
|
|
7203
7227
|
});
|
|
7228
|
+
var FactsApplyResult = z31.object({
|
|
7229
|
+
code: z31.number().int(),
|
|
7230
|
+
lines: z31.array(z31.string()),
|
|
7231
|
+
refused: BuildRefusalView.optional(),
|
|
7232
|
+
leftOut: z31.number().int().positive().optional(),
|
|
7233
|
+
/** Apply to every repo's (POST /api/facts/apply-all): how many repos left facts out. */
|
|
7234
|
+
leftOutRepos: z31.number().int().positive().optional(),
|
|
7235
|
+
next: z31.unknown().optional()
|
|
7236
|
+
});
|
|
7204
7237
|
var CatalogUpgradeView = z31.object({
|
|
7205
7238
|
pending: z31.boolean(),
|
|
7206
7239
|
records: z31.number().int(),
|
|
@@ -7616,6 +7649,22 @@ var VerifyPreviewView = z31.object({
|
|
|
7616
7649
|
}).optional(),
|
|
7617
7650
|
/** The checkout's HEAD is past the facts' commit: verify reads the changed files' facts again. */
|
|
7618
7651
|
headMoved: z31.object({ head: z31.string(), commit: z31.string() }).optional(),
|
|
7652
|
+
/**
|
|
7653
|
+
* 3.14.0 (beta.28.1): what the Apply's guards will say (ADR 0195 point 4), absent when it
|
|
7654
|
+
* writes without a word. It waits for a person's confirm when its build removes more than
|
|
7655
|
+
* the guard's limit (`removals`, how many it lists) or files under catalog/generated were
|
|
7656
|
+
* changed by hand (`edits`, how many), with the command that confirms exactly them; it
|
|
7657
|
+
* refuses whatever is confirmed when `refused` lists reasons (removals nothing explains,
|
|
7658
|
+
* an empty build, nothing read), and no command is given; on a catalog from before the
|
|
7659
|
+
* slots (`upgrade`) the command is `atticus upgrade`.
|
|
7660
|
+
*/
|
|
7661
|
+
confirm: z31.object({
|
|
7662
|
+
removals: z31.number().int().optional(),
|
|
7663
|
+
edits: z31.number().int().optional(),
|
|
7664
|
+
refused: z31.array(z31.enum(["nothing-read", "empty", "unexplained-removals", "newer-atticus"])).optional(),
|
|
7665
|
+
upgrade: z31.literal(true).optional(),
|
|
7666
|
+
command: z31.string().optional()
|
|
7667
|
+
}).optional(),
|
|
7619
7668
|
/** Corrections on file that meet no fact in this read (kept, applied when it is read again). */
|
|
7620
7669
|
staleCorrections: z31.array(z31.string())
|
|
7621
7670
|
}).optional(),
|
|
@@ -9556,9 +9605,30 @@ var CandidateCallView = z31.object({
|
|
|
9556
9605
|
method: z31.string().optional(),
|
|
9557
9606
|
path: z31.string(),
|
|
9558
9607
|
at: z31.string(),
|
|
9559
|
-
|
|
9608
|
+
/**
|
|
9609
|
+
* 3.14: `joined`, a call with an arrow drawn already, listed so it can be moved to this box;
|
|
9610
|
+
* `undrawn`, a call the join ties to something no arrow is drawn for, as loose as any;
|
|
9611
|
+
* `here`, a call with an arrow to this very box (`now` its API), never suggested again.
|
|
9612
|
+
*/
|
|
9613
|
+
status: z31.enum([
|
|
9614
|
+
"asked",
|
|
9615
|
+
"missed",
|
|
9616
|
+
"left",
|
|
9617
|
+
"outside",
|
|
9618
|
+
"unresolved",
|
|
9619
|
+
"paired",
|
|
9620
|
+
"joined",
|
|
9621
|
+
"undrawn",
|
|
9622
|
+
"here"
|
|
9623
|
+
]),
|
|
9560
9624
|
why: z31.string().optional(),
|
|
9561
9625
|
paired: z31.string().optional(),
|
|
9626
|
+
/** 3.14: the box the call goes to now (a repo, or an outside target), before it is moved. */
|
|
9627
|
+
joins: z31.string().optional(),
|
|
9628
|
+
/** 3.14: for `here`, the API of this box the call goes to now. */
|
|
9629
|
+
now: z31.string().optional(),
|
|
9630
|
+
/** 3.14: who paired the call with the box it goes to now, when a person did. */
|
|
9631
|
+
pairedBy: z31.string().optional(),
|
|
9562
9632
|
suggestion: CandidateSuggestion.optional(),
|
|
9563
9633
|
/** 2.57: the APIs it most likely is, best first, at most three. */
|
|
9564
9634
|
suggestions: z31.array(CandidateSuggestion).max(3).optional(),
|
|
@@ -9841,7 +9911,12 @@ var UpgradeView = z31.object({
|
|
|
9841
9911
|
* committed yet, besides the stamp. Final round: the panel reads them from the upgrade job's
|
|
9842
9912
|
* result, and offers Propose for the stamp alone too.
|
|
9843
9913
|
*/
|
|
9844
|
-
upgraded: z31.array(z31.string()).optional()
|
|
9914
|
+
upgraded: z31.array(z31.string()).optional(),
|
|
9915
|
+
/**
|
|
9916
|
+
* 3.15.0 (beta.28.2, ADR 0197): the catalog was built by a newer Atticus, in words that say to
|
|
9917
|
+
* upgrade Atticus (never `atticus upgrade`); `pending` is then empty, as the upgrade refuses.
|
|
9918
|
+
*/
|
|
9919
|
+
newerCatalog: z31.string().optional()
|
|
9845
9920
|
});
|
|
9846
9921
|
var FileEditView = z31.object({
|
|
9847
9922
|
path: z31.string(),
|
|
@@ -10003,7 +10078,12 @@ var ConnectLinksRequest = z31.object({
|
|
|
10003
10078
|
/** Answer A's open target question with /** to B, so calls read later follow it too. */
|
|
10004
10079
|
rule: z31.boolean().optional(),
|
|
10005
10080
|
/** Say what it would write and what the next verify --write changes; write nothing. */
|
|
10006
|
-
preview: z31.boolean().optional()
|
|
10081
|
+
preview: z31.boolean().optional(),
|
|
10082
|
+
/**
|
|
10083
|
+
* 3.14.0 (beta.28.1): run it as a job (202 and its id at once; its steps are the job's lines,
|
|
10084
|
+
* Stop ends it between them, and its result `answer` is this request's result, or `problem`).
|
|
10085
|
+
*/
|
|
10086
|
+
job: z31.boolean().optional()
|
|
10007
10087
|
});
|
|
10008
10088
|
var ConnectLinksResult = z31.object({
|
|
10009
10089
|
written: z31.boolean(),
|
|
@@ -10061,7 +10141,17 @@ var FileChangeResult = z31.object({
|
|
|
10061
10141
|
written: z31.boolean(),
|
|
10062
10142
|
files: z31.array(z31.object({ file: z31.string(), changes: z31.array(LineChangeView) })),
|
|
10063
10143
|
verify: z31.string(),
|
|
10064
|
-
commit: z31.string()
|
|
10144
|
+
commit: z31.string(),
|
|
10145
|
+
/**
|
|
10146
|
+
* 3.14: the System added to a profile first, for a declaration from a box no profile had (a
|
|
10147
|
+
* repo the manifest lists with no System): the person is told it was added, and where.
|
|
10148
|
+
*/
|
|
10149
|
+
created: z31.object({ system: z31.string(), file: z31.string() }).optional(),
|
|
10150
|
+
/**
|
|
10151
|
+
* 3.14: the System the canvas added for a declaration, taken away with its last one (Undo):
|
|
10152
|
+
* the person is told it went, and from where.
|
|
10153
|
+
*/
|
|
10154
|
+
removed: z31.object({ system: z31.string(), file: z31.string() }).optional()
|
|
10065
10155
|
});
|
|
10066
10156
|
var SketchStrokeRequest = z31.object({
|
|
10067
10157
|
stroke: z31.object({ kind: z31.enum(["call", "topic", "table", "remove", "retarget", "undo", "retire"]) }).passthrough(),
|
|
@@ -11661,8 +11751,13 @@ var OPS = {
|
|
|
11661
11751
|
id: "previewVerifyWrite",
|
|
11662
11752
|
summary: "After a correction: the commands to run (atticus verify <repo> --write, then the git steps with the exact files) and what that write will change in the facts and the catalog (links moved, added, removed; facts dropped or edited), computed in-process without writing (ADR 0149)",
|
|
11663
11753
|
tag: "workspace",
|
|
11664
|
-
params: [
|
|
11754
|
+
params: [
|
|
11755
|
+
p("repo"),
|
|
11756
|
+
q("fact", str3, "The fact corrected, for the branch and commit message"),
|
|
11757
|
+
q("job", str3, "3.14.0: 1 runs the preview as a job (202 JobAccepted; its steps are its lines, Stop ends it between them, its result `answer` is this view or `problem`)")
|
|
11758
|
+
],
|
|
11665
11759
|
ok: { status: 200, schema: "VerifyPreviewView", description: "OK" },
|
|
11760
|
+
alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job=1`)" },
|
|
11666
11761
|
errors: [400, 404]
|
|
11667
11762
|
}
|
|
11668
11763
|
},
|
|
@@ -11783,14 +11878,14 @@ var OPS = {
|
|
|
11783
11878
|
"/api/facts/{repo}/apply": {
|
|
11784
11879
|
post: {
|
|
11785
11880
|
id: "applyFacts",
|
|
11786
|
-
summary: "2.65.0 (ADR 0183): run atticus verify <repo> --write, as Apply after an answer or a correction; 3.12.0: with the counts that confirm a refused build",
|
|
11881
|
+
summary: "2.65.0 (ADR 0183): run atticus verify <repo> --write, as Apply after an answer or a correction; 3.12.0: with the counts that confirm a refused build; 3.14.0: a rejected fact is left out and the rest written (leftOut in the result)",
|
|
11787
11882
|
tag: "workspace",
|
|
11788
11883
|
params: [p("repo")],
|
|
11789
11884
|
body: FactsApplyRequest,
|
|
11790
11885
|
ok: {
|
|
11791
11886
|
status: 202,
|
|
11792
11887
|
schema: "JobAccepted",
|
|
11793
|
-
description: "Started: its job's result is the code and the lines verify printed"
|
|
11888
|
+
description: "Started: its job's result is FactsApplyResult: the code and the lines verify printed, a refused build's listing, and (3.14.0) leftOut, how many rejected facts the write left out"
|
|
11794
11889
|
},
|
|
11795
11890
|
// 2.68.0: 409 while another local step (Apply, Propose, Bring in) runs.
|
|
11796
11891
|
errors: [400, 409]
|
|
@@ -12224,19 +12319,22 @@ var OPS = {
|
|
|
12224
12319
|
params: [
|
|
12225
12320
|
q("from", str3, "Box A: the caller's repo"),
|
|
12226
12321
|
q("to", str3, "Box B: a repo of the manifest"),
|
|
12227
|
-
q("system", str3, "Box B: an outside system of the profile (instead of to)")
|
|
12322
|
+
q("system", str3, "Box B: an outside system of the profile (instead of to)"),
|
|
12323
|
+
q("job", str3, "3.14.0: 1 runs the read as a job (202 JobAccepted; its steps are its lines, Stop ends it between them, its result `answer` is this view or `problem`)")
|
|
12228
12324
|
],
|
|
12229
12325
|
ok: { status: 200, schema: "LinkCandidatesView", description: "OK" },
|
|
12326
|
+
alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job=1`)" },
|
|
12230
12327
|
errors: [400, 404]
|
|
12231
12328
|
}
|
|
12232
12329
|
},
|
|
12233
12330
|
"/api/links/connect": {
|
|
12234
12331
|
post: {
|
|
12235
12332
|
id: "connectLinks",
|
|
12236
|
-
summary: "Pair box A's calls with box B's APIs (ADR 0174, G1): a link line per pair in A's corrections, and with rule a /** answer; with preview, what it would write and the next verify --write changes",
|
|
12333
|
+
summary: "Pair box A's calls with box B's APIs (ADR 0174, G1): a link line per pair in A's corrections, and with rule a /** answer; with preview, what it would write and the next verify --write changes. 3.14.0: with `job: true`, 202 JobAccepted at once; the job's result `answer` is this result, or `problem`",
|
|
12237
12334
|
tag: "views",
|
|
12238
12335
|
body: ConnectLinksRequest,
|
|
12239
12336
|
ok: { status: 200, schema: "ConnectLinksResult", description: "OK" },
|
|
12337
|
+
alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job: true`)" },
|
|
12240
12338
|
errors: [400, 404, 409, 422]
|
|
12241
12339
|
}
|
|
12242
12340
|
},
|
|
@@ -12291,7 +12389,7 @@ var OPS = {
|
|
|
12291
12389
|
ok: {
|
|
12292
12390
|
status: 202,
|
|
12293
12391
|
schema: "JobAccepted",
|
|
12294
|
-
description: "Started: its job's result is the code and the lines verify printed"
|
|
12392
|
+
description: "Started: its job's result is FactsApplyResult: the code and the lines verify printed, and (3.14.0) leftOut and leftOutRepos when repos wrote with rejected facts left out (applied, code 0)"
|
|
12295
12393
|
},
|
|
12296
12394
|
errors: [409]
|
|
12297
12395
|
}
|
|
@@ -14044,6 +14142,7 @@ var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSI
|
|
|
14044
14142
|
// packages/core/dist/cancel.js
|
|
14045
14143
|
import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
|
|
14046
14144
|
var store = new AsyncLocalStorage2();
|
|
14145
|
+
var commits = new AsyncLocalStorage2();
|
|
14047
14146
|
|
|
14048
14147
|
// packages/core/dist/assistant-actor.js
|
|
14049
14148
|
init_ai();
|
|
@@ -14613,13 +14712,13 @@ function fsScanCache(dir) {
|
|
|
14613
14712
|
throw new Error(`unsafe repo name: ${repo}`);
|
|
14614
14713
|
const keep = new Set(keepCommits);
|
|
14615
14714
|
let removed = 0;
|
|
14616
|
-
let
|
|
14715
|
+
let commits2;
|
|
14617
14716
|
try {
|
|
14618
|
-
|
|
14717
|
+
commits2 = await readdir2(join3(dir, repo));
|
|
14619
14718
|
} catch {
|
|
14620
14719
|
return 0;
|
|
14621
14720
|
}
|
|
14622
|
-
for (const c of
|
|
14721
|
+
for (const c of commits2) {
|
|
14623
14722
|
if (!keep.has(c)) {
|
|
14624
14723
|
await rm(join3(dir, repo, c), { recursive: true, force: true });
|
|
14625
14724
|
removed++;
|
package/package.json
CHANGED