pi-post 0.1.0

package/src/registry.ts

@@ -0,0 +1,95 @@
+import { readdirSync, readFileSync, unlinkSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { registryDir } from "./mailbox.ts";
+
+export interface SessionRecord {
+  v: 1;
+  address: string;
+  sessionId: string;
+  /** Display name: pi session name when set, else the cwd's basename. */
+  name: string;
+  cwd: string;
+  /** Standing address of the session's canonical cwd. */
+  standing: string;
+  pid?: number;
+  startedAt: number;
+  lastSeen: number;
+}
+
+export type Presence = "live" | "offline";
+
+/** A record outlives the process that wrote it; shutdown marks, never removes. */
+export function writeRecord(root: string, record: SessionRecord): void {
+  const dir = registryDir(root);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, `${record.address}.json`);
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+export function readRecord(root: string, address: string): SessionRecord | null {
+  try {
+    const raw = readFileSync(join(registryDir(root), `${address}.json`), "utf8");
+    const record = JSON.parse(raw) as SessionRecord;
+    return record.v === 1 && typeof record.address === "string" ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+export function listRecords(root: string): SessionRecord[] {
+  let names: string[];
+  try {
+    names = readdirSync(registryDir(root));
+  } catch {
+    return [];
+  }
+  const records: SessionRecord[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const record = readRecord(root, name.slice(0, -".json".length));
+    if (record) records.push(record);
+  }
+  return records;
+}
+
+export function touchRecord(root: string, address: string): void {
+  const record = readRecord(root, address);
+  if (record) writeRecord(root, { ...record, lastSeen: Date.now() });
+}
+
+export function markOffline(root: string, address: string): void {
+  const record = readRecord(root, address);
+  if (record) {
+    const { pid: _pid, ...rest } = record;
+    writeRecord(root, { ...rest, lastSeen: Date.now() });
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function presence(record: SessionRecord): Presence {
+  return record.pid !== undefined && pidAlive(record.pid) ? "live" : "offline";
+}
+
+/** Remove registry records for sessions that are offline and stale. Mail is never touched. */
+export function sweepRegistry(root: string, maxAgeMs = 30 * 24 * 60 * 60 * 1000): void {
+  const now = Date.now();
+  for (const record of listRecords(root)) {
+    if (presence(record) === "offline" && now - record.lastSeen > maxAgeMs) {
+      try {
+        unlinkSync(join(registryDir(root), `${record.address}.json`));
+      } catch {
+        // already gone
+      }
+    }
+  }
+}

package/src/resolve.ts

@@ -0,0 +1,60 @@
+import { basename } from "node:path";
+import { canonicalPath, isAddress, looksLikePath, standingAddress } from "./address.ts";
+import { listRecords, presence, type SessionRecord } from "./registry.ts";
+
+export interface ResolvedTarget {
+  address: string;
+  /** Human-readable description of what the address names. */
+  display: string;
+  record?: SessionRecord;
+}
+
+export class AmbiguousTargetError extends Error {
+  constructor(target: string, candidates: SessionRecord[]) {
+    const lines = candidates.map((r) => `  ${r.name} (${r.address}) — ${r.cwd}`);
+    super(`"${target}" matches more than one session; use an address:\n${lines.join("\n")}`);
+    this.name = "AmbiguousTargetError";
+  }
+}
+
+export class UnknownTargetError extends Error {
+  constructor(target: string) {
+    super(`"${target}" is not an address, a directory path, or a known session name`);
+    this.name = "UnknownTargetError";
+  }
+}
+
+/**
+ * Resolve a target string to an address. Refuses rather than guesses:
+ * - an explicit address is taken as-is
+ * - anything path-shaped becomes the directory's standing address
+ * - otherwise it must match exactly one registered session by name
+ *   (live sessions outrank offline ones before ambiguity is declared)
+ */
+export function resolveTarget(root: string, target: string, cwd?: string): ResolvedTarget {
+  const trimmed = target.trim();
+  if (isAddress(trimmed)) {
+    const record = listRecords(root).find((r) => r.address === trimmed);
+    return { address: trimmed, display: record ? `${record.name} (${record.cwd})` : trimmed, record };
+  }
+
+  if (looksLikePath(trimmed)) {
+    const canonical = canonicalPath(trimmed, cwd);
+    return { address: standingAddress(canonical), display: canonical };
+  }
+
+  const records = listRecords(root);
+  const byName = records.filter((r) => r.name === trimmed);
+  const byBase = byName.length > 0 ? byName : records.filter((r) => basename(r.cwd) === trimmed);
+  let matches = byBase;
+  if (matches.length > 1) {
+    const live = matches.filter((r) => presence(r) === "live");
+    if (live.length === 1) matches = live;
+  }
+  if (matches.length === 1) {
+    const record = matches[0]!;
+    return { address: record.address, display: `${record.name} (${record.cwd})`, record };
+  }
+  if (matches.length > 1) throw new AmbiguousTargetError(trimmed, matches);
+  throw new UnknownTargetError(trimmed);
+}