Skip to content

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

5.7 KB
Raw Blame
/**
 * Where an organization lives on disk. Every path is under the Project directory —
 * `<root>/<projectId>/organizations/<orgId>/` — so the model's `<app_data_dir>` placeholder
 * (its Environment's App Data Dir is the Project directory) resolves to the same place the
 * server reads. Files are the truth for company mode; nothing here touches SQLite.
 */
import path from "node:path";
import { projectDir } from "@adelie/core";
import type { OrgTicketStatus } from "../api/types.js";

/** The kanban columns in board order; each is a directory under `tickets/<yyyy-mm>/`. */
export const ORG_TICKET_COLUMNS: readonly OrgTicketStatus[] = [
  "proposed",
  "in_progress",
  "review",
  "done",
  "rejected",
];

export function isTicketColumn(value: string): value is OrgTicketStatus {
  return (ORG_TICKET_COLUMNS as readonly string[]).includes(value);
}

export function organizationsDir(root: string, projectId: string): string {
  return path.join(projectDir(root, projectId), "organizations");
}

export function orgDir(root: string, projectId: string, orgId: string): string {
  return path.join(organizationsDir(root, projectId), orgId);
}

export function orgConfigPath(dir: string): string {
  return path.join(dir, "org_config.toml");
}

export function orgChartPath(dir: string): string {
  return path.join(dir, "org_chart.yaml");
}

export function desksPath(dir: string): string {
  return path.join(dir, "desks.toml");
}

/** `handbook/`: the organization handbook, the company's knowledge base. */
export function handbookDir(dir: string): string {
  return path.join(dir, "handbook");
}

/** `handbook/README.md`: the index every work run reads first. */
export function handbookPath(dir: string): string {
  return path.join(handbookDir(dir), "README.md");
}

/**
 * A path inside the handbook, relative to `handbook/`: plain segments (no hidden files, no
 * `.`/`..`, at most eight levels), so a request can never name a file outside the directory.
 */
export const HANDBOOK_FILE_PATTERN =
  /^(?:[A-Za-z0-9][A-Za-z0-9._-]{0,63}\/){0,7}[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;

export function isHandbookFilePath(rel: string): boolean {
  return HANDBOOK_FILE_PATTERN.test(rel);
}

export function handbookFilePath(dir: string, rel: string): string {
  if (!isHandbookFilePath(rel)) throw new Error(`invalid handbook path: ${rel}`);
  return path.join(handbookDir(dir), ...rel.split("/"));
}

/**
 * Calendar event names: the file's stem. The store only lists names matching this, so the
 * writers validate against the same rule — otherwise a write lands a file no pass ever sees.
 */
export const CALENDAR_EVENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;

export function isCalendarEventName(name: string): boolean {
  return CALENDAR_EVENT_NAME_PATTERN.test(name);
}

export function calendarDir(dir: string, agentId?: string): string {
  return agentId === undefined ? path.join(dir, "calendar") : path.join(dir, "calendar", agentId);
}

export function calendarEventPath(dir: string, agentId: string, name: string): string {
  return path.join(calendarDir(dir, agentId), `${name}.toml`);
}

export function ticketsDir(dir: string): string {
  return path.join(dir, "tickets");
}

/** `tickets/<yyyy-mm>/<column>/<ticketId>.md`; the month comes from the id's date prefix. */
export function ticketPath(dir: string, ticketId: string, column: OrgTicketStatus): string {
  return path.join(ticketsDir(dir), ticketMonth(ticketId), column, `${ticketId}.md`);
}

/** The `yyyy-mm` a ticket id belongs to (its first seven characters). */
export function ticketMonth(ticketId: string): string {
  return ticketId.slice(0, 7);
}

/**
 * Channel ids follow the semantic-id rule organization and Agent ids use, because the id is
 * the directory name under `channels/`. `default_channel` is reserved for the all-hands
 * channel every employee and every Project member belongs to implicitly.
 */
export const CHANNEL_ID_PATTERN = /^[a-z][a-z0-9_]{1,63}$/;

export const DEFAULT_CHANNEL_ID = "default_channel";

export function isChannelId(value: string): boolean {
  return CHANNEL_ID_PATTERN.test(value);
}

/** `channels/`: one directory per channel. */
export function channelsDir(dir: string): string {
  return path.join(dir, "channels");
}

export function channelDir(dir: string, channelId: string): string {
  return path.join(channelsDir(dir), channelId);
}

/** `channels/<channel_id>/channel.toml`: the channel's name, purpose and membership. */
export function channelConfigPath(dir: string, channelId: string): string {
  return path.join(channelDir(dir, channelId), "channel.toml");
}

/** `channels/<channel_id>/<yyyy-mm-dd>.jsonl`: one day's messages, one JSON line each. */
export function channelDayPath(dir: string, channelId: string, date: string): string {
  return path.join(channelDir(dir, channelId), `${date}.jsonl`);
}

export function workspaceDir(dir: string): string {
  return path.join(dir, "workspace");
}

/**
 * The canonical form of an employee's workspace spec, so `./hr`, `hr/` and `hr` are one
 * partition in the chart rather than three spellings of it: a leading `./` and trailing
 * slashes go, repeated slashes collapse, and `.` (the whole shared workspace) stays `.`.
 * An absolute path keeps its shape — it is a user's directory, not ours to rewrite.
 */
export function normalizeWorkspaceSpec(spec: string): string {
  let out = spec.trim().replace(/\/{2,}/g, "/");
  if (path.isAbsolute(out)) return out.length > 1 ? out.replace(/\/+$/, "") : out;
  while (out.startsWith("./")) out = out.slice(2);
  out = out.replace(/\/+$/, "");
  return out === "" ? "." : out;
}

/** The CEO's Agent id is fixed by the organization id, so creation can check it is free before writing anything. */
export function ceoAgentId(orgId: string): string {
  return `${orgId}_ceo`;
}