notoken-core 1.6.0 → 1.8.1

package/dist/utils/shellCompat.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shell compatibility layer.
+ *
+ * Abstracts platform differences so commands work on:
+ *   - Linux (bash)
+ *   - macOS (zsh/bash)
+ *   - Windows (cmd.exe / PowerShell)
+ *   - WSL (bash, but with /mnt/ Windows drives)
+ *
+ * Use these helpers instead of raw execSync with bash-isms.
+ */
+declare const isWin: boolean;
+declare const isWSL: boolean;
+export { isWin, isWSL };
+/**
+ * Check if a command exists on this platform.
+ */
+export declare function commandExists(cmd: string): boolean;
+/**
+ * Run a command and get output. Returns null on failure.
+ * Handles stderr redirection cross-platform.
+ */
+export declare function tryExec(cmd: string, timeout?: number): string | null;
+/**
+ * Get the temp directory.
+ */
+export declare function getTempDir(): string;
+/**
+ * Generate a timestamp string (replaces `$(date +%Y%m%d-%H%M%S)` in shell).
+ */
+export declare function timestamp(): string;
+/**
+ * Get file size in bytes. Returns 0 if file doesn't exist.
+ */
+export declare function fileSize(path: string): number;
+/**
+ * Count lines in a file without shell commands.
+ */
+export declare function lineCount(path: string): number;
+/**
+ * Run a command with proper shell for this platform.
+ */
+export declare function shellExec(cmd: string, opts?: {
+    cwd?: string;
+    timeout?: number;
+    stdio?: "inherit" | "pipe";
+}): string;
+/**
+ * Build a command that works on both Unix and Windows.
+ * Handles: stderr redirection, path separators, etc.
+ */
+export declare function crossPlatformCmd(unixCmd: string, windowsCmd?: string): string;
+/**
+ * Redirect stderr to null, cross-platform.
+ * Unix: 2>/dev/null
+ * Windows: 2>NUL
+ */
+export declare function silenceStderr(cmd: string): string;
+/**
+ * Get the home directory path.
+ */
+export declare function getHome(): string;
+/**
+ * Resolve a path that works on this platform.
+ */
+export declare function resolvePath(...parts: string[]): string;
+/**
+ * Check if running as root/admin.
+ */
+export declare function isAdmin(): boolean;
+/**
+ * Get the package install command for this platform.
+ */
+export declare function getSystemInstallCmd(pkg: string): string;
+/**
+ * Platform info for display.
+ */
+export declare function getPlatformSummary(): string;

package/dist/utils/shellCompat.js

@@ -0,0 +1,186 @@
+/**
+ * Shell compatibility layer.
+ *
+ * Abstracts platform differences so commands work on:
+ *   - Linux (bash)
+ *   - macOS (zsh/bash)
+ *   - Windows (cmd.exe / PowerShell)
+ *   - WSL (bash, but with /mnt/ Windows drives)
+ *
+ * Use these helpers instead of raw execSync with bash-isms.
+ */
+import { execSync } from "node:child_process";
+import { platform as osPlatform, tmpdir, homedir } from "node:os";
+import { statSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const isWin = osPlatform() === "win32";
+const isWSL = (() => {
+    try {
+        return !!execSync("grep -qi microsoft /proc/version && echo wsl", {
+            encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 2000,
+        }).trim();
+    }
+    catch {
+        return false;
+    }
+})();
+export { isWin, isWSL };
+/**
+ * Check if a command exists on this platform.
+ */
+export function commandExists(cmd) {
+    try {
+        if (isWin) {
+            execSync(`where ${cmd}`, { stdio: "pipe", timeout: 5000 });
+        }
+        else {
+            execSync(`command -v ${cmd}`, { stdio: "pipe", timeout: 5000 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run a command and get output. Returns null on failure.
+ * Handles stderr redirection cross-platform.
+ */
+export function tryExec(cmd, timeout = 5000) {
+    try {
+        const result = execSync(cmd, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout,
+            ...(isWin ? { shell: "cmd.exe" } : {}),
+        });
+        return result.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the temp directory.
+ */
+export function getTempDir() {
+    return tmpdir();
+}
+/**
+ * Generate a timestamp string (replaces `$(date +%Y%m%d-%H%M%S)` in shell).
+ */
+export function timestamp() {
+    const d = new Date();
+    return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}-${String(d.getHours()).padStart(2, "0")}${String(d.getMinutes()).padStart(2, "0")}${String(d.getSeconds()).padStart(2, "0")}`;
+}
+/**
+ * Get file size in bytes. Returns 0 if file doesn't exist.
+ */
+export function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Count lines in a file without shell commands.
+ */
+export function lineCount(path) {
+    try {
+        return readFileSync(path, "utf-8").split("\n").length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Run a command with proper shell for this platform.
+ */
+export function shellExec(cmd, opts = {}) {
+    const execOpts = {
+        encoding: "utf-8",
+        timeout: opts.timeout ?? 30000,
+        stdio: opts.stdio === "pipe" ? ["pipe", "pipe", "pipe"] : "inherit",
+    };
+    if (opts.cwd)
+        execOpts.cwd = opts.cwd;
+    if (isWin)
+        execOpts.shell = "cmd.exe";
+    return execSync(cmd, execOpts);
+}
+/**
+ * Build a command that works on both Unix and Windows.
+ * Handles: stderr redirection, path separators, etc.
+ */
+export function crossPlatformCmd(unixCmd, windowsCmd) {
+    if (isWin && windowsCmd)
+        return windowsCmd;
+    return unixCmd;
+}
+/**
+ * Redirect stderr to null, cross-platform.
+ * Unix: 2>/dev/null
+ * Windows: 2>NUL
+ */
+export function silenceStderr(cmd) {
+    if (isWin)
+        return `${cmd} 2>NUL`;
+    return `${cmd} 2>/dev/null`;
+}
+/**
+ * Get the home directory path.
+ */
+export function getHome() {
+    return homedir();
+}
+/**
+ * Resolve a path that works on this platform.
+ */
+export function resolvePath(...parts) {
+    return resolve(...parts);
+}
+/**
+ * Check if running as root/admin.
+ */
+export function isAdmin() {
+    if (isWin) {
+        return !!tryExec("net session 2>NUL");
+    }
+    return process.getuid?.() === 0;
+}
+/**
+ * Get the package install command for this platform.
+ */
+export function getSystemInstallCmd(pkg) {
+    if (isWin) {
+        if (commandExists("winget"))
+            return `winget install ${pkg} --accept-source-agreements --accept-package-agreements -h`;
+        if (commandExists("choco"))
+            return `choco install ${pkg} -y`;
+        return `echo "Please install ${pkg} manually"`;
+    }
+    if (commandExists("apt-get"))
+        return `sudo apt-get install -y ${pkg}`;
+    if (commandExists("dnf"))
+        return `sudo dnf install -y ${pkg}`;
+    if (commandExists("brew"))
+        return `brew install ${pkg}`;
+    if (commandExists("apk"))
+        return `apk add ${pkg}`;
+    return `echo "Please install ${pkg} manually"`;
+}
+/**
+ * Platform info for display.
+ */
+export function getPlatformSummary() {
+    const os = osPlatform();
+    if (isWSL)
+        return "WSL (Windows Subsystem for Linux)";
+    if (os === "win32")
+        return "Windows";
+    if (os === "darwin")
+        return "macOS";
+    return "Linux";
+}

package/dist/utils/smartArchive.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Smart archive creation.
+ *
+ * Auto-excludes heavy/non-essential directories (node_modules, .git, etc.)
+ * unless the user explicitly requests them. Checks disk space before archiving.
+ */
+export interface ArchiveOptions {
+    source: string;
+    destination?: string;
+    includeAll?: boolean;
+    excludes?: string[];
+}
+/**
+ * Smart archive: checks space, shows what will be excluded, asks before creating.
+ */
+export declare function smartArchive(options: ArchiveOptions): Promise<string>;

package/dist/utils/smartArchive.js

@@ -0,0 +1,172 @@
+/**
+ * Smart archive creation.
+ *
+ * Auto-excludes heavy/non-essential directories (node_modules, .git, etc.)
+ * unless the user explicitly requests them. Checks disk space before archiving.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, statSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { detectLocalPlatform } from "./platform.js";
+import { askForConfirmation } from "../policy/confirm.js";
+const execAsync = promisify(exec);
+const c = {
+    reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+    green: "\x1b[32m", yellow: "\x1b[33m", red: "\x1b[31m", cyan: "\x1b[36m",
+};
+/** Directories that are safe to exclude by default (regenerable/cached). */
+const DEFAULT_EXCLUDES = [
+    "node_modules",
+    ".git",
+    ".next",
+    ".nuxt",
+    "dist",
+    "build",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".env.local",
+    ".cache",
+    ".turbo",
+    "vendor", // PHP composer
+    "target", // Rust cargo
+    ".gradle",
+    ".idea",
+    ".vscode",
+    "*.pyc",
+    "*.o",
+    "*.class",
+    ".DS_Store",
+    "Thumbs.db",
+];
+/** Estimate the size of a directory (excluding default excludes). */
+async function estimateSize(source, excludes) {
+    const plat = detectLocalPlatform();
+    try {
+        // Total size
+        const { stdout: totalOut } = await execAsync(`du -sb "${source}" 2>/dev/null | cut -f1`, { timeout: 30_000 });
+        const totalBytes = parseInt(totalOut.trim()) || 0;
+        // Size of excluded dirs
+        let excludedBytes = 0;
+        for (const ex of excludes) {
+            if (ex.startsWith("*"))
+                continue; // skip glob patterns
+            const exPath = resolve(source, ex);
+            if (existsSync(exPath)) {
+                try {
+                    const { stdout } = await execAsync(`du -sb "${exPath}" 2>/dev/null | cut -f1`, { timeout: 10_000 });
+                    excludedBytes += parseInt(stdout.trim()) || 0;
+                }
+                catch { }
+            }
+        }
+        return {
+            totalGB: totalBytes / 1073741824,
+            excludedGB: excludedBytes / 1073741824,
+        };
+    }
+    catch {
+        return { totalGB: 0, excludedGB: 0 };
+    }
+}
+/** Check available disk space at a path. */
+async function getAvailableSpaceGB(path) {
+    try {
+        const { stdout } = await execAsync(`df -B1 "${path}" 2>/dev/null | tail -1 | awk '{print $4}'`, { timeout: 5000 });
+        return parseInt(stdout.trim()) / 1073741824;
+    }
+    catch {
+        return -1; // unknown
+    }
+}
+/**
+ * Smart archive: checks space, shows what will be excluded, asks before creating.
+ */
+export async function smartArchive(options) {
+    const source = resolve(options.source);
+    const lines = [];
+    if (!existsSync(source)) {
+        return `${c.red}✗ Source not found: ${source}${c.reset}`;
+    }
+    // Determine destination
+    const destName = options.destination || `${basename(source)}.tar.gz`;
+    const dest = resolve(destName.endsWith(".tar.gz") || destName.endsWith(".tgz") ? destName : destName + ".tar.gz");
+    // Determine exclusions
+    const excludes = options.includeAll ? [] : DEFAULT_EXCLUDES;
+    const foundExcludes = [];
+    // Check which excludable dirs actually exist in source
+    if (!options.includeAll) {
+        for (const ex of DEFAULT_EXCLUDES) {
+            if (ex.startsWith("*"))
+                continue;
+            const exPath = resolve(source, ex);
+            if (existsSync(exPath)) {
+                try {
+                    const stat = statSync(exPath);
+                    if (stat.isDirectory()) {
+                        const { stdout } = await execAsync(`du -sb "${exPath}" 2>/dev/null | cut -f1`, { timeout: 10_000 });
+                        const sizeGB = parseInt(stdout.trim()) / 1073741824;
+                        foundExcludes.push({ name: ex, sizeGB });
+                    }
+                }
+                catch { }
+            }
+        }
+    }
+    // Estimate sizes
+    const sizes = await estimateSize(source, options.includeAll ? [] : DEFAULT_EXCLUDES.filter(e => !e.startsWith("*")));
+    const archiveEstimateGB = (sizes.totalGB - sizes.excludedGB) * 0.3; // rough compression ratio
+    const availableGB = await getAvailableSpaceGB(resolve(dest, ".."));
+    lines.push(`\n${c.bold}${c.cyan}── Smart Archive ──${c.reset}\n`);
+    lines.push(`  Source:      ${c.bold}${source}${c.reset}`);
+    lines.push(`  Destination: ${c.bold}${dest}${c.reset}`);
+    lines.push(`  Source size: ${c.bold}${sizes.totalGB.toFixed(2)} GB${c.reset}`);
+    if (foundExcludes.length > 0) {
+        const totalExcluded = foundExcludes.reduce((s, e) => s + e.sizeGB, 0);
+        lines.push(`\n  ${c.bold}Auto-excluding (${totalExcluded.toFixed(2)} GB saved):${c.reset}`);
+        for (const ex of foundExcludes.sort((a, b) => b.sizeGB - a.sizeGB)) {
+            const sizeStr = ex.sizeGB >= 1 ? `${ex.sizeGB.toFixed(2)} GB` : `${(ex.sizeGB * 1024).toFixed(0)} MB`;
+            lines.push(`    ${c.yellow}${sizeStr.padStart(10)}${c.reset}  ${ex.name}/`);
+        }
+        lines.push(`\n  ${c.dim}To include everything: add "include all" or "with node_modules"${c.reset}`);
+    }
+    lines.push(`\n  Estimated archive: ${c.bold}~${archiveEstimateGB.toFixed(2)} GB${c.reset} ${c.dim}(compressed)${c.reset}`);
+    // Space check
+    if (availableGB >= 0) {
+        lines.push(`  Available space:  ${c.bold}${availableGB.toFixed(2)} GB${c.reset}`);
+        if (archiveEstimateGB > availableGB * 0.9) {
+            lines.push(`\n  ${c.red}${c.bold}⚠ NOT ENOUGH SPACE!${c.reset} Archive (~${archiveEstimateGB.toFixed(2)} GB) may exceed available space (${availableGB.toFixed(2)} GB).`);
+            lines.push(`  ${c.yellow}Free up space first: notoken "free up space"${c.reset}`);
+            return lines.join("\n");
+        }
+        else if (archiveEstimateGB > availableGB * 0.5) {
+            lines.push(`  ${c.yellow}⚠ This will use ${Math.round((archiveEstimateGB / availableGB) * 100)}% of remaining space.${c.reset}`);
+        }
+        else {
+            lines.push(`  ${c.green}✓ Plenty of space.${c.reset}`);
+        }
+    }
+    console.log(lines.join("\n"));
+    // Confirm
+    const ok = await askForConfirmation(`\nCreate archive?`);
+    if (!ok) {
+        return `${c.dim}Cancelled.${c.reset}`;
+    }
+    // Build tar command
+    const excludeFlags = excludes.map((e) => `--exclude='${e}'`).join(" ");
+    const tarCmd = `tar -czf "${dest}" ${excludeFlags} -C "${resolve(source, "..")}" "${basename(source)}"`;
+    console.log(`\n${c.dim}→ ${tarCmd}${c.reset}`);
+    try {
+        await execAsync(tarCmd, { timeout: 600_000 }); // 10 min timeout for large archives
+        // Show result
+        const stat = statSync(dest);
+        const resultGB = stat.size / 1073741824;
+        const sizeStr = resultGB >= 1 ? `${resultGB.toFixed(2)} GB` : `${(resultGB * 1024).toFixed(0)} MB`;
+        return `\n${c.green}${c.bold}✓ Archive created: ${dest}${c.reset}\n  Size: ${c.bold}${sizeStr}${c.reset}`;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `\n${c.red}✗ Archive failed: ${msg.split("\n")[0]}${c.reset}`;
+    }
+}

package/dist/utils/smartRetry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Smart Retry — analyzes command failures and suggests fixes.
+ *
+ * When a command fails, this module inspects the error message,
+ * identifies common patterns, and suggests an actionable fix
+ * that can be registered as a pending action.
+ */
+export interface FailureAnalysis {
+    /** Whether this failure has an automated fix */
+    canFix: boolean;
+    /** Short human-friendly suggestion shown to the user */
+    suggestion: string;
+    /** The command/intent text to execute as the fix */
+    fixCommand: string;
+    /** Why this fix should help */
+    explanation: string;
+}
+/**
+ * Analyze a command failure and suggest a fix.
+ *
+ * @param intent  - The intent name or raw text that failed
+ * @param error   - The error (string or Error)
+ * @param fields  - Parsed intent fields (service name, tool, path, etc.)
+ * @returns A FailureAnalysis if a known pattern matches, or null
+ */
+export declare function analyzeFailure(intent: string, error: string | Error, fields?: Record<string, unknown>): FailureAnalysis | null;

package/dist/utils/smartRetry.js

@@ -0,0 +1,114 @@
+/**
+ * Smart Retry — analyzes command failures and suggests fixes.
+ *
+ * When a command fails, this module inspects the error message,
+ * identifies common patterns, and suggests an actionable fix
+ * that can be registered as a pending action.
+ */
+const patterns = [
+    {
+        pattern: /command not found[:\s]*(\S+)|(\S+):\s*not found|'(\S+)' is not recognized/i,
+        build: (m) => {
+            const tool = (m[1] || m[2] || m[3]).replace(/['"]/g, "");
+            return {
+                canFix: true,
+                suggestion: `${tool} is not installed. Install it?`,
+                fixCommand: `install ${tool}`,
+                explanation: `The command "${tool}" was not found on this system. Installing it should fix the issue.`,
+            };
+        },
+    },
+    {
+        pattern: /connection refused|ECONNREFUSED/i,
+        build: (_m, _intent, fields) => {
+            const service = fields.service || fields.tool || "the service";
+            return {
+                canFix: true,
+                suggestion: `Can't connect — ${service} may not be running. Start it?`,
+                fixCommand: `start ${service}`,
+                explanation: `Connection was refused, which usually means the target service is not running.`,
+            };
+        },
+    },
+    {
+        pattern: /permission denied|EACCES|access denied/i,
+        build: (_m, intent) => ({
+            canFix: true,
+            suggestion: "Permission denied. Retry with elevated privileges?",
+            fixCommand: `sudo ${intent}`,
+            explanation: "The command failed due to insufficient permissions. Running with sudo may resolve it.",
+        }),
+    },
+    {
+        pattern: /no such file or directory[:\s]*(.+)|ENOENT[:\s]*(.+)/i,
+        build: (m) => {
+            const raw = (m[1] || m[2] || "").trim().replace(/['"]/g, "");
+            const filename = raw.split("/").pop() || raw;
+            return {
+                canFix: true,
+                suggestion: `File not found: ${filename}. Search for it?`,
+                fixCommand: `find ${filename}`,
+                explanation: `The path "${raw}" does not exist. A search may locate the correct path.`,
+            };
+        },
+    },
+    {
+        pattern: /address already in use|port.*already in use|EADDRINUSE/i,
+        build: () => ({
+            canFix: true,
+            suggestion: "Port already in use. Check what's using it?",
+            fixCommand: "check ports",
+            explanation: "Another process is occupying the required port.",
+        }),
+    },
+    {
+        pattern: /no space left|disk full|ENOSPC/i,
+        build: () => ({
+            canFix: true,
+            suggestion: "Disk is full. Free up space?",
+            fixCommand: "free up space",
+            explanation: "The disk has no remaining space. Clearing caches or temp files may help.",
+        }),
+    },
+    {
+        pattern: /timed?\s*out|ETIMEDOUT|ESOCKETTIMEDOUT/i,
+        build: (_m, intent) => ({
+            canFix: true,
+            suggestion: "Command timed out. Try again?",
+            fixCommand: intent,
+            explanation: "The operation exceeded its time limit. A retry may succeed if the issue was transient.",
+        }),
+    },
+    {
+        pattern: /ECONNREFUSED/i,
+        build: (_m, _intent, fields) => {
+            const service = fields.service || fields.tool || "the service";
+            return {
+                canFix: true,
+                suggestion: `Can't connect to ${service}. Check if it's running?`,
+                fixCommand: `check status ${service}`,
+                explanation: "The connection was actively refused — the target service may be down.",
+            };
+        },
+    },
+];
+/**
+ * Analyze a command failure and suggest a fix.
+ *
+ * @param intent  - The intent name or raw text that failed
+ * @param error   - The error (string or Error)
+ * @param fields  - Parsed intent fields (service name, tool, path, etc.)
+ * @returns A FailureAnalysis if a known pattern matches, or null
+ */
+export function analyzeFailure(intent, error, fields = {}) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message)
+        return null;
+    for (const { pattern, build } of patterns) {
+        const match = message.match(pattern);
+        if (match) {
+            return build(match, intent, fields);
+        }
+    }
+    return null;
+}

package/dist/utils/snippets.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Snippets — save, list, read, and run code snippets.
+ *
+ * Each snippet is a file under ~/.notoken/snippets/<name>.<ext>
+ */
+/** Save a code snippet. */
+export declare function saveSnippet(name: string, code: string, language?: string): void;
+/** List saved snippets. */
+export declare function listSnippets(): string;
+/** Read a snippet by name (matches any extension). */
+export declare function getSnippet(name: string): string | undefined;
+/** Run a snippet, auto-detecting interpreter from extension. */
+export declare function runSnippet(name: string): string;

package/dist/utils/snippets.js

@@ -0,0 +1,53 @@
+/**
+ * Snippets — save, list, read, and run code snippets.
+ *
+ * Each snippet is a file under ~/.notoken/snippets/<name>.<ext>
+ */
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
+import { resolve, extname, basename } from "node:path";
+import { execSync } from "node:child_process";
+const home = process.env.HOME ?? process.env.USERPROFILE ?? ".";
+const dir = resolve(home, ".notoken", "snippets");
+function ensureDir() { mkdirSync(dir, { recursive: true }); }
+function extFor(lang) {
+    if (!lang)
+        return ".sh";
+    const map = { bash: ".sh", sh: ".sh", node: ".js", javascript: ".js", python: ".py", ts: ".ts", typescript: ".ts" };
+    return map[lang.toLowerCase()] ?? `.${lang}`;
+}
+/** Save a code snippet. */
+export function saveSnippet(name, code, language) {
+    ensureDir();
+    writeFileSync(resolve(dir, `${name}${extFor(language)}`), code, "utf-8");
+}
+/** List saved snippets. */
+export function listSnippets() {
+    ensureDir();
+    const files = readdirSync(dir);
+    if (files.length === 0)
+        return "No snippets saved.";
+    return files.map((f) => `  ${basename(f, extname(f))}  (${extname(f).slice(1)})`).join("\n");
+}
+/** Read a snippet by name (matches any extension). */
+export function getSnippet(name) {
+    ensureDir();
+    const hit = readdirSync(dir).find((f) => basename(f, extname(f)) === name);
+    return hit ? readFileSync(resolve(dir, hit), "utf-8") : undefined;
+}
+/** Run a snippet, auto-detecting interpreter from extension. */
+export function runSnippet(name) {
+    ensureDir();
+    const hit = readdirSync(dir).find((f) => basename(f, extname(f)) === name);
+    if (!hit)
+        return `Snippet "${name}" not found.`;
+    const fp = resolve(dir, hit);
+    const ext = extname(hit);
+    const runners = { ".sh": "bash", ".js": "node", ".py": "python3", ".ts": "npx tsx" };
+    const runner = runners[ext] ?? "bash";
+    try {
+        return execSync(`${runner} "${fp}"`, { encoding: "utf-8", timeout: 30_000 }).trim();
+    }
+    catch (e) {
+        return `Error: ${e.message?.split("\n")[0] ?? e}`;
+    }
+}