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

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.
@@ -1,5 +1,5 @@
1
1
  import { type JudgmentStore } from "./judgments.js";
2
- import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
2
+ import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionRole, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
3
3
  /**
4
4
  * Questions as files (ADR 0078): raise, list, read and answer questions/<id>.yaml. The CLI
5
5
  * (atticus questions) and the local API (/api/questions) both call these, so the app and the
@@ -47,6 +47,17 @@ export interface AskedBy {
47
47
  }
48
48
  /** An open question from what an AI step raised. */
49
49
  export declare function questionFromDraft(d: QuestionDraft, by: AskedBy): Question;
50
+ /**
51
+ * ADR 0191: a person re-routes a question to another role (a business question the architect was
52
+ * given goes to the product owner). `role` becomes the new one and `routed` says from which, by
53
+ * whom and when; what it asks follows the role unless the AI tagged it. Open or answered alike:
54
+ * the answer, if any, stays. Written only if the file is as it was read.
55
+ */
56
+ export declare function routeQuestion(root: string, id: string, o: {
57
+ role: QuestionRole;
58
+ by: string;
59
+ at: string;
60
+ }): Promise<Question>;
50
61
  /**
51
62
  * Write a question as it is (a person's comment on a critic finding, ADR 0124 addendum D-app,
52
63
  * is a question they answered as they asked it). Every other writer goes through
@@ -227,8 +238,8 @@ export declare function raiseQuestions(root: string, drafts: QuestionDraft[], by
227
238
  }>;
228
239
  /**
229
240
  * Rewrite questions/<id>.yaml files written at an older question schema version (1, ADR 0078;
230
- * 2, ADR 0117) at the current one (3, ADR 0153): only the version changes, since what each
231
- * version adds is optional. Returns the files, relative to the root; with dryRun, the files it
241
+ * 2, ADR 0117; 3, ADR 0153; 4, ADR 0162; 5, ADR 0181) at the current one (6, ADR 0191): only the
242
+ * version changes, since what each version adds is optional. Returns the files, relative to the root; with dryRun, the files it
232
243
  * would rewrite.
233
244
  */
234
245
  export declare function migrateQuestions(root: string, o?: {
@@ -307,6 +318,20 @@ export interface AnswerInput {
307
318
  batch?: string;
308
319
  /** ADR 0181: a person's rule applies it, from their correction. */
309
320
  rule?: AppliedRule;
321
+ /**
322
+ * Beta.24 review: Ignore, for a question about where calls go: they aren't real calls (CI/CD, a
323
+ * test, a template), so the join leaves them. In place of option and text; the reason, when
324
+ * given, is the answer's words (`Ignore: <reason>`), else the Ignore option is picked (added to
325
+ * the question's options when it was asked before Ignore was offered).
326
+ */
327
+ ignore?: {
328
+ reason?: string;
329
+ };
330
+ /**
331
+ * Beta.24 review: the id of the system `beforeWrite` adds to the profile, which the answer's
332
+ * words name, so they aren't refused as naming nothing.
333
+ */
334
+ adds?: string;
310
335
  }
311
336
  /**
312
337
  * Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
@@ -1,7 +1,8 @@
1
1
  /**
2
- * roles.yaml version 1 → 2 (ADR 0140). Version 2 adds `teams`; a file without them names no
3
- * team, as version 1 did, so the step writes the new number only and keeps the file's comments,
4
- * order and line layout (`atticus upgrade`'s roles-v2).
2
+ * roles.yaml version 1 → 2 (ADR 0140) → 3 (ADR 0191). Version 2 adds `teams`, version 3 who
3
+ * takes each role (`defaults`, a team's `roles`); a file without them names none, as before, so
4
+ * the step writes the new number only and keeps the file's comments, order and line layout
5
+ * (`atticus upgrade`'s roles-v2, which writes the current version).
5
6
  */
6
7
  export declare function migrateRolesText(text: string): {
7
8
  text: string;
@@ -0,0 +1,165 @@
1
+ /**
2
+ * ADR 0187: what a command run outside the app prints, for the app's Console. A long command
3
+ * (`atticus map`, `verify`, `scan`, `workspace sync`, a task run, ...) run in a terminal, by an
4
+ * editor or by a Copilot session keeps:
5
+ *
6
+ * - `.atticus/logs/runs/<runId>.log`: the lines it printed, each redacted as the local log is
7
+ * (ADR 0050's redactText: no secrets, tokens, credentials in URLs or home folder), with no
8
+ * colour codes; bounded (its last lines are kept past RUN_LOG_MAX_BYTES).
9
+ * - `.atticus/logs/running/<runId>.json`: who and what — the command words, the ids it was given
10
+ * (repo, change, run and task ids: words that look like an id and nothing else), the names of
11
+ * its flags (never their values), the process and a hash of the machine's name, when it
12
+ * started, and how it ended (its exit code), written again when it ends. While it runs it is
13
+ * written again every RUN_HEARTBEAT_MS (`beatAt`), and on Linux it keeps when its process
14
+ * started (`procStart`, from /proc): a process id used again by another process, or a run
15
+ * silent past RUN_SILENT_MS, is a run that ended without saying.
16
+ *
17
+ * Only the last RUN_LOG_KEEP runs are kept. `.atticus/logs/` is this machine's own (never
18
+ * committed). The names have no `:` (Windows). Nothing here loads a schema: the command line
19
+ * starts a run before it knows anything else. Writing never throws: a run log that can't be
20
+ * written is skipped, never failing the command it describes.
21
+ */
22
+ export declare const RUN_LOG_KEEP = 50;
23
+ export declare const RUN_LOG_MAX_BYTES: number;
24
+ /** A line longer than this is cut (a minified file printed whole). */
25
+ export declare const RUN_LOG_LINE_MAX = 4000;
26
+ /** The lines a read gives at most. */
27
+ export declare const RUN_LOG_READ_MAX = 5000;
28
+ /** A running command writes its record again this often. */
29
+ export declare const RUN_HEARTBEAT_MS = 30000;
30
+ /** A running record that beats, silent (record and log) for longer than this, has ended. */
31
+ export declare const RUN_SILENT_MS: number;
32
+ /** `20261109-101530-4242-ab12`: when (UTC), the process, and a little randomness. */
33
+ export declare const TERMINAL_RUN_ID: RegExp;
34
+ export declare const runLogsDirOf: (root: string) => string;
35
+ export declare const runningDirOf: (root: string) => string;
36
+ export type StartedBy = "terminal" | "vscode" | "intellij" | "copilot";
37
+ export type TerminalRunState = "running" | "done" | "failed" | "cancelled";
38
+ export interface TerminalRunRecord {
39
+ schemaVersion: 1;
40
+ runId: string;
41
+ pid: number;
42
+ /** A hash of the machine's name: whether the process can be looked for here. */
43
+ host: string;
44
+ title: string;
45
+ command: string[];
46
+ flags: string[];
47
+ startedBy: StartedBy;
48
+ startedAt: string;
49
+ state: TerminalRunState;
50
+ finishedAt?: string;
51
+ exitCode?: number;
52
+ /** Lines printed so far (as of the last write of the record; the log has them all). */
53
+ lines: number;
54
+ /** Lines no longer in the log (the log keeps its last lines). */
55
+ dropped: number;
56
+ /** When the process started, as the system says (Linux: /proc), to tell a reused pid. */
57
+ procStart?: string;
58
+ /** When a running command last wrote its record (every RUN_HEARTBEAT_MS). */
59
+ beatAt?: string;
60
+ }
61
+ /** A record as read: `stale` when its process is gone though it never said it ended. */
62
+ export type TerminalRunView = TerminalRunRecord & {
63
+ stale?: true;
64
+ };
65
+ export declare function recordedCommand(positionals: readonly string[], flags: readonly string[]): boolean;
66
+ /** The command words, ids and flag names of a run, and its title. */
67
+ export declare function runTitle(positionals: readonly string[], flags: readonly string[]): {
68
+ command: string[];
69
+ title: string;
70
+ };
71
+ /** Where the run was started, as its environment says. */
72
+ export declare function startedByOf(env?: NodeJS.ProcessEnv): StartedBy;
73
+ /**
74
+ * When a process started, as Linux keeps it (/proc/<pid>/stat's starttime, in ticks since boot):
75
+ * one file read, no command run. Undefined elsewhere, or when it can't be read.
76
+ */
77
+ export declare function procStartOf(pid: number): string | undefined;
78
+ /** A printed text as the lines the log keeps: no colour codes, no \r, each redacted and cut. */
79
+ export declare function runLogLines(text: string, o?: {
80
+ home?: string;
81
+ user?: string;
82
+ }): string[];
83
+ export interface TerminalRunRecorder {
84
+ readonly runId: string;
85
+ /** Print a line (or several, split at newlines) to the run's log. */
86
+ line(text: string): void;
87
+ /** Record how it ended: 0 done, 130 or 143 (Ctrl+C, a stop) cancelled, else failed. */
88
+ end(code: number, how?: "crash"): void;
89
+ }
90
+ export interface StartRunOptions {
91
+ positionals: readonly string[];
92
+ flags: readonly string[];
93
+ env?: NodeJS.ProcessEnv;
94
+ now?: () => Date;
95
+ pid?: number;
96
+ keep?: number;
97
+ maxBytes?: number;
98
+ redact?: {
99
+ home?: string;
100
+ user?: string;
101
+ };
102
+ /**
103
+ * Record the end on the process's exit, Ctrl+C and SIGTERM too, when nothing else did (the
104
+ * command line passes true; a test doesn't).
105
+ */
106
+ hookProcess?: boolean;
107
+ /** Write the record again this often while it runs. Default RUN_HEARTBEAT_MS with hookProcess. */
108
+ heartbeatMs?: number;
109
+ /** When this process started (procStartOf, for its own pid only). */
110
+ procStart?: () => string | undefined;
111
+ /** Whether a process is there (pidAlive), for the runs pruned as this one starts. */
112
+ alive?: (pid: number) => boolean;
113
+ }
114
+ /**
115
+ * Start a run's files. Undefined when they can't be written (the run goes on without them).
116
+ * The caller checks `recordedCommand` first.
117
+ */
118
+ export declare function startTerminalRun(root: string, o: StartRunOptions): TerminalRunRecorder | undefined;
119
+ /** Whether a process is there: signal 0 asks without sending anything. */
120
+ export declare function pidAlive(pid: number): boolean;
121
+ /**
122
+ * The runs kept, newest first. A run still `running` whose process is gone on this machine (or
123
+ * that started days ago elsewhere) is `stale`: it ended without saying (closed terminal, a crash).
124
+ */
125
+ export declare function readTerminalRuns(root: string, o?: {
126
+ alive?: (pid: number) => boolean;
127
+ now?: () => Date;
128
+ /** When a process started (procStartOf). */
129
+ startOf?: (pid: number) => string | undefined;
130
+ }): TerminalRunView[];
131
+ /** One run as read now, or undefined. */
132
+ export declare const readTerminalRun: (root: string, runId: string, o?: {
133
+ alive?: (pid: number) => boolean;
134
+ now?: () => Date;
135
+ startOf?: (pid: number) => string | undefined;
136
+ }) => TerminalRunView | undefined;
137
+ /**
138
+ * A run's lines from a line on (`from`, counted from its first line ever), at most `max`; without
139
+ * `from`, its last `max`. `total` is how many it has printed. Undefined for no such run.
140
+ */
141
+ export declare function readTerminalRunLines(root: string, runId: string, from?: number, max?: number): {
142
+ from: number;
143
+ lines: string[];
144
+ total: number;
145
+ } | undefined;
146
+ /** Where a tail of a run's log has read to: the next line's number and its byte in the file. */
147
+ export interface RunLogTail {
148
+ line: number;
149
+ bytes: number;
150
+ /** The record's dropped count and the file (its inode) when read: either changing is a cut. */
151
+ dropped: number;
152
+ ino: number;
153
+ }
154
+ /**
155
+ * A run's new lines since `at` (where the last tail read to), at most `max`: only the bytes
156
+ * added are read. Without `at`, or when the log was cut meanwhile, the whole log is read once:
157
+ * its last `max` lines without `at`, else from `at.line` (or the first line kept, when those were
158
+ * dropped). `more` says lines past `max` wait for the next read. Undefined for no such run.
159
+ */
160
+ export declare function tailTerminalRunLines(root: string, runId: string, at: RunLogTail | undefined, max?: number): {
161
+ from: number;
162
+ lines: string[];
163
+ at: RunLogTail;
164
+ more: boolean;
165
+ } | undefined;
@@ -108,8 +108,8 @@ export declare const ContextSource: z.ZodObject<{
108
108
  pattern: "pattern";
109
109
  code: "code";
110
110
  document: "document";
111
- catalog: "catalog";
112
111
  artifact: "artifact";
112
+ catalog: "catalog";
113
113
  checklist: "checklist";
114
114
  skill: "skill";
115
115
  instruction: "instruction";
@@ -134,8 +134,8 @@ export declare const ContextPackManifest: z.ZodObject<{
134
134
  pattern: "pattern";
135
135
  code: "code";
136
136
  document: "document";
137
- catalog: "catalog";
138
137
  artifact: "artifact";
138
+ catalog: "catalog";
139
139
  checklist: "checklist";
140
140
  skill: "skill";
141
141
  instruction: "instruction";
@@ -8,14 +8,14 @@ import { z } from "zod";
8
8
  export declare const DIALECT_SCHEMA_VERSION: 1;
9
9
  /** Grammars shipped with Atticus for syntax matches (ADR 0060). */
10
10
  export declare const SyntaxLanguage: z.ZodEnum<{
11
+ python: "python";
12
+ go: "go";
11
13
  java: "java";
12
14
  kotlin: "kotlin";
13
15
  typescript: "typescript";
14
16
  tsx: "tsx";
15
17
  javascript: "javascript";
16
18
  c_sharp: "c_sharp";
17
- python: "python";
18
- go: "go";
19
19
  scala: "scala";
20
20
  ruby: "ruby";
21
21
  php: "php";
@@ -59,14 +59,14 @@ export declare const DialectMatch: z.ZodUnion<readonly [z.ZodObject<{
59
59
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
60
60
  syntax: z.ZodString;
61
61
  language: z.ZodOptional<z.ZodEnum<{
62
+ python: "python";
63
+ go: "go";
62
64
  java: "java";
63
65
  kotlin: "kotlin";
64
66
  typescript: "typescript";
65
67
  tsx: "tsx";
66
68
  javascript: "javascript";
67
69
  c_sharp: "c_sharp";
68
- python: "python";
69
- go: "go";
70
70
  scala: "scala";
71
71
  ruby: "ruby";
72
72
  php: "php";
@@ -208,14 +208,14 @@ export declare const DialectRule: z.ZodObject<{
208
208
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
209
209
  syntax: z.ZodString;
210
210
  language: z.ZodOptional<z.ZodEnum<{
211
+ python: "python";
212
+ go: "go";
211
213
  java: "java";
212
214
  kotlin: "kotlin";
213
215
  typescript: "typescript";
214
216
  tsx: "tsx";
215
217
  javascript: "javascript";
216
218
  c_sharp: "c_sharp";
217
- python: "python";
218
- go: "go";
219
219
  scala: "scala";
220
220
  ruby: "ruby";
221
221
  php: "php";
@@ -405,14 +405,14 @@ export declare const DialectLookup: z.ZodObject<{
405
405
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
406
406
  syntax: z.ZodString;
407
407
  language: z.ZodOptional<z.ZodEnum<{
408
+ python: "python";
409
+ go: "go";
408
410
  java: "java";
409
411
  kotlin: "kotlin";
410
412
  typescript: "typescript";
411
413
  tsx: "tsx";
412
414
  javascript: "javascript";
413
415
  c_sharp: "c_sharp";
414
- python: "python";
415
- go: "go";
416
416
  scala: "scala";
417
417
  ruby: "ruby";
418
418
  php: "php";
@@ -534,14 +534,14 @@ export declare const Dialect: z.ZodObject<{
534
534
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
535
535
  syntax: z.ZodString;
536
536
  language: z.ZodOptional<z.ZodEnum<{
537
+ python: "python";
538
+ go: "go";
537
539
  java: "java";
538
540
  kotlin: "kotlin";
539
541
  typescript: "typescript";
540
542
  tsx: "tsx";
541
543
  javascript: "javascript";
542
544
  c_sharp: "c_sharp";
543
- python: "python";
544
- go: "go";
545
545
  scala: "scala";
546
546
  ruby: "ruby";
547
547
  php: "php";
@@ -600,14 +600,14 @@ export declare const Dialect: z.ZodObject<{
600
600
  contains: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
601
601
  syntax: z.ZodString;
602
602
  language: z.ZodOptional<z.ZodEnum<{
603
+ python: "python";
604
+ go: "go";
603
605
  java: "java";
604
606
  kotlin: "kotlin";
605
607
  typescript: "typescript";
606
608
  tsx: "tsx";
607
609
  javascript: "javascript";
608
610
  c_sharp: "c_sharp";
609
- python: "python";
610
- go: "go";
611
611
  scala: "scala";
612
612
  ruby: "ruby";
613
613
  php: "php";
@@ -59,6 +59,7 @@ export declare const FactCorrection: z.ZodObject<{
59
59
  config: "config";
60
60
  component: "component";
61
61
  field: "field";
62
+ dependency: "dependency";
62
63
  term: "term";
63
64
  framework: "framework";
64
65
  entry: "entry";
@@ -66,6 +67,7 @@ export declare const FactCorrection: z.ZodObject<{
66
67
  call: "call";
67
68
  deploy: "deploy";
68
69
  flow: "flow";
70
+ artifact: "artifact";
69
71
  }>;
70
72
  file: z.ZodString;
71
73
  line: z.ZodNumber;
@@ -128,6 +130,11 @@ type CallLike = {
128
130
  value: string;
129
131
  };
130
132
  };
133
+ /**
134
+ * Review round 2 (beta.23): a person's newest edit of where a call goes (an `edit` setting `to`,
135
+ * not the AI's), or none.
136
+ */
137
+ export declare function personEditOfTo(f: CallLike, corrections: readonly FactCorrection[]): FactCorrection | undefined;
131
138
  /**
132
139
  * G1 (ADR 0174): every pairing (`link`) that meets a call, newest first: on its cited line by its
133
140
  * id or by what it cites, or by its id where an edit of the same fact moved it to the line it is