charness 0.0.0-stage → 3.1.0

package/dist/connectors/test/sessionKeyCodec.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * @description The test double's {@link SessionKeyCodec}.
+ *
+ * It exists so the seam can be exercised with a NON-Telegram platform id —
+ * without one, `keysEqual`'s platform comparison, the registry's
+ * `matches()`-based dispatch and every degraded capability path are unreachable
+ * and would be shipped untested.
+ *
+ * The spelling deliberately contains no `:`, and `|` guarantees the
+ * all-numeric Telegram pattern can never claim one of these strings, and vice
+ * versa. It has no `decodeSlug`: a test key is never read back from a tmux or
+ * directory name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testSessionKeyCodec = void 0;
+exports.registerTestSessionKeyCodec = registerTestSessionKeyCodec;
+exports.makeTestKey = makeTestKey;
+const sessionKey_1 = require("../../sessionKey");
+const testPlatform = 'test';
+const testKeyRe = /^test\|([^|]*)\|([^|]*)$/;
+exports.testSessionKeyCodec = {
+    platform: testPlatform,
+    encode(key) {
+        return `test|${key.space}|${key.thread}`;
+    },
+    decode(serialized) {
+        const match = testKeyRe.exec(serialized);
+        if (!match)
+            throw new Error(`Invalid test SessionKey string: "${serialized}"`);
+        return { platform: testPlatform, space: match[1], thread: match[2] };
+    },
+    matches(serialized) {
+        return testKeyRe.test(serialized);
+    },
+};
+/**
+ * NOT self-registering, unlike the Telegram codec: a test double that armed
+ * itself on import would silently join the production registry through any
+ * transitive import. Tests register it explicitly and
+ * `unregisterSessionKeyCodec('test')` when done.
+ */
+function registerTestSessionKeyCodec() {
+    (0, sessionKey_1.registerSessionKeyCodec)(exports.testSessionKeyCodec);
+}
+/** Build a test {@link SessionKey}. Mirrors `makeTelegramKey`'s role. */
+function makeTestKey(space, thread) {
+    return { platform: testPlatform, space, thread };
+}
+//# sourceMappingURL=sessionKeyCodec.js.map

package/dist/connectors/test/sessionKeyCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionKeyCodec.js","sourceRoot":"","sources":["../../../src/connectors/test/sessionKeyCodec.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAqCH,kEAEC;AAGD,kCAEC;AA1CD,iDAK0B;AAE1B,MAAM,YAAY,GAAe,MAAM,CAAC;AAExC,MAAM,SAAS,GAAG,0BAA0B,CAAC;AAEhC,QAAA,mBAAmB,GAAoB;IAClD,QAAQ,EAAE,YAAY;IAEtB,MAAM,CAAC,GAAe;QACpB,OAAO,QAAQ,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,CAAC,UAAkB;QACvB,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,UAAU,GAAG,CAAC,CAAC;QAC/E,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,CAAC;IAED,OAAO,CAAC,UAAkB;QACxB,OAAO,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,2BAA2B;IACzC,IAAA,oCAAuB,EAAC,2BAAmB,CAAC,CAAC;AAC/C,CAAC;AAED,yEAAyE;AACzE,SAAgB,WAAW,CAAC,KAAa,EAAE,MAAc;IACvD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC"}

package/dist/diagLog.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @description Append one diagnostic line. Never throws — logging must not be
+ * able to take the bot down, so every IO error is swallowed.
+ */
+export declare function appendDiagLog(message: string): void;
+//# sourceMappingURL=diagLog.d.ts.map

package/dist/diagLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagLog.d.ts","sourceRoot":"","sources":["../src/diagLog.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAYnD"}

package/dist/diagLog.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendDiagLog = appendDiagLog;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const state_1 = require("./state");
+/**
+ * @description Bounded, rotating diagnostic log for agent-backend lifecycle
+ * milestones (SSE connect / stall / reconnect, prompt send / accept / fail,
+ * response complete).
+ *
+ * The bot otherwise logs only to its controlling terminal, so a stall that
+ * happens while nobody is watching is undiagnosable after the fact. This
+ * writes ONE line per milestone to a size-capped file under `DATA_DIR`
+ * (per-instance, so pet/work bots stay separate). It deliberately does NOT
+ * receive the per-delta output firehose — the full console stream would
+ * reach gigabytes in days.
+ *
+ * Size bound: once the file passes `maxLogBytes` it rolls to a single `.1`
+ * backup (overwriting the previous backup), so total on-disk size never
+ * exceeds roughly `2 × maxLogBytes`.
+ */
+const maxLogBytes = 512 * 1024;
+const logFilePath = node_path_1.default.join((0, state_1.resolveDataDir)(), 'agent-diag.log');
+/** Ensure the log directory exists exactly once per process (cheap guard so we
+ * don't issue an mkdir syscall on every append). Without this, a milestone that
+ * fires before `DATA_DIR` is created throws and the breadcrumb is lost in the
+ * `catch` — exactly when a fresh/misconfigured instance needs it most. */
+let isLogDirEnsured = false;
+function rotateIfOversized() {
+    if (!(0, node_fs_1.existsSync)(logFilePath))
+        return;
+    if ((0, node_fs_1.statSync)(logFilePath).size <= maxLogBytes)
+        return;
+    (0, node_fs_1.renameSync)(logFilePath, `${logFilePath}.1`);
+}
+/**
+ * @description Append one diagnostic line. Never throws — logging must not be
+ * able to take the bot down, so every IO error is swallowed.
+ */
+function appendDiagLog(message) {
+    try {
+        if (!isLogDirEnsured) {
+            (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(logFilePath), { recursive: true, mode: 0o700 });
+            isLogDirEnsured = true;
+        }
+        rotateIfOversized();
+        // Owner-only file (mode applies at creation) — diag lines may quote agent errors.
+        (0, node_fs_1.appendFileSync)(logFilePath, `${new Date().toISOString()} ${message}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Diagnostics are best-effort; a logging failure must never break the bot.
+    }
+}
+//# sourceMappingURL=diagLog.js.map

package/dist/diagLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagLog.js","sourceRoot":"","sources":["../src/diagLog.ts"],"names":[],"mappings":";;;;;AAwCA,sCAYC;AApDD,qCAAsF;AACtF,0DAA6B;AAC7B,mCAAyC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC;AAE/B,MAAM,WAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAA,sBAAc,GAAE,EAAE,gBAAgB,CAAC,CAAC;AAElE;;;0EAG0E;AAC1E,IAAI,eAAe,GAAG,KAAK,CAAC;AAE5B,SAAS,iBAAiB;IACxB,IAAI,CAAC,IAAA,oBAAU,EAAC,WAAW,CAAC;QAAE,OAAO;IACrC,IAAI,IAAA,kBAAQ,EAAC,WAAW,CAAC,CAAC,IAAI,IAAI,WAAW;QAAE,OAAO;IACtD,IAAA,oBAAU,EAAC,WAAW,EAAE,GAAG,WAAW,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,OAAe;IAC3C,IAAI,CAAC;QACH,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAA,mBAAS,EAAC,mBAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACvE,eAAe,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,iBAAiB,EAAE,CAAC;QACpB,kFAAkF;QAClF,IAAA,wBAAc,EAAC,WAAW,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;IAC7E,CAAC;AACH,CAAC"}

package/dist/effortLevels.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @description Reasoning-effort level catalogs and per-backend helpers.
+ *
+ * The bot's `/effort` command and both adapters share this module so the
+ * level vocabularies stay in one place and stay easy to unit-test.
+ *
+ * **Two vocabularies, on purpose.**
+ *
+ * - **Claude** has a native `/effort` slash command with a small fixed set
+ *   (`low medium high xhigh max auto ultracode`). claude itself clamps an
+ *   unsupported level for the current model down to the nearest supported
+ *   one, so the bot offers the canonical set unconditionally — the adapter
+ *   has no way to read claude's live model.
+ * - **OpenCode** encodes reasoning effort as the `variants` map on a model
+ *   in `provider.models.<m>.variants` (e.g. anthropic ships `high`/`max`,
+ *   openai ships `none…xhigh`). The legal set therefore depends on which
+ *   model the thread is currently using and cannot be hard-coded — the
+ *   OpenCode adapter reads it live from `GET /config/providers` and applies
+ *   the chosen variant per-prompt. See `openCodeAdapter.ts`.
+ */
+/**
+ * @description Claude `/effort` slash-command levels, in the order they're
+ * shown to the user. Verified against `claude 2.1.158`.
+ *
+ * `auto` resets back to claude's per-model default; `ultracode` is a heavy
+ * coding-focused profile. Both are valid arguments to the TUI slash command.
+ */
+export declare const claudeEffortLevels: readonly ["low", "medium", "high", "xhigh", "max", "auto", "ultracode"];
+export type ClaudeEffortLevel = (typeof claudeEffortLevels)[number];
+/**
+ * @description The bot's default reasoning effort, auto-applied to a
+ * bot-started session whenever the thread has NO explicit per-thread
+ * `/effort` pref. An explicit pick always wins and is never overwritten;
+ * the default is a derived fallback, never persisted as a pref.
+ *
+ * The only real levels are `low`/`medium`/`high`/`xhigh`/`max` (there is no
+ * `xlarge`). OpenCode clamps this to the resolved model's variants via
+ * {@link clampEffortToAvailable}; Claude clamps unsupported levels itself.
+ */
+export declare const defaultEffortLevel: ClaudeEffortLevel;
+/**
+ * @description Clamp a desired effort level to what a model actually offers.
+ *
+ * OpenCode effort is a model VARIANT and not every model ships `xhigh`
+ * (e.g. opus-4-5 / sonnet-4-6 stop at high/max); sending an unknown variant
+ * 400s. This picks the best legal variant:
+ *
+ * - keep only `available` entries we know how to rank ("known"); none known
+ *   → return null (the model has no usable effort concept).
+ * - if `desired` is itself available → return it.
+ * - else return the highest known variant with rank ≤ rank(desired); if none
+ *   are below, return the lowest known variant (closest above).
+ *
+ * Claude clamps itself, so it never calls this.
+ */
+export declare function clampEffortToAvailable(desired: string, available: readonly string[]): string | null;
+/**
+ * @description Canonical Claude effort levels. Returns a fresh mutable copy
+ * so callers can safely sort/filter without mutating the frozen
+ * module-level constant.
+ */
+export declare function getClaudeAvailableLevels(): string[];
+/**
+ * @description Whether `level` is a Claude effort level the TUI accepts.
+ * Used by `/effort <bad>` rejection before we type anything into the pane.
+ */
+export declare function checkIsClaudeEffortLevel(level: string): level is ClaudeEffortLevel;
+//# sourceMappingURL=effortLevels.d.ts.map

package/dist/effortLevels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortLevels.d.ts","sourceRoot":"","sources":["../src/effortLevels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,yEAQrB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAA2B,CAAC;AAQ7D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,GAAG,IAAI,CA0Bf;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAEnD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAElF"}

package/dist/effortLevels.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * @description Reasoning-effort level catalogs and per-backend helpers.
+ *
+ * The bot's `/effort` command and both adapters share this module so the
+ * level vocabularies stay in one place and stay easy to unit-test.
+ *
+ * **Two vocabularies, on purpose.**
+ *
+ * - **Claude** has a native `/effort` slash command with a small fixed set
+ *   (`low medium high xhigh max auto ultracode`). claude itself clamps an
+ *   unsupported level for the current model down to the nearest supported
+ *   one, so the bot offers the canonical set unconditionally — the adapter
+ *   has no way to read claude's live model.
+ * - **OpenCode** encodes reasoning effort as the `variants` map on a model
+ *   in `provider.models.<m>.variants` (e.g. anthropic ships `high`/`max`,
+ *   openai ships `none…xhigh`). The legal set therefore depends on which
+ *   model the thread is currently using and cannot be hard-coded — the
+ *   OpenCode adapter reads it live from `GET /config/providers` and applies
+ *   the chosen variant per-prompt. See `openCodeAdapter.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultEffortLevel = exports.claudeEffortLevels = void 0;
+exports.clampEffortToAvailable = clampEffortToAvailable;
+exports.getClaudeAvailableLevels = getClaudeAvailableLevels;
+exports.checkIsClaudeEffortLevel = checkIsClaudeEffortLevel;
+// ── Claude (canonical set) ──────────────────────────────────────────────────
+/**
+ * @description Claude `/effort` slash-command levels, in the order they're
+ * shown to the user. Verified against `claude 2.1.158`.
+ *
+ * `auto` resets back to claude's per-model default; `ultracode` is a heavy
+ * coding-focused profile. Both are valid arguments to the TUI slash command.
+ */
+exports.claudeEffortLevels = [
+    'low',
+    'medium',
+    'high',
+    'xhigh',
+    'max',
+    'auto',
+    'ultracode',
+];
+/**
+ * @description The bot's default reasoning effort, auto-applied to a
+ * bot-started session whenever the thread has NO explicit per-thread
+ * `/effort` pref. An explicit pick always wins and is never overwritten;
+ * the default is a derived fallback, never persisted as a pref.
+ *
+ * The only real levels are `low`/`medium`/`high`/`xhigh`/`max` (there is no
+ * `xlarge`). OpenCode clamps this to the resolved model's variants via
+ * {@link clampEffortToAvailable}; Claude clamps unsupported levels itself.
+ */
+exports.defaultEffortLevel = 'xhigh';
+/**
+ * @description Internal rank order shared by {@link clampEffortToAvailable}.
+ * Spans both vocabularies (`none` is OpenCode-only) low→high.
+ */
+const effortRankOrder = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+/**
+ * @description Clamp a desired effort level to what a model actually offers.
+ *
+ * OpenCode effort is a model VARIANT and not every model ships `xhigh`
+ * (e.g. opus-4-5 / sonnet-4-6 stop at high/max); sending an unknown variant
+ * 400s. This picks the best legal variant:
+ *
+ * - keep only `available` entries we know how to rank ("known"); none known
+ *   → return null (the model has no usable effort concept).
+ * - if `desired` is itself available → return it.
+ * - else return the highest known variant with rank ≤ rank(desired); if none
+ *   are below, return the lowest known variant (closest above).
+ *
+ * Claude clamps itself, so it never calls this.
+ */
+function clampEffortToAvailable(desired, available) {
+    const known = available.filter((level) => effortRankOrder.includes(level));
+    if (known.length === 0)
+        return null;
+    if (known.includes(desired))
+        return desired;
+    // Rank lookup widens the typed tuple to readonly string[] (the sanctioned
+    // typed-array cast) rather than narrowing the argument; -1 for non-members.
+    const rankOf = (level) => effortRankOrder.indexOf(level);
+    const desiredRank = rankOf(desired);
+    let bestBelow = null;
+    let lowestKnown = null;
+    for (const level of known) {
+        if (lowestKnown === null || rankOf(level) < rankOf(lowestKnown)) {
+            lowestKnown = level;
+        }
+        if (rankOf(level) <= desiredRank) {
+            if (bestBelow === null || rankOf(level) > rankOf(bestBelow)) {
+                bestBelow = level;
+            }
+        }
+    }
+    return bestBelow ?? lowestKnown;
+}
+/**
+ * @description Canonical Claude effort levels. Returns a fresh mutable copy
+ * so callers can safely sort/filter without mutating the frozen
+ * module-level constant.
+ */
+function getClaudeAvailableLevels() {
+    return [...exports.claudeEffortLevels];
+}
+/**
+ * @description Whether `level` is a Claude effort level the TUI accepts.
+ * Used by `/effort <bad>` rejection before we type anything into the pane.
+ */
+function checkIsClaudeEffortLevel(level) {
+    return exports.claudeEffortLevels.includes(level);
+}
+//# sourceMappingURL=effortLevels.js.map

package/dist/effortLevels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortLevels.js","sourceRoot":"","sources":["../src/effortLevels.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAwDH,wDA6BC;AAOD,4DAEC;AAMD,4DAEC;AApGD,+EAA+E;AAE/E;;;;;;GAMG;AACU,QAAA,kBAAkB,GAAG;IAChC,KAAK;IACL,QAAQ;IACR,MAAM;IACN,OAAO;IACP,KAAK;IACL,MAAM;IACN,WAAW;CACH,CAAC;AAIX;;;;;;;;;GASG;AACU,QAAA,kBAAkB,GAAsB,OAAO,CAAC;AAE7D;;;GAGG;AACH,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAEnF;;;;;;;;;;;;;;GAcG;AACH,SAAgB,sBAAsB,CACpC,OAAe,EACf,SAA4B;IAE5B,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CACtC,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,CACvD,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAE5C,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,MAAM,GAAG,CAAC,KAAa,EAAU,EAAE,CACtC,eAAqC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAEpC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,WAAW,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;YAChE,WAAW,GAAG,KAAK,CAAC;QACtB,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;YACjC,IAAI,SAAS,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5D,SAAS,GAAG,KAAK,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,IAAI,WAAW,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,SAAgB,wBAAwB;IACtC,OAAO,CAAC,GAAG,0BAAkB,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,KAAa;IACpD,OAAQ,0BAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC"}

package/dist/folderName.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @description Pure validation for a user-supplied NEW folder name typed
+ * into the `/bind` create-folder flow.
+ *
+ * This is deliberately distinct from `validateSubdir` in `validation.ts`:
+ * that helper resolves an EXISTING path via `realpathSync` and throws
+ * `BIND_NOT_FOUND` for anything not yet on disk. Here the folder does not
+ * exist yet — we only check the name is safe to `mkdir` directly under
+ * `WORK_ROOT` (no traversal, no nesting, no control chars). After the
+ * directory is created the caller routes through `applyBinding`, which
+ * re-validates the now-existing folder with the full path-traversal /
+ * symlink-out defence — so this check is the FIRST gate, not the only one.
+ *
+ * Rejected up front:
+ *  - empty / whitespace-only
+ *  - any path separator (`/` or `\`) — a new folder is a single immediate
+ *    child of WORK_ROOT, not a nested path
+ *  - `.` / `..` — current/parent dir references
+ *  - leading `.` — hidden folders are filtered out of the picker anyway and
+ *    are almost never an intended project root
+ *  - control chars / NUL — explode in tmux send-keys / opencode URLs
+ */
+/** Outcome of validating a typed new-folder name before `mkdir`. */
+export type NewFolderNameResult = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    reason: NewFolderNameError;
+};
+/**
+ * @name NewFolderNameError
+ * @description Why a typed new-folder name was rejected, so the bot can map
+ * each case to a localised reply without pattern-matching strings.
+ */
+export type NewFolderNameError = 'empty' | 'separator' | 'dot_segment' | 'hidden' | 'invalid_chars';
+/**
+ * @description Validate a name typed for a brand-new folder to create under
+ * WORK_ROOT. Returns the NFC-normalised, trimmed name on success.
+ */
+export declare function validateNewFolderName(rawName: string): NewFolderNameResult;
+//# sourceMappingURL=folderName.d.ts.map

package/dist/folderName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folderName.d.ts","sourceRoot":"","sources":["../src/folderName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,WAAW,GACX,aAAa,GACb,QAAQ,GACR,eAAe,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAqB1E"}

package/dist/folderName.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * @description Pure validation for a user-supplied NEW folder name typed
+ * into the `/bind` create-folder flow.
+ *
+ * This is deliberately distinct from `validateSubdir` in `validation.ts`:
+ * that helper resolves an EXISTING path via `realpathSync` and throws
+ * `BIND_NOT_FOUND` for anything not yet on disk. Here the folder does not
+ * exist yet — we only check the name is safe to `mkdir` directly under
+ * `WORK_ROOT` (no traversal, no nesting, no control chars). After the
+ * directory is created the caller routes through `applyBinding`, which
+ * re-validates the now-existing folder with the full path-traversal /
+ * symlink-out defence — so this check is the FIRST gate, not the only one.
+ *
+ * Rejected up front:
+ *  - empty / whitespace-only
+ *  - any path separator (`/` or `\`) — a new folder is a single immediate
+ *    child of WORK_ROOT, not a nested path
+ *  - `.` / `..` — current/parent dir references
+ *  - leading `.` — hidden folders are filtered out of the picker anyway and
+ *    are almost never an intended project root
+ *  - control chars / NUL — explode in tmux send-keys / opencode URLs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateNewFolderName = validateNewFolderName;
+/**
+ * @description Validate a name typed for a brand-new folder to create under
+ * WORK_ROOT. Returns the NFC-normalised, trimmed name on success.
+ */
+function validateNewFolderName(rawName) {
+    // Control chars and NUL bytes can be stored on disk but break shell-quoted
+    // paths downstream (tmux send-keys, opencode HTTP URLs).
+    if (/[\x00-\x1f]/.test(rawName)) {
+        return { ok: false, reason: 'invalid_chars' };
+    }
+    const name = rawName.normalize('NFC').trim();
+    if (!name) {
+        return { ok: false, reason: 'empty' };
+    }
+    if (name.includes('/') || name.includes('\\')) {
+        return { ok: false, reason: 'separator' };
+    }
+    if (name === '.' || name === '..') {
+        return { ok: false, reason: 'dot_segment' };
+    }
+    if (name.startsWith('.')) {
+        return { ok: false, reason: 'hidden' };
+    }
+    return { ok: true, name };
+}
+//# sourceMappingURL=folderName.js.map

package/dist/folderName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folderName.js","sourceRoot":"","sources":["../src/folderName.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AAuBH,sDAqBC;AAzBD;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,OAAe;IACnD,2EAA2E;IAC3E,yDAAyD;IACzD,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACxC,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC"}

package/dist/i18n/de.d.ts

@@ -0,0 +1,2 @@
+export declare const deDict: Record<string, string>;
+//# sourceMappingURL=de.d.ts.map

package/dist/i18n/de.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"de.d.ts","sourceRoot":"","sources":["../../src/i18n/de.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkwBzC,CAAC"}