@sagmans/dsh-tui 0.3.0 → 0.5.0

package/lib/stash.js

@@ -0,0 +1,353 @@
+// User-facing prompt-stash operations, independent of the terminal surface.
+//
+// Every command funnels through one serial queue, so a chord and a typed command
+// can never interleave a read-modify-write on the same bank. The surface is
+// reached through a small host seam, which keeps these operations testable
+// without a terminal and keeps the editor's own text rules — an expanded paste
+// and an empty bar — in exactly one place.
+import { FileTooLargeError } from "./stash/private-fs.js";
+import { StashCommittedError } from "./stash/lock.js";
+import { resolveStashPaths, stashBaseDir } from "./stash/paths.js";
+import { loadStashStore, UnsupportedStashSchemaError, } from "./stash/store.js";
+const EDITOR_BLOCKED_MESSAGE = 'clear or stash the current draft before applying or popping';
+const EDITOR_BUSY_MESSAGE = 'the prompt bar is answering a question; finish or cancel it first';
+const NOTHING_TO_STASH_MESSAGE = 'nothing to stash';
+const NO_DRAFTS_MESSAGE = 'no stashed drafts';
+const CORRUPT_RECOVERY_MESSAGE = 'corrupt stash data was quarantined to';
+const CORRUPT_RECOVERY_UNSYNCED_MESSAGE = ' (its directory could not be synced, so the copy may not survive a crash)';
+const SESSION_CHANGED_MESSAGE = 'the session changed; the stash stayed with the session it belonged to';
+const stashedMessage = (index) => `Stashed [${index}]`;
+const appliedMessage = (index) => `Applied [${index}]`;
+const poppedMessage = (index) => `Popped [${index}]`;
+const droppedMessage = (index) => `Dropped [${index}]`;
+const clearedMessage = (count) => `Cleared ${count} draft${count === 1 ? '' : 's'}`;
+const selectorMissingMessage = (selector) => `no stash matching "${selector}"`;
+const committedMessage = (error, done) => error.releaseFailure === undefined
+    ? `${done}, but the ${error.failure.phase} step failed`
+    : `${done}, but the ${error.failure.phase} and ${error.releaseFailure.phase} steps failed`;
+const removalFailedMessage = (error, done) => `${done}, but removing the entry failed: ${error instanceof Error ? error.message : 'unknown error'}`;
+function describeFailure(error) {
+    const detail = error instanceof Error ? error.message : 'unknown error';
+    return error instanceof UnsupportedStashSchemaError || error instanceof FileTooLargeError
+        ? `stash unavailable: ${detail}`
+        : `stash failed: ${detail}`;
+}
+export class PromptStash {
+    host;
+    options;
+    baseDir;
+    now;
+    write;
+    store;
+    /** The session `store` was read for, so a switch can be told from a re-read. */
+    scope;
+    count = 0;
+    /** The queue a second command waits behind, so writes never interleave. */
+    tail = Promise.resolve();
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        this.baseDir = options.baseDir ?? stashBaseDir();
+        this.now = options.now;
+        this.write = options.write;
+    }
+    /** How many drafts this session holds, as last read. */
+    get entryCount() {
+        return this.count;
+    }
+    /**
+     * Read the bank of the session in force, so the status count is real before a
+     * command and after the surface moves to another session. A read creates
+     * nothing on disk, so a session that never stashes leaves no file behind.
+     */
+    open() {
+        return this.enqueue(async () => {
+            try {
+                await this.ensure(this.options.sessionId());
+            }
+            catch (error) {
+                this.host.notice(describeFailure(error));
+            }
+            this.sync();
+        });
+    }
+    /**
+     * 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) {
+        const sessionId = this.options.sessionId();
+        const named = typed !== undefined && typed.trim() !== '';
+        // The draft goes back into the bar before anything can fail, including
+        // opening the bank: the command line it was typed on is already gone, so
+        // this is the only copy until a write lands.
+        const available = this.host.editorIsAvailable();
+        if (named && available)
+            this.host.setEditorText(typed);
+        // The bar is read now, not when the queue reaches this command: a session
+        // switch in between would otherwise park the next session's draft in this
+        // bank and clear it from the bar the reader is typing in.
+        const captured = available ? (named ? typed : this.host.getEditorText()) : undefined;
+        return this.run(sessionId, async (store) => {
+            if (captured === undefined) {
+                this.host.notice(EDITOR_BUSY_MESSAGE);
+                return;
+            }
+            const text = captured;
+            if (text.trim() === '') {
+                this.host.notice(NOTHING_TO_STASH_MESSAGE);
+                return;
+            }
+            let resolved;
+            let warning;
+            try {
+                resolved = await store.add({ text });
+            }
+            catch (error) {
+                if (!(error instanceof StashCommittedError))
+                    throw error;
+                // The draft is on disk; only the step after the write failed. Reporting
+                // a failure here would invite a retry that stashes the same draft twice.
+                resolved = error.result;
+                warning = committedMessage(error, stashedMessage(resolved.index));
+            }
+            // Only clear what was actually persisted, and only while the bar is still
+            // the reader's and still this session's: a question can borrow the bar
+            // during the write, and a session switch moves the whole surface on.
+            const current = this.isCurrentSession(sessionId);
+            if (current && this.host.editorIsAvailable() && this.host.getEditorText() === text)
+                this.host.setEditorText('');
+            this.host.notice(current ? (warning ?? stashedMessage(resolved.index)) : SESSION_CHANGED_MESSAGE);
+        });
+    }
+    /** Put a draft in an empty editor without removing it. */
+    apply(selector) {
+        const sessionId = this.options.sessionId();
+        return this.run(sessionId, async (store) => {
+            await store.refresh();
+            if (this.abandonIfMoved(sessionId))
+                return;
+            if (!this.editorIsReady())
+                return;
+            const resolved = store.find(selector);
+            if (resolved === undefined) {
+                this.host.notice(this.missingMessage(selector));
+                return;
+            }
+            this.host.setEditorText(resolved.entry.text);
+            this.host.notice(appliedMessage(resolved.index));
+        });
+    }
+    /** Put a draft in an empty editor and remove it from the bank. */
+    pop(selector) {
+        const sessionId = this.options.sessionId();
+        return this.run(sessionId, async (store) => {
+            // Re-read before resolving so "newest" is newest on disk, not newest as of
+            // the last command; the removal re-reads again under the lock.
+            await store.refresh();
+            await this.popFrom(store, sessionId, selector);
+        });
+    }
+    /** Open the list and pop whatever the reader takes. */
+    list(sessionLabel) {
+        const sessionId = this.options.sessionId();
+        return this.run(sessionId, async (store) => {
+            await store.refresh();
+            if (this.abandonIfMoved(sessionId))
+                return;
+            if (store.entryCount === 0) {
+                this.host.notice(NO_DRAFTS_MESSAGE);
+                return;
+            }
+            // The list is handed each entry with the index the bank gives it, so the
+            // row a reader picks and the selector they could have typed agree.
+            const rows = store.entries.map((entry, index) => ({ entry, index }));
+            const picked = await this.host.pick(rows, sessionLabel);
+            if (picked === undefined)
+                return;
+            await this.popFrom(store, sessionId, picked);
+        });
+    }
+    /** Delete one draft without using it. */
+    drop(selector) {
+        const sessionId = this.options.sessionId();
+        return this.run(sessionId, async (store) => {
+            let resolved;
+            let warning;
+            try {
+                resolved = await store.drop(selector);
+            }
+            catch (error) {
+                if (!(error instanceof StashCommittedError))
+                    throw error;
+                resolved = error.result;
+                if (resolved === undefined)
+                    return;
+                warning = committedMessage(error, droppedMessage(resolved.index));
+            }
+            if (resolved === undefined) {
+                this.host.notice(this.missingMessage(selector));
+                return;
+            }
+            this.host.notice(warning ?? droppedMessage(resolved.index));
+        });
+    }
+    /** Confirm, then delete every draft the confirmation named. */
+    clear() {
+        const sessionId = this.options.sessionId();
+        return this.run(sessionId, async (store) => {
+            await store.refresh();
+            if (this.abandonIfMoved(sessionId))
+                return;
+            const count = store.entryCount;
+            if (count === 0) {
+                this.host.notice(NO_DRAFTS_MESSAGE);
+                return;
+            }
+            // The ids the reader was shown, not the ids on disk afterwards: another
+            // surface can stash while the dialog is open, and those drafts were never
+            // part of what this confirmation agreed to delete.
+            const confirmedIds = store.entries.map(entry => entry.id);
+            if (!(await this.host.confirm(confirmedIds.length)))
+                return;
+            let removed = confirmedIds.length;
+            let warning;
+            try {
+                removed = await store.clear(confirmedIds);
+            }
+            catch (error) {
+                if (!(error instanceof StashCommittedError))
+                    throw error;
+                removed = error.result;
+                warning = committedMessage(error, clearedMessage(removed));
+            }
+            this.host.notice(warning ?? clearedMessage(removed));
+        });
+    }
+    /**
+     * 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.
+     */
+    async popFrom(store, sessionId, selector) {
+        if (this.abandonIfMoved(sessionId))
+            return;
+        if (!this.editorIsReady())
+            return;
+        const resolved = store.find(selector);
+        if (resolved === undefined) {
+            this.host.notice(this.missingMessage(selector));
+            return;
+        }
+        this.host.setEditorText(resolved.entry.text);
+        try {
+            const removed = await store.removeById(resolved.entry.id);
+            this.host.notice(poppedMessage(removed?.index ?? resolved.index));
+        }
+        catch (error) {
+            if (error instanceof StashCommittedError) {
+                this.host.notice(committedMessage(error, poppedMessage(resolved.index)));
+                return;
+            }
+            this.host.notice(removalFailedMessage(error, poppedMessage(resolved.index)));
+        }
+    }
+    editorIsReady() {
+        if (!this.editorIsAvailable())
+            return false;
+        if (this.host.getEditorText().trim() === '')
+            return true;
+        this.host.notice(EDITOR_BLOCKED_MESSAGE);
+        return false;
+    }
+    /**
+     * 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.
+     */
+    editorIsAvailable() {
+        if (this.host.editorIsAvailable())
+            return true;
+        this.host.notice(EDITOR_BUSY_MESSAGE);
+        return false;
+    }
+    missingMessage(selector) {
+        const trimmed = selector?.trim();
+        return trimmed === undefined || trimmed === ''
+            ? NO_DRAFTS_MESSAGE
+            : selectorMissingMessage(trimmed);
+    }
+    /**
+     * The store of one session, loaded on first use.
+     *
+     * The session is passed in rather than read here: a command must act on the
+     * session the reader was on when they asked for it, even when the surface
+     * moves on before the queue reaches that command.
+     */
+    async ensure(sessionId) {
+        if (this.store !== undefined && this.scope === sessionId)
+            return this.store;
+        const store = await loadStashStore(resolveStashPaths(sessionId, this.baseDir), this.now, this.write);
+        this.store = store;
+        this.scope = sessionId;
+        return store;
+    }
+    run(sessionId, operation) {
+        return this.enqueue(async () => {
+            try {
+                await operation(await this.ensure(sessionId));
+            }
+            catch (error) {
+                this.host.notice(describeFailure(error));
+            }
+            finally {
+                this.sync();
+            }
+        });
+    }
+    /** Whether the surface still shows the session a command was issued in. */
+    isCurrentSession(sessionId) {
+        return this.options.sessionId() === sessionId;
+    }
+    /**
+     * Stop a command whose session left the screen before the bar could be reached.
+     *
+     * The bank half has already run for the session that asked for it; writing its
+     * draft into whatever bar is on screen now would hand it to the wrong reader.
+     */
+    abandonIfMoved(sessionId) {
+        if (this.isCurrentSession(sessionId))
+            return false;
+        this.host.notice(SESSION_CHANGED_MESSAGE);
+        return true;
+    }
+    enqueue(operation) {
+        const run = this.tail.then(operation, operation);
+        this.tail = run.catch(() => undefined);
+        return run;
+    }
+    /** Publish the bank's size and any quarantine the last read produced. */
+    sync() {
+        if (this.store !== undefined) {
+            // A store read for a session the surface has left is not the count to
+            // draw; the open that follows the switch publishes the right one.
+            this.count = this.scope === this.options.sessionId() ? this.store.entryCount : 0;
+            const quarantine = this.store.takeQuarantine();
+            if (quarantine !== undefined) {
+                const durability = quarantine.syncFailed ? CORRUPT_RECOVERY_UNSYNCED_MESSAGE : '';
+                this.host.notice(`${CORRUPT_RECOVERY_MESSAGE} ${quarantine.path}${durability}`);
+            }
+        }
+        this.host.render();
+    }
+}
+//# sourceMappingURL=stash.js.map

package/lib/stash.js.map

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

package/lib/terminal/external-editor.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Where a reader's editor is configured, most specific first.
+ *
+ * VISUAL is the full-screen editor and EDITOR the line one, which is the
+ * distinction a surface that gives up the whole screen cares about; a reader
+ * who set only one of them still gets it.
+ */
+export declare const EDITOR_ENV_KEYS: readonly ["VISUAL", "EDITOR"];
+/** A draft larger than this is left where it is rather than handed to the bar. */
+export declare const MAX_DRAFT_BYTES = 1048576;
+/**
+ * One configured command line as argv, or undefined when it names nothing.
+ *
+ * A reader writes an editor the way a shell would take it — `code --wait`,
+ * `emacsclient -t` — so the line is split the way a shell would split it:
+ * quotes group, and nothing else is special. No shell ever sees the result,
+ * because an environment value is data and a shell would execute a typo. An
+ * unterminated quote takes the rest of the line rather than refusing the whole
+ * binding: a missing quote should not leave the reader with no editor at all.
+ */
+export declare function parseEditorCommand(value: string): readonly string[] | undefined;
+/** The editor this environment configures, or undefined when none is usable. */
+export declare function resolveEditorCommand(env?: NodeJS.ProcessEnv): readonly string[] | undefined;
+/**
+ * What this module needs from the surface while a child owns the terminal.
+ *
+ * `suspend` and `resume` are the whole reason the handoff is safe — the
+ * alternate screen has to leave before the child starts and be asked for again
+ * after it ends — and only the surface owns that object. `notice` is how a
+ * refusal or a failure reaches the reader, who is looking at the transcript.
+ */
+export interface EditorTerminalHost {
+    suspend(): void;
+    resume(): void;
+    notice(message: string): void;
+}
+/** The slice of a spawned child this module waits on. */
+export interface EditorChild {
+    on(event: 'error', listener: (error: Error) => void): void;
+    on(event: 'exit', listener: (code: number | null, signal: string | null) => void): void;
+}
+export interface EditorSpawnOptions {
+    readonly stdio: 'inherit';
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+}
+/** The one process call this module makes, so a spec can drive it without a terminal. */
+export type EditorSpawn = (file: string, args: readonly string[], options: EditorSpawnOptions) => EditorChild;
+/** How the handoff runs; every part a spec would otherwise have to fake is overridable. */
+export interface ExternalEditorOptions {
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Where the scratch directory is made; tests keep theirs out of the real tmpdir. */
+    readonly tempRoot?: string | undefined;
+    readonly spawn?: EditorSpawn | undefined;
+}
+/**
+ * The reader's editor, opened over one draft.
+ *
+ * Every failure is reported through the host and answered with `undefined`
+ * ("keep what the bar had") rather than thrown, because the caller is a key
+ * press with nowhere to put an error.
+ */
+export declare class ExternalEditor {
+    private readonly host;
+    private readonly env;
+    private readonly tempRoot;
+    private readonly spawn;
+    /** Whether a child holds the terminal; a second handoff would stop it twice. */
+    private running;
+    constructor(host: EditorTerminalHost, options?: ExternalEditorOptions);
+    /** Edit `text` in the reader's editor, and return what was saved, or undefined to keep the bar. */
+    edit(text: string): Promise<string | undefined>;
+    /**
+     * What the editor saved, read through one handle.
+     *
+     * The file is opened without following a link and read through that same
+     * handle, so a replacement between a check and a read cannot slip past it, a
+     * fifo left in the draft's place cannot block the surface, and the read stops
+     * one byte past the cap so a file that grows while it is read cannot exhaust
+     * memory.
+     */
+    private readDraft;
+    /**
+     * Run the editor over one file, and report only whether it could be started.
+     *
+     * A non-zero exit is not a failure: an editor that refused to save its buffer
+     * already told the reader why, and whatever it did save is what they meant to
+     * keep. A child that never started emits `error` and no `exit`, so either one
+     * settling the wait is the answer.
+     */
+    private run;
+}
+//# sourceMappingURL=external-editor.d.ts.map

package/lib/terminal/external-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-editor.d.ts","sourceRoot":"","sources":["../../src/terminal/external-editor.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,+BAAgC,CAAA;AAS5D,kFAAkF;AAClF,eAAO,MAAM,eAAe,UAAY,CAAA;AAuBxC;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CA2B/E;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAQxG;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,IAAI,CAAA;IACf,MAAM,IAAI,IAAI,CAAA;IACd,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;IAC1D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAA;CACxF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAChC;AAED,yFAAyF;AACzF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,KAAK,WAAW,CAAA;AAiB7G,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAA;IAC5C,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CACzC;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IAQvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,gFAAgF;IAChF,OAAO,CAAC,OAAO,CAAQ;gBAGJ,IAAI,EAAE,kBAAkB,EACzC,OAAO,GAAE,qBAA0B;IAOrC,mGAAmG;IAC7F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAwErD;;;;;;;;OAQG;YACW,SAAS;IAkBvB;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG;CAiBZ"}