@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.
Files changed (59) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +73 -21
  3. package/adaptations/brutile.md +19 -6
  4. package/adaptations/cesiumjs.md +14 -5
  5. package/adaptations/common.md +50 -20
  6. package/adaptations/deck-gl.md +19 -6
  7. package/adaptations/duckdb-spatial.md +20 -6
  8. package/adaptations/gdal-api.md +24 -6
  9. package/adaptations/gdal.md +22 -6
  10. package/adaptations/geolibre.md +20 -6
  11. package/adaptations/geometry-api-java.md +14 -6
  12. package/adaptations/geometry-api-net.md +17 -6
  13. package/adaptations/geonode.md +17 -6
  14. package/adaptations/geopandas.md +21 -6
  15. package/adaptations/geopipe-agent.md +21 -6
  16. package/adaptations/geos.md +21 -6
  17. package/adaptations/geoserver-cloud.md +17 -6
  18. package/adaptations/geoserver-rest-api.md +17 -6
  19. package/adaptations/geoserver.md +18 -6
  20. package/adaptations/geotools.md +19 -6
  21. package/adaptations/grass-gis.md +24 -6
  22. package/adaptations/jts.md +18 -6
  23. package/adaptations/kepler-gl.md +18 -5
  24. package/adaptations/leaflet.md +25 -6
  25. package/adaptations/mapbox-gl-js.md +23 -6
  26. package/adaptations/maplibre-gl-js.md +18 -6
  27. package/adaptations/maplibre-native.md +17 -6
  28. package/adaptations/mapserver.md +22 -6
  29. package/adaptations/mapsui.md +22 -6
  30. package/adaptations/nettopologysuite.md +19 -6
  31. package/adaptations/opendronemap.md +19 -6
  32. package/adaptations/opengis-all.md +16 -5
  33. package/adaptations/opengis-daf.md +16 -5
  34. package/adaptations/opengis-utils-for-java.md +20 -6
  35. package/adaptations/opengis-utils-for-net.md +23 -6
  36. package/adaptations/openlayers.md +20 -6
  37. package/adaptations/pdal.md +26 -6
  38. package/adaptations/postgis.md +20 -6
  39. package/adaptations/proj.md +20 -6
  40. package/adaptations/projnet4geoapi.md +21 -6
  41. package/adaptations/pyqgis.md +18 -6
  42. package/adaptations/qgis-process.md +21 -6
  43. package/adaptations/qgis-server.md +18 -6
  44. package/adaptations/shapely.md +22 -6
  45. package/adaptations/sharpmap.md +19 -6
  46. package/adaptations/spatialite.md +23 -6
  47. package/adaptations/stac-cog-titiler.md +21 -6
  48. package/adaptations/whitebox-tools.md +19 -6
  49. package/docs/DETAIL.md +18 -0
  50. package/lib/adaptations.d.ts +9 -0
  51. package/lib/adaptations.js +161 -27
  52. package/lib/index.d.ts +62 -12
  53. package/lib/index.js +165 -64
  54. package/lib/markdown-links.js +9 -2
  55. package/lib/taxonomy.d.ts +41 -0
  56. package/lib/taxonomy.js +369 -0
  57. package/locale/en.json +1 -0
  58. package/locale/zh.json +1 -0
  59. 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
- * Cached shared-guidance read.
67
+ * Report whether one read failure means the instruction file no longer exists.
49
68
  *
50
- * "common.md" is appended to every loaded skill and never changes while the
51
- * process runs, so it is read once and reused. Only a successful read is
52
- * cached: a transient failure must not poison the provider for the rest of the
53
- * session, and a caller-supplied abort signal must not cancel a shared read
54
- * that other callers are waiting on.
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
- let commonContent;
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
- * Read the shared DSH guidance, memoizing the successful result.
82
+ * Combine the registration lifecycle signal with one caller signal.
60
83
  *
61
- * @returns the normalized guidance text.
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 sharedGuidance() {
64
- if (commonContent === undefined) {
65
- commonContent = readCommon(ADAPTATION_ROOT).catch((cause) => {
66
- commonContent = undefined;
67
- throw cause;
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 parsed upstream frontmatter.
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" is always an array so a consumer can map
78
- * over it without a guard.
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 metadata - the parsed frontmatter metadata, when the skill has any.
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(metadata) {
84
- const tags = Array.isArray(metadata?.tags) ? metadata.tags : [];
85
- return metadata?.category === undefined ? { tags } : { category: metadata.category, tags };
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(ASSET_ROOT);
128
+ return readSkillCatalog(assetRoot);
98
129
  } catch (cause) {
99
- throw new Error("opengis-skill: cannot load skill assets from " + ASSET_ROOT + ": " + cause.message, { cause });
130
+ throw new Error("opengis-skill: cannot load skill assets from " + assetRoot + ": " + cause.message, { cause });
100
131
  }
101
132
  }
102
133
 
103
134
  /**
104
- * Register the bundled OpenGIS skill provider on "ctx.skills".
135
+ * Create the skill provider over one asset root.
105
136
  *
106
- * The returned disposer of "registerProvider" is owned by the calling fiber,
107
- * so plugin unload removes the provider without an extra "ctx.effect" wrapper.
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 ctx - Cordis context carrying the skill registry.
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 apply(ctx) {
112
- const skills = loadSkills();
113
- const byName = new Map(skills.map((skill) => [skill.name, skill]));
114
- const candidates = skills.map((skill) => ({
115
- name: skill.name,
116
- description: skill.description,
117
- invocation: { ...INVOCATION },
118
- source: SOURCE,
119
- provider: PROVIDER_NAME,
120
- rank: RANK,
121
- locator: skill.path,
122
- path: skill.path,
123
- resourceBase: resourceBaseOf(skill.directory),
124
- // The registry keeps upstream routing metadata on the candidate only;
125
- // a definition is a summary and must not carry it. Absent values are
126
- // omitted rather than emitted as undefined keys.
127
- metadata: candidateMetadata(skill.metadata)
128
- }));
129
- const provider = {
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
- list: () => Promise.resolve(candidates),
132
- async get(candidate, options) {
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) throw new Error('opengis-skill: unknown skill "' + candidate.name + '"');
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: options?.signal }),
137
- readAdaptation(ADAPTATION_ROOT, skill.name, options?.signal),
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: { ...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
- ctx.skills.registerProvider(() => provider);
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 };
@@ -11,8 +11,15 @@
11
11
  import { existsSync } from "node:fs";
12
12
  import { dirname, resolve, sep } from "node:path";
13
13
 
14
- /** One inline markdown link target, as written. */
15
- const LINK = /\]\(([^)]+)\)/gu;
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[];