dsh-system-prompt-insertion 0.0.1 → 0.2.0

package/lib/index.d.ts

@@ -0,0 +1,324 @@
+import Schema from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+/**
+ * The data model this plugin persists.
+ *
+ * ## One source of truth
+ *
+ * Everything the model sees comes from one JSON file
+ * (`$DSH_HOME/system-prompt-insertion.json`). The profile row's `config` only carries
+ * deployment-level switches (master switch, file override, soft size cap) — never
+ * prompt text — so there is exactly one place a section can be edited, and the
+ * Web editor and a hand-edited file cannot disagree.
+ *
+ * @module dsh-system-prompt-insertion/types
+ */
+/** Where a section lands inside the assembled system prompt. */
+export declare const POSITIONS: readonly ['head', 'body', 'tail'];
+/** A placement band, resolved to a concrete `order` at registration time. */
+type Position = (typeof POSITIONS)[number];
+/** One user-owned prompt section. */
+interface SectionSpec {
+  /** Stable identifier; also part of the registered section name. */
+  id: string;
+  /** Short label shown by the editor and in diagnostics. */
+  title: string;
+  /** The text contributed to the system prompt. */
+  text: string;
+  /** Placement band; ignored when {@link order} is set. */
+  position: Position;
+  /** Explicit `order` override, or `null` to follow {@link position}. */
+  order: number | null;
+  /** Whether this section is contributed at all. */
+  enabled: boolean;
+  /** Whether `{{variable}}` references resolve (false keeps the text literal). */
+  interpolate: boolean;
+}
+/** The whole persisted state. */
+interface LayerState {
+  /** Store format version; bumped only with a migration. */
+  version: 1;
+  /** Plugin-wide kill switch, editable from the UI. */
+  enabled: boolean;
+  /** Sections in editor order; the array order breaks ties inside one band. */
+  sections: SectionSpec[];
+}
+/** A section id: lowercase alphanumerics and dashes, long enough to be unique. */
+export declare const SECTION_ID: RegExp;
+/** Section-name prefix; also how the preview tells our sections apart. */
+export declare const SECTION_PREFIX: string;
+/** Upper bound on a stored section text, in UTF-8 bytes. */
+export declare const MAX_TEXT_BYTES: number;
+/** Upper bound on stored sections; the editor warns instead of silently dropping. */
+export declare const MAX_SECTIONS: number;
+/** The empty state a fresh install starts from. */
+export declare function emptyState(): LayerState;
+/** Thrown when a state document cannot be accepted. */
+export declare class StateValidationError extends Error {
+  readonly path: string;
+  constructor(path: string, message: string);
+}
+/**
+ * Validate and normalize one stored state document.
+ *
+ * Unknown keys inside a section are rejected rather than dropped: a section whose
+ * field was renamed by a future version must fail loudly instead of silently
+ * losing configuration.
+ *
+ * @param input - the parsed JSON value.
+ * @returns a fresh, fully normalized state.
+ * @throws StateValidationError when the document is not acceptable.
+ */
+export declare function normalizeState(input: unknown): LayerState;
+/** The logging surface this module needs (a subset of `ctx.logger`). */
+interface StoreLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+/** Where the current state came from, for the UI's status line. */
+type StoreSource = 'memory' | 'file' | 'missing' | 'unreadable';
+/** Constructor options. */
+interface PromptStoreOptions {
+  /** Absolute path of the JSON document. */
+  path: string;
+  /** Logger used for load/save diagnostics. */
+  logger: StoreLogger;
+}
+/**
+ * Render a path for the UI without leaking a machine-specific home directory.
+ *
+ * @param path - absolute path.
+ * @returns `~/.dsh/...` for paths under the default home, `$DSH_HOME/...` for a
+ *   configured one, and the path unchanged otherwise.
+ */
+export declare function displayPath(path: string): string;
+/** The section store. */
+export declare class PromptStore {
+  private readonly path;
+  private readonly logger;
+  private state;
+  private stamp;
+  private source;
+  private error;
+  private loaded;
+  constructor(options: PromptStoreOptions);
+  /** Absolute path of the JSON document. */
+  file(): string;
+  /** Display form of {@link file} for user-facing text. */
+  displayPath(): string;
+  /** Where the current state came from. */
+  origin(): StoreSource;
+  /** The last load or parse error, if the file could not be read. */
+  lastError(): string | undefined;
+  /**
+   * The current state, re-reading the file when it changed on disk.
+   *
+   * @returns a frozen view; callers must not mutate it.
+   */
+  current(): LayerState;
+  /**
+   * Validate, persist, and publish a new state.
+   *
+   * @param input - the candidate state (already parsed JSON).
+   * @returns the normalized state that was stored.
+   * @throws StateValidationError when the candidate is not acceptable.
+   */
+  save(input: unknown): LayerState;
+  /** Re-read the file. A failed read keeps the previous state live. */
+  private reload;
+}
+/** First order inside the `head` band — right after the persona prefix. */
+export declare const HEAD_BASE = 10;
+/** First order inside the `body` band — after every tool guidance section. */
+export declare const BODY_BASE = 5100;
+/** Distance kept above the host's own last section. */
+export declare const TAIL_GAP = 300;
+/** Spacing between two sections of the same band. */
+export declare const SECTION_STEP = 10;
+/** Fallback for the host's last built-in section order (`DEPLOYMENT_PERSONA_SUFFIX`). */
+export declare const FALLBACK_TAIL_BASE = 10200;
+/** The band bases resolved once per load. */
+interface OrderBases {
+  /** Order of the host's `deployment:persona-suffix` section. */
+  tailBase: number;
+}
+/**
+ * Resolve the concrete order of one section.
+ *
+ * @param section - the stored section.
+ * @param ordinal - its index among ALL sections of the same band, in editor
+ *   order. Disabled and empty entries keep their slot, so switching one off does
+ *   not renumber its neighbours.
+ * @param bases - the band bases for this load.
+ * @returns the order to register.
+ */
+export declare function resolveSectionOrder(section: SectionSpec, ordinal: number, bases: OrderBases): number;
+/**
+ * Plan the registrations for one state: which sections are contributed, under
+ * which name and at which order.
+ *
+ * @param state - the stored state.
+ * @param bases - the band bases for this load.
+ * @param prefix - registered-name prefix (`user:system-prompt-insertion:` by default).
+ * @returns one plan per ENABLED, non-empty section, in editor order.
+ */
+export declare function planRegistrations(state: LayerState, bases: OrderBases, prefix: string): Array<{
+  section: SectionSpec;
+  name: string;
+  order: number;
+}>;
+/** Read the host's own last built-in section order at runtime. */
+export declare function resolveOrderBases(ctx: Context): OrderBases;
+/** Diagnostics surface (a subset of `ctx.logger`). */
+type RegistrarLogger = StoreLogger;
+/** Owns the registered sections of one plugin instance. */
+export declare class SectionRegistrar {
+  private readonly ctx;
+  private readonly store;
+  private readonly logger;
+  private readonly prefix;
+  private disposers;
+  private names;
+  private orderByName;
+  private bases;
+  constructor(ctx: Context, store: PromptStore, logger: RegistrarLogger, prefix?: string);
+  /** The band bases currently in use (also reported to the preview). */
+  orderBases(): OrderBases;
+  /** Names of the sections currently registered, for diagnostics and the preview. */
+  registeredNames(): string[];
+  /** The concrete order each registered section was placed at. */
+  registeredOrders(): ReadonlyMap<string, number>;
+  /**
+   * Rebuild the registration plan from the store.
+   *
+   * Registration is idempotent per plan: the previous plan is disposed first, so a
+   * removed section cannot linger. A section whose registration throws (a name
+   * collision with another plugin) is reported and skipped instead of taking the
+   * whole plugin down.
+   *
+   * @returns the state that was planned from.
+   */
+  sync(): LayerState;
+  /** Dispose every registration this instance owns. */
+  dispose(): void;
+}
+/** One warning the editor shows above the preview. */
+interface PreviewWarning {
+  /** Stable machine code the client localizes. */
+  code: 'hidden' | 'duplicate' | 'unknown-variable' | 'oversize' | 'empty' | 'store-error' | 'render-error' | 'preview-partial';
+  /** The section the warning is about, when it is about one. */
+  sectionId?: string;
+  /** Values the client interpolates into its own localized copy. */
+  params?: Record<string, string | number>;
+  /** English fallback for a client that does not know this code. */
+  message: string;
+}
+/** One section of the assembled prompt. */
+interface PreviewSection {
+  /** Registry name. */
+  name: string;
+  /** Zero-based position in the rendered prompt. */
+  index: number;
+  /** The order this plugin registered the section at, when it is ours. */
+  order?: number;
+  /** UTF-8 size of the resolved text. */
+  bytes: number;
+  /** Whether this section came from this plugin. */
+  ours: boolean;
+  /** The resolved (probably interpolated) text. */
+  text: string;
+}
+/** Everything the preview panel renders. */
+interface PreviewResult {
+  /** The rendered system prompt, or `''` when rendering failed. */
+  rendered: string;
+  /** UTF-8 size of {@link rendered}. */
+  bytes: number;
+  /** The assembly's sections in canonical order. */
+  sections: PreviewSection[];
+  /** Variables the loop registered for this assembly. */
+  variables: string[];
+  /** Warnings derived from the state and the assembly. */
+  warnings: PreviewWarning[];
+  /** Whether an effective complete-prompt section owns the assembly. */
+  complete: boolean;
+  /** Why rendering failed, when it did. */
+  renderError?: string;
+}
+/** The subset of host services the preview needs. */
+interface PreviewHost {
+  ctx: Context;
+  store: PromptStore;
+  registrar: SectionRegistrar;
+  maxSectionBytes: number;
+}
+/**
+ * Build the preview for the current state.
+ *
+ * @param host - the store, registrar, host context and soft size cap.
+ * @returns the assembled prompt, its sections, and every warning.
+ */
+export declare function buildPreview(host: PreviewHost): Promise<PreviewResult>;
+/** URL prefix of every route this plugin owns. */
+export declare const ROUTE_PREFIX = "/dsh-system-prompt-insertion";
+/** Largest accepted request body (the state document is small; 512 KiB is slack). */
+export declare const MAX_BODY_BYTES: number;
+/** Services the routes need. */
+interface RouteDeps {
+  /** The state document. */
+  store: PromptStore;
+  /** Rebuilds the registration plan after a save. */
+  registrar: SectionRegistrar;
+  /** Produces the assembled prompt for the preview. */
+  preview(): Promise<PreviewResult>;
+  /** Logger for rejected requests. */
+  logger: StoreLogger;
+}
+/**
+ * Register the three routes on `ctx.webServer` when that service is present.
+ *
+ * The plugin stays fully functional without it (the host half needs only the
+ * prompt registry); a headless profile simply has no editor.
+ *
+ * @param ctx - the plugin context.
+ * @param deps - store, registrar, preview builder and logger.
+ */
+export declare function registerRoutes(ctx: Context, deps: RouteDeps): void;
+/** Cordis plugin name. */
+export declare const name = "system-prompt-insertion";
+/** The prompt registry must exist before a section can be registered. */
+export declare const inject: string[];
+/** The profile row's configuration. */
+export interface Config {
+  /** Master switch: `false` registers nothing and serves no routes. */
+  enabled: boolean;
+  /** State file override; empty uses `$DSH_HOME/system-prompt-insertion.json`. */
+  storeFile: string;
+  /** Soft per-section size cap reported by the editor. */
+  maxSectionBytes: number;
+}
+/** Schema for {@link Config}. */
+export declare const Config: Schema<Config>;
+/** Options resolved from {@link Config}. */
+export interface ResolvedOptions {
+  /** Absolute path of the state document. */
+  storeFile: string;
+  /** Soft per-section size cap. */
+  maxSectionBytes: number;
+}
+/**
+ * Resolve the row configuration into absolute options.
+ *
+ * @param config - the row configuration.
+ * @returns the paths and limits the plugin runs with.
+ */
+export declare function resolveOptions(config: Config): ResolvedOptions;
+/**
+ * Mount the user-owned system-prompt text and its editor.
+ *
+ * @param ctx - the profile row's context.
+ * @param config - the validated row configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export type { LayerState, OrderBases, Position, SectionSpec };