@maycombhq/sdk 0.0.0-stage → 2.0.0-beta.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.
Files changed (75) hide show
  1. package/LICENSE +177 -0
  2. package/npm/cache.d.ts +47 -0
  3. package/npm/core/api.d.ts +6098 -0
  4. package/npm/core/assistant-actor.d.ts +15 -0
  5. package/npm/core/branches.d.ts +21 -0
  6. package/npm/core/cancel.d.ts +9 -0
  7. package/npm/core/catalog.d.ts +4733 -0
  8. package/npm/core/change-types-migrate.d.ts +10 -0
  9. package/npm/core/cite.d.ts +54 -0
  10. package/npm/core/curated.d.ts +37 -0
  11. package/npm/core/facts-callers.d.ts +150 -0
  12. package/npm/core/facts-carry.d.ts +36 -0
  13. package/npm/core/facts-join-prototype.d.ts +177 -0
  14. package/npm/core/facts-join-vendor.d.ts +92 -0
  15. package/npm/core/facts-join.d.ts +256 -0
  16. package/npm/core/facts.d.ts +94 -0
  17. package/npm/core/fs.d.ts +47 -0
  18. package/npm/core/gates-migrate.d.ts +10 -0
  19. package/npm/core/host-questions.d.ts +24 -0
  20. package/npm/core/identity.d.ts +17 -0
  21. package/npm/core/index.d.ts +62 -0
  22. package/npm/core/json-schema.d.ts +20 -0
  23. package/npm/core/judgments.d.ts +63 -0
  24. package/npm/core/light.d.ts +8 -0
  25. package/npm/core/log.d.ts +49 -0
  26. package/npm/core/manifest-edit.d.ts +48 -0
  27. package/npm/core/merge.d.ts +78 -0
  28. package/npm/core/metarepo.d.ts +83 -0
  29. package/npm/core/migrate.d.ts +31 -0
  30. package/npm/core/migration-files.d.ts +13 -0
  31. package/npm/core/orgpack-defaults.d.ts +194 -0
  32. package/npm/core/orgpack-load.d.ts +86 -0
  33. package/npm/core/questions.d.ts +267 -0
  34. package/npm/core/record-cache.d.ts +52 -0
  35. package/npm/core/refs.d.ts +9 -0
  36. package/npm/core/repo-description.d.ts +44 -0
  37. package/npm/core/runtime-migrate.d.ts +11 -0
  38. package/npm/core/schema/ai.d.ts +397 -0
  39. package/npm/core/schema/change.d.ts +244 -0
  40. package/npm/core/schema/common.d.ts +135 -0
  41. package/npm/core/schema/dialect.d.ts +801 -0
  42. package/npm/core/schema/executors.d.ts +396 -0
  43. package/npm/core/schema/fact-corrections.d.ts +55 -0
  44. package/npm/core/schema/facts.d.ts +1476 -0
  45. package/npm/core/schema/frameworks.d.ts +371 -0
  46. package/npm/core/schema/judgment.d.ts +77 -0
  47. package/npm/core/schema/kinds.d.ts +5166 -0
  48. package/npm/core/schema/layout.d.ts +25 -0
  49. package/npm/core/schema/orgpack.d.ts +1167 -0
  50. package/npm/core/schema/plugin.d.ts +73 -0
  51. package/npm/core/schema/question.d.ts +152 -0
  52. package/npm/core/schema/repo-type.d.ts +109 -0
  53. package/npm/core/schema/review.d.ts +558 -0
  54. package/npm/core/schema/scan-settings.d.ts +34 -0
  55. package/npm/core/schema/scan-verify.d.ts +535 -0
  56. package/npm/core/schema/spec.d.ts +269 -0
  57. package/npm/core/schema/version.d.ts +9 -0
  58. package/npm/core/schema/workspace.d.ts +312 -0
  59. package/npm/core/serialize.d.ts +17 -0
  60. package/npm/core/sources-migrate.d.ts +15 -0
  61. package/npm/core/specs.d.ts +66 -0
  62. package/npm/core/tar-read.d.ts +13 -0
  63. package/npm/core/template.d.ts +101 -0
  64. package/npm/core/words.d.ts +13 -0
  65. package/npm/core/zip-read.d.ts +37 -0
  66. package/npm/core/zip.d.ts +13 -0
  67. package/npm/fs-repo.d.ts +34 -0
  68. package/npm/index.d.ts +6 -0
  69. package/npm/index.js +8892 -0
  70. package/npm/parse-cache.d.ts +97 -0
  71. package/npm/plugin.d.ts +89 -0
  72. package/npm/runner.d.ts +72 -0
  73. package/npm/sandbox.d.ts +80 -0
  74. package/package.json +28 -3
  75. package/README.md +0 -3
@@ -0,0 +1,256 @@
1
+ import type { CatalogRecord } from "./catalog.js";
2
+ import type { Fact, FactOf } from "./schema/facts.js";
3
+ /**
4
+ * The estate join from facts (ADR 0124 addendum C-join): every call a repo's facts name, joined
5
+ * to the entry of the repo that serves it, deterministically and with a citation at both ends.
6
+ *
7
+ * Which repo a call goes to is read, in order, from: a person's answer; the call's `to` (a
8
+ * component, or a repo, of the estate); the host, or the base URL a config fact gives, that a
9
+ * repo lists in the manifest (or a host whose first label is a component). A host nobody lists
10
+ * is asked (`Which repo answers on <host>?`), never guessed, and a call whose `to` names an
11
+ * outside system (or names something outside the estate and has a host) is left to that name.
12
+ * A call with no host whose `to` names nothing in the estate (a relative call whose reader
13
+ * guessed a name), or that names nothing, joins the one entry of the caller's own repo that
14
+ * serves that method and path (or gRPC/SOAP name) in the same shape, else the one of the
15
+ * estate, marked inferred; two or more is a question. A publish joins every listener of its topic.
16
+ *
17
+ * Then the fields that cross: a caller's request fields to the callee entry's, the callee's
18
+ * response fields back, a message's to the listener's, by name (last dotted part, case, `_`
19
+ * and `-` aside), each with the column the receiving side stores it in when a store under the
20
+ * entry writes it (the field's `mappedTo`, else by name). A sent field nothing takes is a gap.
21
+ *
22
+ * Through a gateway (ADR 0124 addendum A-gateway): a call that lands on a gateway's route (an
23
+ * entry of a repo the manifest types `gateway`, or one cited in an Apigee bundle) whose
24
+ * forwarding calls (`from` the route) all join one entry joins that entry, with the path the
25
+ * service receives after the gateway's rewrite, and keeps the hop (the route, its forwarding
26
+ * call and the TargetServer or KVM config that ties it to a host). A route whose forwarding call
27
+ * is asked or missed, or that forwards to several services, is joined at the gateway, as before.
28
+ * A base whose config values (one per environment) are hosts different repos answer on is asked,
29
+ * never one of them guessed.
30
+ *
31
+ * Through several gateways (A-gateway2): where a route forwards into another gateway's route, the
32
+ * walk goes on, so `gateway` is the hops in order (caller → gateway A → gateway B → service) and
33
+ * `path` is what the last one's target receives. Each hop keeps its own auth and the `scopes` its
34
+ * route demands, and is marked `internal` or `external` when something says which: the repo's
35
+ * manifest type (`gateway-external`, `gateway-internal`), else the proxy's own `VirtualHost`
36
+ * config fact. Nothing says, the hop is just a gateway. The walk is bounded (`MAX_GATEWAY_HOPS`)
37
+ * and a route that forwards back into a gateway already in the path is a question (`cycle`), not
38
+ * a loop; a walk that runs past the bound is a question too. The join stops at the last gateway
39
+ * whose next hop is asked, missed or forwards to several services, exactly as one hop does.
40
+ *
41
+ * Pure: the same facts and answers give the same result, whatever order the repos come in.
42
+ */
43
+ export interface JoinRepo {
44
+ repo: string;
45
+ facts: readonly Fact[];
46
+ /** The component a fact with none belongs to (the manifest's); the repo when left out. */
47
+ component?: string;
48
+ /** Hosts the repo answers on (repos.manifest.yaml). */
49
+ hosts?: readonly string[];
50
+ /** Modules with hosts of their own (ADR 0057). */
51
+ modules?: readonly {
52
+ component: string;
53
+ hosts: readonly string[];
54
+ }[];
55
+ /** An API gateway (the manifest's `type: gateway`): its entries are routes it forwards. */
56
+ gateway?: boolean;
57
+ /**
58
+ * Which side of the organisation this gateway faces, when the manifest's repo type says
59
+ * (`gateway-external`, `gateway-internal`): a hop through it is marked so (A-gateway2). Left
60
+ * out, the proxy's own `VirtualHost` config fact is read instead, and failing that the hop is
61
+ * just a gateway.
62
+ */
63
+ facing?: GatewayFacing;
64
+ }
65
+ /** An Apigee proxy or shared flow bundle's file: its entries are gateway routes whatever the repo. */
66
+ export declare const APIGEE_BUNDLE: RegExp;
67
+ /** Whether a gateway hop stays inside the organisation or faces a partner or the internet. */
68
+ export type GatewayFacing = "internal" | "external";
69
+ /**
70
+ * How far the walk through gateways goes before it gives up and asks (A-gateway2). Four is a
71
+ * gateway at each of three boundaries and one more: past that, nobody means it.
72
+ */
73
+ export declare const MAX_GATEWAY_HOPS = 4;
74
+ /** The words a `VirtualHost` (or a manifest repo type) uses for each side (A-gateway2). */
75
+ export interface FacingWords {
76
+ internal: readonly string[];
77
+ external: readonly string[];
78
+ }
79
+ /**
80
+ * The default words, overridable per estate (`joinFacts`'s `facing`), because which virtual host
81
+ * means which side is each estate's own convention. A value that says neither leaves the hop a
82
+ * plain gateway: the join never guesses from a basepath or a host's shape.
83
+ */
84
+ export declare const FACING_WORDS: FacingWords;
85
+ /** The hop a call takes through a gateway: the route it lands on and the call that forwards it. */
86
+ export interface GatewayHop {
87
+ /** The gateway's route (its entry fact). */
88
+ entry: FactEnd;
89
+ /** The gateway's forwarding call, whose path is the one the next hop or the service receives. */
90
+ call: FactEnd;
91
+ /** The config fact (a TargetServer, a KVM entry) that ties the forwarding call to its host. */
92
+ tie?: FactEnd;
93
+ /** The catalog GatewayRoute of the route. */
94
+ route: string;
95
+ /** The auth a caller meets at this hop, when the route's facts say (A-gateway2). */
96
+ auth?: string;
97
+ /** The scopes this hop's route demands of the caller's token, in the facts' order (A-gateway2). */
98
+ scopes?: string[];
99
+ /** Which side this gateway faces, when the manifest or the proxy's virtual host says. */
100
+ facing?: GatewayFacing;
101
+ }
102
+ /** One end of a join: a fact, its repo and component, and the line it cites. */
103
+ export interface FactEnd {
104
+ repo: string;
105
+ fact: string;
106
+ component: string;
107
+ /** path:line of the fact's citation. */
108
+ at: string;
109
+ }
110
+ /**
111
+ * How the callee was found: `answer` (a person named it), `named` (the call's `to` names the
112
+ * component), `repo` (its `to` names the repo), `host` (a host or base URL the manifest lists,
113
+ * or the component's own name as the host), `path` (no target named: the only entry of the
114
+ * estate that serves it), `topic` (a listener of the published topic).
115
+ */
116
+ export type JoinHow = "answer" | "named" | "repo" | "host" | "path" | "topic";
117
+ export interface FactJoin {
118
+ call: FactEnd;
119
+ entry: FactEnd;
120
+ /** The config fact that gives the call's base URL, when one ties the call to the host. */
121
+ tie?: FactEnd;
122
+ how: JoinHow;
123
+ /**
124
+ * A join by path (the join fallback): nobody named the callee, so it is inferred. `within`
125
+ * says where the one entry that serves the call was found: the caller's own repo first, else
126
+ * the estate; `named` is the target the call gave, when it named one the estate doesn't have.
127
+ */
128
+ inferred?: {
129
+ within: "repo" | "estate";
130
+ named?: string;
131
+ };
132
+ /**
133
+ * The gateway hops the call went through to reach `entry`, in the order it meets them
134
+ * (A-gateway, many hops in A-gateway2); `path` is what the last hop's target receives. Left
135
+ * out when the call reaches the entry directly.
136
+ */
137
+ gateway?: GatewayHop[];
138
+ /**
139
+ * Every scope the call's token must hold to get through, the hops' in order, each once
140
+ * (A-gateway2). Left out when no hop demands one.
141
+ */
142
+ scopes?: string[];
143
+ callType: string;
144
+ method?: string;
145
+ /** The path, gRPC or SOAP name, or topic the entry serves, as the entry writes it. */
146
+ path: string;
147
+ /** The catalog Interface of the join. */
148
+ interface: string;
149
+ }
150
+ export interface FactJoinAsk {
151
+ call: FactEnd;
152
+ /**
153
+ * `unknown-host`: no repo lists the host; `ambiguous`: more than one entry could answer;
154
+ * `cycle`: the gateway routes the call passes through lead back into a gateway it has already
155
+ * been through, so where the call ends can't be read from the facts (A-gateway2).
156
+ */
157
+ reason: "unknown-host" | "ambiguous" | "cycle";
158
+ host?: string;
159
+ question: string;
160
+ /** The entries that could answer (none for an unknown host). */
161
+ candidates: FactEnd[];
162
+ }
163
+ /** A call whose named target (a repo or component of the estate) has no entry for it. */
164
+ export interface FactJoinMiss {
165
+ call: FactEnd;
166
+ target: string;
167
+ message: string;
168
+ }
169
+ export interface FieldEnd {
170
+ repo: string;
171
+ fact: string;
172
+ name: string;
173
+ }
174
+ /** A field crossing a join: the sender's field, the receiver's, and where the receiver stores it. */
175
+ export interface FieldLink {
176
+ interface: string;
177
+ side: "request" | "response" | "message";
178
+ from: FieldEnd;
179
+ to: FieldEnd;
180
+ column?: {
181
+ table: string;
182
+ name: string;
183
+ fact?: string;
184
+ how: "mapped" | "name";
185
+ };
186
+ }
187
+ /** A field sent (or expected back) that the other side's facts don't have. */
188
+ export interface FieldGap {
189
+ interface: string;
190
+ side: "request" | "response" | "message";
191
+ field: FieldEnd;
192
+ message: string;
193
+ }
194
+ export interface FactsJoinResult {
195
+ joins: FactJoin[];
196
+ asks: FactJoinAsk[];
197
+ misses: FactJoinMiss[];
198
+ lineage: FieldLink[];
199
+ gaps: FieldGap[];
200
+ }
201
+ export interface JoinFactsInput {
202
+ repos: readonly JoinRepo[];
203
+ /** A person's answer naming the repo or component a call goes to: repo → call fact id → name. */
204
+ targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
205
+ /**
206
+ * Outside systems (the org pack's vendors), by id: a call whose `to` names one keeps it and
207
+ * is never joined by path to an entry of the estate.
208
+ */
209
+ outside?: readonly string[];
210
+ /**
211
+ * The words this estate's virtual hosts and gateway repo types use for each side of the
212
+ * organisation (A-gateway2). The defaults are `FACING_WORDS`; a value matching neither list
213
+ * leaves the hop a plain gateway.
214
+ */
215
+ facing?: FacingWords;
216
+ }
217
+ type Entry = FactOf<"entry">;
218
+ type Call = FactOf<"call">;
219
+ /** A field's name as compared: its last dotted part, letter case, `_` and `-` aside. */
220
+ export declare const fieldNameKey: (name: string) => string;
221
+ /**
222
+ * How well a called path matches a served one: 1000 the same; 500 less one for each served
223
+ * parameter standing for a literal of the call; 100 and up a catch-all route whose fixed part
224
+ * starts the call; the length of the shorter when it ends the other with a plain segment (a
225
+ * context path or base path in front); else 0.
226
+ */
227
+ export declare function routeScore(called: string, served: string): number;
228
+ /** How well a called gRPC or SOAP name matches a served one: the same, or the same short service and method. */
229
+ export declare function nameScore(called: string, served: string): number;
230
+ /** The question for a call no single repo answers: the same words as the facts-targets question. */
231
+ export declare function callTargetQuestion(f: Call, component: string): string;
232
+ /** The question for a call whose gateway routes lead back where they came from (A-gateway2). */
233
+ export declare function gatewayCycleQuestion(f: Call, component: string, gateway: string): string;
234
+ /** Join every call of the estate's facts to the entry that serves it, or say why not. */
235
+ export declare function joinFacts(input: JoinFactsInput): FactsJoinResult;
236
+ /** The path a joined Interface records: the entry's, normalised (a gRPC or SOAP name as written). */
237
+ export declare function servedPath(e: Entry): string;
238
+ /** A gateway route's GatewayRoute id: `gw-<component>-<method>-<path>`, no dots (as a hop names one). */
239
+ export declare function gatewayRouteId(n: {
240
+ component: string;
241
+ fact: Entry;
242
+ }): string;
243
+ /**
244
+ * A route's base path: the part of its citation (`cite.with`) its path starts with (an Apigee
245
+ * `<BasePath>`), else its whole path.
246
+ */
247
+ export declare function basePathOf(e: Entry): string;
248
+ /**
249
+ * The joins as C1 records: an Interface per call joined to an entry (a publish to each
250
+ * listener, as the merge would pair them), citing the caller's call, the config that ties it to
251
+ * the host and the callee's entry; and a FieldMapping per field that crosses, and
252
+ * per column the receiving side stores a field in. Mappings by name are inferred, by `mappedTo`
253
+ * verified.
254
+ */
255
+ export declare function joinRecords(result: FactsJoinResult, repos: readonly JoinRepo[]): CatalogRecord[];
256
+ export {};
@@ -0,0 +1,94 @@
1
+ import type { CatalogRecord } from "./catalog.js";
2
+ import { Fact, type FactOf } from "./schema/facts.js";
3
+ /**
4
+ * The facts file (ADR 0124): read, write and project into catalog C1.
5
+ *
6
+ * `parseFacts` reads JSONL (or a JSON array) and refuses anything the schema refuses, with the
7
+ * line it was on. `serializeFacts` writes one canonical line per fact, sorted by id, so the same
8
+ * facts give the same bytes. `projectFacts` turns facts into C1 records deterministically:
9
+ * nothing downstream of C1 has to know facts exist.
10
+ */
11
+ export interface FactIssue {
12
+ line?: number;
13
+ factId?: string;
14
+ code: string;
15
+ message: string;
16
+ }
17
+ export type ParseFactsResult = {
18
+ ok: true;
19
+ facts: Fact[];
20
+ } | {
21
+ ok: false;
22
+ issues: FactIssue[];
23
+ };
24
+ export declare function parseFacts(text: string): ParseFactsResult;
25
+ /** A line of a facts file that isn't a fact, with its number, its text and what is wrong. */
26
+ export type BadFactLine = {
27
+ line: number;
28
+ raw: string;
29
+ issues: FactIssue[];
30
+ };
31
+ /**
32
+ * One line of a facts file: the fact it holds, or what is wrong with it, or neither when the line
33
+ * is blank. `seen` holds the ids read so far and gains this one, so a repeated id keeps its first
34
+ * line. The whole of reading a line is here, so a reader that streams the file (ADR 0124 addendum
35
+ * A-room) and one that has the text in hand give the same facts and the same issues.
36
+ */
37
+ export declare function parseFactLine(raw: string, line: number, seen: Set<string>): {
38
+ fact?: Fact;
39
+ bad?: BadFactLine;
40
+ };
41
+ /**
42
+ * Read a JSONL facts file line by line, keeping every line that reads and returning the others
43
+ * with their issues, so one bad line (a capital in an id, a missing field) costs that fact, not
44
+ * the whole read (feedback from the A4 run). A repeated id keeps its first line.
45
+ *
46
+ * This takes the whole file as one string; a big repo's facts are read a line at a time instead
47
+ * (`streamFacts` in the CLI, ADR 0124 addendum A-room), through the same `parseFactLine`.
48
+ */
49
+ export declare function parseFactsLines(text: string): {
50
+ facts: Fact[];
51
+ bad: BadFactLine[];
52
+ };
53
+ /** One canonical JSON line per fact, sorted by id; the same facts give the same bytes. */
54
+ export declare function serializeFacts(facts: readonly Fact[]): string;
55
+ export interface ProjectOptions {
56
+ /** The System every projected Component belongs to. Default: the repo's slug. */
57
+ system?: string;
58
+ /** Overrides the facts' own `repo` as the evidence repo (a renamed clone, say). */
59
+ repo?: string;
60
+ }
61
+ export interface ProjectResult {
62
+ records: CatalogRecord[];
63
+ issues: FactIssue[];
64
+ /**
65
+ * The catalog id each fact became, by fact id, in id order (fields that became a Column or a
66
+ * Schema field are left out). A writer follows them through the catalog merge (ADR 0124, A3b).
67
+ */
68
+ ids: Record<string, string>;
69
+ }
70
+ /** A name as a part of a projected catalog id: its slug, with dots made dashes (a component, a store). */
71
+ export declare const factIdPart: (text: string) => string;
72
+ /** The Endpoint id an entry fact projects to in its component (`projectFacts`). */
73
+ export declare function entryEndpointId(f: FactOf<"entry">, component: string): string;
74
+ /**
75
+ * A call's normalised path: a gRPC method stays `package.Service/Method` and a SOAP operation
76
+ * `Contract/Operation` (a client may write either with a leading slash); an HTTP path loses a parameter's optional marker and constraint first
77
+ * (`{brandId:int?}`), so the `?` isn't read as a query string.
78
+ */
79
+ export declare function callPath(callType: string, path: string): string;
80
+ /**
81
+ * The `auth` an entry fact may put in the catalog (ADR 0124 addendum A-uncited): the claim stands
82
+ * in C1 only where a line is cited for it (`authCite`), or where a person made the fact, since
83
+ * that is their own word, marked as theirs. The facts file keeps what its writer wrote either
84
+ * way; this is the gate on the way into the catalog, so the catalog never says an auth no line
85
+ * was cited for, and the verifier's `authUncited` warning stays until a line is cited.
86
+ */
87
+ export declare function catalogAuth(f: FactOf<"entry">): FactOf<"entry">["auth"];
88
+ /**
89
+ * Facts to C1. Ids are made from the claims, so the same facts give the same ids:
90
+ * Endpoint `<component>.<method-path>`, Interface `if-<hash>`, DataStore `<store>`,
91
+ * Table `<store>.<table>`, Column `<store>.<table>.<column>`, Schema `<endpoint>.<side>`,
92
+ * Deployment `<component>.<env>`, Setting `<component>.<key>`, Flow `<component>.<name>`.
93
+ */
94
+ export declare function projectFacts(input: readonly Fact[], opts?: ProjectOptions): ProjectResult;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Write a file so a crash never leaves it half-written: write a temporary file beside it,
3
+ * then rename it over the old one (a rename within a folder is atomic on every platform
4
+ * Atticus supports). The temporary name is unique, so two writers never share it. On
5
+ * Windows a rename can fail for a moment while a virus scanner or indexer holds the file:
6
+ * it is retried a few times before giving up.
7
+ */
8
+ export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
9
+ export declare function renameRetrying(from: string, to: string, tries?: number): Promise<void>;
10
+ export interface LockInfo {
11
+ pid: number;
12
+ host: string;
13
+ startedAt: string;
14
+ what: string;
15
+ }
16
+ export declare class LockHeldError extends Error {
17
+ readonly held: LockInfo;
18
+ constructor(held: LockInfo);
19
+ }
20
+ /** Where a metarepo's locks live: .atticus/locks/, on this machine only (git-ignored). */
21
+ export declare const lockFileOf: (root: string, name: string) => string;
22
+ /** Read a lock: undefined when free; `stale` when its process is gone (it was cut short). */
23
+ export declare function readLock(root: string, name: string): Promise<(LockInfo & {
24
+ stale: boolean;
25
+ }) | undefined>;
26
+ /**
27
+ * Take a lock for a long write (a scan): one at a time per metarepo. A lock whose process is
28
+ * gone was cut short (a crash, a closed terminal); it is taken over and reported as
29
+ * `interrupted`, so the caller can say the last run didn't finish.
30
+ */
31
+ export declare function acquireLock(root: string, name: string, what: string, now?: () => Date): Promise<{
32
+ release: () => Promise<void>;
33
+ interrupted?: LockInfo;
34
+ }>;
35
+ /**
36
+ * What stays on this machine inside .atticus/: the person's settings, the log, locks, upgrade
37
+ * backups, the prompt and response history (ADR 0110), what `atticus probe` measured of the
38
+ * person's assistant (ADR 0124 addendum A-probe) and the parses kept between runs
39
+ * (`cache/`, record-cache.ts).
40
+ */
41
+ export declare const LOCAL_ONLY: readonly ["me.yaml", "logs/", "locks/", "backups/", "history/", "probe/", "cache/"];
42
+ /**
43
+ * Make sure .atticus/.gitignore keeps this machine's files out of Git. It lives inside
44
+ * .atticus/, so it works the same in a metarepo and in a repo adopted in place (where Atticus
45
+ * writes nothing outside .atticus/).
46
+ */
47
+ export declare function ensureLocalIgnore(root: string): Promise<void>;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * gates.yaml version 1 → 2 (ADR 0087). Version 2 reads a gate with no maxAuthorRounds as
3
+ * unlimited; version 1 read it as two rounds. So that nothing loosens without a person
4
+ * choosing it, the migration writes `maxAuthorRounds: 2` on every gate that left it out, and
5
+ * keeps the file's comments and order. Deleting that line afterwards makes the gate unlimited.
6
+ */
7
+ export declare function migrateGatesText(text: string): {
8
+ text: string;
9
+ changed: boolean;
10
+ };
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Which repo answers on a host (ADR 0088): a scan or atticus estate join asks, as a question
3
+ * file (ADR 0078), for each host the estate's calls name that no repo lists in its `hosts`;
4
+ * the answer writes the host under that repo's `hosts` in its repos.manifest.yaml.
5
+ */
6
+ /** The step that asks which repo answers on a host. */
7
+ export declare const HOSTS_STEP = "scan-hosts";
8
+ /** The last option of a hosts question: no repo of the estate answers on it. */
9
+ export declare const HOSTS_NONE = "None of these";
10
+ /** The question for a host, with its port when the calls name one: localhost:9966. */
11
+ export declare const hostQuestionText: (host: string) => string;
12
+ /** The host a hosts question asks about, read back from its words. */
13
+ export declare function hostOfQuestion(q: {
14
+ question: string;
15
+ }): string | undefined;
16
+ /**
17
+ * Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
18
+ * file's comments and order. `added` is false when the repo already lists it. Throws when no
19
+ * manifest lists the repo, or the host isn't one the manifest takes.
20
+ */
21
+ export declare function addManifestHost(root: string, repo: string, host: string): Promise<{
22
+ manifest: string;
23
+ added: boolean;
24
+ }>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Normalise an HTTP path or topic so the same interface found in different places
3
+ * (caller code, gateway route, callee controller) gets the same identity.
4
+ *
5
+ * - path parameters in any style ({id}, :id, <id>, ${id}) become "{}"
6
+ * - query strings and fragments are dropped
7
+ * - repeated and trailing slashes are removed; a leading slash is ensured for paths
8
+ * - topics (no leading slash in the input and no "/" at all) are returned trimmed
9
+ */
10
+ export declare function normalizePath(input: string): string;
11
+ /**
12
+ * Stable interface id: a hash of caller, callee, method and normalised path, so the same
13
+ * edge seen by several extractors merges into one Interface record.
14
+ */
15
+ export declare function interfaceId(from: string, to: string, method: string | undefined, path: string): string;
16
+ /** Lowercase slug suitable as a record id, built from free text such as a system name. */
17
+ export declare function slugify(text: string): string;
@@ -0,0 +1,62 @@
1
+ export * from "./schema/common.js";
2
+ export * from "./schema/kinds.js";
3
+ export * from "./schema/facts.js";
4
+ export * from "./schema/fact-corrections.js";
5
+ export * from "./facts.js";
6
+ export * from "./migration-files.js";
7
+ export * from "./facts-join.js";
8
+ export * from "./facts-join-vendor.js";
9
+ export * from "./facts-join-prototype.js";
10
+ export * from "./facts-carry.js";
11
+ export * from "./facts-callers.js";
12
+ export * from "./cite.js";
13
+ export * from "./catalog.js";
14
+ export * from "./identity.js";
15
+ export * from "./serialize.js";
16
+ export * from "./json-schema.js";
17
+ export * from "./schema/workspace.js";
18
+ export * from "./schema/change.js";
19
+ export * from "./branches.js";
20
+ export * from "./template.js";
21
+ export * from "./schema/dialect.js";
22
+ export * from "./schema/frameworks.js";
23
+ export * from "./schema/scan-settings.js";
24
+ export * from "./schema/scan-verify.js";
25
+ export * from "./schema/repo-type.js";
26
+ export * from "./schema/layout.js";
27
+ export * from "./schema/plugin.js";
28
+ export * from "./schema/review.js";
29
+ export * from "./schema/orgpack.js";
30
+ export * from "./schema/executors.js";
31
+ export * from "./orgpack-defaults.js";
32
+ export * from "./orgpack-load.js";
33
+ export * from "./schema/ai.js";
34
+ export * as Api from "./api.js";
35
+ export { API_VERSION, DEFAULT_PORT, openApiDocument } from "./api.js";
36
+ export * from "./merge.js";
37
+ export * from "./refs.js";
38
+ export * from "./curated.js";
39
+ export * from "./migrate.js";
40
+ export * from "./gates-migrate.js";
41
+ export * from "./change-types-migrate.js";
42
+ export * from "./sources-migrate.js";
43
+ export * from "./runtime-migrate.js";
44
+ export * from "./metarepo.js";
45
+ export * from "./fs.js";
46
+ export * from "./record-cache.js";
47
+ export * from "./log.js";
48
+ export * from "./zip.js";
49
+ export * from "./words.js";
50
+ export * from "./zip-read.js";
51
+ export * from "./tar-read.js";
52
+ export * from "./schema/question.js";
53
+ export * from "./questions.js";
54
+ export * from "./schema/judgment.js";
55
+ export * from "./judgments.js";
56
+ export * from "./host-questions.js";
57
+ export * from "./repo-description.js";
58
+ export * from "./manifest-edit.js";
59
+ export * from "./schema/spec.js";
60
+ export * from "./specs.js";
61
+ export * from "./cancel.js";
62
+ export * from "./assistant-actor.js";
@@ -0,0 +1,20 @@
1
+ import { type RecordKind } from "./schema/kinds.js";
2
+ /**
3
+ * JSON Schema for every record kind, generated from the zod source of truth, for editors,
4
+ * other tools and org-pack validation outside TypeScript.
5
+ */
6
+ export declare function catalogJsonSchemas(): Record<RecordKind, object>;
7
+ /**
8
+ * JSON Schema for the workspace files: repos.manifest.yaml, and a change's repos.yaml,
9
+ * change.yaml (its lifecycle state) and review/outcomes.yaml (ADR 0045), and a view's kept
10
+ * arrangement, diagrams/layouts/<view-key>.yaml (ADR 0081).
11
+ */
12
+ export declare function workspaceJsonSchemas(): Record<"RepoManifest" | "ChangeRepos" | "ChangeLifecycle" | "ChangeOutcomes" | "CatalogBaseline" | "MetarepoStamp" | "DiagramLayout", object>;
13
+ /** JSON Schema for the dialect rule file (C2) and checklist packs and findings (C3). */
14
+ export declare function rulesJsonSchemas(): Record<"Dialect" | "ChecklistPack" | "Finding", object>;
15
+ /** JSON Schema for every org-pack file (C6). */
16
+ export declare function orgPackJsonSchemas(): Record<string, object>;
17
+ /** JSON Schema for the AI runtime's run files (C5). */
18
+ export declare function aiJsonSchemas(): Record<string, object>;
19
+ /** The facts file the assistant writes (ADR 0124): one Fact per JSON line, or a FactsFile array. */
20
+ export declare function factsJsonSchemas(): Record<"Fact" | "FactsFile", object>;
@@ -0,0 +1,63 @@
1
+ import { Judgment, type JudgmentConfirmer, type JudgmentVerdict } from "./schema/judgment.js";
2
+ /**
3
+ * The judgments store (ADR 0117): judgments/<kind>/<key>.yaml, the key a hash of the inputs.
4
+ * Any step that asks a model a closed question about meaning keeps the answer here (the judge
5
+ * step in @maycombhq/ai, and the context engine's query expansion and rerank), so the same
6
+ * commit with the same inputs reads the stored verdict and never asks again, and a changed input
7
+ * invalidates only its own judgment.
8
+ *
9
+ * The interface is two calls, get and put by kind and key; `judgmentKey` makes the key.
10
+ */
11
+ export interface JudgmentStore {
12
+ get(kind: string, key: string): Promise<Judgment | undefined>;
13
+ /**
14
+ * Keep a judgment. A person's verdict on file is never replaced by a model's or a check's:
15
+ * the stored one comes back instead.
16
+ */
17
+ put(j: Judgment): Promise<Judgment>;
18
+ }
19
+ /**
20
+ * The key of a judgment: 24 hex characters of the sha256 of the kind and the inputs in
21
+ * canonical form (keys sorted, undefined left out), so the same inputs in any key order give
22
+ * the same key.
23
+ */
24
+ export declare function judgmentKey(kind: string, inputs: unknown): string;
25
+ /** A new judgment at the current schema version, its key made from the inputs. */
26
+ export declare function makeJudgment(o: {
27
+ kind: string;
28
+ inputs: Record<string, unknown>;
29
+ verdict: JudgmentVerdict;
30
+ confirmedBy: JudgmentConfirmer;
31
+ at: string;
32
+ value?: unknown;
33
+ quotes?: {
34
+ of: string;
35
+ text: string;
36
+ }[];
37
+ why?: string;
38
+ }): Judgment;
39
+ /** The store in the metarepo: judgments/ (or .atticus/judgments/ when adopted). */
40
+ export declare function fileJudgments(root: string): JudgmentStore & {
41
+ list(kind?: string): Promise<{
42
+ judgments: Judgment[];
43
+ problems: {
44
+ file: string;
45
+ message: string;
46
+ }[];
47
+ }>;
48
+ };
49
+ /** A store in memory, for tests and for a step run without a metarepo. */
50
+ export declare function memoryJudgments(initial?: Judgment[]): JudgmentStore & {
51
+ all(): Judgment[];
52
+ };
53
+ /**
54
+ * A person overrides a judgment: their verdict is kept, with the one it replaced under
55
+ * `overrides`. Every step that reads the judgment follows the person from then on.
56
+ */
57
+ export declare function overrideJudgment(store: JudgmentStore, kind: string, key: string, o: {
58
+ verdict: JudgmentVerdict;
59
+ value?: unknown;
60
+ name: string;
61
+ at: string;
62
+ why?: string;
63
+ }): Promise<Judgment>;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * `@maycombhq/core/light`: the few parts of core the command line needs before it knows which
3
+ * command runs (its help's first line and its log). They load no schema, no zod and no YAML
4
+ * reader, so `atticus --help` and the start of every command don't pay for building C1-C6.
5
+ * Each is the same export as the package's own (`@maycombhq/core`); nothing here is new.
6
+ */
7
+ export { SCHEMA_VERSION } from "./schema/version.js";
8
+ export { createLog, logFileOf, NO_LOG, type Log, type LogEntry, type LogLevel } from "./log.js";
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The local log (ADR 0050): one JSON object per line in `.atticus/logs/atticus.log`,
3
+ * kept on this machine. It records what ran (command and flag names, never their values),
4
+ * how it ended, how long it took and, on a crash, the error with its stack. Every entry is
5
+ * redacted before it is written: secrets, credentials in URLs, tokens and the person's home
6
+ * folder never reach the file.
7
+ */
8
+ export type LogLevel = "debug" | "info" | "warn" | "error" | "off";
9
+ export interface LogEntry {
10
+ at: string;
11
+ level: Exclude<LogLevel, "off">;
12
+ event: string;
13
+ [field: string]: unknown;
14
+ }
15
+ export interface Log {
16
+ readonly file: string;
17
+ debug(event: string, fields?: Record<string, unknown>): void;
18
+ info(event: string, fields?: Record<string, unknown>): void;
19
+ warn(event: string, fields?: Record<string, unknown>): void;
20
+ error(event: string, err: unknown, fields?: Record<string, unknown>): void;
21
+ }
22
+ export declare const LOG_MAX_BYTES: number;
23
+ export declare const LOG_KEEP = 3;
24
+ /** Where the log of a metarepo lives. */
25
+ export declare const logFileOf: (root: string) => string;
26
+ /** Strings with anything that looks like a secret replaced by "***", and home folders by "~". */
27
+ export declare function redactText(s: string, o?: {
28
+ home?: string;
29
+ user?: string;
30
+ }): string;
31
+ /** A value with secret-named keys masked and every string redacted. */
32
+ export declare function redact(v: unknown, o?: {
33
+ home?: string;
34
+ user?: string;
35
+ }): unknown;
36
+ /** The level from ATTICUS_LOG (debug, info, warn, error or off); info by default. */
37
+ export declare function logLevelFrom(env?: NodeJS.ProcessEnv): LogLevel;
38
+ /**
39
+ * A log for a metarepo. Writing never throws: a log that can't be written (a read-only folder,
40
+ * a full disk) is skipped rather than failing the command it describes.
41
+ */
42
+ export declare function createLog(root: string, o?: {
43
+ level?: LogLevel;
44
+ now?: () => Date;
45
+ maxBytes?: number;
46
+ keep?: number;
47
+ }): Log;
48
+ /** A log that writes nothing (tests, and commands run with no metarepo). */
49
+ export declare const NO_LOG: Log;