@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/core/src/stations/account-files.ts

@@ -0,0 +1,41 @@
+import { readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { log } from '../log.js';
+
+export interface AccountFiles {
+  path: (accountId: string) => string;
+  forget: (accountId: string) => void;
+  forgetExcept: (keptAccountIds: readonly string[]) => void;
+}
+
+const safeSegment = (s: string): string => s.replace(/[^A-Za-z0-9_-]/g, '_');
+
+function listed(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+export function accountFiles(dirEnv: string, prefix: string): AccountFiles {
+  const dir = (): string => process.env[dirEnv] ?? join(homedir(), '.metro');
+  const name = (accountId: string): string => `${prefix}${safeSegment(accountId)}.json`;
+  const remove = (file: string, reason: string): void => {
+    rmSync(join(dir(), file), { force: true });
+    log.info({ file: join(dir(), file) }, reason);
+  };
+  return {
+    path: (accountId) => join(dir(), name(accountId)),
+    forget: (accountId) => {
+      remove(name(accountId), 'station: removed the files of a detached account');
+    },
+    forgetExcept: (keptAccountIds) => {
+      const kept = new Set(keptAccountIds.map(name));
+      for (const file of listed(dir()))
+        if (file.startsWith(prefix) && file.endsWith('.json') && !kept.has(file))
+          remove(file, 'station: removed the files of an account that is no longer attached');
+    },
+  };
+}

package/runtime/node_modules/@metro-labs/core/src/stations/account-store.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg } from '../log.js';
+import { chmodIfExists } from '../secure-fs.js';
+
+export type Die = (msg: string) => never;
+
+export interface AccountStoreOpts<T> {
+  prefix: string;
+  validate?: (raw: T[], die: Die) => void;
+}
+
+export interface Loader<T> {
+  die: Die;
+  loadAccounts: () => T[];
+}
+
+const envName = (prefix: string): string =>
+  `${prefix.toUpperCase().replace(/-/g, '_')}_ACCOUNTS_FILE`;
+
+const accountsFile = (prefix: string): string =>
+  process.env[envName(prefix)] ?? join(homedir(), '.metro', `${prefix}-accounts.json`);
+
+function checkIds(raw: { id: string }[], die: Die): void {
+  const seen = new Set<string>();
+  for (const a of raw) {
+    if (!a.id) die('account missing id');
+    if (seen.has(a.id)) die(`duplicate account id '${a.id}'`);
+    seen.add(a.id);
+  }
+}
+
+function readList<T>(file: string, die: Die): T[] {
+  if (!existsSync(file))
+    return die(
+      `no accounts file ${file} — the daemon writes it from ~/.metro/agents/agent.json at boot; attach an account to this station from the page first`,
+    );
+  chmodIfExists(file);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return die(`bad ${file}: ${errMsg(e)}`);
+  }
+  if (!Array.isArray(raw) || raw.length === 0)
+    return die(`${file} must be a non-empty array`);
+  return raw as T[];
+}
+
+export function makeAccountStore<T extends { id: string }>(
+  opts: AccountStoreOpts<T>,
+): Loader<T> {
+  const die: Die = (msg) => {
+    process.stderr.write(`${opts.prefix}: ${msg}\n`);
+    process.exit(2);
+  };
+
+  function loadAccounts(): T[] {
+    const raw = readList<T>(accountsFile(opts.prefix), die);
+    checkIds(raw, die);
+    opts.validate?.(raw, die);
+    return raw;
+  }
+
+  return { die, loadAccounts };
+}
+
+export function resolveAccountId(
+  accounts: Map<string, unknown>,
+  args: { account?: string; line?: string },
+  parseAccountId: (line: string) => string | undefined,
+): string {
+  const have = [...accounts.keys()];
+  let id = args.account;
+  id ??= args.line ? parseAccountId(args.line) : undefined;
+  id ??= have.length === 1 ? have[0] : undefined;
+  if (id === undefined)
+    throw new Error(`name an account (have: ${have.join(', ')})`);
+  if (!accounts.has(id))
+    throw new Error(`unknown account '${id}' (have: ${have.join(', ')})`);
+  return id;
+}

package/runtime/node_modules/@metro-labs/{mcp → core}/src/stations/attachments.ts

@@ -106,9 +106,16 @@ export const saveBufferToCache = async (
   meta: { mime?: string; name?: string },
 ): Promise<SavedAttachment> => {
   assertAttachmentSize(data.length);
-  const { writeFile } = await import('node:fs/promises');
+  const { writeFile, rename, rm } = await import('node:fs/promises');
+  const { randomUUID } = await import('node:crypto');
   const path = await cachePathFor(messageId, index, meta);
-  await writeFile(path, data);
+  const part = `${await cachePathFor(randomUUID(), index, meta)}.part`;
+  try {
+    await writeFile(part, data);
+    await rename(part, path);
+  } finally {
+    await rm(part, { force: true });
+  }
   return { path, mime: meta.mime, name: meta.name, bytes: data.length };
 };
 
@@ -190,7 +197,6 @@ export const toCanonical = (a: {
 }): Record<string, unknown> => ({
   kind: kindOf(a.mime, a.path),
   path: a.path,
-  url: a.path,
   name: a.name,
   mime: a.mime,
 });

package/runtime/node_modules/@metro-labs/core/src/stations/channel-directory.ts

@@ -0,0 +1,159 @@
+import { Line } from '../lines.js';
+import { ticketStore } from '../tickets.js';
+import { TrainError } from '../train-error.js';
+
+export const DIRECTORY_LIMIT = 5000;
+const SNAPSHOT_BYTES = 2 * 1024 * 1024;
+const CURSOR_TTL = 5 * 60 * 1000;
+const KINDS = new Set(['direct', 'group', 'channel', 'thread']);
+
+export interface ChannelEntry {
+  id: string;
+  line: string;
+  name?: string;
+  kind: 'direct' | 'group' | 'channel' | 'thread';
+}
+
+export interface ChannelCapability {
+  supported: boolean;
+  complete: boolean;
+  source: 'remote' | 'local' | 'mixed' | 'unsupported';
+  reason?: string;
+}
+
+export interface ChannelSnapshot {
+  channels: ChannelEntry[];
+  capability: ChannelCapability;
+}
+
+export interface ChannelList extends ChannelSnapshot {
+  next_cursor?: string;
+}
+
+export interface ChannelOptions {
+  query: string;
+  limit: number;
+  cursor?: string;
+}
+
+function cursorOf(cursor: unknown): string | undefined {
+  if (cursor === undefined) return undefined;
+  if (typeof cursor !== 'string' || !cursor || cursor.length > 2048)
+    throw new TrainError('bad_request', 'cursor must be a nonempty string of at most 2048 characters');
+  return cursor;
+}
+
+export function channelOptions(args: Record<string, unknown>): ChannelOptions {
+  const { query = '', limit = 50 } = args;
+  if (typeof query !== 'string' || query.length > 200)
+    throw new TrainError('bad_request', 'query must be a string of at most 200 characters');
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new TrainError('bad_request', 'limit must be an integer from 1 to 100');
+  const cursor = cursorOf(args.cursor);
+  return { query: query.trim().toLowerCase(), limit, ...(cursor === undefined ? {} : { cursor }) };
+}
+
+export function channelMatches(entry: ChannelEntry, query: string): boolean {
+  return [entry.id, entry.line, entry.name ?? ''].some((value) => value.toLowerCase().includes(query));
+}
+
+export function channelEntry(entry: ChannelEntry, account: string): ChannelEntry | undefined {
+  if (!entry.id || entry.id.length > 1024 || entry.line.length > 2048 || !KINDS.has(entry.kind))
+    return undefined;
+  const parsed = Line.parse(entry.line);
+  if (parsed?.path[0] !== account || parsed.path.length < 2) return undefined;
+  return {
+    id: entry.id,
+    line: entry.line,
+    kind: entry.kind,
+    ...(entry.name ? { name: Array.from(entry.name).slice(0, 256).join('') } : {}),
+  };
+}
+
+function limitedCapability(capability: ChannelCapability): ChannelCapability {
+  return {
+    ...capability,
+    complete: false,
+    reason: [capability.reason, 'Directory metadata exceeded the local size or entry limit; results are partial.']
+      .filter(Boolean).join(' '),
+  };
+}
+
+function bounded(snapshot: ChannelSnapshot, account: string, query: string): ChannelSnapshot {
+  const seen = new Set<string>();
+  const channels: ChannelEntry[] = [];
+  let bytes = 0;
+  let clipped = snapshot.channels.length > DIRECTORY_LIMIT;
+  for (const raw of snapshot.channels.slice(0, DIRECTORY_LIMIT)) {
+    const entry = channelEntry(raw, account);
+    if (!entry) {
+      clipped = true;
+      continue;
+    }
+    if (seen.has(entry.line)) continue;
+    bytes += Buffer.byteLength(JSON.stringify(entry));
+    if (bytes > SNAPSHOT_BYTES) {
+      clipped = true;
+      break;
+    }
+    seen.add(entry.line);
+    if (channelMatches(raw, query)) channels.push(entry);
+  }
+  channels.sort((a, b) => a.line < b.line ? -1 : Number(a.line > b.line));
+  return { channels, capability: clipped ? limitedCapability(snapshot.capability) : { ...snapshot.capability } };
+}
+
+interface Cursor {
+  account: string;
+  query: string;
+  snapshot: ChannelSnapshot;
+  offset: number;
+  expiresAt: number;
+}
+
+export class ChannelDirectory {
+  private readonly cursors = ticketStore<Cursor>(CURSOR_TTL, 32);
+
+  async list(
+    account: string,
+    args: Record<string, unknown>,
+    load: () => Promise<ChannelSnapshot>,
+  ): Promise<ChannelList> {
+    const options = channelOptions(args);
+    const cursor = options.cursor === undefined
+      ? {
+        account,
+        query: options.query,
+        snapshot: bounded(await load(), account, options.query),
+        offset: 0,
+        expiresAt: Date.now() + CURSOR_TTL,
+      }
+      : this.resume(options.cursor, account, options.query);
+    return this.page(cursor, options.limit);
+  }
+
+  private resume(ticket: string, account: string, query: string): Cursor {
+    const cursor = this.cursors.peek(ticket);
+    if (!cursor || cursor.account !== account || cursor.query !== query || cursor.expiresAt <= Date.now())
+      throw new TrainError('channel_cursor', 'Invalid or expired channel cursor; start a new listing for this account and query.');
+    return cursor;
+  }
+
+  private page(cursor: Cursor, limit: number): ChannelList {
+    const { snapshot, offset } = cursor;
+    const channels = snapshot.channels.slice(offset, offset + limit).map((entry) => ({ ...entry }));
+    const nextOffset = offset + channels.length;
+    if (nextOffset >= snapshot.channels.length)
+      return { channels, capability: { ...snapshot.capability } };
+    const { ticket } = this.cursors.mint({ ...cursor, offset: nextOffset });
+    return {
+      channels,
+      capability: {
+        ...snapshot.capability,
+        complete: false,
+        reason: [snapshot.capability.reason, 'More channels are available; follow next_cursor.'].filter(Boolean).join(' '),
+      },
+      next_cursor: ticket,
+    };
+  }
+}

package/runtime/node_modules/@metro-labs/core/src/stations/channel-pages.ts

@@ -0,0 +1,129 @@
+import { ticketStore } from '../tickets.js';
+import { TrainError } from '../train-error.js';
+import { channelEntry, channelMatches, channelOptions, DIRECTORY_LIMIT, type ChannelEntry, type ChannelList } from './channel-directory.js';
+
+const TTL = 5 * 60 * 1000;
+const MAX_BYTES = 2 * 1024 * 1024;
+const CAP_REASON = 'Stopped after 5000 metadata records or pages; search does not cover the whole mailbox.';
+const SIZE_REASON = 'Directory metadata exceeded the local size or entry limit; search is partial.';
+
+export interface ChannelPage {
+  channels: ChannelEntry[];
+  scanned: number;
+  next?: string;
+}
+
+export type ChannelPageLoader = (token: string | undefined, limit: number, seen: ReadonlySet<string>) => Promise<ChannelPage>;
+
+interface Scan {
+  next?: string;
+  channels: ChannelEntry[];
+  seen: Set<string>;
+  visited: Set<string>;
+  scanned: number;
+  bytes: number;
+  complete: boolean;
+  stopped?: string;
+}
+
+interface Cursor {
+  account: string;
+  query: string;
+  scope: string;
+  expiresAt: number;
+  scan: Scan;
+  loaded?: Promise<Scan>;
+}
+
+function addEntries(scan: Scan, rows: ChannelEntry[], account: string, query: string): void {
+  for (const raw of rows) {
+    const entry = channelEntry(raw, account);
+    if (!entry) {
+      scan.stopped = SIZE_REASON;
+      continue;
+    }
+    if (scan.seen.has(entry.id)) continue;
+    const size = Buffer.byteLength(JSON.stringify(entry)) + Buffer.byteLength(JSON.stringify(entry.id));
+    if (scan.bytes + size > MAX_BYTES) {
+      scan.stopped = SIZE_REASON;
+      break;
+    }
+    scan.bytes += size;
+    scan.seen.add(entry.id);
+    if (channelMatches(raw, query)) scan.channels.push(entry);
+  }
+}
+
+function project(cursor: Cursor, page: ChannelPage): Scan {
+  const scan: Scan = {
+    next: page.next, channels: [], seen: new Set(cursor.scan.seen),
+    visited: new Set(cursor.scan.visited).add(cursor.scan.next ?? ''),
+    scanned: cursor.scan.scanned + page.scanned,
+    bytes: cursor.scan.bytes + Buffer.byteLength(page.next ?? ''), complete: !page.next,
+  };
+  if (page.next && scan.visited.has(page.next)) throw new TrainError('channel_page', 'The mailbox repeated a channel page token.');
+  addEntries(scan, page.channels, cursor.account, cursor.query);
+  if (scan.bytes > MAX_BYTES) scan.stopped = SIZE_REASON;
+  if (page.next && Math.max(scan.scanned, scan.visited.size) >= DIRECTORY_LIMIT) scan.stopped ??= CAP_REASON;
+  if (scan.stopped) {
+    scan.next = undefined;
+    scan.complete = false;
+  }
+  return scan;
+}
+
+export class ChannelPages {
+  private readonly cursors = ticketStore<Cursor>(TTL, 32);
+
+  async list(account: string, args: Record<string, unknown>, load: ChannelPageLoader, scope: string): Promise<ChannelList> {
+    const { query, limit, cursor: ticket } = channelOptions(args);
+    const cursor: Cursor = ticket === undefined
+      ? {
+        account, query, scope, expiresAt: Date.now() + TTL,
+        scan: { channels: [], seen: new Set(), visited: new Set(), scanned: 0, bytes: Buffer.byteLength(account + query + scope), complete: false },
+      }
+      : this.resume(ticket, account, query);
+    const scan = await this.load(cursor, load);
+    if (cursor.expiresAt <= Date.now()) throw new TrainError('channel_cursor', 'Channel listing expired; start a new listing.');
+    const channels = scan.channels.slice(0, limit);
+    const remaining = scan.channels.slice(channels.length);
+    const more = remaining.length > 0 || (!scan.complete && !scan.stopped);
+    const next = more ? this.cursors.mint({ ...cursor, scan: { ...scan, channels: remaining }, loaded: undefined }).ticket : undefined;
+    return {
+      channels: channels.map((entry) => ({ ...entry })),
+      capability: {
+        supported: true, complete: scan.complete && !more, source: 'remote',
+        reason: [cursor.scope, scan.stopped, more ? 'More metadata remains; follow next_cursor, even after an empty page.' : ''].filter(Boolean).join(' '),
+      },
+      ...(next === undefined ? {} : { next_cursor: next }),
+    };
+  }
+
+  private resume(ticket: string, account: string, query: string): Cursor {
+    const cursor = this.cursors.peek(ticket);
+    if (!cursor || cursor.account !== account || cursor.query !== query || cursor.expiresAt <= Date.now())
+      throw new TrainError('channel_cursor', 'Invalid or expired channel cursor; start a new listing for this account and query.');
+    return cursor;
+  }
+
+  private async load(cursor: Cursor, load: ChannelPageLoader): Promise<Scan> {
+    if (cursor.scan.channels.length || cursor.scan.complete || cursor.scan.stopped) return cursor.scan;
+    cursor.loaded ??= this.fetch(cursor, load);
+    try {
+      return await cursor.loaded;
+    } catch (err) {
+      cursor.loaded = undefined;
+      throw err;
+    }
+  }
+
+  private async fetch(cursor: Cursor, load: ChannelPageLoader): Promise<Scan> {
+    const count = Math.min(100, DIRECTORY_LIMIT - cursor.scan.scanned);
+    const page = await load(cursor.scan.next, count, new Set(cursor.scan.seen));
+    if (!Number.isInteger(page.scanned) || page.scanned < 0 || page.scanned > count || page.channels.length > page.scanned)
+      throw new TrainError('channel_page', 'The mailbox returned more channel metadata than requested.');
+    if (page.next !== undefined && (typeof page.next !== 'string' || !page.next || page.next.length > 16384))
+      throw new TrainError('channel_page', 'The mailbox returned an invalid channel page token.');
+    return project(cursor, page);
+  }
+}

package/runtime/node_modules/@metro-labs/core/src/stations/mail-text.ts

@@ -0,0 +1,72 @@
+export const MAX_TEXT_CHARS = 20_000;
+
+const ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  ndash: '-',
+  mdash: '-',
+  hellip: '...',
+  rsquo: "'",
+  lsquo: "'",
+  rdquo: '"',
+  ldquo: '"',
+};
+
+function codePoint(n: number): string {
+  return Number.isInteger(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
+}
+
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, name: string) => {
+    if (name.startsWith('#x') || name.startsWith('#X')) return codePoint(parseInt(name.slice(2), 16));
+    if (name.startsWith('#')) return codePoint(Number(name.slice(1)));
+    return ENTITIES[name.toLowerCase()] ?? whole;
+  });
+}
+
+export function htmlToText(html: string): string {
+  const text = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(head|style|script|title)\b[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<li\b[^>]*>/gi, '\n- ')
+    .replace(/<\/(p|div|tr|h[1-6]|blockquote|table|ul|ol)\s*>/gi, '\n')
+    .replace(/<(p|div|tr|h[1-6]|blockquote|table)\b[^>]*>/gi, '\n')
+    .replace(/<\/t[dh]\s*>/gi, ' ')
+    .replace(/<[^>]*>/g, '');
+  return tidy(decodeEntities(text));
+}
+
+export function tidy(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t ]+/g, ' ')
+    .split('\n')
+    .map((l) => l.trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function capText(text: string, max = MAX_TEXT_CHARS): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n[... ${String(text.length - max)} more characters]`;
+}
+
+export function bodyText(body: { contentType?: unknown; content?: unknown } | undefined): string {
+  const content = typeof body?.content === 'string' ? body.content : '';
+  return String(body?.contentType).toLowerCase() === 'html' ? htmlToText(content) : tidy(content);
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '<br>');
+}

package/runtime/node_modules/@metro-labs/core/src/stations/mail-trust.ts

@@ -0,0 +1,29 @@
+export interface MailHeader {
+  name?: string;
+  value?: string;
+}
+
+export type Screened = { skip: string } | { verified: boolean };
+
+const AUTOMATED_LOCAL = /^(no-?reply|do-?not-?reply|donotreply|mailer-daemon|notifications?)([+._-].*)?$/i;
+const BULK = new Set(['bulk', 'list', 'junk']);
+
+export const headerValues = (headers: MailHeader[], name: string): string[] =>
+  headers.filter((h) => (h.name ?? '').toLowerCase() === name).map((h) => (h.value ?? '').trim());
+
+export const firstHeader = (headers: MailHeader[], name: string): string | undefined => headerValues(headers, name)[0];
+
+export function automatedBySender(address: string): string | null {
+  const local = address.split('@')[0] ?? '';
+  return AUTOMATED_LOCAL.test(local) ? `sender ${address}` : null;
+}
+
+export function automatedByHeaders(headers: MailHeader[]): string | null {
+  if (firstHeader(headers, 'list-unsubscribe') !== undefined) return 'List-Unsubscribe';
+  const auto = firstHeader(headers, 'auto-submitted');
+  if (auto !== undefined && auto.toLowerCase() !== 'no') return `Auto-Submitted: ${auto}`;
+  const precedence = (firstHeader(headers, 'precedence') ?? '').toLowerCase();
+  return BULK.has(precedence) ? `Precedence: ${precedence}` : null;
+}
+
+export const domainOf = (address: string): string => (address.split('@')[1] ?? '').toLowerCase();