@forgezero/agent 0.1.0 → 0.1.9

package/dist/deployment-runner.d.ts

@@ -0,0 +1,23 @@
+import { type Server } from 'node:net';
+import type { CommandInput, CommandResult } from './deployment';
+export declare const DEFAULT_DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+/**
+ * Execute tenant-controlled project commands under a separate Unix identity.
+ *
+ * This daemon has no LoadCredential directive and cannot open the owner-only
+ * agent socket. The credential-bearing agent may submit an exact command and
+ * only the secrets named for that step; the subprocess can steal those values,
+ * because it is the intended consumer, but cannot steal the node or Git key.
+ */
+export declare function startDeploymentRunner(options: {
+    root: string;
+    home: string;
+    socketPath?: string;
+    /** systemd socket activation passes the agent-owned listener as fd 3. */
+    listenFd?: number;
+    exec?: (input: CommandInput, home: string) => Promise<CommandResult>;
+}): {
+    server: Server;
+    stop(): Promise<void>;
+};
+export declare function requestDeploymentCommand(input: CommandInput, socketPath?: string): Promise<CommandResult>;

package/dist/deployment-runner.js

@@ -0,0 +1,199 @@
+// src/deployment-runner.ts
+import { chmodSync, existsSync, realpathSync, unlinkSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { connect, createServer } from "node:net";
+var DEFAULT_DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+var MAX_REQUEST_BYTES = 256 * 1024;
+var MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+var MAX_RESPONSE_BYTES = 2 * MAX_OUTPUT_BYTES + MAX_REQUEST_BYTES;
+var READ_TIMEOUT_MS = 5000;
+var MAX_COMMAND_TIMEOUT_MS = 60 * 60000;
+function within(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${sep}`);
+}
+function validate(root, input) {
+  if (!input || typeof input.command !== "string" || input.command.length < 1 || input.command.length > 64 * 1024) {
+    throw new Error("invalid deployment command");
+  }
+  if (!input.cwd || !isAbsolute(input.cwd))
+    throw new Error("deployment command needs an absolute working directory");
+  const realRoot = realpathSync(root);
+  const realCwd = realpathSync(input.cwd);
+  if (!within(realRoot, realCwd))
+    throw new Error("deployment command escaped the release root");
+  const timeoutMs = Math.trunc(input.timeoutMs ?? 10 * 60000);
+  if (timeoutMs < 1000 || timeoutMs > MAX_COMMAND_TIMEOUT_MS)
+    throw new Error("invalid deployment command timeout");
+  const env = {};
+  let environmentBytes = 0;
+  for (const [name, value] of Object.entries(input.env ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || typeof value !== "string") {
+      throw new Error("invalid deployment environment");
+    }
+    environmentBytes += Buffer.byteLength(name) + Buffer.byteLength(value);
+    if (environmentBytes > 128 * 1024)
+      throw new Error("deployment environment is too large");
+    env[name] = value;
+  }
+  return { command: input.command, cwd: realCwd, env, timeoutMs };
+}
+async function limited(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder;
+  let output = "";
+  let remaining = MAX_OUTPUT_BYTES;
+  for (;; ) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    if (remaining > 0) {
+      const chunk = value.byteLength <= remaining ? value : value.subarray(0, remaining);
+      output += decoder.decode(chunk, { stream: true });
+      remaining -= chunk.byteLength;
+    }
+  }
+  output += decoder.decode();
+  return remaining === 0 ? `${output}
+[output truncated at ${MAX_OUTPUT_BYTES} bytes]` : output;
+}
+async function execute(input, home) {
+  const child = Bun.spawn(["bash", "-Eeuo", "pipefail", "-c", input.command], {
+    cwd: input.cwd,
+    detached: true,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      PATH: "/usr/local/bin:/usr/bin:/bin",
+      HOME: home,
+      XDG_CACHE_HOME: `${home}/cache`,
+      LANG: "C.UTF-8",
+      ...input.env ?? {}
+    }
+  });
+  let timedOut = false;
+  let forceTimer;
+  const killGroup = (signal) => {
+    try {
+      process.kill(-child.pid, signal);
+    } catch (cause) {
+      if (cause.code !== "ESRCH")
+        throw cause;
+    }
+  };
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killGroup("SIGTERM");
+    forceTimer = setTimeout(() => killGroup("SIGKILL"), 2000);
+  }, input.timeoutMs);
+  const [stdout, stderr, exitCode] = await Promise.all([
+    limited(child.stdout),
+    limited(child.stderr),
+    child.exited
+  ]);
+  clearTimeout(timer);
+  if (forceTimer)
+    clearTimeout(forceTimer);
+  return {
+    exitCode: timedOut ? 124 : exitCode,
+    output: `${stdout}${stderr}${timedOut ? `
+command exceeded ${input.timeoutMs}ms` : ""}`
+  };
+}
+function startDeploymentRunner(options) {
+  const root = resolve(options.root);
+  const home = resolve(options.home);
+  const socketPath = options.socketPath ?? DEFAULT_DEPLOYMENT_RUNNER_SOCKET;
+  if (options.listenFd === undefined && existsSync(socketPath))
+    unlinkSync(socketPath);
+  const active = new Set;
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.setTimeout(READ_TIMEOUT_MS, () => socket.end(`${JSON.stringify({
+      ok: false,
+      error: { code: "REFUSED", message: "request timed out" }
+    })}
+`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
+        socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request too large" } })}
+`);
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.setTimeout(0);
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      const work = (async () => {
+        try {
+          const input = validate(root, JSON.parse(line));
+          return { ok: true, result: await (options.exec ?? execute)(input, home) };
+        } catch (cause) {
+          return {
+            ok: false,
+            error: { code: "REFUSED", message: cause instanceof Error ? cause.message : "deployment command refused" }
+          };
+        }
+      })();
+      active.add(work);
+      work.finally(() => active.delete(work));
+      work.then((response) => socket.end(`${JSON.stringify(response)}
+`));
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  if (options.listenFd !== undefined)
+    server.listen({ fd: options.listenFd });
+  else
+    server.listen(socketPath, () => chmodSync(socketPath, 432));
+  return {
+    server,
+    async stop() {
+      await new Promise((resolveStop) => server.close(() => resolveStop()));
+      await Promise.all(active);
+    }
+  };
+}
+function requestDeploymentCommand(input, socketPath = DEFAULT_DEPLOYMENT_RUNNER_SOCKET) {
+  return new Promise((resolveRequest, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify(input)}
+`));
+    const timeout = Math.max(1000, input.timeoutMs ?? 10 * 60000) + 1e4;
+    socket.setTimeout(timeout, () => {
+      socket.destroy();
+      reject(new Error("deployment runner response timed out"));
+    });
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_RESPONSE_BYTES) {
+        socket.destroy();
+        reject(new Error("deployment runner response is too large"));
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        if (response.ok)
+          resolveRequest(response.result);
+        else
+          reject(new Error(response.error.message));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+export {
+  startDeploymentRunner,
+  requestDeploymentCommand,
+  DEFAULT_DEPLOYMENT_RUNNER_SOCKET
+};

package/dist/deployment-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deployment-watch.d.ts

@@ -0,0 +1,36 @@
+import type { DeploymentManager } from './deployment';
+export type StaticDeploymentOutcome = 'pending' | 'running' | 'deployed' | 'failed';
+export interface StaticDeploymentState {
+    revision: string;
+    outcome: StaticDeploymentOutcome;
+    updatedAtTs: number;
+    detail?: string;
+}
+export interface StaticDeploymentWatchOptions {
+    manager: DeploymentManager;
+    statePath: string;
+    coordinator?: boolean;
+    intervalMs?: number;
+    readState?: () => StaticDeploymentState | null;
+    writeState?: (state: StaticDeploymentState) => void;
+    /** Active release on the first watcher boot, before a state file exists. */
+    currentRevision?: () => string | undefined;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    now?: () => number;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+export declare function readStaticDeploymentState(path: string): StaticDeploymentState | null;
+export declare function writeStaticDeploymentState(path: string, state: StaticDeploymentState): void;
+/**
+ * Git is only an intake adapter. Every discovered revision is still executed
+ * by DeploymentManager and therefore by the common keyed async queue.
+ *
+ * The state file is business recovery state, not queue persistence: pending
+ * and running are written before execution, so a process crash re-submits the
+ * exact commit on boot; deployed is written only after the awaited result.
+ */
+export declare function startStaticDeploymentWatch(options: StaticDeploymentWatchOptions): {
+    stop(): Promise<void>;
+    readonly active: boolean;
+};

package/dist/deployment-watch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deployment.d.ts

@@ -0,0 +1,86 @@
+import { type DrainReport, type QueueTask } from '@forgezero/runtime/queue';
+import { type RunResult } from './pipeline';
+import type { SecretCache } from './cache';
+import type { AttestationSource } from './socket';
+export interface CommandInput {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface CommandResult {
+    exitCode: number;
+    output: string;
+}
+export interface DeploymentRequest {
+    /** Optional exact commit from a verified webhook. Never a branch name. */
+    revision?: string;
+    /** Whether this node is the coordinator allowed to execute `once` steps. */
+    coordinator?: boolean;
+}
+export interface DeploymentResult {
+    key: string;
+    repository: string;
+    branch: string;
+    revision: string;
+    release: string;
+    ok: boolean;
+    phases: readonly RunResult[];
+}
+export interface DeploymentOptions {
+    /** Queue key. Same project/environment is serial; other managers may run in parallel. */
+    key: string;
+    repository: string;
+    branch: string;
+    role: string;
+    root: string;
+    publicApiUrl?: string;
+    gitCredentialPath?: string;
+    knownHostsPath?: string;
+    /** Server-owned, operator-pinned host keys for a dynamically assigned source. */
+    knownHostsContent?: string;
+    cache?: Pick<SecretCache, 'get'>;
+    /** Non-secret values explicitly passed to every project phase. */
+    environment?: Record<string, string>;
+    attestation?: AttestationSource;
+    width?: number;
+    /** Project commands run through a credential-free Unix identity in production. */
+    projectExec?: (input: CommandInput) => Promise<CommandResult>;
+    exec?: (input: CommandInput) => Promise<CommandResult>;
+    now?: () => number;
+    readDefinition?: (path: string) => unknown;
+}
+export declare class DeploymentError extends Error {
+    readonly code: 'BAD_REVISION' | 'SOURCE_FAILED' | 'PIPELINE_FAILED' | 'SECRET_MISSING';
+    constructor(code: 'BAD_REVISION' | 'SOURCE_FAILED' | 'PIPELINE_FAILED' | 'SECRET_MISSING', message: string);
+}
+/**
+ * One source and one pipeline owner.
+ *
+ * A request may choose an exact commit and whether this assigned node is the
+ * coordinator. It cannot choose a repository, branch, working directory or
+ * command: those are sealed into the agent unit and the checked-out definition.
+ */
+export declare function createDeploymentManager(options: DeploymentOptions): {
+    latestRevision(): Promise<string>;
+    deploy(request?: DeploymentRequest): QueueTask<DeploymentResult>;
+    snapshot: () => {
+        running: number;
+        queued: number;
+        keys: number;
+        paused: boolean;
+        pausedKeys: string[];
+        stoppedKeys: string[];
+        completed: number;
+        failed: number;
+    };
+    pause: () => void;
+    resume: () => void;
+    pauseKey: (key: string) => void;
+    resumeKey: (key: string) => void;
+    stopKey: (key: string) => number;
+    startKey: (key: string) => boolean;
+    cancel: (id: string) => boolean;
+    stop(deadlineMs?: number): Promise<DrainReport>;
+};
+export type DeploymentManager = ReturnType<typeof createDeploymentManager>;

package/dist/deployment.test.d.ts

@@ -0,0 +1 @@
+export {};