ysagc-agent 0.3.0 → 0.4.0

package/dist/cli.js

@@ -0,0 +1,267 @@
+#!/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 });
+exports.runSelfTest = runSelfTest;
+const commander_1 = require("commander");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const agent_1 = require("./agent");
+const config_1 = require("./config");
+const logger_1 = require("./logger");
+const path_utils_1 = require("./path-utils");
+const security_1 = require("./security");
+const tools_1 = require("./tools");
+const program = new commander_1.Command();
+program
+    .name('ysagc-agent')
+    .description('Local execution agent for ysagc (state-agnostic, safety-bounded)')
+    .version(agent_1.AGENT_VERSION)
+    .option('--server <url>', 'platform WebSocket URL for the agent channel')
+    .option('--token <token>', 'device/agent auth token')
+    .option('--device-id <id>', 'stable device identifier')
+    .option('--root <dir>', 'authorisation root for all file operations')
+    .option('--mode <mode>', 'permission mode: supervise | smart | auto', 'smart')
+    .option('--web', 'enable the local web_search (stub) tool')
+    .option('--timeout <ms>', 'command timeout in milliseconds')
+    .option('--max-bytes <n>', 'per-stream output cap in bytes')
+    .option('--log-level <level>', 'silent | error | warn | info | debug', 'info')
+    .option('--selftest', 'run a local self-test and exit');
+program.parse(process.argv);
+const opts = program.opts();
+function toInt(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+function asStr(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function shutdown(handle, signal) {
+    // eslint-disable-next-line no-console
+    console.log(`\n${signal} received; shutting down`);
+    handle?.stop();
+    process.exit(0);
+}
+async function main() {
+    if (opts.selftest) {
+        const results = await runSelfTest();
+        runAndPrintSelfTest(results);
+        return;
+    }
+    try {
+        const config = (0, config_1.loadConfig)({
+            server: asStr(opts.server),
+            token: asStr(opts.token),
+            deviceId: asStr(opts.deviceId),
+            root: asStr(opts.root),
+            mode: asStr(opts.mode),
+            web: opts.web === true ? true : undefined,
+            timeoutMs: toInt(opts.timeout),
+            maxBytes: toInt(opts.maxBytes),
+            logLevel: asStr(opts.logLevel),
+        });
+        const log = new logger_1.Logger({ level: config.logLevel, name: 'cli' });
+        log.info('agent config', (0, config_1.describeConfig)(config));
+        const handle = (0, agent_1.startAgent)(config);
+        process.on('SIGINT', () => shutdown(handle, 'SIGINT'));
+        process.on('SIGTERM', () => shutdown(handle, 'SIGTERM'));
+    }
+    catch (err) {
+        if (err instanceof config_1.ConfigError) {
+            // eslint-disable-next-line no-console
+            console.error(`\nConfiguration error: ${err.message}\n`);
+            // eslint-disable-next-line no-console
+            console.error('Run `ysagc-agent --help` for usage, or set the matching environment variables.');
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+function runAndPrintSelfTest(results) {
+    let failed = 0;
+    for (const r of results) {
+        const status = r.ok ? 'PASS' : 'FAIL';
+        const detail = [r.details, r.error].filter(Boolean).join(' — ');
+        // eslint-disable-next-line no-console
+        console.log(`[${status}] ${r.name}${detail ? ` — ${detail}` : ''}`);
+        if (!r.ok)
+            failed += 1;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`\nSelf-test: ${results.length - failed}/${results.length} passed.`);
+    process.exit(failed === 0 ? 0 : 1);
+}
+/**
+ * Run a local smoke test of path safety, danger-command detection, sensitive
+ * path detection, secret masking and the tool registry. Returns structured
+ * PASS/FAIL results; the CLI prints them and picks the exit code.
+ */
+async function runSelfTest() {
+    const results = [];
+    const add = (name, ok, details, error) => {
+        results.push({ name, ok, details, error });
+    };
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ysagc-test-'));
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'ysagc-outside-'));
+    const sync = (name, fn) => {
+        try {
+            add(name, fn());
+        }
+        catch (err) {
+            add(name, false, undefined, err instanceof Error ? err.message : String(err));
+        }
+    };
+    const asyncCheck = async (name, fn) => {
+        try {
+            add(name, await fn());
+        }
+        catch (err) {
+            add(name, false, undefined, err instanceof Error ? err.message : String(err));
+        }
+    };
+    try {
+        // --- path safety ------------------------------------------------------
+        sync('canonicalize resolves ..', () => {
+            const cwd = dir;
+            const resolved = (0, path_utils_1.canonicalize)('sub/dir/../file.txt', cwd);
+            return resolved === path.resolve(dir, 'sub', 'file.txt');
+        });
+        sync('isWithinRoot: child inside root', () => (0, path_utils_1.isWithinRoot)(dir, path.join(dir, 'a', 'b')));
+        sync('isWithinRoot: .. escape rejected', () => !(0, path_utils_1.isWithinRoot)(dir, path.join(dir, '..', 'escape')));
+        sync('isWithinRoot: equal root rejected when writing', () => !(0, path_utils_1.isWithinRoot)(dir, dir));
+        sync('isWithinRoot: equal root allowed when reading', () => (0, path_utils_1.isWithinRoot)(dir, dir, { allowEqual: true }));
+        sync('windows reserved name detected', () => (0, path_utils_1.isWindowsReservedName)('CON'));
+        sync('non-reserved name ok', () => !(0, path_utils_1.isWindowsReservedName)('hello'));
+        sync('symlink escape rejected', () => {
+            try {
+                const link = path.join(dir, 'linkdir');
+                fs.symlinkSync(outside, link, 'junction');
+                return !(0, path_utils_1.isWithinRoot)(dir, path.join(link, 'file.txt'));
+            }
+            catch {
+                return true; // skipped when symlinks are unsupported (e.g. unprivileged Windows)
+            }
+        });
+        // --- danger detection -------------------------------------------------
+        const dangerCases = [
+            ['rm -rf /tmp/foo', true],
+            ['sudo apt-get update', true],
+            ['git reset --hard', true],
+            ['format d:', true],
+            ['echo hello world', false],
+            ['ls -la', false],
+            ['cat package.json', false],
+        ];
+        for (const [cmd, shouldBlock] of dangerCases) {
+            const a = (0, security_1.isDangerCommand)(cmd);
+            add(`danger: ${cmd}`, a.danger === shouldBlock, `severity=${a.severity}`);
+        }
+        // --- sensitive path ---------------------------------------------------
+        sync('sensitive /etc/passwd blocked', () => (0, security_1.isSensitivePath)('/etc/passwd'));
+        sync('sensitive .env blocked', () => (0, security_1.isSensitivePath)('/some/root/.env'));
+        sync('normal file allowed', () => !(0, security_1.isSensitivePath)(path.join(dir, 'x.txt')));
+        // --- secret masking ---------------------------------------------------
+        sync('maskSecrets redacts sk- keys', () => {
+            const masked = (0, security_1.maskSecrets)('key=sk-abcdefghijklmnopqrstuvwxyz123456 extra');
+            return !/sk-[a-f0-9]{6,}/i.test(masked) && masked.includes('***');
+        });
+        sync('maskSecrets redacts bearer/JWT', () => {
+            const masked = (0, security_1.maskSecrets)('Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.sig');
+            return !masked.includes('eyJhbGci') && masked.includes('***');
+        });
+        // --- tools ------------------------------------------------------------
+        const logger = new logger_1.Logger({ level: 'error', name: 'selftest' });
+        const registry = (0, tools_1.createToolRegistry)({
+            root: dir,
+            mode: 'smart',
+            webEnabled: false,
+            timeoutMs: 10000,
+            maxBytes: 8000,
+            logger,
+        });
+        await asyncCheck('write_file', async () => {
+            const w = await registry.dispatch('write_file', { path: 'hello.txt', content: 'hello world' });
+            return w.ok && w.result?.bytesWritten === 11;
+        });
+        await asyncCheck('read_file', async () => {
+            const r = await registry.dispatch('read_file', { path: 'hello.txt', maxBytes: 100 });
+            return r.ok && String(r.result?.content ?? '').includes('hello world');
+        });
+        await asyncCheck('list_dir', async () => {
+            const l = await registry.dispatch('list_dir', { path: '.', depth: 1 });
+            const entries = l.result?.entries ?? [];
+            return l.ok && entries.some((entry) => entry.name === 'hello.txt');
+        });
+        await asyncCheck('edit_file', async () => {
+            const e = await registry.dispatch('edit_file', { path: 'hello.txt', oldText: 'world', newText: 'there' });
+            return e.ok && e.result?.replacements === 1;
+        });
+        await asyncCheck('write_file rejects outside root', async () => {
+            const out = await registry.dispatch('write_file', { path: '../escape.txt', content: 'nope' });
+            return !out.ok;
+        });
+        await asyncCheck('generate', async () => {
+            const g = await registry.dispatch('generate', { template: 'node', name: 'myproj' });
+            const files = g.result?.files ?? [];
+            return g.ok && files.some((f) => f.path.includes('myproj/package.json'));
+        });
+        await asyncCheck('run_command echo', async () => {
+            const c = await registry.dispatch('run_command', { cmd: 'echo hello from selftest' });
+            const stdout = String(c.result?.stdout ?? '');
+            return c.ok && stdout.includes('hello from selftest');
+        });
+    }
+    finally {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            fs.rmSync(outside, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    return results;
+}
+if (require.main === module) {
+    main().catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error(`Fatal error: ${err instanceof Error ? err.message : String(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":"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"}

package/dist/config.d.ts

@@ -0,0 +1,52 @@
+import { Logger, type LogLevel } from './logger';
+export type PermissionMode = 'supervise' | 'smart' | 'auto';
+export interface AgentConfig {
+    /** Platform WebSocket URL for the agent channel. */
+    server: string;
+    /** Device/agent auth token presented in the hello frame. */
+    token: string;
+    /** Stable device identifier sent in the hello frame. */
+    deviceId: string;
+    /** Authorisation root; every file operation must stay inside it. */
+    root: string;
+    /** Permission policy for shell commands. */
+    mode: PermissionMode;
+    /** Whether the local web_search tool is enabled. */
+    web: boolean;
+    /** Command timeout in milliseconds. */
+    timeoutMs: number;
+    /** Per-stream output cap in bytes before it is truncated/spilled. */
+    maxBytes: number;
+    /** Log verbosity. */
+    logLevel: LogLevel;
+    /** Passed in the hello frame to let the platform route the agent. */
+    platform: string;
+}
+export interface ConfigOverrides {
+    server?: string;
+    token?: string;
+    deviceId?: string;
+    root?: string;
+    mode?: string;
+    web?: boolean;
+    timeoutMs?: number;
+    maxBytes?: number;
+    logLevel?: string;
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve an {@link AgentConfig} from defaults, environment variables and CLI
+ * overrides (in that order of precedence). Environment variables are read from
+ * WS_URL / YSAGC_TOKEN / DEVICE_ID / WORKSPACE_ROOT / PERMISSION_MODE /
+ * YSAGC_WEB / YSAGC_TIMEOUT / YSAGC_MAX_BYTES / YSAGC_LOG_LEVEL.
+ */
+export declare function loadConfig(overrides?: ConfigOverrides): AgentConfig;
+/** Validate the subset of config required to start the agent. Throws a
+ * {@link ConfigError} with a friendly message for missing values. */
+export declare function validateConfig(config: AgentConfig): void;
+/** Build a logger from a config. */
+export declare function loggerFromConfig(config: AgentConfig): Logger;
+export declare function describeConfig(config: AgentConfig): Record<string, unknown>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAI5D,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,cAAc,CAAC;IACrB,oDAAoD;IACpD,GAAG,EAAE,OAAO,CAAC;IACb,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AA+CD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,GAAE,eAAoB,GAAG,WAAW,CA0BvE;AAiBD;qEACqE;AACrE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAYxD;AAED,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE5D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa3E"}

package/dist/config.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+exports.loadConfig = loadConfig;
+exports.validateConfig = validateConfig;
+exports.loggerFromConfig = loggerFromConfig;
+exports.describeConfig = describeConfig;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const logger_1 = require("./logger");
+const VALID_MODES = new Set(['supervise', 'smart', 'auto']);
+class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+exports.ConfigError = ConfigError;
+const DEFAULT_TIMEOUT_MS = 120000;
+const DEFAULT_MAX_BYTES = 64000;
+function readEnv(name) {
+    const v = process.env[name];
+    return v && v.trim() !== '' ? v.trim() : undefined;
+}
+function parseMode(value, fallback) {
+    if (!value)
+        return fallback;
+    const v = value.toLowerCase();
+    if (VALID_MODES.has(v))
+        return v;
+    throw new ConfigError(`Invalid permission mode "${value}". Expected one of: supervise, smart, auto.`);
+}
+function parsePosInt(value, fallback, name) {
+    if (!value)
+        return fallback;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new ConfigError(`Invalid ${name}: "${value}" must be a positive integer.`);
+    }
+    return Math.floor(n);
+}
+function parseLogLevel(value) {
+    if (!value)
+        return 'info';
+    const v = value.toLowerCase();
+    if (v === 'silent' || v === 'error' || v === 'warn' || v === 'info' || v === 'debug') {
+        return v;
+    }
+    throw new ConfigError(`Invalid log level "${value}". Expected: silent, error, warn, info, debug.`);
+}
+function resolveRoot(raw) {
+    if (!raw)
+        return process.cwd();
+    // Expand a leading ~ to the home directory at configuration time only; the
+    // path-utils canonicaliser intentionally does not expand `~`.
+    const t = raw.trim();
+    if (t === '~')
+        return node_os_1.default.homedir();
+    if (t.startsWith('~/') || t.startsWith('~\\'))
+        return node_path_1.default.join(node_os_1.default.homedir(), t.slice(2));
+    return node_path_1.default.resolve(t);
+}
+/**
+ * Resolve an {@link AgentConfig} from defaults, environment variables and CLI
+ * overrides (in that order of precedence). Environment variables are read from
+ * WS_URL / YSAGC_TOKEN / DEVICE_ID / WORKSPACE_ROOT / PERMISSION_MODE /
+ * YSAGC_WEB / YSAGC_TIMEOUT / YSAGC_MAX_BYTES / YSAGC_LOG_LEVEL.
+ */
+function loadConfig(overrides = {}) {
+    const mode = parseMode(overrides.mode ?? readEnv('PERMISSION_MODE'), 'smart');
+    return {
+        server: overrides.server ?? readEnv('WS_URL') ?? '',
+        token: overrides.token ?? readEnv('YSAGC_TOKEN') ?? '',
+        deviceId: overrides.deviceId ??
+            readEnv('DEVICE_ID') ??
+            defaultDeviceId(),
+        root: resolveRoot(overrides.root ?? readEnv('WORKSPACE_ROOT')),
+        mode,
+        web: overrides.web ?? truthy(readEnv('YSAGC_WEB')),
+        timeoutMs: parsePosInt(overrides.timeoutMs != null ? String(overrides.timeoutMs) : readEnv('YSAGC_TIMEOUT'), DEFAULT_TIMEOUT_MS, 'timeout'),
+        maxBytes: parsePosInt(overrides.maxBytes != null ? String(overrides.maxBytes) : readEnv('YSAGC_MAX_BYTES'), DEFAULT_MAX_BYTES, 'max-bytes'),
+        logLevel: parseLogLevel(overrides.logLevel ?? readEnv('YSAGC_LOG_LEVEL')),
+        platform: 'node',
+    };
+}
+function truthy(value) {
+    if (!value)
+        return false;
+    return /^(1|true|yes|on)$/i.test(value);
+}
+/** A stable-ish default device id derived from the hostname. */
+function defaultDeviceId() {
+    try {
+        const host = node_os_1.default.hostname();
+        return `agent-${host || 'unknown'}-${process.pid}`;
+    }
+    catch {
+        return `agent-${process.pid}`;
+    }
+}
+/** Validate the subset of config required to start the agent. Throws a
+ * {@link ConfigError} with a friendly message for missing values. */
+function validateConfig(config) {
+    if (!config.server || config.server.trim() === '') {
+        throw new ConfigError('Missing platform WebSocket URL. Pass --server <url> or set WS_URL.');
+    }
+    if (!config.token || config.token.trim() === '') {
+        throw new ConfigError('Missing auth token. Pass --token <token> or set YSAGC_TOKEN.');
+    }
+    if (!config.deviceId || config.deviceId.trim() === '') {
+        throw new ConfigError('Missing device id. Pass --device-id <id> or set DEVICE_ID.');
+    }
+}
+/** Build a logger from a config. */
+function loggerFromConfig(config) {
+    return new logger_1.Logger({ level: config.logLevel, name: 'ysagc-agent' });
+}
+function describeConfig(config) {
+    return {
+        server: config.server,
+        deviceId: config.deviceId,
+        root: config.root,
+        mode: config.mode,
+        web: config.web,
+        timeoutMs: config.timeoutMs,
+        maxBytes: config.maxBytes,
+        logLevel: config.logLevel,
+        platform: config.platform,
+        // token deliberately omitted — never log it.
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/executor.d.ts

@@ -0,0 +1,46 @@
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+    /** True when the process was killed because the timeout elapsed. */
+    timedOut: boolean;
+    /** True when a stream was truncated to the max-bytes cap. */
+    truncated: boolean;
+    /** Path to a temp file holding the full stdout when truncated. */
+    stdoutFile?: string;
+    /** Path to a temp file holding the full stderr when truncated. */
+    stderrFile?: string;
+}
+export interface RunCommandOptions {
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+    /** Extra environment variables (merged over the default, sanitised env). */
+    env?: NodeJS.ProcessEnv;
+    /** Abort signal; aborting kills the process tree. */
+    signal?: AbortSignal;
+    /** Force shell mode (default: auto-detect per platform / metacharacters). */
+    shell?: boolean;
+}
+/**
+ * Split a simple command string into argv (respects single/double quotes and
+ * backslash escape). Do not use for commands with shell metacharacters.
+ */
+export declare function tokenize(input: string): string[];
+/** Decide whether a command must run through a shell. On Windows the shell is
+ * always used because many common commands are cmd builtins. */
+export declare function shouldUseShell(command: string, override?: boolean): boolean;
+/** Build a sanitised env so agent/platform credentials never reach child
+ * processes. Essential environment (PATH, HOME, LANG, ...) is preserved. */
+export declare function sanitizeEnv(base: NodeJS.ProcessEnv, extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Run a command, capturing stdout/stderr (spilled to a temp file when it
+ * exceeds `maxBytes`), enforcing a timeout, and killing the process tree on
+ * timeout or abort. Non-zero exit codes are returned, not thrown. Output is
+ * captured through file-descriptor redirection rather than a pipe so it is
+ * robust on constrained platforms and for very large outputs.
+ */
+export declare function runCommand(opts: RunCommandOptions): Promise<CommandResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAoCD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAsChD;AAED;gEACgE;AAChE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAI3E;AAED;4EAC4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAiBjG;AA2DD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkM1E"}