@pulsehub/runner 0.1.4 → 0.1.6

package/src/runtime.js

@@ -0,0 +1,301 @@
+import { appendFile, chmod, mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureDataDir, paths, readCredential, readProfiles, removeTemporary } from './config.js';
+import { validateJob, sanitize } from './job.js';
+import { command, resolveExecutable, runAgent } from './process.js';
+import { addIsolatedWorktree, removeIsolatedWorktree } from './worktree.js';
+import { resolveProfile, validateLocalRepo } from './profile.js';
+import { inspectReadiness, assertLocalReadiness, localIdentities } from './readiness.js';
+
+export async function logEvent(event, details = {}) {
+  try {
+    const p = await ensureDataDir();
+    const safeDetails = Object.fromEntries(Object.entries(details).map(([key, value]) => [
+      key,
+      typeof value === 'string' ? sanitize(value) : value,
+    ]));
+    const file = join(p.logs, 'runner.jsonl');
+    await appendFile(file, `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...safeDetails })}\n`, { mode: 0o600 });
+    await chmod(file, 0o600);
+  } catch {
+    // Logging must not turn a successfully completed job into a failed one.
+  }
+}
+
+export async function request(config, path, body) {
+  const credential = await readCredential();
+  if (!credential) throw new Error('Runner is not paired. Run pulse-runner pair first.');
+  const response = await fetch(`${config.endpoint}/${path}`, { method: 'POST', headers: { Authorization: `Bearer ${credential}`, 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(10_000) });
+  if (!response.ok) throw Object.assign(new Error(`Pulse endpoint rejected request (${response.status}).`), { status: response.status });
+  return response.json();
+}
+
+function repoPath(repo) { return repo.replace('/', '__'); }
+function failureDetail(output) {
+  return sanitize(output).split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3).join(' | ').slice(-240);
+}
+function completionSummary(result, publication) {
+  const entries = [{
+    label: result.code === 0 ? 'Agent completed' : `Agent failed (exit ${result.code})`,
+    detail: result.code === 0 ? '' : failureDetail(result.output),
+  }];
+  for (const published of publication.succeeded) entries.push({ label: 'Publication succeeded', detail: published });
+  for (const failed of publication.failed) entries.push({
+    label: `Publication failed for ${failed.repo} during ${failed.phase}`,
+    detail: failureDetail(failed.error),
+  });
+  const detailCount = entries.filter((entry) => entry.detail).length;
+  const prefixSize = entries.reduce((sum, entry) => sum + entry.label.length + (entry.detail ? 2 : 0), 0) + entries.length - 1;
+  const detailBudget = detailCount ? Math.max(0, Math.floor((480 - prefixSize) / detailCount)) : 0;
+  return entries.map(({ label, detail }) => detail && detailBudget ? `${label}: ${detail.slice(-detailBudget)}` : label).join('\n').slice(-500);
+}
+async function checkoutRepo(repo, worktree, signal, sourceDirectory) {
+  if (sourceDirectory) return addIsolatedWorktree(repo, sourceDirectory, worktree, { signal, sourceDirectory });
+  const p = paths(); const mirror = join(p.repos, `${repoPath(repo)}.git`);
+  const existing = await command('git', ['--git-dir', mirror, 'rev-parse', '--git-dir']).catch(() => ({ code: 1, output: '' }));
+  if (existing.code !== 0) {
+    const cloned = await command('git', ['clone', '--mirror', `https://github.com/${repo}.git`, mirror], { signal, timeout: 120_000 });
+    if (cloned.code !== 0) throw new Error(sanitize(cloned.output));
+  }
+  const fetchResult = await command('git', ['--git-dir', mirror, 'fetch', '--prune', 'origin'], { signal, timeout: 120_000 }); if (fetchResult.code !== 0) throw new Error(sanitize(fetchResult.output));
+  return addIsolatedWorktree(repo, mirror, worktree, { signal });
+}
+async function checkout(job, options = {}) {
+  const root = join(paths().worktrees, job.id); const repos = [...new Set(job.contextRepos || [job.repoFullName])]; const checkouts = [];
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  try {
+    for (const repo of repos) {
+      const checkout = await checkoutRepo(repo, join(root, repoPath(repo)), options.signal, repo === job.repoFullName ? options.profile?.directory : undefined);
+      await writeFile(join(checkout.worktree, '.pulse-runner-job'), job.id, { mode: 0o600 });
+      checkouts.push(checkout);
+    }
+    const primary = checkouts.find((checkout) => checkout.repo === job.repoFullName);
+    if (!primary) throw new Error('Job context does not include its target repository.');
+    return { primary, checkouts };
+  } catch (error) { await cleanup(checkouts); await removeTemporary(root); throw error; }
+}
+async function cleanup(checkouts) {
+  await Promise.all(checkouts.map(async ({ worktree, mirror, sourceDirectory }) => {
+    await removeIsolatedWorktree({ mirror, worktree, sourceDirectory });
+    await removeTemporary(worktree);
+  }));
+}
+async function publishCheckout(checkout, jobId, checkActive, signal) {
+  const branchResult = await command('git', ['-C', checkout.worktree, 'branch', '--show-current'], { signal });
+  const branch = branchResult.output.trim();
+  if (!branch || !branch.startsWith('pul/')) {
+    await logEvent('publication.skipped', { jobId, repo: checkout.repo, reason: 'branch-not-pulse' });
+    return '';
+  }
+  let phase = 'validate-commit';
+  const status = await command('git', ['-C', checkout.worktree, 'status', '--porcelain'], { signal });
+  const uncommitted = status.output.split('\n').filter((line) => line && !line.endsWith('.pulse-runner-job'));
+  if (uncommitted.length > 0) throw Object.assign(new Error(`Uncommitted changes remain in ${checkout.repo}; the agent must commit every changed worktree.`), { phase });
+  phase = 'inspect-commit';
+  const head = await command('git', ['-C', checkout.worktree, 'rev-parse', 'HEAD'], { signal });
+  if (head.code !== 0) throw Object.assign(new Error(sanitize(head.output)), { phase });
+  if (head.output.trim() === checkout.baseCommit) {
+    await logEvent('publication.skipped', { jobId, repo: checkout.repo, branch, reason: 'no-commits' });
+    return '';
+  }
+  // Sólo se publica una rama de trabajo Pulse de un worktree firmado como
+  // contexto de este job. El Runner no elige repos ni destinos externos.
+  phase = 'push';
+  await logEvent('publication.started', { jobId, repo: checkout.repo, branch, phase });
+  await checkActive();
+  const pushed = await command('git', [...(checkout.sourceDirectory ? ['-C', checkout.worktree] : ['-c', 'remote.origin.mirror=false', '--git-dir', checkout.mirror]), 'push', 'origin', `refs/heads/${branch}:refs/heads/${branch}`], { signal, timeout: 120_000 });
+  if (pushed.code !== 0) throw Object.assign(new Error(sanitize(pushed.output)), { phase });
+  await logEvent('publication.pushed', { jobId, repo: checkout.repo, branch, phase });
+  phase = 'find-pull-request';
+  const existing = await command(resolveExecutable('gh'), ['pr', 'view', branch, '--repo', checkout.repo, '--json', 'url'], { signal, timeout: 30_000 });
+  if (existing.code === 0) {
+    await logEvent('publication.pull-request-exists', { jobId, repo: checkout.repo, branch });
+    return `Published ${checkout.repo}:${branch}; existing PR detected.`;
+  }
+  if (!/no pull requests found/i.test(existing.output)) throw Object.assign(new Error(sanitize(existing.output)), { phase });
+  phase = 'create-pull-request';
+  await checkActive();
+  const created = await command(resolveExecutable('gh'), ['pr', 'create', '--repo', checkout.repo, '--base', 'main', '--head', branch, '--fill'], { signal, timeout: 30_000 });
+  if (created.code !== 0) throw Object.assign(new Error(sanitize(created.output)), { phase });
+  await logEvent('publication.pull-request-created', { jobId, repo: checkout.repo, branch, url: created.output.trim() });
+  return `Published ${checkout.repo}:${branch}; ${created.output.trim()}`;
+}
+async function publish(checkouts, jobId, checkActive, signal) {
+  const publications = { succeeded: [], failed: [] };
+  for (const checkout of checkouts) {
+    try {
+      const published = await publishCheckout(checkout, jobId, checkActive, signal);
+      if (published) publications.succeeded.push(published);
+    } catch (error) {
+      if (error.name === 'AbortError') throw error;
+      const failure = { repo: checkout.repo, phase: error.phase || 'prepare', error: sanitize(error.message) };
+      publications.failed.push(failure);
+      await logEvent('publication.failed', { jobId, ...failure });
+    }
+  }
+  return publications;
+}
+let readinessCache;
+async function readinessFor(config, force = false) {
+  const key = JSON.stringify([config.workspaceId, localIdentities(config), config.repos]);
+  if (force || !readinessCache || readinessCache.key !== key || Date.now() - readinessCache.at > 60_000) readinessCache = { key, at: Date.now(), value: await inspectReadiness(config) };
+  return readinessCache.value;
+}
+/** Run one delivered job. Dependencies allow integration tests to use a local control plane. */
+export async function runOnce(config, options = {}) {
+  const remote = options.request || request;
+  const readinessForJob = options.readinessFor || readinessFor;
+  const prepare = options.checkout || checkout;
+  const publishWork = options.publish || publish;
+  const cleanWork = options.cleanup || cleanup;
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  if (options.signal?.aborted) return false;
+  options.signal?.addEventListener('abort', cancel, { once: true });
+  let watcher;
+  let expiryTimer;
+  const stopWatching = new AbortController();
+  let job;
+  let jobPhase = 'poll';
+  let completionReported = false;
+  const journal = join(paths().root, 'active-job.json');
+  const checkActive = async () => {
+    controller.signal.throwIfAborted();
+    if (Date.parse(job.expiresAt) <= Date.now()) controller.abort();
+    const response = await remote(config, 'pulseRunnerHeartbeat', { status: 'busy', jobId: job.id });
+    if (response.cancelRequested) controller.abort();
+    controller.signal.throwIfAborted();
+  };
+  try {
+    const readiness = await readinessForJob(config);
+    await remote(config, 'pulseRunnerHeartbeat', { status: 'online', readiness });
+    const delivery = await remote(config, 'pulseRunnerPoll', {});
+    if (!delivery.job) return false;
+    job = delivery.job;
+    await logEvent('job.received', { jobId: job.id, issueId: job.issueId, agentId: job.agentId, mode: job.mode, repo: job.repoFullName });
+    jobPhase = 'validate-job';
+    const agent = delivery.agent || { kind: config.agentKind, role: job.agentId === config.agentId ? 'dev' : null };
+    validateJob(job, config, agent);
+    jobPhase = 'local-preflight';
+    const profile = await resolveProfile({ ...config, agentKind: agent.kind }, job);
+    const jobConfig = job.protocolVersion === 2 ? { ...config, repos: job.contextRepos || [job.repoFullName] } : config;
+    assertLocalReadiness(job, jobConfig, agent, await readinessForJob(jobConfig, true));
+    await logEvent('job.validated', { jobId: job.id, repoCount: (job.contextRepos || [job.repoFullName]).length });
+    await checkActive();
+    expiryTimer = setTimeout(cancel, Math.max(0, Date.parse(job.expiresAt) - Date.now()));
+    expiryTimer.unref();
+    // Heartbeat stays outbound while the CLI runs. Losing authorization or
+    // contact with Pulse stops local execution rather than publishing blindly.
+    watcher = (async () => {
+      while (!stopWatching.signal.aborted) {
+        await new Promise((resolve) => {
+          const done = () => { clearTimeout(timer); stopWatching.signal.removeEventListener('abort', done); resolve(); };
+          const timer = setTimeout(done, options.heartbeatIntervalMs || 2000);
+          stopWatching.signal.addEventListener('abort', done, { once: true });
+        });
+        if (stopWatching.signal.aborted) break;
+        try { await checkActive(); } catch { controller.abort(); break; }
+      }
+    })();
+    jobPhase = 'prepare-worktrees';
+    await writeFile(journal, JSON.stringify({ jobId: job.id }), { mode: 0o600 });
+    await chmod(journal, 0o600);
+    const { primary, checkouts } = await prepare(job, { signal: controller.signal, profile });
+    const temp = join(paths().root, 'tmp', job.id);
+    let completion;
+    try {
+      controller.signal.throwIfAborted();
+      jobPhase = 'run-agent';
+      await logEvent('agent.started', { jobId: job.id, repo: primary.repo, mode: job.mode });
+      const result = await runAgent(agent.kind, job, primary.worktree, checkouts.filter((entry) => entry !== primary), config, delivery.mcpCredential, temp, { signal: controller.signal, profile });
+      controller.signal.throwIfAborted();
+      await checkActive();
+      await logEvent(result.code === 0 ? 'agent.completed' : 'agent.failed', { jobId: job.id, exitCode: result.code, ...(result.code === 0 ? {} : { error: failureDetail(result.output) }) });
+      jobPhase = 'publication';
+      const publication = result.code === 0 && job.mode !== 'review' ? await publishWork(checkouts, job.id, checkActive, controller.signal) : { succeeded: [], failed: [] };
+      await checkActive();
+      const outcome = result.code === 0 && publication.failed.length === 0 ? 'completed' : 'failed';
+      const failure = outcome === 'failed' ? { phase: result.code !== 0 ? 'run-agent' : publication.failed[0]?.phase || 'publication', category: 'execution', correlationId: job.id } : null;
+      jobPhase = 'report-completion';
+      completion = { jobId: job.id, outcome, result: sanitize(completionSummary(result, publication)), failure };
+    } finally {
+      await removeTemporary(temp);
+      await cleanWork(checkouts);
+      await removeTemporary(join(paths().worktrees, job.id));
+    }
+    controller.signal.throwIfAborted();
+    await remote(config, 'pulseRunnerComplete', completion);
+    completionReported = true;
+    await logEvent('job.completed', { jobId: job.id, outcome: completion.outcome });
+  } catch (error) {
+    if (!job) throw error;
+    const canceled = controller.signal.aborted;
+    const phase = error.phase || jobPhase;
+    const message = canceled ? 'Job canceled; local execution stopped.' : error?.message || String(error);
+    await logEvent(canceled ? 'job.canceled' : 'job.failed', { jobId: job.id, phase, error: message });
+    await remote(config, 'pulseRunnerComplete', { jobId: job.id, outcome: canceled ? 'canceled' : 'failed', result: sanitize(`${phase}: ${message}`), failure: canceled ? null : { phase, category: phase === 'validate-job' ? 'configuration' : ['local-preflight', 'prepare-worktrees'].includes(phase) ? 'local_preparation' : 'execution', correlationId: job.id } }).then(() => { completionReported = true; }).catch(async (completionError) => {
+      await logEvent('job.completion-report-failed', { jobId: job.id, error: completionError.message });
+    });
+    if (!canceled) throw error;
+  } finally {
+    stopWatching.abort();
+    if (expiryTimer) clearTimeout(expiryTimer);
+    await watcher;
+    if (completionReported) await rm(journal, { force: true });
+    options.signal?.removeEventListener('abort', cancel);
+    if (job) await remote(config, 'pulseRunnerHeartbeat', { status: 'online' }).catch(() => {});
+  }
+  return true;
+}
+
+export async function recoverInterruptedWork(config) {
+  const p = await ensureDataDir();
+  for (const area of [p.worktrees, join(p.root, 'tmp')]) {
+    await mkdir(area, { recursive: true, mode: 0o700 });
+    const jobs = await readdir(area, { withFileTypes: true });
+    await Promise.all(jobs.map((entry) => rm(join(area, entry.name), { recursive: true, force: true })));
+  }
+  const repositories = await readdir(p.repos, { withFileTypes: true });
+  await Promise.all(repositories.filter((entry) => entry.isDirectory()).map((entry) => command('git', ['--git-dir', join(p.repos, entry.name), 'worktree', 'prune']).catch(() => {})));
+  const profiles = await readProfiles();
+  for (const profile of Object.values(profiles)) {
+    for (const [repo, directory] of Object.entries(profile.directories || {})) {
+      const source = await validateLocalRepo(config, repo, directory).catch(() => null);
+      if (source) await command('git', ['-C', source, 'worktree', 'prune']).catch(() => {});
+    }
+  }
+  if (config) {
+    const journal = join(p.root, 'active-job.json');
+    const interrupted = await readFile(journal, 'utf8').then(JSON.parse).catch((error) => {
+      if (error.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (interrupted) {
+      await request(config, 'pulseRunnerComplete', { jobId: interrupted.jobId, outcome: 'canceled', result: 'Runner restarted; interrupted worktrees and temporary MCP files cleaned.' }).catch((error) => {
+        if (![404, 409].includes(error.status)) throw error;
+      });
+      await rm(journal, { force: true });
+    }
+  }
+}
+
+/** A per-data-directory lock covers both the daemon and one-shot execution. */
+export async function withRunnerLock(run) {
+  const p = await ensureDataDir();
+  const lockPath = join(p.root, 'runner.lock');
+  let lock;
+  try { lock = await open(lockPath, 'wx', 0o600); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const pid = Number((await readFile(lockPath, 'utf8')).trim());
+    let active = false;
+    if (Number.isInteger(pid) && pid > 0) {
+      try { process.kill(pid, 0); active = true; } catch (probeError) { active = probeError.code !== 'ESRCH'; }
+    } else active = Date.now() - (await stat(lockPath)).mtimeMs < 10_000;
+    if (active) throw new Error('Pulse Runner is already active.');
+    await rm(lockPath, { force: true });
+    lock = await open(lockPath, 'wx', 0o600);
+  }
+  try { await lock.writeFile(`${process.pid}\n`); return await run(); }
+  finally { await lock.close(); await rm(lockPath, { force: true }); }
+}

package/src/service.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { ensureDataDir } from './config.js';
+import { command as nativeCommand } from './process.js';
+import { sanitize } from './job.js';
+
+export async function service(action, options = {}) {
+  const p = await ensureDataDir();
+  const os = options.platform || platform();
+  const userId = options.userId ?? process.getuid?.() ?? 0;
+  const userHome = options.userHome || homedir();
+  const command = options.command || nativeCommand;
+  const print = options.print || console.log;
+  const scriptPath = fileURLToPath(new URL('./index.js', import.meta.url));
+  const instance = createHash('sha256').update(p.root).digest('hex').slice(0, 12);
+  const label = `com.pulse.runner.${instance}`;
+  const unitName = `pulse-runner-${instance}.service`;
+  const taskName = `PulseRunner-${instance}`;
+  const launchAgent = join(userHome, 'Library', 'LaunchAgents', `${label}.plist`);
+  const systemdDir = join((!options.userHome && process.env.XDG_CONFIG_HOME) || join(userHome, '.config'), 'systemd', 'user');
+  const unitPath = join(systemdDir, unitName);
+  const lockPath = join(p.root, 'runner.lock');
+  const xml = (value) => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+  const manager = async (exe, argv) => { const result = await command(exe, argv); if (result.code !== 0) throw new Error(sanitize(result.output)); };
+  const unitValue = (value) => String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '').replaceAll('\r', '');
+  const currentPid = async () => { try { return Number((await readFile(lockPath, 'utf8')).trim()); } catch { return 0; } };
+
+  if (action === 'install') {
+    if (os === 'darwin') {
+      await mkdir(join(userHome, 'Library', 'LaunchAgents'), { recursive: true, mode: 0o700 });
+      const plist = `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(scriptPath)}</string><string>start</string><string>--home</string><string>${xml(p.root)}</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(process.env.PATH || '')}</string></dict><key>StandardOutPath</key><string>${xml(join(p.logs, 'service.log'))}</string><key>StandardErrorPath</key><string>${xml(join(p.logs, 'service.log'))}</string></dict></plist>`;
+      await writeFile(launchAgent, plist, { mode: 0o600 });
+      await command('launchctl', ['bootout', `gui/${userId}/${label}`]).catch(() => {});
+      await manager('launchctl', ['bootstrap', `gui/${userId}`, launchAgent]);
+    } else if (os === 'linux') {
+      await mkdir(systemdDir, { recursive: true, mode: 0o700 });
+      const unit = `[Unit]\nDescription=Pulse local Runner\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart="${unitValue(process.execPath)}" "${unitValue(scriptPath)}" start --home "${unitValue(p.root)}"\nRestart=on-failure\nRestartSec=5\nEnvironment="PATH=${unitValue(process.env.PATH || '/usr/local/bin:/usr/bin:/bin')}"\n\n[Install]\nWantedBy=default.target\n`;
+      await writeFile(unitPath, unit, { mode: 0o600 });
+      await manager('systemctl', ['--user', 'daemon-reload']);
+      await manager('systemctl', ['--user', 'enable', '--now', unitName]);
+    } else if (os === 'win32') {
+      await manager('schtasks', ['/Create', '/SC', 'ONLOGON', '/TN', taskName, '/TR', `"${process.execPath}" "${scriptPath}" start --home "${p.root}"`, '/RL', 'LIMITED', '/F']);
+      await manager('schtasks', ['/Run', '/TN', taskName]);
+    } else throw new Error(`Service installation is not supported on ${os}.`);
+    return print('Pulse Runner is installed as a per-user background service.');
+  }
+
+  if (action === 'uninstall') {
+    if (os === 'darwin') { await command('launchctl', ['bootout', `gui/${userId}/${label}`]).catch(() => {}); await rm(launchAgent, { force: true }); }
+    else if (os === 'linux') { await command('systemctl', ['--user', 'disable', '--now', unitName]).catch(() => {}); await rm(unitPath, { force: true }); await command('systemctl', ['--user', 'daemon-reload']).catch(() => {}); }
+    else if (os === 'win32') { await command('schtasks', ['/End', '/TN', taskName]).catch(() => {}); await command('schtasks', ['/Delete', '/TN', taskName, '/F']).catch(() => {}); }
+    return print('Pulse Runner background service removed.');
+  }
+  if (action === 'start') {
+    if (os === 'darwin') {
+      await command('launchctl', ['bootstrap', `gui/${userId}`, launchAgent]).catch(() => {});
+      await manager('launchctl', ['kickstart', `gui/${userId}/${label}`]);
+    }
+    else if (os === 'linux') await manager('systemctl', ['--user', 'start', unitName]);
+    else if (os === 'win32') await manager('schtasks', ['/Run', '/TN', taskName]);
+    else throw new Error(`Service management is not supported on ${os}.`);
+    return print('Pulse Runner service started.');
+  }
+  if (action === 'stop') {
+    if (os === 'darwin') await command('launchctl', ['bootout', `gui/${userId}/${label}`]).catch(() => {});
+    else if (os === 'linux') await command('systemctl', ['--user', 'stop', unitName]).catch(() => {});
+    else if (os === 'win32') {
+      const processId = await currentPid();
+      if (processId) { try { process.kill(processId, 'SIGTERM'); } catch {} }
+      await command('schtasks', ['/End', '/TN', taskName]).catch(() => {});
+    }
+    return print('Pulse Runner service stopped.');
+  }
+  if (action === 'status') {
+    const processId = await currentPid();
+    if (processId) { try { process.kill(processId, 0); return print(`Pulse Runner is running (pid ${processId}).`); } catch {} }
+    return print('Pulse Runner is stopped.');
+  }
+  throw new Error('Supported service commands: install, start, stop, status, uninstall.');
+}

package/src/worktree.js

@@ -0,0 +1,19 @@
+import { command } from './process.js';
+import { sanitize } from './job.js';
+
+export async function addIsolatedWorktree(repo, gitDir, worktree, options = {}) {
+  options.signal?.throwIfAborted();
+  const prefix = options.sourceDirectory ? ['-C', options.sourceDirectory] : ['--git-dir', gitDir];
+  const added = await command('git', [...prefix, 'worktree', 'add', '--detach', worktree, 'HEAD'], options);
+  if (added.code !== 0) throw new Error(sanitize(added.output));
+  const base = await command('git', ['-C', worktree, 'rev-parse', 'HEAD'], options);
+  if (base.code !== 0) {
+    await command('git', [...prefix, 'worktree', 'remove', '--force', worktree]).catch(() => {});
+    throw new Error(sanitize(base.output));
+  }
+  return { repo, mirror: options.sourceDirectory ? null : gitDir, sourceDirectory: options.sourceDirectory, worktree, baseCommit: base.output.trim() };
+}
+
+export async function removeIsolatedWorktree(checkout) {
+  await command('git', [...(checkout.sourceDirectory ? ['-C', checkout.sourceDirectory] : ['--git-dir', checkout.mirror]), 'worktree', 'remove', '--force', checkout.worktree]).catch(() => {});
+}