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

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/log.ts

@@ -0,0 +1,42 @@
+import { writeSync } from 'node:fs';
+import pino from 'pino';
+import pinoPretty from 'pino-pretty';
+
+const stream = process.stderr.isTTY
+  ? pinoPretty({
+      colorize: true,
+      translateTime: 'HH:MM:ss',
+      ignore: 'pid,hostname,name',
+      destination: 2,
+    })
+  : pino.destination(2);
+
+export const log = pino(
+  { base: { name: 'metro' }, level: process.env.METRO_LOG_LEVEL ?? 'info' },
+  stream,
+);
+
+export const logFatalSync = (
+  fields: Record<string, unknown>,
+  msg: string,
+): void => {
+  const line = JSON.stringify({
+    level: 60,
+    time: Date.now(),
+    name: 'metro',
+    ...fields,
+    msg,
+  });
+  try {
+    writeSync(2, `${line}\n`);
+  } catch {
+    return;
+  }
+};
+
+export const errMsg = (err: unknown): string => {
+  if (err instanceof Error) return err.message;
+  if (err && typeof err === 'object' && 'message' in err)
+    return String(err.message);
+  return String(err);
+};

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/protocol.ts

@@ -0,0 +1,227 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, parse as parsePath } from 'node:path';
+import { errMsg, log } from './log.js';
+import { coerceErrorInfo, type TrainErrorInfo } from './train-error.js';
+import type { StructuredEvent } from './events.js';
+import type { CallMsg } from './stations/station-runtime.js';
+
+export {
+  TrainError,
+  serializeTrainError,
+  type TrainErrorInfo,
+} from './train-error.js';
+
+const CALL_TIMEOUT_MS = 60_000;
+
+export interface Pending {
+  resolve: (r: TrainCallResponse) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+export interface CallTarget {
+  name: string;
+  pending: Map<string, Pending>;
+  proc: ({ stdin?: unknown } & Record<string, unknown>) | null;
+}
+
+const STDOUT_LINE_MAX = 4 * 1024 * 1024;
+
+export type TrainEvent = {
+  station?: string;
+  line?: string;
+  line_name?: string;
+  from?: string;
+  from_name?: string;
+  from_display_name?: string;
+  to?: string;
+  message_id?: string;
+  reply_to?: string;
+  is_private?: boolean;
+  mentions_self?: boolean;
+  reply_to_self?: boolean;
+  sender_verified?: boolean;
+  text?: string;
+  emoji?: string;
+  payload?: unknown;
+  ts?: string;
+  id?: string;
+  event?: StructuredEvent;
+} & Record<string, unknown>;
+
+export interface TrainCallResponse {
+  result?: unknown;
+  error?: string;
+  errorInfo?: TrainErrorInfo;
+}
+
+export type TrainMessage =
+  | {
+      op: 'response';
+      id: string;
+      result?: unknown;
+      error?: string;
+      errorInfo?: TrainErrorInfo;
+    }
+  | { op: 'log'; text?: string }
+  | { op: 'event'; event: TrainEvent }
+  | { op: 'ignore' };
+
+export function parseTrainLine(
+  name: string,
+  line: string,
+): TrainMessage | null {
+  let msg: {
+    op?: string;
+    id?: string;
+    result?: unknown;
+    error?: string;
+    errorInfo?: unknown;
+    text?: string;
+  } & Record<string, unknown>;
+  try {
+    msg = JSON.parse(line) as typeof msg;
+  } catch (err) {
+    log.warn(
+      { name, err: errMsg(err), line: line.slice(0, 200) },
+      'train: bad JSON',
+    );
+    return null;
+  }
+  if (msg.op === 'response') {
+    if (typeof msg.id !== 'string') return { op: 'ignore' };
+    return {
+      op: 'response',
+      id: msg.id,
+      result: msg.result,
+      error: msg.error,
+      errorInfo: coerceErrorInfo(msg.errorInfo),
+    };
+  }
+  if (msg.op === 'log') return { op: 'log', text: msg.text };
+  if (typeof msg.line !== 'string') {
+    log.warn(
+      { name, line: line.slice(0, 200) },
+      'train: event missing `line` (string) — dropped',
+    );
+    return { op: 'ignore' };
+  }
+  return { op: 'event', event: msg };
+}
+
+export function drainLines(
+  name: string,
+  buf: string,
+  onLine: (line: string) => void,
+): string {
+  if (buf.length > STDOUT_LINE_MAX && !buf.includes('\n')) {
+    log.warn(
+      { name, bytes: buf.length },
+      'train: dropping oversized stdout line',
+    );
+    return '';
+  }
+  let nl;
+  while ((nl = buf.indexOf('\n')) !== -1) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    onLine(line);
+  }
+  return buf;
+}
+
+export function readCalls(
+  name: string,
+  handleCall: (msg: CallMsg) => Promise<void>,
+): void {
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk: Buffer | string) => {
+    buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    buf = drainLines(name, buf, (line) => {
+      try {
+        const msg = JSON.parse(line) as Partial<CallMsg>;
+        if (msg.op === 'call')
+          handleCall(msg as CallMsg).catch((e: unknown) => {
+            process.stderr.write(`call failed: ${errMsg(e)}\n`);
+          });
+      } catch (err: unknown) {
+        process.stderr.write(`bad stdin line: ${errMsg(err)}\n`);
+      }
+    });
+  });
+}
+
+function encodeCall(id: string, action: string, args: unknown): string {
+  return JSON.stringify({ op: 'call', id, action, args }) + '\n';
+}
+
+function isTrainFile(name: string): boolean {
+  return (
+    /\.(ts|js|mjs)$/.test(name) &&
+    !name.startsWith('_') &&
+    !name.startsWith('.')
+  );
+}
+
+export function listTrainFiles(dir: string): { name: string; path: string }[] {
+  return readdirSync(dir)
+    .filter(isTrainFile)
+    .map((f) => ({ name: parsePath(f).name, path: join(dir, f) }))
+    .filter((t) => {
+      try {
+        return statSync(t.path).isFile();
+      } catch {
+        return false;
+      }
+    });
+}
+
+export function mintCallId(seq: number): string {
+  return `req_${seq}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function failAllPending(
+  pending: Map<string, Pending>,
+  reason: string,
+): void {
+  for (const p of pending.values()) {
+    clearTimeout(p.timer);
+    p.reject(new Error(reason));
+  }
+  pending.clear();
+}
+
+export function sendCall(
+  t: CallTarget,
+  id: string,
+  action: string,
+  args: unknown,
+): Promise<TrainCallResponse> {
+  return new Promise<TrainCallResponse>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      t.pending.delete(id);
+      reject(
+        new Error(
+          `train '${t.name}' call '${action}' timed out after ${CALL_TIMEOUT_MS}ms`,
+        ),
+      );
+    }, CALL_TIMEOUT_MS);
+    t.pending.set(id, { resolve, reject, timer });
+    try {
+      const stdin = (
+        t.proc as {
+          stdin?: { write: (s: string) => void; flush: () => void };
+        } | null
+      )?.stdin;
+      if (!stdin || typeof stdin === 'number')
+        throw new Error('stdin not piped');
+      stdin.write(encodeCall(id, action, args));
+      stdin.flush();
+    } catch (err) {
+      clearTimeout(timer);
+      t.pending.delete(id);
+      reject(new Error(`train '${t.name}' stdin write failed: ${errMsg(err)}`));
+    }
+  });
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/runner-activity.ts

@@ -0,0 +1,270 @@
+import { isRecord } from './is-record.js';
+
+const PHASES = ['starting', 'idle', 'working', 'approval', 'compacting', 'stopped', 'error'] as const;
+const TASK_STATES = ['pending', 'running', 'completed', 'failed', 'stopped', 'paused', 'unknown'] as const;
+const EVENTS = ['turn_started', 'turn_finished', 'turn_failed', 'tool_started', 'tool_finished', 'tool_failed', 'task_started', 'task_completed', 'task_failed', 'task_stopped', 'task_updated', 'compacting', 'compacted', 'compact_failed', 'api_retry', 'approval_waiting', 'approval_ended', 'permission_denied', 'session_failed'] as const;
+export type RunnerPhase = (typeof PHASES)[number];
+export type RunnerTaskState = (typeof TASK_STATES)[number];
+export type RunnerEventKind = (typeof EVENTS)[number];
+
+const FAILURE = {
+  authentication: 'The provider refused authentication. Check the Model page.',
+  billing: 'The provider refused billing. Check the Model page.',
+  rate_limit: 'The provider rate limit was reached. Retry later or check the Model page.',
+  provider_unavailable: 'The provider is unavailable. Retry later or check the Model page.',
+  invalid_request: 'The provider rejected the request. Check Conversations and the Model page.',
+  output_limit: 'The model reached its output token limit. Check Conversations.',
+  provider_error: 'SDK turn failed (provider_error). Check Conversations and the Model page.',
+  error_during_execution: 'SDK turn failed (error_during_execution). Check Conversations and the Model page.',
+  error_max_turns: 'SDK turn failed (error_max_turns). Check Conversations and the Model page.',
+  error_max_budget_usd: 'SDK turn failed (error_max_budget_usd). Check Conversations and the Model page.',
+  error_max_structured_output_retries: 'SDK turn failed (error_max_structured_output_retries). Check Conversations and the Model page.',
+  read_token_limit: 'Read exceeded its token limit. Read a smaller range with offset and limit, or search the file.',
+  tool_error: 'A tool failed. See its result in Conversations.',
+  task_error: 'A background task failed. See Conversations and Terminal.',
+  compact_error: 'Conversation compaction failed.',
+  status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
+  saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
+  executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  module: 'The SDK runtime could not load a required module. Prepare the SDK runtime again.',
+  configuration: 'The SDK launch configuration is missing or invalid. Check Harness and the Model page before starting.',
+  process_exit: 'The SDK process exited unexpectedly. Check its reported exit code or signal before retrying.',
+  connection: 'The SDK connection failed. Check the server and provider connection.',
+  session_ended: 'The Agent SDK session ended unexpectedly.',
+  interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
+  session_error: 'The Agent SDK session failed. Check Terminal and the Model page.',
+} as const;
+export type RunnerFailureCode = keyof typeof FAILURE;
+
+const ERROR_CODES = ['ENOENT', 'EACCES', 'EPERM', 'ENOEXEC', 'ENOMEM', 'ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ERR_DLOPEN_FAILED', 'ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'] as const;
+const SIGNALS = ['SIGTERM', 'SIGKILL', 'SIGSEGV', 'SIGABRT', 'SIGBUS', 'SIGILL', 'SIGINT', 'SIGHUP', 'SIGPIPE'] as const;
+
+const ERROR_NAME_RE = /^[A-Z][A-Za-z0-9]{0,39}Error$/;
+
+export interface RunnerDiagnostic {
+  source: 'exception' | 'stderr';
+  errorName?: string;
+  errorCode?: (typeof ERROR_CODES)[number];
+  httpStatus?: number;
+  exitCode?: number;
+  signal?: (typeof SIGNALS)[number];
+}
+
+const boundedNumber = (value: unknown, min: number, max: number): number | undefined => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max ? value : undefined;
+
+const errorNameOf = (value: unknown): string | undefined => typeof value === 'string' && value !== 'Error' && ERROR_NAME_RE.test(value) ? value : undefined;
+
+export function runnerDiagnostic(raw: unknown): RunnerDiagnostic | undefined {
+  if (!isRecord(raw) || (raw.source !== 'exception' && raw.source !== 'stderr')) return undefined;
+  const errorCode = ERROR_CODES.find((code) => code === raw.errorCode);
+  const signal = SIGNALS.find((value) => value === raw.signal);
+  const httpStatus = boundedNumber(raw.httpStatus, 400, 599);
+  const exitCode = boundedNumber(raw.exitCode, 0, 255);
+  const errorName = errorNameOf(raw.errorName);
+  return {
+    source: raw.source,
+    ...(errorName === undefined ? {} : { errorName }),
+    ...(errorCode === undefined ? {} : { errorCode }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(exitCode === undefined ? {} : { exitCode }),
+    ...(signal === undefined ? {} : { signal }),
+  };
+}
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null, diagnostic?: RunnerDiagnostic): string {
+  const summary = code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+  const safe = runnerDiagnostic(diagnostic);
+  if (safe === undefined) return summary;
+  const details = [safe.errorName, safe.errorCode, safe.httpStatus === undefined ? null : `HTTP ${safe.httpStatus}`, safe.exitCode === undefined ? null : `exit ${safe.exitCode}`, safe.signal].filter((value) => value !== undefined && value !== null);
+  return details.length === 0 ? summary : `${summary} Observed: ${details.join(', ')} (${safe.source === 'stderr' ? 'startup stderr' : 'exception'}).`;
+}
+
+export interface RunnerTask {
+  id: string;
+  kind: string | null;
+  agent: string | null;
+  description?: string | null;
+  lastObservedModel?: string | null;
+  status: RunnerTaskState;
+  background: boolean;
+  startedAt: number;
+  firstStartedAt?: number;
+  updatedAt: number;
+  endedAt: number | null;
+  lastTool: string | null;
+  toolUses: number;
+  durationMs: number;
+}
+
+export interface RunnerTool {
+  id: string;
+  name: string;
+  taskId: string | null;
+  worker?: boolean;
+  startedAt: number;
+}
+
+export interface RunnerEvent {
+  id?: string;
+  at: number;
+  kind: RunnerEventKind;
+  tool: string | null;
+  toolUseId?: string;
+  taskId: string | null;
+  code?: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
+}
+
+export interface RunnerFailure extends RunnerEvent {
+  id: string;
+  code: RunnerFailureCode;
+}
+
+export interface RunnerInput {
+  id: string;
+  kind: 'chat' | 'call' | 'note';
+  state: 'accepted' | 'consumed' | 'output' | 'completed' | 'cancelled';
+  acceptedAt: number;
+  dispatchedAt: number | null;
+  consumedAt: number | null;
+  firstOutputAt: number | null;
+  completedAt: number | null;
+}
+
+export interface RunnerActivity {
+  pid: number;
+  procStart?: string;
+  cancelSignal?: 'SIGUSR2';
+  runner: 'sdk';
+  phase: RunnerPhase;
+  mainPhase: RunnerPhase;
+  mainStartedAt: number | null;
+  sessionId: string | null;
+  updatedAt: number;
+  pending: number;
+  queueOldestAt?: number | null;
+  inputs?: RunnerInput[];
+  callState?: 'started' | 'ended' | 'accepted' | 'queued' | 'speaking' | 'completed' | 'interrupted' | 'failed';
+  workers: number;
+  approvals: number;
+  tools: string[];
+  activeTools: RunnerTool[];
+  tasks: RunnerTask[];
+  events: RunnerEvent[];
+  lastError: string | null;
+  activeFailure?: RunnerFailure | null;
+  lastFailure?: RunnerFailure | null;
+}
+
+const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+const phase = (value: unknown): value is RunnerPhase => PHASES.some((p) => p === value);
+const taskState = (value: unknown): value is RunnerTaskState => TASK_STATES.some((s) => s === value);
+const eventKind = (value: unknown): value is RunnerEventKind => EVENTS.some((e) => e === value);
+const name = (value: unknown): string | null => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value) ? value : null;
+const sessionId = (value: unknown): string | null => typeof value === 'string' && /^[0-9a-f-]{36}$/.test(value) ? value : null;
+
+export function runnerTaskDescription(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const line = value.split(/\r|\n|\p{Zl}|\p{Zp}/u, 1)[0] ?? '';
+  const description = line.replace(/[\p{Cc}\p{Cf}]/gu, ' ').replace(/\s+/g, ' ').trim().slice(0, 160).trim();
+  return description.length > 0 ? description : null;
+}
+
+export const runnerTaskModel = (value: unknown): string | null => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:/@+[\]-]{0,127}$/.test(value) ? value : null;
+
+function task(raw: unknown): RunnerTask | null {
+  if (!isRecord(raw) || !name(raw.id) || !taskState(raw.status)) return null;
+  return {
+    id: String(raw.id), kind: name(raw.kind), agent: name(raw.agent), status: raw.status, background: raw.background === true,
+    startedAt: count(raw.startedAt), updatedAt: count(raw.updatedAt), endedAt: count(raw.endedAt) || null,
+    lastTool: name(raw.lastTool), toolUses: count(raw.toolUses), durationMs: count(raw.durationMs),
+    ...(count(raw.firstStartedAt) > 0 ? { firstStartedAt: count(raw.firstStartedAt) } : {}),
+    ...(raw.description === undefined ? {} : { description: runnerTaskDescription(raw.description) }),
+    ...(raw.lastObservedModel === undefined ? {} : { lastObservedModel: runnerTaskModel(raw.lastObservedModel) }),
+  };
+}
+
+function tool(raw: unknown): RunnerTool | null {
+  if (!isRecord(raw) || !name(raw.id) || !name(raw.name)) return null;
+  return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
+}
+
+export const runnerFailureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
+
+function event(raw: unknown): RunnerEvent | null {
+  if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
+  return {
+    at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
+    ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
+    ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
+    ...(failureKind(raw.kind) && runnerFailureCode(raw.code) ? { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) } : {}),
+  };
+}
+
+function failure(raw: unknown): RunnerFailure | null {
+  const parsed = event(raw);
+  return parsed?.id !== undefined && parsed.code !== undefined ? { ...parsed, id: parsed.id, code: parsed.code } : null;
+}
+
+function safeError(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const known = Object.values(FAILURE).find((text) => text === raw);
+  if (known !== undefined) return known;
+  const tool = /^([A-Za-z0-9_.:-]{1,128}) failed\. See its result in Conversations\.$/.exec(raw)?.[1];
+  return tool === undefined ? FAILURE.session_error : runnerFailureSummary('tool_error', tool);
+}
+
+function list<T>(raw: unknown, parse: (item: unknown) => T | null, max: number): T[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(parse).filter((item): item is T => item !== null).slice(0, max);
+}
+
+function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
+  return typeof value === 'string' && /^\d{1,32}$/.test(value) ? { procStart: value } : {};
+}
+
+function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
+  const activeFailure = failure(raw.activeFailure);
+  return {
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool, activeFailure.diagnostic) : safeError(raw.lastError),
+    ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
+    ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
+  };
+}
+
+function input(raw: unknown): RunnerInput | null {
+  if (!isRecord(raw) || sessionId(raw.id) === null) return null;
+  const kind = (['chat', 'call', 'note'] as const).find((value) => value === raw.kind);
+  const state = (['accepted', 'consumed', 'output', 'completed', 'cancelled'] as const).find((value) => value === raw.state);
+  if (kind === undefined || state === undefined) return null;
+  return {
+    id: String(raw.id), kind, state, acceptedAt: count(raw.acceptedAt),
+    dispatchedAt: count(raw.dispatchedAt) || null, consumedAt: count(raw.consumedAt) || null,
+    firstOutputAt: count(raw.firstOutputAt) || null, completedAt: count(raw.completedAt) || null,
+  };
+}
+
+function inputFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'inputs' | 'queueOldestAt' | 'callState'> {
+  const states = ['started', 'ended', 'accepted', 'queued', 'speaking', 'completed', 'interrupted', 'failed'] as const;
+  const callState = states.find((state) => state === raw.callState);
+  return {
+    ...(raw.inputs === undefined ? {} : { inputs: list(raw.inputs, input, 40) }),
+    ...(raw.queueOldestAt === undefined ? {} : { queueOldestAt: count(raw.queueOldestAt) || null }),
+    ...(callState === undefined ? {} : { callState }),
+  };
+}
+
+export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
+  if (!isRecord(raw) || raw.runner !== 'sdk' || !phase(raw.phase) || count(raw.pid) === 0 || count(raw.updatedAt) === 0) return null;
+  return {
+    runner: 'sdk', pid: count(raw.pid), ...processIdentity(raw.procStart), phase: raw.phase, mainPhase: phase(raw.mainPhase) ? raw.mainPhase : raw.phase,
+    ...(raw.cancelSignal === 'SIGUSR2' ? { cancelSignal: raw.cancelSignal } : {}),
+    mainStartedAt: count(raw.mainStartedAt) || null, sessionId: sessionId(raw.sessionId), updatedAt: count(raw.updatedAt),
+    pending: count(raw.pending), workers: count(raw.workers), approvals: count(raw.approvals),
+    tools: list(raw.tools, name, 20), activeTools: list(raw.activeTools, tool, 20),
+    tasks: list(raw.tasks, task, 30), events: list(raw.events, event, 40),
+    ...failureFields(raw), ...inputFields(raw),
+  };
+}

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

@@ -0,0 +1,74 @@
+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);
+}
+
+function modeOf(path: string): number | null {
+  try {
+    return statSync(path).mode & 0o777;
+  } catch {
+    return null;
+  }
+}
+
+export function writeAtomic(path: string, data: string, mode?: number): void {
+  const chosen = mode ?? modeOf(path) ?? 0o644;
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}.tmp`;
+  writeFileSync(tmp, data, { mode: chosen });
+  chmodSync(tmp, chosen);
+  renameSync(tmp, path);
+}
+
+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));
+}