@stage-labs/metro 0.1.0-beta.16 → 0.1.0-beta.161

package/runtime/node_modules/@metro-labs/core/src/secure-fs.ts

@@ -0,0 +1,57 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import { errMsg, log } from './log.js';
+
+export function ensureSecureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+  }
+}
+
+export function chmodIfExists(path: string, mode = 0o600): void {
+  if (!existsSync(path)) return;
+  try {
+    if ((statSync(path).mode & 0o777) !== mode) chmodSync(path, mode);
+  } catch {
+  }
+}
+
+export function writeSecure(path: string, data: string): void {
+  ensureSecureDir(dirname(path));
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, data, { mode: 0o600 });
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+  }
+  renameSync(tmp, path);
+  chmodIfExists(path, 0o600);
+}
+
+export function readJson<T>(
+  path: string,
+  fallback: T,
+  opts?: { warn?: string },
+): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch (err) {
+    if (opts?.warn) log.warn({ err: errMsg(err), path }, opts.warn);
+    return fallback;
+  }
+}
+
+export function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, JSON.stringify(value, null, 2));
+}

package/runtime/node_modules/@metro-labs/core/src/station-names.ts

@@ -0,0 +1,13 @@
+export const STATIONS = [
+  'xmtp',
+  'telegram-bot',
+  'telegram',
+  'discord-bot',
+  'whatsapp',
+  'threema',
+  'webhook',
+] as const;
+
+export type StationName = (typeof STATIONS)[number];
+
+export type ConnectorTransport = 'http' | 'sse';

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

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { errMsg } from '../log.js';
+import { chmodIfExists } from '../secure-fs.js';
+
+export type Die = (msg: string) => never;
+
+export interface MakeLoaderOpts<T> {
+  prefix: string;
+  file: string;
+  validate: (raw: T[], die: Die) => void;
+}
+
+export interface Loader<T> {
+  die: Die;
+  loadAccounts: () => T[];
+}
+
+export function makeAccountStore<T extends { id: string }>(
+  opts: MakeLoaderOpts<T>,
+): Loader<T> {
+  const die: Die = (msg) => {
+    process.stderr.write(`${opts.prefix}: ${msg}\n`);
+    process.exit(2);
+  };
+
+  function loadAccounts(): T[] {
+    if (!existsSync(opts.file))
+      return die(
+        `no accounts file ${opts.file} — the daemon writes it from the database at boot; set DATABASE_URL and populate the accounts table`,
+      );
+    chmodIfExists(opts.file);
+    let raw: T[];
+    try {
+      raw = JSON.parse(readFileSync(opts.file, 'utf8')) as T[];
+    } catch (e) {
+      return die(`bad ${opts.file}: ${errMsg(e)}`);
+    }
+    if (!Array.isArray(raw) || raw.length === 0)
+      die(`${opts.file} must be a non-empty array`);
+    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 {
+  let id = args.account;
+  id ??= args.line ? parseAccountId(args.line) : undefined;
+  id ??= (accounts.size === 1 ? [...accounts.keys()][0] : 'default') ?? 'default';
+  if (!accounts.has(id))
+    throw new Error(
+      `unknown account '${id}' (have: ${[...accounts.keys()].join(', ')})`,
+    );
+  return id;
+}

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

@@ -0,0 +1,196 @@
+export const attachDir = (): string =>
+  process.env.METRO_XMTP_ATTACH_DIR ??
+  `${process.env.HOME}/.cache/metro/messenger-uploads`;
+
+const CACHE_NAME_RE = /^msg_[A-Za-z0-9]{1,16}_\d+\.[A-Za-z0-9]{1,5}$/;
+
+export const resolveCachedAttachment = (name: string): string | null =>
+  CACHE_NAME_RE.test(name) ? `${attachDir()}/${name}` : null;
+
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/heic': 'heic',
+  'audio/mp4': 'm4a',
+  'audio/mpeg': 'mp3',
+  'audio/ogg': 'ogg',
+  'audio/wav': 'wav',
+  'video/mp4': 'mp4',
+  'video/quicktime': 'mov',
+  'video/webm': 'webm',
+  'application/pdf': 'pdf',
+};
+
+const extFromName = (filename: string | undefined): string | undefined => {
+  const ext = filename
+    ?.split('?')[0]
+    ?.split('#')[0]
+    ?.split('.')
+    .pop()
+    ?.toLowerCase();
+  return ext !== undefined && ext.length >= 1 && ext.length <= 5
+    ? ext
+    : undefined;
+};
+
+export const extFromMime = (mime: string | undefined): string | undefined => {
+  if (mime === undefined) return undefined;
+  const mapped = MIME_EXT[mime];
+  if (mapped) return mapped;
+  if (mime.startsWith('image/')) return mime.slice(6).replace('jpeg', 'jpg');
+  return undefined;
+};
+
+const extFor = (
+  filename: string | undefined,
+  mime: string | undefined,
+): string => extFromName(filename) ?? extFromMime(mime) ?? 'bin';
+
+const cacheFileName = (
+  messageId: string,
+  index: number,
+  filename: string | undefined,
+  mime: string | undefined,
+): string => {
+  const safeId =
+    messageId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 16) || 'unknown';
+  return `msg_${safeId}_${index}.${extFor(filename, mime)}`;
+};
+
+export interface SavedAttachment {
+  path: string;
+  mime?: string;
+  name?: string;
+  bytes: number;
+}
+
+export const MAX_ATTACHMENT_BYTES = Number(
+  process.env.METRO_ATTACH_MAX_BYTES ?? 100 * 1024 * 1024,
+);
+
+export function assertAttachmentSize(bytes: number): void {
+  if (bytes > MAX_ATTACHMENT_BYTES)
+    throw new Error(
+      `attachment size ${bytes} exceeds limit of ${MAX_ATTACHMENT_BYTES} bytes`,
+    );
+}
+
+export function assertContentLength(header: string | null | undefined): void {
+  if (header == null) return;
+  const n = Number(header);
+  if (Number.isFinite(n)) assertAttachmentSize(n);
+}
+
+const cachePathFor = async (
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<string> => {
+  const { mkdir } = await import('node:fs/promises');
+  const nodePath = await import('node:path');
+  const dir = attachDir();
+  await mkdir(dir, { recursive: true });
+  return nodePath.join(
+    dir,
+    cacheFileName(messageId, index, meta.name, meta.mime),
+  );
+};
+
+export const saveBufferToCache = async (
+  data: Uint8Array,
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<SavedAttachment> => {
+  assertAttachmentSize(data.length);
+  const { writeFile } = await import('node:fs/promises');
+  const path = await cachePathFor(messageId, index, meta);
+  await writeFile(path, data);
+  return { path, mime: meta.mime, name: meta.name, bytes: data.length };
+};
+
+export const saveStreamToCache = async (
+  chunks: AsyncIterable<Uint8Array>,
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<SavedAttachment> => {
+  const { open, rename, rm } = await import('node:fs/promises');
+  const path = await cachePathFor(messageId, index, meta);
+  const part = `${path}.part`;
+  const handle = await open(part, 'w');
+  let bytes = 0;
+  try {
+    for await (const chunk of chunks) {
+      bytes += chunk.length;
+      assertAttachmentSize(bytes);
+      await handle.write(chunk);
+    }
+  } catch (err) {
+    await handle.close();
+    await rm(part, { force: true });
+    throw err;
+  }
+  await handle.close();
+  await rename(part, path);
+  return { path, mime: meta.mime, name: meta.name, bytes };
+};
+
+export const guessMime = (path: string): string => {
+  const ext = (path.split('.').pop() ?? '').toLowerCase();
+  const map: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    heic: 'image/heic',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    m4v: 'video/x-m4v',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+    pdf: 'application/pdf',
+  };
+  return map[ext] ?? 'application/octet-stream';
+};
+
+export const isImageMime = (mime: string): boolean =>
+  mime.toLowerCase().startsWith('image/');
+export const isImageExt = (path: string): boolean =>
+  /\.(png|jpe?g|gif|webp|heic|bmp|svg)$/i.test(path);
+
+export const appendFile = async (
+  form: FormData,
+  field: string,
+  path: string,
+  name: string,
+): Promise<void> => {
+  const data = await Bun.file(path).arrayBuffer();
+  form.append(field, new Blob([data]), name);
+};
+
+export const kindOf = (mime: string, path: string): string => {
+  if (isImageMime(mime) || isImageExt(path)) return 'image';
+  if (mime.startsWith('video/')) return 'video';
+  if (mime.startsWith('audio/')) return 'audio';
+  return 'file';
+};
+
+export const toCanonical = (a: {
+  path: string;
+  mime: string;
+  name: string;
+}): 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/messaging-normalize.ts

@@ -0,0 +1,88 @@
+type Args = Record<string, unknown>;
+export interface Normalized {
+  action: string;
+  args: Args;
+}
+
+interface Attachment {
+  kind?: string;
+  path?: string;
+  url?: string;
+  data?: string;
+  mime?: string;
+  name?: string;
+}
+
+interface DiscordFile {
+  file: string;
+  kind: string;
+  name: string;
+}
+
+const discordFile = (a: Attachment): DiscordFile | null => {
+  const file = a.path ?? a.url;
+  if (typeof file !== 'string') return null;
+  return { file, kind: a.kind ?? 'file', name: a.name ?? '' };
+};
+
+function discordAttachments(att: Attachment[]): Args {
+  const usable = att
+    .map(discordFile)
+    .filter((f): f is DiscordFile => f !== null);
+  if (!usable.length) return {};
+  return {
+    files: usable.map((f) => f.file),
+    attachmentKinds: usable.map((f) => f.kind),
+    attachmentNames: usable.map((f) => f.name),
+  };
+}
+
+export function normalizeDiscord(action: string, env: Args): Normalized {
+  const att = (env.attachments as Attachment[] | undefined) ?? [];
+  if (action === 'send') {
+    return { action: 'send', args: { ...env, ...discordAttachments(att) } };
+  }
+  if (action === 'reply') {
+    const replyTo = env.replyTo ?? env.messageId;
+    return {
+      action: 'send',
+      args: { ...env, replyTo, ...discordAttachments(att) },
+    };
+  }
+  if (action === 'unreact')
+    return { action: 'react', args: { ...env, emoji: '' } };
+  if (action === 'read') {
+    return {
+      action: 'fetch',
+      args: { line: env.line, limit: env.limit, before: env.before },
+    };
+  }
+  return { action, args: env };
+}
+
+export function normalizeTelegram(action: string, env: Args): Normalized {
+  if (action === 'reply') {
+    return {
+      action: 'send',
+      args: {
+        line: env.line,
+        text: env.text,
+        replyTo: env.replyTo,
+        attachments: env.attachments,
+      },
+    };
+  }
+  if (action === 'unreact')
+    return { action: 'react', args: { ...env, emoji: '' } };
+  return { action, args: env };
+}
+
+export function normalizeXmtp(action: string, env: Args): Normalized {
+  if (action === 'unreact') {
+    return { action: 'react', args: { ...env, action: 'removed' } };
+  }
+  if (action === 'read') {
+    return { action: 'query', args: { line: env.line, limit: env.limit } };
+  }
+  return { action, args: env };
+}

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

@@ -0,0 +1,58 @@
+import { TrainError } from '../train-error.js';
+
+export const PROFILE_FIELDS = ['name', 'bio', 'avatar'] as const;
+export type ProfileField = (typeof PROFILE_FIELDS)[number];
+
+export const NAME_MAX = 64;
+export const BIO_MAX = 512;
+
+export interface ProfileAvatar {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ProfileChange {
+  name?: string;
+  bio?: string;
+  avatar?: ProfileAvatar;
+}
+
+export interface ProfileApplied {
+  account: string;
+  applied: ProfileField[];
+}
+
+const text = (value: unknown, field: string, max: number): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw new TrainError('bad_request', `${field} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed === '') throw new TrainError('bad_request', `${field} cannot be empty`);
+  if (trimmed.length > max) throw new TrainError('bad_request', `${field} is over ${String(max)} characters`);
+  return trimmed;
+};
+
+function avatarOf(value: unknown): ProfileAvatar | undefined {
+  if (value === undefined) return undefined;
+  const raw = (value ?? {}) as Record<string, unknown>;
+  if (typeof raw.path !== 'string' || raw.path === '') throw new TrainError('bad_request', 'avatar needs a local file');
+  return { path: raw.path, mime: typeof raw.mime === 'string' ? raw.mime : 'application/octet-stream', name: typeof raw.name === 'string' ? raw.name : 'avatar' };
+}
+
+export function parseProfileChange(args: Record<string, unknown>): ProfileChange {
+  const change: ProfileChange = {};
+  const name = text(args.name, 'name', NAME_MAX);
+  const bio = text(args.bio, 'bio', BIO_MAX);
+  const avatar = avatarOf(args.avatar);
+  if (name !== undefined) change.name = name;
+  if (bio !== undefined) change.bio = bio;
+  if (avatar !== undefined) change.avatar = avatar;
+  if (Object.keys(change).length === 0) throw new TrainError('bad_request', 'set_profile needs at least one of name, bio, avatar');
+  return change;
+}
+
+export const fieldsOf = (change: ProfileChange): ProfileField[] => PROFILE_FIELDS.filter((f) => change[f] !== undefined);
+
+export const assertImage = (avatar: ProfileAvatar): void => {
+  if (!avatar.mime.startsWith('image/')) throw new TrainError('bad_request', `avatar must be an image, not ${avatar.mime}`);
+};

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

@@ -0,0 +1,64 @@
+import { serializeTrainError, type TrainErrorInfo } from '../train-error.js';
+import type { Normalized } from './messaging-normalize.js';
+
+export const emit = (e: unknown): void =>
+  void process.stdout.write(JSON.stringify(e) + '\n');
+
+export const respond = (
+  id: string,
+  body: { result?: unknown; error?: string; errorInfo?: TrainErrorInfo },
+): void =>
+  void process.stdout.write(
+    JSON.stringify({ op: 'response', id, ...body }) + '\n',
+  );
+
+export const mintId = (): string =>
+  `msg_${Math.random().toString(36).slice(2, 10)}`;
+
+type Args = Record<string, unknown>;
+
+export interface CallMsg {
+  op: 'call';
+  id: string;
+  action: string;
+  args: Args;
+}
+
+export type StationHandler = (id: string, args: Args) => void | Promise<void>;
+
+export interface StationConfig {
+  handlers: Record<string, StationHandler>;
+  normalize: (action: string, args: Args) => Normalized;
+  preDispatch?: (id: string, action: string) => boolean;
+}
+
+const lineTag = (args: Args): string =>
+  typeof args.line === 'string' ? args.line : '?';
+
+export function makeStation({ handlers, normalize, preDispatch }: StationConfig) {
+  const known = Object.keys(handlers).join(', ');
+  return async function handleCall(msg: CallMsg): Promise<void> {
+    const { id } = msg;
+    let action = msg.action;
+    let args: Args = msg.args;
+    try {
+      ({ action, args } = normalize(msg.action, msg.args));
+      emit({ op: 'log', text: `call ${action} recv (line=${lineTag(args)})` });
+      if (preDispatch?.(id, action)) return;
+      const handler = handlers[action];
+      if (!handler) {
+        respond(id, { error: `unknown action '${action}' (have: ${known})` });
+        return;
+      }
+      await handler(id, args);
+      emit({ op: 'log', text: `call ${action} done (line=${lineTag(args)})` });
+    } catch (err) {
+      const info = serializeTrainError(err);
+      emit({
+        op: 'log',
+        text: `call ${action} FAILED (line=${lineTag(args)}): ${info.error}`,
+      });
+      respond(id, info);
+    }
+  };
+}

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

@@ -0,0 +1,112 @@
+import type { ProfileField } from './profile.js';
+
+export type Verb =
+  | 'send'
+  | 'reply'
+  | 'react'
+  | 'unreact'
+  | 'edit'
+  | 'delete'
+  | 'read';
+
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+  isError?: boolean;
+}
+
+export interface CanonicalAttachment {
+  path?: string;
+  url?: string;
+  data?: string;
+  upload?: string;
+  mime?: string;
+  name?: string;
+}
+
+export interface ToolContext {
+  call(
+    action: string,
+    args: Record<string, unknown>,
+  ): Promise<{ result: unknown }>;
+  ok(text: string): ToolResult;
+  okJson(value: unknown): ToolResult;
+  err(text: string): ToolResult;
+  readFile(path: string): Promise<Buffer>;
+}
+
+export interface StationTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handle(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+}
+
+export interface MetroMember {
+  id: string;
+  name?: string;
+  display_name?: string;
+  address?: string;
+  roles?: string[];
+  is_admin?: boolean;
+  is_bot?: boolean;
+}
+
+export interface MemberCapability {
+  supported: boolean;
+  complete: boolean;
+  reason?: string;
+  total?: number;
+}
+
+export interface MemberList {
+  members: MetroMember[];
+  capability: MemberCapability;
+}
+
+export type GroupOp =
+  | 'create_group'
+  | 'add_members'
+  | 'remove_members'
+  | 'invite_link';
+
+export type MemberOutcomeStatus = 'added' | 'invited' | 'removed' | 'failed';
+
+export interface MemberOutcome {
+  id: string;
+  status: MemberOutcomeStatus;
+  reason?: string;
+}
+
+export interface GroupCapability {
+  supported: boolean;
+  reason?: string;
+}
+
+export interface GroupResult {
+  capability: GroupCapability;
+  line?: string;
+  id?: string;
+  name?: string;
+  members?: MemberOutcome[];
+  inviteLink?: string;
+}
+
+export type AttachmentMode = 'canonical' | 'native' | 'none';
+
+export interface Station {
+  name: string;
+  hasAccounts: boolean;
+  hasTrain: boolean;
+  messageVerbs: ReadonlySet<Verb>;
+  groupOps?: ReadonlySet<GroupOp>;
+  resolvesSenders?: boolean;
+  profileFields?: ReadonlySet<ProfileField>;
+  claimsName?: boolean;
+  attachmentMode: AttachmentMode;
+  sendAttachments?(
+    line: string,
+    atts: CanonicalAttachment[],
+    ctx: ToolContext,
+  ): Promise<string[]>;
+  tools: StationTool[];
+}

package/runtime/node_modules/@metro-labs/core/src/str.ts

@@ -0,0 +1,5 @@
+export function str(v: unknown): string {
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  return '';
+}