@sagmans/dsh-tui 0.3.0 → 0.4.0

package/lib/stash/schema.js

@@ -0,0 +1,127 @@
+// Stash entry + file schema and pure parsing/validation helpers.
+//
+// Every disk format is validated on read, so a corrupt or hand-edited stash file
+// can never crash the editor: an unparseable file is treated as empty and
+// quarantined by the store. Keeping this module free of fs dependencies makes
+// the schema fully unit-testable.
+import { randomUUID } from 'node:crypto';
+export const STASH_SCHEMA_VERSION = 1;
+/** A stash longer than this is refused rather than stored. */
+export const MAX_STASH_ENTRY_BYTES = 1_048_576;
+const ENTRY_ID_MAX_LENGTH = 128;
+const ENTRY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const NUMERIC_SELECTOR_PATTERN = /^\d+$/u;
+const INVALID_ENTRY_ID_MESSAGE = 'invalid stash entry id';
+const ENTRY_TOO_LARGE_MESSAGE = 'stashed draft is too large';
+/**
+ * Control characters a draft can never legitimately need: everything below the
+ * printable range except the tab and line feed that lay text out, plus DEL and
+ * the C1 block.
+ *
+ * A draft is written straight into a terminal, so a sequence that reached the
+ * bank through a hand-edited or hostile file would be executed as a command —
+ * clearing the screen, or replacing the reader's clipboard over OSC 52 — instead
+ * of appearing as the text they asked for. Stripping at the storage boundary
+ * covers every path a draft can take back to the screen.
+ *
+ * The bidi overrides are stripped with them: they draw nothing, so they cannot
+ * be seen and cannot be removed by hand, and what they reorder is what the reader
+ * is about to run. A terminal that shapes right-to-left text still has the
+ * letters themselves.
+ */
+const DISALLOWED_CONTROL_CHARACTERS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
+export function stripControlCharacters(text) {
+    return text.replace(DISALLOWED_CONTROL_CHARACTERS, '');
+}
+export function isSafeEntryId(value) {
+    return value.length <= ENTRY_ID_MAX_LENGTH && ENTRY_ID_PATTERN.test(value);
+}
+export function assertSafeEntryId(value) {
+    if (!isSafeEntryId(value))
+        throw new Error(INVALID_ENTRY_ID_MESSAGE);
+}
+/** Refuse one draft that no amount of storage capacity could justify holding. */
+export function assertSafeStashText(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_STASH_ENTRY_BYTES)
+        throw new Error(ENTRY_TOO_LARGE_MESSAGE);
+}
+/** The form of a draft that is safe to hand back to a terminal. */
+export function sanitizeStashText(text) {
+    return stripControlCharacters(text);
+}
+export const createNewId = () => randomUUID();
+export function createEmptyStashFile(cwd, now) {
+    return { version: STASH_SCHEMA_VERSION, cwd, createdAt: now, updatedAt: now, entries: [] };
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isValidTimestamp(value) {
+    return typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(new Date(value).getTime());
+}
+export function normalizeEntry(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const { id, text, createdAt } = raw;
+    if (typeof id !== 'string' || !isSafeEntryId(id))
+        return undefined;
+    if (typeof text !== 'string')
+        return undefined;
+    if (!isValidTimestamp(createdAt))
+        return undefined;
+    return { id, text: sanitizeStashText(text), createdAt };
+}
+/**
+ * Read one stash file, or nothing when it is not this surface's current format.
+ *
+ * Strict on purpose: a duplicate id, a missing timestamp, or a foreign working
+ * directory is corruption the store quarantines rather than a shape to repair,
+ * because a silently repaired file can resurrect entries the reader thought they
+ * dropped — or hand another directory's drafts to this one.
+ */
+export function parseStashFile(raw) {
+    if (!isRecord(raw) || raw.version !== STASH_SCHEMA_VERSION)
+        return undefined;
+    if (typeof raw.cwd !== 'string')
+        return undefined;
+    if (!isValidTimestamp(raw.createdAt) || !isValidTimestamp(raw.updatedAt))
+        return undefined;
+    if (!Array.isArray(raw.entries))
+        return undefined;
+    const entries = [];
+    const ids = new Set();
+    for (const rawEntry of raw.entries) {
+        const entry = normalizeEntry(rawEntry);
+        if (entry === undefined || ids.has(entry.id))
+            return undefined;
+        ids.add(entry.id);
+        entries.push(entry);
+    }
+    return { version: STASH_SCHEMA_VERSION, cwd: raw.cwd, createdAt: raw.createdAt, updatedAt: raw.updatedAt, entries };
+}
+/**
+ * Resolve a selector against newest-first entries.
+ *
+ * Index 0 is the newest, mirroring git's index-0-is-tip convention. A selector
+ * is an entry id, a numeric index string, or empty for the most recent entry.
+ */
+export function resolveBySelector(entries, selector) {
+    if (entries.length === 0)
+        return undefined;
+    const trimmed = selector?.trim();
+    if (trimmed === undefined || trimmed === '') {
+        const entry = entries[0];
+        return entry === undefined ? undefined : { entry, index: 0 };
+    }
+    const index = entries.findIndex(entry => entry.id === trimmed);
+    if (index >= 0)
+        return { entry: entries[index], index };
+    if (!NUMERIC_SELECTOR_PATTERN.test(trimmed))
+        return undefined;
+    const numeric = Number(trimmed);
+    if (!Number.isSafeInteger(numeric) || numeric >= entries.length)
+        return undefined;
+    const entry = entries[numeric];
+    return entry === undefined ? undefined : { entry, index: numeric };
+}
+//# sourceMappingURL=schema.js.map

package/lib/stash/schema.js.map

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

package/lib/stash/store.d.ts

@@ -0,0 +1,92 @@
+import { rename } from 'node:fs/promises';
+import { type StashFailurePhase } from './lock.ts';
+import type { StashPaths } from './paths.ts';
+import { syncDirectoryEntry } from './private-fs.ts';
+import { type Clock, type ResolvedEntry, type StashEntry, type StashFile } from './schema.ts';
+/**
+ * A stash file larger than this is refused, never quarantined: hiding a
+ * legitimate bank because it grew past a cap would be worse than refusing it.
+ */
+export declare const MAX_STASH_FILE_BYTES = 16777216;
+/**
+ * A bank that cannot be written because it would no longer be readable.
+ *
+ * The cap is only useful if it is enforced before the write: a file that grows
+ * past it is refused by every later read, so letting one save through would turn
+ * a full bank into an unreadable one.
+ */
+export declare class StashFileTooLargeError extends Error {
+    readonly bytes: number;
+    constructor(bytes: number);
+}
+export interface AddEntryInput {
+    readonly text: string;
+    /** Caller-supplied id; generated when omitted. */
+    readonly id?: string;
+    /** Caller-supplied timestamp, used only when a recovery path restores an entry. */
+    readonly createdAt?: number;
+}
+type LoadResult = {
+    kind: 'ready';
+    file: StashFile;
+} | {
+    kind: 'corrupt';
+    quarantinedTo: string | undefined;
+    quarantineSyncFailed: boolean;
+} | {
+    kind: 'unsupported';
+    version: number;
+};
+/** Where a read moved an unreadable bank, and whether that move is durable. */
+export interface QuarantineRecord {
+    readonly path: string;
+    readonly syncFailed: boolean;
+}
+export interface StashWriteOutcome {
+    readonly committed: true;
+    readonly phase: StashFailurePhase;
+    readonly error: unknown;
+}
+export type StashWriter = (filePath: string, file: StashFile, syncDirectory?: typeof syncDirectoryEntry, replaceFile?: typeof rename) => Promise<void | StashWriteOutcome>;
+/** Stash data written by a newer build, which this one must not touch. */
+export declare class UnsupportedStashSchemaError extends Error {
+    readonly detectedVersion: number;
+    readonly supportedVersion: number;
+    constructor(detectedVersion: number, supportedVersion?: number);
+}
+export declare class StashStore {
+    private file;
+    private corruptRecovery;
+    private readonly filePath;
+    private readonly paths;
+    private readonly now;
+    private readonly write;
+    constructor(paths: StashPaths, loaded: LoadResult, now?: Clock, write?: StashWriter);
+    get entries(): readonly StashEntry[];
+    get entryCount(): number;
+    /** The recovery location the last read produced, if any, reported once. */
+    takeQuarantine(): QuarantineRecord | undefined;
+    /** Resolve a selector against the entries currently held. */
+    find(selector: string | undefined): ResolvedEntry | undefined;
+    refresh(): Promise<void>;
+    add(input: AddEntryInput): Promise<ResolvedEntry>;
+    /** Remove one entry by its exact id, reporting what was removed. */
+    removeById(id: string): Promise<ResolvedEntry | undefined>;
+    /** Remove the entry a selector names, reporting what was removed. */
+    drop(selector: string | undefined): Promise<ResolvedEntry | undefined>;
+    /**
+     * Remove drafts, reporting how many were dropped.
+     *
+     * Ids restrict the removal to exactly what a reader confirmed. Clearing
+     * whatever is on disk instead would delete drafts another surface added while
+     * the confirmation was on screen, which is a loss nobody agreed to.
+     */
+    clear(ids?: readonly string[]): Promise<number>;
+    private removeAt;
+    private persistMutation;
+    private reloadFresh;
+}
+export declare function loadStashStore(paths: StashPaths, now?: Clock, write?: StashWriter): Promise<StashStore>;
+export declare function writeStashFile(filePath: string, file: StashFile, syncDirectory?: typeof syncDirectoryEntry, replaceFile?: typeof rename): Promise<void | StashWriteOutcome>;
+export {};
+//# sourceMappingURL=store.d.ts.map

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

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

package/lib/stash/store.js

@@ -0,0 +1,262 @@
+// StashStore: on-disk CRUD for stash entries, scoped to one working directory.
+//
+// Entries are stored newest-first (`entries[0]` is `stash@{0}`), mirroring git's
+// index-0-is-tip convention. Every mutation re-reads the file inside an
+// exclusive lock so two surfaces in the same directory cannot lose updates to a
+// read-modify-write race. Writes are atomic (exclusive temp + rename + directory
+// fsync) with tight 0o600/0o700 permissions, because a stashed draft may hold
+// anything the reader was about to send. A corrupt file is quarantined rather
+// than overwritten, so a hand-edit mistake never silently destroys saved drafts.
+import { rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { StashCommittedError, withStashFileLock, withStashMutationLock, } from "./lock.js";
+import { ensurePrivateDirectory, hasErrorCode, quarantinePrivateFile, readPrivateTextFile, syncDirectoryEntry, writePrivateFileExclusive, } from "./private-fs.js";
+import { assertSafeEntryId, assertSafeStashText, createEmptyStashFile, createNewId, isRecord, parseStashFile, resolveBySelector, sanitizeStashText, STASH_SCHEMA_VERSION, } from "./schema.js";
+/**
+ * A stash file larger than this is refused, never quarantined: hiding a
+ * legitimate bank because it grew past a cap would be worse than refusing it.
+ */
+export const MAX_STASH_FILE_BYTES = 16_777_216;
+const DUPLICATE_STASH_ID_MESSAGE = 'duplicate stash id';
+const UNSUPPORTED_SCHEMA_GUIDANCE = 'Upgrade dsh-tui before using this stash, or move the stash file aside for safe recovery.';
+const FILE_TOO_LARGE_MESSAGE = 'this directory has no room left for another draft; drop one first';
+/**
+ * A bank that cannot be written because it would no longer be readable.
+ *
+ * The cap is only useful if it is enforced before the write: a file that grows
+ * past it is refused by every later read, so letting one save through would turn
+ * a full bank into an unreadable one.
+ */
+export class StashFileTooLargeError extends Error {
+    bytes;
+    constructor(bytes) {
+        super(FILE_TOO_LARGE_MESSAGE);
+        this.name = 'StashFileTooLargeError';
+        this.bytes = bytes;
+    }
+}
+/** Stash data written by a newer build, which this one must not touch. */
+export class UnsupportedStashSchemaError extends Error {
+    detectedVersion;
+    supportedVersion;
+    constructor(detectedVersion, supportedVersion = STASH_SCHEMA_VERSION) {
+        super(`stash data uses version ${detectedVersion}; this build supports versions through ${supportedVersion}. ${UNSUPPORTED_SCHEMA_GUIDANCE}`);
+        this.name = 'UnsupportedStashSchemaError';
+        this.detectedVersion = detectedVersion;
+        this.supportedVersion = supportedVersion;
+    }
+}
+export class StashStore {
+    file;
+    corruptRecovery;
+    filePath;
+    paths;
+    now;
+    write;
+    constructor(paths, loaded, now = Date.now, write = writeStashFile) {
+        this.paths = paths;
+        this.now = now;
+        this.write = write;
+        this.file = loaded.kind === 'ready' ? loaded.file : createEmptyStashFile(paths.cwd, now());
+        this.corruptRecovery =
+            loaded.kind === 'corrupt' && loaded.quarantinedTo !== undefined
+                ? { path: loaded.quarantinedTo, syncFailed: loaded.quarantineSyncFailed }
+                : undefined;
+        this.filePath = paths.file;
+    }
+    get entries() {
+        return this.file.entries;
+    }
+    get entryCount() {
+        return this.file.entries.length;
+    }
+    /** The recovery location the last read produced, if any, reported once. */
+    takeQuarantine() {
+        const recovery = this.corruptRecovery;
+        this.corruptRecovery = undefined;
+        return recovery;
+    }
+    /** Resolve a selector against the entries currently held. */
+    find(selector) {
+        return resolveBySelector(this.file.entries, selector);
+    }
+    async refresh() {
+        await withStashFileLock(this.filePath, () => this.reloadFresh());
+    }
+    async add(input) {
+        const id = input.id ?? createNewId();
+        assertSafeEntryId(id);
+        assertSafeStashText(input.text);
+        // A draft is stored in the form it is safe to draw again, so no path back to
+        // the screen has to remember to strip it.
+        const text = sanitizeStashText(input.text);
+        return withStashMutationLock(this.filePath, async () => {
+            await this.reloadFresh();
+            if (this.file.entries.some(entry => entry.id === id))
+                throw new Error(DUPLICATE_STASH_ID_MESSAGE);
+            const entry = { id, text, createdAt: input.createdAt ?? this.now() };
+            const next = {
+                ...this.file,
+                updatedAt: entry.createdAt,
+                entries: [entry, ...this.file.entries],
+            };
+            return this.persistMutation(next, { entry, index: 0 });
+        });
+    }
+    /** Remove one entry by its exact id, reporting what was removed. */
+    async removeById(id) {
+        assertSafeEntryId(id);
+        return withStashMutationLock(this.filePath, async () => {
+            await this.reloadFresh();
+            return this.removeAt(selector => selector === id);
+        });
+    }
+    /** Remove the entry a selector names, reporting what was removed. */
+    async drop(selector) {
+        return withStashMutationLock(this.filePath, async () => {
+            await this.reloadFresh();
+            const resolved = resolveBySelector(this.file.entries, selector);
+            if (resolved === undefined)
+                return { didPersist: false, result: undefined };
+            const next = {
+                ...this.file,
+                updatedAt: this.now(),
+                entries: this.file.entries.filter((_, index) => index !== resolved.index),
+            };
+            return this.persistMutation(next, resolved);
+        });
+    }
+    /**
+     * Remove drafts, reporting how many were dropped.
+     *
+     * Ids restrict the removal to exactly what a reader confirmed. Clearing
+     * whatever is on disk instead would delete drafts another surface added while
+     * the confirmation was on screen, which is a loss nobody agreed to.
+     */
+    async clear(ids) {
+        return withStashMutationLock(this.filePath, async () => {
+            await this.reloadFresh();
+            const confirmed = ids === undefined ? undefined : new Set(ids);
+            const kept = confirmed === undefined ? [] : this.file.entries.filter(entry => !confirmed.has(entry.id));
+            const removed = this.file.entries.length - kept.length;
+            if (removed === 0)
+                return { didPersist: false, result: 0 };
+            const next = {
+                ...createEmptyStashFile(this.paths.cwd, this.now()),
+                updatedAt: this.now(),
+                entries: kept,
+            };
+            return this.persistMutation(next, removed);
+        });
+    }
+    async removeAt(match) {
+        const index = this.file.entries.findIndex(entry => match(entry.id));
+        const found = index < 0 ? undefined : this.file.entries[index];
+        if (found === undefined)
+            return { didPersist: false, result: undefined };
+        const next = {
+            ...this.file,
+            updatedAt: this.now(),
+            entries: this.file.entries.filter((_, position) => position !== index),
+        };
+        return this.persistMutation(next, { entry: found, index });
+    }
+    async persistMutation(next, result) {
+        const outcome = await this.write(this.filePath, next);
+        this.file = next;
+        if (outcome?.committed === true) {
+            throw new StashCommittedError(result, { phase: outcome.phase, error: outcome.error });
+        }
+        return { didPersist: true, result };
+    }
+    async reloadFresh() {
+        const loaded = await readCurrentStashFile(this.filePath, this.paths.cwd, this.now());
+        if (loaded.kind === 'ready') {
+            this.file = loaded.file;
+            return;
+        }
+        if (loaded.kind === 'unsupported')
+            throw new UnsupportedStashSchemaError(loaded.version);
+        // Corrupt input is quarantined and replaced in memory, so later writes
+        // cannot resurrect entries from the invalidated snapshot.
+        this.file = createEmptyStashFile(this.paths.cwd, this.now());
+        this.corruptRecovery =
+            loaded.quarantinedTo === undefined
+                ? undefined
+                : { path: loaded.quarantinedTo, syncFailed: loaded.quarantineSyncFailed };
+    }
+}
+export async function loadStashStore(paths, now = Date.now, write = writeStashFile) {
+    const loaded = await withStashFileLock(paths.file, () => readCurrentStashFile(paths.file, paths.cwd, now()));
+    if (loaded.kind === 'unsupported')
+        throw new UnsupportedStashSchemaError(loaded.version);
+    return new StashStore(paths, loaded, now, write);
+}
+async function readCurrentStashFile(filePath, cwd, now) {
+    let source;
+    try {
+        source = await readPrivateTextFile(filePath, 'stash file', MAX_STASH_FILE_BYTES);
+    }
+    catch (error) {
+        // A missing bank is an empty one; an oversized or unreadable bank is a real
+        // failure the caller must report rather than silently start over from.
+        if (hasErrorCode(error, 'ENOENT'))
+            return { kind: 'ready', file: createEmptyStashFile(cwd, now) };
+        throw error;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(source.text);
+    }
+    catch {
+        return await quarantineCorrupt(filePath, source.identity);
+    }
+    const parsed = parseStashFile(raw);
+    if (parsed !== undefined && parsed.cwd === cwd)
+        return { kind: 'ready', file: parsed };
+    if (isRecord(raw) &&
+        typeof raw.version === 'number' &&
+        Number.isSafeInteger(raw.version) &&
+        raw.version > STASH_SCHEMA_VERSION) {
+        return { kind: 'unsupported', version: raw.version };
+    }
+    return await quarantineCorrupt(filePath, source.identity);
+}
+async function quarantineCorrupt(filePath, identity) {
+    const quarantined = await quarantinePrivateFile(filePath, identity, `corrupt-${Date.now()}`);
+    return { kind: 'corrupt', quarantinedTo: quarantined.path, quarantineSyncFailed: quarantined.syncError !== undefined };
+}
+export async function writeStashFile(filePath, file, syncDirectory = syncDirectoryEntry, replaceFile = rename) {
+    const directory = path.dirname(filePath);
+    await ensurePrivateDirectory(directory);
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const data = `${JSON.stringify(file, null, 2)}\n`;
+    // Every later read refuses a file past this cap, so a write that would cross
+    // it has to be refused here instead: the alternative is a bank that saves
+    // successfully, clears the editor, and can never be opened again.
+    const bytes = Buffer.byteLength(data);
+    if (bytes > MAX_STASH_FILE_BYTES)
+        throw new StashFileTooLargeError(bytes);
+    let tempCreated = false;
+    try {
+        await writePrivateFileExclusive(tempPath, data);
+        tempCreated = true;
+        await replaceFile(tempPath, filePath);
+        tempCreated = false;
+    }
+    catch (error) {
+        if (tempCreated)
+            await rm(tempPath, { force: true });
+        throw error;
+    }
+    // The rename is durable once the directory naming the file is flushed. The
+    // directories that name the storage itself were flushed when they were created,
+    // so this is the entry the save is actually responsible for.
+    try {
+        await syncDirectory(directory);
+    }
+    catch (error) {
+        return { committed: true, phase: 'directory-sync', error };
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/stash/store.js.map

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

package/lib/stash.d.ts

@@ -0,0 +1,91 @@
+import type { ResolvedEntry } from './stash/schema.ts';
+import { type StashWriter } from './stash/store.ts';
+/**
+ * Everything the stash needs from the surface.
+ *
+ * The surface owns the editor and the picker, so the stash asks for text and
+ * hands back text; it never reaches into a component of its own. `render` is
+ * called after every state change so the status count follows the bank, and
+ * `editorIsAvailable` is what tells a stash that the bar is the reader's rather
+ * than a question's: writing a draft into an answer would submit it as one.
+ */
+export interface StashHost {
+    /** The draft as written, with a pasted block expanded back to its text. */
+    getEditorText(): string;
+    setEditorText(text: string): void;
+    /** Whether the prompt bar currently belongs to the reader. */
+    editorIsAvailable(): boolean;
+    notice(message: string): void;
+    /** Ask the reader which entry to take, by id; undefined when they leave. */
+    pick(entries: readonly ResolvedEntry[], cwdLabel: string): Promise<string | undefined>;
+    /** Ask the reader to confirm clearing `count` drafts. */
+    confirm(count: number): Promise<boolean>;
+    render(): void;
+}
+export interface PromptStashOptions {
+    readonly cwd: string;
+    /** Override the storage root; tests keep it inside a scratch directory. */
+    readonly baseDir?: string | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly write?: StashWriter | undefined;
+}
+export declare class PromptStash {
+    private readonly host;
+    private readonly options;
+    private readonly paths;
+    private readonly now;
+    private readonly write;
+    private store;
+    private count;
+    /** The queue a second command waits behind, so writes never interleave. */
+    private tail;
+    constructor(host: StashHost, options: PromptStashOptions);
+    /** How many drafts this directory holds, as last read. */
+    get entryCount(): number;
+    /** Load the bank once at startup so the status count is real before a command. */
+    open(): Promise<void>;
+    /**
+     * Persist the draft the reader is looking at, or the one named on the command
+     * line.
+     *
+     * An argument is written into the editor before the write is attempted —
+     * before the bank is even opened — because the command line it came from is
+     * already gone: a refused write has to leave the draft where the reader can
+     * retry it instead of losing the only copy. A command that names nothing — the
+     * chord, or a bare `/stash` — parks whatever the bar is holding.
+     */
+    stashEditor(typed?: string): Promise<void>;
+    /** Put a draft in an empty editor without removing it. */
+    apply(selector: string | undefined): Promise<void>;
+    /** Put a draft in an empty editor and remove it from the bank. */
+    pop(selector: string | undefined): Promise<void>;
+    /** Open the list and pop whatever the reader takes. */
+    list(cwdLabel: string): Promise<void>;
+    /** Delete one draft without using it. */
+    drop(selector: string | undefined): Promise<void>;
+    /** Confirm, then delete every draft the confirmation named. */
+    clear(): Promise<void>;
+    /**
+     * Put one entry in an empty editor, then remove it.
+     *
+     * The editor is filled before the entry is removed, so a crash between the two
+     * leaves the draft in the bank rather than only in a terminal that is gone.
+     */
+    private popFrom;
+    private editorIsReady;
+    /**
+     * Whether the bar is the reader's to write in.
+     *
+     * A question borrows the bar and empties it, so an empty check alone would
+     * let a pop write the draft into an answer, and the draft's only other copy is
+     * deleted right afterwards.
+     */
+    private editorIsAvailable;
+    private missingMessage;
+    private ensure;
+    private run;
+    private enqueue;
+    /** Publish the bank's size and any quarantine the last read produced. */
+    private sync;
+}
+//# sourceMappingURL=stash.d.ts.map

package/lib/stash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stash.d.ts","sourceRoot":"","sources":["../src/stash.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAA;AAsBzB;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,aAAa,IAAI,MAAM,CAAA;IACvB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,8DAA8D;IAC9D,iBAAiB,IAAI,OAAO,CAAA;IAC5B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,4EAA4E;IAC5E,IAAI,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACtF,yDAAyD;IACzD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACxC,MAAM,IAAI,IAAI,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAA;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CACzC;AASD,qBAAa,WAAW;IAUpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAAI;IACjB,2EAA2E;IAC3E,OAAO,CAAC,IAAI,CAAmC;gBAG5B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,kBAAkB;IAO9C,0DAA0D;IAC1D,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,kFAAkF;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC1C,0DAA0D;IAC1D,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAclD,kEAAkE;IAClE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,uDAAuD;IACvD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrC,yCAAyC;IACzC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBjD,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BtB;;;;;OAKG;YACW,OAAO;IAoBrB,OAAO,CAAC,aAAa;IAOrB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,cAAc;YAOR,MAAM;IAOpB,OAAO,CAAC,GAAG;IAYX,OAAO,CAAC,OAAO;IAMf,yEAAyE;IACzE,OAAO,CAAC,IAAI;CAWb"}