Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

9.4 KB
Raw Blame
/**
 * Where an Agent's workflows live and how their versions are kept.
 *
 *   <agentDir>/workflows/<id>/package.json   `penguin.modules` manifests (a plugin package)
 *   <agentDir>/workflows/<id>/index.ts       default export `{ modules: { <Name>: { create } } }`
 *   <agentDir>/workflows/<id>/ui/            the pages its contributed tabs name
 *   <agentDir>/workflows/<id>/state.json     the workflow's own document (WorkflowHost.getState)
 *   <agentDir>/workflows/<id>/.harness/      the types it was written against (harness-types.ts)
 *   <agentDir>/workflows/<id>/.build/        its emitted code, per revision (compile.ts)
 *   <agentDir>/workflows-history/<id>/<revision>/   a full copy of the folder at each successful load
 *   <agentDir>/workflows-history/<id>/versions.json  the list, newest first
 *
 * The revision is the content hash of every file except `state.json` (the state is the
 * workflow's data, not its code, and survives a rollback untouched), `node_modules` and the
 * dot-directories, which are the server's. Reading is tolerant:
 * a folder without a package.json is not a workflow, a broken versions.json is an empty list.
 */
import { createHash, randomBytes } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import { agentDir } from "@adelie/core";
import type { WorkflowVersion } from "../mechanisms/workflows.js";

export const STATE_FILE = "state.json";
export const UI_DIR = "ui";
/** Versions kept per workflow; older copies are removed with their folders. */
export const KEEP_VERSIONS = 20;

export interface WorkflowFolder {
  id: string;
  dir: string;
  /** Relative paths, sorted, excluding state.json. */
  files: string[];
  revision: string;
  uiRev: string | null;
  pkg: { name: string; version: string | null };
}

export function workflowsDir(root: string, projectId: string, agentId: string): string {
  return path.join(agentDir(root, projectId, agentId), "workflows");
}

export function historyDir(root: string, projectId: string, agentId: string): string {
  return path.join(agentDir(root, projectId, agentId), "workflows-history");
}

/** A workflow id is one path segment of the folder's own name; nothing else is accepted. */
export function isWorkflowId(id: string): boolean {
  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id) && id !== "." && id !== "..";
}

export function isSafeRelPath(rel: string): boolean {
  if (rel === "" || rel.startsWith("/") || rel.includes("\\")) return false;
  return rel.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
}

async function walk(dir: string, prefix = ""): Promise<string[]> {
  let entries: import("node:fs").Dirent[];
  try {
    entries = await fs.readdir(dir, { withFileTypes: true });
  } catch {
    return [];
  }
  const out: string[] = [];
  for (const e of entries) {
    if (e.name === "node_modules" || e.name.startsWith(".") || isTempName(e.name)) continue;
    const rel = prefix === "" ? e.name : `${prefix}/${e.name}`;
    if (e.isDirectory()) out.push(...(await walk(path.join(dir, e.name), rel)));
    else if (e.isFile()) out.push(rel);
  }
  return out.sort();
}

async function hashFiles(dir: string, files: string[]): Promise<string> {
  const h = createHash("sha256");
  for (const rel of files) {
    // A file listed a moment ago can be gone by now — an editor's own scratch file, the
    // Agent deleting one mid-write. That is a folder that has changed, not a broken read:
    // the hash covers what is still there, and the watcher brings the next one round.
    // Reading whatever is there is also what every other read in this module does.
    let body: Buffer;
    try {
      body = await fs.readFile(path.join(dir, rel));
    } catch {
      continue;
    }
    h.update(rel).update("\0");
    h.update(body).update("\0");
  }
  return h.digest("hex").slice(0, 12);
}

/** Reads one workflow folder; null when it is not a workflow (no package.json). */
export async function readFolder(dir: string, id: string): Promise<WorkflowFolder | null> {
  let raw: string;
  try {
    raw = await fs.readFile(path.join(dir, "package.json"), "utf8");
  } catch {
    return null;
  }
  let pkg: { name?: unknown; version?: unknown } = {};
  try {
    pkg = JSON.parse(raw) as typeof pkg;
  } catch {
    // A broken package.json is still a workflow folder: the loader reports the error.
  }
  const files = (await walk(dir)).filter((f) => f !== STATE_FILE);
  const ui = files.filter((f) => f.startsWith(`${UI_DIR}/`));
  return {
    id,
    dir,
    files,
    revision: await hashFiles(dir, files),
    uiRev: ui.length === 0 ? null : await hashFiles(dir, ui),
    pkg: {
      name: typeof pkg.name === "string" && pkg.name !== "" ? pkg.name : id,
      version: typeof pkg.version === "string" ? pkg.version : null,
    },
  };
}

export async function listFolders(base: string): Promise<WorkflowFolder[]> {
  let entries: import("node:fs").Dirent[];
  try {
    entries = await fs.readdir(base, { withFileTypes: true });
  } catch {
    return [];
  }
  const out: WorkflowFolder[] = [];
  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
    if (!e.isDirectory() || !isWorkflowId(e.name)) continue;
    const folder = await readFolder(path.join(base, e.name), e.name);
    if (folder) out.push(folder);
  }
  return out;
}

export async function readState(dir: string): Promise<unknown> {
  try {
    return JSON.parse(await fs.readFile(path.join(dir, STATE_FILE), "utf8")) as unknown;
  } catch {
    return null;
  }
}

/**
 * The suffix every staged write of ours carries. It is what tells the watcher and the
 * revision hash that a file is the server's own scratch and not an edit: a fixed
 * `state.json.tmp` was neither — it reloaded the workflow on every `setState`, and entered
 * the hash it was supposed to be outside of. The random middle keeps two concurrent writes
 * from truncating each other's staging file and renaming a half-written document into place.
 */
export const TMP_SUFFIX = ".penguin-tmp";
export const isTempName = (name: string): boolean => name.includes(TMP_SUFFIX);
const tempPath = (file: string) => `${file}${TMP_SUFFIX}${randomBytes(6).toString("hex")}`;

export async function writeState(dir: string, state: unknown): Promise<void> {
  const file = path.join(dir, STATE_FILE);
  const staged = tempPath(file);
  try {
    await fs.writeFile(staged, JSON.stringify(state ?? null, null, 2));
    await fs.rename(staged, file);
  } catch (err) {
    await fs.rm(staged, { force: true }).catch(() => undefined);
    throw err;
  }
}

async function readVersions(dir: string): Promise<WorkflowVersion[]> {
  try {
    const parsed = JSON.parse(await fs.readFile(path.join(dir, "versions.json"), "utf8"));
    return Array.isArray(parsed) ? (parsed as WorkflowVersion[]) : [];
  } catch {
    return [];
  }
}

async function writeVersions(dir: string, versions: WorkflowVersion[]): Promise<void> {
  await fs.mkdir(dir, { recursive: true });
  const file = path.join(dir, "versions.json");
  const staged = tempPath(file);
  await fs.writeFile(staged, JSON.stringify(versions, null, 2));
  await fs.rename(staged, file);
}

/**
 * Records the folder's current content as a version (no-op when that revision is already
 * the newest), copying the files and trimming to KEEP_VERSIONS.
 */
export async function recordVersion(
  history: string,
  folder: WorkflowFolder,
  now: Date,
): Promise<WorkflowVersion[]> {
  const dir = path.join(history, folder.id);
  const versions = await readVersions(dir);
  if (versions[0]?.revision === folder.revision) return versions;
  const target = path.join(dir, folder.revision);
  await fs.rm(target, { recursive: true, force: true });
  for (const rel of folder.files) {
    await fs.mkdir(path.dirname(path.join(target, rel)), { recursive: true });
    await fs.copyFile(path.join(folder.dir, rel), path.join(target, rel));
  }
  const entry: WorkflowVersion = {
    revision: folder.revision,
    savedAt: now.toISOString(),
    name: folder.pkg.name,
    version: folder.pkg.version,
    uiRev: folder.uiRev,
    files: folder.files,
  };
  // A revision seen before moves to the front rather than duplicating (a rollback IS such a load).
  const next = [entry, ...versions.filter((v) => v.revision !== folder.revision)];
  for (const old of next.splice(KEEP_VERSIONS)) {
    await fs.rm(path.join(dir, old.revision), { recursive: true, force: true });
  }
  await writeVersions(dir, next);
  return next;
}

export function listVersions(history: string, id: string): Promise<WorkflowVersion[]> {
  return readVersions(path.join(history, id));
}

/**
 * Replaces the folder's code files with a recorded version's, keeping state.json. Files
 * the current folder has and the version lacks are removed, so the result is exactly that
 * version. Returns false when the version is not recorded.
 */
export async function restoreVersion(
  history: string,
  folder: WorkflowFolder,
  revision: string,
): Promise<boolean> {
  const versions = await readVersions(path.join(history, folder.id));
  const version = versions.find((v) => v.revision === revision);
  if (!version) return false;
  const source = path.join(history, folder.id, revision);
  const keep = new Set(version.files);
  for (const rel of folder.files) {
    if (!keep.has(rel)) await fs.rm(path.join(folder.dir, rel), { force: true });
  }
  for (const rel of version.files) {
    await fs.mkdir(path.dirname(path.join(folder.dir, rel)), { recursive: true });
    await fs.copyFile(path.join(source, rel), path.join(folder.dir, rel));
  }
  return true;
}