script-runner-kit 0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Being respectful and constructive
+- Accepting feedback gracefully
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior include:
+
+- Harassment, trolling, or insulting language
+- Personal attacks or discrimination
+- Publishing others' private information without permission
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and may remove or edit contributions that violate this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and public spaces when an individual is representing the project.

package/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Thanks for contributing!
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+## Pull Request Checklist
+
+- Keep changes focused and small.
+- Update docs when behavior changes.
+- Run `npm run check` before opening PR.
+- Add or update tests/checks for new behavior.
+
+## Commit Style
+
+Use clear commit messages that explain **why** the change is needed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# script-runner-kit
+
+A CLI tool for bot/webhook-triggered script execution with live output streaming. Supports `--config` and is ready for npm + `npx` usage.
+
+## Features
+
+- Stream script stdout/stderr over Server-Sent Events (SSE)
+- Prevent duplicate concurrent runs per script name
+- Audit logs for every execution
+- Config-driven scripts via `--config`
+
+## Install / Run
+
+### Use with npx
+
+```bash
+ npx script-runner-kit --config ./script-runner.config.json
+```
+
+### Local development
+
+```bash
+npm install
+npm run check
+node bin/script-runner-kit.js --config ./script-runner.config.json
+```
+
+Server default URL:
+
+```text
+http://127.0.0.1:8088
+```
+
+## CLI
+
+```bash
+script-runner-kit --config <path> [--port <number>]
+```
+
+Options:
+
+- `--config <path>`: required, supports `.json` / `.js` / `.cjs`
+- `--port <number>`: optional, override config/env port
+- `PORT` env: optional fallback if `--port` omitted
+
+Port precedence:
+
+1. `--port`
+2. `PORT` environment variable
+3. `port` from config file
+4. default `8088`
+
+## Configuration
+
+Example `script-runner.config.json`:
+
+```json
+{
+  "port": 8088,
+  "auditDir": ".script-audit-logs",
+  "authTokens": ["global-secret-a", "global-secret-b"],
+  "scripts": {
+    "check-update": {
+      "scriptPath": "./scripts/check-update.sh",
+      "rootDir": ".",
+      "authTokens": ["check-secret-a", "check-secret-b"]
+    }
+  }
+}
+```
+
+Notes:
+
+- `scriptPath` and `rootDir` are resolved relative to the config file directory.
+- Each script supports either:
+  - `scriptPath` (execute via `bash <scriptPath>`)
+  - or `command` + optional `args`.
+- Auth uses JWT and supports multiple secrets per script via `authTokens`.
+
+### Auto package.json scripts
+
+When starting in a directory containing `package.json`, this tool auto-discovers npm scripts and exposes them as runnable items:
+
+- `<name>` (for example `build`)
+- `npm:<name>` (for example `npm:build`)
+
+Config-defined scripts take priority on name conflict.
+
+### Authentication
+
+Every API call requires a JWT token. Supported token sources:
+
+- `Authorization: Bearer <token>` (recommended)
+- `x-runner-token: <token>`
+- query parameter `?token=<token>` (convenient for EventSource demos)
+
+Verification rules:
+
+- Uses `jsonwebtoken.verify()` with algorithms `HS256/HS384/HS512`
+- Supports multiple secrets per script (`authTokens` array), useful for key rotation
+- If a script has no local `authTokens`, top-level `authTokens` is used as fallback
+
+## HTTP API
+
+- `GET /` – minimal UI page
+- `GET /api/<script-name>` – run script and stream SSE events
+
+SSE events:
+
+- `start`
+- `log`
+- `end`
+- `error`
+
+## Security Notes
+
+- This tool executes shell scripts from your config. Only expose it inside trusted networks.
+- Avoid putting untrusted script paths into config.
+
+## Open Source Workflow
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 --title "v0.1.0" --notes "Release v0.1.0"
+```
+
+GitHub Actions workflow `.github/workflows/publish.yml` will publish to npm automatically.
+It triggers on `v*` tags and supports npm Trusted Publishing (OIDC) or `NPM_TOKEN` secret.
+
+4. Verify via:
+
+```bash
+npx script-runner-kit --config ./script-runner.config.json --help
+```
+
+Detailed release steps: see `docs/RELEASE.md`.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest minor release is actively supported with security fixes.
+
+## Reporting a Vulnerability
+
+Please do not open public issues for security vulnerabilities.
+
+Instead, contact the maintainer privately and include:
+
+- Affected version
+- Reproduction steps
+- Impact assessment
+- Suggested mitigation (if any)
+
+We will acknowledge the report as quickly as possible and work on a fix.

package/bin/script-runner-kit.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/cli");
+
+runCli(process.argv.slice(2));

package/docs/AUTHENTICATION.md

@@ -0,0 +1,43 @@
+# Authentication (JWT)
+
+`script-runner-kit` protects script execution endpoints with JWT.
+
+## Token transport
+
+Supported sources (priority order):
+
+1. `Authorization: Bearer <token>`
+2. `x-runner-token: <token>`
+3. Query param `?token=<token>`
+
+## Config example
+
+```json
+{
+  "authTokens": ["global-secret-a", "global-secret-b"],
+  "scripts": {
+    "deploy": {
+      "command": "npm",
+      "args": ["run", "deploy"],
+      "authTokens": ["deploy-secret-v2", "deploy-secret-v1"]
+    },
+    "build": {
+      "command": "npm",
+      "args": ["run", "build"]
+    }
+  }
+}
+```
+
+- Script-level `authTokens` are preferred.
+- If missing, top-level `authTokens` is used.
+
+## Key rotation
+
+Use multiple secrets and keep new secret first:
+
+```json
+"authTokens": ["new-secret", "old-secret"]
+```
+
+The runner tries each secret until verification succeeds.

package/docs/RELEASE.md

@@ -0,0 +1,64 @@
+# Release Guide (GitHub + npm)
+
+## 1) Prepare repository
+
+1. Create a GitHub repo (for example: `script-runner-kit`).
+2. Push this project to `main` branch.
+3. Update `package.json` fields:
+   - `repository.url`
+   - `bugs.url`
+   - `homepage`
+
+## 2) Verify before release
+
+```bash
+npm run check
+npm pack --dry-run
+```
+
+## 3) Publish to npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+### Publish via GitHub Actions (recommended)
+
+1. Configure one of the following auth methods:
+   - Preferred: npm Trusted Publishing (OIDC)
+   - Compatible fallback: npm Automation Token in repo secret `NPM_TOKEN`
+2. Push a version tag (or run workflow manually):
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow at `.github/workflows/publish.yml` will then:
+
+- install dependencies
+- run `npm run check`
+- run `npm pack --dry-run`
+- publish to npm with provenance
+
+After publish succeeds, you can create a GitHub Release if needed:
+
+```bash
+gh release create v0.1.0 --title "v0.1.0" --notes "Initial open-source release"
+```
+
+## 4) Verify npx usage
+
+```bash
+npx script-runner-kit --help
+npx script-runner-kit --config ./script-runner.config.json
+```
+
+## 5) Create GitHub release
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+gh release create v0.1.0 --title "v0.1.0" --notes "Initial open-source release"
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "script-runner-kit",
+  "version": "0.1.0",
+  "description": "Run project scripts via webhook-friendly HTTP endpoints",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "script-runner-kit": "bin/script-runner-kit.js"
+  },
+  "access": "public",
+  "main": "src/server.js",
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "script-runner.config.json",
+    "README.md",
+    "docs",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "webhook",
+    "bot",
+    "script-runner",
+    "cli",
+    "npx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GitaiQAQ/script-runner-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GitaiQAQ/script-runner-kit/issues"
+  },
+  "homepage": "https://github.com/GitaiQAQ/script-runner-kit#readme",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2"
+  },
+  "scripts": {
+    "check": "pnpm run check:syntax && pnpm run check:cli",
+    "check:syntax": "node --check src/index.js && node --check bin/script-runner-kit.js && node --check src/config.js && node --check src/server.js && node --check src/cli.js",
+    "check:cli": "node bin/script-runner-kit.js --help"
+  }
+}

package/script-runner.config.json

@@ -0,0 +1,14 @@
+{
+  "port": 8088,
+  "auditDir": ".script-audit-logs",
+  "authTokens": [
+    "replace-with-strong-jwt-secret-1",
+    "replace-with-strong-jwt-secret-2"
+  ],
+  "scripts": {
+    "check-update": {
+      "scriptPath": "./scripts/check-update.sh",
+      "rootDir": "."
+    }
+  }
+}

package/scripts/check-update.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+echo "[check-update] started at $(date -u +%FT%TZ)"
+echo "[check-update] no remote configured in demo script"
+echo "[check-update] finished"

package/src/cli.js

@@ -0,0 +1,45 @@
+const { loadRunnerConfig, parseArgv, printHelp } = require("./config");
+const { startServer } = require("./server");
+
+function runCli(argv) {
+  let parsed;
+  try {
+    parsed = parseArgv(argv);
+  } catch (err) {
+    process.stderr.write(`Argument error: ${err.message}\n\n`);
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  let config;
+  try {
+    config = loadRunnerConfig(parsed.configPath, process.cwd());
+  } catch (err) {
+    process.stderr.write(`Config error: ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const envPort =
+    process.env.PORT && Number.isInteger(Number(process.env.PORT))
+      ? Number(process.env.PORT)
+      : undefined;
+
+  const port = parsed.port || envPort || config.port || 8088;
+
+  startServer({
+    scripts: config.scripts,
+    auditDir: config.auditDir,
+    port,
+  });
+}
+
+module.exports = {
+  runCli,
+};

package/src/config.js

@@ -0,0 +1,300 @@
+const fs = require("fs");
+const path = require("path");
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "Script Runner Kit",
+      "",
+      "Usage:",
+      "  script-runner-kit --config <path-to-config>",
+      "",
+      "Options:",
+      "  --config <path>   Required. Path to runner config file (.json/.js/.cjs)",
+      "  --port <number>   Optional. Override port from config",
+      "  -h, --help        Show help",
+      "",
+      "Example:",
+      "  npx script-runner-kit --config ./script-runner.config.json",
+      "",
+    ].join("\n")
+  );
+}
+
+function parseArgv(argv) {
+  const args = [...argv];
+  const parsed = {
+    configPath: "",
+    port: undefined,
+    help: false,
+  };
+
+  while (args.length > 0) {
+    const current = args.shift();
+
+    if (!current) {
+      continue;
+    }
+
+    if (current === "-h" || current === "--help") {
+      parsed.help = true;
+      continue;
+    }
+
+    if (current.startsWith("--config=")) {
+      parsed.configPath = current.slice("--config=".length).trim();
+      continue;
+    }
+
+    if (current === "--config") {
+      const value = args.shift();
+      if (!value) {
+        throw new Error("Missing value for --config");
+      }
+      parsed.configPath = value.trim();
+      continue;
+    }
+
+    if (current.startsWith("--port=")) {
+      const value = current.slice("--port=".length).trim();
+      const port = Number(value);
+      if (!Number.isInteger(port) || port <= 0) {
+        throw new Error(`Invalid --port value: ${value}`);
+      }
+      parsed.port = port;
+      continue;
+    }
+
+    if (current === "--port") {
+      const value = args.shift();
+      if (!value) {
+        throw new Error("Missing value for --port");
+      }
+      const port = Number(value);
+      if (!Number.isInteger(port) || port <= 0) {
+        throw new Error(`Invalid --port value: ${value}`);
+      }
+      parsed.port = port;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${current}`);
+  }
+
+  return parsed;
+}
+
+function loadJsonConfig(configPath) {
+  const raw = fs.readFileSync(configPath, "utf8");
+  return JSON.parse(raw);
+}
+
+function loadJsConfig(configPath) {
+  const loaded = require(configPath);
+  if (loaded && typeof loaded === "object" && "default" in loaded) {
+    return loaded.default;
+  }
+  return loaded;
+}
+
+function normalizeAuthTokens(value, fieldPath) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${fieldPath} must be an array of strings`);
+  }
+  const tokens = value.map((item) => String(item).trim()).filter(Boolean);
+  if (tokens.length === 0) {
+    throw new Error(`${fieldPath} must contain at least one non-empty token`);
+  }
+  return tokens;
+}
+
+function normalizeScriptFromConfig(configDir, scriptName, scriptConfig) {
+  if (!scriptConfig || typeof scriptConfig !== "object") {
+    throw new Error(`scripts.${scriptName} must be an object`);
+  }
+
+  const resolvedRootDir = path.resolve(
+    configDir,
+    typeof scriptConfig.rootDir === "string" && scriptConfig.rootDir.trim()
+      ? scriptConfig.rootDir
+      : "."
+  );
+  const authTokens =
+    scriptConfig.authTokens === undefined
+      ? undefined
+      : normalizeAuthTokens(scriptConfig.authTokens, `scripts.${scriptName}.authTokens`);
+
+  if (typeof scriptConfig.scriptPath === "string" && scriptConfig.scriptPath.trim()) {
+    return {
+      rootDir: resolvedRootDir,
+      scriptPath: path.resolve(configDir, scriptConfig.scriptPath),
+      authTokens,
+    };
+  }
+
+  if (typeof scriptConfig.command === "string" && scriptConfig.command.trim()) {
+    const args =
+      scriptConfig.args === undefined
+        ? []
+        : Array.isArray(scriptConfig.args)
+          ? scriptConfig.args
+          : null;
+    if (!args || args.some((item) => typeof item !== "string")) {
+      throw new Error(`scripts.${scriptName}.args must be an array of strings`);
+    }
+    return {
+      rootDir: resolvedRootDir,
+      command: scriptConfig.command,
+      args,
+      authTokens,
+    };
+  }
+
+  throw new Error(
+    `scripts.${scriptName} must provide either scriptPath or command`
+  );
+}
+
+function loadPackageJsonScripts(cwd) {
+  const packageJsonPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return {};
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (err) {
+    throw new Error(`Failed to parse package.json at ${packageJsonPath}: ${err.message}`);
+  }
+
+  if (!pkg || typeof pkg !== "object") {
+    return {};
+  }
+
+  const scripts = pkg.scripts;
+  if (!scripts || typeof scripts !== "object" || Array.isArray(scripts)) {
+    return {};
+  }
+
+  const discovered = {};
+  for (const scriptName of Object.keys(scripts)) {
+    discovered[scriptName] = {
+      rootDir: cwd,
+      command: "npm",
+      args: ["run", scriptName],
+    };
+    discovered[`npm:${scriptName}`] = {
+      rootDir: cwd,
+      command: "npm",
+      args: ["run", scriptName],
+    };
+  }
+
+  return discovered;
+}
+
+function resolveScriptConfig(configPath, rawConfig, cwd) {
+  if (!rawConfig || typeof rawConfig !== "object") {
+    throw new Error("Config must be an object");
+  }
+
+  const configDir = path.dirname(configPath);
+  const globalAuthTokens =
+    rawConfig.authTokens === undefined
+      ? undefined
+      : normalizeAuthTokens(rawConfig.authTokens, "authTokens");
+  const scripts = rawConfig.scripts || {};
+  if (typeof scripts !== "object" || Array.isArray(scripts)) {
+    throw new Error("Config field 'scripts' must be an object when provided");
+  }
+
+  const resolvedScripts = {};
+  for (const [scriptName, scriptConfig] of Object.entries(scripts)) {
+    resolvedScripts[scriptName] = normalizeScriptFromConfig(
+      configDir,
+      scriptName,
+      scriptConfig
+    );
+  }
+
+  const discoveredScripts = loadPackageJsonScripts(cwd);
+  for (const [scriptName, scriptConfig] of Object.entries(discoveredScripts)) {
+    if (!resolvedScripts[scriptName]) {
+      resolvedScripts[scriptName] = scriptConfig;
+    }
+  }
+
+  if (Object.keys(resolvedScripts).length === 0) {
+    throw new Error(
+      "No scripts available. Add config.scripts or run in a directory with package.json scripts"
+    );
+  }
+
+  for (const [scriptName, scriptConfig] of Object.entries(resolvedScripts)) {
+    if (!Array.isArray(scriptConfig.authTokens) || scriptConfig.authTokens.length === 0) {
+      if (globalAuthTokens && globalAuthTokens.length > 0) {
+        resolvedScripts[scriptName] = {
+          ...scriptConfig,
+          authTokens: globalAuthTokens,
+        };
+      } else {
+        throw new Error(
+          `Auth required for scripts.${scriptName}. Add scripts.${scriptName}.authTokens or top-level authTokens`
+        );
+      }
+    }
+  }
+
+  const resolvedAuditDir = path.resolve(
+    configDir,
+    typeof rawConfig.auditDir === "string" && rawConfig.auditDir.trim()
+      ? rawConfig.auditDir
+      : ".script-audit-logs"
+  );
+
+  const configuredPort =
+    rawConfig.port !== undefined && rawConfig.port !== null
+      ? Number(rawConfig.port)
+      : undefined;
+  if (
+    configuredPort !== undefined &&
+    (!Number.isInteger(configuredPort) || configuredPort <= 0)
+  ) {
+    throw new Error("Config field 'port' must be a positive integer when provided");
+  }
+
+  return {
+    scripts: resolvedScripts,
+    auditDir: resolvedAuditDir,
+    port: configuredPort,
+  };
+}
+
+function loadRunnerConfig(configPathArg, cwd) {
+  if (!configPathArg || typeof configPathArg !== "string") {
+    throw new Error("--config is required");
+  }
+  const resolvedPath = path.resolve(cwd, configPathArg);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Config file not found: ${resolvedPath}`);
+  }
+
+  const ext = path.extname(resolvedPath).toLowerCase();
+  let rawConfig;
+  if (ext === ".json") {
+    rawConfig = loadJsonConfig(resolvedPath);
+  } else if (ext === ".js" || ext === ".cjs") {
+    rawConfig = loadJsConfig(resolvedPath);
+  } else {
+    throw new Error("Unsupported config extension. Use .json, .js, or .cjs");
+  }
+
+  return resolveScriptConfig(resolvedPath, rawConfig, cwd);
+}
+
+module.exports = {
+  parseArgv,
+  printHelp,
+  loadRunnerConfig,
+};

package/src/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runCli } = require("./cli");
+
+runCli(process.argv.slice(2));

package/src/server.js

@@ -0,0 +1,334 @@
+const http = require("http");
+const { spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const jwt = require("jsonwebtoken");
+
+function nowStamp() {
+  return new Date().toISOString().replaceAll(":", "-");
+}
+
+function fileSafeName(name) {
+  return name.replaceAll(/[^a-zA-Z0-9._-]/g, "-");
+}
+
+function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function send(res, status, body, contentType = "text/plain; charset=utf-8") {
+  res.writeHead(status, { "Content-Type": contentType });
+  res.end(body);
+}
+
+function sendSse(res, event, payload) {
+  res.write(`event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`);
+}
+
+function readTokenFromRequest(req, url) {
+  const auth = req.headers.authorization;
+  if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+    const token = auth.slice("Bearer ".length).trim();
+    if (token) {
+      return token;
+    }
+  }
+
+  const headerToken = req.headers["x-runner-token"];
+  if (typeof headerToken === "string" && headerToken.trim()) {
+    return headerToken.trim();
+  }
+
+  const queryToken = url.searchParams.get("token");
+  if (typeof queryToken === "string" && queryToken.trim()) {
+    return queryToken.trim();
+  }
+
+  return "";
+}
+
+function verifyJwtWithSecrets(token, secrets) {
+  for (const secret of secrets) {
+    try {
+      const payload = jwt.verify(token, secret, {
+        algorithms: ["HS256", "HS384", "HS512"],
+      });
+      return { ok: true, payload };
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return { ok: false };
+}
+
+function createAuditLogger(auditDir, scriptName, rootDir, target, remoteAddress) {
+  fs.mkdirSync(auditDir, { recursive: true });
+  const logFile = path.join(
+    auditDir,
+    `${nowStamp()}__${fileSafeName(scriptName)}.log`
+  );
+  const stream = fs.createWriteStream(logFile, { flags: "a" });
+  const write = (record) => {
+    stream.write(
+      `${JSON.stringify({ ts: new Date().toISOString(), ...record })}\n`
+    );
+  };
+
+  write({
+    event: "start",
+    script: scriptName,
+    rootDir,
+    target,
+    remoteAddress,
+  });
+
+  return {
+    logFile,
+    write,
+    close: () => stream.end(),
+  };
+}
+
+function resolveExecutionTarget(scriptName, scriptConfig) {
+  const rootDir = path.resolve(scriptConfig.rootDir);
+  if (!fs.existsSync(rootDir)) {
+    return { error: `Script config invalid (rootDir missing): ${scriptName}` };
+  }
+
+  if (typeof scriptConfig.scriptPath === "string" && scriptConfig.scriptPath.trim()) {
+    const scriptPath = path.resolve(scriptConfig.scriptPath);
+    if (!fs.existsSync(scriptPath)) {
+      return { error: `Script config invalid (scriptPath missing): ${scriptName}` };
+    }
+    return {
+      rootDir,
+      target: scriptPath,
+      command: "bash",
+      args: [scriptPath],
+    };
+  }
+
+  if (typeof scriptConfig.command === "string" && scriptConfig.command.trim()) {
+    return {
+      rootDir,
+      target: `${scriptConfig.command} ${(scriptConfig.args || []).join(" ")}`.trim(),
+      command: scriptConfig.command,
+      args: Array.isArray(scriptConfig.args) ? scriptConfig.args : [],
+    };
+  }
+
+  return { error: `Script config invalid (no executable target): ${scriptName}` };
+}
+
+function renderHome(scripts) {
+  const options = Object.entries(scripts)
+    .map(([name, config]) => {
+      const safeName = escapeHtml(name);
+      const safeRoot = escapeHtml(config.rootDir);
+      return `<option value="${safeName}">${safeName} (${safeRoot})</option>`;
+    })
+    .join("");
+
+  return `<!doctype html>
+<meta charset="utf-8">
+<title>Script Runner</title>
+<h1>Script Runner</h1>
+<p>Use GET /api/&lt;script-name&gt; to trigger execution and stream output via SSE.</p>
+<h2>Quick Usage</h2>
+<ul>
+  <li>Start: <code>npx script-runner-kit --config ./script-runner.config.json</code></li>
+  <li>Trigger: <code>GET /api/&lt;script-name&gt;</code> (for example <code>/api/check</code>)</li>
+  <li>Auto-loads scripts from local <code>package.json</code> (config entries take precedence on name conflicts)</li>
+  <li>Auth: send JWT via <code>Authorization: Bearer &lt;token&gt;</code>, <code>x-runner-token</code>, or <code>?token=</code></li>
+</ul>
+<label>script:</label>
+<select id="name">${options}</select>
+<label>jwt token:</label>
+<input id="token" type="password" placeholder="paste JWT token" style="min-width: 360px" />
+<button id="run">Run</button>
+<pre id="out"></pre>
+<script>
+const out = document.getElementById('out');
+const name = document.getElementById('name');
+const token = document.getElementById('token');
+const run = document.getElementById('run');
+let es;
+function log(line) { out.textContent += line + '\\n'; }
+run.onclick = () => {
+  out.textContent = '';
+  if (es) es.close();
+  const script = encodeURIComponent(name.value);
+  const t = token.value.trim();
+  const suffix = t ? ('?token=' + encodeURIComponent(t)) : '';
+  es = new EventSource('/api/' + script + suffix);
+  es.addEventListener('start', (e) => {
+    const m = JSON.parse(e.data);
+    log('[start] ' + m.script);
+  });
+  es.addEventListener('log', (e) => {
+    const m = JSON.parse(e.data);
+    log('[' + m.stream + '] ' + m.text);
+  });
+  es.addEventListener('end', (e) => {
+    const m = JSON.parse(e.data);
+    log('[end] exit=' + m.code + ' signal=' + m.signal);
+    es.close();
+  });
+  es.addEventListener('error', (e) => {
+    if (e.data) {
+      const m = JSON.parse(e.data);
+      log('[error] ' + m.message);
+    } else {
+      log('[error] connection closed');
+    }
+    if (es) es.close();
+  });
+};
+</script>`;
+}
+
+function createServer({ scripts, auditDir }) {
+  const running = new Map();
+
+  return http.createServer((req, res) => {
+    if (!req.url) {
+      send(res, 400, "Bad Request");
+      return;
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
+
+    if (req.method === "GET" && url.pathname === "/") {
+      send(res, 200, renderHome(scripts), "text/html; charset=utf-8");
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname.startsWith("/api/")) {
+      const scriptName = decodeURIComponent(
+        url.pathname.slice("/api/".length)
+      ).trim();
+      const scriptConfig = scripts[scriptName];
+
+      if (!scriptName || !scriptConfig) {
+        send(res, 404, "Unknown script");
+        return;
+      }
+
+      const token = readTokenFromRequest(req, url);
+      if (!token) {
+        send(res, 401, "Unauthorized: missing JWT token");
+        return;
+      }
+
+      const authResult = verifyJwtWithSecrets(token, scriptConfig.authTokens || []);
+      if (!authResult.ok) {
+        send(res, 403, "Forbidden: invalid token");
+        return;
+      }
+
+      const targetSpec = resolveExecutionTarget(scriptName, scriptConfig);
+      if (targetSpec.error) {
+        send(res, 500, targetSpec.error);
+        return;
+      }
+
+      const { rootDir, target, command, args } = targetSpec;
+
+      if (running.get(scriptName)) {
+        send(res, 409, `Script is already running: ${scriptName}`);
+        return;
+      }
+
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-store, must-revalidate, no-transform",
+        Connection: "keep-alive",
+        Pragma: "no-cache",
+        Expires: "0",
+        "X-Accel-Buffering": "no",
+      });
+      res.flushHeaders();
+      res.write(": connected\n\n");
+
+      const audit = createAuditLogger(
+        auditDir,
+        scriptName,
+        rootDir,
+        target,
+        req.socket.remoteAddress || "unknown"
+      );
+
+      const child = spawn(command, args, {
+        cwd: rootDir,
+        stdio: ["pipe", "pipe", "pipe"],
+        env: process.env,
+      });
+      child.stdin.end();
+      running.set(scriptName, child);
+
+      sendSse(res, "start", {
+        script: scriptName,
+        rootDir,
+        target,
+        subject:
+          authResult.payload && typeof authResult.payload === "object"
+            ? authResult.payload.sub || ""
+            : "",
+        logFile: audit.logFile,
+      });
+
+      child.stdout.on("data", (chunk) => {
+        const text = String(chunk);
+        sendSse(res, "log", { stream: "stdout", text });
+        audit.write({ event: "log", stream: "stdout", text });
+      });
+
+      child.stderr.on("data", (chunk) => {
+        const text = String(chunk);
+        sendSse(res, "log", { stream: "stderr", text });
+        audit.write({ event: "log", stream: "stderr", text });
+      });
+
+      child.on("error", (err) => {
+        sendSse(res, "error", { message: err.message });
+        audit.write({ event: "error", message: err.message });
+      });
+
+      child.on("close", (code, signal) => {
+        running.delete(scriptName);
+        sendSse(res, "end", { code, signal });
+        audit.write({ event: "end", code, signal });
+        audit.close();
+        res.end();
+      });
+
+      req.on("close", () => {
+        if (running.get(scriptName) === child) {
+          audit.write({ event: "client-disconnect" });
+          child.kill("SIGTERM");
+        }
+      });
+      return;
+    }
+
+    send(res, 404, "Not Found");
+  });
+}
+
+function startServer({ scripts, auditDir, port }) {
+  const server = createServer({ scripts, auditDir });
+  server.listen(port, () => {
+    process.stdout.write(`Server listening on http://0.0.0.0:${port}\n`);
+  });
+  return server;
+}
+
+module.exports = {
+  createServer,
+  startServer,
+};