@lolkda/dsh-prompt-manager 3.0.0

package/lib/types/scripts.d.ts

@@ -0,0 +1,455 @@
+/**
+ * User-authored scripts that supply prompt variables.
+ *
+ * One script is one file under `scripts/`, run as a child process, and one JSON
+ * object printed on stdout: its keys become the `{{name}}` references the
+ * prompt can use. A script therefore declares its own variables — there is no
+ * second place to register a name — and one script can supply many.
+ *
+ * Execution is deliberately out of process. A provider is evaluated
+ * synchronously for every assembly, so nothing that costs a subprocess can live
+ * there; more to the point, user code that hangs or crashes must not be able to
+ * take the host down with it. A run is bounded by a timeout, its output is
+ * bounded by a size cap, and every failure is a report rather than a throw.
+ *
+ * A script's values are cached after every successful run, so a profile start
+ * never has to execute anything to keep the prompt rendering the values it saw
+ * last: the cache is read synchronously at mount, and changed scripts are
+ * picked up by a refresh that runs behind the mount.
+ *
+ * @module @lolkda/dsh-prompt-manager/scripts
+ */
+import { type ProbeRun, type ProbeTexts } from './probe.js';
+/** Directory name, under the plugin's storage root, holding the scripts. */
+export declare const SCRIPTS_DIR_NAME = "scripts";
+/** Extension every script file carries. */
+export declare const SCRIPT_EXTENSION = ".js";
+/** Largest accepted script, in bytes. */
+export declare const MAX_SCRIPT_BYTES: number;
+/** At most this many scripts may live in the directory. */
+export declare const MAX_SCRIPTS = 20;
+/** At most this many variables may come from one script. */
+export declare const MAX_SCRIPT_VARIABLES = 64;
+/** Per-run timeout, used when a script's override sets none. */
+export declare const DEFAULT_SCRIPT_TIMEOUT_MS = 3000;
+/** Largest amount of output read back from one run, in bytes. */
+export declare const MAX_SCRIPT_OUTPUT: number;
+/** Default interpreter. An override replaces it, e.g. `python`. */
+export declare const DEFAULT_SCRIPT_COMMAND = "node";
+/** Placeholder an override's `args` may carry for the script's own path. */
+export declare const SCRIPT_PLACEHOLDER = "{script}";
+/** Bookkeeping file beside the scripts; dot-prefixed so no scan ever sees it. */
+export declare const SCRIPT_STATE_FILE = ".state.json";
+/** What a composition may override about one script's execution. */
+export interface ScriptOverride {
+    /** Interpreter to run; defaults to {@link DEFAULT_SCRIPT_COMMAND}. */
+    command?: string | undefined;
+    /** Arguments; `{script}` becomes the script's absolute path. */
+    args?: string[] | undefined;
+    /** Timeout for this script alone, in milliseconds. */
+    timeoutMs?: number | undefined;
+}
+/** One resolved execution, ready for a runner. */
+export interface ScriptSpec {
+    /** Interpreter name or absolute path. */
+    command: string;
+    /** Arguments, with the script's path already substituted in. */
+    args: string[];
+    /** Timeout for this run. */
+    timeoutMs: number;
+}
+/** Runs one script. Replaced in tests, so no interpreter is needed. */
+export type ScriptRunner = (spec: ScriptSpec, options: {
+    cwd: string;
+    name: string;
+}) => Promise<ProbeRun>;
+/** One script's cached result, as persisted beside the scripts. */
+export interface ScriptRecord {
+    /** sha1 of the script source that produced {@link ScriptRecord.variables}. */
+    sha1: string;
+    /** When the successful run happened, ISO-8601. */
+    ranAt: string;
+    /** Wall time of that run, in milliseconds. */
+    ms: number;
+    /** Exit code of that run, when it had one. */
+    exitCode?: number | undefined;
+    /** Variables it supplied, as registered. */
+    variables: Record<string, string>;
+    /** Why the most recent run after that one failed, when it did. */
+    error?: string | undefined;
+}
+/** Every script's bookkeeping, keyed by script name. */
+export type ScriptState = Record<string, ScriptRecord>;
+/** One script as the settings page sees it. */
+export interface ScriptSummary {
+    /** Script name, which is also the file stem. */
+    name: string;
+    /** sha1 of the file on disk now, or `null` when it cannot be read. */
+    sha1: string | null;
+    /** Variables the last successful run supplied. */
+    variables: string[];
+    /** When that run happened. */
+    ranAt?: string | undefined;
+    /** Its exit code. */
+    exitCode?: number | undefined;
+    /** Its wall time, in milliseconds. */
+    ms?: number | undefined;
+    /** Why the most recent attempt failed, when it did. */
+    error?: string | undefined;
+    /** The file changed since the cached run, so its values are stale. */
+    pending: boolean;
+}
+/** What one run produced. */
+export interface ScriptRunReport {
+    /** Script name; a draft run reports the name it was tested under. */
+    name: string;
+    /** Whether the run produced a usable variable set. */
+    ok: boolean;
+    /** Exit code, when the process ran. */
+    exitCode: number | undefined;
+    /** Wall time, in milliseconds. */
+    ms: number;
+    /** The variables the run supplies, when it succeeded. */
+    variables: Record<string, string>;
+    /** Variables whose value was cut to {@link MAX_PROBE_VALUE} characters. */
+    truncated: string[];
+    /** Everything that made the run unusable, in the order it was discovered. */
+    problems: string[];
+    /** Things worth showing that did not make the run unusable. */
+    warnings: string[];
+    /** Standard output, trimmed to a readable head for the page. */
+    stdout: string;
+    /** Standard error, trimmed to a readable tail for the page. */
+    stderr: string;
+}
+/** Why a script operation was refused. */
+export type ScriptErrorReason = 
+/** The name is not a usable script name. */
+'invalid-name'
+/** The source does not parse, or is too large. */
+ | 'invalid-source'
+/** The script ran but produced no usable variable set. */
+ | 'invalid-output'
+/** A variable name it wants belongs to something else. */
+ | 'conflict'
+/** Too many scripts, or too many variables from one. */
+ | 'too-many'
+/** The script file is not there. */
+ | 'unknown-script';
+/** A script operation the caller should report, not retry blindly. */
+export declare class ScriptError extends Error {
+    /** Machine-readable reason. */
+    readonly reason: ScriptErrorReason;
+    /** The run report, when the refusal came from running something. */
+    readonly report: ScriptRunReport | undefined;
+    /**
+     * @param reason - machine-readable reason.
+     * @param message - human-facing detail.
+     * @param report - the run that produced the refusal, when there was one.
+     */
+    constructor(reason: ScriptErrorReason, message: string, report?: ScriptRunReport);
+}
+/** What the script engine needs from the plugin. */
+export interface ScriptHost {
+    /** Absolute directory holding `<name>.js`. */
+    dir(): string;
+    /** Per-script overrides, from composition config. */
+    overrides(): Record<string, ScriptOverride>;
+    /** Placeholder texts a value falls back to. */
+    texts(): ProbeTexts;
+    /**
+     * Offer one variable to the prompt registry.
+     * @param name - the `{{name}}` reference.
+     * @param value - the value to serve; never empty.
+     * @param detail - owning script name.
+     * @returns `assigned` when this script already owns the name, `declared` when
+     * it was free, `conflict` when another owner has it.
+     */
+    declare(name: string, value: string, detail: string): 'assigned' | 'declared' | 'conflict';
+    /**
+     * Who owns a variable name right now.
+     * @param name - the `{{name}}` reference.
+     * @returns the owning script name, or `undefined` when the name is free.
+     */
+    owner(name: string): string | undefined;
+    /**
+     * Whether any active entry still writes one reference.
+     *
+     * Letting go of a script means keeping its variables — a value that is not
+     * there makes every section referencing it fail to assemble — but only a
+     * reference justifies that, and this is how the engine knows whether there is
+     * one.
+     *
+     * @param name - the `{{name}}` reference.
+     * @returns `true` when some entry still writes that reference.
+     */
+    referenced(name: string): boolean;
+    /**
+     * Drop a variable this engine declared.
+     *
+     * Called for a variable nothing references any more, so the prompt stops
+     * carrying a value whose script is gone. A name that has since moved to
+     * another owner is left alone: only `<detail>`'s own declaration is dropped.
+     *
+     * @param name - the `{{name}}` reference.
+     * @param detail - the script that declared it.
+     */
+    forget(name: string, detail: string): void;
+    /** Report a non-fatal problem. */
+    warn(message: string): void;
+}
+/**
+ * Run one script and collect both streams.
+ *
+ * `spawn` rather than a synchronous runner, because a save or a test run is
+ * driven by a click and must not block the host's event loop for the length of
+ * the timeout. The timeout is enforced here, so a script that never exits is
+ * killed and reported as a timeout rather than held open.
+ *
+ * @param spec - resolved interpreter, arguments, and timeout.
+ * @param options - working directory, which is the script directory.
+ * @returns the normalized run.
+ */
+export declare const defaultScriptRunner: ScriptRunner;
+/**
+ * Resolve one script's execution from its override.
+ *
+ * An override with no `command` keeps the default interpreter; one that names a
+ * command replaces both the command and the arguments, with `{script}`
+ * substituted for the script's path — appended when the override does not
+ * mention the placeholder at all.
+ *
+ * @param scriptPath - absolute path of the script file.
+ * @param override - the script's configured override, when it has one.
+ * @returns the resolved spec.
+ */
+export declare function resolveSpec(scriptPath: string, override: ScriptOverride | undefined): ScriptSpec;
+/**
+ * Accept the `scripts` config value in whatever shape a composition delivers.
+ *
+ * Reports rather than throws: a malformed override is a composition mistake the
+ * caller fails the mount over, but the caller is the one that knows the mount is
+ * still happening.
+ *
+ * @param raw - the config value.
+ * @returns the usable overrides, plus one problem message per dropped entry.
+ */
+export declare function normalizeScriptOverrides(raw: unknown): {
+    overrides: Record<string, ScriptOverride>;
+    problems: string[];
+};
+/**
+ * Whether a script's source parses.
+ *
+ * Compiling is not running: `new vm.Script()` reports a syntax error and
+ * executes nothing, which is what makes it safe to call on a draft.
+ *
+ * @param source - the script text.
+ * @returns the parser's complaint, or `undefined` when it is fine.
+ */
+export declare function checkSyntax(source: string): string | undefined;
+/**
+ * Turn one script's output into the variables it supplies.
+ *
+ * The output must be a flat JSON object; its keys are the variable names. A
+ * string is used as it stands, a finite number is stringified, and anything
+ * else is refused — a value that is not text cannot be interpolated into a
+ * prompt, and refusing it here is better than discovering it at assembly.
+ *
+ * @param raw - the script's standard output.
+ * @param texts - placeholder used for a value that came out empty.
+ * @returns the variables, plus every reason the output is unusable.
+ */
+export declare function parseScriptOutput(raw: string, texts?: ProbeTexts): {
+    variables: Record<string, string>;
+    truncated: string[];
+    problems: string[];
+};
+/**
+ * Read the bookkeeping beside the scripts.
+ * @param dir - the script directory.
+ * @returns one record per script; an unreadable or malformed file reads as empty.
+ */
+export declare function readScriptState(dir: string): ScriptState;
+/**
+ * Persist the bookkeeping.
+ * @param dir - the script directory.
+ * @param state - the state to write.
+ */
+export declare function writeScriptState(dir: string, state: ScriptState): void;
+/**
+ * Remove draft files this module left behind, so an interrupted run cannot
+ * accumulate files in a directory a person reads.
+ * @param dir - the script directory.
+ */
+export declare function cleanDrafts(dir: string): void;
+/** The script engine: on-disk scripts, their runs, and their values. */
+export declare class PromptScripts {
+    private readonly host;
+    /** `<root>/scripts`, from the plugin's resolved storage root. */
+    private readonly store;
+    /** How one script is executed; replaced in tests. */
+    private readonly runner;
+    /** Keep a run from writing its values into a prompt that has been torn down. */
+    private disposed;
+    /**
+     * @param host - the plugin side of the engine.
+     * @param options - the process runner; the real one by default.
+     */
+    constructor(host: ScriptHost, options?: {
+        run?: ScriptRunner | undefined;
+    });
+    /** Absolute directory holding the scripts. */
+    get dir(): string;
+    /** Stop accepting run results. */
+    dispose(): void;
+    /**
+     * Script names present on disk, in directory order.
+     * @returns the names, capped at {@link MAX_SCRIPTS}.
+     */
+    names(): string[];
+    /**
+     * Read one script's source.
+     *
+     * A lookup answers `undefined` rather than throwing: an unusable name is a
+     * script that is not there, and a file that cannot be read is reported and
+     * skipped, so neither can turn a page refresh into a failed request.
+     *
+     * @param name - script name.
+     * @returns the source and its hash, or `undefined` when there is no readable file.
+     */
+    read(name: string): {
+        source: string;
+        sha1: string;
+    } | undefined;
+    /**
+     * The scripts as the settings page sees them.
+     * @returns one summary per script on disk.
+     */
+    list(): ScriptSummary[];
+    /**
+     * Declare the values cached for every script whose file has not changed.
+     *
+     * Called at mount, synchronously, so a profile start serves the values it saw
+     * last without executing anything. A script with no cache, or one whose file
+     * changed while the profile was down, is left to {@link refresh}.
+     *
+     * @returns the names that still need a run.
+     */
+    mountDeclare(): string[];
+    /**
+     * Run every named script, or every script on disk, and publish the values.
+     * @param names - scripts to run; all of them when omitted.
+     * @returns one report per script, in the order they were run.
+     */
+    refresh(names?: readonly string[]): Promise<ScriptRunReport[]>;
+    /**
+     * Run one script from disk and publish whatever it supplies.
+     * @param name - script name.
+     * @returns the run report.
+     * @throws {ScriptError} when the script does not exist.
+     */
+    run(name: string): Promise<ScriptRunReport>;
+    /**
+     * Run a draft without touching the disk, the cache, or the prompt.
+     *
+     * This is the test button: the run is the same code path a saved script takes,
+     * so what it reports is what saving would produce — but nothing is registered,
+     * which is what makes it safe to try things out.
+     *
+     * @param name - the name the draft is being written under.
+     * @param source - the draft's source.
+     * @returns the run report.
+     * @throws {ScriptError} when the name or the source is unusable.
+     */
+    runSource(name: string, source: string): Promise<ScriptRunReport>;
+    /**
+     * Validate a draft, run it, and only then put it in place.
+     *
+     * Nothing is written until the script has produced a usable variable set and
+     * no name it wants is taken by something else, so a broken or conflicting
+     * script never becomes a file.
+     *
+     * @param name - script name.
+     * @param source - the source to save.
+     * @param fence - what the caller expects to find on disk.
+     * @returns the variables that are now in force, and the run that produced them.
+     * @throws {ScriptError} on any refusal, carrying the run report when there was one.
+     */
+    save(name: string, source: string, fence: {
+        kind: 'absent';
+    } | {
+        kind: 'sha1';
+        sha1: string;
+    } | {
+        kind: 'any';
+    }): Promise<{
+        name: string;
+        sha1: string;
+        variables: Record<string, string>;
+        report: ScriptRunReport;
+    }>;
+    /**
+     * Forget one script: its file and its cache entry.
+     *
+     * A variable an entry still references stays declared, frozen at the value it
+     * last held: a missing value would make every section that references it fail
+     * to assemble. One that nothing references is dropped outright — keeping it
+     * would leave the variables page showing a value for a script that is gone,
+     * which is what made a deleted script look undeletable.
+     *
+     * @param name - script name.
+     * @returns `true` when a file was removed.
+     */
+    remove(name: string): boolean;
+    /**
+     * Drop the cache entries and variables of scripts that are no longer on disk.
+     * @param onDisk - script names currently on disk.
+     */
+    private reconcile;
+    /**
+     * Let go of what one script supplied, keeping whatever is still referenced.
+     * @param name - the script that is gone.
+     * @param record - its cache entry, when it had one.
+     */
+    private release;
+    /**
+     * Record a successful run: its values reach the registry, its summary reaches
+     * the cache.
+     * @param name - owning script.
+     * @param sha1 - hash of the source that produced the values.
+     * @param report - the run that succeeded.
+     */
+    private recordSuccess;
+    /**
+     * Record a failed run.
+     *
+     * The values from the last success stay in force: a variable with no value
+     * would make every section referencing it fail to assemble, so a broken run
+     * costs the error message and nothing else. The hash of the success those
+     * values belong to is kept too, so the script still reads as needing a run.
+     *
+     * @param name - owning script.
+     * @param error - why the run failed.
+     */
+    private recordFailure;
+    /**
+     * Publish one variable, reporting a name another owner already holds.
+     * @param name - owning script.
+     * @param variable - the `{{name}}` reference.
+     * @param value - the value to serve.
+     */
+    private apply;
+    /**
+     * Execute a source without writing it: a draft file is used so that the script
+     * sees a real path, a real `__dirname`, and a real working directory, which is
+     * what makes a test run the same thing as a saved run.
+     *
+     * @param name - script name, for the report.
+     * @param source - the source to run.
+     * @param draft - whether to run from a throwaway file.
+     * @returns the report, never a throw for a script-level failure.
+     */
+    private execute;
+}
+//# sourceMappingURL=scripts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/scripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,EAAwC,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAGjG,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAEzC,2CAA2C;AAC3C,eAAO,MAAM,gBAAgB,QAAQ,CAAA;AAErC,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,QAAY,CAAA;AAEzC,2DAA2D;AAC3D,eAAO,MAAM,WAAW,KAAK,CAAA;AAE7B,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,gEAAgE;AAChE,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAE7C,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,QAAY,CAAA;AAE1C,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,SAAS,CAAA;AAE5C,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAiB9C,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC3B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,uEAAuE;AACvE,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACnC,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtB,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAA;IACV,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAEtD,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,sCAAsC;IACtC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,sEAAsE;IACtE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,EAAE,EAAE,OAAO,CAAA;IACX,uCAAuC;IACvC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,2EAA2E;IAC3E,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAA;CACf;AAED,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB;AAC3B,4CAA4C;AAC1C,cAAc;AAChB,kDAAkD;GAChD,gBAAgB;AAClB,0DAA0D;GACxD,gBAAgB;AAClB,0DAA0D;GACxD,UAAU;AACZ,wDAAwD;GACtD,UAAU;AACZ,oCAAoC;GAClC,gBAAgB,CAAA;AAEpB,sEAAsE;AACtE,qBAAa,WAAY,SAAQ,KAAK;IACpC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAElC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAA;IAE5C;;;;OAIG;gBACS,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe;CAMjF;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,GAAG,IAAI,MAAM,CAAA;IACb,qDAAqD;IACrD,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC3C,+CAA+C;IAC/C,KAAK,IAAI,UAAU,CAAA;IACnB;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAA;IAC1F;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1C,kCAAkC;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAoBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,EAAE,YA+CjC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,UAAU,CAahG;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG;IACtD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB,CA6CA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,UAAgC,GACtC;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA+ChF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAmCxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAS7C;AAED,wEAAwE;AACxE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IAEjC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;OAGG;gBACS,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;KAAO;IAM9E,8CAA8C;IAC9C,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,KAAK,IAAI,MAAM,EAAE;IAIjB;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAYhE;;;OAGG;IACH,IAAI,IAAI,aAAa,EAAE;IAqBvB;;;;;;;;OAQG;IACH,YAAY,IAAI,MAAM,EAAE;IAqBxB;;;;OAIG;IACG,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAWpE;;;;;OAKG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IASjD;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvE;;;;;;;;;;;;OAYG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,GAC3E,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC;IAsCtG;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAY7B;;;OAGG;IACH,OAAO,CAAC,SAAS;IAajB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAQf;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAOb;;;;;;;;;OASG;YACW,OAAO;CAwDtB"}

package/lib/types/source.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Subscription sources: where a prompt set comes from, and what the repository
+ * manifest says is inside it.
+ *
+ * Everything in this module is pure: string and JSON work only. The network
+ * lives in `net.ts`, the files and their history live in `sync.ts`, and the two
+ * are joined by the engine in `subscriptions.ts`.
+ *
+ * @module @lolkda/dsh-prompt-manager/source
+ */
+/** Manifest every subscribed repository must carry at its root. */
+export declare const MANIFEST_FILE = "prompt-manager.json";
+/** Largest manifest accepted, in bytes. */
+export declare const MAX_MANIFEST_BYTES: number;
+/** Largest single prompt body accepted, in bytes. Mirrors the store's limit. */
+export declare const MAX_FILE_BYTES: number;
+/** At most this many prompts may come from one source. */
+export declare const MAX_SOURCE_FILES = 50;
+/** At most this many sources may be configured. */
+export declare const MAX_SOURCES = 20;
+/** One prompt declared by a repository manifest. */
+export interface ManifestPrompt {
+    /** Repository-relative path of the markdown body. */
+    file: string;
+    /** Id stem; defaults to the file name. */
+    id?: string;
+    /** Display title; defaults to the manifest id or file stem. */
+    title?: string;
+    /** Default placement; defaults to the importer's next free slot. */
+    order?: number;
+    /** Default enabled state; the importer overrides this to `false` on import. */
+    enabled?: boolean;
+}
+/** A configured subscription source. */
+export interface PromptSource {
+    /** Local slug: entry-id prefix, workspace directory name. */
+    id: string;
+    /** `owner/name`. */
+    repo: string;
+    /** Branch, tag, or commit sha. */
+    ref: string;
+    /** URL-prefix mirror; empty means inherit the global one. */
+    mirror: string;
+    /** Whether this source takes part in a check. */
+    enabled: boolean;
+}
+/** A manifest that cannot be used, with the reason a person needs. */
+export declare class ManifestError extends Error {
+    /** Machine-readable reason. */
+    readonly reason: 'not-json' | 'not-object' | 'no-prompts' | 'bad-entry' | 'too-large' | 'too-many';
+    /**
+     * @param reason - machine-readable reason.
+     * @param message - human-facing detail.
+     */
+    constructor(reason: ManifestError['reason'], message: string);
+}
+/**
+ * Whether a value is a usable `owner/name`.
+ * @param value - candidate repository.
+ * @returns `true` when the shape is acceptable.
+ */
+export declare function isRepo(value: unknown): value is string;
+/**
+ * Whether a value is a usable ref. Path-shaped refs (`release/notes`) are
+ * allowed; anything with `..`, a leading dash, or a scheme is not.
+ * @param value - candidate ref.
+ * @returns `true` when the shape is acceptable.
+ */
+export declare function isRef(value: unknown): value is string;
+/**
+ * Whether a value is a usable source slug.
+ * @param value - candidate slug.
+ * @returns `true` when the shape is acceptable.
+ */
+export declare function isSourceId(value: unknown): value is string;
+/**
+ * Derive a source slug from `owner/name`.
+ * @param repo - a validated `owner/name`.
+ * @returns a lowercase, hyphenated slug.
+ */
+export declare function sourceSlug(repo: string): string;
+/**
+ * The id stem of one manifest file: its basename without the extension.
+ * @param file - repository-relative path.
+ * @returns a lowercase slug.
+ */
+export declare function stemOf(file: string): string;
+/**
+ * The local entry id a manifest file becomes.
+ *
+ * The id is capped at {@link MAX_ID_LENGTH}, so the source half gives up exactly
+ * the room its stem needs. Truncating the tail instead would collapse every file
+ * of a long-named source onto one id, and the index would silently keep only the
+ * first of them.
+ *
+ * @param sourceId - owning source slug.
+ * @param file - repository-relative path.
+ * @returns `<sourceId>-<stem>`, within the entry-id grammar.
+ */
+export declare function entryIdFor(sourceId: string, file: string): string;
+/**
+ * The local entry id one stem becomes.
+ *
+ * Kept separate from {@link entryIdFor} because a manifest may declare the stem
+ * itself: `id` is the file's identity, not a label, so a file may be renamed in
+ * the repository while its local entry — and every preset naming it — stays put.
+ *
+ * @param sourceId - owning source slug.
+ * @param stem - declared id, or a file's own stem.
+ * @returns `<sourceId>-<stem>`, within the entry-id grammar.
+ */
+export declare function entryIdForStem(sourceId: string, stem: string): string;
+/**
+ * The entry id one manifest prompt becomes, its own declaration first.
+ *
+ * @param sourceId - owning source slug.
+ * @param prompt - the manifest entry.
+ * @returns the local entry id.
+ */
+export declare function entryIdForPrompt(sourceId: string, prompt: ManifestPrompt): string;
+/**
+ * Validate and normalize a repository manifest.
+ *
+ * The manifest is untrusted input from the internet: every field is checked,
+ * unknown fields are dropped, and a manifest that declares nothing usable is
+ * refused rather than silently producing an empty import.
+ *
+ * @param raw - parsed JSON from the repository.
+ * @returns the usable prompts, in manifest order.
+ * @throws {ManifestError} when the manifest cannot be used at all.
+ */
+export declare function parseManifest(raw: unknown): ManifestPrompt[];
+/**
+ * Normalize a URL-prefix mirror. Only an absolute `https` origin (plus an
+ * optional path) is accepted, with no query, fragment, or credentials — the
+ * same bar the market plugin applies to its `githubProxy`.
+ * @param value - the configured value.
+ * @returns the normalized mirror, or `undefined` when it is unusable.
+ */
+export declare function normalizeMirror(value: unknown): string | undefined;
+/**
+ * Rewrite an upstream URL for a mirror.
+ *
+ * Both shapes are accepted so an existing configuration keeps working: a
+ * template containing `{url}` gets the URL substituted, and anything else is
+ * treated as a prefix, giving `<prefix>/<url>` — exactly what the market plugin
+ * writes into its `githubProxy`.
+ *
+ * @param mirror - normalized mirror; empty means no rewrite.
+ * @param url - the absolute upstream URL.
+ * @returns the URL to request.
+ */
+export declare function withMirror(mirror: string, url: string): string;
+/**
+ * The raw-content URL of one repository file.
+ * @param repo - `owner/name`.
+ * @param ref - branch, tag, or commit.
+ * @param file - repository-relative path.
+ * @returns an absolute `raw.githubusercontent.com` URL.
+ */
+export declare function rawUrl(repo: string, ref: string, file: string): string;
+/**
+ * The commits feed that carries a branch's head sha without spending API quota.
+ * @param repo - `owner/name`.
+ * @param ref - branch name.
+ * @returns an absolute `github.com` atom URL.
+ */
+export declare function headAtomUrl(repo: string, ref: string): string;
+/**
+ * Read the newest commit sha out of a commits atom feed.
+ * @param atom - the feed's XML.
+ * @returns the sha, or `undefined` when the feed does not carry one.
+ */
+export declare function parseHeadSha(atom: string): string | undefined;
+/**
+ * Whether a ref is worth probing for changes: a branch moves, a tag or commit
+ * does not.
+ * @param ref - the configured ref.
+ * @returns `true` when the ref should be probed.
+ */
+export declare function isMovableRef(ref: string): boolean;
+/**
+ * Narrow one settings value into a source, dropping unknown fields.
+ * @param raw - a candidate from the `sources` array.
+ * @returns the source, or `undefined` when it is unusable.
+ */
+export declare function parseSource(raw: unknown): PromptSource | undefined;
+/**
+ * Narrow a settings value into a source list, dropping unusable entries.
+ * @param raw - the resolved `sources` field.
+ * @returns the usable sources, capped at {@link MAX_SOURCES}.
+ */
+export declare function parseSources(raw: unknown): PromptSource[];
+//# sourceMappingURL=source.d.ts.map

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

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