@dsh-gis/dsh-opengis-skill 0.4.0 → 0.5.1
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/CHANGELOG.md +49 -0
- package/README.md +73 -21
- package/adaptations/brutile.md +19 -6
- package/adaptations/cesiumjs.md +14 -5
- package/adaptations/common.md +50 -20
- package/adaptations/deck-gl.md +19 -6
- package/adaptations/duckdb-spatial.md +20 -6
- package/adaptations/gdal-api.md +24 -6
- package/adaptations/gdal.md +22 -6
- package/adaptations/geolibre.md +20 -6
- package/adaptations/geometry-api-java.md +14 -6
- package/adaptations/geometry-api-net.md +17 -6
- package/adaptations/geonode.md +17 -6
- package/adaptations/geopandas.md +21 -6
- package/adaptations/geopipe-agent.md +21 -6
- package/adaptations/geos.md +21 -6
- package/adaptations/geoserver-cloud.md +17 -6
- package/adaptations/geoserver-rest-api.md +17 -6
- package/adaptations/geoserver.md +18 -6
- package/adaptations/geotools.md +19 -6
- package/adaptations/grass-gis.md +24 -6
- package/adaptations/jts.md +18 -6
- package/adaptations/kepler-gl.md +18 -5
- package/adaptations/leaflet.md +25 -6
- package/adaptations/mapbox-gl-js.md +23 -6
- package/adaptations/maplibre-gl-js.md +18 -6
- package/adaptations/maplibre-native.md +17 -6
- package/adaptations/mapserver.md +22 -6
- package/adaptations/mapsui.md +22 -6
- package/adaptations/nettopologysuite.md +19 -6
- package/adaptations/opendronemap.md +19 -6
- package/adaptations/opengis-all.md +16 -5
- package/adaptations/opengis-daf.md +16 -5
- package/adaptations/opengis-utils-for-java.md +20 -6
- package/adaptations/opengis-utils-for-net.md +23 -6
- package/adaptations/openlayers.md +20 -6
- package/adaptations/pdal.md +26 -6
- package/adaptations/postgis.md +20 -6
- package/adaptations/proj.md +20 -6
- package/adaptations/projnet4geoapi.md +21 -6
- package/adaptations/pyqgis.md +18 -6
- package/adaptations/qgis-process.md +21 -6
- package/adaptations/qgis-server.md +18 -6
- package/adaptations/shapely.md +22 -6
- package/adaptations/sharpmap.md +19 -6
- package/adaptations/spatialite.md +23 -6
- package/adaptations/stac-cog-titiler.md +21 -6
- package/adaptations/whitebox-tools.md +19 -6
- package/docs/DETAIL.md +18 -0
- package/lib/adaptations.d.ts +9 -0
- package/lib/adaptations.js +161 -27
- package/lib/index.d.ts +62 -12
- package/lib/index.js +165 -64
- package/lib/markdown-links.js +9 -2
- package/lib/taxonomy.d.ts +41 -0
- package/lib/taxonomy.js +369 -0
- package/locale/en.json +1 -0
- package/locale/zh.json +1 -0
- package/package.json +4 -2
package/lib/index.js
CHANGED
|
@@ -11,6 +11,21 @@
|
|
|
11
11
|
* guidance lives outside them: "adaptations/<skill>.md" plus the shared
|
|
12
12
|
* "adaptations/common.md" are appended when a skill is loaded.
|
|
13
13
|
*
|
|
14
|
+
* Three catalog layers stay outside the vendored snapshot on purpose:
|
|
15
|
+
*
|
|
16
|
+
* - "lib/taxonomy.js" maps each skill to coarse groups and to the Chinese
|
|
17
|
+
* trigger phrases a request actually uses, and the provider exposes both on
|
|
18
|
+
* the candidate metadata.
|
|
19
|
+
* - The plugin config ("groups", "skills", "exclude") trims the catalog per
|
|
20
|
+
* bundle configuration, so a browser-map session never pays for the server
|
|
21
|
+
* and database skills.
|
|
22
|
+
* - Loading appends the DSH guidance, so the upstream body stays byte-identical.
|
|
23
|
+
*
|
|
24
|
+
* The provider follows the "dsh-skill" contract at the version declared by
|
|
25
|
+
* "engines.dsh": "list()" resolves a complete array of candidates, "get()"
|
|
26
|
+
* resolves the full definition or "undefined" when the instruction file is no
|
|
27
|
+
* longer loadable, and both settle promptly when their abort signal fires.
|
|
28
|
+
*
|
|
14
29
|
* @module @dsh-gis/dsh-opengis-skill
|
|
15
30
|
*/
|
|
16
31
|
|
|
@@ -19,6 +34,7 @@ import { fileURLToPath } from "node:url";
|
|
|
19
34
|
import { composeSkillContent, readAdaptation, readCommon } from "./adaptations.js";
|
|
20
35
|
import { readSkillCatalog, resourceBaseOf } from "./catalog.js";
|
|
21
36
|
import { parseSkillFile } from "./skill-file.js";
|
|
37
|
+
import { groupsOf, keywordsOf, normalizeSelection, selectSkills } from "./taxonomy.js";
|
|
22
38
|
|
|
23
39
|
/** Provider name registered on "ctx.skills" (the runtime name "runtime" is reserved). */
|
|
24
40
|
const PROVIDER_NAME = "opengis";
|
|
@@ -42,101 +58,170 @@ const name = "opengis-skill";
|
|
|
42
58
|
const inject = ["skills"];
|
|
43
59
|
|
|
44
60
|
/** The invocation policy every bundled skill uses: model and user may load it. */
|
|
45
|
-
const INVOCATION = { modelInvocable: true, userInvocable: true };
|
|
61
|
+
const INVOCATION = Object.freeze({ modelInvocable: true, userInvocable: true });
|
|
62
|
+
|
|
63
|
+
/** File-system error codes that mean "the skill is gone" rather than "the read failed". */
|
|
64
|
+
const MISSING_FILE_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR"]);
|
|
46
65
|
|
|
47
66
|
/**
|
|
48
|
-
*
|
|
67
|
+
* Report whether one read failure means the instruction file no longer exists.
|
|
49
68
|
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
69
|
+
* The registry contract asks a provider to resolve "undefined" when a listed
|
|
70
|
+
* candidate can no longer be loaded, so a skill directory removed between
|
|
71
|
+
* discovery and load must not surface as a tool failure.
|
|
72
|
+
*
|
|
73
|
+
* @param cause - the rejection reason from readFile.
|
|
74
|
+
* @returns whether the failure is a missing path.
|
|
55
75
|
*/
|
|
56
|
-
|
|
76
|
+
function isMissingFile(cause) {
|
|
77
|
+
const code = cause?.code;
|
|
78
|
+
return typeof code === "string" && MISSING_FILE_CODES.has(code);
|
|
79
|
+
}
|
|
57
80
|
|
|
58
81
|
/**
|
|
59
|
-
*
|
|
82
|
+
* Combine the registration lifecycle signal with one caller signal.
|
|
60
83
|
*
|
|
61
|
-
*
|
|
84
|
+
* The registry aborts "control.signal" when the exact provider registration is
|
|
85
|
+
* disposed, while "options.signal" cancels one lookup. Either one must settle
|
|
86
|
+
* the read, so the provider races both.
|
|
87
|
+
*
|
|
88
|
+
* @param signals - the optional signals to race; omitted entries are ignored.
|
|
89
|
+
* @returns the combined signal, or undefined when no signal applies.
|
|
62
90
|
*/
|
|
63
|
-
function
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
});
|
|
69
|
-
}
|
|
70
|
-
return commonContent;
|
|
91
|
+
function combineSignals(...signals) {
|
|
92
|
+
const active = signals.filter((signal) => signal !== undefined);
|
|
93
|
+
if (active.length === 0) return undefined;
|
|
94
|
+
if (active.length === 1) return active[0];
|
|
95
|
+
return AbortSignal.any(active);
|
|
71
96
|
}
|
|
72
97
|
|
|
73
98
|
/**
|
|
74
|
-
* Build the candidate metadata from the
|
|
99
|
+
* Build the candidate metadata from the upstream frontmatter plus the local
|
|
100
|
+
* taxonomy.
|
|
75
101
|
*
|
|
76
102
|
* "category" is omitted when upstream does not declare one, so consumers never
|
|
77
|
-
* see an explicit undefined; "tags"
|
|
78
|
-
* over
|
|
103
|
+
* see an explicit undefined; "tags", "groups" and "keywords" are always arrays
|
|
104
|
+
* so a consumer can map over them without a guard. "groups" and "keywords" are
|
|
105
|
+
* local additions: upstream carries neither, and a host that does not know them
|
|
106
|
+
* simply ignores the keys.
|
|
79
107
|
*
|
|
80
|
-
* @param
|
|
81
|
-
* @returns the metadata object carried on the candidate.
|
|
108
|
+
* @param skill - the parsed catalog entry.
|
|
109
|
+
* @returns the frozen metadata object carried on the candidate.
|
|
82
110
|
*/
|
|
83
|
-
function candidateMetadata(
|
|
84
|
-
const tags = Array.isArray(metadata?.tags) ? metadata.tags : [];
|
|
85
|
-
|
|
111
|
+
function candidateMetadata(skill) {
|
|
112
|
+
const tags = Array.isArray(skill.metadata?.tags) ? skill.metadata.tags : [];
|
|
113
|
+
const metadata = { tags: Object.freeze([...tags]), groups: Object.freeze(groupsOf(skill.name)), keywords: Object.freeze(keywordsOf(skill.name)) };
|
|
114
|
+
if (skill.metadata?.category !== undefined) metadata.category = skill.metadata.category;
|
|
115
|
+
return Object.freeze(metadata);
|
|
86
116
|
}
|
|
87
117
|
|
|
88
118
|
/**
|
|
89
119
|
* Read and validate the packaged skill catalog, annotating asset failures with
|
|
90
120
|
* the plugin name so a broken installation is diagnosable from the host log.
|
|
91
121
|
*
|
|
122
|
+
* @param assetRoot - absolute directory holding one subdirectory per skill.
|
|
92
123
|
* @returns the validated catalog sorted by name.
|
|
93
124
|
* @throws when the packaged assets are missing or malformed.
|
|
94
125
|
*/
|
|
95
|
-
function loadSkills() {
|
|
126
|
+
function loadSkills(assetRoot) {
|
|
96
127
|
try {
|
|
97
|
-
return readSkillCatalog(
|
|
128
|
+
return readSkillCatalog(assetRoot);
|
|
98
129
|
} catch (cause) {
|
|
99
|
-
throw new Error("opengis-skill: cannot load skill assets from " +
|
|
130
|
+
throw new Error("opengis-skill: cannot load skill assets from " + assetRoot + ": " + cause.message, { cause });
|
|
100
131
|
}
|
|
101
132
|
}
|
|
102
133
|
|
|
103
134
|
/**
|
|
104
|
-
*
|
|
135
|
+
* Create the skill provider over one asset root.
|
|
105
136
|
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
137
|
+
* This is the testable core of {@link apply}: the packaged entry point only
|
|
138
|
+
* supplies the module-relative roots and the registration-lived abort signal,
|
|
139
|
+
* while a test can point it at a fixture tree.
|
|
108
140
|
*
|
|
109
|
-
* @param
|
|
141
|
+
* @param options - optional overrides: "assetRoot", "adaptationRoot", "config"
|
|
142
|
+
* (the plugin config) and "signal" (the registration lifecycle signal).
|
|
143
|
+
* @returns the provider object the skill registry holds.
|
|
144
|
+
* @throws when the assets are missing or the configuration names an unknown
|
|
145
|
+
* group or skill.
|
|
110
146
|
*/
|
|
111
|
-
function
|
|
112
|
-
const
|
|
113
|
-
const
|
|
114
|
-
const
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
147
|
+
export function createProvider(options = {}) {
|
|
148
|
+
const assetRoot = options.assetRoot ?? ASSET_ROOT;
|
|
149
|
+
const adaptationRoot = options.adaptationRoot ?? ADAPTATION_ROOT;
|
|
150
|
+
const lifecycleSignal = options.signal;
|
|
151
|
+
const skills = loadSkills(assetRoot);
|
|
152
|
+
const visible = selectSkills(skills, normalizeSelection(options.config, skills));
|
|
153
|
+
const byName = new Map(visible.map((skill) => [skill.name, skill]));
|
|
154
|
+
const candidates = Object.freeze(
|
|
155
|
+
visible.map((skill) =>
|
|
156
|
+
Object.freeze({
|
|
157
|
+
name: skill.name,
|
|
158
|
+
description: skill.description,
|
|
159
|
+
invocation: INVOCATION,
|
|
160
|
+
source: SOURCE,
|
|
161
|
+
provider: PROVIDER_NAME,
|
|
162
|
+
rank: RANK,
|
|
163
|
+
locator: skill.path,
|
|
164
|
+
path: skill.path,
|
|
165
|
+
resourceBase: Object.freeze(resourceBaseOf(skill.directory)),
|
|
166
|
+
// Routing metadata rides on the candidate only. The registry and the
|
|
167
|
+
// "skill" tool never read it (the model-facing catalog renders name and
|
|
168
|
+
// description), so a definition would only carry dead payload. Absent
|
|
169
|
+
// values are omitted rather than emitted as undefined keys.
|
|
170
|
+
metadata: candidateMetadata(skill)
|
|
171
|
+
})
|
|
172
|
+
)
|
|
173
|
+
);
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Cached shared-guidance read.
|
|
177
|
+
*
|
|
178
|
+
* "common.md" is appended to every loaded skill and never changes while the
|
|
179
|
+
* provider runs, so it is read once and reused. Only a successful read is
|
|
180
|
+
* cached: a transient failure must not poison the provider for the rest of
|
|
181
|
+
* the session, and a caller-supplied abort signal must not cancel a shared
|
|
182
|
+
* read that other callers are waiting on.
|
|
183
|
+
*/
|
|
184
|
+
let commonContent;
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Read the shared DSH guidance, memoizing the successful result.
|
|
188
|
+
*
|
|
189
|
+
* @returns the normalized guidance text.
|
|
190
|
+
*/
|
|
191
|
+
function sharedGuidance() {
|
|
192
|
+
if (commonContent === undefined) {
|
|
193
|
+
commonContent = readCommon(adaptationRoot).catch((cause) => {
|
|
194
|
+
commonContent = undefined;
|
|
195
|
+
throw cause;
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
return commonContent;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
return Object.freeze({
|
|
130
202
|
name: PROVIDER_NAME,
|
|
131
|
-
|
|
132
|
-
|
|
203
|
+
// A fresh array per call: the elements stay frozen, but a consumer that
|
|
204
|
+
// sorts or splices the result cannot corrupt the provider's catalog.
|
|
205
|
+
list: () => Promise.resolve([...candidates]),
|
|
206
|
+
async get(candidate, lookup) {
|
|
207
|
+
// A candidate this provider did not list, or one the configuration no
|
|
208
|
+
// longer selects, is "no longer loadable": the registry contract resolves
|
|
209
|
+
// undefined so the caller can report it as unknown instead of failing the
|
|
210
|
+
// whole lookup with a provider-specific error.
|
|
133
211
|
const skill = byName.get(candidate.name);
|
|
134
|
-
if (skill === undefined)
|
|
212
|
+
if (skill === undefined) return undefined;
|
|
213
|
+
const signal = combineSignals(lifecycleSignal, lookup?.signal);
|
|
135
214
|
const [raw, adaptation, common] = await Promise.all([
|
|
136
|
-
readFile(skill.path, { encoding: "utf8", signal
|
|
137
|
-
|
|
215
|
+
readFile(skill.path, { encoding: "utf8", signal }).catch((cause) => {
|
|
216
|
+
// A listed skill whose directory disappeared is "no longer loadable";
|
|
217
|
+
// the registry contract reports that as undefined, not as a failure.
|
|
218
|
+
if (isMissingFile(cause)) return undefined;
|
|
219
|
+
throw cause;
|
|
220
|
+
}),
|
|
221
|
+
readAdaptation(adaptationRoot, skill.name, signal),
|
|
138
222
|
sharedGuidance()
|
|
139
223
|
]);
|
|
224
|
+
if (raw === undefined) return undefined;
|
|
140
225
|
let parsed;
|
|
141
226
|
try {
|
|
142
227
|
parsed = parseSkillFile(raw, skill.path);
|
|
@@ -146,19 +231,35 @@ function apply(ctx) {
|
|
|
146
231
|
if (parsed.name !== candidate.name) {
|
|
147
232
|
throw new Error("opengis-skill: " + skill.path + ' now declares "' + parsed.name + '" but was listed as "' + candidate.name + '"');
|
|
148
233
|
}
|
|
149
|
-
return {
|
|
234
|
+
return Object.freeze({
|
|
150
235
|
name: parsed.name,
|
|
151
236
|
description: parsed.description,
|
|
152
|
-
invocation:
|
|
237
|
+
invocation: INVOCATION,
|
|
153
238
|
source: SOURCE,
|
|
154
239
|
provider: PROVIDER_NAME,
|
|
155
|
-
resourceBase: resourceBaseOf(skill.directory),
|
|
240
|
+
resourceBase: Object.freeze(resourceBaseOf(skill.directory)),
|
|
156
241
|
path: skill.path,
|
|
157
242
|
content: composeSkillContent(parsed.content, adaptation, common)
|
|
158
|
-
};
|
|
243
|
+
});
|
|
159
244
|
}
|
|
160
|
-
};
|
|
161
|
-
|
|
245
|
+
});
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Register the bundled OpenGIS skill provider on "ctx.skills".
|
|
250
|
+
*
|
|
251
|
+
* The returned disposer of "registerProvider" is owned by the calling fiber,
|
|
252
|
+
* so plugin unload removes the provider without an extra "ctx.effect" wrapper.
|
|
253
|
+
* The registration-scoped abort signal reaches every load, so an unload cannot
|
|
254
|
+
* leave a half-read skill behind.
|
|
255
|
+
*
|
|
256
|
+
* @param ctx - Cordis context carrying the skill registry.
|
|
257
|
+
* @param config - optional plugin config: "groups" (string[]), "skills"
|
|
258
|
+
* (string[] allow list) and "exclude" (string[] deny list). Unknown names are
|
|
259
|
+
* rejected so a typo cannot silently return the wrong catalog.
|
|
260
|
+
*/
|
|
261
|
+
function apply(ctx, config) {
|
|
262
|
+
ctx.skills.registerProvider((control) => createProvider({ config, signal: control?.signal }));
|
|
162
263
|
}
|
|
163
264
|
|
|
164
|
-
export { apply, inject, name };
|
|
265
|
+
export { apply, inject, name };
|
package/lib/markdown-links.js
CHANGED
|
@@ -11,8 +11,15 @@
|
|
|
11
11
|
import { existsSync } from "node:fs";
|
|
12
12
|
import { dirname, resolve, sep } from "node:path";
|
|
13
13
|
|
|
14
|
-
/**
|
|
15
|
-
|
|
14
|
+
/**
|
|
15
|
+
* One inline markdown link target, as written.
|
|
16
|
+
*
|
|
17
|
+
* The target may not span a line break, and it may contain one level of
|
|
18
|
+
* balanced parentheses: a path such as "reference/foo_(bar).md" is a legal
|
|
19
|
+
* markdown destination, while the naive "[^)]+" would stop at the inner ")" and
|
|
20
|
+
* report a broken link.
|
|
21
|
+
*/
|
|
22
|
+
const LINK = /\]\(((?:[^()\n]|\([^()\n]*\))+)\)/gu;
|
|
16
23
|
|
|
17
24
|
/** A link with a URI scheme or a fragment-only target is not a file link. */
|
|
18
25
|
const NON_FILE_LINK = /^(?:[a-z][a-z0-9+.-]*:|#)/iu;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** The coarse groups a plugin config may select from. */
|
|
2
|
+
export declare const GROUP_IDS: readonly string[];
|
|
3
|
+
|
|
4
|
+
/** One-line description of every group. */
|
|
5
|
+
export declare const GROUP_DESCRIPTIONS: Readonly<Record<string, string>>;
|
|
6
|
+
|
|
7
|
+
/** The groups one skill belongs to. */
|
|
8
|
+
export declare function groupsOf(name: string): string[];
|
|
9
|
+
|
|
10
|
+
/** The trigger keywords of one skill. */
|
|
11
|
+
export declare function keywordsOf(name: string): string[];
|
|
12
|
+
|
|
13
|
+
/** One routing score for one skill. */
|
|
14
|
+
export interface OpenGisRoutingScore {
|
|
15
|
+
/** Kebab-case skill name. */
|
|
16
|
+
name: string;
|
|
17
|
+
/** Weighted hits: 3 per keyword match, 1 per description token match. */
|
|
18
|
+
score: number;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** Score every catalog entry against one lowercased request. */
|
|
22
|
+
export declare function keywordScores(skills: readonly { name: string; description?: string }[], query: string): OpenGisRoutingScore[];
|
|
23
|
+
|
|
24
|
+
/** Report taxonomy entries that disagree with the catalog. */
|
|
25
|
+
export declare function taxonomyProblems(names: readonly string[]): string[];
|
|
26
|
+
|
|
27
|
+
/** The normalized plugin selection. */
|
|
28
|
+
export interface OpenGisSkillSelection {
|
|
29
|
+
/** Groups to union; ignored when "only" is non-empty. */
|
|
30
|
+
groups: string[];
|
|
31
|
+
/** Explicit skill allow list; wins over "groups". */
|
|
32
|
+
only: string[];
|
|
33
|
+
/** Skill deny list, applied last. */
|
|
34
|
+
exclude: string[];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Validate and normalize the raw plugin config. */
|
|
38
|
+
export declare function normalizeSelection(config: unknown, skills: readonly { name: string }[]): OpenGisSkillSelection;
|
|
39
|
+
|
|
40
|
+
/** Apply one selection to the catalog, keeping the catalog order. */
|
|
41
|
+
export declare function selectSkills<T extends { name: string }>(skills: readonly T[], selection: OpenGisSkillSelection): T[];
|