dsh-plugin-cc 0.1.0

package/plugins/dsh/scripts/lib/tracked-jobs.mjs

@@ -0,0 +1,242 @@
+import fs from "node:fs";
+import process from "node:process";
+
+import { readJobFile, resolveJobFile, resolveJobLogFile, upsertJob, withStateLock, writeJobFile } from "./state.mjs";
+
+export const SESSION_ID_ENV = "DSH_COMPANION_SESSION_ID";
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeProgressEvent(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return {
+      message: String(value.message ?? "").trim(),
+      phase: typeof value.phase === "string" && value.phase.trim() ? value.phase.trim() : null,
+      dshSessionId:
+        typeof value.dshSessionId === "string" && value.dshSessionId.trim() ? value.dshSessionId.trim() : null,
+      stderrMessage: value.stderrMessage == null ? null : String(value.stderrMessage).trim(),
+      logTitle: typeof value.logTitle === "string" && value.logTitle.trim() ? value.logTitle.trim() : null,
+      logBody: value.logBody == null ? null : String(value.logBody).trimEnd()
+    };
+  }
+
+  return {
+    message: String(value ?? "").trim(),
+    phase: null,
+    dshSessionId: null,
+    stderrMessage: String(value ?? "").trim(),
+    logTitle: null,
+    logBody: null
+  };
+}
+
+export function appendLogLine(logFile, message) {
+  const normalized = String(message ?? "").trim();
+  if (!logFile || !normalized) {
+    return;
+  }
+  fs.appendFileSync(logFile, `[${nowIso()}] ${normalized}\n`, "utf8");
+}
+
+export function appendLogBlock(logFile, title, body) {
+  if (!logFile || !body) {
+    return;
+  }
+  fs.appendFileSync(logFile, `\n[${nowIso()}] ${title}\n${String(body).trimEnd()}\n`, "utf8");
+}
+
+export function createJobLogFile(workspaceRoot, jobId, title) {
+  const logFile = resolveJobLogFile(workspaceRoot, jobId);
+  fs.writeFileSync(logFile, "", "utf8");
+  if (title) {
+    appendLogLine(logFile, `Starting ${title}.`);
+  }
+  return logFile;
+}
+
+export function createJobRecord(base, options = {}) {
+  const env = options.env ?? process.env;
+  const sessionId = env[options.sessionIdEnv ?? SESSION_ID_ENV];
+  return {
+    ...base,
+    createdAt: nowIso(),
+    ...(sessionId ? { sessionId } : {})
+  };
+}
+
+function readStoredJobOrNull(workspaceRoot, jobId) {
+  const jobFile = resolveJobFile(workspaceRoot, jobId);
+  if (!fs.existsSync(jobFile)) {
+    return null;
+  }
+  return readJobFile(jobFile);
+}
+
+// Records phase and dsh session id changes in both the state index and the job file.
+export function createJobProgressUpdater(workspaceRoot, jobId) {
+  let lastPhase = null;
+  let lastDshSessionId = null;
+
+  return (event) => {
+    const normalized = normalizeProgressEvent(event);
+    const patch = { id: jobId };
+    let changed = false;
+
+    if (normalized.phase && normalized.phase !== lastPhase) {
+      lastPhase = normalized.phase;
+      patch.phase = normalized.phase;
+      changed = true;
+    }
+
+    if (normalized.dshSessionId && normalized.dshSessionId !== lastDshSessionId) {
+      lastDshSessionId = normalized.dshSessionId;
+      patch.dshSessionId = normalized.dshSessionId;
+      changed = true;
+    }
+
+    if (!changed) {
+      return;
+    }
+
+    withStateLock(workspaceRoot, () => {
+      const stored = readStoredJobOrNull(workspaceRoot, jobId);
+      if (stored?.status === "cancelled") {
+        return;
+      }
+      upsertJob(workspaceRoot, patch);
+      if (stored) {
+        writeJobFile(workspaceRoot, jobId, { ...stored, ...patch });
+      }
+    });
+  };
+}
+
+// Records the dsh process-group leader pid so cancel can kill the whole group.
+export function recordDshPid(workspaceRoot, jobId, dshPid) {
+  return withStateLock(workspaceRoot, () => {
+    const stored = readStoredJobOrNull(workspaceRoot, jobId);
+    if (stored?.status === "cancelled") {
+      return false;
+    }
+    upsertJob(workspaceRoot, { id: jobId, dshPid });
+    if (stored) {
+      writeJobFile(workspaceRoot, jobId, { ...stored, dshPid });
+    }
+    return true;
+  });
+}
+
+export function createProgressReporter({ stderr = false, logFile = null, onEvent = null } = {}) {
+  if (!stderr && !logFile && !onEvent) {
+    return null;
+  }
+
+  return (eventOrMessage) => {
+    const event = normalizeProgressEvent(eventOrMessage);
+    const stderrMessage = event.stderrMessage ?? event.message;
+    if (stderr && stderrMessage) {
+      process.stderr.write(`[dsh] ${stderrMessage}\n`);
+    }
+    appendLogLine(logFile, event.message);
+    appendLogBlock(logFile, event.logTitle, event.logBody);
+    onEvent?.(event);
+  };
+}
+
+export function isJobCancelled(workspaceRoot, jobId) {
+  return readStoredJobOrNull(workspaceRoot, jobId)?.status === "cancelled";
+}
+
+/**
+ * Runner contract: { exitStatus, payload, rendered, summary, dshSessionId, model, permissionMode, cwd }.
+ * A job that was cancelled while running stays cancelled; cancellation is terminal.
+ */
+export async function runTrackedJob(job, runner, options = {}) {
+  const logFile = options.logFile ?? job.logFile ?? null;
+  const runningRecord = {
+    ...job,
+    status: "running",
+    startedAt: nowIso(),
+    phase: "starting",
+    pid: process.pid,
+    logFile
+  };
+  if (isJobCancelled(job.workspaceRoot, job.id)) {
+    throw new Error(`Job ${job.id} was cancelled before it started.`);
+  }
+  writeJobFile(job.workspaceRoot, job.id, runningRecord);
+  upsertJob(job.workspaceRoot, runningRecord);
+
+  try {
+    const execution = await runner();
+    const outcome = withStateLock(job.workspaceRoot, () => {
+      // Cancellation is terminal: it is checked and the completion is written under one lock.
+      if (isJobCancelled(job.workspaceRoot, job.id)) {
+        return "cancelled";
+      }
+      const completionStatus = execution.exitStatus === 0 ? "completed" : "failed";
+      const completedAt = nowIso();
+      const finalState = {
+        dshSessionId: execution.dshSessionId ?? null,
+        model: execution.model ?? null,
+        permissionMode: execution.permissionMode ?? null,
+        cwd: execution.cwd ?? job.cwd ?? null
+      };
+      const existing = readStoredJobOrNull(job.workspaceRoot, job.id) ?? runningRecord;
+      writeJobFile(job.workspaceRoot, job.id, {
+        ...existing,
+        status: completionStatus,
+        ...finalState,
+        pid: null,
+        phase: completionStatus === "completed" ? "done" : "failed",
+        completedAt,
+        result: execution.payload,
+        rendered: execution.rendered
+      });
+      upsertJob(job.workspaceRoot, {
+        id: job.id,
+        status: completionStatus,
+        ...finalState,
+        summary: execution.summary,
+        phase: completionStatus === "completed" ? "done" : "failed",
+        pid: null,
+        completedAt
+      });
+      return completionStatus;
+    });
+    if (outcome === "cancelled") {
+      return { ...execution, cancelled: true };
+    }
+    appendLogBlock(logFile, "Final output", execution.rendered);
+    return execution;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    withStateLock(job.workspaceRoot, () => {
+      if (isJobCancelled(job.workspaceRoot, job.id)) {
+        return;
+      }
+      const existing = readStoredJobOrNull(job.workspaceRoot, job.id) ?? runningRecord;
+      const completedAt = nowIso();
+      writeJobFile(job.workspaceRoot, job.id, {
+        ...existing,
+        status: "failed",
+        phase: "failed",
+        errorMessage,
+        pid: null,
+        completedAt,
+        logFile: logFile ?? existing.logFile ?? null
+      });
+      upsertJob(job.workspaceRoot, {
+        id: job.id,
+        status: "failed",
+        phase: "failed",
+        pid: null,
+        errorMessage,
+        completedAt
+      });
+    });
+    throw error;
+  }
+}

package/plugins/dsh/scripts/lib/workspace.mjs

@@ -0,0 +1,9 @@
+import { ensureGitRepository } from "./git.mjs";
+
+export function resolveWorkspaceRoot(cwd) {
+  try {
+    return ensureGitRepository(cwd);
+  } catch {
+    return cwd;
+  }
+}

package/plugins/dsh/scripts/session-lifecycle-hook.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import process from "node:process";
+
+import { CHILD_ENV } from "./lib/dsh.mjs";
+import { processCommandIncludes, terminateProcessTree } from "./lib/process.mjs";
+import { listJobs, readJobFile, resolveJobFile, resolveStateFile, upsertJob, withStateLock, writeJobFile } from "./lib/state.mjs";
+import { nowIso, SESSION_ID_ENV } from "./lib/tracked-jobs.mjs";
+import { resolveWorkspaceRoot } from "./lib/workspace.mjs";
+
+const PLUGIN_DATA_ENV = "CLAUDE_PLUGIN_DATA";
+
+function readHookInput() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) {
+    return {};
+  }
+  return JSON.parse(raw);
+}
+
+function shellEscape(value) {
+  return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function appendEnvVar(name, value) {
+  if (!process.env.CLAUDE_ENV_FILE || value == null || value === "") {
+    return;
+  }
+  fs.appendFileSync(process.env.CLAUDE_ENV_FILE, `export ${name}=${shellEscape(value)}\n`, "utf8");
+}
+
+function killQuietly(pid, killer) {
+  if (!Number.isFinite(pid)) {
+    return;
+  }
+  try {
+    killer(pid);
+  } catch {
+    // Ignore teardown failures during session shutdown.
+  }
+}
+
+function cleanupSessionJobs(cwd, sessionId) {
+  if (!cwd || !sessionId) {
+    return;
+  }
+
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  if (!fs.existsSync(resolveStateFile(workspaceRoot))) {
+    return;
+  }
+
+  for (const job of listJobs(workspaceRoot)) {
+    const stillRunning = job.status === "queued" || job.status === "running";
+    if (job.sessionId !== sessionId || !stillRunning) {
+      continue;
+    }
+
+    // Mark the job cancelled first, under the state lock, so a racing completion cannot overwrite it.
+    const completedAt = nowIso();
+    const cancelled = {
+      status: "cancelled",
+      phase: "cancelled",
+      pid: null,
+      errorMessage: "Session ended.",
+      completedAt
+    };
+    withStateLock(workspaceRoot, () => {
+      const jobFile = resolveJobFile(workspaceRoot, job.id);
+      const stored = fs.existsSync(jobFile) ? readJobFile(jobFile) : job;
+      writeJobFile(workspaceRoot, job.id, { ...stored, ...cancelled });
+      upsertJob(workspaceRoot, { id: job.id, ...cancelled });
+    });
+
+    killQuietly(job.dshPid, terminateProcessTree);
+    killQuietly(job.pid, (pid) => {
+      if (processCommandIncludes(pid, "dsh-companion")) {
+        process.kill(pid, "SIGTERM");
+      }
+    });
+  }
+}
+
+function handleSessionStart(input) {
+  appendEnvVar(SESSION_ID_ENV, input.session_id);
+  appendEnvVar(PLUGIN_DATA_ENV, process.env[PLUGIN_DATA_ENV]);
+}
+
+function handleSessionEnd(input) {
+  cleanupSessionJobs(input.cwd || process.cwd(), input.session_id || process.env[SESSION_ID_ENV]);
+}
+
+function main() {
+  if (process.env[CHILD_ENV] === "1") {
+    return;
+  }
+  const input = readHookInput();
+  const eventName = process.argv[2] ?? input.hook_event_name ?? "";
+
+  if (eventName === "SessionStart") {
+    handleSessionStart(input);
+    return;
+  }
+
+  if (eventName === "SessionEnd") {
+    handleSessionEnd(input);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}

package/plugins/dsh/skills/dsh-cli-runtime/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: dsh-cli-runtime
+description: Internal helper contract for calling the dsh-companion runtime from Claude Code
+user-invocable: false
+---
+
+# dsh Runtime
+
+Use this skill only inside the `dsh:dsh-rescue` subagent.
+
+Primary helper:
+- `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" task "<raw arguments>"`
+
+Execution rules:
+- Set the Bash `timeout` to `600000` and put the task text between single quotes (escape each `'` as `'\''`), after all flags.
+- The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke `task` once and return that stdout unchanged.
+- Prefer the helper over hand-rolled `dsh` command lines or any other Bash activity.
+- Do not call `setup`, `plan`, `review-plan`, `status`, `result`, or `cancel` from `dsh:dsh-rescue`.
+- Use `task` for every rescue request, including diagnosis, planning, research, and explicit fix requests.
+- Leave the model unset by default. Add `--model` only when the user explicitly asks for one. The aliases are `flash` (deepseek-flash) and `pro` (deepseek-v4-pro).
+
+Flags the `task` helper accepts:
+- `--write`: run with the workspace-write sandbox.
+- `--read-only`: run with the read-only sandbox. This is the helper's default when neither flag is given, so the agent always states the mode it wants.
+- `--resume-last`: continue the previous rescue session of this Claude session in this directory.
+- `--model <flash|pro|name>`.
+
+Command selection:
+- Use exactly one `task` invocation per rescue handoff.
+- Strip `--background` and `--wait` before calling `task`. They are Claude-side execution control only.
+- `--resume`: strip that token from the task text and add `--resume-last`.
+- `--fresh`: strip that token from the task text and do not add `--resume-last`.
+- Fresh run: add `--write` unless the user asked for read-only, diagnosis-only or research-only work, in which case add `--read-only`.
+- Resumed run: add no mode flag unless the user explicitly asked for one. The session keeps the mode it was created with, and asking for a different mode fails with an instruction to use `--fresh`.
+
+Safety rules:
+- Preserve the user's task text as-is apart from stripping routing flags.
+- Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.
+- Return the stdout of the `task` command exactly as-is.
+- If the Bash call fails, return its error message and nothing else.

package/plugins/dsh/skills/dsh-result-handling/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: dsh-result-handling
+description: Internal guidance for presenting dsh helper output back to the user
+user-invocable: false
+---
+
+# dsh Result Handling
+
+When the helper returns dsh output:
+- Present dsh's final text verbatim, including the `dsh session: … · model: … · mode: …` footer.
+- For `/dsh:review-plan` output, keep the `Verdict:` line first and keep findings in the order dsh gave them.
+- Use the file paths and line numbers exactly as dsh reports them.
+- Preserve evidence boundaries. If dsh marked something as an inference, uncertainty, or open question, keep that distinction.
+- If dsh made edits (rescue in `workspace-write` mode), say so explicitly and list the touched files when the helper provides them.
+- Do not turn a failed or incomplete dsh run into a Claude-side implementation attempt. Report the failure and stop.
+- If dsh was never successfully invoked, do not generate a substitute answer.
+- CRITICAL: After presenting a plan or a plan review, STOP. Do not apply the plan and do not edit the reviewed plan. Explicitly ask the user what, if anything, they want done before touching a single file. Auto-applying fixes from a plan or review is strictly forbidden, even if the fix is obvious.
+- If the helper reports a failed dsh run, include the most actionable stderr lines and stop there instead of guessing.
+- If the helper reports that setup or authentication is required, direct the user to `/dsh:setup` and do not improvise alternate auth flows.