charness 0.0.0-stage → 3.0.0

package/dist/cli/hot.js

@@ -0,0 +1,323 @@
+"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.runHot = runHot;
+exports.getHotChildShutdownSignal = getHotChildShutdownSignal;
+exports.getUnexpectedHotChildExitCode = getUnexpectedHotChildExitCode;
+exports.checkIsHotModeSupported = checkIsHotModeSupported;
+exports.checkIsTscWatchReady = checkIsTscWatchReady;
+exports.prepareHotOpenCodeServer = prepareHotOpenCodeServer;
+exports.buildHotWorkerEnv = buildHotWorkerEnv;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const connectorGuards_1 = require("./connectorGuards");
+const connectorSet_1 = require("../platform/connectorSet");
+const installManager_1 = require("../installManager");
+const tscWatchCompleteMarker = 'Watching for file changes.';
+const tscWatchReadyMarker = `Found 0 errors. ${tscWatchCompleteMarker}`;
+const tscWatchTailLength = tscWatchReadyMarker.length - 1;
+/**
+ * @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`).
+ */
+async function runHot() {
+    // The operator's real launch directory (e.g. `~/src`). Captured BEFORE any
+    // spawn so it reflects where `telegramcode hot` was invoked — the worker
+    // can't derive it later, because nodemon runs it with cwd = projectRoot.
+    const launchCwd = process.cwd();
+    const projectRoot = resolveProjectRoot();
+    if (!checkIsHotModeSupported(process.platform)) {
+        process.stderr.write('telegramcode hot: Windows is not supported because nodemon cannot gracefully drain its worker tree.\n');
+        process.exit(1);
+        return;
+    }
+    // Match the worker's env sources without changing the launch cwd that owns
+    // WORK_ROOT. This is load-bearing when the repo .env selects a custom port.
+    // The connector guards wrap it, as in the plain start (Jira plan J3).
+    (0, connectorGuards_1.loadEnvWithConnectorGuards)(projectRoot);
+    // Only nodemon's replaceable worker externalizes later server generations.
+    // The long-lived supervisor owns the initial server directly.
+    delete process.env[installManager_1.openCodeExternalHostEnvName];
+    process.env[installManager_1.openCodeOwnershipFileEnvName] = (0, installManager_1.getDefaultOpenCodeOwnershipFilePath)(projectRoot);
+    const distEntry = path.join(projectRoot, 'dist', 'cli', 'botEntry.js');
+    const tscBin = localBin(projectRoot, 'tsc');
+    const nodemonBin = localBin(projectRoot, 'nodemon');
+    if (!fs.existsSync(tscBin) || !fs.existsSync(nodemonBin)) {
+        process.stderr.write(`telegramcode hot: missing devDependencies in ${projectRoot}.\n` +
+            `  expected: ${tscBin}\n` +
+            `  expected: ${nodemonBin}\n` +
+            `Run \`yarn install\` (or \`npm install\`) in the project root and retry.\n`);
+        process.exit(1);
+        return;
+    }
+    // nodemon kills the worker's complete descendant tree on every rebuild.
+    // Own OpenCode here, as a sibling of nodemon, so an agent turn survives the
+    // relay worker being replaced. The worker's normal ensure call adopts it.
+    // OpenCode serves Telegram topics only; an instance without Telegram must not
+    // start — or, finding a stale server on the port, stop — any OpenCode server.
+    const connectors = (0, connectorSet_1.parseConnectors)(process.env.CONNECTORS);
+    if (connectors.ok && connectors.connectors.includes('telegram'))
+        await prepareHotOpenCodeServer();
+    process.stderr.write(`telegramcode hot: project=${projectRoot}\n` +
+        `telegramcode hot: starting \`tsc -w\`; nodemon starts after the first completed compile.\n` +
+        `telegramcode hot: Ctrl-C stops both watchers.\n`);
+    // Forward terminating signals. We deliberately do NOT re-raise on
+    // ourselves after children exit — once both watchers are down the wrapper
+    // resolves normally and Node exits with the recorded code. Re-raising
+    // would mask the underlying child exit code.
+    const children = new Set();
+    let nodemonChild = null;
+    let shuttingDown = false;
+    let finalCode = 0;
+    let resolveChildrenStopped = null;
+    const childrenStopped = new Promise((resolve) => {
+        resolveChildrenStopped = resolve;
+    });
+    const checkShouldResolveChildren = () => {
+        if (shuttingDown && children.size === 0)
+            resolveChildrenStopped?.();
+    };
+    const forwardSignal = (sig) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        for (const child of children) {
+            if (child.killed || child.exitCode !== null)
+                continue;
+            const childName = child === nodemonChild ? 'nodemon' : 'tsc';
+            child.kill(getHotChildShutdownSignal(childName, sig));
+        }
+        checkShouldResolveChildren();
+    };
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(sig, () => forwardSignal(sig));
+    }
+    const registerChild = (child, childName) => {
+        children.add(child);
+        let isSettled = false;
+        const settleChild = (code, signal, error) => {
+            if (isSettled)
+                return;
+            isSettled = true;
+            children.delete(child);
+            if (error) {
+                process.stderr.write(`telegramcode hot: child error (${childName}): ${error.message}\n`);
+                if (!shuttingDown && finalCode === 0)
+                    finalCode = 1;
+            }
+            else {
+                const label = childName === 'tsc' ? 'tsc -w' : 'nodemon';
+                process.stderr.write(`telegramcode hot: ${label} exited ` +
+                    `(code=${code ?? 'null'}, signal=${signal ?? 'null'})\n`);
+                if (!shuttingDown && finalCode === 0) {
+                    finalCode = getUnexpectedHotChildExitCode(code);
+                }
+            }
+            if (!shuttingDown)
+                forwardSignal('SIGTERM');
+            checkShouldResolveChildren();
+        };
+        child.on('exit', (code, signal) => settleChild(code, signal));
+        child.on('error', (error) => settleChild(null, null, error));
+    };
+    const startNodemon = () => {
+        if (shuttingDown || nodemonChild !== null)
+            return;
+        nodemonChild = (0, child_process_1.spawn)(process.execPath, [nodemonBin], {
+            cwd: projectRoot,
+            stdio: 'inherit',
+            env: buildHotWorkerEnv(process.env, launchCwd),
+        });
+        registerChild(nodemonChild, 'nodemon');
+    };
+    // Keep stdout piped so tsc does not clear the terminal between rebuilds and
+    // so nodemon can be gated on the first completed watch compile.
+    const tscChild = (0, child_process_1.spawn)(process.execPath, [tscBin, '-w'], {
+        cwd: projectRoot,
+        stdio: ['ignore', 'pipe', 'inherit'],
+    });
+    registerChild(tscChild, 'tsc');
+    let tscOutputTail = '';
+    tscChild.stdout?.on('data', (chunk) => {
+        const output = chunk.toString();
+        process.stdout.write(output);
+        const inspectionText = tscOutputTail + output;
+        const isWatchComplete = inspectionText.includes(tscWatchCompleteMarker);
+        const isWatchReady = checkIsTscWatchReady(inspectionText);
+        tscOutputTail = inspectionText.slice(-tscWatchTailLength);
+        if (!isWatchComplete || nodemonChild !== null || shuttingDown)
+            return;
+        tscOutputTail = '';
+        if (!isWatchReady) {
+            process.stderr.write('telegramcode hot: compile has TypeScript errors; nodemon is waiting for a clean build. ' +
+                'Fix the errors and save.\n');
+            return;
+        }
+        if (fs.existsSync(distEntry)) {
+            startNodemon();
+            return;
+        }
+        process.stderr.write('telegramcode hot: clean compile produced no dist worker entry. ' +
+            'Check the TypeScript output path and save; nodemon will keep waiting.\n');
+    });
+    await childrenStopped;
+    process.exit(finalCode);
+}
+/**
+ * @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.
+ */
+function getHotChildShutdownSignal(childName, wrapperSignal) {
+    return childName === 'nodemon' ? 'SIGINT' : wrapperSignal;
+}
+/** Return a failing wrapper code whenever a watcher stops on its own. */
+function getUnexpectedHotChildExitCode(code) {
+    return code !== null && code !== 0 ? code : 1;
+}
+function checkIsHotModeSupported(platform) {
+    return platform !== 'win32';
+}
+function checkIsTscWatchReady(text) {
+    return text.includes(tscWatchReadyMarker);
+}
+/**
+ * @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.
+ */
+async function prepareHotOpenCodeServer(deps = {
+    checkIsInstalled: installManager_1.checkIsInstalled,
+    ensureOpenCodeServer: installManager_1.ensureOpenCodeServer,
+    stopOpenCodeServer: installManager_1.stopOpenCodeServer,
+    writeWarning: (message) => process.stderr.write(message),
+}) {
+    if (!deps.checkIsInstalled('opencode'))
+        return false;
+    try {
+        await deps.ensureOpenCodeServer();
+        return true;
+    }
+    catch (error) {
+        // `ensureOpenCodeServer` confirms cleanup for generations it started. This
+        // extra stop also covers failures outside that startup window.
+        deps.stopOpenCodeServer();
+        const message = error instanceof Error ? error.message : error?.toString() ?? 'unknown error';
+        deps.writeWarning(`telegramcode hot: OpenCode pre-start failed: ${message}\n`);
+        return false;
+    }
+}
+/**
+ * @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`).
+ */
+function buildHotWorkerEnv(baseEnv, launchCwd) {
+    return {
+        ...baseEnv,
+        WORK_ROOT: baseEnv.WORK_ROOT || launchCwd,
+        [installManager_1.openCodeExternalHostEnvName]: installManager_1.openCodeExternalHostEnvValue,
+    };
+}
+/**
+ * @description Resolve the project root from this module's own location.
+ *
+ * Layout: this file compiles to `<root>/dist/cli/hot.js`, so two `dirname`
+ * hops land on `<root>`. We canonicalize via `fs.realpathSync` because the
+ * global bin is an `npm link` symlink — without it, `__dirname` would point
+ * at the symlinked clone in the user's `node_modules`, not the editable
+ * checkout where `tsc -w` and `nodemon` must actually run.
+ */
+function resolveProjectRoot() {
+    const here = fs.realpathSync(__dirname);
+    return path.resolve(here, '..', '..');
+}
+/**
+ * @description Path to a binary inside the project's local `node_modules/.bin`.
+ *
+ * Returned even if the file is missing — the caller checks `fs.existsSync`
+ * and prints a help message naming the expected path.
+ */
+function localBin(projectRoot, name) {
+    return path.join(projectRoot, 'node_modules', '.bin', name);
+}
+//# sourceMappingURL=hot.js.map

package/dist/cli/hot.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+"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 });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const applyDnsFix_1 = require("./cli/applyDnsFix");
+const bot_1 = require("./cli/bot");
+const hot_1 = require("./cli/hot");
+(0, applyDnsFix_1.applyDnsFix)();
+/**
+ * @description Print the package version to stdout for `telegramcode --version`.
+ *
+ * Reads it from the shipped package.json (`__dirname` is `dist/`, so the file
+ * sits one level up) — the same idiom the `/version` bot command uses — so the
+ * number never drifts from a hardcoded string.
+ */
+function printVersion() {
+    let version = 'unknown';
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+        version = pkg.version || version;
+    }
+    catch {
+        /* fall through to unknown */
+    }
+    process.stdout.write(`${version}\n`);
+}
+/**
+ * @description Print top-level usage to stderr.
+ *
+ * Keeps the message short and copy-pastable. Detailed docs live in README;
+ * we surface just enough here for someone running `telegramcode --help`
+ * cold to know what to try next.
+ */
+function printUsage() {
+    process.stderr.write(`Usage:\n` +
+        `  telegramcode                  Start the bot (WORK_ROOT defaults to $PWD)\n` +
+        `  telegramcode hot              Hot-reload dev mode: tsc -w + nodemon on dist/\n` +
+        `                                  (rebuilds + restarts the bot on src/ edits;\n` +
+        `                                   in-flight agent sessions are reattached)\n` +
+        `  telegramcode --help, -h       Show this help\n` +
+        `  telegramcode --version, -v    Print the version\n` +
+        `\n` +
+        `Environment:\n` +
+        `  Loaded from ~/.config/telegramcode/.env (base) then $PWD/.env (override),\n` +
+        `  or with ENV_FILE=<absolute path> from that one file only.\n` +
+        `  Required to start: TELEGRAM_BOT_TOKEN (unless CONNECTORS leaves out telegram).\n` +
+        `  Access = creator + admins of the served forum group (read live; no user list).\n` +
+        `  ALLOWED_GROUP_ID is optional — leave it empty to auto-pair with your\n` +
+        `  forum supergroup on first contact (or use /pair in the group).\n` +
+        `  WORK_ROOT defaults to $PWD if unset.\n`);
+}
+/**
+ * @description Top-level dispatcher.
+ *
+ * Branches on `argv[2]`:
+ *   - missing          → start the Telegram bot
+ *   - `hot`            → hot-reload dev mode
+ *   - `-h | --help | help` → usage
+ *   - `-v | --version | version` → print the package version
+ *   - anything else → usage + exit 2
+ *
+ * The old `cli claude` passthrough is REMOVED: running plain
+ * `claude --dangerously-skip-permissions` in the project folder shares
+ * sessions with the bot naturally (same `~/.claude/projects/<cwd-slug>/`
+ * transcript store), so the wrapper added nothing.
+ *
+ * Exit 2 (not 1) for unknown commands matches the convention used by most
+ * Unix tools to distinguish "bad invocation" from "ran but failed".
+ */
+async function main() {
+    const [sub] = process.argv.slice(2);
+    if (sub === undefined) {
+        await (0, bot_1.runBot)();
+        return;
+    }
+    if (sub === 'hot') {
+        await (0, hot_1.runHot)();
+        return;
+    }
+    if (sub === '--help' || sub === '-h' || sub === 'help') {
+        printUsage();
+        return;
+    }
+    if (sub === '--version' || sub === '-v' || sub === 'version') {
+        printVersion();
+        return;
+    }
+    process.stderr.write(`Unknown command: ${sub}\n\n`);
+    printUsage();
+    process.exit(2);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,uCAAyB;AACzB,2CAA6B;AAC7B,mDAAgD;AAChD,mCAAmC;AACnC,mCAAmC;AAEnC,IAAA,yBAAW,GAAE,CAAC;AAEd;;;;;;GAMG;AACH,SAAS,YAAY;IACnB,IAAI,OAAO,GAAG,SAAS,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5F,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU;IACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,UAAU;QACR,8EAA8E;QAC9E,kFAAkF;QAClF,iFAAiF;QACjF,+EAA+E;QAC/E,kDAAkD;QAClD,qDAAqD;QACrD,IAAI;QACJ,gBAAgB;QAChB,+EAA+E;QAC/E,+DAA+D;QAC/D,oFAAoF;QACpF,oFAAoF;QACpF,0EAA0E;QAC1E,oEAAoE;QACpE,0CAA0C,CAC7C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAA,YAAM,GAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,MAAM,IAAA,YAAM,GAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;QACvD,UAAU,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IAED,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QAC7D,YAAY,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,GAAG,MAAM,CAAC,CAAC;IACpD,UAAU,EAAE,CAAC;IACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/connectors/jira/adf.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+/**
+ * @description Atlassian Document Format for the Jira connector (plan J4, D3):
+ * the agent's Markdown answer becomes an ADF comment body (`marklassian`), an
+ * issue's ADF description / comments become plain text for the agent's prompt
+ * (D15), and an answer longer than a comment holds is split on block
+ * boundaries first.
+ */
+/** An attribute value: any JSON value (ADF keeps e.g. a table's column widths as an array). */
+export type AdfAttributeValue = string | number | boolean | null | AdfAttributeValue[] | {
+    [name: string]: AdfAttributeValue;
+};
+export interface AdfMark {
+    type: string;
+    attrs?: Record<string, AdfAttributeValue>;
+}
+export interface AdfNode {
+    type: string;
+    attrs?: Record<string, AdfAttributeValue>;
+    content?: AdfNode[];
+    marks?: AdfMark[];
+    text?: string;
+}
+export interface AdfDocument {
+    version: 1;
+    type: 'doc';
+    content: AdfNode[];
+}
+/** Any JSON value — an ADF attribute, and the raw value of a Jira field the connector does not model. */
+export declare const attributeValueSchema: z.ZodType<AdfAttributeValue>;
+/** Validates an ADF node from a Jira response (unknown keys are dropped). */
+export declare const adfNodeSchema: z.ZodType<AdfNode>;
+/** Markdown the agent wrote → an ADF document for a comment body (D3); HTML in it stays literal text (R17), no media or unsafe links (R25). */
+export declare function convertMarkdownToAdf(markdown: string): AdfDocument;
+export declare function getStringAttribute(node: AdfNode | AdfMark, name: string): string | null;
+/**
+ * What a media node (`media` in a `mediaSingle` / `mediaGroup`, or a `mediaInline`) stands for in the text.
+ * The caller supplies it: only it knows the issue's attachments.
+ */
+export type AdfMediaResolver = (node: AdfNode) => string;
+/**
+ * @description An ADF document (or node) as plain text for the agent's prompt:
+ * one line per block, list items as `- …`, mentions by their display text,
+ * cards by their URL, a link as `text (address)`, a media node by what
+ * `resolveMedia` says (nothing without one). Other formatting is dropped.
+ */
+export declare function getAdfText(node: AdfNode | AdfDocument | null | undefined, resolveMedia?: AdfMediaResolver): string;
+/** Comfortably under Jira's 32 767-character comment body. */
+export declare const jiraCommentMarkdownMaxChars = 30000;
+/**
+ * The same margin for the serialized ADF body (R19): which count Jira enforces
+ * is not documented, and ADF JSON runs several times longer than its Markdown.
+ */
+export declare const jiraCommentAdfMaxChars = 30000;
+/**
+ * @description Split an answer into comment-sized Markdown chunks: whole blocks
+ * (paragraphs, lists, fenced code) packed in order; only a block that alone is
+ * too long is split inside, a code block keeping its fences on every piece.
+ * Blank input yields no chunk.
+ */
+export declare function splitMarkdownForComments(markdown: string, maxChars?: number): string[];
+/**
+ * @description An answer as the comment bodies to post, in order (R19): each
+ * fits Jira's limit by BOTH counts — its Markdown and its serialized ADF. Split
+ * by {@link splitMarkdownForComments} first; a piece whose ADF is still too
+ * long is split again with a cap scaled by its own ADF/Markdown ratio.
+ */
+export declare function createCommentBodies(markdown: string, limits?: {
+    markdownMaxChars: number;
+    adfMaxChars: number;
+}): AdfDocument[];
+//# sourceMappingURL=adf.d.ts.map

package/dist/connectors/jira/adf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adf.d.ts","sourceRoot":"","sources":["../../../src/connectors/jira/adf.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,+FAA+F;AAC/F,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,iBAAiB,EAAE,GAAG;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAE/H,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,KAAK,CAAC;IACZ,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB;AAED,yGAAyG;AACzG,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAS7D,CAAC;AAOF,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAQ5C,CAAC;AAsHF,+IAA+I;AAC/I,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAMlE;AAWD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvF;AAUD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;AAwCzD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,GAAG,SAAS,EAAE,YAAY,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAKlH;AAED,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAClD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAiI7C;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAA8B,GAAG,MAAM,EAAE,CAkB3G;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAA2F,GACjJ,WAAW,EAAE,CAEf"}