@lolkda/dsh-prompt-manager 3.0.0

package/lib/types/pack.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Preset packs: one preset, the bodies of its local members, and enough
+ * provenance to say where the bodies that are *not* in the pack come from.
+ *
+ * A pack is plain JSON a person can read, diff, mail, and keep. It carries no
+ * code: scripts stay on the machine that wrote them, and a pack cannot ask for
+ * one. Everything in this module is pure — building, validating, and planning an
+ * import are all functions of their arguments — so the rules a pack has to pass
+ * are testable without an HTTP request, a store, or a settings namespace.
+ *
+ * The split of responsibility is deliberate:
+ *
+ * - {@link buildPack} turns already-resolved members into a pack. Reading bodies
+ *   and subscription origins is the host's job, because only it knows them.
+ * - {@link parsePack} decides whether a foreign file is a pack this build can
+ *   use at all, and refuses by naming the entry that is wrong.
+ * - {@link planImport} works out which ids the entries will take on this machine
+ *   and rewrites the preset's membership to match, without touching anything.
+ *
+ * @module @lolkda/dsh-prompt-manager/pack
+ */
+import { type PromptPreset } from './entries.js';
+/** Marker every pack carries, so a foreign JSON file is refused by name. */
+export declare const PACK_FORMAT = "dsh-prompt-manager-pack";
+/** Pack schema this build writes, and the only one it reads. */
+export declare const PACK_VERSION = 1;
+/**
+ * Largest pack accepted on import, in bytes.
+ *
+ * A pack can carry up to {@link MAX_ENTRIES} bodies of {@link MAX_BODY_BYTES}
+ * each, so the route's ordinary JSON limit — sized for one body — is far too
+ * small here. This is the ceiling that replaces it, and it is also the largest
+ * body the route will read at all.
+ */
+export declare const MAX_PACK_BYTES: number;
+/** At most this many entries one pack may declare. Mirrors the index's own cap. */
+export declare const MAX_PACK_ENTRIES = 50;
+/** Where a subscribed entry's body comes from, as recorded in a pack. */
+export interface PackSourceRef {
+    /** Source slug the entry is subscribed to, e.g. `lolkda-dsh-prompt-pack`. */
+    slug: string;
+    /** `owner/repo`, when the exporting machine still had that source configured. */
+    repo?: string | undefined;
+    /** The ref in force there, e.g. `main`. */
+    ref?: string | undefined;
+    /** Path inside the source's workspace, e.g. `ctf.md`. */
+    file?: string | undefined;
+}
+/** Where an exported body came from. */
+export type PackOrigin = 'local' | 'builtin';
+/** One entry inside a pack. */
+export interface PackEntry {
+    /** Id it had on the exporting machine; not necessarily free on this one. */
+    id: string;
+    /** Human label, used to allocate a new id when this one is taken. */
+    title: string;
+    /** Section placement, carried over as written. */
+    order: number;
+    /** The entry's own switch, carried over as written. */
+    enabled: boolean;
+    /** Body text. Absent for a subscribed entry, whose body belongs to a source. */
+    body?: string | undefined;
+    /** Which layer supplied {@link PackEntry.body}. Absent for a subscription. */
+    origin?: PackOrigin | undefined;
+    /** Present instead of a body when the entry is a subscription. */
+    source?: PackSourceRef | undefined;
+}
+/** The preset a pack carries. */
+export interface PackPreset {
+    /** Id it had on the exporting machine; not necessarily free on this one. */
+    id: string;
+    /** Display name; kept verbatim on import even when the id has to change. */
+    name: string;
+    /** Member ids, referring to {@link PromptPack.entries}. */
+    entries: string[];
+}
+/** A pack this build understands. */
+export interface PromptPack {
+    /** Always {@link PACK_FORMAT}. */
+    format: string;
+    /** Always {@link PACK_VERSION}. */
+    version: number;
+    /** When the exporting machine wrote it, for a human reading the file. */
+    exportedAt: string;
+    /** What wrote it, for a human reading the file. */
+    generator: {
+        plugin: string;
+        pluginVersion: string;
+    };
+    /** The preset being moved. */
+    preset: PackPreset;
+    /** Its members, in the order the exporting index held them. */
+    entries: PackEntry[];
+    /** Members the preset named that no longer existed when the pack was written. */
+    missing: string[];
+}
+/** Why a pack was refused. */
+export interface PackRefusal {
+    ok: false;
+    /** Stable code the browser can branch on. */
+    code: PackRefusalCode;
+    /** Message written for the person reading the page. */
+    message: string;
+}
+/** The refusal codes a pack can be turned down with. */
+export type PackRefusalCode = 'bad-format' | 'bad-version' | 'bad-preset' | 'bad-entry' | 'bad-reference' | 'too-large' | 'too-many-entries';
+/** One member of a preset, resolved for export. */
+export interface PackMember {
+    /** Entry id. */
+    id: string;
+    /** Human label. */
+    title: string;
+    /** Section placement. */
+    order: number;
+    /** The entry's own switch. */
+    enabled: boolean;
+    /** Resolved body, when this machine has one. */
+    body?: string | undefined;
+    /** Which layer supplied the body. */
+    origin?: PackOrigin | undefined;
+    /** Subscription origin, when the body belongs to a source. */
+    source?: PackSourceRef | undefined;
+}
+/** Everything {@link buildPack} needs, all of it already resolved. */
+export interface PackExportInput {
+    /** The preset being exported. */
+    preset: PromptPreset;
+    /** Its resolvable members, in the order the pack should carry them. */
+    members: PackMember[];
+    /** Member ids the preset names that this machine cannot resolve. */
+    missing?: string[] | undefined;
+    /** This plugin's package name, recorded in the pack's header. */
+    pluginName: string;
+    /** This plugin's version, recorded in the pack's header. */
+    pluginVersion: string;
+    /** Clock, for tests; defaults to now. */
+    now?: Date | undefined;
+}
+/** One entry an import would create. */
+export interface PackImportEntry {
+    /** The id it will take on this machine. */
+    id: string;
+    /** Human label. */
+    title: string;
+    /** Section placement. */
+    order: number;
+    /** Whether it contributes while no preset is in force. */
+    enabled: boolean;
+    /** Body to write, absent for an entry whose text a source supplies. */
+    body?: string | undefined;
+    /** Which layer the body came from. */
+    origin?: PackOrigin | undefined;
+    /** Source slug to record in the index, when the entry is a subscription. */
+    source?: string | undefined;
+    /** The id this entry had on the exporting machine, when it had to change. */
+    renamedFrom?: string | undefined;
+}
+/** What an import would do, ready to be checked and then carried out. */
+export interface PackImportPlan {
+    /** Entries to create, in pack order. */
+    entries: PackImportEntry[];
+    /** The preset to create, with membership pointing at the ids above. */
+    preset: PromptPreset;
+    /** Every id that had to change, for the report. */
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Titles whose bodies this machine will not have until a source is set up. */
+    noBody: string[];
+    /**
+     * Titles that arrived as subscriptions but had to give up their id, and with
+     * it the ability to read their body from the source. They are imported as
+     * ordinary empty entries, and this is how the page says so.
+     */
+    sourceDropped: string[];
+    /** Preset members the pack itself could not carry (already gone at export). */
+    missingMembers: string[];
+}
+/** The result of planning an import. */
+export type PackImportResult = {
+    ok: true;
+    plan: PackImportPlan;
+} | PackRefusal;
+/** What an import did, in the words the page reports it with. */
+export interface PackImportReport {
+    /** Entries created, in pack order. */
+    entries: Array<{
+        id: string;
+        title: string;
+        renamedFrom?: string | undefined;
+    }>;
+    /** The preset created, with membership already pointing at the ids above. */
+    preset: PromptPreset;
+    /** Every id that changed, so the page can say which entry is which. */
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Titles whose body the pack does not carry, because a source supplies it. */
+    noBody: string[];
+    /** Titles that arrived as subscriptions but could not keep their id. */
+    sourceDropped: string[];
+    /** Preset members the pack itself could not carry. */
+    missingMembers: string[];
+    /**
+     * Variable names the imported bodies reference that *this* plugin does not
+     * supply. Not proof of a broken prompt: another row may register them, and the
+     * reference guard renders whatever is left as prose and says so in the log.
+     */
+    unregistered: string[];
+}
+/** The result of carrying out an import. */
+export type PackApplyResult = {
+    ok: true;
+    report: PackImportReport;
+} | PackRefusal;
+/** The result of reading a pack. */
+export type PackParseResult = {
+    ok: true;
+    pack: PromptPack;
+} | PackRefusal;
+/**
+ * Assemble a pack from members whose bodies the host has already resolved.
+ *
+ * Refuses nothing: a member with no body is exactly what a subscribed entry
+ * looks like, and its provenance is what makes the pack usable somewhere else.
+ *
+ * @param input - the preset, its resolved members, and the version recording it.
+ * @returns the pack, ready to be serialized.
+ */
+export declare function buildPack(input: PackExportInput): PromptPack;
+/** Where an import's body files go. */
+export interface PackBodySink {
+    /**
+     * Create one body file.
+     *
+     * Must refuse to replace a file that already exists: an id the planner
+     * believes is free may have been taken by somebody else in the meantime, and
+     * silently overwriting their body is the one outcome worse than failing.
+     */
+    write(id: string, body: string): void;
+    /**
+     * Remove one body file this call created.
+     *
+     * Expected to swallow its own failures — there is nothing useful to do about
+     * one at this point, and the original error is the one worth reporting.
+     */
+    remove(id: string): void;
+}
+/**
+ * Write the bodies an import carries, and take back whatever was written if one
+ * of them fails.
+ *
+ * An import that gets half-way leaves an index nobody has updated yet and a pile
+ * of files nothing points at, which is why the files go down first and the index
+ * last: a failure here removes exactly what this call created, so the machine
+ * ends up as it was, and importing the same pack again starts clean.
+ *
+ * @param entries - the planned entries, in pack order.
+ * @param sink - where the bodies go.
+ * @throws the sink's own error, after the rollback.
+ */
+export declare function writePackBodies(entries: readonly PackImportEntry[], sink: PackBodySink): void;
+/**
+ * Read a pack from an untrusted value.
+ *
+ * Strict about what cannot be recovered and forgiving about what can: a title is
+ * required because a missing id is derived from it, while an unusable id, a
+ * missing order, or an absent `enabled` are all things the importer decides
+ * again anyway. A body that no assembly could render is refused here rather than
+ * written into the index, because an index entry that cannot assemble fails
+ * every model step until somebody edits it.
+ *
+ * @param raw - the parsed JSON value.
+ * @returns the pack, or the first reason it is unusable.
+ */
+export declare function parsePack(raw: unknown): PackParseResult;
+/**
+ * Decide which ids an imported pack will take here, and what its preset will say.
+ *
+ * A taken id is not an error and not an overwrite: the entry gets a fresh id
+ * derived from its title, the preset's membership follows it, and the pack's
+ * display name is kept. Importing the same pack twice therefore produces two
+ * distinct sets rather than quietly rewriting the first one. Members the pack
+ * itself could not carry are kept in the preset as they were — the same rule the
+ * index uses for a subscription that may come back — and reported separately.
+ *
+ * @param pack - a pack that already passed {@link parsePack}.
+ * @param taken - ids already in use here: the index, the stored bodies, the
+ * built-ins, and the configured presets.
+ * @returns the plan, or why the pack does not fit on this machine.
+ */
+export declare function planImport(pack: PromptPack, taken: {
+    entryIds: Iterable<string>;
+    presetIds: Iterable<string>;
+}): PackImportResult;
+//# sourceMappingURL=pack.d.ts.map

package/lib/types/pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../src/pack.ts"],"names":[],"mappings":"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"}

package/lib/types/probe.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Mount-time detection of the tools a machine actually has.
+ *
+ * A prompt variable's provider is evaluated synchronously on every assembly, so
+ * a value that costs a subprocess cannot be computed there: this plugin probes
+ * once, when it mounts, and then serves the measured strings from memory.
+ *
+ * Every probe yields a string. A tool that is absent, one that prints nothing,
+ * and one that hangs are all ordinary outcomes, because a variable that resolves
+ * to `undefined` makes every section referencing it fail to render — one missing
+ * tool would cost the whole system prompt.
+ *
+ * @module @lolkda/dsh-prompt-manager/probe
+ */
+/** Largest number of probes one configuration may declare. */
+export declare const MAX_PROBES = 64;
+/** Per-probe timeout, used when a probe sets no `timeoutMs` of its own. */
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 1500;
+/**
+ * Ceiling on the whole probing pass. Reaching it does not fail the mount: the
+ * remaining probes report {@link ProbeTexts.skipped} instead, so a command that
+ * hangs cannot stall a session's startup.
+ */
+export declare const DEFAULT_PROBE_BUDGET_MS = 8000;
+/** Longest value a probe may contribute to the prompt. */
+export declare const MAX_PROBE_VALUE = 120;
+/** What a probe contributes when it cannot contribute a version. */
+export interface ProbeTexts {
+    /** The executable could not be started. */
+    missing: string;
+    /** The executable ran and printed nothing. */
+    empty: string;
+    /** The executable outlived its timeout. */
+    timeout: string;
+    /** The pass ran out of budget before this probe started. */
+    skipped: string;
+}
+/** Default placeholder texts, in English and machine-independent. */
+export declare const DEFAULT_PROBE_TEXTS: ProbeTexts;
+/** One executable a deployment asks this plugin to detect at mount. */
+export interface ProbeSpec {
+    /** Executable name on `PATH`, or an absolute path for a tool outside it. */
+    command: string;
+    /** Fixed arguments; passed without a shell unless {@link ProbeSpec.shell} is set. */
+    args?: string[] | undefined;
+    /**
+     * Run the command through the platform shell. Needed on Windows for
+     * `.cmd`/`.bat` shims such as `npm` and `pnpm`, which cannot be spawned
+     * directly.
+     */
+    shell?: boolean | undefined;
+    /**
+     * Optional regular expression whose first capture group narrows the value, so
+     * `Python 3.12.10` or `git version 2.55.0` can feed a bare `3.12.10`. When it
+     * does not match, the untrimmed first line is used instead.
+     */
+    pattern?: string | undefined;
+    /** Timeout for this probe alone, in milliseconds. */
+    timeoutMs?: number | undefined;
+}
+/**
+ * Probes the built-in machine-environment prompt needs, so a deployment that
+ * configures nothing still resolves every `{{...}}` that body references.
+ *
+ * They are ordinary probes: `config.probes` overrides any of them by name, and
+ * `probeDefaults: false` drops them all. Dropping them while the built-in body
+ * is still in force leaves its variables unregistered, which fails assembly, so
+ * the two settings belong together.
+ */
+export declare const DEFAULT_PROBES: Readonly<Record<string, ProbeSpec>>;
+/** What one process run reported, normalized across success and failure. */
+export interface ProbeRun {
+    /** `error.code` when the process could not be started at all, e.g. `ENOENT`. */
+    spawnError: string | undefined;
+    /** Exit code, when the process ran at all. */
+    status: number | undefined;
+    /** Captured standard output. */
+    stdout: string;
+    /** Captured standard error; some tools print their version there. */
+    stderr: string;
+    /** The runner killed the process when its timeout expired. */
+    timedOut: boolean;
+}
+/** Runs one probe's command. Replaced in tests, so no real tool is needed. */
+export type ProbeRunner = (command: string, args: string[], options: {
+    shell: boolean;
+    timeoutMs: number;
+}) => ProbeRun;
+/** One probe's result, as {@link runProbes} reports it. */
+export interface ProbeOutcome {
+    /** The variable name this probe feeds. */
+    name: string;
+    /** The value to register; never empty. */
+    value: string;
+    /** Wall time this probe took, in milliseconds. */
+    ms: number;
+}
+/** The result of a probing pass. */
+export interface ProbeReport {
+    /** One outcome per probe that ran or was skipped, in declaration order. */
+    outcomes: ProbeOutcome[];
+}
+/**
+ * Run a command and collect both streams.
+ *
+ * `spawnSync` rather than `execFileSync`, because the latter discards standard
+ * error on success — and some tools, `java -version` among them, print their
+ * version there while exiting zero.
+ *
+ * @param command - executable name or absolute path.
+ * @param args - fixed arguments.
+ * @param options - whether to use a shell, and the timeout.
+ * @returns the normalized run.
+ */
+export declare const defaultProbeRunner: ProbeRunner;
+/**
+ * The value one probe contributes.
+ * @param spec - the probe to run.
+ * @param run - process runner; the real one by default.
+ * @param texts - placeholders for the outcomes that carry no version.
+ * @returns a non-empty string, whatever happened.
+ */
+export declare function probeValue(spec: ProbeSpec, run?: ProbeRunner, texts?: ProbeTexts): string;
+/**
+ * Accept the `probes` config value in whatever shape a composition delivers and
+ * keep only the specs that can be run.
+ *
+ * Reports rather than throws: the caller decides whether a malformed probe is a
+ * composition error worth failing the mount over.
+ *
+ * @param raw - the config value.
+ * @returns the usable specs, plus one problem message per dropped entry.
+ */
+export declare function normalizeProbes(raw: unknown): {
+    specs: Record<string, ProbeSpec>;
+    problems: string[];
+};
+/**
+ * Probe every declared command once, in declaration order.
+ * @param specs - usable specs, as {@link normalizeProbes} returns them.
+ * @param options - runner, placeholder texts, total budget, and clock.
+ * @returns one outcome per probe, none of which can be empty.
+ */
+export declare function runProbes(specs: Record<string, ProbeSpec>, options?: {
+    run?: ProbeRunner | undefined;
+    texts?: ProbeTexts | undefined;
+    budgetMs?: number | undefined;
+    now?: (() => number) | undefined;
+}): ProbeReport;
+//# sourceMappingURL=probe.d.ts.map

package/lib/types/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../src/probe.ts"],"names":[],"mappings":"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"}

package/lib/types/routes.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The browser-facing half of the prompt store: one prefix route carrying the
+ * body files the settings page edits.
+ *
+ * Bodies cannot ride the settings transport, because they are markdown files a
+ * person also edits directly. This route is therefore the only write path from
+ * the page, and it is fenced twice: loopback peers only, and same-origin
+ * requests only for anything that mutates. A stale editor is refused with 409
+ * through the hash the page read, so two open drafts cannot silently overwrite
+ * each other.
+ *
+ * Everything else the page edits — the entry index, the presets, the
+ * subscriptions, the outbound settings — is a settings field, and this route
+ * only fills the gaps that transport leaves: an id nobody holds, a body file, a
+ * script on disk, a source's upstream check.
+ *
+ * @module @lolkda/dsh-prompt-manager/routes
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedBody } from './entries.js';
+import { PromptStore } from './store.js';
+import { type PromptScripts } from './scripts.js';
+import { type PackApplyResult, type PromptPack } from './pack.js';
+import type { Subscriptions } from './subscriptions.js';
+import type { VariableView } from './index.js';
+/** The single prefix every route below lives under. */
+export declare const ROUTE_PREFIX = "/dsh-prompt-manager";
+/** What the route needs from the plugin that owns the index. */
+export interface PromptRouteHost {
+    /** Body files. */
+    store: PromptStore;
+    /** Effective body for one entry, whichever layer supplies it. */
+    describe(id: string): ResolvedBody;
+    /** Allocate an unused entry id for a new title. */
+    idFor(title: string): string;
+    /**
+     * Ids the configured presets already hold.
+     *
+     * The page writes the preset list over the settings transport like it writes
+     * the entry index, so the only thing it cannot work out by itself is which id
+     * is still free for a new one.
+     */
+    presetIds(): string[];
+    /** Report a non-fatal problem. */
+    warn(message: string): void;
+    /** The subscription engine, for the source routes. */
+    subscriptions: Subscriptions;
+    /** The user-script engine, for the variable and script routes. */
+    scripts: PromptScripts;
+    /**
+     * The prompt variables in force, with their provenance and the entries that
+     * reference them. Probes and cached script runs are read once at mount, so
+     * this is how a deployment checks what is actually being interpolated without
+     * making a model step.
+     */
+    variables(): VariableView[];
+    /**
+     * The pack for one preset, or `undefined` when no preset here has that id.
+     *
+     * Built on demand rather than cached: a body can be edited between two
+     * exports, and an export that served a stale copy would be worse than one that
+     * costs a few file reads.
+     */
+    packFor(presetId: string): PromptPack | undefined;
+    /**
+     * Carry out an import.
+     *
+     * Resolves to what it did, or to why it did nothing — a pack that does not fit
+     * or names an unusable body is refused without a single write. A thrown error
+     * means the machine was left part-way, and the route reports it as the failure
+     * it is.
+     */
+    importPack(pack: PromptPack): Promise<PackApplyResult>;
+}
+/**
+ * Register the prompt-store route.
+ *
+ * A composition without a web server (the TUI and SDK profiles) simply gets no
+ * route; the settings page then reports the store as unreachable.
+ *
+ * @param ctx - the plugin context whose `webServer` service is injected.
+ * @param host - body resolution, id allocation, and logging.
+ */
+export declare function installPromptRoutes(ctx: Context, host: PromptRouteHost): void;
+//# sourceMappingURL=routes.d.ts.map

package/lib/types/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAShD,OAAO,EAAY,WAAW,EAAoB,MAAM,YAAY,CAAA;AAKpE,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAC9D,OAAO,EAA6B,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,uDAAuD;AACvD,eAAO,MAAM,YAAY,wBAAwB,CAAA;AAoBjD,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,KAAK,EAAE,WAAW,CAAA;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAAA;IAClC,mDAAmD;IACnD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IAC5B;;;;;;OAMG;IACH,SAAS,IAAI,MAAM,EAAE,CAAA;IACrB,kCAAkC;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,sDAAsD;IACtD,aAAa,EAAE,aAAa,CAAA;IAC5B,kEAAkE;IAClE,OAAO,EAAE,aAAa,CAAA;IACtB;;;;;OAKG;IACH,SAAS,IAAI,YAAY,EAAE,CAAA;IAC3B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IACjD;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CACvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAW7E"}