@fraziym/axoniz 0.1.0

package/dist/startup.js

@@ -0,0 +1,194 @@
+/**
+ * AXONIZ-ZERO Startup Integration — boots every subsystem in the right order.
+ * Port of axoniz/startup.py.
+ *
+ * Handles:
+ *   - Palace / KG memory warm-up
+ *   - Workflow engine start
+ *   - Awareness service start (optional)
+ *   - Telegram bot start (if configured)
+ *   - Sidecar connection attempt
+ *   - Web server init with all managers wired
+ */
+import process from "node:process";
+import { loadConfig, loadConfigWithAutodetect } from "./core/config.js";
+import { debug, info, warn } from "./core/debug.js";
+/* ── Step 1: Build agent ──────────────────────────────────────────────────── */
+export async function bootAgent(cfg = null, overrides = null) {
+    const { Agent } = await import("./core/agent.js");
+    const config = (cfg ?? loadConfigWithAutodetect());
+    if (overrides) {
+        for (const [k, v] of Object.entries(overrides)) {
+            if (v !== null && v !== undefined)
+                config[k] = v;
+        }
+    }
+    // Ensure a provider is set only when none is configured.
+    const llm = config.llm;
+    if (!config.provider && !config.backend && !llm?.active_provider) {
+        config.provider = "llamacpp";
+        config.backend = "llamacpp";
+    }
+    // Enable standby mode for faster startup: weights load on first use.
+    if (config.standby === undefined || config.standby === null)
+        config.standby = true;
+    info(`[Startup] Building agent | provider=${String(config.provider)} ` +
+        `model=${String(config.model_path ?? "none")}`);
+    return new Agent(config);
+}
+/* ── Step 2: Warm up memory ───────────────────────────────────────────────── */
+export function bootMemory(agent) {
+    // Non-blocking warm-up.
+    void (async () => {
+        try {
+            if (agent.memory.palace.is_available()) {
+                const ctx = await agent.memory.palace.get_context();
+                info(`[Memory] Palace warm | ${String(ctx).length} chars context loaded`);
+            }
+            const kgStats = agent.memory.kg.stats();
+            info(`[Memory] KG ready | ${Number(kgStats.total_facts ?? 0)} facts`);
+        }
+        catch (e) {
+            warn(`[Memory] Warm failed: ${errMsg(e)}`);
+        }
+    })();
+}
+/* ── Step 3: Workflow engine ──────────────────────────────────────────────── */
+export async function bootWorkflows(agent) {
+    try {
+        const m = (await import("./workflows/engine.js"));
+        const wf = m.getWorkflowEngine();
+        wf.setAgentCallback((task) => agent.run(task));
+        wf.start();
+        const st = wf.status();
+        info(`[Workflows] ${st.total_workflows ?? 0} workflows | ${st.enabled ?? 0} enabled`);
+        return wf;
+    }
+    catch (e) {
+        warn(`[Workflows] Failed to start: ${errMsg(e)}`);
+        return null;
+    }
+}
+/* ── Step 4: Awareness service (optional) ─────────────────────────────────── */
+export async function bootAwareness(agent) {
+    if (!loadConfig().awareness?.enabled) {
+        debug("[Awareness] Disabled in config (set awareness.enabled=true to enable)");
+        return null;
+    }
+    try {
+        const m = (await import("./awareness/service.js"));
+        const svc = m.getAwarenessService();
+        svc.setSuggestionCallback((s) => {
+            agent.onToken?.(`\n[\u26a1 FRAZIYM AI] ${s}\n`);
+        });
+        svc.start();
+        info("[Awareness] Service started");
+        return svc;
+    }
+    catch (e) {
+        warn(`[Awareness] Failed to start: ${errMsg(e)}`);
+        return null;
+    }
+}
+/* ── Step 5: Telegram bot (optional) ──────────────────────────────────────── */
+export async function bootTelegram(agent) {
+    try {
+        const m = (await import("./comms/telegram.js"));
+        const bot = m.getBot();
+        if (!bot.isConfigured()) {
+            debug("[Telegram] Not configured (set BERU_TELEGRAM_TOKEN + BERU_TELEGRAM_CHAT_ID)");
+            return null;
+        }
+        m.startBot({ agentCallback: (t) => agent.run(t) });
+        info("[Telegram] Bot started");
+        return bot;
+    }
+    catch (e) {
+        warn(`[Telegram] Failed to start: ${errMsg(e)}`);
+        return null;
+    }
+}
+/* ── Step 6: Sidecar connection ───────────────────────────────────────────── */
+export async function bootSidecar() {
+    try {
+        const m = (await import("./sidecar/client.js"));
+        const sc = await m.getSidecar();
+        if (await sc.is_alive()) {
+            info(`[Sidecar] Connected at ${sc.base_url}`);
+            return sc;
+        }
+        debug("[Sidecar] Not running (optional — install Jarvis sidecar to enable)");
+        return null;
+    }
+    catch (e) {
+        warn(`[Sidecar] Connection failed: ${errMsg(e)}`);
+        return null;
+    }
+}
+/* ── Step 7: Web server ───────────────────────────────────────────────────── */
+export async function bootWeb(agent, port = 7860, host = "localhost", openBrowser = true) {
+    const { WebServer } = await import("./web/server.js");
+    const ws = new WebServer({ agent, host, port });
+    await ws.start(openBrowser);
+}
+/**
+ * Boot everything in the correct order and return the agent.
+ * If `web` is true, blocks serving the web UI.
+ */
+export async function fullBoot(opts = {}) {
+    const { cfg = null, overrides = null, port = 7860, openBrowser = true, web = true } = opts;
+    printBootHeader();
+    const agent = await bootAgent(cfg, overrides);
+    printStep("Agent", `provider=${String(agent.config.provider)} workspace=${agent.workspace}`);
+    bootMemory(agent);
+    printStep("Memory", "palace + KG warming");
+    // Phase: Axodex check
+    const axStatus = await agent.axodex.status();
+    if (axStatus.includes("ERROR")) {
+        printStep("Axodex", "\u001b[91mNo index found\u001b[0m (Run 'axodex analyze')");
+    }
+    else {
+        printStep("Axodex", "Graph index active");
+    }
+    await bootWorkflows(agent);
+    printStep("Workflows", "engine running");
+    await bootAwareness(agent);
+    printStep("Awareness", loadConfig().awareness?.enabled ? "started" : "disabled");
+    await bootTelegram(agent);
+    const sc = await bootSidecar();
+    printStep("Sidecar", sc ? "connected" : "offline (optional)");
+    console.log();
+    if (web) {
+        await bootWeb(agent, port, "localhost", openBrowser);
+    }
+    return agent;
+}
+/* ── Print helpers ────────────────────────────────────────────────────────── */
+function c(code) {
+    if (process.env.NO_COLOR || !process.stdout.isTTY)
+        return "";
+    return `\u001b[${code}m`;
+}
+const R = c("0");
+const DG = c("90");
+const GR = c("37");
+const GB = c("92");
+const WH = c("97");
+const B = c("1");
+const PU = c("95");
+void WH;
+void R;
+function printBootHeader() {
+    console.log();
+    console.log(`  ${PU}${B}AXONIZ-ZERO - FRAZIYM AI${c("0")}  ${DG}booting...${c("0")}`);
+    console.log();
+}
+function printStep(name, detail) {
+    const lower = detail.toLowerCase();
+    const status = !lower.includes("fail") && !lower.includes("error") ? `${GB}+${c("0")}` : `\u001b[91m-${c("0")}`;
+    console.log(`  ${status}  ${DG}${name.padEnd(14)}${c("0")}${GR}${detail}${c("0")}`);
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=startup.js.map

package/dist/startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.js","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAqB,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAGpD,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAG,GAAwB,IAAI,EAC/B,SAAS,GAAmC,IAAI;IAEhD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,wBAAwB,EAAE,CAAuC,CAAC;IACzF,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;gBAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,yDAAyD;IACzD,MAAM,GAAG,GAAG,MAAM,CAAC,GAA0C,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC;QACjE,MAAM,CAAC,QAAQ,GAAG,UAAU,CAAC;QAC7B,MAAM,CAAC,OAAO,GAAG,UAAU,CAAC;IAC9B,CAAC;IAED,qEAAqE;IACrE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAEnF,IAAI,CACF,uCAAuC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG;QAC/D,SAAS,MAAM,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,EAAE,CACjD,CAAC;IACF,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,iFAAiF;AAEjF,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,wBAAwB;IACxB,KAAK,CAAC,KAAK,IAAI,EAAE;QACf,IAAI,CAAC;YACH,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC;gBACvC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;gBACpD,IAAI,CAAC,0BAA0B,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,uBAAuB,CAAC,CAAC;YAC5E,CAAC;YACD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YACxC,IAAI,CAAC,uBAAuB,MAAM,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,yBAAyB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;AACP,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAY;IAC9C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAM/C,CAAC;QACF,MAAM,EAAE,GAAG,CAAC,CAAC,iBAAiB,EAAE,CAAC;QACjC,EAAE,CAAC,gBAAgB,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,eAAe,EAAE,CAAC,eAAe,IAAI,CAAC,gBAAgB,EAAE,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC;QACtF,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,gCAAgC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAY;IAC9C,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC;QACrC,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAKhD,CAAC;QACF,MAAM,GAAG,GAAG,CAAC,CAAC,mBAAmB,EAAE,CAAC;QACpC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAS,EAAE,EAAE;YACtC,KAAK,CAAC,OAAO,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,IAAI,CAAC,6BAA6B,CAAC,CAAC;QACpC,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,gCAAgC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAY;IAC7C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAG7C,CAAC;QACF,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC;YACxB,KAAK,CAAC,6EAA6E,CAAC,CAAC;YACrF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,CAAC,CAAC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAC/B,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,+BAA+B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAE7C,CAAC;QACF,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,UAAU,EAAE,CAAC;QAChC,IAAI,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC,0BAA0B,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,KAAK,CAAC,qEAAqE,CAAC,CAAC;QAC7E,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,gCAAgC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAY,EACZ,IAAI,GAAG,IAAI,EACX,IAAI,GAAG,WAAW,EAClB,WAAW,GAAG,IAAI;IAElB,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;AAC9B,CAAC;AAYD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAI,GAAoB,EAAE;IACvD,MAAM,EAAE,GAAG,GAAG,IAAI,EAAE,SAAS,GAAG,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAE3F,eAAe,EAAE,CAAC;IAElB,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC9C,SAAS,CACP,OAAO,EACP,YAAY,MAAM,CAAE,KAAK,CAAC,MAAkC,CAAC,QAAQ,CAAC,cAAc,KAAK,CAAC,SAAS,EAAE,CACtG,CAAC;IAEF,UAAU,CAAC,KAAK,CAAC,CAAC;IAClB,SAAS,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;IAE3C,sBAAsB;IACtB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC7C,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,SAAS,CAAC,QAAQ,EAAE,0DAA0D,CAAC,CAAC;IAClF,CAAC;SAAM,CAAC;QACN,SAAS,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3B,SAAS,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAEzC,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3B,SAAS,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAEjF,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;IAE1B,MAAM,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAC/B,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAE9D,OAAO,CAAC,GAAG,EAAE,CAAC;IAEd,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AAEjF,SAAS,CAAC,CAAC,IAAY;IACrB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAC7D,OAAO,UAAU,IAAI,GAAG,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AACjB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AACnB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AACnB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AACnB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AACnB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AACjB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AACnB,KAAK,EAAE,CAAC;AACR,KAAK,CAAC,CAAC;AAEP,SAAS,eAAe;IACtB,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,2BAA2B,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,MAAc;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,MAAM,MAAM,GACV,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACnG,OAAO,CAAC,GAAG,CAAC,KAAK,MAAM,KAAK,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/tools/_internal.d.ts

@@ -0,0 +1,90 @@
+/**
+ * AXONIZ-ZERO — internal helpers shared by the `src/tools/*` ports.
+ *
+ * Private to `src/tools` (`_` prefix, not re-exported from `index.ts`). It
+ * replaces the Python standard-library primitives the original modules used:
+ *
+ *   subprocess.run(capture_output=True) -> runCaptured   (promisified exec)
+ *   subprocess.run([...])               -> execFileCaptured
+ *   glob.glob(..., recursive=True)      -> expandGlob / globToRegExp
+ *   difflib.unified_diff                -> unifiedDiff
+ *   shutil.which                        -> resolveCommand (wraps core whichSync)
+ */
+export interface CapturedRun {
+    /** Captured stdout (UTF-8 decoded, invalid bytes replaced). */
+    stdout: string;
+    /** Captured stderr (UTF-8 decoded, invalid bytes replaced). */
+    stderr: string;
+    /** Exit code; `null` when the process was killed by a signal. */
+    code: number | null;
+    /** True when the process was killed because the timeout elapsed. */
+    timedOut: boolean;
+}
+export interface RunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    /** Output ceiling in characters (default 16 MiB). */
+    maxBuffer?: number;
+}
+/**
+ * Run a command through the platform shell (`cmd.exe /c` on Windows,
+ * `/bin/sh -c` elsewhere) with output captured as text.
+ *
+ * Never rejects: spawn failures, non-zero exits and timeouts all resolve with
+ * a `CapturedRun`, mirroring `subprocess.run` inside a try/except.
+ */
+export declare function runCaptured(command: string, opts?: RunOptions): Promise<CapturedRun>;
+/**
+ * Run an executable directly (no shell) with output captured as text.
+ * Rejects with the original error when the binary cannot be spawned at all
+ * (Python's `FileNotFoundError`); non-zero exits and timeouts resolve.
+ */
+export declare function execFileCaptured(file: string, args: string[], opts?: RunOptions): Promise<CapturedRun>;
+/**
+ * Resolve an executable against PATH, following Windows shim extensions
+ * (`npx` -> `npx.cmd`) so `execFile` can launch it without a shell.
+ */
+export declare function resolveCommand(name: string): string | null;
+/** Render an unknown thrown value the way Python's `str(e)` would. */
+export declare function errText(e: unknown): string;
+/** True when the segment contains glob metacharacters (`*`, `?`, `[...]`). */
+export declare function hasGlobMagic(segment: string): boolean;
+/**
+ * Compile one `path`-style glob pattern into an anchored RegExp supporting
+ * `*` (segment-local), `**` (any number of segments) and `[...]` classes.
+ * Matching is done on forward-slash-normalised paths.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/**
+ * `glob.glob(os.path.join(base, "**", pattern), recursive=True)`.
+ *
+ * Returns absolute paths built with the native separator, skipping
+ * dot-directories (Python's `glob` does not descend into hidden entries for a
+ * wildcard segment) and refusing to escape `base`.
+ */
+export declare function expandGlob(base: string, pattern: string): string[];
+export interface UnifiedDiffOptions {
+    fromFile: string;
+    toFile: string;
+    /** Context lines, mirrors difflib's `n=`. Default 3. */
+    context?: number;
+}
+/** One difflib-style opcode: a[i1:i2] vs b[j1:j2]. */
+interface Opcode {
+    tag: "equal" | "delete" | "insert";
+    i1: number;
+    i2: number;
+    j1: number;
+    j2: number;
+}
+/** Opcodes from an LCS table — same shape as `difflib.SequenceMatcher.get_opcodes()`. */
+export declare function sequenceOpcodes(a: string[], b: string[]): Opcode[];
+/**
+ * Pragmatic stand-in for `difflib.unified_diff(a, b, fromfile, tofile, n=k)`.
+ * Emits `---`/`+++` headers, `@@ -l,s +l,s @@` hunk headers, then context,
+ * removal (`-`) and addition (`+`) lines exactly as difflib does.
+ */
+export declare function unifiedDiff(a: string[], b: string[], opts: UnifiedDiffOptions): string[];
+export {};
+//# sourceMappingURL=_internal.d.ts.map

package/dist/tools/_internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_internal.d.ts","sourceRoot":"","sources":["../../src/tools/_internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAuCxF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,WAAW,CAAC,CA8CtB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO1D;AAED,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAQ1C;AAID,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErD;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA6CpD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA6ClE;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sDAAsD;AACtD,UAAU,MAAM;IACd,GAAG,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAoClE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,CA4ExF"}

package/dist/tools/_internal.js

@@ -0,0 +1,375 @@
+/**
+ * AXONIZ-ZERO — internal helpers shared by the `src/tools/*` ports.
+ *
+ * Private to `src/tools` (`_` prefix, not re-exported from `index.ts`). It
+ * replaces the Python standard-library primitives the original modules used:
+ *
+ *   subprocess.run(capture_output=True) -> runCaptured   (promisified exec)
+ *   subprocess.run([...])               -> execFileCaptured
+ *   glob.glob(..., recursive=True)      -> expandGlob / globToRegExp
+ *   difflib.unified_diff                -> unifiedDiff
+ *   shutil.which                        -> resolveCommand (wraps core whichSync)
+ */
+import { exec, execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { whichSync } from "../core/which.js";
+/**
+ * Run a command through the platform shell (`cmd.exe /c` on Windows,
+ * `/bin/sh -c` elsewhere) with output captured as text.
+ *
+ * Never rejects: spawn failures, non-zero exits and timeouts all resolve with
+ * a `CapturedRun`, mirroring `subprocess.run` inside a try/except.
+ */
+export function runCaptured(command, opts = {}) {
+    const timeout = opts.timeoutMs ?? 0;
+    return new Promise((resolve) => {
+        exec(command, {
+            cwd: opts.cwd,
+            env: opts.env,
+            timeout: timeout > 0 ? timeout : undefined,
+            killSignal: "SIGKILL",
+            maxBuffer: opts.maxBuffer ?? 16 * 1024 * 1024,
+            encoding: "utf8",
+            windowsHide: true,
+        }, (err, stdout, stderr) => {
+            const e = err;
+            let code = 0;
+            let timedOut = false;
+            if (e) {
+                if (typeof e.code === "number") {
+                    code = e.code;
+                }
+                else if (e.killed || e.signal) {
+                    code = null;
+                    timedOut = true;
+                }
+                else {
+                    code = 1;
+                }
+            }
+            resolve({
+                stdout: String(stdout ?? ""),
+                stderr: String(stderr ?? ""),
+                code,
+                timedOut,
+            });
+        });
+    });
+}
+/**
+ * Run an executable directly (no shell) with output captured as text.
+ * Rejects with the original error when the binary cannot be spawned at all
+ * (Python's `FileNotFoundError`); non-zero exits and timeouts resolve.
+ */
+export function execFileCaptured(file, args, opts = {}) {
+    const timeout = opts.timeoutMs ?? 0;
+    return new Promise((resolve, reject) => {
+        execFile(file, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            timeout: timeout > 0 ? timeout : undefined,
+            killSignal: "SIGKILL",
+            maxBuffer: opts.maxBuffer ?? 16 * 1024 * 1024,
+            encoding: "utf8",
+            windowsHide: true,
+            shell: false,
+        }, (err, stdout, stderr) => {
+            const e = err;
+            if (!e) {
+                resolve({ stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), code: 0, timedOut: false });
+                return;
+            }
+            if (e.killed || e.signal) {
+                resolve({
+                    stdout: String(stdout ?? ""),
+                    stderr: String(stderr ?? ""),
+                    code: null,
+                    timedOut: true,
+                });
+                return;
+            }
+            if (typeof e.code === "number") {
+                resolve({
+                    stdout: String(stdout ?? ""),
+                    stderr: String(stderr ?? ""),
+                    code: e.code,
+                    timedOut: false,
+                });
+                return;
+            }
+            reject(e);
+        });
+    });
+}
+/**
+ * Resolve an executable against PATH, following Windows shim extensions
+ * (`npx` -> `npx.cmd`) so `execFile` can launch it without a shell.
+ */
+export function resolveCommand(name) {
+    const direct = whichSync(name);
+    if (direct)
+        return direct;
+    if (process.platform === "win32" && !/\.(cmd|bat|exe|com)$/i.test(name)) {
+        return whichSync(`${name}.cmd`) ?? whichSync(`${name}.bat`) ?? whichSync(`${name}.exe`);
+    }
+    return null;
+}
+/** Render an unknown thrown value the way Python's `str(e)` would. */
+export function errText(e) {
+    if (e instanceof Error)
+        return e.message || e.name;
+    if (typeof e === "string")
+        return e;
+    try {
+        return JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+/* ── glob (replaces the Python `glob` module; the npm package is unavailable) ── */
+/** True when the segment contains glob metacharacters (`*`, `?`, `[...]`). */
+export function hasGlobMagic(segment) {
+    return /[*?[]/.test(segment);
+}
+function escapeReChar(ch) {
+    return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+/**
+ * Compile one `path`-style glob pattern into an anchored RegExp supporting
+ * `*` (segment-local), `**` (any number of segments) and `[...]` classes.
+ * Matching is done on forward-slash-normalised paths.
+ */
+export function globToRegExp(pattern) {
+    const p = pattern.replace(/\\/g, "/");
+    let out = "";
+    let i = 0;
+    while (i < p.length) {
+        const ch = p[i];
+        if (ch === "*") {
+            let stars = 0;
+            while (p[i] === "*") {
+                stars++;
+                i++;
+            }
+            if (stars >= 2) {
+                if (p[i] === "/") {
+                    out += "(?:[^/]*/)*"; // `**/` => zero or more directories
+                    i++;
+                }
+                else {
+                    out += ".*";
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+            continue;
+        }
+        if (ch === "?") {
+            out += "[^/]";
+            i++;
+            continue;
+        }
+        if (ch === "[") {
+            const close = p.indexOf("]", i + 1);
+            if (close > i + 1) {
+                const inner = p.slice(i + 1, close);
+                out += `[${inner.split("").map(escapeReChar).join("")}]`;
+                i = close + 1;
+                continue;
+            }
+            out += "\\[";
+            i++;
+            continue;
+        }
+        out += escapeReChar(ch);
+        i++;
+    }
+    return new RegExp(`^${out}$`);
+}
+/**
+ * `glob.glob(os.path.join(base, "**", pattern), recursive=True)`.
+ *
+ * Returns absolute paths built with the native separator, skipping
+ * dot-directories (Python's `glob` does not descend into hidden entries for a
+ * wildcard segment) and refusing to escape `base`.
+ */
+export function expandGlob(base, pattern) {
+    const results = [];
+    const pat = pattern.replace(/\\/g, "/");
+    const patWantsHidden = pat.startsWith(".") || pat.includes("/.");
+    // A literal name (no magic, no separators) is resolved relative to base.
+    if (!hasGlobMagic(pat) && !pat.includes("/")) {
+        const candidate = path.join(base, pat);
+        try {
+            fs.statSync(candidate);
+            results.push(candidate);
+        }
+        catch {
+            /* not found */
+        }
+        return results;
+    }
+    const matchers = [globToRegExp(`**/${pat}`), globToRegExp(pat)];
+    const walk = (dir, depth) => {
+        if (depth > 64)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const name = ent.name;
+            const full = path.join(dir, name);
+            if (ent.isDirectory()) {
+                if (!patWantsHidden && name.startsWith("."))
+                    continue;
+                walk(full, depth + 1);
+                continue;
+            }
+            if (!patWantsHidden && name.startsWith("."))
+                continue;
+            const rel = path.relative(base, full);
+            if (rel.startsWith(".."))
+                continue;
+            const abs = full.replace(/\\/g, "/");
+            const relSlash = rel.replace(/\\/g, "/");
+            if (matchers.some((rx) => rx.test(abs) || rx.test(relSlash)))
+                results.push(full);
+        }
+    };
+    walk(path.resolve(base), 0);
+    return results;
+}
+/** Opcodes from an LCS table — same shape as `difflib.SequenceMatcher.get_opcodes()`. */
+export function sequenceOpcodes(a, b) {
+    const n = a.length;
+    const m = b.length;
+    // dp[i][j] = LCS length of a[i:] and b[j:]
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        const row = dp[i];
+        const nxt = dp[i + 1];
+        for (let j = m - 1; j >= 0; j--) {
+            row[j] = a[i] === b[j] ? nxt[j + 1] + 1 : Math.max(nxt[j], row[j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        const startI = i;
+        const startJ = j;
+        if (a[i] === b[j]) {
+            while (i < n && j < m && a[i] === b[j]) {
+                i++;
+                j++;
+            }
+            ops.push({ tag: "equal", i1: startI, i2: i, j1: startJ, j2: j });
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            while (i < n && j < m && a[i] !== b[j] && dp[i + 1][j] >= dp[i][j + 1])
+                i++;
+            ops.push({ tag: "delete", i1: startI, i2: i, j1: startJ, j2: j });
+        }
+        else {
+            while (i < n && j < m && a[i] !== b[j] && dp[i + 1][j] < dp[i][j + 1])
+                j++;
+            ops.push({ tag: "insert", i1: startI, i2: i, j1: startJ, j2: j });
+        }
+    }
+    if (i < n)
+        ops.push({ tag: "delete", i1: i, i2: n, j1: j, j2: m });
+    if (j < m)
+        ops.push({ tag: "insert", i1: i, i2: n, j1: j, j2: m });
+    return ops;
+}
+/**
+ * Pragmatic stand-in for `difflib.unified_diff(a, b, fromfile, tofile, n=k)`.
+ * Emits `---`/`+++` headers, `@@ -l,s +l,s @@` hunk headers, then context,
+ * removal (`-`) and addition (`+`) lines exactly as difflib does.
+ */
+export function unifiedDiff(a, b, opts) {
+    const n = opts.context ?? 3;
+    const out = [`--- ${opts.fromFile}`, `+++ ${opts.toFile}`];
+    const tagged = [];
+    for (const op of sequenceOpcodes(a, b)) {
+        if (op.tag === "equal") {
+            for (let k = op.i1; k < op.i2; k++)
+                tagged.push({ tag: "equal", text: a[k] });
+        }
+        else if (op.tag === "delete") {
+            for (let k = op.i1; k < op.i2; k++)
+                tagged.push({ tag: "delete", text: a[k] });
+        }
+        else {
+            for (let k = op.j1; k < op.j2; k++)
+                tagged.push({ tag: "insert", text: b[k] });
+        }
+    }
+    if (!tagged.some((t) => t.tag !== "equal"))
+        return out;
+    const changedIdx = [];
+    tagged.forEach((t, i) => {
+        if (t.tag !== "equal")
+            changedIdx.push(i);
+    });
+    // Merge change windows that overlap within 2*n of context.
+    const ranges = [];
+    let start = Math.max(0, changedIdx[0] - n);
+    let end = Math.min(tagged.length, changedIdx[0] + n + 1);
+    for (let k = 1; k < changedIdx.length; k++) {
+        const i = changedIdx[k];
+        if (i - n <= end) {
+            end = Math.min(tagged.length, i + n + 1);
+        }
+        else {
+            ranges.push([start, end]);
+            start = Math.max(0, i - n);
+            end = Math.min(tagged.length, i + n + 1);
+        }
+    }
+    ranges.push([start, end]);
+    // Track 1-based line numbers on both sides across the whole stream.
+    const aNo = new Array(tagged.length + 1);
+    const bNo = new Array(tagged.length + 1);
+    let aLine = 1;
+    let bLine = 1;
+    for (let i = 0; i < tagged.length; i++) {
+        aNo[i] = aLine;
+        bNo[i] = bLine;
+        const t = tagged[i];
+        if (t.tag !== "insert")
+            aLine++;
+        if (t.tag !== "delete")
+            bLine++;
+    }
+    aNo[tagged.length] = aLine;
+    bNo[tagged.length] = bLine;
+    for (const [s, e] of ranges) {
+        let aLen = 0;
+        let bLen = 0;
+        for (let k = s; k < e; k++) {
+            const t = tagged[k];
+            if (t.tag !== "insert")
+                aLen++;
+            if (t.tag !== "delete")
+                bLen++;
+        }
+        const aStart = aLen === 0 ? aNo[s] - 1 : aNo[s];
+        const bStart = bLen === 0 ? bNo[s] - 1 : bNo[s];
+        out.push(`@@ -${aStart},${aLen} +${bStart},${bLen} @@`);
+        for (let k = s; k < e; k++) {
+            const t = tagged[k];
+            const prefix = t.tag === "equal" ? " " : t.tag === "delete" ? "-" : "+";
+            out.push(`${prefix}${t.text}`);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=_internal.js.map