Skip to content

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

19.8 KB
Raw Blame
/**
 * File I/O for organization directories: the one place that knows how the files are laid
 * out on disk. Reads return the raw text next to the parse result so callers can hash,
 * echo or report it; writes are whole-file replacements. No SQLite here — the caches are
 * the service's business.
 */
import fs from "node:fs/promises";
import path from "node:path";
import { atomicWriteFile } from "@adelie/core";
import type { OrgChannelMessage, OrgTicketStatus } from "../api/types.js";
import type {
  CalendarEvent,
  ChannelConfig,
  Desks,
  OrgChart,
  OrgConfig,
  ParseResult,
  TicketDoc,
} from "./files.js";
import {
  parseCalendarEvent,
  parseChannelConfig,
  parseChannelMessageLine,
  parseDesks,
  parseOrgChart,
  parseOrgConfig,
  parseTicket,
  serializeChannelConfig,
  serializeDesks,
  serializeOrgChart,
  serializeOrgConfig,
  serializeTicket,
} from "./files.js";
import {
  DEFAULT_CHANNEL_ID,
  ORG_TICKET_COLUMNS,
  calendarDir,
  calendarEventPath,
  channelConfigPath,
  channelDayPath,
  channelDir,
  channelsDir,
  desksPath,
  handbookDir,
  handbookFilePath,
  handbookPath,
  isCalendarEventName,
  isChannelId,
  orgChartPath,
  orgConfigPath,
  orgDir,
  organizationsDir,
  ticketPath,
  ticketsDir,
  workspaceDir,
} from "./paths.js";

/** Directory names that are Agent ids (organizations, calendar owners). */
const ID = /^[a-z][a-z0-9_]{1,63}$/;
const DATE = /^\d{4}-\d{2}-\d{2}$/;
const MONTH = /^\d{4}-\d{2}$/;

export interface OrgFile<T> {
  raw: string;
  parsed: ParseResult<T>;
}

/** One file of the handbook, `path` relative to `handbook/` with `/` separators. */
export interface HandbookFile {
  path: string;
  size: number;
  mtimeMs: number;
}

export interface CalendarFile {
  agentId: string;
  name: string;
  raw: string;
  parsed: ParseResult<CalendarEvent>;
  mtimeMs: number;
}

/** One `channels/<channel_id>/channel.toml`, parsed; the id is the directory name. */
export interface ChannelFile {
  channelId: string;
  raw: string;
  parsed: ParseResult<ChannelConfig>;
  mtimeMs: number;
}

export interface TicketFile {
  /** Path relative to the organization directory. */
  relPath: string;
  ticketId: string;
  /** The column directory the file sits in. */
  column: OrgTicketStatus;
  raw: string;
  parsed: ParseResult<TicketDoc>;
  mtimeMs: number;
}

async function readText(p: string): Promise<string | null> {
  try {
    return await fs.readFile(p, "utf8");
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw err;
  }
}

async function writeText(p: string, text: string): Promise<void> {
  await fs.mkdir(path.dirname(p), { recursive: true });
  // Atomic whole-file replacement (uniquely-named temp file + rename): a crash mid-write
  // must not leave a truncated TOML/YAML/MD behind — an unparsable org file drops its
  // ticket from the board (reconcile's listTickets), so the core's own state-file
  // discipline applies here too.
  await atomicWriteFile(p, text);
}

/** Where deleted organizations go, under a Project's `organizations/`. */
export const TRASH_DIR = ".trash";

export class OrgStore {
  constructor(readonly root: string) {}

  dir(projectId: string, orgId: string): string {
    return orgDir(this.root, projectId, orgId);
  }

  /** Organization ids under a Project: the directories that carry an `org_config.toml`. */
  async listOrgIds(projectId: string): Promise<string[]> {
    let items: import("node:fs").Dirent[];
    try {
      items = await fs.readdir(organizationsDir(this.root, projectId), { withFileTypes: true });
    } catch {
      return [];
    }
    const out: string[] = [];
    for (const d of items) {
      if (!d.isDirectory() || !ID.test(d.name)) continue;
      if (
        (await readText(
          orgConfigPath(path.join(organizationsDir(this.root, projectId), d.name)),
        )) !== null
      ) {
        out.push(d.name);
      }
    }
    return out.sort();
  }

  async exists(projectId: string, orgId: string): Promise<boolean> {
    return (await readText(orgConfigPath(this.dir(projectId, orgId)))) !== null;
  }

  /**
   * Creates the directory skeleton and the one file that is not a caller's to choose: the
   * all-hands channel, which exists for as long as the organization does.
   */
  async createLayout(dir: string, createdAt = new Date().toISOString()): Promise<void> {
    await fs.mkdir(path.dirname(dir), { recursive: true });
    // Not recursive: an existing directory is a taken id, never something to reuse.
    await fs.mkdir(dir, { recursive: false });
    for (const sub of [
      handbookDir(dir),
      calendarDir(dir),
      ticketsDir(dir),
      channelsDir(dir),
      workspaceDir(dir),
    ]) {
      await fs.mkdir(sub, { recursive: true });
    }
    // The purpose is left empty on purpose: seeded English prose would show verbatim in
    // every locale. The channel view renders its own localized line for the all-hands
    // channel when the purpose is unset, and a person may still write one.
    await this.writeChannel(dir, DEFAULT_CHANNEL_ID, {
      name: "All hands",
      purpose: "",
      createdBy: "system",
      createdAt,
      archived: false,
      everyone: true,
    });
  }

  async remove(dir: string): Promise<void> {
    await fs.rm(dir, { recursive: true, force: true });
  }

  /**
   * Takes an organization out of the Project without destroying it: its directory moves to
   * `organizations/.trash/<orgId>-<stamp>/`, whole. Nothing lists a dot-directory, so the
   * organization is gone from every surface; moving the directory
   * back is how it is restored. Returns where it went.
   */
  async trash(projectId: string, orgId: string, stamp: string): Promise<string> {
    const bin = path.join(organizationsDir(this.root, projectId), TRASH_DIR);
    await fs.mkdir(bin, { recursive: true });
    const target = path.join(bin, `${orgId}-${stamp.replace(/[^0-9A-Za-z]/g, "")}`);
    await fs.rename(this.dir(projectId, orgId), target);
    return target;
  }

  // ---- org_config.toml / org_chart.yaml / desks.toml / handbook/ ----

  async readConfig(dir: string): Promise<OrgFile<OrgConfig> | null> {
    const raw = await readText(orgConfigPath(dir));
    return raw === null ? null : { raw, parsed: parseOrgConfig(raw) };
  }

  async writeConfig(dir: string, cfg: OrgConfig): Promise<void> {
    await writeText(orgConfigPath(dir), serializeOrgConfig(cfg));
  }

  async readChart(dir: string, orgId: string): Promise<OrgFile<OrgChart> | null> {
    const raw = await readText(orgChartPath(dir));
    return raw === null ? null : { raw, parsed: parseOrgChart(raw, orgId) };
  }

  async writeChart(dir: string, chart: OrgChart): Promise<void> {
    await writeText(orgChartPath(dir), serializeOrgChart(chart));
  }

  /** A missing ledger is an empty ledger. */
  async readDesks(dir: string): Promise<OrgFile<Desks>> {
    const raw = await readText(desksPath(dir));
    return raw === null
      ? { raw: "", parsed: { ok: true, value: {} } }
      : { raw, parsed: parseDesks(raw) };
  }

  async writeDesks(dir: string, desks: Desks): Promise<void> {
    await writeText(desksPath(dir), serializeDesks(desks));
  }

  async readHandbook(dir: string): Promise<string> {
    return (await readText(handbookPath(dir))) ?? "";
  }

  async writeHandbook(dir: string, content: string): Promise<void> {
    await writeText(handbookPath(dir), content);
  }

  /** Every file under `handbook/` (hidden entries skipped), the index first, then by path. */
  async listHandbookFiles(dir: string): Promise<HandbookFile[]> {
    const base = handbookDir(dir);
    const out: HandbookFile[] = [];
    const walk = async (rel: string[]): Promise<void> => {
      let entries: import("node:fs").Dirent[];
      try {
        entries = await fs.readdir(path.join(base, ...rel), { withFileTypes: true });
      } catch {
        return;
      }
      for (const e of entries) {
        if (e.name.startsWith(".")) continue;
        const next = [...rel, e.name];
        if (e.isDirectory()) {
          await walk(next);
        } else if (e.isFile()) {
          const st = await fs.stat(path.join(base, ...next));
          out.push({ path: next.join("/"), size: st.size, mtimeMs: st.mtimeMs });
        }
      }
    };
    await walk([]);
    out.sort((a, b) =>
      a.path === "README.md" ? -1 : b.path === "README.md" ? 1 : a.path.localeCompare(b.path),
    );
    return out;
  }

  async readHandbookFile(dir: string, rel: string): Promise<string | null> {
    return readText(handbookFilePath(dir, rel));
  }

  async writeHandbookFile(dir: string, rel: string, content: string): Promise<void> {
    await writeText(handbookFilePath(dir, rel), content);
  }

  /** Removes the file and any directory it leaves empty, up to (not including) `handbook/`. */
  async deleteHandbookFile(dir: string, rel: string): Promise<void> {
    const file = handbookFilePath(dir, rel);
    await fs.rm(file, { force: true });
    const base = handbookDir(dir);
    let parent = path.dirname(file);
    while (parent !== base && parent.startsWith(base)) {
      try {
        await fs.rmdir(parent);
      } catch {
        break;
      }
      parent = path.dirname(parent);
    }
  }

  // ---- calendar ----

  async listCalendar(dir: string): Promise<CalendarFile[]> {
    const out: CalendarFile[] = [];
    let agents: import("node:fs").Dirent[];
    try {
      agents = await fs.readdir(calendarDir(dir), { withFileTypes: true });
    } catch {
      return out;
    }
    for (const a of agents) {
      if (!a.isDirectory() || !ID.test(a.name)) continue;
      const files = await fs.readdir(calendarDir(dir, a.name), { withFileTypes: true });
      for (const f of files) {
        if (!f.isFile() || !f.name.endsWith(".toml")) continue;
        const name = f.name.slice(0, -".toml".length);
        if (!isCalendarEventName(name)) continue;
        const p = calendarEventPath(dir, a.name, name);
        const [raw, stat] = await Promise.all([fs.readFile(p, "utf8"), fs.stat(p)]);
        out.push({
          agentId: a.name,
          name,
          raw,
          parsed: parseCalendarEvent(name, raw),
          mtimeMs: stat.mtimeMs,
        });
      }
    }
    return out.sort((x, y) => x.agentId.localeCompare(y.agentId) || x.name.localeCompare(y.name));
  }

  async readCalendarEvent(
    dir: string,
    agentId: string,
    name: string,
  ): Promise<CalendarFile | null> {
    const p = calendarEventPath(dir, agentId, name);
    const raw = await readText(p);
    if (raw === null) return null;
    const stat = await fs.stat(p);
    return { agentId, name, raw, parsed: parseCalendarEvent(name, raw), mtimeMs: stat.mtimeMs };
  }

  async writeCalendarEvent(dir: string, agentId: string, name: string, raw: string): Promise<void> {
    await writeText(calendarEventPath(dir, agentId, name), raw);
  }

  async deleteCalendarEvent(dir: string, agentId: string, name: string): Promise<boolean> {
    try {
      await fs.unlink(calendarEventPath(dir, agentId, name));
      return true;
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
      throw err;
    }
  }

  // ---- tickets ----

  /**
   * Every `.md` file under a `<yyyy-mm>/<column>/` directory, its name minus the extension
   * taken as the ticket id. Anything outside that shape — another month directory, a
   * directory that is not one of the columns, a file that is not Markdown — is skipped.
   * The id itself is NOT matched against `TICKET_ID_PATTERN` here: a file named by hand is
   * still a ticket the board has to show, and what it is called is the caller's to judge.
   */
  async listTickets(dir: string): Promise<TicketFile[]> {
    const out: TicketFile[] = [];
    let months: import("node:fs").Dirent[];
    try {
      months = await fs.readdir(ticketsDir(dir), { withFileTypes: true });
    } catch {
      return out;
    }
    for (const m of months) {
      if (!m.isDirectory() || !MONTH.test(m.name)) continue;
      for (const column of ORG_TICKET_COLUMNS) {
        const colDir = path.join(ticketsDir(dir), m.name, column);
        let files: import("node:fs").Dirent[];
        try {
          files = await fs.readdir(colDir, { withFileTypes: true });
        } catch {
          continue;
        }
        for (const f of files) {
          if (!f.isFile() || !f.name.endsWith(".md")) continue;
          const ticketId = f.name.slice(0, -".md".length);
          const p = path.join(colDir, f.name);
          const [raw, stat] = await Promise.all([fs.readFile(p, "utf8"), fs.stat(p)]);
          out.push({
            relPath: path.relative(dir, p),
            ticketId,
            column,
            raw,
            parsed: parseTicket(raw),
            mtimeMs: stat.mtimeMs,
          });
        }
      }
    }
    return out.sort((a, b) => a.ticketId.localeCompare(b.ticketId));
  }

  /** Locates a ticket by id: its month is in the id, its column is whichever directory holds it. */
  async findTicket(dir: string, ticketId: string): Promise<TicketFile | null> {
    for (const column of ORG_TICKET_COLUMNS) {
      const p = ticketPath(dir, ticketId, column);
      const raw = await readText(p);
      if (raw === null) continue;
      const stat = await fs.stat(p);
      return {
        relPath: path.relative(dir, p),
        ticketId,
        column,
        raw,
        parsed: parseTicket(raw),
        mtimeMs: stat.mtimeMs,
      };
    }
    return null;
  }

  async writeTicket(
    dir: string,
    ticketId: string,
    column: OrgTicketStatus,
    doc: TicketDoc,
  ): Promise<void> {
    await writeText(ticketPath(dir, ticketId, column), serializeTicket(doc));
  }

  /** Rewrites the file in its new column and removes the old one (the frontmatter was updated by the caller). */
  async moveTicket(
    dir: string,
    ticketId: string,
    from: OrgTicketStatus,
    to: OrgTicketStatus,
    doc: TicketDoc,
  ): Promise<void> {
    await this.writeTicket(dir, ticketId, to, doc);
    if (from !== to) {
      try {
        await fs.unlink(ticketPath(dir, ticketId, from));
      } catch (err) {
        // Already gone is fine; anything else must not pass in silence — a quietly kept
        // old column would leave the id in two columns for the reader to resolve.
        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
      }
    }
  }

  // ---- channels ----

  /**
   * Every channel directory that carries a `channel.toml`, by id. A plain file under
   * `channels/` is not a channel and is skipped rather than reported, and neither is a
   * directory without that file — a stray entry must not make the whole listing an error.
   */
  async listChannels(dir: string): Promise<ChannelFile[]> {
    let entries: import("node:fs").Dirent[];
    try {
      entries = await fs.readdir(channelsDir(dir), { withFileTypes: true });
    } catch {
      return [];
    }
    const out: ChannelFile[] = [];
    for (const e of entries) {
      if (!e.isDirectory() || !isChannelId(e.name)) continue;
      const file = await this.readChannel(dir, e.name);
      if (file !== null) out.push(file);
    }
    return out.sort((a, b) => a.channelId.localeCompare(b.channelId));
  }

  /** Null when the directory carries no `channel.toml`: it is not a channel. */
  async readChannel(dir: string, channelId: string): Promise<ChannelFile | null> {
    const p = channelConfigPath(dir, channelId);
    const raw = await readText(p);
    if (raw === null) return null;
    const stat = await fs.stat(p);
    return { channelId, raw, parsed: parseChannelConfig(channelId, raw), mtimeMs: stat.mtimeMs };
  }

  async writeChannel(dir: string, channelId: string, cfg: ChannelConfig): Promise<void> {
    await writeText(channelConfigPath(dir, channelId), serializeChannelConfig(cfg));
  }

  // ---- channel messages ----

  async listMessageDays(dir: string, channelId: string): Promise<string[]> {
    let files: import("node:fs").Dirent[];
    try {
      files = await fs.readdir(channelDir(dir, channelId), { withFileTypes: true });
    } catch {
      return [];
    }
    return files
      .filter(
        (f) =>
          f.isFile() && f.name.endsWith(".jsonl") && DATE.test(f.name.slice(0, -".jsonl".length)),
      )
      .map((f) => f.name.slice(0, -".jsonl".length))
      .sort()
      .reverse();
  }

  async appendMessageLine(
    dir: string,
    channelId: string,
    date: string,
    line: string,
  ): Promise<void> {
    const p = channelDayPath(dir, channelId, date);
    await fs.mkdir(path.dirname(p), { recursive: true });
    await fs.appendFile(p, `${line}\n`, "utf8");
  }

  /** Every parsable message of a day, in file order; malformed lines are reported alongside. */
  async readMessageDay(
    dir: string,
    channelId: string,
    date: string,
  ): Promise<{ messages: OrgChannelMessage[]; invalid: number }> {
    const raw = await readText(channelDayPath(dir, channelId, date));
    if (raw === null) return { messages: [], invalid: 0 };
    const messages: OrgChannelMessage[] = [];
    let invalid = 0;
    for (const line of raw.split("\n")) {
      if (line.trim() === "") continue;
      const r = parseChannelMessageLine(line);
      if (r.ok) messages.push(r.value);
      else invalid++;
    }
    return { messages, invalid };
  }

  /**
   * Tail scan: the complete lines after a byte offset, and the offset they end at. A file
   * shorter than the offset (rewritten by hand) is re-read from the start.
   */
  async readMessagesFrom(
    dir: string,
    channelId: string,
    date: string,
    offset: number,
  ): Promise<{ lines: string[]; nextOffset: number }> {
    const p = channelDayPath(dir, channelId, date);
    let buf: Buffer;
    try {
      buf = await fs.readFile(p);
    } catch {
      return { lines: [], nextOffset: 0 };
    }
    const start = offset > buf.length ? 0 : offset;
    const lastNl = buf.lastIndexOf(0x0a);
    if (lastNl < start) return { lines: [], nextOffset: start };
    const text = buf.subarray(start, lastNl + 1).toString("utf8");
    return {
      lines: text.split("\n").filter((l) => l.trim() !== ""),
      nextOffset: lastNl + 1,
    };
  }

  // ---- workspace ----

  /**
   * Where an employee's workspace spec points, without touching the disk: relative → under
   * the shared workspace, absolute → itself. Null only when a relative spec climbs out of
   * the shared workspace with `..` — that is a spec no organization may hold, whether or not
   * the directory happens to exist.
   */
  workspaceTarget(shared: string, spec: string): string | null {
    if (path.isAbsolute(spec)) return spec;
    const target = path.resolve(shared, spec);
    const rel = path.relative(shared, target);
    return rel.startsWith("..") || path.isAbsolute(rel) ? null : target;
  }

  /**
   * Resolves an employee's workspace as the chart writes it, read-only: null when the spec
   * escapes the shared workspace or the directory does not exist. Callers that are about to
   * put an employee to work use {@link ensureWorkspace} instead.
   */
  async resolveWorkspace(shared: string, spec: string): Promise<string | null> {
    const target = this.workspaceTarget(shared, spec);
    if (target === null) return null;
    try {
      const stat = await fs.stat(target);
      return stat.isDirectory() ? target : null;
    } catch {
      return null;
    }
  }

  /**
   * The workspace to open a session in, created when it is the organization's to create: a
   * relative spec names a partition of the shared workspace, so the server makes it rather
   * than refusing an employee for a directory nobody thought to create; an absolute spec
   * names an arbitrary user directory and must already exist. Null when a relative spec
   * escapes the shared workspace, or when an absolute one is missing or not a directory.
   */
  async ensureWorkspace(shared: string, spec: string): Promise<string | null> {
    const target = this.workspaceTarget(shared, spec);
    if (target === null) return null;
    if (path.isAbsolute(spec)) return this.resolveWorkspace(shared, spec);
    try {
      await fs.mkdir(target, { recursive: true });
    } catch {
      return null;
    }
    return target;
  }
}