just-bash

import { Bash, decodeBytesToUtf8, defineCommand } from "just-bash";

const upper = defineCommand("upper", async (args, ctx) => {
  // ctx.stdin は ByteString。文字列操作の前にデコードする。
  return {
    stdout: decodeBytesToUtf8(ctx.stdin).toUpperCase(),
    stderr: "",
    exitCode: 0,
  };
});

const bash = new Bash({ customCommands: [upper] });
await bash.exec("echo 'test' | upper"); // "TEST\n"

import { Bash, BashTransformPipeline, TeePlugin, CommandCollectorPlugin } from "just-bash";

// 単体パイプライン — 出力は任意のシェルで実行できる
const pipeline = new BashTransformPipeline()
  .use(new TeePlugin({ outputDir: "/tmp/logs" }))
  .use(new CommandCollectorPlugin());
const result = pipeline.transform("echo hello | grep hello");
result.script;            // 変換後の bash 文字列
result.metadata.commands; // ["echo", "grep", "tee"]

// 統合 API — exec() が変換を自動適用し metadata を返す
const bash = new Bash();
bash.registerTransformPlugin(new CommandCollectorPlugin());
const execResult = await bash.exec("echo hello | grep hello");
execResult.metadata?.commands; // ["echo", "grep"]

import { Bash } from "just-bash";
import { OverlayFs } from "just-bash/fs/overlay-fs";

const overlay = new OverlayFs({
  root: "/path/to/project",
  // copy-on-write のデータ量は実ファイル読み取りとは独立に制限される
  maxMemoryBytes: 256 * 1024 * 1024,
});
const env = new Bash({ fs: overlay, cwd: overlay.getMountPoint() });

await env.exec("cat package.json");            // ディスクから読む
await env.exec('echo "modified" > package.json'); // メモリに留まる

import { Bash, MountableFs, InMemoryFs } from "just-bash";
import { OverlayFs } from "just-bash/fs/overlay-fs";
import { ReadWriteFs } from "just-bash/fs/read-write-fs";

const fs = new MountableFs({ base: new InMemoryFs() });

// 読み取り専用のナレッジベースをマウント
fs.mount("/mnt/knowledge", new OverlayFs({ root: "/path/to/knowledge", readOnly: true }));

// 読み書き可能なワークスペースをマウント
fs.mount("/workspace", new ReadWriteFs({ root: "/path/to/workspace" }));

const bash = new Bash({ fs, cwd: "/workspace" });
await bash.exec("cp /mnt/knowledge/doc.txt ./"); // マウントをまたぐコピー

// URL プレフィックスを限定し、メソッドは GET / HEAD のみ（最も安全）
const env = new Bash({
  network: {
    allowedUrlPrefixes: [
      "https://api.github.com/orgs/myorg/",
      "https://api.example.com",
    ],
  },
});

// 認証情報はヘッダ変換で注入する（シークレットはサンドボックスに入らない）
const env2 = new Bash({
  network: {
    allowedUrlPrefixes: [
      "https://public-api.com",
      {
        url: "https://ai-gateway.vercel.sh",
        transform: [{ headers: { Authorization: "Bearer secret" } }],
      },
    ],
  },
});

const bash = new Bash({
  javascript: {
    // path:     "math.add"（ドット区切り）
    // argsJson: '{"a":1,"b":2}'（引数なしなら ""）
    // 戻り値:   JSON 文字列。undefined なら ""
    // throw:    サンドボックス内の例外として伝播する
    invokeTool: async (path, argsJson) => {
      const args = argsJson ? JSON.parse(argsJson) : undefined;
      if (path === "math.add") return JSON.stringify({ sum: args.a + args.b });
      throw new Error(`Unknown tool: ${path}`);
    },
  },
});

const env = new Bash({
  executionLimitProfile: "hardened",
  executionLimits: {
    maxCallDepth: 100,                    // 関数の再帰深度
    maxCommandCount: 20000,               // ネストした実行と共有
    maxSourceBytes: 8 * 1024 * 1024,      // パース前のシェルソース
    maxFileSystemBytes: 256 * 1024 * 1024,// 既定 FS が保持するデータ
    maxOutputSize: 32 * 1024 * 1024,      // stdout + stderr の合計
    maxArchiveBytes: 256 * 1024 * 1024,   // 展開後のアーカイブ
    maxDatabaseBytes: 128 * 1024 * 1024,  // SQLite イメージ
    maxExecutionTimeMs: 30_000,           // 実行全体の壁時計期限
    maxExtensionCleanupTimeMs: 25,        // キャンセル応答の猶予
  },
});