@melra/terminal-runtime 0.3.0-alpha.10

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,46 @@
+# @melra/terminal-runtime
+
+Bounded process execution for [MELRA](https://github.com/XAGI-Lab/melra):
+one-shot `run`, plus `start`/`status`/`output`/`stop` for longer-lived processes.
+
+```bash
+npm install @melra/terminal-runtime
+```
+
+```ts
+import { TerminalOperationSchema } from "@melra/protocol";
+import { TerminalRuntime } from "@melra/terminal-runtime";
+
+const terminal = await TerminalRuntime.create({ root: workspaceRoot });
+const result = await terminal.execute(
+  TerminalOperationSchema.parse({
+    kind: "terminal",
+    action: "run",
+    command: "git",
+    args: ["status", "--porcelain"],
+  }),
+);
+```
+
+Commands are spawned without a shell. Arguments are passed as an array, never
+interpolated into a command line, so a value containing `;` or `$(...)` is an
+argument rather than a second command. The working directory stays inside
+`root`, and only environment variables you name in `allowedEnvironment` are
+passed through.
+
+Output is captured up to the operation's `maxOutputChars` and flagged
+`truncated` past it, and every process runs under an `AbortSignal` so a duration
+budget actually stops work rather than just reporting a timeout.
+
+`redactTerminalOutput` strips credential-shaped values from captured output
+before it is persisted — tokens, `Authorization` headers, and connection strings
+show up in stdout more often than anyone expects.
+
+Allowlisting decides which commands may run at all, and that lives in
+[`@melra/policy-core`](https://www.npmjs.com/package/@melra/policy-core), not
+here.
+
+Requires Node.js 22 or newer. Full documentation:
+[github.com/XAGI-Lab/melra](https://github.com/XAGI-Lab/melra)
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import type { TerminalOperation } from "@melra/protocol";
+export { quoteForCmd, resolveCommand } from "./resolve-command.js";
+export type { ResolvedCommand } from "./resolve-command.js";
+export interface TerminalRuntimeOptions {
+    root: string;
+    allowedEnvironment?: string[];
+    baseEnvironment?: NodeJS.ProcessEnv;
+}
+export declare function redactTerminalOutput(value: string): string;
+export declare class TerminalRuntime {
+    readonly root: string;
+    readonly allowedEnvironment: Set<string>;
+    readonly baseEnvironment: NodeJS.ProcessEnv;
+    private readonly jobs;
+    private constructor();
+    static create(options: TerminalRuntimeOptions): Promise<TerminalRuntime>;
+    private resolveCwd;
+    private prepare;
+    private runForeground;
+    private startBackground;
+    /**
+     * Answers a prompt on a running job's stdin.
+     *
+     * This is a pipe, not a terminal. A program that asks `isatty` still sees a
+     * non-interactive session and may keep its non-interactive behaviour — reading
+     * a password without echo is the usual one, and it will not work here. A real
+     * PTY needs a native addon; this covers the case that does not.
+     *
+     * ponytail: pipe-only. Add `node-pty` behind an optional dependency if a task
+     * genuinely needs a program that refuses to run without a tty.
+     */
+    private sendInput;
+    private job;
+    private jobResult;
+    execute(operation: TerminalOperation, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    close(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACrC;AAcD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AA+CD,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,UAAU,CAAC;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoC;IAEzD,OAAO;WAWM,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;YAIhE,UAAU;YAQV,OAAO;YA8CP,aAAa;YA+Db,eAAe;IAgF7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS;IA0BjB,OAAO,CAAC,GAAG;IASX,OAAO,CAAC,SAAS;IAuBX,OAAO,CACX,SAAS,EAAE,iBAAiB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAoBnC,KAAK,IAAI,IAAI;CAOd"}

package/dist/index.js

@@ -0,0 +1,331 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { resolveCommand } from "./resolve-command.js";
+export { quoteForCmd, resolveCommand } from "./resolve-command.js";
+const SECRET_PATTERNS = [
+    /\bgh[opurs]_[A-Za-z0-9]{20,}\b/g,
+    /\b(?:sk|pk|api)[-_][a-z0-9_-]{16,}\b/gi,
+    /\bBearer\s+[A-Za-z0-9._~+/-]+=*\b/gi,
+    /\b(password|passwd|secret)\s*[:=]\s*\S+/gi,
+];
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+export function redactTerminalOutput(value) {
+    return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED]"), value);
+}
+/**
+ * `spawn` reports a missing program as a bare `ENOENT` naming only the syscall,
+ * which reads as an internal fault rather than "that program is not installed".
+ */
+function describeSpawnError(error, command) {
+    const code = error?.code;
+    if (code === "ENOENT")
+        return new Error(`terminal_command_not_found:${command}`);
+    if (code === "EACCES")
+        return new Error(`terminal_command_not_executable:${command}`);
+    return error instanceof Error ? error : new Error(String(error));
+}
+export class TerminalRuntime {
+    root;
+    allowedEnvironment;
+    baseEnvironment;
+    jobs = new Map();
+    constructor(options, root) {
+        this.root = root;
+        this.allowedEnvironment = new Set(options.allowedEnvironment ?? ["CI", "LANG", "LC_ALL", "NO_COLOR", "TERM"]);
+        this.baseEnvironment = options.baseEnvironment ?? process.env;
+    }
+    static async create(options) {
+        return new TerminalRuntime(options, await realpath(options.root));
+    }
+    async resolveCwd(cwd) {
+        const candidate = resolve(this.root, cwd ?? ".");
+        if (!inside(this.root, candidate))
+            throw new Error("cwd_outside_workspace");
+        const actual = await realpath(candidate);
+        if (!inside(this.root, actual))
+            throw new Error("cwd_outside_workspace");
+        return actual;
+    }
+    async prepare(operation) {
+        if (operation.command === undefined) {
+            throw new Error(`terminal_${operation.action}_requires_command`);
+        }
+        if (operation.command.includes("\0") || operation.args.some((arg) => arg.includes("\0"))) {
+            throw new Error("terminal_input_contains_null");
+        }
+        const cwd = await this.resolveCwd(operation.cwd);
+        const environment = {};
+        for (const name of ["PATH", "PATHEXT", "SYSTEMROOT", "WINDIR", "COMSPEC"]) {
+            if (this.baseEnvironment[name] !== undefined) {
+                environment[name] = this.baseEnvironment[name];
+            }
+        }
+        for (const name of this.allowedEnvironment) {
+            if (this.baseEnvironment[name] !== undefined) {
+                environment[name] = this.baseEnvironment[name];
+            }
+        }
+        for (const [name, value] of Object.entries(operation.env ?? {})) {
+            if (!this.allowedEnvironment.has(name)) {
+                throw new Error(`environment_variable_not_allowed:${name}`);
+            }
+            environment[name] = value;
+        }
+        const resolved = await resolveCommand(operation.command, operation.args, {
+            cwd,
+            path: environment["PATH"] ?? environment["Path"],
+            pathExt: environment["PATHEXT"],
+            comspec: this.baseEnvironment["COMSPEC"],
+        });
+        return {
+            command: operation.command,
+            args: operation.args,
+            file: resolved.file,
+            spawnArgs: resolved.args,
+            windowsVerbatimArguments: resolved.windowsVerbatimArguments,
+            executable: resolved.executable,
+            cwd,
+            environment,
+            timeoutMs: operation.timeoutMs,
+            maxOutputChars: operation.maxOutputChars,
+            interactive: operation.interactive,
+        };
+    }
+    async runForeground(prepared, signal) {
+        return await new Promise((resolvePromise, reject) => {
+            const child = spawn(prepared.file, prepared.spawnArgs, {
+                cwd: prepared.cwd,
+                env: prepared.environment,
+                shell: false,
+                windowsHide: true,
+                windowsVerbatimArguments: prepared.windowsVerbatimArguments,
+                stdio: ["ignore", "pipe", "pipe"],
+                signal,
+            });
+            let stdout = "";
+            let stderr = "";
+            let truncated = false;
+            let timedOut = false;
+            const append = (current, chunk) => {
+                const next = current + chunk.toString("utf8");
+                if (next.length > prepared.maxOutputChars) {
+                    truncated = true;
+                    return next.slice(0, prepared.maxOutputChars);
+                }
+                return next;
+            };
+            child.stdout.on("data", (chunk) => {
+                stdout = append(stdout, chunk);
+            });
+            child.stderr.on("data", (chunk) => {
+                stderr = append(stderr, chunk);
+            });
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+                setTimeout(() => child.kill("SIGKILL"), 1_000).unref();
+            }, prepared.timeoutMs);
+            timer.unref();
+            child.once("error", (error) => {
+                clearTimeout(timer);
+                reject(describeSpawnError(error, prepared.command));
+            });
+            child.once("close", (code, terminationSignal) => {
+                clearTimeout(timer);
+                resolvePromise({
+                    command: prepared.command,
+                    args: prepared.args,
+                    cwd: relative(this.root, prepared.cwd) || ".",
+                    exitCode: code,
+                    signal: terminationSignal,
+                    timedOut,
+                    stdout: redactTerminalOutput(stdout),
+                    stderr: redactTerminalOutput(stderr),
+                    truncated,
+                    success: code === 0 && !timedOut,
+                });
+            });
+        });
+    }
+    async startBackground(prepared) {
+        const id = randomUUID();
+        const child = spawn(prepared.file, prepared.spawnArgs, {
+            cwd: prepared.cwd,
+            env: prepared.environment,
+            shell: false,
+            windowsHide: true,
+            windowsVerbatimArguments: prepared.windowsVerbatimArguments,
+            stdio: [prepared.interactive ? "pipe" : "ignore", "pipe", "pipe"],
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 1_000).unref();
+        }, prepared.timeoutMs);
+        timer.unref();
+        const job = {
+            id,
+            child,
+            command: prepared.command,
+            args: prepared.args,
+            cwd: prepared.cwd,
+            stdout: "",
+            stderr: "",
+            truncated: false,
+            startedAt: new Date().toISOString(),
+            timer,
+        };
+        const append = (current, chunk) => {
+            const next = current + chunk.toString("utf8");
+            if (next.length > prepared.maxOutputChars) {
+                job.truncated = true;
+                return next.slice(0, prepared.maxOutputChars);
+            }
+            return next;
+        };
+        child.stdout?.on("data", (chunk) => {
+            job.stdout = append(job.stdout, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            job.stderr = append(job.stderr, chunk);
+        });
+        child.once("error", (error) => {
+            job.error = error.message;
+            job.endedAt = new Date().toISOString();
+            clearTimeout(timer);
+        });
+        child.once("close", (exitCode, terminationSignal) => {
+            job.exitCode = exitCode;
+            job.signal = terminationSignal;
+            job.endedAt = new Date().toISOString();
+            clearTimeout(timer);
+        });
+        // `spawn` only reports a failed start asynchronously, so returning as soon
+        // as the call came back reported `started: true` for a command that never
+        // ran — the caller got a job id for a process that did not exist. Waiting
+        // for whichever of `spawn`/`error` fires first makes the reported start real.
+        try {
+            await new Promise((settled, failed) => {
+                child.once("spawn", settled);
+                child.once("error", failed);
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            throw describeSpawnError(error, prepared.command);
+        }
+        this.jobs.set(id, job);
+        return {
+            success: true,
+            started: true,
+            jobId: id,
+            pid: child.pid ?? null,
+            command: prepared.command,
+            executable: prepared.executable,
+            cwd: relative(this.root, prepared.cwd) || ".",
+            interactive: prepared.interactive,
+        };
+    }
+    /**
+     * Answers a prompt on a running job's stdin.
+     *
+     * This is a pipe, not a terminal. A program that asks `isatty` still sees a
+     * non-interactive session and may keep its non-interactive behaviour — reading
+     * a password without echo is the usual one, and it will not work here. A real
+     * PTY needs a native addon; this covers the case that does not.
+     *
+     * ponytail: pipe-only. Add `node-pty` behind an optional dependency if a task
+     * genuinely needs a program that refuses to run without a tty.
+     */
+    sendInput(operation) {
+        const job = this.job(operation);
+        if (operation.input === undefined) {
+            throw new Error("terminal_send_requires_input");
+        }
+        if (job.endedAt !== undefined)
+            throw new Error("terminal_job_not_running");
+        const stdin = job.child.stdin;
+        // `start` without `interactive: true` gets an ignored stdin, and writing to
+        // a closed one throws EPIPE asynchronously — which would surface as an
+        // unhandled error rather than a failed task.
+        if (stdin === null || stdin.destroyed || !stdin.writable) {
+            throw new Error("terminal_job_not_interactive");
+        }
+        const payload = operation.appendNewline && !operation.input.endsWith("\n")
+            ? `${operation.input}\n`
+            : operation.input;
+        stdin.write(payload);
+        return {
+            success: true,
+            sent: true,
+            bytes: Buffer.byteLength(payload),
+            ...this.jobResult(job, false),
+        };
+    }
+    job(operation) {
+        if (operation.jobId === undefined) {
+            throw new Error(`terminal_${operation.action}_requires_job_id`);
+        }
+        const job = this.jobs.get(operation.jobId);
+        if (job === undefined)
+            throw new Error("terminal_job_not_found");
+        return job;
+    }
+    jobResult(job, includeOutput) {
+        return {
+            jobId: job.id,
+            running: job.endedAt === undefined,
+            pid: job.child.pid ?? null,
+            command: job.command,
+            args: job.args,
+            cwd: relative(this.root, job.cwd) || ".",
+            startedAt: job.startedAt,
+            ...(job.endedAt === undefined ? {} : { endedAt: job.endedAt }),
+            ...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+            ...(job.signal === undefined ? {} : { signal: job.signal }),
+            ...(job.error === undefined ? {} : { error: job.error }),
+            truncated: job.truncated,
+            ...(includeOutput
+                ? {
+                    stdout: redactTerminalOutput(job.stdout),
+                    stderr: redactTerminalOutput(job.stderr),
+                }
+                : {}),
+        };
+    }
+    async execute(operation, signal) {
+        switch (operation.action) {
+            case "run":
+                return await this.runForeground(await this.prepare(operation), signal);
+            case "start":
+                return await this.startBackground(await this.prepare(operation));
+            case "status":
+                return this.jobResult(this.job(operation), false);
+            case "output":
+                return this.jobResult(this.job(operation), true);
+            case "send":
+                return this.sendInput(operation);
+            case "stop": {
+                const job = this.job(operation);
+                if (job.endedAt === undefined)
+                    job.child.kill("SIGTERM");
+                return { stopped: true, ...this.jobResult(job, true) };
+            }
+        }
+    }
+    close() {
+        for (const job of this.jobs.values()) {
+            clearTimeout(job.timer);
+            if (job.endedAt === undefined)
+                job.child.kill("SIGTERM");
+        }
+        this.jobs.clear();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

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

package/dist/index.test.js

@@ -0,0 +1,148 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { TerminalOperationSchema } from "@melra/protocol";
+import { TerminalRuntime, redactTerminalOutput } from "./index.js";
+const roots = [];
+afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+describe("TerminalRuntime", () => {
+    it("runs executable and argument arrays without a shell", async () => {
+        const root = await mkdtemp(join(tmpdir(), "melra-terminal-"));
+        roots.push(root);
+        const runtime = await TerminalRuntime.create({ root });
+        const result = await runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "run",
+            command: process.execPath,
+            args: ["-e", "process.stdout.write(process.argv[1])", "hello; touch nope"],
+        }));
+        expect(result.success).toBe(true);
+        expect(result.stdout).toBe("hello; touch nope");
+    });
+    it("redacts secret-shaped output", () => {
+        expect(redactTerminalOutput("password=hunter2 ghp_123456789012345678901234")).not.toContain("hunter2");
+    });
+    it("stops commands at the configured timeout", async () => {
+        const root = await mkdtemp(join(tmpdir(), "melra-terminal-"));
+        roots.push(root);
+        const runtime = await TerminalRuntime.create({ root });
+        const result = await runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "run",
+            command: process.execPath,
+            args: ["-e", "setTimeout(() => {}, 10_000)"],
+            timeoutMs: 150,
+        }));
+        expect(result.timedOut).toBe(true);
+        expect(result.success).toBe(false);
+    });
+    it("supervises bounded background jobs and output", async () => {
+        const root = await mkdtemp(join(tmpdir(), "melra-terminal-"));
+        roots.push(root);
+        const runtime = await TerminalRuntime.create({ root });
+        const started = await runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "start",
+            command: process.execPath,
+            args: [
+                "-e",
+                "process.stdout.write('background-ready'); setTimeout(() => {}, 150)",
+            ],
+            timeoutMs: 2_000,
+        }));
+        expect(started.started).toBe(true);
+        // The child writes its output and then exits on its own. How long that
+        // takes depends on process startup under CI load, so poll for completion
+        // rather than assuming it finishes within a fixed wall-clock delay.
+        const deadline = Date.now() + 10_000;
+        const readOutput = async () => runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "output",
+            jobId: started.jobId,
+        }));
+        let output = await readOutput();
+        while (output.running === true && Date.now() < deadline) {
+            await new Promise((resolvePromise) => setTimeout(resolvePromise, 25));
+            output = await readOutput();
+        }
+        expect(output.stdout).toContain("background-ready");
+        expect(output.running).toBe(false);
+        runtime.close();
+    }, 30_000);
+    it("answers a running job's prompt and refuses one that cannot be answered", async () => {
+        const root = await mkdtemp(join(tmpdir(), "melra-terminal-"));
+        roots.push(root);
+        const runtime = await TerminalRuntime.create({ root });
+        const script = "process.stdout.write('name? ');" +
+            "process.stdin.once('data', (d) => { process.stdout.write('hello ' + String(d).trim()); process.exit(0); })";
+        const start = (interactive) => runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "start",
+            command: process.execPath,
+            args: ["-e", script],
+            interactive,
+            timeoutMs: 5_000,
+        }));
+        const interactive = await start(true);
+        const sent = await runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "send",
+            jobId: interactive.jobId,
+            input: "melra",
+        }));
+        expect(sent.sent).toBe(true);
+        const deadline = Date.now() + 10_000;
+        const readOutput = async (jobId) => runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "output",
+            jobId,
+        }));
+        let output = await readOutput(interactive.jobId);
+        while (output.running === true && Date.now() < deadline) {
+            await new Promise((done) => setTimeout(done, 25));
+            output = await readOutput(interactive.jobId);
+        }
+        expect(output.stdout).toContain("hello melra");
+        // Without `interactive`, stdin is ignored rather than piped. Writing to it
+        // would throw EPIPE asynchronously and surface as an unhandled error, so
+        // the refusal has to come first and name the reason.
+        const plain = await start(false);
+        await expect(runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "send",
+            jobId: plain.jobId,
+            input: "melra",
+        }))).rejects.toThrow("terminal_job_not_interactive");
+        runtime.close();
+    }, 30_000);
+    it("names a missing program instead of surfacing a bare ENOENT", async () => {
+        const root = await mkdtemp(join(tmpdir(), "melra-terminal-"));
+        roots.push(root);
+        const runtime = await TerminalRuntime.create({ root });
+        await expect(runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "run",
+            command: "melra-program-that-does-not-exist",
+        }))).rejects.toThrow("terminal_command_not_found");
+        runtime.close();
+    });
+    it("does not report a background job that never started", async () => {
+        // `spawn` reports a failed start asynchronously, so this used to resolve
+        // with `started: true` and a job id for a process that never existed.
+        const root = await mkdtemp(join(tmpdir(), "melra-terminal-"));
+        roots.push(root);
+        const runtime = await TerminalRuntime.create({ root });
+        await expect(runtime.execute(TerminalOperationSchema.parse({
+            kind: "terminal",
+            action: "start",
+            command: "melra-program-that-does-not-exist",
+        }))).rejects.toThrow("terminal_command_not_found");
+        runtime.close();
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

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

package/dist/resolve-command.d.ts

@@ -0,0 +1,45 @@
+export interface ResolvedCommand {
+    /** Executable actually handed to `spawn`. */
+    file: string;
+    args: string[];
+    /** True when `args` is an already-quoted Windows command line. */
+    windowsVerbatimArguments: boolean;
+    /** Absolute path of the program the caller named, for the receipt. */
+    executable: string;
+}
+export interface ResolveCommandOptions {
+    cwd: string;
+    platform?: NodeJS.Platform;
+    path?: string | undefined;
+    pathExt?: string | undefined;
+    comspec?: string | undefined;
+    /** Seam for tests: decides whether a candidate path is a runnable file. */
+    exists?: (candidate: string) => Promise<boolean>;
+}
+/**
+ * Quote one argument so `cmd.exe /s /c` passes it through unchanged.
+ *
+ * Two layers have to agree. `cmd.exe` treats `& | < > ^ ( )` as syntax, but not
+ * inside double quotes, so quoting neutralises them. The program's own
+ * `CommandLineToArgvW` then unquotes, which is why backslashes before a quote
+ * are doubled and a trailing backslash run is doubled before the closing quote.
+ *
+ * `%` and `!` are the exception: `cmd.exe` expands those *inside* quotes, and no
+ * escape survives the round trip reliably. Rather than ship a
+ * quoting scheme with a hole in it, an argument containing them is refused —
+ * the allowlist would otherwise be bypassable by `npm install "%FOO%"`.
+ * Newlines are refused for the same reason: a command line cannot carry one.
+ */
+export declare function quoteForCmd(value: string): string;
+/**
+ * Turn an allowlisted command name into something `spawn` can actually start.
+ *
+ * On POSIX the name is already runnable and is returned untouched. On Windows it
+ * usually is not: `spawn` runs without a shell, so `npm` never resolves to
+ * `npm.cmd`, and a `.cmd` cannot be executed directly at all. That is the whole
+ * Windows deadlock — the bare name passed policy but could not run, and the
+ * `.cmd` spelling could run but was denied by policy. Resolving here (and
+ * normalising the extension in the policy allowlist) fixes both ends.
+ */
+export declare function resolveCommand(command: string, args: string[], options: ResolveCommandOptions): Promise<ResolvedCommand>;
+//# sourceMappingURL=resolve-command.d.ts.map

package/dist/resolve-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-command.d.ts","sourceRoot":"","sources":["../src/resolve-command.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kEAAkE;IAClE,wBAAwB,EAAE,OAAO,CAAC;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAgDD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAiC1B"}

package/dist/resolve-command.js

@@ -0,0 +1,126 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { win32 } from "node:path";
+/** What `cmd.exe` itself assumes when PATHEXT is unset. */
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/**
+ * Batch shims cannot be executed by `CreateProcess`, so Node refuses to spawn
+ * them without a shell (CVE-2024-27980). They have to go through `cmd.exe`.
+ */
+const BATCH_SUFFIXES = [".bat", ".cmd"];
+async function isFile(candidate) {
+    try {
+        await access(candidate, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Quote one argument so `cmd.exe /s /c` passes it through unchanged.
+ *
+ * Two layers have to agree. `cmd.exe` treats `& | < > ^ ( )` as syntax, but not
+ * inside double quotes, so quoting neutralises them. The program's own
+ * `CommandLineToArgvW` then unquotes, which is why backslashes before a quote
+ * are doubled and a trailing backslash run is doubled before the closing quote.
+ *
+ * `%` and `!` are the exception: `cmd.exe` expands those *inside* quotes, and no
+ * escape survives the round trip reliably. Rather than ship a
+ * quoting scheme with a hole in it, an argument containing them is refused —
+ * the allowlist would otherwise be bypassable by `npm install "%FOO%"`.
+ * Newlines are refused for the same reason: a command line cannot carry one.
+ */
+export function quoteForCmd(value) {
+    if (/[%!\r\n]/.test(value)) {
+        throw new Error("terminal_windows_argument_not_quotable");
+    }
+    const escaped = value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+    return `"${escaped}"`;
+}
+function spellings(command, pathExt) {
+    const extensions = pathExt
+        .split(";")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    const lowered = command.toLowerCase();
+    // An explicit extension is honoured as written. Otherwise only the PATHEXT
+    // spellings are tried and never the bare name — npm ships a *POSIX* `npm`
+    // shell script next to `npm.cmd`, and preferring the bare name would find the
+    // one Windows cannot run.
+    return extensions.some((extension) => lowered.endsWith(extension.toLowerCase()))
+        ? [command]
+        // PATHEXT is conventionally uppercase, and Windows filenames are matched
+        // case-insensitively, so the appended suffix is lowercased purely so the
+        // path recorded in the receipt looks like the file on disk.
+        : extensions.map((extension) => `${command}${extension.toLowerCase()}`);
+}
+async function findExecutable(command, options, exists) {
+    const directoryQualified = /[\\/]/.test(command);
+    // The current directory is deliberately not searched for a bare command.
+    // Windows `CreateProcess` does search it, which would let a `git.cmd` dropped
+    // in the workspace shadow the real `git` that policy actually allowlisted.
+    //
+    // `win32` rather than the ambient path module: these are Windows paths whether
+    // or not the host is Windows, and pinning it is what lets the win32 branch be
+    // tested from any machine.
+    const directories = directoryQualified
+        ? [win32.resolve(options.cwd, win32.dirname(command))]
+        : (options.path ?? "")
+            .split(win32.delimiter)
+            .filter((item) => item.length > 0);
+    const name = directoryQualified ? win32.basename(command) : command;
+    for (const directory of directories) {
+        for (const spelling of spellings(name, options.pathExt ?? DEFAULT_PATHEXT)) {
+            const candidate = win32.resolve(options.cwd, win32.join(directory, spelling));
+            if (await exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Turn an allowlisted command name into something `spawn` can actually start.
+ *
+ * On POSIX the name is already runnable and is returned untouched. On Windows it
+ * usually is not: `spawn` runs without a shell, so `npm` never resolves to
+ * `npm.cmd`, and a `.cmd` cannot be executed directly at all. That is the whole
+ * Windows deadlock — the bare name passed policy but could not run, and the
+ * `.cmd` spelling could run but was denied by policy. Resolving here (and
+ * normalising the extension in the policy allowlist) fixes both ends.
+ */
+export async function resolveCommand(command, args, options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "win32") {
+        return {
+            file: command,
+            args,
+            windowsVerbatimArguments: false,
+            executable: command,
+        };
+    }
+    const found = await findExecutable(command, options, options.exists ?? isFile);
+    if (found === undefined) {
+        throw new Error(`terminal_command_not_found:${command}`);
+    }
+    const isBatch = BATCH_SUFFIXES.some((suffix) => found.toLowerCase().endsWith(suffix));
+    if (!isBatch) {
+        return {
+            file: found,
+            args,
+            windowsVerbatimArguments: false,
+            executable: found,
+        };
+    }
+    return {
+        file: options.comspec ?? "cmd.exe",
+        // `/d` skips AutoRun registry commands, `/s` makes cmd strip exactly the
+        // outer quote pair and leave everything between them alone.
+        args: ["/d", "/s", "/c", `"${[found, ...args].map(quoteForCmd).join(" ")}"`],
+        windowsVerbatimArguments: true,
+        executable: found,
+    };
+}
+//# sourceMappingURL=resolve-command.js.map

package/dist/resolve-command.js.map

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

package/dist/resolve-command.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resolve-command.test.d.ts.map

package/dist/resolve-command.test.d.ts.map

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

package/dist/resolve-command.test.js

@@ -0,0 +1,96 @@
+// Copyright 2026 XAGI Labs Private Limited
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from "vitest";
+import { quoteForCmd, resolveCommand } from "./resolve-command.js";
+/**
+ * These run the Windows branch on every host. The Windows breakage shipped green
+ * through a CI matrix that *includes* `windows-latest` precisely because nothing
+ * exercised the win32 path, so platform and filesystem are injected rather than
+ * detected.
+ */
+const WINDOWS_FILES = new Set([
+    "C:\\Program Files\\nodejs\\npm.cmd",
+    "C:\\Program Files\\nodejs\\node.exe",
+    "C:\\Windows\\System32\\where.exe",
+    // npm also ships a POSIX shell script with no extension, right next to the
+    // shim. It is not runnable on Windows.
+    "C:\\Program Files\\nodejs\\npm",
+].map((item) => item.toLowerCase()));
+const windows = {
+    cwd: "C:\\workspace",
+    platform: "win32",
+    path: "C:\\Program Files\\nodejs;C:\\Windows\\System32",
+    pathExt: ".COM;.EXE;.BAT;.CMD",
+    comspec: "C:\\Windows\\System32\\cmd.exe",
+    exists: async (candidate) => WINDOWS_FILES.has(candidate.toLowerCase()),
+};
+describe("resolveCommand", () => {
+    it("leaves POSIX commands untouched", async () => {
+        await expect(resolveCommand("git", ["status"], {
+            cwd: "/workspace",
+            platform: "linux",
+        })).resolves.toEqual({
+            file: "git",
+            args: ["status"],
+            windowsVerbatimArguments: false,
+            executable: "git",
+        });
+    });
+    it("resolves a bare Windows name to its .exe", async () => {
+        const resolved = await resolveCommand("node", ["-v"], windows);
+        expect(resolved.file.toLowerCase()).toBe("c:\\program files\\nodejs\\node.exe");
+        expect(resolved.args).toEqual(["-v"]);
+        expect(resolved.windowsVerbatimArguments).toBe(false);
+    });
+    it("prefers the .cmd shim over the extension-less POSIX script", async () => {
+        // The deadlock in miniature: `npm` is what policy allowlists, `npm.cmd` is
+        // what Windows can actually start, and `npm` (the sh script) is a trap.
+        const resolved = await resolveCommand("npm", ["install"], windows);
+        expect(resolved.executable.toLowerCase()).toBe("c:\\program files\\nodejs\\npm.cmd");
+    });
+    it("runs a batch shim through cmd.exe with the payload quoted", async () => {
+        const resolved = await resolveCommand("npm", ["run", "build"], windows);
+        expect(resolved.file).toBe("C:\\Windows\\System32\\cmd.exe");
+        expect(resolved.windowsVerbatimArguments).toBe(true);
+        expect(resolved.args.slice(0, 3)).toEqual(["/d", "/s", "/c"]);
+        expect(resolved.args[3]).toBe('""C:\\Program Files\\nodejs\\npm.cmd" "run" "build""');
+    });
+    it("keeps shell metacharacters inside the quoted argument", async () => {
+        // Without quoting, cmd.exe would treat `&&` as a separator and run a second
+        // program that policy never allowlisted.
+        const resolved = await resolveCommand("npm", ["install", "x && calc.exe"], windows);
+        expect(resolved.args[3]).toContain('"install" "x && calc.exe"');
+    });
+    it("refuses arguments cmd.exe would expand rather than quoting them wrongly", async () => {
+        await expect(resolveCommand("npm", ["install", "%USERPROFILE%"], windows)).rejects.toThrow("terminal_windows_argument_not_quotable");
+    });
+    it("reports a missing program by name instead of a bare ENOENT", async () => {
+        await expect(resolveCommand("rg", [], windows)).rejects.toThrow("terminal_command_not_found:rg");
+    });
+    it("does not search the working directory for a bare command", async () => {
+        // A `git.cmd` dropped in the workspace must not shadow the allowlisted git.
+        await expect(resolveCommand("git", [], {
+            ...windows,
+            exists: async (candidate) => candidate.toLowerCase() === "c:\\workspace\\git.cmd",
+        })).rejects.toThrow("terminal_command_not_found:git");
+    });
+    it("still honours an explicitly directory-qualified command", async () => {
+        const resolved = await resolveCommand(".\\tool", [], {
+            ...windows,
+            exists: async (candidate) => candidate.toLowerCase() === "c:\\workspace\\tool.exe",
+        });
+        expect(resolved.file.toLowerCase()).toBe("c:\\workspace\\tool.exe");
+    });
+});
+describe("quoteForCmd", () => {
+    it("escapes embedded quotes so the program sees them literally", () => {
+        expect(quoteForCmd('say "hi"')).toBe('"say \\"hi\\""');
+    });
+    it("doubles a trailing backslash run before the closing quote", () => {
+        expect(quoteForCmd("C:\\path\\")).toBe('"C:\\path\\\\"');
+    });
+    it("refuses a newline, which a command line cannot carry", () => {
+        expect(() => quoteForCmd("a\nb")).toThrow("terminal_windows_argument_not_quotable");
+    });
+});
+//# sourceMappingURL=resolve-command.test.js.map

package/dist/resolve-command.test.js.map

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

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@melra/terminal-runtime",
+  "version": "0.3.0-alpha.10",
+  "description": "Shell-free supervised terminal reference effect adapter for the MELRA kernel.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XAGI-Lab/melra.git",
+    "directory": "packages/terminal-runtime"
+  },
+  "homepage": "https://github.com/XAGI-Lab/melra#readme",
+  "bugs": "https://github.com/XAGI-Lab/melra/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@melra/protocol": "0.3.0-alpha.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}