@lolkda/dsh-prompt-manager 3.0.0

package/lib/types/store.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The on-disk half of the prompt index: one markdown file per entry under a
+ * single directory, addressed by entry id.
+ *
+ * Everything a caller can name is validated before it reaches the filesystem —
+ * the id grammar is the only path segment this store ever accepts — and writes
+ * land through a temporary file plus a rename, so a crashed or interrupted
+ * write cannot leave a half-written body in the prompt.
+ *
+ * @module @lolkda/dsh-prompt-manager/store
+ */
+/** Why a store operation was refused. */
+export type PromptStoreErrorCode = 'invalid-id' | 'too-large' | 'conflict' | 'unwritable' | 'unreadable';
+/** A store operation the caller should report, not retry blindly. */
+export declare class PromptStoreError extends Error {
+    /** Machine-readable reason. */
+    readonly code: PromptStoreErrorCode;
+    /**
+     * @param code - machine-readable reason.
+     * @param message - human-facing detail.
+     */
+    constructor(code: PromptStoreErrorCode, message: string);
+}
+/** What a write expects to find on disk. */
+export type WriteFence = 
+/** Overwrite whatever is there. */
+{
+    readonly kind: 'any';
+}
+/** Refuse unless this entry has no body file yet. */
+ | {
+    readonly kind: 'absent';
+}
+/** Refuse unless the current body still hashes to `sha1`. */
+ | {
+    readonly kind: 'sha1';
+    readonly sha1: string;
+};
+/** One stored body plus the hash a later write can fence against. */
+export interface StoredBody {
+    /** Exact UTF-8 contents. */
+    body: string;
+    /** sha1 of {@link body}, the fence value for the next write. */
+    sha1: string;
+}
+/** The store's current situation, as reported to the settings page. */
+export interface StoreStatus {
+    /** Absolute directory holding the body files. */
+    dir: string;
+    /** Whether a body can be written right now. */
+    writable: boolean;
+    /** Ids that currently have a body file. */
+    ids: string[];
+}
+/**
+ * sha1 of one body, the value the settings page round-trips to fence writes.
+ * @param body - exact UTF-8 contents.
+ * @returns a lowercase hex digest.
+ */
+export declare function bodyHash(body: string): string;
+/** What one store holds: the file shape and the size a body may reach. */
+export interface PromptStoreOptions {
+    /** File extension, leading dot included. Defaults to `.md`. */
+    extension?: string | undefined;
+    /** Largest accepted body, in bytes. Defaults to {@link MAX_BODY_BYTES}. */
+    maxBytes?: number | undefined;
+}
+/**
+ * Body files for prompt entries, confined to one directory.
+ *
+ * The same guards back the user-script directory, where `id` is a script name
+ * and the file is `<name>.js`: one id grammar, one fence, one atomic write.
+ */
+export declare class PromptStore {
+    /** Absolute directory holding the body files. */
+    readonly dir: string;
+    /** File extension the store owns, leading dot included. */
+    private readonly extension;
+    /** Largest body this store accepts, in bytes. */
+    private readonly maxBytes;
+    /**
+     * @param dir - directory holding `<id><extension>`; created on first write.
+     * @param options - file extension and size cap; the prompt-body defaults are
+     * `.md` at 256 KiB, so the script store reuses every guard below unchanged.
+     */
+    constructor(dir: string, options?: PromptStoreOptions);
+    /**
+     * Absolute path of one entry's body file.
+     * @param id - entry id; validated against the id grammar.
+     * @returns the absolute file path.
+     * @throws {PromptStoreError} when the id is unusable or escapes {@link dir}.
+     */
+    bodyPath(id: string): string;
+    /**
+     * Whether a body file exists.
+     * @param id - entry id.
+     * @returns `true` when the file is present.
+     */
+    has(id: string): boolean;
+    /**
+     * Read one stored body.
+     * @param id - entry id.
+     * @returns the body and its hash, or `undefined` when no file exists.
+     * @throws {PromptStoreError} when the file exists but cannot be read.
+     */
+    read(id: string): StoredBody | undefined;
+    /**
+     * Write one body, refusing a stale editor.
+     *
+     * The fence is judged against the file as it stands when the write reaches
+     * the disk, so two editors holding the same draft cannot both land.
+     *
+     * @param id - entry id.
+     * @param body - exact UTF-8 contents to store.
+     * @param fence - what the caller expects to find; defaults to overwriting.
+     * @returns the hash of what was written.
+     * @throws {PromptStoreError} on an invalid id, oversized body, fence mismatch, or failed write.
+     */
+    write(id: string, body: string, fence?: WriteFence): StoredBody;
+    /**
+     * Remove one stored body, which restores the bundled default.
+     * @param id - entry id.
+     * @returns `true` when a file was removed.
+     * @throws {PromptStoreError} when the removal fails.
+     */
+    remove(id: string): boolean;
+    /**
+     * The directory's situation, for the settings page.
+     * @returns the directory, whether writing is possible, and the stored ids.
+     */
+    status(): StoreStatus;
+    /**
+     * Ids that currently have a body file.
+     * @returns the stored ids, in directory order; empty when the directory is absent.
+     */
+    ids(): string[];
+    /** Create {@link dir} when it is missing. */
+    private ensureDirectory;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoBH,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAA;AAExG,qEAAqE;AACrE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;IAEnC;;;OAGG;gBACS,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAKxD;AAED,4CAA4C;AAC5C,MAAM,MAAM,UAAU;AACpB,mCAAmC;AACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AAC1B,qDAAqD;GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AAC7B,6DAA6D;GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;CACb;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAA;IACX,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAA;IACjB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,EAAE,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9B;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IAEjC;;;;OAIG;gBACS,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAMzD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAO5B;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAQxB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAWxC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,UAA4B,GAAG,UAAU;IAgChF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAW3B;;;OAGG;IACH,MAAM,IAAI,WAAW;IAYrB;;;OAGG;IACH,GAAG,IAAI,MAAM,EAAE;IAaf,6CAA6C;IAC7C,OAAO,CAAC,eAAe;CAOxB"}

package/lib/types/subscriptions.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The subscription engine: the one thing the HTTP routes call, the one thing the
+ * settings page reads, and the source of truth for the bodies of subscribed
+ * entries.
+ *
+ * It owns no global state of its own. Sources come from the resolved settings
+ * document, proxy and mirror come from the same place, and the index it rewrites
+ * is handed back to the plugin through {@link SubscriptionHost.setEntries}, so
+ * the plugin stays the only writer of its own namespace.
+ *
+ * @module @lolkda/dsh-prompt-manager/subscriptions
+ */
+import { type ProxyConfig } from './net.js';
+import { type PromptSource } from './source.js';
+import { SourceWorkspace, type CheckOutcome, type PlannedChange } from './sync.js';
+import type { PromptEntry } from './entries.js';
+/** One source as the settings page sees it. */
+export interface SourceSummary {
+    /** Slug. */
+    id: string;
+    /** `owner/name`. */
+    repo: string;
+    /** Branch, tag, or commit. */
+    ref: string;
+    /** Effective mirror, with the global default already folded in. */
+    mirror: string;
+    /** Whether the source takes part in a check, an apply, or a revert. */
+    enabled: boolean;
+    /** When its files were last applied. */
+    appliedAt?: string;
+    /** Commit in force. */
+    headSha?: string;
+    /** Bodies in force. */
+    files: number;
+    /** Files a previous check staged and nobody applied yet. */
+    pending: number;
+}
+/** Where a subscribed entry's body lives. */
+export interface SubscriptionLocation {
+    /** Owning source. */
+    slug: string;
+    /** Repository-relative path. */
+    path: string;
+}
+/** What the engine needs from the plugin. */
+export interface SubscriptionHost {
+    /** Sources in force, already narrowed from the settings document. */
+    sources(): PromptSource[];
+    /** Global proxy. */
+    proxy(): ProxyConfig;
+    /** Global mirror, used when a source does not set its own. */
+    mirror(): string;
+    /** The plugin's storage root. */
+    root(): string;
+    /** The index in force. */
+    entries(): PromptEntry[];
+    /** Replace the index's entry list. */
+    setEntries(entries: PromptEntry[]): Promise<void>;
+    /** The next free placement for an added entry. */
+    nextOrder(): number;
+    /** Report a non-fatal problem. */
+    warn(message: string): void;
+}
+/** The result of applying a staged plan. */
+export interface ApplyOutcome {
+    /** Source slug. */
+    slug: string;
+    /** Changes that landed. */
+    applied: PlannedChange[];
+    /** The index after the apply. */
+    entries: PromptEntry[];
+}
+/** The subscription engine. */
+export declare class Subscriptions {
+    private readonly host;
+    /** How one source's workspace is built; replaced in tests. */
+    private readonly workspaceOf;
+    /**
+     * Where the subscribed bodies were last found.
+     *
+     * Section text is resolved on every assembly, so `readBody` runs once per
+     * subscribed entry per model step. Rebuilding this map each time would re-read
+     * and re-parse every source's `state.json` in that hot path, so it is computed
+     * once and dropped whenever the files or the source list can have changed.
+     */
+    private cachedLocations;
+    /**
+     * @param host - the plugin side of the engine.
+     * @param options - workspace factory, for tests that count what the engine reads.
+     */
+    constructor(host: SubscriptionHost, options?: {
+        workspace?: (slug: string) => SourceWorkspace;
+    });
+    /**
+     * The workspace of one source.
+     * @param slug - source id.
+     * @returns its file workspace.
+     */
+    workspace(slug: string): SourceWorkspace;
+    /**
+     * Where every subscribed entry's body lives.
+     * @returns entry id → source and path, for the entries on disk.
+     */
+    locate(): Map<string, SubscriptionLocation>;
+    /**
+     * Forget the cached map and read the sources again.
+     *
+     * Called when the source list changed, or after this engine moved files, so
+     * the map never describes a snapshot that has already been replaced.
+     *
+     * @returns the freshly computed map.
+     */
+    refreshLocations(): Map<string, SubscriptionLocation>;
+    /**
+     * Read one subscribed entry's body.
+     * @param id - entry id.
+     * @returns the body, or `undefined` when it is not a subscribed entry.
+     */
+    readBody(id: string): string | undefined;
+    /** Build the location map from every source's bookkeeping. */
+    private computeLocations;
+    /**
+     * The configured sources with their on-disk situation.
+     * @returns one summary per source.
+     */
+    list(): SourceSummary[];
+    /**
+     * Check one source against its upstream and stage whatever changed.
+     * @param slug - source id.
+     * @returns the check outcome, tagged with its source.
+     * @throws {CheckError} when the source is unknown, switched off, or the check cannot conclude.
+     */
+    check(slug: string): Promise<CheckOutcome & {
+        slug: string;
+    }>;
+    /**
+     * Apply what a check staged.
+     * @param slug - source id.
+     * @param files - paths to apply; all staged changes when omitted.
+     * @returns what landed and the index that resulted.
+     * @throws {CheckError} when nothing is staged for this source.
+     */
+    apply(slug: string, files?: readonly string[]): Promise<ApplyOutcome>;
+    /**
+     * Put back the version the last apply replaced.
+     * @param slug - source id.
+     * @returns the paths that moved back and the index that resulted.
+     */
+    revert(slug: string): Promise<{
+        slug: string;
+        reverted: string[];
+        entries: PromptEntry[];
+    }>;
+    /**
+     * Forget one source: its files and its entries.
+     *
+     * A source that is switched off can still be forgotten: removing it is exactly
+     * what a person does with one they no longer want.
+     *
+     * @param slug - source id.
+     * @returns the index that resulted.
+     */
+    remove(slug: string): Promise<{
+        slug: string;
+        entries: PromptEntry[];
+    }>;
+    /**
+     * Rebuild the index's subscribed half from every source's state.
+     *
+     * Local entries are carried through untouched. A subscribed entry keeps the
+     * title, placement, and switch a person gave it; an entry seen for the first
+     * time arrives disabled, because remote prose must not reach the prompt before
+     * someone turns it on.
+     *
+     * @returns the index now in force.
+     */
+    syncEntries(): Promise<PromptEntry[]>;
+    /**
+     * The mirror actually used for one source.
+     * @param source - the source.
+     * @returns its own mirror, or the global one.
+     */
+    private effectiveMirror;
+    /**
+     * Look one source up.
+     * @param slug - source id.
+     * @returns the source.
+     * @throws {CheckError} when no such source is configured.
+     */
+    private source;
+    /**
+     * Look up a source that may be operated on.
+     *
+     * A switched-off source keeps the bodies it already applied — turning it off
+     * is not a way to erase entries that are in force — but it takes no new work
+     * from upstream until it is switched back on.
+     *
+     * @param slug - source id.
+     * @returns the source.
+     * @throws {CheckError} when no such source is configured, or it is switched off.
+     */
+    private writableSource;
+}
+//# sourceMappingURL=subscriptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AAC1D,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAKL,eAAe,EAEf,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,WAAW,CAAA;AAClB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,YAAY;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,IAAI,YAAY,EAAE,CAAA;IACzB,oBAAoB;IACpB,KAAK,IAAI,WAAW,CAAA;IACpB,8DAA8D;IAC9D,MAAM,IAAI,MAAM,CAAA;IAChB,iCAAiC;IACjC,IAAI,IAAI,MAAM,CAAA;IACd,0BAA0B;IAC1B,OAAO,IAAI,WAAW,EAAE,CAAA;IACxB,sCAAsC;IACtC,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,kDAAkD;IAClD,SAAS,IAAI,MAAM,CAAA;IACnB,kCAAkC;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,2BAA2B;IAC3B,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,iCAAiC;IACjC,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;AAED,+BAA+B;AAC/B,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IAEvC,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAE/D;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe,CAA+C;IAEtE;;;OAGG;gBACS,IAAI,EAAE,gBAAgB,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAA;KAAO;IAKnG;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAIxC;;;OAGG;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAK3C;;;;;;;OAOG;IACH,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAKrD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMxC,8DAA8D;IAC9D,OAAO,CAAC,gBAAgB;IAWxB;;;OAGG;IACH,IAAI,IAAI,aAAa,EAAE;IAoBvB;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAUnE;;;;;;OAMG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAqB3E;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;IAWjG;;;;;;;;OAQG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;IAO7E;;;;;;;;;OASG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAgC3C;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IAMd;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;CAOvB"}

package/lib/types/sync.d.ts

@@ -0,0 +1,248 @@
+/**
+ * One source's files on disk, and the three operations the settings page drives:
+ * check what changed upstream, apply it, undo the last apply.
+ *
+ * The layout is a three-slot rotation, so nothing is ever half-updated:
+ * `staging/` holds what a check downloaded, `current/` is what the prompt reads,
+ * and `previous/` keeps the version the last apply replaced so one click can put
+ * it back. `state.json` carries the bookkeeping: which commit is in force, which
+ * entry each file became, and the hashes and validators that make the next check
+ * cheap.
+ *
+ * @module @lolkda/dsh-prompt-manager/sync
+ */
+import { type Fetcher } from './net.js';
+import { type ManifestPrompt, type PromptSource } from './source.js';
+/** One file's bookkeeping inside a source. */
+export interface SourceFileState {
+    /** Local entry id this file became. */
+    id: string;
+    /**
+     * The id this file carried before the apply that recorded it, when that apply
+     * changed the id — a manifest that started declaring its own `id`, or a file
+     * whose name changed. The index reads it to move the title, placement, and
+     * switch a person chose onto the new id instead of starting the entry over.
+     * Dropped by the next apply of the same path, so it never outlives its use.
+     */
+    renamedFromId?: string;
+    /** Display title the manifest asked for, when it asked for one. */
+    title?: string;
+    /** Placement the manifest asked for, when it asked for one. */
+    order?: number;
+    /** Whether the manifest wanted it enabled; the importer overrides on import. */
+    enabled: boolean;
+    /** sha1 of the body in force. */
+    sha1: string;
+    /** `etag` the upstream sent for that body. */
+    etag?: string;
+}
+/** A source's bookkeeping, persisted beside its files. */
+export interface SourceState {
+    /** Ref the snapshot was taken from. */
+    ref: string;
+    /** Commit in force, when the ref could be resolved to one. */
+    headSha?: string;
+    /** Commit the last apply replaced, for revert. */
+    headShaPrevious?: string;
+    /** sha1 of the manifest in force. */
+    manifestSha1?: string;
+    /** When the last apply ran, ISO-8601. */
+    appliedAt?: string;
+    /** One record per body file in force, keyed by repository path. */
+    files: Record<string, SourceFileState>;
+    /**
+     * The last apply's undo ledger: the record each touched path had before, or
+     * `null` when the path had no file at all. This is what makes revert exact —
+     * a removed file comes back with the title, placement, and switch it had.
+     */
+    undo?: Record<string, SourceFileState | null>;
+}
+/** One file the upstream check found a difference in. */
+export interface PlannedChange {
+    /** Repository-relative path. */
+    path: string;
+    /** Local entry id. */
+    id: string;
+    /** Display title from the manifest, when present. */
+    title?: string;
+    /** Placement from the manifest, when present. */
+    order?: number;
+    /** Which way the file moved. */
+    kind: 'added' | 'changed' | 'removed';
+    /** Lines the new body has and the old one did not. */
+    added: number;
+    /** Lines the old body had and the new one does not. */
+    removed: number;
+    /**
+     * On an added file: the path this file was renamed from, when the check
+     * recognised it as a rename. The pair is applied together or not at all.
+     */
+    renamedFrom?: string;
+    /**
+     * On a removal: the path this file was renamed to. Present exactly when the
+     * matching added change carries {@link renamedFrom}.
+     */
+    renamedTo?: string;
+}
+/** What a check concluded. */
+export interface CheckOutcome {
+    /** Whether upstream already matches what is in force. */
+    upToDate: boolean;
+    /** Commit the ref resolves to, when it could be resolved. */
+    headSha?: string;
+    /** Files that differ, newest manifest order first. */
+    changes: PlannedChange[];
+    /** Prompts the manifest declared, in order. */
+    prompts: ManifestPrompt[];
+    /** Non-fatal problems worth showing: an unreachable feed, a skipped file. */
+    warnings: string[];
+}
+/** What a check left staged, for a later apply to pick up. */
+export interface StagedPlan {
+    /** Commit the check resolved. */
+    headSha?: string;
+    /** sha1 of the manifest the check read. */
+    manifestSha1: string;
+    /** Prompts the manifest declared. */
+    prompts: ManifestPrompt[];
+    /** Files the check staged. */
+    changes: PlannedChange[];
+    /** `etag` per staged path, the validator the next check sends. */
+    etags: Record<string, string>;
+}
+/** A check that could not conclude. */
+export declare class CheckError extends Error {
+    /** Machine-readable reason. */
+    readonly reason: 'manifest' | 'network' | 'mirror' | 'too-large' | 'unknown-source' | 'nothing-staged' | 'disabled';
+    /**
+     * @param reason - machine-readable reason.
+     * @param message - human-facing detail.
+     */
+    constructor(reason: CheckError['reason'], message: string);
+}
+/** The files of one source, confined to one directory. */
+export declare class SourceWorkspace {
+    /** Source slug. */
+    readonly slug: string;
+    /** `<root>/sources/<slug>`. */
+    readonly dir: string;
+    /**
+     * @param root - the plugin's storage root, e.g. `$DSH_HOME/prompt-manager`.
+     * @param slug - the source id.
+     */
+    constructor(root: string, slug: string);
+    /** Directory holding the version in force. */
+    get currentDir(): string;
+    /** Directory holding the version the last apply replaced. */
+    get previousDir(): string;
+    /** Directory holding what a check downloaded but nobody applied yet. */
+    get stagingDir(): string;
+    /** Path of the bookkeeping file. */
+    get statePath(): string;
+    /**
+     * Absolute path of one body file inside one slot.
+     * @param slot - which slot.
+     * @param path - repository-relative manifest path.
+     * @returns the absolute path; a traversal attempt resolves to `undefined`.
+     */
+    slotPath(slot: 'current' | 'previous' | 'staging', path: string): string | undefined;
+    /** Whether this source has any files on disk. */
+    exists(): boolean;
+    /**
+     * Read the bookkeeping, defaulting to an empty state.
+     * @returns the state; an unreadable or malformed file reads as empty.
+     */
+    readState(): SourceState;
+    /**
+     * Persist the bookkeeping.
+     * @param state - the state to write.
+     */
+    writeState(state: SourceState): void;
+    /** Read one body from a slot. */
+    read(slot: 'current' | 'previous' | 'staging', path: string): string | undefined;
+    /** Paths present in a slot, relative to that slot. */
+    list(slot: 'current' | 'previous' | 'staging'): string[];
+    /** Write one body into the staging slot. */
+    stage(path: string, text: string): void;
+    /** Empty the staging slot. */
+    clearStaging(): void;
+    /**
+     * Record what a check staged, so an apply can run without repeating the
+     * network round trip.
+     * @param plan - the staged plan.
+     */
+    writePlan(plan: StagedPlan): void;
+    /**
+     * Read the staged plan.
+     * @returns the plan, or `undefined` when nothing is staged.
+     */
+    readPlan(): StagedPlan | undefined;
+    /** Remove the whole source directory. */
+    remove(): void;
+}
+/**
+ * Line counts of what a change adds and removes, by longest common
+ * subsequence over lines. The dynamic table is skipped for pathologically large
+ * pairs, where the answer degrades to "roughly how many lines differ" rather
+ * than stalling the request.
+ *
+ * @param before - the body in force, or `''` for a new file.
+ * @param after - the checked body.
+ * @returns added and removed line counts.
+ */
+export declare function diffCounts(before: string, after: string): {
+    added: number;
+    removed: number;
+};
+/**
+ * Check one source against its upstream and stage whatever changed.
+ *
+ * @param input - source, workspace, and the fetcher carrying the proxy and mirror.
+ * @returns what changed, or that nothing did.
+ * @throws {CheckError} when the check cannot conclude.
+ */
+export declare function checkSource(input: {
+    source: PromptSource;
+    workspace: SourceWorkspace;
+    fetcher: Fetcher;
+}): Promise<CheckOutcome>;
+/**
+ * Apply staged changes into the version in force.
+ *
+ * @param input - workspace, current state, the staged plan, the source, and the
+ * paths the caller selected (all of them when omitted).
+ * @returns the new state and the changes that landed.
+ */
+export declare function applyChanges(input: {
+    workspace: SourceWorkspace;
+    state: SourceState;
+    plan: StagedPlan;
+    source: PromptSource;
+    selected?: readonly string[];
+    nowIso: string;
+}): {
+    state: SourceState;
+    applied: PlannedChange[];
+};
+/**
+ * Put the version the last apply replaced back in force, guided by the apply's
+ * undo ledger so a restored file also gets its title, placement, and switch back.
+ *
+ * @param input - workspace and current state.
+ * @returns the restored state and the paths that moved back.
+ */
+export declare function revertChanges(input: {
+    workspace: SourceWorkspace;
+    state: SourceState;
+}): {
+    state: SourceState;
+    reverted: string[];
+};
+/**
+ * The entry title a manifest file should get on import.
+ * @param source - owning source.
+ * @param prompt - the manifest entry.
+ * @returns a non-empty display title.
+ */
+export declare function titleFor(source: PromptSource, prompt: ManifestPrompt): string;
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAWL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAA;AAEpB,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAA;IAChB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACtC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC,CAAA;CAC9C;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;IACrC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAA;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sDAAsD;IACtD,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,+CAA+C;IAC/C,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,8BAA8B;IAC9B,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B;AAED,uCAAuC;AACvC,qBAAa,UAAW,SAAQ,KAAK;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,UAAU,CAAA;IAEnH;;;OAGG;gBACS,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,0DAA0D;AAC1D,qBAAa,eAAe;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAKtC,8CAA8C;IAC9C,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,6DAA6D;IAC7D,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,wEAAwE;IACxE,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,oCAAoC;IACpC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAOpF,iDAAiD;IACjD,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACH,SAAS,IAAI,WAAW;IAuBxB;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAKpC,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhF,sDAAsD;IACtD,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,EAAE;IAexD,4CAA4C;IAC5C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAOvC,8BAA8B;IAC9B,YAAY,IAAI,IAAI;IAIpB;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAKjC;;;OAGG;IACH,QAAQ,IAAI,UAAU,GAAG,SAAS;IAuBlC,yCAAyC;IACzC,MAAM,IAAI,IAAI;CAGf;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAkB5F;AAsBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE;IACvC,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,eAAe,CAAA;IAC1B,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,OAAO,CAAC,YAAY,CAAC,CA2KxB;AAsDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,SAAS,EAAE,eAAe,CAAA;IAC1B,KAAK,EAAE,WAAW,CAAA;IAClB,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAA;CACf,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CAmEnD;AAgCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,SAAS,EAAE,eAAe,CAAA;IAC1B,KAAK,EAAE,WAAW,CAAA;CACnB,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA4B7C;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAI7E"}