@nexus-aethra/dshell-std 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Aethra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/contracts.js

@@ -0,0 +1,129 @@
+/**
+ * Every dshell wire contract: the `/api/dshell/*` paths and the shapes that
+ * cross them.
+ *
+ * Layering rule for this file, and for this package as a whole: it declares
+ * FACTS, not behaviour. No dsh packages, no runtime state, and no imports except
+ * types from this package's own sibling modules — so both halves of every plugin
+ * (host route and browser face) can import the same declaration, and a contract
+ * change is a compile error on both sides instead of a silent drift. The browser
+ * faces used to restate these shapes by hand precisely because there was nowhere
+ * shared to put them.
+ *
+ * Sections below were moved verbatim from the packages' own protocol modules,
+ * which now re-export from here; the package-local headers are kept because they
+ * carry the reasoning for each shape.
+ */
+/**
+ * The file navigator's wire vocabulary, shared by the host route and the
+ * browser face.
+ *
+ * Deliberately free of value imports: the browser half imports this module, and
+ * anything it pulls in would be bundled into `client.js`.
+ *
+ * A path on the wire is always the CANONICAL absolute path **in the session's
+ * own execution world** — the host path for a local session, the device path
+ * for a device-bound one. That is the string the client shows, splits into
+ * segments, trims for `..`, and hands back to list again, so both ends agree on
+ * one spelling without either knowing which world produced it.
+ */
+/** The exact `/api` path the file navigator talks to. */
+export const DSHELL_FILES_PATH = '/api/dshell/files';
+// ─── files — the two-world transfer view ───
+// moved from packages/dshell/files/src/transfer-protocol.ts
+/**
+ * The file-transfer wire vocabulary: one device session's two file trees, and
+ * the copies between them.
+ *
+ * Separate from `./protocol.ts` because it is a different route with a
+ * different subject. The navigator's route answers about ONE world (the
+ * session's); this one is about the pair — this machine and the device the
+ * session runs on — and about work that outlives one request.
+ *
+ * Deliberately free of value imports: the browser face imports this module, and
+ * anything it pulled in would be bundled into `client.js`. `Buffer`-style host
+ * types are not needed on the browser side at all.
+ */
+/** The exact `/api` path the transfer view talks to. */
+export const DSHELL_TRANSFER_PATH = '/api/dshell/transfer';
+// ─── buffer — the cross-session pipe: links, tickets, grants, transfers ───
+// moved from packages/dshell/buffer/src/protocol.ts
+/**
+ * The buffer's wire vocabulary, shared by the host route and the browser face.
+ *
+ * Deliberately free of value imports: the browser half imports this module, and
+ * anything it pulls in would be bundled into `client.js`. Identifiers that the
+ * host validates against (a request `action`, a ticket `state`) are plain
+ * strings here and narrowed on the host side.
+ *
+ * Session ids travel as plain strings rather than the branded `SessionId`
+ * because this is a JSON boundary; the host converts at the edges.
+ */
+/** The exact `/api` path the pipe UI talks to. */
+export const DSHELL_BUFFER_PATH = '/api/dshell/buffer';
+/** The plugin name every buffer-authored message carries as its provenance. */
+export const BUFFER_PLUGIN = 'dshell-buffer';
+/** States after which a ticket is settled and never changes again. */
+export const SETTLED_STATES = ['done', 'failed', 'timeout', 'cancelled'];
+// ─── ssh — devices, bindings, their requests/responses ───
+// moved from packages/dshell/ssh/src/protocol.ts
+/**
+ * dshell-ssh wire — one exact `/api/dshell/ssh` route, plus the device shapes
+ * both halves agree on.
+ *
+ * The route carries what must not travel through the settings document: the
+ * private keys themselves. A device's durable record is small JSON; its key is
+ * a separate file written 0600 under `$DSH_HOME/dshell/ssh/keys/`.
+ *
+ * This module is imported by the browser half through the package's
+ * `./protocol` subpath, so it must stay free of value imports: anything it
+ * pulls in would be bundled into the client.
+ */
+/** Exact `/api` route path owned by the SSH device registry. */
+export const DSHELL_SSH_PATH = '/api/dshell/ssh';
+/** Settings namespace owned by this plugin; also the device card's slot key. */
+export const SSH_SETTINGS_NAMESPACE = 'dshell-ssh';
+// ─── workspace — the session archive routes ───
+// moved from packages/dshell/workspace/src/protocol.ts
+/**
+ * dshell session-panel wire — design 4.7 follow-up.
+ *
+ * The sidebar's session rows need two things dsh does not offer: an archive
+ * tag that hides a session without touching its log, and a history purge.
+ * Both are dshell concepts, so they travel over dshell's own exact route on
+ * the shared `/api` channel rather than through the Typert Remote table
+ * (whose client artifacts are generated from dsh's own packages).
+ *
+ * The path sits below the shared channel exactly like file-upload's: the
+ * physical carrier applies dsh's trust and authentication policy before the
+ * handler ever runs, so the route itself does no authorization.
+ *
+ * Shared by both halves of the package, so the constant and the shapes live
+ * in one file that neither the host nor the client bundle owns.
+ */
+/** Exact `/api` route path owned by the dshell session panel. */
+export const DSHELL_SESSIONS_PATH = '/api/dshell/sessions';
+// ─── terminal-bridge — the shell's history read ───
+// moved from packages/dshell/terminal-bridge/src/route.ts
+export const DSHELL_PTY_PATH = '/api/dshell/pty';
+// ─── terminal-bridge — the frame stream over the shared API channel ───
+/**
+ * Downstream half of the frame stream: a long-lived GET whose response body is
+ * newline-delimited JSON, one bridge frame per line.
+ *
+ * The wire itself is unchanged — these are the very frames the ws upgrade
+ * carries — but a Response body is reachable from any composition the
+ * `connection` service is in, while `registerUpgrade` needs `webServer`, which
+ * the desktop shell deliberately does not compose. Identity is explicit because
+ * an HTTP stream has no socket to key on: both halves carry the client's own
+ * `clientId`, and the GET carries the bind (`sessionId` + `stream`) that a ws
+ * would have sent as a frame.
+ */
+export const DSHELL_STREAM_PATH = '/api/dshell/stream';
+/**
+ * Upstream half: one POST per control frame (`input`, `resize`, `signal`,
+ * `agent-open`, `reconnect`), identified by the same `clientId` the GET opened
+ * with. Answers with no body; the stream is the only place results appear.
+ */
+export const DSHELL_STREAM_SEND_PATH = '/api/dshell/stream/send';
+//# sourceMappingURL=contracts.js.map

package/lib/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH;;;;;;;;;;;;GAYG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAA;AA2KpD,8CAA8C;AAC9C,4DAA4D;AAE5D;;;;;;;;;;;;GAYG;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAA;AAsH1D,6EAA6E;AAC7E,oDAAoD;AAEpD;;;;;;;;;;GAUG;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAA;AAEtD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAA;AAW5C,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAiC,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CAAA;AAyLtG,4DAA4D;AAC5D,iDAAiD;AAEjD;;;;;;;;;;;GAWG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAEhD,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAG,YAAY,CAAA;AA6GlD,iDAAiD;AACjD,uDAAuD;AAEvD;;;;;;;;;;;;;;;GAeG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAA;AA0B1D,qDAAqD;AACrD,0DAA0D;AAE1D,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAuChD,yEAAyE;AAEzE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAA;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAA"}

package/lib/host-copy.js

@@ -0,0 +1,25 @@
+/**
+ * The host copy direction: the contract for text a HOST writes that the user
+ * reads.
+ *
+ * Browser faces learn their language from dsh's `ctx.locale`, which the host
+ * cannot see. Host-composed text — route refusals, device errors, the delegated
+ * request a peer's model reads, a command's result line — therefore needs its
+ * own statement of "which language", and it needs it from the browser that is
+ * actually on screen. Two signals stand in for it, in order: what the browser
+ * last reported to {@link DSHELL_LOCALE_PATH} (exact, and it covers a language
+ * the browser picked for itself when the user never chose one), then the durable
+ * `locale.preference` dsh's own Language row writes. With neither, the host
+ * writes the project's source-of-truth language, `zh`.
+ *
+ * The rules here follow this package's layering: declaration only — the shapes
+ * and the path — with no imports, no dsh packages and no runtime state. The
+ * service that RESOLVES the language is provided by `dshell-mode`
+ * (`ctx.dshellHostCopy`), so every package binds its own host dictionaries to it
+ * instead of re-implementing the lookup.
+ */
+/** Where the browser reports the locale it actually resolved. */
+export const DSHELL_LOCALE_PATH = '/api/dshell/locale';
+/** The languages a host message can be written in, in report order. */
+export const HOST_LOCALE_IDS = ['zh', 'en'];
+//# sourceMappingURL=host-copy.js.map

package/lib/host-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-copy.js","sourceRoot":"","sources":["../src/host-copy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAA;AAEtD,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,IAAI,CAAU,CAAA"}

package/lib/index.js

@@ -0,0 +1,21 @@
+/**
+ * dshell's standard layer.
+ *
+ * Everything here is shared machinery that must not belong to any one feature:
+ * the wire contracts ({@link ./contracts.ts}), the host copy direction
+ * ({@link ./host-copy.ts}) that a host half binds its own dictionaries to, the
+ * storage contract ({@link ./storage.ts}) that a feature calls without knowing
+ * its medium, and as the refactor continues, the dsh seam adapters (route
+ * definition, session/world addressing, capability probing) that today live
+ * duplicated inside feature packages.
+ *
+ * The rule that makes this layer worth having: it is the ONLY dshell package
+ * allowed to care about how dsh spells things. A feature package imports from
+ * here and keeps to its own product logic, so a dsh interface change is
+ * absorbed in one place instead of re-implemented per plugin.
+ */
+export * from './contracts.js';
+export * from './host-copy.js';
+export * from './shell-line.js';
+export * from './storage.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/lib/shell-line.js

@@ -0,0 +1,275 @@
+/**
+ * The shell line, tokenized and classified — the rule table behind Tab.
+ *
+ * The composer's completion has to know WHICH position the caret is in before it
+ * can know what to offer, because a position is a property of the LINE, not of
+ * the word: `dock` is a command in `dock`, an argument in `cd dock`, and a file
+ * in `tee > dock`. bash's own grammar is what defines it (the start of a *simple
+ * command*), and that start is introduced by an operator, a keyword, or a prefix
+ * word — never by "it happens to be first".
+ *
+ * This module is that rule table, kept pure: no services, no filesystem, no
+ * process. Both halves of the feature depend on it — the host decides which
+ * source answers, the browser decides when an empty answer is worth showing —
+ * and `packages/dshell/std/tests/shell-line.spec.ts` drives it with real lines.
+ *
+ * Deliberately NOT a shell parser. bash's grammar is unbounded (`eval`, nested
+ * substitutions, heredocs, functions), so this walk answers the shapes it can
+ * PROVE and admits what it cannot: a blank line or an operator under the caret
+ * reports "nothing to complete" rather than guessing, and the caller decides
+ * what no-answer means. There is no "maybe" position — a caller cannot act on
+ * one, and a wrong KIND of candidate (`-launcher.sh` offered for `-la<Tab>`) is
+ * worse than silence.
+ */
+/** Characters that end a word. */
+const BLANKS = new Set([' ', '\t', '\n', '\r']);
+/**
+ * Words after which a simple command begins, so the NEXT word is that command's
+ * name: wrapper commands (`sudo`, `env`, `time`, `xargs`, … — bash's own
+ * bash-completion registers several of these, e.g. `complete -F _comp_command
+ * time xargs nohup`) and the keywords that open a command list.
+ */
+const BEFORE_COMMAND = new Set([
+    'if', 'then', 'else', 'elif', 'while', 'until', 'do', '!', 'time', '{',
+    'sudo', 'doas', 'env', 'nice', 'ionice', 'nohup', 'setsid', 'strace',
+    'command', 'builtin', 'exec', 'xargs', 'watch', 'timeout', 'noglob', 'nocorrect',
+]);
+/**
+ * Keywords that END a command list rather than open one. `in` is here on
+ * purpose: what follows it are words (`for f in a b`), not a command.
+ *
+ * The walk does not need this split — a keyword in the command position is never
+ * the command itself, whatever list it belongs to — so this set only decides
+ * which words are tokens of kind `reserved` rather than plain words.
+ */
+const AFTER_COMMAND = new Set(['fi', 'done', 'esac', '}', 'in', 'case', 'select', 'function', 'for']);
+/** One operator form. Order matters: the longest/dup forms must be tried first. */
+const OPERATORS = [
+    { re: /^&&/u, kind: 'separator', target: false },
+    { re: /^\|\|/u, kind: 'separator', target: false },
+    { re: /^\|&/u, kind: 'separator', target: false },
+    { re: /^;/u, kind: 'separator', target: false },
+    { re: /^\|/u, kind: 'separator', target: false },
+    // A file-descriptor duplication (`2>&1`, `>&2`) names a descriptor, not a
+    // file — it must be matched before the plain redirections below.
+    { re: /^[0-9]*>&[0-9-]+/u, kind: 'redirection', target: false },
+    { re: /^&>>?/u, kind: 'redirection', target: true },
+    { re: /^&/u, kind: 'separator', target: false },
+    { re: /^[0-9]*(?:>>|>\||>\|?|<[<>]?)/u, kind: 'redirection', target: true },
+    { re: /^\$\(/u, kind: 'open', target: false },
+    { re: /^\(/u, kind: 'open', target: false },
+    { re: /^\)/u, kind: 'close', target: false },
+    { re: /^`/u, kind: 'open', target: false },
+];
+/** The operator at `index`, if any. */
+function operatorAt(line, index) {
+    for (const form of OPERATORS) {
+        const matched = form.re.exec(line.slice(index));
+        if (matched !== null)
+            return { kind: form.kind, text: matched[0], target: form.target };
+    }
+    return undefined;
+}
+/** Whether a bare word is an assignment rather than a name. */
+function isAssignment(text) {
+    return /^[A-Za-z_][A-Za-z0-9_]*=/u.test(text);
+}
+/** The kind of a word, from its own shape alone (its position decides the rest). */
+function kindOfWord(text, quoted) {
+    if (!quoted && (text === '{' || text === '}'))
+        return text === '{' ? 'open' : 'close';
+    // An assignment tests the RAW text, not the quoting: what makes `FOO='a b'`
+    // an assignment is its unquoted `name=` head, and the quotes only hide the
+    // value. Quoting the NAME (`'FOO'=a`) makes it an ordinary word, which is
+    // exactly what anchoring the test at offset 0 already gives.
+    if (isAssignment(text))
+        return 'assign';
+    if (quoted)
+        return 'word';
+    if (BEFORE_COMMAND.has(text) || AFTER_COMMAND.has(text))
+        return 'reserved';
+    return 'word';
+}
+/**
+ * Split one line into tokens, stopping at nothing: a completion also runs on a
+ * half-written line, so quotes may be open and the last word may be cut off.
+ *
+ * Quote handling is what a completion needs, not what a shell needs: whitespace
+ * inside quotes does not split, an unterminated quote keeps its token whole (the
+ * reader is still typing it), and the operators that are not separated by spaces
+ * (`a>b`, `x;y`) still split — which the word scanner does by asking
+ * {@link operatorAt} before consuming a character.
+ *
+ * @param line - the line as written.
+ * @returns the tokens in order, with their offsets.
+ */
+export function tokenizeShellLine(line) {
+    const tokens = [];
+    let index = 0;
+    while (index < line.length) {
+        if (BLANKS.has(line[index])) {
+            index += 1;
+            continue;
+        }
+        const operator = operatorAt(line, index);
+        if (operator !== undefined) {
+            tokens.push({
+                kind: operator.kind, text: operator.text, start: index, end: index + operator.text.length,
+                quoted: false, target: operator.target,
+            });
+            index += operator.text.length;
+            continue;
+        }
+        const start = index;
+        let text = '';
+        let quoted = false;
+        while (index < line.length) {
+            const char = line[index];
+            if (BLANKS.has(char))
+                break;
+            if (char === '\\' && index + 1 < line.length) {
+                text += line.slice(index, index + 2);
+                index += 2;
+                continue;
+            }
+            if (char === '\'' || char === '"' || char === '`') {
+                quoted = true;
+                text += char;
+                index += 1;
+                while (index < line.length && line[index] !== char) {
+                    if (char === '"' && line[index] === '\\' && index + 1 < line.length) {
+                        text += line.slice(index, index + 2);
+                        index += 2;
+                        continue;
+                    }
+                    text += line[index];
+                    index += 1;
+                }
+                // An unterminated quote is a word still being written: keep it whole.
+                if (index < line.length) {
+                    text += char;
+                    index += 1;
+                }
+                continue;
+            }
+            if (operatorAt(line, index) !== undefined)
+                break;
+            text += char;
+            index += 1;
+        }
+        if (text.length === 0) {
+            index += 1;
+            continue;
+        }
+        tokens.push({ kind: kindOfWord(text, quoted), text, start, end: index, quoted, target: false });
+    }
+    return tokens;
+}
+/**
+ * Walk the tokens before the caret and report what the line expects there.
+ *
+ * `command` is the command the caret's word belongs to, so it is undefined
+ * wherever the line has not named one YET — which is why every operator, and
+ * every keyword sitting where a command would go, clears it again.
+ *
+ * @param tokens - the line's tokens, in order.
+ * @param index - the token under the caret, or the token count for a word that
+ *   has not been typed yet (an empty token after whitespace).
+ * @returns the position, and the command it belongs to when there is one.
+ */
+export function classifyShellPosition(tokens, index) {
+    let expecting = 'command';
+    let command;
+    for (let at = 0; at < index && at < tokens.length; at += 1) {
+        const token = tokens[at];
+        if (token.kind === 'redirection') {
+            // A duplication (`2>&1`) names no file, so it leaves the expectation
+            // alone; only a real redirection opens the file slot that follows it.
+            expecting = token.target ? 'file' : expecting;
+            continue;
+        }
+        if (token.kind === 'separator' || token.kind === 'open') {
+            expecting = 'command';
+            command = undefined;
+            continue;
+        }
+        if (token.kind === 'close') {
+            expecting = 'argument';
+            continue;
+        }
+        if (token.kind === 'assign')
+            continue;
+        if (token.kind === 'reserved' && expecting === 'command') {
+            // A keyword or a wrapper word in the command position does not become the
+            // command: `if`/`then`/`do` open a list and `fi`/`done` close one (either
+            // way a command follows), while `sudo`/`env`/`time` hand the position on
+            // to the next word. So all of them clear `command` and keep waiting.
+            command = undefined;
+            continue;
+        }
+        if (expecting === 'command') {
+            command = token.text;
+            expecting = 'argument';
+            continue;
+        }
+        if (expecting === 'file')
+            expecting = 'argument';
+    }
+    const caret = tokens[index];
+    // No word under the caret yet: the expectation IS the answer, with the file
+    // slot reported as the `redir` position it always was.
+    if (caret === undefined)
+        return { position: expecting === 'file' ? 'redir' : expecting, command };
+    if (expecting === 'file')
+        return { position: 'redir', command };
+    if (expecting === 'command')
+        return { position: 'command', command };
+    if (caret.kind === 'word' && caret.text.length > 1 && caret.text.startsWith('-')) {
+        return { position: 'flag', command };
+    }
+    return { position: 'argument', command };
+}
+/**
+ * Everything the completion needs to know about one caret: where the word is,
+ * which part of it is the name, and what the line expects there.
+ *
+ * @param line - the line as written (the draft).
+ * @param cursor - the caret offset within it.
+ * @returns the caret reading, or undefined when there is nothing to complete —
+ *   a blank line, or an operator under the caret, which names no word (a
+ *   redirection WITH a target is the exception: `ls >` is a file slot with an
+ *   empty word in it, and the reader reports it as such).
+ */
+export function readShellCaret(line, cursor) {
+    const before = line.slice(0, Math.max(0, Math.min(cursor, line.length)));
+    const tokens = tokenizeShellLine(before);
+    const last = tokens[tokens.length - 1];
+    let index = tokens.length;
+    let start = before.length;
+    let dirPart = '';
+    let prefix = '';
+    let empty = true;
+    if (last !== undefined && last.end === before.length && last.kind === 'redirection' && last.target) {
+        // `ls >` — the operator is complete and the word it names is empty, so the
+        // walk (which now sees that redirection) reports the file slot. bash reads
+        // it the same way: Tab right after `>` lists the directory.
+    }
+    else if (last !== undefined && last.end === before.length) {
+        // An operator under the caret names nothing: there is no word being typed.
+        if (last.kind !== 'word' && last.kind !== 'assign' && last.kind !== 'reserved')
+            return undefined;
+        const slash = last.text.lastIndexOf('/');
+        dirPart = slash < 0 ? '' : last.text.slice(0, slash + 1);
+        prefix = last.text.slice(slash + 1);
+        start = last.start + dirPart.length;
+        index = tokens.length - 1;
+        empty = false;
+    }
+    else if (before.trim().length === 0) {
+        // A blank line completes nothing, which is what a terminal does too.
+        return undefined;
+    }
+    const { position, command } = classifyShellPosition(tokens, index);
+    return { position, command, start, end: before.length, dirPart, prefix, empty };
+}
+//# sourceMappingURL=shell-line.js.map

package/lib/shell-line.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-line.js","sourceRoot":"","sources":["../src/shell-line.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAsEH,kCAAkC;AAClC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG;IACtE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ;IACpE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW;CACjF,CAAC,CAAA;AAEF;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAA;AAErG,mFAAmF;AACnF,MAAM,SAAS,GAAgG;IAC7G,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IAChD,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IAClD,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IACjD,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IAC/C,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IAChD,0EAA0E;IAC1E,iEAAiE;IACjE,EAAE,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE;IAC/D,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE;IACnD,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE;IAC/C,EAAE,EAAE,EAAE,gCAAgC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE;IAC3E,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;IAC7C,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;IAC3C,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE;IAC5C,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;CAC3C,CAAA;AAED,uCAAuC;AACvC,SAAS,UAAU,CAAC,IAAY,EAAE,KAAa;IAC7C,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;QAC/C,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAA;IACzF,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,+DAA+D;AAC/D,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC/C,CAAC;AAED,oFAAoF;AACpF,SAAS,UAAU,CAAC,IAAY,EAAE,MAAe;IAC/C,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAA;IACrF,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,6DAA6D;IAC7D,IAAI,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAA;IACvC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAA;IACzB,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAA;IAC1E,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,MAAM,GAAiB,EAAE,CAAA;IAC/B,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAW,CAAC,EAAE,CAAC;YAAC,KAAK,IAAI,CAAC,CAAC;YAAC,SAAQ;QAAC,CAAC;QAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACxC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM;gBACzF,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM;aACvC,CAAC,CAAA;YACF,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAA;YAC7B,SAAQ;QACV,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAA;QACnB,IAAI,IAAI,GAAG,EAAE,CAAA;QACb,IAAI,MAAM,GAAG,KAAK,CAAA;QAClB,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAW,CAAA;YAClC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,MAAK;YAC3B,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC7C,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;gBACpC,KAAK,IAAI,CAAC,CAAA;gBACV,SAAQ;YACV,CAAC;YACD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBAClD,MAAM,GAAG,IAAI,CAAA;gBACb,IAAI,IAAI,IAAI,CAAA;gBACZ,KAAK,IAAI,CAAC,CAAA;gBACV,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;oBACnD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;wBACpE,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;wBACpC,KAAK,IAAI,CAAC,CAAA;wBACV,SAAQ;oBACV,CAAC;oBACD,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;oBACnB,KAAK,IAAI,CAAC,CAAA;gBACZ,CAAC;gBACD,sEAAsE;gBACtE,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;oBAAC,IAAI,IAAI,IAAI,CAAC;oBAAC,KAAK,IAAI,CAAC,CAAA;gBAAC,CAAC;gBACrD,SAAQ;YACV,CAAC;YACD,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,SAAS;gBAAE,MAAK;YAChD,IAAI,IAAI,IAAI,CAAA;YACZ,KAAK,IAAI,CAAC,CAAA;QACZ,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAAC,KAAK,IAAI,CAAC,CAAC;YAAC,SAAQ;QAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IACjG,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA6B,EAC7B,KAAa;IAEb,IAAI,SAAS,GAAoC,SAAS,CAAA;IAC1D,IAAI,OAA2B,CAAA;IAC/B,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,KAAK,IAAI,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAe,CAAA;QACtC,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACjC,qEAAqE;YACrE,sEAAsE;YACtE,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;YAC7C,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACxD,SAAS,GAAG,SAAS,CAAA;YACrB,OAAO,GAAG,SAAS,CAAA;YACnB,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAAC,SAAS,GAAG,UAAU,CAAC;YAAC,SAAQ;QAAC,CAAC;QAChE,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAQ;QACrC,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YACzD,0EAA0E;YAC1E,0EAA0E;YAC1E,yEAAyE;YACzE,qEAAqE;YACrE,OAAO,GAAG,SAAS,CAAA;YACnB,SAAQ;QACV,CAAC;QACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,GAAG,KAAK,CAAC,IAAI,CAAA;YACpB,SAAS,GAAG,UAAU,CAAA;YACtB,SAAQ;QACV,CAAC;QACD,IAAI,SAAS,KAAK,MAAM;YAAE,SAAS,GAAG,UAAU,CAAA;IAClD,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC3B,4EAA4E;IAC5E,uDAAuD;IACvD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAA;IACjG,IAAI,SAAS,KAAK,MAAM;QAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAA;IAC/D,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,CAAA;IACpE,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACtC,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,CAAA;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAc;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACxE,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACtC,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,CAAA;IACzB,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,CAAA;IACzB,IAAI,OAAO,GAAG,EAAE,CAAA;IAChB,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,IAAI,KAAK,GAAG,IAAI,CAAA;IAChB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACnG,2EAA2E;QAC3E,2EAA2E;QAC3E,4DAA4D;IAC9D,CAAC;SAAM,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5D,2EAA2E;QAC3E,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,SAAS,CAAA;QAChG,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QACxC,OAAO,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;QACxD,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;QACnC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAA;QACnC,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA;QACzB,KAAK,GAAG,KAAK,CAAA;IACf,CAAC;SAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,qEAAqE;QACrE,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,qBAAqB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAClE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AACjF,CAAC"}

package/lib/storage.js

@@ -0,0 +1,41 @@
+/**
+ * The storage contract: what a dshell store *is*, with no medium attached.
+ *
+ * dshell has one durable store for shell history today and a reason to expect
+ * more (agent-facing records that want indexes). The split that keeps that from
+ * becoming each feature's private file format:
+ *
+ *   - **the contract** lives here — the record shape, the store surface, the
+ *     on-disk naming and layout version, and the failure vocabulary;
+ *   - **the medium** lives in `@nexus-aethra/dshell-storage` (`node:sqlite`);
+ *   - **a feature** only calls the store, and never names a file, a pragma or a
+ *     schema.
+ *
+ * Nothing here may import a Node builtin: `std` is inlined into client bundles,
+ * so this file has to stay an isomorphic declaration. The engine is host-only
+ * for exactly that reason — `node:sqlite` cannot cross into a browser bundle.
+ */
+/** File name of the shared database inside a log directory. */
+export const HISTORY_STORE_FILENAME = 'history.sqlite';
+/**
+ * Physical layout version of the history database, stamped in
+ * `PRAGMA user_version`.
+ *
+ * The engine migrates the layouts it knows: 1 dropped `commands_at(at)`, an
+ * index for a cross-session time query that was never built and that nothing
+ * read; 2 added `command_output`, the per-command output the agent-facing read
+ * tool addresses by offset. A database stamped with anything else is rejected:
+ * this code is the only producer, and history is a convenience the user may
+ * lose without losing a session.
+ */
+export const HISTORY_STORE_SCHEMA_VERSION = 3;
+/** A store that cannot be opened, or was written by another layout. */
+export class HistoryStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'HistoryStoreError';
+    }
+}
+//# sourceMappingURL=storage.js.map

package/lib/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,gBAAgB,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAA;AAK7C,uEAAuE;AACvE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACrB;IAArB,YAAqB,IAA2B,EAAE,OAAe;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAA;QADK,SAAI,GAAJ,IAAI,CAAuB;QAE9C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF"}