charness 0.0.0-stage → 3.0.0

package/dist/cli/connectorGuards.js

@@ -0,0 +1,159 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPreloadGuardErrors = getPreloadGuardErrors;
+exports.getConnectorGuardErrors = getConnectorGuardErrors;
+exports.loadEnvWithConnectorGuards = loadEnvWithConnectorGuards;
+const fs = __importStar(require("fs"));
+const connectorSet_1 = require("../platform/connectorSet");
+const configFile_1 = require("../connectors/jira/configFile");
+const state_1 = require("../state");
+const envLoader_1 = require("./envLoader");
+/**
+ * @description The fail-closed guards that stop a start before it can touch
+ * anything (Jira connector plan J3: D6, D7, D8); which connectors an instance
+ * serves is `platform/connectorSet.ts`. They run in the CLI preflight — before
+ * the console tee, the lock and the bot module — for the plain and the hot
+ * start alike.
+ *
+ * What they make impossible for an instance that serves Jira:
+ *  - using a Telegram bot token it inherited (a live bot's): with the Telegram
+ *    connector off a present `TELEGRAM_BOT_TOKEN` is fatal;
+ *  - reading the shared config files that hold such tokens: its settings come
+ *    from `ENV_FILE` only, required before any file is read;
+ *  - touching the default tmux server, where another bot's sessions live (its
+ *    boot kills every session it does not own): `TMUX_SOCKET_NAME` is required
+ *    and may not name the default server;
+ *  - acting under the operator's Atlassian identity: a Jira-only instance
+ *    refuses any `ATLASSIAN_*` variable in its environment (its own Jira
+ *    settings use other names).
+ */
+/** `tmux -L default` IS the default server. */
+const defaultTmuxSocketName = 'default';
+/** A socket NAME, never a path: `-L` puts it in tmux's own socket directory. */
+const tmuxSocketNameRe = /^[A-Za-z0-9_-]+$/;
+const atlassianEnvPrefix = 'ATLASSIAN_';
+/**
+ * The oldest Node the Jira connector runs on (R20): it loads an ES-module-only
+ * package through `require()`, unflagged from 22.12 — earlier, its first answer
+ * would crash the instance instead of refusing the start.
+ */
+const jiraMinimumNodeVersion = [22, 12];
+/** Is `version` (`process.versions.node`, e.g. `22.11.0`) older than `minimum`? */
+function checkIsNodeVersionBelow(version, minimum) {
+    const [major = 0, minor = 0] = version.split('.').map((part) => Number.parseInt(part, 10));
+    return major < minimum[0] || (major === minimum[0] && minor < minimum[1]);
+}
+const envFileRequiredError = 'CONNECTORS lists jira: set ENV_FILE to the instance\'s own env file (it is the only file read)';
+/**
+ * @description The guard that must hold BEFORE any env file is read: an instance
+ * the shell already marks as serving Jira reads its settings from `ENV_FILE`
+ * only, so the shared config files (which hold a live bot's token) are never
+ * opened. A `CONNECTORS` the shell sets but that does not parse is refused here
+ * too: it cannot tell whether the instance was meant to serve Jira.
+ */
+function getPreloadGuardErrors(env) {
+    const parsed = (0, connectorSet_1.parseConnectors)(env.CONNECTORS);
+    if (!parsed.ok)
+        return [parsed.error];
+    if (!parsed.connectors.includes('jira') || env.ENV_FILE)
+        return [];
+    return [envFileRequiredError];
+}
+/**
+ * @description The guards on the loaded environment. Names only — never a value.
+ * `envFileAtLaunch` is `ENV_FILE` as it was BEFORE the load: only that value
+ * says the instance read nothing but its own file, since a shared config file
+ * may itself define `ENV_FILE`.
+ */
+function getConnectorGuardErrors(input) {
+    const { env } = input;
+    const parsed = (0, connectorSet_1.parseConnectors)(env.CONNECTORS);
+    if (!parsed.ok)
+        return [parsed.error];
+    const isTelegramServed = parsed.connectors.includes('telegram');
+    const isJiraServed = parsed.connectors.includes('jira');
+    const errors = [];
+    if (!isTelegramServed && env.TELEGRAM_BOT_TOKEN) {
+        errors.push('TELEGRAM_BOT_TOKEN is set but the telegram connector is off: refusing a bot token this instance must not use');
+    }
+    if (env.ENV_FILE !== input.envFileAtLaunch) {
+        // The env load already happened from other files; in hot mode the worker would then read a different one.
+        errors.push('ENV_FILE is set inside an env file: it may only come from the launching environment');
+    }
+    else if (isJiraServed && !input.envFileAtLaunch) {
+        errors.push(envFileRequiredError);
+    }
+    if (isJiraServed && checkIsNodeVersionBelow(input.nodeVersion, jiraMinimumNodeVersion)) {
+        errors.push(`CONNECTORS lists jira: Node ${input.nodeVersion} is too old — the Jira connector needs Node ${jiraMinimumNodeVersion.join('.')} or newer`);
+    }
+    if (isJiraServed && !input.hasJiraConfig) {
+        errors.push(`CONNECTORS lists jira but DATA_DIR has no ${configFile_1.jiraConfigFileName}`);
+    }
+    const tmuxSocketName = env.TMUX_SOCKET_NAME;
+    if (tmuxSocketName !== undefined && (!tmuxSocketNameRe.test(tmuxSocketName) || tmuxSocketName === defaultTmuxSocketName)) {
+        errors.push(`TMUX_SOCKET_NAME must be a plain name other than "${defaultTmuxSocketName}" (letters, digits, "_", "-")`);
+    }
+    else if (isJiraServed && !tmuxSocketName) {
+        errors.push('CONNECTORS lists jira: set TMUX_SOCKET_NAME — this instance must not use the default tmux server');
+    }
+    if (isJiraServed && !isTelegramServed) {
+        const atlassianNames = Object.keys(env).filter((name) => name.startsWith(atlassianEnvPrefix)).sort();
+        if (atlassianNames.length > 0) {
+            errors.push(`a Jira-only instance refuses Atlassian variables in its environment: ${atlassianNames.join(', ')}`);
+        }
+    }
+    return errors;
+}
+function exitOnGuardErrors(errors) {
+    if (errors.length === 0)
+        return;
+    for (const error of errors)
+        process.stderr.write(`[startup] ${error}\n`);
+    process.exit(1);
+}
+/**
+ * @description Load the env files between the two guard passes — the ONE way the
+ * CLI starts (plain and hot), so no start skips a guard. Exits 1 on a breach.
+ */
+function loadEnvWithConnectorGuards(localDirectory) {
+    exitOnGuardErrors(getPreloadGuardErrors(process.env));
+    const envFileAtLaunch = process.env.ENV_FILE;
+    const result = (0, envLoader_1.loadEnvFiles)(localDirectory);
+    const hasJiraConfig = fs.existsSync((0, configFile_1.getJiraConfigPath)((0, state_1.resolveDataDir)()));
+    exitOnGuardErrors(getConnectorGuardErrors({ env: process.env, hasJiraConfig, envFileAtLaunch, nodeVersion: process.versions.node }));
+    return result;
+}
+//# sourceMappingURL=connectorGuards.js.map

package/dist/cli/connectorGuards.js.map

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

package/dist/cli/envLoader.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @description Path to the per-user global config file.
+ *
+ * Prefers the canonical `~/.config/telegramcode/.env`; falls back to the
+ * legacy `~/.config/telegram-code/.env` when only that one exists. When
+ * neither exists the canonical path is returned, so callers report the
+ * location a fresh install should use.
+ *
+ * Resolved lazily per call — tests may swap `HOME` between cases.
+ */
+export declare function globalEnvPath(): string;
+/** @description Path to the local `.env` for a supplied directory (defaults to `$PWD`). */
+export declare function localEnvPath(localDirectory?: string): string;
+/**
+ * @description Load environment from the wrapper's two well-known locations.
+ *
+ * Order is **global first, local second** so that `dotenv.config({ override: true })`
+ * on the local file gives `<localDirectory>/.env` last-write-wins semantics over
+ * the global. Both files are optional; if neither exists this is a no-op. The
+ * explicit directory lets a supervisor load its worker's project config without
+ * changing the operator-facing process cwd.
+ *
+ * The first load uses `override: false` so that variables already in
+ * `process.env` (set by the user's shell, systemd, etc.) win against the
+ * global file — matching how `dotenv/config` behaves today. The local file
+ * then forces an override only for keys it explicitly sets.
+ *
+ * Returns the list of paths actually read, in load order. Useful for the
+ * `telegramcode` startup banner and for test assertions.
+ */
+export declare function loadEnvFiles(localDirectory?: string): {
+    loaded: string[];
+};
+//# sourceMappingURL=envLoader.d.ts.map

package/dist/cli/envLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envLoader.d.ts","sourceRoot":"","sources":["../../src/cli/envLoader.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAMtC;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,cAAc,SAAgB,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,cAAc,SAAgB,GAAG;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAuCjF"}

package/dist/cli/envLoader.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalEnvPath = globalEnvPath;
+exports.localEnvPath = localEnvPath;
+exports.loadEnvFiles = loadEnvFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const dotenv = __importStar(require("dotenv"));
+const agentEnvironment_1 = require("../utils/agentEnvironment");
+/** Canonical per-user config dir name under `~/.config` (post-rename). */
+const configDirName = 'telegramcode';
+/**
+ * Pre-rename config dir name — still honoured as a fallback so installs
+ * that predate the `telegramcode` rename keep working without moving files.
+ */
+const legacyConfigDirName = 'telegram-code';
+function buildGlobalEnvPath(dirName) {
+    return path.join(os.homedir(), '.config', dirName, '.env');
+}
+/**
+ * @description Path to the per-user global config file.
+ *
+ * Prefers the canonical `~/.config/telegramcode/.env`; falls back to the
+ * legacy `~/.config/telegram-code/.env` when only that one exists. When
+ * neither exists the canonical path is returned, so callers report the
+ * location a fresh install should use.
+ *
+ * Resolved lazily per call — tests may swap `HOME` between cases.
+ */
+function globalEnvPath() {
+    const canonicalPath = buildGlobalEnvPath(configDirName);
+    if (fs.existsSync(canonicalPath))
+        return canonicalPath;
+    const legacyPath = buildGlobalEnvPath(legacyConfigDirName);
+    if (fs.existsSync(legacyPath))
+        return legacyPath;
+    return canonicalPath;
+}
+/** @description Path to the local `.env` for a supplied directory (defaults to `$PWD`). */
+function localEnvPath(localDirectory = process.cwd()) {
+    return path.join(localDirectory, '.env');
+}
+/**
+ * @description Load environment from the wrapper's two well-known locations.
+ *
+ * Order is **global first, local second** so that `dotenv.config({ override: true })`
+ * on the local file gives `<localDirectory>/.env` last-write-wins semantics over
+ * the global. Both files are optional; if neither exists this is a no-op. The
+ * explicit directory lets a supervisor load its worker's project config without
+ * changing the operator-facing process cwd.
+ *
+ * The first load uses `override: false` so that variables already in
+ * `process.env` (set by the user's shell, systemd, etc.) win against the
+ * global file — matching how `dotenv/config` behaves today. The local file
+ * then forces an override only for keys it explicitly sets.
+ *
+ * Returns the list of paths actually read, in load order. Useful for the
+ * `telegramcode` startup banner and for test assertions.
+ */
+function loadEnvFiles(localDirectory = process.cwd()) {
+    // An isolated instance (Jira connector plan J3, D7): ONLY its own file — no
+    // global config, no legacy config, no `$PWD/.env`, which may hold another
+    // bot's token. It wins over the inherited environment.
+    const envFile = process.env.ENV_FILE;
+    if (envFile !== undefined) {
+        if (!path.isAbsolute(envFile))
+            throw new Error(`ENV_FILE must be an absolute path (got "${envFile}")`);
+        if (!fs.existsSync(envFile))
+            throw new Error(`ENV_FILE does not exist: ${envFile}`);
+        if (!fs.statSync(envFile).isFile())
+            throw new Error(`ENV_FILE is not a regular file: ${envFile}`);
+        // dotenv REPORTS a read failure instead of throwing; ignoring it would start
+        // the instance on the inherited environment with nothing loaded.
+        const { error, parsed } = dotenv.config({ path: envFile, override: true });
+        if (error)
+            throw new Error(`ENV_FILE could not be read: ${envFile} (${error.message})`);
+        // R32: what the instance file set never reaches a tracker conversation's agent.
+        (0, agentEnvironment_1.addEnvFileVariableNames)(Object.keys(parsed ?? {}));
+        return { loaded: [envFile] };
+    }
+    const loaded = [];
+    const globalPath = globalEnvPath();
+    if (fs.existsSync(globalPath)) {
+        dotenv.config({ path: globalPath, override: false });
+        loaded.push(globalPath);
+        if (globalPath === buildGlobalEnvPath(legacyConfigDirName)) {
+            process.stderr.write(`Using legacy config ${globalPath} — preferred location: ` +
+                `~/.config/${configDirName}/.env\n`);
+        }
+    }
+    const localPath = localEnvPath(localDirectory);
+    if (fs.existsSync(localPath)) {
+        dotenv.config({ path: localPath, override: true });
+        loaded.push(localPath);
+    }
+    return { loaded };
+}
+//# sourceMappingURL=envLoader.js.map

package/dist/cli/envLoader.js.map

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

package/dist/cli/hot.d.ts

@@ -0,0 +1,82 @@
+interface HotOpenCodeDeps {
+    checkIsInstalled: (toolName: string) => boolean;
+    ensureOpenCodeServer: () => Promise<void>;
+    stopOpenCodeServer: () => void;
+    writeWarning: (message: string) => void;
+}
+type HotChildName = 'tsc' | 'nodemon';
+/**
+ * @description Wrapper-entry for `telegramcode hot` — hot-reload mode for
+ * the global terminal bin.
+ *
+ * **What it does:** starts `tsc -w` from the project root, then starts
+ * `nodemon` only after the watcher's first completed compile. Editing any
+ * `src/**` file rebuilds `dist/` and nodemon restarts the internal
+ * `dist/cli/botEntry.js` worker on the new artifact. The bot's own
+ * graceful-shutdown sequence (state flush → lock release → exit) makes the
+ * old → new handoff clean enough that mid-work agent sessions are re-attached
+ * on the next boot. OpenCode is pre-started by this long-lived supervisor;
+ * later generations use a one-shot external host, so none remain inside
+ * nodemon's worker subtree and in-flight turns survive reloads.
+ *
+ * **Why it lives in the bin** (not only as `yarn hot`): the user runs
+ * `telegramcode` as a globally-installed `npm link` symlink, so they don't
+ * have a yarn project in front of them. Exposing hot reload as a
+ * subcommand makes the same workflow reachable from any CWD — we just
+ * resolve the project root from the bin's own realpath. `yarn hot` in the
+ * repo is the in-project equivalent.
+ *
+ * **Failure modes handled:**
+ *   - fresh checkout → nodemon waits until `tsc -w` produces the worker entry;
+ *   - broken intermediate TS edit → `tsc -w` doesn't emit, so nodemon
+ *     never sees a new artifact and the running bot keeps serving;
+ *   - bot crash at runtime (e.g. a second poller appears and Telegram
+ *     answers 409) → nodemon's `exitcrash` exits instead of parking on
+ *     "app crashed - waiting for file changes", so this wrapper tears
+ *     down and the supervisor (systemd) starts a clean generation.
+ *     Without it the wrapper stays alive with no bot under it, and the
+ *     service looks `active (running)` while the bot is dead;
+ *   - wrapper termination → tsc receives the original signal, while nodemon
+ *     receives its graceful `SIGINT`; we wait for both before exiting.
+ *
+ * `yarn hot` reaches this same wrapper. It spawns directly so the installed
+ * bin doesn't need any devDep but `nodemon` + `typescript`
+ * (always present in this project because the consumer of the bin IS this
+ * project — `npm link` exposes the same `node_modules/.bin`).
+ */
+export declare function runHot(): Promise<void>;
+/**
+ * @description Select the signal used to stop each hot-mode watcher. Nodemon's
+ * SIGTERM handler can terminate its shell before the asynchronous process-tree
+ * sweep reaches the bot worker, leaving that worker alive with the instance
+ * lock. SIGINT follows nodemon's graceful quit path and waits for the tree.
+ */
+export declare function getHotChildShutdownSignal(childName: HotChildName, wrapperSignal: NodeJS.Signals): NodeJS.Signals;
+/** Return a failing wrapper code whenever a watcher stops on its own. */
+export declare function getUnexpectedHotChildExitCode(code: number | null): number;
+export declare function checkIsHotModeSupported(platform: typeof process.platform): boolean;
+export declare function checkIsTscWatchReady(text: string): boolean;
+/**
+ * @description Pre-start OpenCode in the long-lived hot supervisor, outside
+ * nodemon's worker subtree. A missing binary or failed start stays non-fatal:
+ * hot mode must still serve Claude/terminal and the worker can retry OpenCode
+ * through the externally hosted startup path.
+ */
+export declare function prepareHotOpenCodeServer(deps?: HotOpenCodeDeps): Promise<boolean>;
+/**
+ * @description Build the env handed to the hot-mode worker (nodemon → bot).
+ *
+ * In hot mode the supervisor runs `nodemon` with cwd = projectRoot (it must,
+ * to watch `dist/`), and the worker (`node dist/cli/botEntry.js`) inherits that
+ * cwd. Left alone the worker would default `WORK_ROOT` to `process.cwd()` =
+ * the project checkout, so `/bind` would list folders inside the Charness
+ * checkout instead of the operator's projects parent. We hand the worker the real
+ * launch dir as `WORK_ROOT` so it binds against where the wrapper was started.
+ *
+ * An explicit `WORK_ROOT` in the inherited env always wins (advanced
+ * override); empty/unset falls back to `launchCwd` — matching how `runBot`
+ * itself treats `WORK_ROOT` (`!process.env.WORK_ROOT`).
+ */
+export declare function buildHotWorkerEnv(baseEnv: NodeJS.ProcessEnv, launchCwd: string): NodeJS.ProcessEnv;
+export {};
+//# sourceMappingURL=hot.d.ts.map

package/dist/cli/hot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot.d.ts","sourceRoot":"","sources":["../../src/cli/hot.ts"],"names":[],"mappings":"AAeA,UAAU,eAAe;IACvB,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,KAAK,YAAY,GAAG,KAAK,GAAG,SAAS,CAAC;AAMtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CA2J5C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,YAAY,EACvB,aAAa,EAAE,MAAM,CAAC,OAAO,GAC5B,MAAM,CAAC,OAAO,CAEhB;AAED,yEAAyE;AACzE,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEzE;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,OAAO,CAAC,QAAQ,GAAG,OAAO,CAElF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,GAAE,eAKL,GACA,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,UAAU,CAMnB"}