A local-first multi-agent app development platform, built on PenguinHarness
/**
* 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;
}
}