@shidesheng0218/dsh-plugin-lint 0.1.0 → 0.4.0

package/src/probe/environment/docker.js

@@ -0,0 +1,270 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { join } from 'node:path';
+import { ToolError } from '../../shared/errors.js';
+import { safeEnv } from '../dsh-adapter.js';
+
+const IMAGE = 'node:22-bookworm-slim';
+// node:22-bookworm-slim ships npm/npx but not pnpm, and `dsh plugin add`
+// spawns pnpm from PATH. The shim is written into the writable profile mount
+// and prepended to PATH; npx downloads the pinned pnpm on first use.
+// pnpm 9 refuses `pnpm add` in a workspace root without -w; DSH invokes it
+// without that flag, and the profile is a pnpm workspace. pnpm 11 accepts it.
+const PNPM_SPEC = 'pnpm@11';
+const PNPM_SHIM = '#!/bin/sh\nexec npx --yes ' + PNPM_SPEC + ' "$@"\n';
+const CONTAINER_PATH = '/profile/.probe-bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
+const STUB_SCRIPT = `
+import { createServer } from 'node:http';
+import { appendFileSync } from 'node:fs';
+const server = createServer((req, res) => {
+  let raw = '';
+  req.on('data', (chunk) => { raw += chunk; });
+  req.on('end', () => {
+    let body = null;
+    try { body = JSON.parse(raw); } catch { body = null; }
+    if (body) appendFileSync('/profile/stub-seen.jsonl', JSON.stringify(body) + '\\n');
+    if (!body || !body.stream) {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ id: 'msg_probe', type: 'message', role: 'assistant', model: body?.model || 'probe', content: [{ type: 'text', text: 'ok' }], stop_reason: 'end_turn', stop_sequence: null, usage: { input_tokens: 1, output_tokens: 1 } }));
+      return;
+    }
+    const sse = (event, data) => res.write('event: ' + event + '\\ndata: ' + JSON.stringify(data) + '\\n\\n');
+    res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+    sse('message_start', { type: 'message_start', message: { id: 'msg_probe', type: 'message', role: 'assistant', model: body.model || 'probe', content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 1, output_tokens: 1 } } });
+    sse('content_block_start', { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } });
+    sse('content_block_delta', { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'ok' } });
+    sse('content_block_stop', { type: 'content_block_stop', index: 0 });
+    sse('message_delta', { type: 'message_delta', delta: { stop_reason: 'end_turn', stop_sequence: null }, usage: { output_tokens: 1 } });
+    sse('message_stop', { type: 'message_stop' });
+    res.end();
+  });
+});
+server.listen(3000, '0.0.0.0', () => console.log('PROBE_STUB_READY'));
+`;
+
+export async function preflightDocker({ runner, timeoutMs = 10000 }) {
+  await runner('docker', ['version', '--format', '{{.Server.Version}}'], {
+    env: safeEnv(),
+    timeout: timeoutMs,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+  });
+}
+
+export function createDockerEnvironment({ workDir, sourceDir, profileDir, dshDir, toolDir, timeoutMs, network, runner, materialize }) {
+  const containers = new Set();
+  const networks = new Set();
+
+  // `dsh plugin add` spawns pnpm, which node:22-bookworm-slim does not ship.
+  // The shim lives in the writable profile mount and is first on PATH.
+  const probeBin = join(profileDir, '.probe-bin');
+  mkdirSync(probeBin, { recursive: true });
+  writeFileSync(join(probeBin, 'pnpm'), PNPM_SHIM, { mode: 0o755 });
+
+  function dockerArgs(name, dsh, args, env, requestedNetwork, { writableDsh = false } = {}) {
+    const networkName = requestedNetwork === 'registry' || requestedNetwork === 'bridge' ? 'bridge' : (requestedNetwork || 'none');
+    const containerEnv = safeEnv({
+      HOME: '/profile',
+      DSH_HOME: '/profile',
+      NO_COLOR: '1',
+      PATH: CONTAINER_PATH,
+      // The native-addon loader copies .node files into os.tmpdir() and dlopens
+      // them there; Docker mounts /tmp noexec, so the copy cannot be mapped.
+      // Loading straight from the read-only package tree works.
+      NARB_DISABLE_NATIVE_CACHE: '1',
+      // Share the npx/pnpm download cache across cells when the environment
+      // provides a shared tool directory.
+      ...(toolDir ? { npm_config_cache: '/tools/npm' } : {}),
+      ...env,
+    });
+    return [
+      'run', '--rm', '--name', name,
+      '--read-only',
+      '--cap-drop=ALL',
+      '--security-opt=no-new-privileges',
+      '--user=1000:1000',
+      '--pids-limit=128',
+      '--memory=512m',
+      '--cpus=1',
+      `--network=${networkName}`,
+      `--volume=${sourceDir}:/source:ro`,
+      `--volume=${profileDir}:/profile:rw`,
+      `--volume=${dshDir}:/dsh:${writableDsh ? 'rw' : 'ro'}`,
+      ...(toolDir ? [`--volume=${toolDir}:/tools:rw`] : []),
+      '--tmpfs=/tmp:rw,nosuid,nodev,size=128m',
+      '--workdir=/profile',
+      ...Object.entries(containerEnv).map(([key, value]) => `--env=${key}=${value}`),
+      IMAGE,
+      dsh.containerNode || 'node',
+      ...(dsh.extraArgs || []),
+      dsh.containerCli || dsh.cli,
+      ...args,
+    ];
+  }
+
+  /**
+   * Run a container until its output matches `readyRe`, then stop it.
+   *
+   * `execFile` cannot see the readiness line until the (long-lived) web server
+   * exits, so the old code capped every web boot at 15 s: fast boots wasted the
+   * whole cap and slower ones were killed and reported boot-failed. Polling
+   * `docker logs` lets a ready container stop immediately and a slow one use
+   * the full environment timeout. It also keeps the injected `runner` as the
+   * only process boundary, so the path is testable without a daemon.
+   */
+  async function runUntilReady(name, argsForDocker, readyRe, { timeoutMs: limit, graceMs = 2500 } = {}) {
+    const started = Date.now();
+    let settled;
+    const runPromise = runner('docker', argsForDocker, {
+      env: safeEnv(),
+      timeout: limit,
+      encoding: 'utf8',
+      maxBuffer: 32 * 1024 * 1024,
+    }).then((result) => { settled = { result }; })
+      .catch((error) => { settled = { error }; });
+    let out = '';
+    let ready = false;
+    while (!settled && Date.now() - started < limit) {
+      await delay(150);
+      if (settled) break;
+      try {
+        const logs = await runner('docker', ['logs', name], { env: safeEnv(), timeout: 5000, encoding: 'utf8' });
+        out = String(logs.stdout || '') + String(logs.stderr || '');
+        if (readyRe.test(out)) { ready = true; break; }
+      } catch { /* the container may not have started yet */ }
+    }
+    if (ready) await delay(graceMs);
+    // Stop a running container after readiness or timeout; a natural exit makes
+    // this a no-op that fails harmlessly.
+    try {
+      await runner('docker', ['kill', name], { env: safeEnv(), timeout: 5000, encoding: 'utf8' });
+    } catch { /* already exited */ }
+    await runPromise;
+    const final = settled?.result || settled?.error;
+    if (final) out = String(final.stdout || '') + String(final.stderr || '') || out;
+    return out;
+  }
+
+  async function execute(stage, dsh, args, env, requestedNetwork, { writableDsh = false, readyRe, timeoutMs: commandTimeout, graceMs } = {}) {
+    if (dsh.kind === 'desktop') {
+      throw new ToolError('ISOLATION_UNSUPPORTED', 'Desktop DSH is not supported by the Docker backend.');
+    }
+    const name = `dsh-probe-${randomUUID()}`;
+    containers.add(name);
+    const argsForDocker = dockerArgs(name, dsh, args, env, requestedNetwork, { writableDsh });
+    try {
+      if (readyRe) {
+        const out = await runUntilReady(name, argsForDocker, readyRe, {
+          timeoutMs: commandTimeout ?? timeoutMs,
+          graceMs,
+        });
+        return { stage, out, ready: readyRe.test(out) };
+      }
+      const result = await runner('docker', argsForDocker, {
+        env: safeEnv(),
+        timeout: commandTimeout ?? timeoutMs,
+        encoding: 'utf8',
+        maxBuffer: 32 * 1024 * 1024,
+      });
+      return { ...result, stage, out: String(result.stdout || '') + String(result.stderr || '') };
+    } catch (error) {
+      const out = String(error.stdout || '') + String(error.stderr || '');
+      if (readyRe?.test(out)) return { stage, out, ready: true };
+      throw error;
+    }
+  }
+
+  return {
+    backend: 'docker',
+    isolation: 'docker',
+    workDir,
+    sourceDir,
+    profileDir,
+    dshDir,
+    materialize,
+    async install({ dsh, target, profile = 'headless', env = {} }) {
+      const installTarget = typeof target === 'string' ? target : target?.installTarget;
+      if (!installTarget) throw new ToolError('ARTIFACT_MISSING', 'No pinned artifact was provided for installation.');
+      return execute('install', dsh, ['plugin', '--profile', profile, 'add', installTarget], env, 'registry');
+    },
+    async boot({ dsh, args, env = {}, network: bootNetwork, writableDsh = false, readyRe, graceMs, timeoutMs: bootTimeout }) {
+      return execute('boot', dsh, args, env, bootNetwork || network, { writableDsh, readyRe, graceMs, timeoutMs: bootTimeout });
+    },
+    async startStub() {
+      const networkName = `dsh-probe-net-${randomUUID()}`;
+      const stubName = `dsh-probe-stub-${randomUUID()}`;
+      writeFileSync(join(sourceDir, 'probe-stub.mjs'), STUB_SCRIPT);
+      networks.add(networkName);
+      await runner('docker', ['network', 'create', '--internal', networkName], { env: safeEnv(), timeout: 10000, encoding: 'utf8' });
+      containers.add(stubName);
+      await runner('docker', [
+        'run', '-d', '--rm', '--name', stubName,
+        '--network', networkName,
+        '--network-alias', 'probe-stub',
+        '--read-only',
+        '--cap-drop=ALL',
+        '--security-opt=no-new-privileges',
+        '--user=1000:1000',
+        '--pids-limit=64',
+        '--memory=256m',
+        '--cpus=0.5',
+        `--volume=${sourceDir}:/source:ro`,
+        `--volume=${profileDir}:/profile:rw`,
+        '--tmpfs=/tmp:rw,nosuid,nodev,size=64m',
+        '--env=HOME=/profile',
+        IMAGE,
+        'node', '/source/probe-stub.mjs',
+      ], { env: safeEnv(), timeout: 30000, encoding: 'utf8' });
+      let ready = false;
+      for (let attempt = 0; attempt < 40 && !ready; attempt += 1) {
+        const result = await runner('docker', ['logs', stubName], { env: safeEnv(), timeout: 5000, encoding: 'utf8' });
+        ready = String(result.stdout || '').includes('PROBE_STUB_READY');
+        if (!ready) await delay(25);
+      }
+      if (!ready) throw new ToolError('ISOLATION_UNAVAILABLE', 'The isolated stub did not become ready.');
+      const seen = [];
+      let offset = 0;
+      return {
+        baseURL: 'http://probe-stub:3000',
+        network: networkName,
+        port: 3000,
+        seen,
+        async sync() {
+          const path = join(profileDir, 'stub-seen.jsonl');
+          if (!existsSync(path)) return;
+          const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+          for (const line of lines.slice(offset)) {
+            try { seen.push(JSON.parse(line)); } catch { /* incomplete final record */ }
+          }
+          offset = lines.length;
+        },
+      };
+    },
+    async destroy() {
+      const removals = [...containers].map((name) => runner('docker', ['rm', '-f', name], {
+        env: safeEnv(),
+        timeout: 10000,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+      }));
+      await Promise.allSettled(removals);
+      containers.clear();
+      const networkRemovals = [...networks].map((name) => runner('docker', ['network', 'rm', name], {
+        env: safeEnv(),
+        timeout: 10000,
+        encoding: 'utf8',
+      }));
+      await Promise.allSettled(networkRemovals);
+      networks.clear();
+      try {
+        rmSync(workDir, { recursive: true, force: true });
+      } catch {
+        // The container writes npm cache directories as uid 1000; the host user
+        // may not be able to traverse them. The tree lives under the per-run
+        // temp root and is reclaimed by the OS, so a cleanup failure must not
+        // turn a completed observation into an error.
+      }
+    },
+  };
+}

package/src/probe/environment/host-unsafe.js

@@ -0,0 +1,39 @@
+import { rmSync } from 'node:fs';
+import { ToolError } from '../../shared/errors.js';
+import { runDsh, runUntilReady } from '../dsh-adapter.js';
+
+export function createHostUnsafeEnvironment({ workDir, profileDir, dshDir, timeoutMs, runner, materialize }) {
+  // DSH_HOME must be the profile root. The Docker backend mounts the same
+  // directory at /profile, so the probe reads profiles/<name> from one place in
+  // both backends. Before this, the host backend set DSH_HOME to workDir while
+  // probe.js read profileDir, and every non-Docker probe ended in TEMPLATE_FAILED.
+  return {
+    backend: 'host-unsafe',
+    isolation: 'host-unsafe',
+    warning: 'UNSAFE: plugin code runs on the host without container isolation.',
+    workDir,
+    profileDir,
+    dshDir,
+    materialize,
+    async install({ dsh, target, profile = 'headless', env = {} }) {
+      const installTarget = typeof target === 'string' ? target : target?.hostPath || target?.installTarget || target?.path;
+      if (!installTarget) throw new ToolError('ARTIFACT_MISSING', 'No artifact was provided for installation.');
+      const out = await runDsh(dsh, profileDir, ['plugin', '--profile', profile, 'add', installTarget], env, { runner, timeoutMs });
+      return { out };
+    },
+    async boot({ dsh, args, env = {}, readyRe, graceMs = 2500 }) {
+      const out = readyRe
+        ? await runUntilReady(dsh, profileDir, args, env, readyRe, { timeoutMs, graceMs })
+        : await runDsh(dsh, profileDir, args, env, { runner, timeoutMs });
+      return { out };
+    },
+    async destroy() {
+      try {
+        rmSync(workDir, { recursive: true, force: true });
+      } catch {
+        // Same rationale as the Docker backend: the per-run tree is disposable
+        // and a cleanup failure must not rewrite the verdict.
+      }
+    },
+  };
+}

package/src/probe/environment/materialize.js

@@ -0,0 +1,22 @@
+import { copyFileSync, cpSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { ToolError } from '../../shared/errors.js';
+
+export async function materializeArtifact(artifact, sourceDir) {
+  const sourcePath = artifact?.tarballPath || artifact?.path;
+  if (!sourcePath) throw new ToolError('ARTIFACT_MISSING', 'The artifact has no local file or directory to materialize.');
+  let stat;
+  try {
+    stat = statSync(sourcePath);
+  } catch (cause) {
+    throw new ToolError('ARTIFACT_MISSING', 'The artifact source is missing or unreadable.', { cause });
+  }
+  const name = stat.isDirectory()
+    ? String(artifact.name || basename(sourcePath)).replace(/[^A-Za-z0-9._-]/g, '_')
+    : basename(sourcePath);
+  const hostPath = join(sourceDir, name);
+  if (stat.isDirectory()) cpSync(sourcePath, hostPath, { recursive: true, force: true });
+  else copyFileSync(sourcePath, hostPath);
+  const containerPath = `/source/${name}`;
+  return { ...artifact, hostPath, containerPath, installTarget: containerPath };
+}

package/src/probe/environment.js

@@ -0,0 +1,50 @@
+import { chmodSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { execFileRunner } from './dsh-adapter.js';
+import { createDockerEnvironment, preflightDocker } from './environment/docker.js';
+import { createHostUnsafeEnvironment } from './environment/host-unsafe.js';
+import { materializeArtifact } from './environment/materialize.js';
+
+export async function createProbeEnvironment({
+  backend = 'auto',
+  workDir,
+  dshDir: sharedDshDir,
+  timeoutMs = 180000,
+  network = 'none',
+  runner = execFileRunner,
+} = {}) {
+  const parent = workDir ? resolve(workDir) : tmpdir();
+  mkdirSync(parent, { recursive: true });
+  const root = mkdtempSync(join(parent, 'dsh-probe-'));
+  const sourceDir = join(root, 'source');
+  const profileDir = join(root, 'profile');
+  // A shared dshDir (one per DSH version under the cache root) lets consecutive
+  // probe cells reuse the harness install instead of downloading it per cell.
+  const dshDir = sharedDshDir ? resolve(sharedDshDir) : join(root, 'dsh');
+  // The npm cache behind the pnpm shim is shared too: without it every cell
+  // re-downloads pnpm before it can install the plugin.
+  const toolDir = join(parent, '.probe-tools');
+  for (const dir of [sourceDir, profileDir, dshDir, toolDir]) mkdirSync(dir, { recursive: true });
+  chmodSync(root, 0o755);
+  chmodSync(sourceDir, 0o755);
+  chmodSync(profileDir, 0o777);
+  chmodSync(dshDir, 0o777);
+  chmodSync(toolDir, 0o777);
+  const materialize = (artifact) => materializeArtifact(artifact, sourceDir);
+  try {
+    if (backend === 'host-unsafe') {
+      return createHostUnsafeEnvironment({ workDir: root, profileDir, dshDir, timeoutMs, runner, materialize });
+    }
+    if (backend !== 'auto' && backend !== 'docker') {
+      throw new ToolError('ISOLATION_UNSUPPORTED', `Unsupported probe backend: ${backend}`);
+    }
+    await preflightDocker({ runner, timeoutMs: Math.min(timeoutMs, 10000) });
+    return createDockerEnvironment({ workDir: root, sourceDir, profileDir, dshDir, toolDir, timeoutMs, network, runner, materialize });
+  } catch (error) {
+    rmSync(root, { recursive: true, force: true });
+    if (error instanceof ToolError) throw error;
+    throw new ToolError('ISOLATION_UNAVAILABLE', 'Docker is unavailable; no plugin code was executed.', { cause: error });
+  }
+}

package/src/probe/installed-artifact.js

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+
+export function readInstalledArtifact(profileDir, name) {
+  if (typeof name !== 'string' || name.includes('..') || name.startsWith('/') || name.startsWith('\\')) {
+    throw new ToolError('ARTIFACT_MISSING', 'The installed artifact name is invalid.');
+  }
+  const path = join(profileDir, 'node_modules', ...name.split('/'));
+  try {
+    const manifest = JSON.parse(readFileSync(join(path, 'package.json'), 'utf8'));
+    if (typeof manifest.version !== 'string' || !manifest.version) throw new Error('missing version');
+    return { version: manifest.version, path };
+  } catch (cause) {
+    throw new ToolError('ARTIFACT_MISSING', `The installed manifest for ${name} is missing or unreadable.`, { cause });
+  }
+}