diffwiki-core 0.4.0-rc.202607221918.a124bf3 → 0.4.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/dist/index.cjs +167 -1147
- package/dist/index.d.cts +14 -389
- package/dist/index.d.ts +14 -389
- package/dist/index.js +187 -608
- package/package.json +1 -7
- package/dist/chunk-AZ6SZH6P.js +0 -484
- package/dist/chunk-EEETAETA.js +0 -145
- package/dist/events-H3D7FT4O.js +0 -6
- package/dist/plugin.cjs +0 -175
- package/dist/plugin.d.cts +0 -229
- package/dist/plugin.d.ts +0 -229
- package/dist/plugin.js +0 -14
package/dist/plugin.cjs
DELETED
|
@@ -1,175 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __defProp = Object.defineProperty;
|
|
3
|
-
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
-
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
-
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
-
var __export = (target, all) => {
|
|
7
|
-
for (var name in all)
|
|
8
|
-
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
-
};
|
|
10
|
-
var __copyProps = (to, from, except, desc) => {
|
|
11
|
-
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
-
for (let key of __getOwnPropNames(from))
|
|
13
|
-
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
-
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
-
}
|
|
16
|
-
return to;
|
|
17
|
-
};
|
|
18
|
-
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
-
|
|
20
|
-
// src/plugin.ts
|
|
21
|
-
var plugin_exports = {};
|
|
22
|
-
__export(plugin_exports, {
|
|
23
|
-
commandExists: () => commandExists,
|
|
24
|
-
definePlugin: () => definePlugin,
|
|
25
|
-
resolveDependency: () => resolveDependency,
|
|
26
|
-
runProcess: () => runProcess,
|
|
27
|
-
runProcessJson: () => runProcessJson
|
|
28
|
-
});
|
|
29
|
-
module.exports = __toCommonJS(plugin_exports);
|
|
30
|
-
|
|
31
|
-
// src/plugins/sdk.ts
|
|
32
|
-
var import_node_child_process = require("child_process");
|
|
33
|
-
var import_node_util = require("util");
|
|
34
|
-
var import_node_fs = require("fs");
|
|
35
|
-
var import_node_path = require("path");
|
|
36
|
-
var import_node_url = require("url");
|
|
37
|
-
var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
|
|
38
|
-
async function runProcess(file, args, opts) {
|
|
39
|
-
const { stdout, stderr } = await execFileAsync(file, args, {
|
|
40
|
-
env: opts?.env,
|
|
41
|
-
timeout: opts?.timeout,
|
|
42
|
-
// Large: qmd emits multi-MB JSON search payloads that overflow the default 1 MB.
|
|
43
|
-
maxBuffer: 50 * 1024 * 1024
|
|
44
|
-
});
|
|
45
|
-
return { stdout, stderr };
|
|
46
|
-
}
|
|
47
|
-
async function runProcessJson(file, args, opts) {
|
|
48
|
-
const { stdout } = await runProcess(file, args, opts);
|
|
49
|
-
try {
|
|
50
|
-
return JSON.parse(stdout);
|
|
51
|
-
} catch {
|
|
52
|
-
throw new Error(`${file} ${args.join(" ")} did not return valid JSON: ${stdout.slice(0, 200)}`);
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
async function commandExists(name) {
|
|
56
|
-
try {
|
|
57
|
-
await execFileAsync(name, ["--version"]);
|
|
58
|
-
return true;
|
|
59
|
-
} catch {
|
|
60
|
-
return false;
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
function resolveNpmBin(pkg, command, fromUrl) {
|
|
64
|
-
try {
|
|
65
|
-
let dir = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(fromUrl));
|
|
66
|
-
for (; ; ) {
|
|
67
|
-
const pkgJson = (0, import_node_path.join)(dir, "node_modules", pkg, "package.json");
|
|
68
|
-
if ((0, import_node_fs.existsSync)(pkgJson)) {
|
|
69
|
-
const raw = JSON.parse((0, import_node_fs.readFileSync)(pkgJson, "utf8"));
|
|
70
|
-
const rel = typeof raw.bin === "string" ? raw.bin : raw.bin?.[command];
|
|
71
|
-
if (!rel) return null;
|
|
72
|
-
const binPath = (0, import_node_path.join)((0, import_node_path.dirname)(pkgJson), rel);
|
|
73
|
-
return (0, import_node_fs.existsSync)(binPath) ? binPath : null;
|
|
74
|
-
}
|
|
75
|
-
const parent = (0, import_node_path.dirname)(dir);
|
|
76
|
-
if (parent === dir) return null;
|
|
77
|
-
dir = parent;
|
|
78
|
-
}
|
|
79
|
-
} catch {
|
|
80
|
-
return null;
|
|
81
|
-
}
|
|
82
|
-
}
|
|
83
|
-
async function resolveDependency(dep, fromUrl) {
|
|
84
|
-
if (dep.npm) {
|
|
85
|
-
const local = resolveNpmBin(dep.npm, dep.command, fromUrl);
|
|
86
|
-
if (local) return { dependency: dep, command: [local], source: "npm" };
|
|
87
|
-
}
|
|
88
|
-
if (await commandExists(dep.command)) {
|
|
89
|
-
return { dependency: dep, command: [dep.command], source: "path" };
|
|
90
|
-
}
|
|
91
|
-
return { dependency: dep, command: null, source: "missing" };
|
|
92
|
-
}
|
|
93
|
-
function definePlugin(def) {
|
|
94
|
-
const { name, kind, version, capabilities, dependencies, handlers } = def;
|
|
95
|
-
const describeResult = {
|
|
96
|
-
name,
|
|
97
|
-
kind,
|
|
98
|
-
version,
|
|
99
|
-
capabilities: {
|
|
100
|
-
searchTypes: capabilities.searchTypes,
|
|
101
|
-
collectionFilter: capabilities.collectionFilter,
|
|
102
|
-
events: capabilities.events
|
|
103
|
-
},
|
|
104
|
-
dependencies: (dependencies ?? []).map((d) => ({ command: d.command, npm: d.npm, hint: d.hint }))
|
|
105
|
-
};
|
|
106
|
-
async function dispatch(op, params, log) {
|
|
107
|
-
switch (op) {
|
|
108
|
-
case "describe":
|
|
109
|
-
return describeResult;
|
|
110
|
-
case "search":
|
|
111
|
-
return handlers.search(params, log);
|
|
112
|
-
case "index":
|
|
113
|
-
if (handlers.index) return handlers.index(params, log);
|
|
114
|
-
return { indexed: 0 };
|
|
115
|
-
case "setup":
|
|
116
|
-
if (handlers.setup) return handlers.setup(params, log);
|
|
117
|
-
return { ready: true };
|
|
118
|
-
case "event":
|
|
119
|
-
if (handlers.onEvent) return handlers.onEvent(params, log);
|
|
120
|
-
return { accepted: true };
|
|
121
|
-
case "health":
|
|
122
|
-
if (handlers.health) return handlers.health(params, log);
|
|
123
|
-
return { ready: true, diagnostics: [] };
|
|
124
|
-
default:
|
|
125
|
-
throw new Error(`unknown op: ${op}`);
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
function run() {
|
|
129
|
-
const log = (level, message) => {
|
|
130
|
-
process.stderr.write(JSON.stringify({ log: { level, message } }) + "\n");
|
|
131
|
-
};
|
|
132
|
-
let buffer = "";
|
|
133
|
-
process.stdin.setEncoding("utf8");
|
|
134
|
-
process.stdin.on("data", (chunk) => {
|
|
135
|
-
buffer += chunk;
|
|
136
|
-
});
|
|
137
|
-
process.stdin.on("end", () => {
|
|
138
|
-
const line = buffer.trim();
|
|
139
|
-
if (!line) {
|
|
140
|
-
process.stderr.write(`${name}: no input received on stdin
|
|
141
|
-
`);
|
|
142
|
-
process.exit(1);
|
|
143
|
-
return;
|
|
144
|
-
}
|
|
145
|
-
let req;
|
|
146
|
-
try {
|
|
147
|
-
req = JSON.parse(line);
|
|
148
|
-
} catch {
|
|
149
|
-
process.stderr.write(`${name}: malformed JSON on stdin: ${line.slice(0, 200)}
|
|
150
|
-
`);
|
|
151
|
-
process.exit(1);
|
|
152
|
-
return;
|
|
153
|
-
}
|
|
154
|
-
dispatch(req.op, req.params ?? {}, log).then((result) => {
|
|
155
|
-
const response = { ok: true, result };
|
|
156
|
-
process.stdout.write(JSON.stringify(response) + "\n");
|
|
157
|
-
process.exit(0);
|
|
158
|
-
}).catch((err) => {
|
|
159
|
-
const message = err instanceof Error ? err.message : String(err);
|
|
160
|
-
const response = { ok: false, error: { message } };
|
|
161
|
-
process.stdout.write(JSON.stringify(response) + "\n");
|
|
162
|
-
process.exit(1);
|
|
163
|
-
});
|
|
164
|
-
});
|
|
165
|
-
}
|
|
166
|
-
return { definition: def, run };
|
|
167
|
-
}
|
|
168
|
-
// Annotate the CommonJS export names for ESM import in node:
|
|
169
|
-
0 && (module.exports = {
|
|
170
|
-
commandExists,
|
|
171
|
-
definePlugin,
|
|
172
|
-
resolveDependency,
|
|
173
|
-
runProcess,
|
|
174
|
-
runProcessJson
|
|
175
|
-
});
|
package/dist/plugin.d.cts
DELETED
|
@@ -1,229 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Wire-protocol and SDK types shared by the plugin authoring SDK (`sdk.ts`) and
|
|
3
|
-
* re-exported to plugin authors via the `diffwiki-core/plugin` subpath.
|
|
4
|
-
*
|
|
5
|
-
* @module
|
|
6
|
-
*/
|
|
7
|
-
/** Log severity levels for plugin diagnostic messages. */
|
|
8
|
-
type LogLevel = 'info' | 'warn' | 'error';
|
|
9
|
-
/** A logging function that plugins use to emit diagnostic messages to stderr. */
|
|
10
|
-
type PluginLogFn = (level: LogLevel, message: string) => void;
|
|
11
|
-
/** A wire-format collection as received in handler params. */
|
|
12
|
-
interface WireCollection {
|
|
13
|
-
name: string;
|
|
14
|
-
path: string;
|
|
15
|
-
}
|
|
16
|
-
/** Diagnostic entry returned by the health handler. */
|
|
17
|
-
interface WireDiagnostic {
|
|
18
|
-
level: 'ok' | 'warn' | 'error';
|
|
19
|
-
message: string;
|
|
20
|
-
}
|
|
21
|
-
/** Readiness details returned by the health handler. */
|
|
22
|
-
interface WireReadiness {
|
|
23
|
-
toolInstalled: boolean;
|
|
24
|
-
modelsPresent: boolean;
|
|
25
|
-
indexBuilt: boolean;
|
|
26
|
-
docsIndexed: number;
|
|
27
|
-
embeddingsPending: number;
|
|
28
|
-
firstSearchCost: 'instant' | 'model-load' | 'model-download';
|
|
29
|
-
}
|
|
30
|
-
/** A single search hit returned by the search handler. */
|
|
31
|
-
interface SearchHandlerHit {
|
|
32
|
-
collection: string;
|
|
33
|
-
relPath: string;
|
|
34
|
-
title: string;
|
|
35
|
-
snippet?: string;
|
|
36
|
-
score?: number;
|
|
37
|
-
docid?: string;
|
|
38
|
-
tags?: string[];
|
|
39
|
-
}
|
|
40
|
-
/** Result shape returned by the search handler. */
|
|
41
|
-
interface SearchHandlerResult {
|
|
42
|
-
hits: SearchHandlerHit[];
|
|
43
|
-
}
|
|
44
|
-
/** Result shape returned by the index handler. */
|
|
45
|
-
interface IndexHandlerResult {
|
|
46
|
-
indexed: number;
|
|
47
|
-
}
|
|
48
|
-
/** Result shape returned by the health handler. */
|
|
49
|
-
interface HealthHandlerResult {
|
|
50
|
-
ready: boolean;
|
|
51
|
-
readiness?: WireReadiness;
|
|
52
|
-
diagnostics: WireDiagnostic[];
|
|
53
|
-
}
|
|
54
|
-
/** Result shape returned by the setup handler. */
|
|
55
|
-
interface SetupHandlerResult {
|
|
56
|
-
ready: boolean;
|
|
57
|
-
steps?: Array<{
|
|
58
|
-
step: string;
|
|
59
|
-
ok: boolean;
|
|
60
|
-
message?: string;
|
|
61
|
-
}>;
|
|
62
|
-
}
|
|
63
|
-
/** Result shape returned by the onEvent handler. */
|
|
64
|
-
interface EventHandlerResult {
|
|
65
|
-
accepted: boolean;
|
|
66
|
-
}
|
|
67
|
-
/** Parameters passed to the search handler. */
|
|
68
|
-
interface SearchParams {
|
|
69
|
-
term: string;
|
|
70
|
-
collections: WireCollection[];
|
|
71
|
-
collection?: string;
|
|
72
|
-
type?: string;
|
|
73
|
-
limit?: number;
|
|
74
|
-
}
|
|
75
|
-
/** Parameters passed to the index handler. */
|
|
76
|
-
interface IndexParams {
|
|
77
|
-
collections: WireCollection[];
|
|
78
|
-
embed?: boolean;
|
|
79
|
-
}
|
|
80
|
-
/** Parameters passed to the setup handler. */
|
|
81
|
-
interface SetupParams {
|
|
82
|
-
collections: WireCollection[];
|
|
83
|
-
embed?: boolean;
|
|
84
|
-
prefetchModels?: boolean;
|
|
85
|
-
}
|
|
86
|
-
/** Parameters passed to the onEvent handler. */
|
|
87
|
-
interface EventParams {
|
|
88
|
-
event: string;
|
|
89
|
-
collection: WireCollection;
|
|
90
|
-
relPath?: string;
|
|
91
|
-
collections: WireCollection[];
|
|
92
|
-
}
|
|
93
|
-
/** Parameters passed to the health handler. */
|
|
94
|
-
interface HealthParams {
|
|
95
|
-
collections: WireCollection[];
|
|
96
|
-
}
|
|
97
|
-
/** Plugin capabilities advertised during describe. */
|
|
98
|
-
interface PluginCapabilities {
|
|
99
|
-
searchTypes: string[];
|
|
100
|
-
collectionFilter: boolean;
|
|
101
|
-
events: boolean;
|
|
102
|
-
}
|
|
103
|
-
/**
|
|
104
|
-
* An external executable a plugin needs at runtime (e.g. `qmd`, `rg`).
|
|
105
|
-
*
|
|
106
|
-
* Declaring a dependency lets the plugin resolve the binary uniformly and lets
|
|
107
|
-
* `setup`/`health` report it. When `npm` is set, the package is expected to be a
|
|
108
|
-
* regular dependency in the plugin's own `package.json`, so `diffwiki plugin
|
|
109
|
-
* install` pulls it transitively and {@link ResolvedDependency} finds its bin in
|
|
110
|
-
* the plugin's `node_modules` — no global install required.
|
|
111
|
-
*/
|
|
112
|
-
interface PluginDependency {
|
|
113
|
-
/** The executable name, e.g. `'qmd'` or `'rg'`. */
|
|
114
|
-
command: string;
|
|
115
|
-
/** npm package that provides the executable; when set, the local bin is preferred over PATH. */
|
|
116
|
-
npm?: string;
|
|
117
|
-
/** Human-facing manual install hint, shown when the dependency is unresolved. */
|
|
118
|
-
hint?: string;
|
|
119
|
-
}
|
|
120
|
-
/**
|
|
121
|
-
* The outcome of resolving a {@link PluginDependency}: the argv prefix to invoke
|
|
122
|
-
* it, plus where it was found. `command` is null when unresolved.
|
|
123
|
-
*/
|
|
124
|
-
interface ResolvedDependency {
|
|
125
|
-
dependency: PluginDependency;
|
|
126
|
-
/** Argv prefix to spawn the tool, or null if unresolved. */
|
|
127
|
-
command: string[] | null;
|
|
128
|
-
/** How it resolved: the npm-provided local bin, the system PATH, or nowhere. */
|
|
129
|
-
source: 'npm' | 'path' | 'missing';
|
|
130
|
-
}
|
|
131
|
-
/** The handler functions a plugin provides. */
|
|
132
|
-
interface PluginHandlers {
|
|
133
|
-
/** Handle a search request. Required for search plugins. */
|
|
134
|
-
search: (params: SearchParams, log: PluginLogFn) => Promise<SearchHandlerResult> | SearchHandlerResult;
|
|
135
|
-
/** Handle a reindex request. Optional -- defaults to `{ indexed: 0 }`. */
|
|
136
|
-
index?: (params: IndexParams, log: PluginLogFn) => Promise<IndexHandlerResult> | IndexHandlerResult;
|
|
137
|
-
/** Handle an initial setup/provisioning request. Optional -- defaults to `{ ready: true }`. */
|
|
138
|
-
setup?: (params: SetupParams, log: PluginLogFn) => Promise<SetupHandlerResult> | SetupHandlerResult;
|
|
139
|
-
/** Handle a lifecycle event (article/collection add/update/remove). Optional. */
|
|
140
|
-
onEvent?: (params: EventParams, log: PluginLogFn) => Promise<EventHandlerResult> | EventHandlerResult;
|
|
141
|
-
/** Report plugin health and readiness. Optional. */
|
|
142
|
-
health?: (params: HealthParams, log: PluginLogFn) => Promise<HealthHandlerResult> | HealthHandlerResult;
|
|
143
|
-
}
|
|
144
|
-
/** The definition object passed to `definePlugin()`. */
|
|
145
|
-
interface PluginDefinition {
|
|
146
|
-
/** Plugin name (must match the name used in `diffwiki plugin register`). */
|
|
147
|
-
name: string;
|
|
148
|
-
/** Plugin kind. Currently only `'search'` is supported. */
|
|
149
|
-
kind: 'search';
|
|
150
|
-
/** Semantic version string. */
|
|
151
|
-
version?: string;
|
|
152
|
-
/** Plugin capabilities advertised to the host. */
|
|
153
|
-
capabilities: PluginCapabilities;
|
|
154
|
-
/** External executables the plugin needs. Reported via `describe` and resolvable via {@link ResolvedDependency}. */
|
|
155
|
-
dependencies?: PluginDependency[];
|
|
156
|
-
/** Handler functions for each operation. */
|
|
157
|
-
handlers: PluginHandlers;
|
|
158
|
-
}
|
|
159
|
-
/** The object returned by `definePlugin()`. Call `.run()` to serve one request. */
|
|
160
|
-
interface DefinedPlugin {
|
|
161
|
-
/** The plugin definition. */
|
|
162
|
-
definition: PluginDefinition;
|
|
163
|
-
/**
|
|
164
|
-
* Read one JSON request from stdin, dispatch to the matching handler, write
|
|
165
|
-
* the JSON response to stdout, and exit. Exit code 0 on success, 1 on
|
|
166
|
-
* handler error. Logs go to stderr.
|
|
167
|
-
*/
|
|
168
|
-
run: () => void;
|
|
169
|
-
}
|
|
170
|
-
/** Options for `runProcess` and `runProcessJson`. */
|
|
171
|
-
interface RunProcessOptions {
|
|
172
|
-
/** Environment variables for the child process. Defaults to `process.env`. */
|
|
173
|
-
env?: NodeJS.ProcessEnv;
|
|
174
|
-
/** Timeout in milliseconds. No timeout by default. */
|
|
175
|
-
timeout?: number;
|
|
176
|
-
}
|
|
177
|
-
|
|
178
|
-
/**
|
|
179
|
-
* diffwiki plugin authoring SDK — the public surface for plugin authors, imported
|
|
180
|
-
* via the `diffwiki-core/plugin` subpath export. Self-contained by design: it does
|
|
181
|
-
* NOT import host-side code (fs registry, spawn-host, query) so plugin binaries
|
|
182
|
-
* stay slim.
|
|
183
|
-
*
|
|
184
|
-
* @module
|
|
185
|
-
*/
|
|
186
|
-
|
|
187
|
-
/**
|
|
188
|
-
* Run an external command and return its stdout/stderr — a promisified
|
|
189
|
-
* `child_process.execFile` with uniform env/timeout defaults. Plugins driving
|
|
190
|
-
* external CLIs (`qmd`, `rg`) use this instead of their own exec wrappers.
|
|
191
|
-
*/
|
|
192
|
-
declare function runProcess(file: string, args: readonly string[], opts?: RunProcessOptions): Promise<{
|
|
193
|
-
stdout: string;
|
|
194
|
-
stderr: string;
|
|
195
|
-
}>;
|
|
196
|
-
/** Run an external command and JSON-parse its stdout. Throws if the output is not valid JSON. */
|
|
197
|
-
declare function runProcessJson<T>(file: string, args: readonly string[], opts?: RunProcessOptions): Promise<T>;
|
|
198
|
-
/** Return `true` if `<name> --version` exits successfully. Never throws. */
|
|
199
|
-
declare function commandExists(name: string): Promise<boolean>;
|
|
200
|
-
/**
|
|
201
|
-
* Resolve a declared {@link PluginDependency} to an argv prefix. Prefers the
|
|
202
|
-
* npm-provided local bin (when `dep.npm` is set, looked up relative to `fromUrl`),
|
|
203
|
-
* then falls back to the bare command on PATH. Returns
|
|
204
|
-
* `{ command: null, source: 'missing' }` when neither resolves. Never throws.
|
|
205
|
-
*
|
|
206
|
-
* @param dep The dependency to resolve.
|
|
207
|
-
* @param fromUrl The plugin bin's `import.meta.url`, used to anchor node resolution.
|
|
208
|
-
*/
|
|
209
|
-
declare function resolveDependency(dep: PluginDependency, fromUrl: string): Promise<ResolvedDependency>;
|
|
210
|
-
/**
|
|
211
|
-
* Define a diffwiki plugin. The required entry point for all plugins: accepts a
|
|
212
|
-
* {@link PluginDefinition} and returns a {@link DefinedPlugin} whose `.run()`
|
|
213
|
-
* serves one request over stdin/stdout then exits.
|
|
214
|
-
*
|
|
215
|
-
* @example
|
|
216
|
-
* ```ts
|
|
217
|
-
* import { definePlugin } from 'diffwiki-core/plugin';
|
|
218
|
-
*
|
|
219
|
-
* definePlugin({
|
|
220
|
-
* name: 'my-plugin',
|
|
221
|
-
* kind: 'search',
|
|
222
|
-
* capabilities: { searchTypes: ['text'], collectionFilter: true, events: false },
|
|
223
|
-
* handlers: { async search() { return { hits: [] }; } },
|
|
224
|
-
* }).run();
|
|
225
|
-
* ```
|
|
226
|
-
*/
|
|
227
|
-
declare function definePlugin(def: PluginDefinition): DefinedPlugin;
|
|
228
|
-
|
|
229
|
-
export { type DefinedPlugin, type EventHandlerResult, type EventParams, type HealthHandlerResult, type HealthParams, type IndexHandlerResult, type IndexParams, type LogLevel, type PluginCapabilities, type PluginDefinition, type PluginDependency, type PluginHandlers, type PluginLogFn, type ResolvedDependency, type RunProcessOptions, type SearchHandlerHit, type SearchHandlerResult, type SearchParams, type SetupHandlerResult, type SetupParams, type WireCollection, type WireDiagnostic, type WireReadiness, commandExists, definePlugin, resolveDependency, runProcess, runProcessJson };
|
package/dist/plugin.d.ts
DELETED
|
@@ -1,229 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Wire-protocol and SDK types shared by the plugin authoring SDK (`sdk.ts`) and
|
|
3
|
-
* re-exported to plugin authors via the `diffwiki-core/plugin` subpath.
|
|
4
|
-
*
|
|
5
|
-
* @module
|
|
6
|
-
*/
|
|
7
|
-
/** Log severity levels for plugin diagnostic messages. */
|
|
8
|
-
type LogLevel = 'info' | 'warn' | 'error';
|
|
9
|
-
/** A logging function that plugins use to emit diagnostic messages to stderr. */
|
|
10
|
-
type PluginLogFn = (level: LogLevel, message: string) => void;
|
|
11
|
-
/** A wire-format collection as received in handler params. */
|
|
12
|
-
interface WireCollection {
|
|
13
|
-
name: string;
|
|
14
|
-
path: string;
|
|
15
|
-
}
|
|
16
|
-
/** Diagnostic entry returned by the health handler. */
|
|
17
|
-
interface WireDiagnostic {
|
|
18
|
-
level: 'ok' | 'warn' | 'error';
|
|
19
|
-
message: string;
|
|
20
|
-
}
|
|
21
|
-
/** Readiness details returned by the health handler. */
|
|
22
|
-
interface WireReadiness {
|
|
23
|
-
toolInstalled: boolean;
|
|
24
|
-
modelsPresent: boolean;
|
|
25
|
-
indexBuilt: boolean;
|
|
26
|
-
docsIndexed: number;
|
|
27
|
-
embeddingsPending: number;
|
|
28
|
-
firstSearchCost: 'instant' | 'model-load' | 'model-download';
|
|
29
|
-
}
|
|
30
|
-
/** A single search hit returned by the search handler. */
|
|
31
|
-
interface SearchHandlerHit {
|
|
32
|
-
collection: string;
|
|
33
|
-
relPath: string;
|
|
34
|
-
title: string;
|
|
35
|
-
snippet?: string;
|
|
36
|
-
score?: number;
|
|
37
|
-
docid?: string;
|
|
38
|
-
tags?: string[];
|
|
39
|
-
}
|
|
40
|
-
/** Result shape returned by the search handler. */
|
|
41
|
-
interface SearchHandlerResult {
|
|
42
|
-
hits: SearchHandlerHit[];
|
|
43
|
-
}
|
|
44
|
-
/** Result shape returned by the index handler. */
|
|
45
|
-
interface IndexHandlerResult {
|
|
46
|
-
indexed: number;
|
|
47
|
-
}
|
|
48
|
-
/** Result shape returned by the health handler. */
|
|
49
|
-
interface HealthHandlerResult {
|
|
50
|
-
ready: boolean;
|
|
51
|
-
readiness?: WireReadiness;
|
|
52
|
-
diagnostics: WireDiagnostic[];
|
|
53
|
-
}
|
|
54
|
-
/** Result shape returned by the setup handler. */
|
|
55
|
-
interface SetupHandlerResult {
|
|
56
|
-
ready: boolean;
|
|
57
|
-
steps?: Array<{
|
|
58
|
-
step: string;
|
|
59
|
-
ok: boolean;
|
|
60
|
-
message?: string;
|
|
61
|
-
}>;
|
|
62
|
-
}
|
|
63
|
-
/** Result shape returned by the onEvent handler. */
|
|
64
|
-
interface EventHandlerResult {
|
|
65
|
-
accepted: boolean;
|
|
66
|
-
}
|
|
67
|
-
/** Parameters passed to the search handler. */
|
|
68
|
-
interface SearchParams {
|
|
69
|
-
term: string;
|
|
70
|
-
collections: WireCollection[];
|
|
71
|
-
collection?: string;
|
|
72
|
-
type?: string;
|
|
73
|
-
limit?: number;
|
|
74
|
-
}
|
|
75
|
-
/** Parameters passed to the index handler. */
|
|
76
|
-
interface IndexParams {
|
|
77
|
-
collections: WireCollection[];
|
|
78
|
-
embed?: boolean;
|
|
79
|
-
}
|
|
80
|
-
/** Parameters passed to the setup handler. */
|
|
81
|
-
interface SetupParams {
|
|
82
|
-
collections: WireCollection[];
|
|
83
|
-
embed?: boolean;
|
|
84
|
-
prefetchModels?: boolean;
|
|
85
|
-
}
|
|
86
|
-
/** Parameters passed to the onEvent handler. */
|
|
87
|
-
interface EventParams {
|
|
88
|
-
event: string;
|
|
89
|
-
collection: WireCollection;
|
|
90
|
-
relPath?: string;
|
|
91
|
-
collections: WireCollection[];
|
|
92
|
-
}
|
|
93
|
-
/** Parameters passed to the health handler. */
|
|
94
|
-
interface HealthParams {
|
|
95
|
-
collections: WireCollection[];
|
|
96
|
-
}
|
|
97
|
-
/** Plugin capabilities advertised during describe. */
|
|
98
|
-
interface PluginCapabilities {
|
|
99
|
-
searchTypes: string[];
|
|
100
|
-
collectionFilter: boolean;
|
|
101
|
-
events: boolean;
|
|
102
|
-
}
|
|
103
|
-
/**
|
|
104
|
-
* An external executable a plugin needs at runtime (e.g. `qmd`, `rg`).
|
|
105
|
-
*
|
|
106
|
-
* Declaring a dependency lets the plugin resolve the binary uniformly and lets
|
|
107
|
-
* `setup`/`health` report it. When `npm` is set, the package is expected to be a
|
|
108
|
-
* regular dependency in the plugin's own `package.json`, so `diffwiki plugin
|
|
109
|
-
* install` pulls it transitively and {@link ResolvedDependency} finds its bin in
|
|
110
|
-
* the plugin's `node_modules` — no global install required.
|
|
111
|
-
*/
|
|
112
|
-
interface PluginDependency {
|
|
113
|
-
/** The executable name, e.g. `'qmd'` or `'rg'`. */
|
|
114
|
-
command: string;
|
|
115
|
-
/** npm package that provides the executable; when set, the local bin is preferred over PATH. */
|
|
116
|
-
npm?: string;
|
|
117
|
-
/** Human-facing manual install hint, shown when the dependency is unresolved. */
|
|
118
|
-
hint?: string;
|
|
119
|
-
}
|
|
120
|
-
/**
|
|
121
|
-
* The outcome of resolving a {@link PluginDependency}: the argv prefix to invoke
|
|
122
|
-
* it, plus where it was found. `command` is null when unresolved.
|
|
123
|
-
*/
|
|
124
|
-
interface ResolvedDependency {
|
|
125
|
-
dependency: PluginDependency;
|
|
126
|
-
/** Argv prefix to spawn the tool, or null if unresolved. */
|
|
127
|
-
command: string[] | null;
|
|
128
|
-
/** How it resolved: the npm-provided local bin, the system PATH, or nowhere. */
|
|
129
|
-
source: 'npm' | 'path' | 'missing';
|
|
130
|
-
}
|
|
131
|
-
/** The handler functions a plugin provides. */
|
|
132
|
-
interface PluginHandlers {
|
|
133
|
-
/** Handle a search request. Required for search plugins. */
|
|
134
|
-
search: (params: SearchParams, log: PluginLogFn) => Promise<SearchHandlerResult> | SearchHandlerResult;
|
|
135
|
-
/** Handle a reindex request. Optional -- defaults to `{ indexed: 0 }`. */
|
|
136
|
-
index?: (params: IndexParams, log: PluginLogFn) => Promise<IndexHandlerResult> | IndexHandlerResult;
|
|
137
|
-
/** Handle an initial setup/provisioning request. Optional -- defaults to `{ ready: true }`. */
|
|
138
|
-
setup?: (params: SetupParams, log: PluginLogFn) => Promise<SetupHandlerResult> | SetupHandlerResult;
|
|
139
|
-
/** Handle a lifecycle event (article/collection add/update/remove). Optional. */
|
|
140
|
-
onEvent?: (params: EventParams, log: PluginLogFn) => Promise<EventHandlerResult> | EventHandlerResult;
|
|
141
|
-
/** Report plugin health and readiness. Optional. */
|
|
142
|
-
health?: (params: HealthParams, log: PluginLogFn) => Promise<HealthHandlerResult> | HealthHandlerResult;
|
|
143
|
-
}
|
|
144
|
-
/** The definition object passed to `definePlugin()`. */
|
|
145
|
-
interface PluginDefinition {
|
|
146
|
-
/** Plugin name (must match the name used in `diffwiki plugin register`). */
|
|
147
|
-
name: string;
|
|
148
|
-
/** Plugin kind. Currently only `'search'` is supported. */
|
|
149
|
-
kind: 'search';
|
|
150
|
-
/** Semantic version string. */
|
|
151
|
-
version?: string;
|
|
152
|
-
/** Plugin capabilities advertised to the host. */
|
|
153
|
-
capabilities: PluginCapabilities;
|
|
154
|
-
/** External executables the plugin needs. Reported via `describe` and resolvable via {@link ResolvedDependency}. */
|
|
155
|
-
dependencies?: PluginDependency[];
|
|
156
|
-
/** Handler functions for each operation. */
|
|
157
|
-
handlers: PluginHandlers;
|
|
158
|
-
}
|
|
159
|
-
/** The object returned by `definePlugin()`. Call `.run()` to serve one request. */
|
|
160
|
-
interface DefinedPlugin {
|
|
161
|
-
/** The plugin definition. */
|
|
162
|
-
definition: PluginDefinition;
|
|
163
|
-
/**
|
|
164
|
-
* Read one JSON request from stdin, dispatch to the matching handler, write
|
|
165
|
-
* the JSON response to stdout, and exit. Exit code 0 on success, 1 on
|
|
166
|
-
* handler error. Logs go to stderr.
|
|
167
|
-
*/
|
|
168
|
-
run: () => void;
|
|
169
|
-
}
|
|
170
|
-
/** Options for `runProcess` and `runProcessJson`. */
|
|
171
|
-
interface RunProcessOptions {
|
|
172
|
-
/** Environment variables for the child process. Defaults to `process.env`. */
|
|
173
|
-
env?: NodeJS.ProcessEnv;
|
|
174
|
-
/** Timeout in milliseconds. No timeout by default. */
|
|
175
|
-
timeout?: number;
|
|
176
|
-
}
|
|
177
|
-
|
|
178
|
-
/**
|
|
179
|
-
* diffwiki plugin authoring SDK — the public surface for plugin authors, imported
|
|
180
|
-
* via the `diffwiki-core/plugin` subpath export. Self-contained by design: it does
|
|
181
|
-
* NOT import host-side code (fs registry, spawn-host, query) so plugin binaries
|
|
182
|
-
* stay slim.
|
|
183
|
-
*
|
|
184
|
-
* @module
|
|
185
|
-
*/
|
|
186
|
-
|
|
187
|
-
/**
|
|
188
|
-
* Run an external command and return its stdout/stderr — a promisified
|
|
189
|
-
* `child_process.execFile` with uniform env/timeout defaults. Plugins driving
|
|
190
|
-
* external CLIs (`qmd`, `rg`) use this instead of their own exec wrappers.
|
|
191
|
-
*/
|
|
192
|
-
declare function runProcess(file: string, args: readonly string[], opts?: RunProcessOptions): Promise<{
|
|
193
|
-
stdout: string;
|
|
194
|
-
stderr: string;
|
|
195
|
-
}>;
|
|
196
|
-
/** Run an external command and JSON-parse its stdout. Throws if the output is not valid JSON. */
|
|
197
|
-
declare function runProcessJson<T>(file: string, args: readonly string[], opts?: RunProcessOptions): Promise<T>;
|
|
198
|
-
/** Return `true` if `<name> --version` exits successfully. Never throws. */
|
|
199
|
-
declare function commandExists(name: string): Promise<boolean>;
|
|
200
|
-
/**
|
|
201
|
-
* Resolve a declared {@link PluginDependency} to an argv prefix. Prefers the
|
|
202
|
-
* npm-provided local bin (when `dep.npm` is set, looked up relative to `fromUrl`),
|
|
203
|
-
* then falls back to the bare command on PATH. Returns
|
|
204
|
-
* `{ command: null, source: 'missing' }` when neither resolves. Never throws.
|
|
205
|
-
*
|
|
206
|
-
* @param dep The dependency to resolve.
|
|
207
|
-
* @param fromUrl The plugin bin's `import.meta.url`, used to anchor node resolution.
|
|
208
|
-
*/
|
|
209
|
-
declare function resolveDependency(dep: PluginDependency, fromUrl: string): Promise<ResolvedDependency>;
|
|
210
|
-
/**
|
|
211
|
-
* Define a diffwiki plugin. The required entry point for all plugins: accepts a
|
|
212
|
-
* {@link PluginDefinition} and returns a {@link DefinedPlugin} whose `.run()`
|
|
213
|
-
* serves one request over stdin/stdout then exits.
|
|
214
|
-
*
|
|
215
|
-
* @example
|
|
216
|
-
* ```ts
|
|
217
|
-
* import { definePlugin } from 'diffwiki-core/plugin';
|
|
218
|
-
*
|
|
219
|
-
* definePlugin({
|
|
220
|
-
* name: 'my-plugin',
|
|
221
|
-
* kind: 'search',
|
|
222
|
-
* capabilities: { searchTypes: ['text'], collectionFilter: true, events: false },
|
|
223
|
-
* handlers: { async search() { return { hits: [] }; } },
|
|
224
|
-
* }).run();
|
|
225
|
-
* ```
|
|
226
|
-
*/
|
|
227
|
-
declare function definePlugin(def: PluginDefinition): DefinedPlugin;
|
|
228
|
-
|
|
229
|
-
export { type DefinedPlugin, type EventHandlerResult, type EventParams, type HealthHandlerResult, type HealthParams, type IndexHandlerResult, type IndexParams, type LogLevel, type PluginCapabilities, type PluginDefinition, type PluginDependency, type PluginHandlers, type PluginLogFn, type ResolvedDependency, type RunProcessOptions, type SearchHandlerHit, type SearchHandlerResult, type SearchParams, type SetupHandlerResult, type SetupParams, type WireCollection, type WireDiagnostic, type WireReadiness, commandExists, definePlugin, resolveDependency, runProcess, runProcessJson };
|
package/dist/plugin.js
DELETED