@yaag/runtime 0.14.1 → 0.15.0
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/package.json +1 -1
- package/src/catalog/catalog-entry.ts +25 -4
- package/src/catalog/catalog-fixture.ts +22 -8
- package/src/catalog/catalog-match.ts +9 -4
- package/src/catalog/catalog-result.ts +24 -3
- package/src/catalog/index.ts +1 -0
- package/src/catalog/program-scan.ts +3 -1
- package/src/catalog/registry-reader.ts +72 -19
- package/src/catalog/registry-schema.ts +114 -31
- package/src/index.ts +1 -0
package/package.json
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
|
-
* One registered Agent Definition
|
|
8
|
-
*
|
|
7
|
+
* One registered Agent Definition (ADR-0046, the registration exception to
|
|
8
|
+
* ADR-0019). A registry file also registers Orchestration Programs — see
|
|
9
|
+
* `ProgramEntry` (ADR-0050).
|
|
9
10
|
*
|
|
10
11
|
* `file` resolves relative to the directory of the declaring registry file,
|
|
11
12
|
* never to the current working directory. Only `name` is verifiable against
|
|
@@ -19,13 +20,30 @@ export interface AgentDefinitionEntry {
|
|
|
19
20
|
readonly tags?: readonly string[];
|
|
20
21
|
}
|
|
21
22
|
|
|
23
|
+
/**
|
|
24
|
+
* One registered Orchestration Program (ADR-0050). There is no `exportName`: a
|
|
25
|
+
* program is always the default export that `defineRun(...)` makes. Listing
|
|
26
|
+
* imports no module, thus the entry must declare `name`.
|
|
27
|
+
*
|
|
28
|
+
* `file` resolves relative to the directory of the declaring registry file,
|
|
29
|
+
* never to the current working directory.
|
|
30
|
+
*/
|
|
31
|
+
export interface ProgramEntry {
|
|
32
|
+
readonly file: string;
|
|
33
|
+
readonly name: string;
|
|
34
|
+
readonly description?: string;
|
|
35
|
+
readonly tags?: readonly string[];
|
|
36
|
+
}
|
|
37
|
+
|
|
22
38
|
/**
|
|
23
39
|
* The document one `registry.json` holds. The schema is lenient on purpose: an
|
|
24
40
|
* unknown key is preserved by the file and ignored by the parser, so an older
|
|
25
|
-
* yaag still reads a newer registry file.
|
|
41
|
+
* yaag still reads a newer registry file. The `programs` section is discovery
|
|
42
|
+
* only: it makes a program listable, it does not change how it runs.
|
|
26
43
|
*/
|
|
27
44
|
export interface RegistryDocument {
|
|
28
45
|
readonly agents?: readonly AgentDefinitionEntry[];
|
|
46
|
+
readonly programs?: readonly ProgramEntry[];
|
|
29
47
|
}
|
|
30
48
|
|
|
31
49
|
/** Which layer a Catalog row came from. A `dir` query never matches `global`. */
|
|
@@ -34,6 +52,9 @@ export type CatalogLayer = "global" | "project";
|
|
|
34
52
|
/** Where a Catalog row came from, for disambiguating duplicate names. */
|
|
35
53
|
export interface CatalogSource {
|
|
36
54
|
readonly layer: CatalogLayer;
|
|
37
|
-
/**
|
|
55
|
+
/**
|
|
56
|
+
* The declaring registry file for every registered row — an agent and a
|
|
57
|
+
* registered program — or the Program Directory for a scanned program row.
|
|
58
|
+
*/
|
|
38
59
|
readonly origin: string;
|
|
39
60
|
}
|
|
@@ -5,14 +5,16 @@ import { parseRegistryFile } from "./registry-schema.ts";
|
|
|
5
5
|
const BROKEN_REGISTRY_FILE = "/repo/other/.yaag/registry.json";
|
|
6
6
|
|
|
7
7
|
/**
|
|
8
|
-
* The
|
|
8
|
+
* The six contract cases. The order here is the order the cases were written,
|
|
9
9
|
* not the order a reader produces: `CatalogResult` states the global layer
|
|
10
10
|
* first, then the Program Directories in sorted order.
|
|
11
11
|
*
|
|
12
12
|
* A scanned program row carries no `description`: a program states its
|
|
13
13
|
* description inside `defineRun(...)`, and ADR-0046 forbids the import at list
|
|
14
|
-
* time.
|
|
15
|
-
*
|
|
14
|
+
* time. A registered program row carries the curated `description` and `tags`
|
|
15
|
+
* its Registry File entry states, and no `exportName` at all. An agent row
|
|
16
|
+
* with a path states the stat the reader ran, so `fileMissing: false` means
|
|
17
|
+
* "checked and present", not "not checked".
|
|
16
18
|
*/
|
|
17
19
|
const ROWS: readonly CatalogRow[] = [
|
|
18
20
|
{
|
|
@@ -57,21 +59,33 @@ const ROWS: readonly CatalogRow[] = [
|
|
|
57
59
|
diagnostics: [
|
|
58
60
|
{
|
|
59
61
|
scope: "entry",
|
|
62
|
+
section: "agents",
|
|
60
63
|
index: 2,
|
|
61
64
|
message: '$: must have required property "name"',
|
|
62
65
|
},
|
|
63
66
|
],
|
|
64
67
|
},
|
|
68
|
+
{
|
|
69
|
+
kind: "program",
|
|
70
|
+
registered: true,
|
|
71
|
+
name: "research",
|
|
72
|
+
description: "Runs a multi-model research panel",
|
|
73
|
+
tags: ["research", "panel"],
|
|
74
|
+
path: "/home/u/.config/yaag/programs/research.ts",
|
|
75
|
+
source: { layer: "global", origin: "/home/u/.config/yaag/registry.json" },
|
|
76
|
+
fileMissing: false,
|
|
77
|
+
},
|
|
65
78
|
];
|
|
66
79
|
|
|
67
80
|
/**
|
|
68
81
|
* The in-memory Catalog every consumer test asserts against. Construction is
|
|
69
82
|
* pure and the result is deep-frozen, so a consumer cannot change the contract
|
|
70
|
-
* by accident. It holds
|
|
71
|
-
* healthy agent, an
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
* diagnostic whose message form is
|
|
83
|
+
* by accident. It holds six rows — a healthy scanned program with no
|
|
84
|
+
* description, a healthy agent, an agent whose file is missing, a duplicate
|
|
85
|
+
* name across layers, an entry that carries a diagnostic but is still listed,
|
|
86
|
+
* and a globally registered program with a curated description and tags and
|
|
87
|
+
* no `exportName` — plus one file-scoped diagnostic whose message form is
|
|
88
|
+
* what `parseRegistryFile` emits.
|
|
75
89
|
*/
|
|
76
90
|
export const CATALOG_FIXTURE: CatalogResult = deepFreeze({
|
|
77
91
|
rows: ROWS,
|
|
@@ -6,7 +6,9 @@ import type { CatalogQuery, CatalogRow } from "./catalog-result.ts";
|
|
|
6
6
|
* Matches one row against a substring or glob pattern — never a regex. An
|
|
7
7
|
* absent, empty, or whitespace-only pattern matches everything. The haystack
|
|
8
8
|
* fields are tested independently: `name`, `description`, each tag, `path`,
|
|
9
|
-
* and `exportName`.
|
|
9
|
+
* and `exportName`. A field that the row does not carry is skipped, thus a
|
|
10
|
+
* registered program row, which has no `exportName`, is tested on its name,
|
|
11
|
+
* its description, its tags and its path. Matching is case-insensitive.
|
|
10
12
|
*
|
|
11
13
|
* A pattern that contains `*` or `?` is a glob anchored per field (`*` is any
|
|
12
14
|
* run including empty, `?` is exactly one character). Every other character is
|
|
@@ -37,9 +39,12 @@ export function filterCatalog(
|
|
|
37
39
|
}
|
|
38
40
|
|
|
39
41
|
/**
|
|
40
|
-
* A `dir` query names one Program Directory.
|
|
41
|
-
*
|
|
42
|
-
*
|
|
42
|
+
* A `dir` query names one Program Directory. A row matches when the Program
|
|
43
|
+
* Directory of its origin is that directory: a scanned program states the
|
|
44
|
+
* directory directly, and a registered row — an agent or a program that
|
|
45
|
+
* `<dir>/.yaag/registry.json` registers — states the registry file, from which
|
|
46
|
+
* the `/.yaag/` segment is stripped. A global row never matches a `dir`,
|
|
47
|
+
* whatever its origin.
|
|
43
48
|
*/
|
|
44
49
|
function matchesDirectory(row: CatalogRow, dir: string | undefined): boolean {
|
|
45
50
|
if (dir === undefined || dir === "") return true;
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
import type { CatalogSource } from "./catalog-entry.ts";
|
|
2
2
|
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* What a Catalog row describes. `program` covers a scanned program and a
|
|
5
|
+
* program that a registry file registers; `agent` is a registered Agent
|
|
6
|
+
* Definition.
|
|
7
|
+
*/
|
|
4
8
|
export type CatalogKind = "program" | "agent";
|
|
5
9
|
|
|
6
10
|
/**
|
|
@@ -10,8 +14,16 @@ export type CatalogKind = "program" | "agent";
|
|
|
10
14
|
export interface CatalogDiagnostic {
|
|
11
15
|
/** `file` = the whole registry file is unusable; `entry` = one entry, still listed. */
|
|
12
16
|
readonly scope: "file" | "entry";
|
|
13
|
-
/**
|
|
17
|
+
/**
|
|
18
|
+
* Index within the entry's own section (`agents` or `programs`), when the
|
|
19
|
+
* diagnostic is entry-scoped. Read `section` to know which array it indexes.
|
|
20
|
+
*/
|
|
14
21
|
readonly index?: number;
|
|
22
|
+
/**
|
|
23
|
+
* Which registry file section an entry-scoped diagnostic came from. Absent on
|
|
24
|
+
* a file-scoped diagnostic and on a diagnostic that an older producer made.
|
|
25
|
+
*/
|
|
26
|
+
readonly section?: "agents" | "programs";
|
|
15
27
|
/**
|
|
16
28
|
* The registry file the problem came from. A file-scoped diagnostic produces
|
|
17
29
|
* no row, so this field is the only thing that names its file; absent means
|
|
@@ -35,8 +47,17 @@ export interface CatalogRow {
|
|
|
35
47
|
readonly name: string;
|
|
36
48
|
readonly description?: string;
|
|
37
49
|
readonly tags?: readonly string[];
|
|
38
|
-
/**
|
|
50
|
+
/**
|
|
51
|
+
* The scanned program's file path, or the resolved `file` of a registry entry
|
|
52
|
+
* (an agent or a registered program). It is `""` when the entry declares no
|
|
53
|
+
* file.
|
|
54
|
+
*/
|
|
39
55
|
readonly path: string;
|
|
56
|
+
/**
|
|
57
|
+
* Set only on a program row that a registry file entry made. It is absent on
|
|
58
|
+
* a scanned program row and on every agent row, which is registered already.
|
|
59
|
+
*/
|
|
60
|
+
readonly registered?: true;
|
|
40
61
|
/** Agents only: the module export the Definition is read from. */
|
|
41
62
|
readonly exportName?: string;
|
|
42
63
|
readonly source: CatalogSource;
|
package/src/catalog/index.ts
CHANGED
|
@@ -10,7 +10,9 @@ import type { CatalogResult, CatalogRow } from "./catalog-result.ts";
|
|
|
10
10
|
*
|
|
11
11
|
* A scanned row carries no `description`: a program's description lives inside
|
|
12
12
|
* `defineRun(...)`, and reading it needs an import, which ADR-0046 forbids at
|
|
13
|
-
* list time. `yaag_describe` owns that path.
|
|
13
|
+
* list time. `yaag_describe` owns that path. A registered program row is
|
|
14
|
+
* different: its `description` and `tags` come from the registry file entry, so
|
|
15
|
+
* they are curated text and no import reads them.
|
|
14
16
|
*
|
|
15
17
|
* Never throws: an unreadable or absent directory becomes one file-scoped
|
|
16
18
|
* diagnostic and zero rows.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { readFile, stat } from "node:fs/promises";
|
|
2
2
|
import { dirname, resolve } from "node:path";
|
|
3
|
-
import type { AgentDefinitionEntry, CatalogLayer } from "./catalog-entry.ts";
|
|
3
|
+
import type { AgentDefinitionEntry, CatalogLayer, ProgramEntry } from "./catalog-entry.ts";
|
|
4
4
|
import type { CatalogDiagnostic, CatalogResult, CatalogRow } from "./catalog-result.ts";
|
|
5
5
|
import { parseRegistryFile } from "./registry-schema.ts";
|
|
6
6
|
|
|
@@ -18,8 +18,21 @@ const EMPTY: CatalogResult = { rows: [], diagnostics: [] };
|
|
|
18
18
|
* becomes a diagnostic. This deviates from `readConfigLayer`, which throws on
|
|
19
19
|
* `EACCES`, on purpose: the Catalog flags, it never fails (ADR-0046).
|
|
20
20
|
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
21
|
+
* For one registry file the reader emits every `agents` row first, then every
|
|
22
|
+
* `programs` row, each in file order. Rows are never sorted here.
|
|
23
|
+
*
|
|
24
|
+
* Entry diagnostics are bucketed per section. A `programs` diagnostic never
|
|
25
|
+
* attaches to an `agents` row, because `index` counts inside its own section.
|
|
26
|
+
*
|
|
27
|
+
* The `fileMissing` flag is a `stat` only, for an agent row and for a
|
|
28
|
+
* registered program row. Thus a registered program whose target file was
|
|
29
|
+
* deleted is flagged. This is intended.
|
|
30
|
+
*
|
|
31
|
+
* This function imports no Orchestration Program module and reads no target
|
|
32
|
+
* file. Two guards keep that honest: `registry-reader.test.ts` writes a module
|
|
33
|
+
* with a top-level side effect and asserts the marker file was never created,
|
|
34
|
+
* and `apps/yaag/src/program/runtime-alias.test.ts` guards the
|
|
35
|
+
* program-visible surface.
|
|
23
36
|
*/
|
|
24
37
|
export async function readRegistryLayer(request: RegistryLayerRequest): Promise<CatalogResult> {
|
|
25
38
|
let text: string;
|
|
@@ -41,39 +54,60 @@ export async function readRegistryLayer(request: RegistryLayerRequest): Promise<
|
|
|
41
54
|
|
|
42
55
|
const parsed = parseRegistryFile(text, request.path);
|
|
43
56
|
const fileScoped: CatalogDiagnostic[] = [];
|
|
44
|
-
const
|
|
57
|
+
const buckets = new Map<string, CatalogDiagnostic[]>();
|
|
45
58
|
for (const diagnostic of parsed.diagnostics) {
|
|
46
59
|
if (diagnostic.scope === "file" || diagnostic.index === undefined) {
|
|
47
60
|
fileScoped.push(diagnostic);
|
|
48
61
|
continue;
|
|
49
62
|
}
|
|
50
|
-
|
|
63
|
+
// A diagnostic without `section` can only come from an older producer of
|
|
64
|
+
// `ParsedRegistryFile`, when `agents` was the only section. Never drop it.
|
|
65
|
+
const key = bucketKey(diagnostic.section ?? "agents", diagnostic.index);
|
|
66
|
+
const bucket = buckets.get(key) ?? [];
|
|
51
67
|
bucket.push(diagnostic);
|
|
52
|
-
|
|
68
|
+
buckets.set(key, bucket);
|
|
53
69
|
}
|
|
54
70
|
|
|
55
71
|
const base = dirname(resolve(request.path));
|
|
56
|
-
const
|
|
57
|
-
|
|
72
|
+
const agentRows = parsed.entries.map((entry, index) =>
|
|
73
|
+
toAgentRow({ entry, base, request, diagnostics: buckets.get(bucketKey("agents", index)) }),
|
|
58
74
|
);
|
|
75
|
+
const programRows = parsed.programs.map((entry, index) =>
|
|
76
|
+
toProgramRow({ entry, base, request, diagnostics: buckets.get(bucketKey("programs", index)) }),
|
|
77
|
+
);
|
|
78
|
+
const rows = [...agentRows, ...programRows];
|
|
59
79
|
return { rows: await Promise.all(rows.map(withFileMissing)), diagnostics: fileScoped };
|
|
60
80
|
}
|
|
61
81
|
|
|
82
|
+
type EntrySection = "agents" | "programs";
|
|
83
|
+
|
|
84
|
+
/** Keys an entry diagnostic bucket, so an index counts inside its section. */
|
|
85
|
+
function bucketKey(section: EntrySection, index: number): string {
|
|
86
|
+
return `${section}:${index}`;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** One row to build. An options object keeps the positional parameters few. */
|
|
90
|
+
interface RowRequest<Entry> {
|
|
91
|
+
readonly entry: Entry;
|
|
92
|
+
readonly base: string;
|
|
93
|
+
readonly request: RegistryLayerRequest;
|
|
94
|
+
readonly diagnostics: readonly CatalogDiagnostic[] | undefined;
|
|
95
|
+
}
|
|
96
|
+
|
|
62
97
|
/**
|
|
63
|
-
*
|
|
64
|
-
* file
|
|
65
|
-
* its `file` keeps an empty path
|
|
98
|
+
* The fields an agent row and a registered program row share. A relative
|
|
99
|
+
* `file` resolves against the declaring registry file's directory, never the
|
|
100
|
+
* current working directory; an entry that lost its `file` keeps an empty path
|
|
101
|
+
* and is never checked on disk.
|
|
66
102
|
*/
|
|
67
|
-
function
|
|
68
|
-
entry
|
|
69
|
-
base
|
|
70
|
-
request
|
|
71
|
-
diagnostics
|
|
72
|
-
): CatalogRow {
|
|
103
|
+
function commonFields({
|
|
104
|
+
entry,
|
|
105
|
+
base,
|
|
106
|
+
request,
|
|
107
|
+
diagnostics,
|
|
108
|
+
}: RowRequest<ProgramEntry>): Omit<CatalogRow, "kind"> {
|
|
73
109
|
return {
|
|
74
|
-
kind: "agent",
|
|
75
110
|
name: entry.name,
|
|
76
|
-
exportName: entry.exportName,
|
|
77
111
|
path: entry.file === "" ? "" : resolve(base, entry.file),
|
|
78
112
|
...(entry.description === undefined ? {} : { description: entry.description }),
|
|
79
113
|
...(entry.tags === undefined ? {} : { tags: entry.tags }),
|
|
@@ -82,6 +116,25 @@ function toRow(
|
|
|
82
116
|
};
|
|
83
117
|
}
|
|
84
118
|
|
|
119
|
+
/** Builds one registered Agent Definition row. */
|
|
120
|
+
function toAgentRow(row: RowRequest<AgentDefinitionEntry>): CatalogRow {
|
|
121
|
+
const { name, ...rest } = commonFields(row);
|
|
122
|
+
return { kind: "agent", name, exportName: row.entry.exportName, ...rest };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Builds one registered Orchestration Program row. There is no `exportName`
|
|
127
|
+
* key at all, not an empty one: the matcher must not test it and the renderers
|
|
128
|
+
* must print no `export=`.
|
|
129
|
+
*/
|
|
130
|
+
function toProgramRow(row: RowRequest<ProgramEntry>): CatalogRow {
|
|
131
|
+
return { kind: "program", registered: true, ...commonFields(row) };
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Adds the `fileMissing` flag from a single `stat`. A row with an empty path
|
|
136
|
+
* is returned unchanged: no stat is run and no `fileMissing` key appears.
|
|
137
|
+
*/
|
|
85
138
|
async function withFileMissing(row: CatalogRow): Promise<CatalogRow> {
|
|
86
139
|
if (row.path === "") return row;
|
|
87
140
|
return { ...row, fileMissing: !(await isFile(row.path)) };
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { Type } from "typebox";
|
|
1
|
+
import { type TSchema, Type } from "typebox";
|
|
2
2
|
import { Value } from "typebox/value";
|
|
3
3
|
import { formatValidationErrors } from "../validation-errors.ts";
|
|
4
|
-
import type { AgentDefinitionEntry, RegistryDocument } from "./catalog-entry.ts";
|
|
4
|
+
import type { AgentDefinitionEntry, ProgramEntry, RegistryDocument } from "./catalog-entry.ts";
|
|
5
5
|
import type { CatalogDiagnostic } from "./catalog-result.ts";
|
|
6
6
|
|
|
7
7
|
/**
|
|
@@ -21,13 +21,25 @@ const AGENT_ENTRY_SCHEMA = Type.Object({
|
|
|
21
21
|
tags: Type.Optional(Type.Array(Type.String())),
|
|
22
22
|
});
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
const PROGRAM_ENTRY_SCHEMA = Type.Object({
|
|
25
|
+
file: Type.String(),
|
|
26
|
+
name: Type.String(),
|
|
27
|
+
description: Type.Optional(Type.String()),
|
|
28
|
+
tags: Type.Optional(Type.Array(Type.String())),
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* The outcome of parsing one registry file: the agent entries, the program
|
|
33
|
+
* entries, plus every problem found. `entries` holds agent entries only, and
|
|
34
|
+
* `programs` is an empty array when the file declares none — never `undefined`.
|
|
35
|
+
*/
|
|
25
36
|
export interface ParsedRegistryFile {
|
|
26
37
|
readonly entries: readonly AgentDefinitionEntry[];
|
|
38
|
+
readonly programs: readonly ProgramEntry[];
|
|
27
39
|
readonly diagnostics: readonly CatalogDiagnostic[];
|
|
28
40
|
}
|
|
29
41
|
|
|
30
|
-
const EMPTY: ParsedRegistryFile = { entries: [], diagnostics: [] };
|
|
42
|
+
const EMPTY: ParsedRegistryFile = { entries: [], programs: [], diagnostics: [] };
|
|
31
43
|
|
|
32
44
|
/**
|
|
33
45
|
* Parses one registry file's JSON text. Never throws: invalid JSON becomes one
|
|
@@ -41,7 +53,11 @@ export function parseRegistryFile(text: string, path?: string): ParsedRegistryFi
|
|
|
41
53
|
value = JSON.parse(text);
|
|
42
54
|
} catch (cause) {
|
|
43
55
|
const message = cause instanceof Error ? cause.message : String(cause);
|
|
44
|
-
return {
|
|
56
|
+
return {
|
|
57
|
+
entries: [],
|
|
58
|
+
programs: [],
|
|
59
|
+
diagnostics: [fileIssue(`is not valid JSON: ${message}`, path)],
|
|
60
|
+
};
|
|
45
61
|
}
|
|
46
62
|
return readRegistryDocument(value, path);
|
|
47
63
|
}
|
|
@@ -49,36 +65,83 @@ export function parseRegistryFile(text: string, path?: string): ParsedRegistryFi
|
|
|
49
65
|
/**
|
|
50
66
|
* Reads an already-parsed registry document. Never throws: a wrong root shape
|
|
51
67
|
* is a file-scoped diagnostic naming `path`, and a malformed entry is kept
|
|
52
|
-
* with an entry-scoped diagnostic carrying its index.
|
|
68
|
+
* with an entry-scoped diagnostic carrying its index. It parses `agents` and
|
|
69
|
+
* `programs` independently — a broken section never discards the other — and
|
|
70
|
+
* stamps every entry-scoped diagnostic with its section and its index within
|
|
71
|
+
* that section.
|
|
53
72
|
*/
|
|
54
73
|
export function readRegistryDocument(value: unknown, path?: string): ParsedRegistryFile {
|
|
55
74
|
const document = asRegistryDocument(value);
|
|
56
75
|
if (document === undefined) {
|
|
57
|
-
return {
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
return { entries: [], diagnostics: [fileIssue('"agents" must be an array', path)] };
|
|
76
|
+
return {
|
|
77
|
+
entries: [],
|
|
78
|
+
programs: [],
|
|
79
|
+
diagnostics: [fileIssue("must contain a JSON object", path)],
|
|
80
|
+
};
|
|
63
81
|
}
|
|
82
|
+
if (document.agents === undefined && document.programs === undefined) return EMPTY;
|
|
64
83
|
|
|
65
|
-
const
|
|
84
|
+
const agents = parseSection<AgentDefinitionEntry>({
|
|
85
|
+
raw: document.agents,
|
|
86
|
+
section: "agents",
|
|
87
|
+
schema: AGENT_ENTRY_SCHEMA,
|
|
88
|
+
build: toAgentEntry,
|
|
89
|
+
path,
|
|
90
|
+
});
|
|
91
|
+
const programs = parseSection<ProgramEntry>({
|
|
92
|
+
raw: document.programs,
|
|
93
|
+
section: "programs",
|
|
94
|
+
schema: PROGRAM_ENTRY_SCHEMA,
|
|
95
|
+
build: toProgramEntry,
|
|
96
|
+
path,
|
|
97
|
+
});
|
|
98
|
+
return {
|
|
99
|
+
entries: agents.items,
|
|
100
|
+
programs: programs.items,
|
|
101
|
+
diagnostics: [...agents.diagnostics, ...programs.diagnostics],
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** What `parseSection` needs to read one registry file section. */
|
|
106
|
+
interface SectionRequest<T> {
|
|
107
|
+
readonly raw: unknown;
|
|
108
|
+
readonly section: "agents" | "programs";
|
|
109
|
+
readonly schema: TSchema;
|
|
110
|
+
readonly build: (element: unknown) => T;
|
|
111
|
+
readonly path: string | undefined;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Reads one section. An absent section gives no entry and no diagnostic; a
|
|
116
|
+
* section that is not an array gives one file-scoped diagnostic and no entry,
|
|
117
|
+
* and it never touches the other section.
|
|
118
|
+
*/
|
|
119
|
+
function parseSection<T>(request: SectionRequest<T>): {
|
|
120
|
+
items: T[];
|
|
121
|
+
diagnostics: CatalogDiagnostic[];
|
|
122
|
+
} {
|
|
123
|
+
const { raw, section, schema, build, path } = request;
|
|
124
|
+
if (raw === undefined) return { items: [], diagnostics: [] };
|
|
125
|
+
if (!Array.isArray(raw)) {
|
|
126
|
+
return { items: [], diagnostics: [fileIssue(`"${section}" must be an array`, path)] };
|
|
127
|
+
}
|
|
128
|
+
const items: T[] = [];
|
|
66
129
|
const diagnostics: CatalogDiagnostic[] = [];
|
|
67
|
-
|
|
68
|
-
const errors = formatValidationErrors(element, Value.Errors(
|
|
130
|
+
raw.forEach((element, index) => {
|
|
131
|
+
const errors = formatValidationErrors(element, Value.Errors(schema, element));
|
|
69
132
|
if (errors.length > 0) {
|
|
70
|
-
diagnostics.push({ scope: "entry", index, message: errors.join("; ") });
|
|
133
|
+
diagnostics.push({ scope: "entry", section, index, message: errors.join("; ") });
|
|
71
134
|
}
|
|
72
|
-
|
|
135
|
+
items.push(build(element));
|
|
73
136
|
});
|
|
74
|
-
return {
|
|
137
|
+
return { items, diagnostics };
|
|
75
138
|
}
|
|
76
139
|
|
|
77
140
|
/**
|
|
78
141
|
* Narrows a parsed JSON root to a registry document. An array, a scalar, and
|
|
79
|
-
* `null` are all rejected: only a JSON object can hold
|
|
80
|
-
*
|
|
81
|
-
* its own diagnostic.
|
|
142
|
+
* `null` are all rejected: only a JSON object can hold the `agents` and
|
|
143
|
+
* `programs` sections. The two fields themselves stay unchecked here, because
|
|
144
|
+
* the caller reports a wrong one as its own diagnostic, one section at a time.
|
|
82
145
|
*/
|
|
83
146
|
function asRegistryDocument(value: unknown): RegistryDocument | undefined {
|
|
84
147
|
if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
|
|
@@ -86,26 +149,46 @@ function asRegistryDocument(value: unknown): RegistryDocument | undefined {
|
|
|
86
149
|
}
|
|
87
150
|
|
|
88
151
|
/**
|
|
89
|
-
* Builds an entry from a possibly malformed element. A missing or
|
|
90
|
-
* field becomes `""` so the entry still produces a row: the Catalog
|
|
91
|
-
* problem, it never drops the entry.
|
|
152
|
+
* Builds an agent entry from a possibly malformed element. A missing or
|
|
153
|
+
* non-string field becomes `""` so the entry still produces a row: the Catalog
|
|
154
|
+
* flags a problem, it never drops the entry.
|
|
92
155
|
*/
|
|
93
|
-
function
|
|
94
|
-
const record = (
|
|
95
|
-
string,
|
|
96
|
-
unknown
|
|
97
|
-
>;
|
|
98
|
-
const description = record["description"];
|
|
99
|
-
const tags = record["tags"];
|
|
156
|
+
function toAgentEntry(element: unknown): AgentDefinitionEntry {
|
|
157
|
+
const record = asRecord(element);
|
|
100
158
|
return {
|
|
101
159
|
file: text(record["file"]),
|
|
102
160
|
exportName: text(record["exportName"]),
|
|
103
161
|
name: text(record["name"]),
|
|
162
|
+
...metadata(record),
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/** Builds a program entry from a possibly malformed element, repaired the same way. */
|
|
167
|
+
function toProgramEntry(element: unknown): ProgramEntry {
|
|
168
|
+
const record = asRecord(element);
|
|
169
|
+
return { file: text(record["file"]), name: text(record["name"]), ...metadata(record) };
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** Keeps `description` when it is a string and keeps the string tags only. */
|
|
173
|
+
function metadata(record: Record<string, unknown>): {
|
|
174
|
+
description?: string;
|
|
175
|
+
tags?: string[];
|
|
176
|
+
} {
|
|
177
|
+
const description = record["description"];
|
|
178
|
+
const tags = record["tags"];
|
|
179
|
+
return {
|
|
104
180
|
...(typeof description === "string" ? { description } : {}),
|
|
105
181
|
...(Array.isArray(tags) ? { tags: tags.filter((tag) => typeof tag === "string") } : {}),
|
|
106
182
|
};
|
|
107
183
|
}
|
|
108
184
|
|
|
185
|
+
function asRecord(element: unknown): Record<string, unknown> {
|
|
186
|
+
return (typeof element === "object" && element !== null ? element : {}) as Record<
|
|
187
|
+
string,
|
|
188
|
+
unknown
|
|
189
|
+
>;
|
|
190
|
+
}
|
|
191
|
+
|
|
109
192
|
function text(value: unknown): string {
|
|
110
193
|
return typeof value === "string" ? value : "";
|
|
111
194
|
}
|