@monster-orange/den 0.2.8 → 0.4.0

package/src/shared/process/process-group.ts

@@ -0,0 +1,202 @@
+/**
+ * Process groups that a detached `up` started (0.3.0-dev.37).
+ *
+ * A detached service is spawned as the leader of its own process group, so
+ * its pid is the group id. `up` records that pgid together with the leader's
+ * start time, and `down` signals the whole group: SIGTERM, a short grace
+ * period, then SIGKILL.
+ *
+ * A recorded pid can be reused once its process exits, so nothing is
+ * signalled until the group is shown to still be the one `up` started:
+ *
+ *  - the leader (pid == pgid) is alive: its start time must equal the
+ *    recorded one, and it must still lead that group. Anything else is a
+ *    different process that happens to hold the pid, and it is left alone.
+ *  - the leader has exited but members still carry the pgid: the group is
+ *    still ours. A process group id is not handed out again while any
+ *    process is in that group, so live members of it are ones the leader
+ *    started.
+ *  - nothing carries the pgid: the group has exited.
+ */
+
+import { execFile, execFileSync } from "child_process";
+
+export interface RecordedProcessGroup {
+  /** The group id: the detached leader's pid. */
+  pgid: number;
+  /** The leader's start time as `ps -o lstart=` prints it. */
+  startedAt: string;
+}
+
+export type GroupState =
+  | { state: "ours"; members: number[] }
+  | { state: "gone" }
+  | { state: "reused"; detail: string };
+
+export type StopGroupOutcome =
+  | { outcome: "stopped"; signal: "SIGTERM" | "SIGKILL"; members: number[] }
+  | { outcome: "gone" }
+  | { outcome: "reused"; detail: string }
+  | { outcome: "survived"; members: number[] }
+  | { outcome: "error"; detail: string };
+
+interface PsRow {
+  pid: number;
+  pgid: number;
+  zombie: boolean;
+  lstart: string;
+}
+
+const PS = "ps";
+// lstart is printed in the C locale's fixed format, whatever the user's.
+const PS_ENV = { ...process.env, LC_ALL: "C", LANG: "C" };
+
+function parsePs(out: string): PsRow[] {
+  const rows: PsRow[] = [];
+  for (const line of out.split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+    if (!m) continue;
+    rows.push({
+      pid: Number(m[1]),
+      pgid: Number(m[2]),
+      zombie: m[3].startsWith("Z"),
+      lstart: m[4].trim().replace(/\s+/g, " "),
+    });
+  }
+  return rows;
+}
+
+const PS_COLUMNS = ["-o", "pid=,pgid=,stat=,lstart="];
+const PS_ARGS = ["-A", ...PS_COLUMNS];
+
+function psRowsSync(args: string[]): PsRow[] | null {
+  try {
+    return parsePs(
+      execFileSync(PS, args, {
+        env: PS_ENV,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5000,
+      }),
+    );
+  } catch {
+    return null;
+  }
+}
+
+function psRows(): Promise<PsRow[] | null> {
+  return new Promise((resolve) => {
+    execFile(
+      PS,
+      PS_ARGS,
+      { env: PS_ENV, encoding: "utf-8", timeout: 5000 },
+      (err, stdout) => resolve(err ? null : parsePs(stdout)),
+    );
+  });
+}
+
+/**
+ * The record `up` keeps for a detached leader it just spawned, or null when
+ * the process cannot be read (it already exited, or `ps` is unavailable).
+ */
+export function recordProcessGroup(pid: number): RecordedProcessGroup | null {
+  const row = psRowsSync(["-p", String(pid), ...PS_COLUMNS])?.find(
+    (r) => r.pid === pid && !r.zombie,
+  );
+  if (!row || row.pgid !== pid) return null;
+  return { pgid: pid, startedAt: row.lstart };
+}
+
+/** A recorded group's state now, synchronously; null when `ps` cannot be run. */
+export function processGroupStateSync(
+  rec: RecordedProcessGroup,
+): GroupState | null {
+  const rows = psRowsSync(PS_ARGS);
+  return rows ? classifyGroup(rec, rows) : null;
+}
+
+/** Whether a recorded group is still the one `up` started (see the header). */
+export function classifyGroup(
+  rec: RecordedProcessGroup,
+  rows: PsRow[],
+): GroupState {
+  const live = rows.filter((r) => !r.zombie);
+  const leader = live.find((r) => r.pid === rec.pgid);
+  if (leader && (leader.lstart !== rec.startedAt || leader.pgid !== rec.pgid))
+    return {
+      state: "reused",
+      detail: `pid ${rec.pgid} now belongs to another process (started ${leader.lstart}; the recorded one started ${rec.startedAt})`,
+    };
+  const members = live.filter((r) => r.pgid === rec.pgid).map((r) => r.pid);
+  return members.length > 0 ? { state: "ours", members } : { state: "gone" };
+}
+
+/** The recorded group's state now; null when `ps` cannot be run. */
+export async function processGroupState(
+  rec: RecordedProcessGroup,
+): Promise<GroupState | null> {
+  const rows = await psRows();
+  return rows ? classifyGroup(rec, rows) : null;
+}
+
+function signalGroup(
+  pgid: number,
+  signal: NodeJS.Signals,
+): "sent" | "gone" | string {
+  try {
+    process.kill(-pgid, signal);
+    return "sent";
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return "gone";
+    return `${signal} to process group ${pgid} failed: ${code ?? (e as Error).message}`;
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function waitUntilGone(
+  rec: RecordedProcessGroup,
+  ms: number,
+): Promise<GroupState | null> {
+  const deadline = Date.now() + ms;
+  let state = await processGroupState(rec);
+  while (state?.state === "ours" && Date.now() < deadline) {
+    await sleep(100);
+    state = await processGroupState(rec);
+  }
+  return state;
+}
+
+/**
+ * Stop a recorded process group: SIGTERM, up to `graceMs` for it to exit,
+ * then SIGKILL. The group is re-verified before each signal, so a pid that
+ * was reused in between is never signalled.
+ */
+export async function stopProcessGroup(
+  rec: RecordedProcessGroup,
+  graceMs = 3000,
+): Promise<StopGroupOutcome> {
+  const before = await processGroupState(rec);
+  if (!before) return { outcome: "error", detail: "could not run ps" };
+  if (before.state === "gone") return { outcome: "gone" };
+  if (before.state === "reused")
+    return { outcome: "reused", detail: before.detail };
+
+  const term = signalGroup(rec.pgid, "SIGTERM");
+  if (term === "gone") return { outcome: "gone" };
+  if (term !== "sent") return { outcome: "error", detail: term };
+
+  const afterTerm = await waitUntilGone(rec, graceMs);
+  if (!afterTerm) return { outcome: "error", detail: "could not run ps" };
+  if (afterTerm.state !== "ours")
+    return { outcome: "stopped", signal: "SIGTERM", members: before.members };
+
+  const kill = signalGroup(rec.pgid, "SIGKILL");
+  if (kill !== "sent" && kill !== "gone")
+    return { outcome: "error", detail: kill };
+  const afterKill = await waitUntilGone(rec, 2000);
+  if (afterKill?.state === "ours")
+    return { outcome: "survived", members: afterKill.members };
+  return { outcome: "stopped", signal: "SIGKILL", members: before.members };
+}

package/src/shared/process/spawn-streaming.ts

@@ -74,6 +74,7 @@ export function spawnDaemon(
   onClose: (exitCode: number) => void,
   cwd?: string,
   onServiceExit?: (exitCode: number) => void,
+  onSpawn?: (pid: number) => void,
 ): ReturnType<typeof spawn> {
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
 
@@ -112,6 +113,9 @@ export function spawnDaemon(
     onLine(`Error: ${err.message}`);
     onServiceExit?.(1);
   });
+  // The service leads its own process group (detached), so its pid is the
+  // group id `down` signals later.
+  if (onSpawn && svcProc.pid) onSpawn(svcProc.pid);
   svcProc.unref(); // den's event loop can exit independently
   fs.closeSync(logFd); // parent closes its copy; child keeps its own fd
 
@@ -148,6 +152,7 @@ export function spawnDaemon(
  * @param cwd      Working directory (defaults to process.cwd())
  * @param detached Put the child in its own process group (default false)
  * @param logPath  If provided together with detached=true, run as a daemon writing to this path
+ * @param onSpawn  Daemon mode: called with the service's pid (its process group id) once spawned
  */
 export function spawnStreaming(
   command: string,
@@ -159,6 +164,7 @@ export function spawnStreaming(
   detached?: boolean,
   logPath?: string,
   onServiceExit?: (exitCode: number) => void,
+  onSpawn?: (pid: number) => void,
 ): ReturnType<typeof spawn> {
   // Daemon mode: service runs independently from den — survives restarts.
   if (detached && logPath) {
@@ -170,6 +176,7 @@ export function spawnStreaming(
       onClose,
       cwd,
       onServiceExit,
+      onSpawn,
     );
   }
 

package/src/shared/secret-env.ts

@@ -0,0 +1,70 @@
+/**
+ * Which environment variables are credentials, by name or by value. One
+ * set of patterns for everything that checks an environment: the test
+ * workers (tests/scrub-env.ts), the audit of `sessions start --keep-env`,
+ * and `<cli> doctor --probe` (with the text redactor's own patterns,
+ * redact.ts). They err on the side of flagging: a harmless variable called
+ * a credential costs less than a token called harmless.
+ *
+ * Nothing here returns or logs a value.
+ */
+
+import { redactSecrets, SECRET_PATTERNS } from "./redact.js";
+
+/** Variable names that hold credentials. */
+const SECRET_NAME =
+  /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|API_?KEY|PRIVATE_KEY|ACCESS_KEY|AUTH)/i;
+
+/** Whole families of credential variables. */
+const SECRET_PREFIX = /^(OP_|DOPPLER_|AWS_|GH_|GITHUB_|NPM_|ANTHROPIC_)/i;
+
+/** Values shaped like well-known tokens, whatever the variable is called. */
+const SECRET_VALUE =
+  /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|ops_[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|dp\.(st|ct|sa|scim)\.[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{20,}|xox[abpr]-[A-Za-z0-9-]{10,})/;
+
+/** Whether a variable looks like a credential, by name or by value. */
+export function isCredentialEnv(
+  name: string,
+  value: string | undefined,
+): boolean {
+  return (
+    SECRET_NAME.test(name) ||
+    SECRET_PREFIX.test(name) ||
+    (value !== undefined && SECRET_VALUE.test(value))
+  );
+}
+
+/**
+ * Credential-shaped: by name or value (isCredentialEnv), or a value the
+ * text redactor would redact.
+ */
+export function isCredentialShaped(
+  name: string,
+  value: string | undefined,
+): boolean {
+  return (
+    isCredentialEnv(name, value) ||
+    (value !== undefined && value !== "" && redactSecrets(value) !== value)
+  );
+}
+
+/**
+ * Every pattern isCredentialShaped uses, as plain data (source and flags,
+ * global flag dropped), for a check run in another process (the probe).
+ */
+export function credentialPatternData(): {
+  name: { source: string; flags: string }[];
+  value: { source: string; flags: string }[];
+} {
+  const data = (re: RegExp) => ({
+    source: re.source,
+    flags: re.flags.replace("g", ""),
+  });
+  return {
+    name: [SECRET_NAME, SECRET_PREFIX].map(data),
+    value: [SECRET_VALUE, ...SECRET_PATTERNS.map((p) => p.re)].map(data),
+  };
+}
+
+/** An environment variable name (`--keep-env NAME`). */
+export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/src/shared/secrets/doppler.ts

@@ -1,6 +1,6 @@
 /**
  * Doppler strategy — reads/writes flat keys with the `doppler` CLI.
- * Selected with `secrets.provider: doppler` (the default).
+ * Selected with `secrets.provider: doppler`.
  *
  * Project/config come from `secrets.doppler.{project,config}` in
  * config/den.yml, else from the directory's `doppler setup` scope,