@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.130

package/runtime/node_modules/@metro-labs/daemon/src/claude/setup.ts

@@ -0,0 +1,239 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+import { agentsDir } from '../agents/files.js';
+import { claudeDir } from './files.js';
+import { stagedMarketplaceDir } from './plugin-install.js';
+import { readModelConfig, type ModelConfig } from '../gateway/model-config.js';
+
+export const PRIVACY_ENV: Record<string, string> = {
+  DISABLE_TELEMETRY: '1',
+  DISABLE_ERROR_REPORTING: '1',
+  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+  CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF: '1',
+};
+export const RETENTION_DAYS = 7;
+export const SKILL_NAME = 'metro-orchestrator';
+const STATE_FILE = 'claude-setup.json';
+const GUIDANCE = 'orchestrator.md';
+
+export const WORKER_AGENT = `---
+name: worker
+description: Default execution agent for delegated work. Full tool access and maximum reasoning effort. Use for any substantive task the orchestrator main thread cannot perform itself - reading and writing code, running commands, research, analysis.
+effort: xhigh
+---
+
+You are a worker agent. The main thread that dispatched you is an orchestrator with no file, shell or network access; it can only delegate and relay messages. That means you are where the actual work happens, and the quality of your output is the quality of the result.
+
+Work to completion. Do not hand back a partial answer with a suggestion that someone else finish it; there is no one else. If part of the task is genuinely blocked, complete every other part in full and say plainly what you left undone and why.
+
+Never call AskUserQuestion or ExitPlanMode. They are blocked by policy, because nobody is watching the terminal around the clock and a blocking prompt stalls indefinitely. When you hit an ambiguity: do everything that does not depend on it, then choose the most reasonable interpretation, state the assumption explicitly in your report, and continue.
+
+Your final message is a report to the orchestrator, not a message to a human. It gets relayed onward, so make it self-contained and concise. Lead with the outcome. Include concrete evidence, command output, file paths with line numbers, test results, for anything you claim to have verified. Report failures faithfully: if a test failed, say so and show the output; if you skipped a step, say that too.
+`;
+
+export interface SetupDeps {
+  dir?: string;
+  agents?: string;
+  guidance?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export type Placed = 'written' | 'present' | 'missing';
+export type SettingsOutcome = 'written' | 'unchanged' | 'unreadable';
+
+export interface SetupReport {
+  privacy: boolean;
+  guard: 'plugin';
+  worker: Placed;
+  skill: Placed;
+  settings: SettingsOutcome;
+}
+
+export interface SetupStatus {
+  privacy: boolean;
+  permissionMode: PermissionMode;
+  guard: 'plugin';
+  worker: boolean;
+  skill: boolean;
+  privacyApplied: boolean;
+  retentionDays: number | null;
+}
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+export const PERMISSION_MODES = ['auto', 'bypass'] as const;
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+
+function readState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+function writeState(agents: string, patch: Record<string, unknown>): void {
+  mkdirSync(agents, { recursive: true });
+  writeJson(statePath(agents), { ...readState(agents), ...patch });
+}
+
+export const privacyEnabled = (agents = agentsDir()): boolean => readState(agents).privacy !== false;
+
+export function setPrivacy(enabled: boolean, agents = agentsDir()): void {
+  writeState(agents, { privacy: enabled });
+}
+
+export const isPermissionMode = (value: unknown): value is PermissionMode => PERMISSION_MODES.some((m) => m === value);
+
+export function permissionMode(agents = agentsDir()): PermissionMode {
+  const mode = readState(agents).permissionMode;
+  return isPermissionMode(mode) ? mode : 'auto';
+}
+
+export function setPermissionMode(mode: PermissionMode, agents = agentsDir()): void {
+  writeState(agents, { permissionMode: mode });
+}
+
+export function guidancePath(env: NodeJS.ProcessEnv = process.env): string {
+  const staged = stagedMarketplaceDir(env);
+  if (staged !== null) {
+    const path = join(staged, 'plugin', GUIDANCE);
+    if (existsSync(path)) return path;
+  }
+  return fileURLToPath(new URL(`../../../../plugin/${GUIDANCE}`, import.meta.url));
+}
+
+function ensureFile(path: string, text: string): Placed {
+  if (existsSync(path)) return 'present';
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text, { mode: 0o644 });
+  return 'written';
+}
+
+function readSettings(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function withPrivacy(settings: Record<string, unknown>, enabled: boolean): Record<string, unknown> {
+  const current = isRecord(settings.env) ? settings.env : {};
+  if (enabled)
+    return { ...settings, env: { ...current, ...PRIVACY_ENV }, cleanupPeriodDays: settings.cleanupPeriodDays ?? RETENTION_DAYS };
+  const env = Object.fromEntries(Object.entries(current).filter(([key]) => !(key in PRIVACY_ENV)));
+  const rest = Object.fromEntries(Object.entries(settings).filter(([key]) => key !== 'env'));
+  return Object.keys(env).length === 0 ? rest : { ...rest, env };
+}
+
+export function applyPrivacy(dir: string, enabled: boolean): SettingsOutcome {
+  const path = join(dir, 'settings.json');
+  const current = readSettings(path);
+  if (current === null) return 'unreadable';
+  const next = withPrivacy(current, enabled);
+  if (existsSync(path) && JSON.stringify(next) === JSON.stringify(current)) return 'unchanged';
+  const text = `${JSON.stringify(next, null, 2)}\n`;
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o644 });
+  renameSync(tmp, path);
+  return 'written';
+}
+
+const skillPath = (dir: string): string => join(dir, 'skills', SKILL_NAME, 'SKILL.md');
+const workerPath = (dir: string): string => join(dir, 'agents', 'worker.md');
+
+function placeSkill(dir: string, guidance: string): Placed {
+  if (!existsSync(guidance)) return 'missing';
+  return ensureFile(skillPath(dir), readFileSync(guidance, 'utf8'));
+}
+
+export function ensureClaudeSetup(deps: SetupDeps = {}): SetupReport {
+  const dir = deps.dir ?? claudeDir();
+  const agents = deps.agents ?? agentsDir();
+  const privacy = privacyEnabled(agents);
+  const report: SetupReport = {
+    privacy,
+    guard: 'plugin',
+    worker: ensureFile(workerPath(dir), WORKER_AGENT),
+    skill: placeSkill(dir, deps.guidance ?? guidancePath(deps.env)),
+    settings: applyPrivacy(dir, privacy),
+  };
+  syncAvailableModelsQuietly({ ...deps, dir, agents });
+  if (report.worker === 'written' || report.skill === 'written' || report.settings === 'written')
+    log.info(report, 'claude-setup: applied the Claude Code setup for a metro box');
+  if (report.settings === 'unreadable') log.warn({ path: join(dir, 'settings.json') }, 'claude-setup: settings.json is not valid JSON, so the privacy settings were not written');
+  return report;
+}
+
+export function claudeSetupStatus(deps: SetupDeps = {}): SetupStatus {
+  const dir = deps.dir ?? claudeDir();
+  const settings = readSettings(join(dir, 'settings.json'));
+  const env = settings !== null && isRecord(settings.env) ? settings.env : {};
+  const days = settings?.cleanupPeriodDays;
+  return {
+    privacy: privacyEnabled(deps.agents ?? agentsDir()),
+    permissionMode: permissionMode(deps.agents ?? agentsDir()),
+    guard: 'plugin',
+    worker: existsSync(workerPath(dir)),
+    skill: existsSync(skillPath(dir)),
+    privacyApplied: Object.keys(PRIVACY_ENV).every((key) => env[key] === '1'),
+    retentionDays: typeof days === 'number' ? days : null,
+  };
+}
+
+export function tryClaudeSetup(deps: SetupDeps = {}): void {
+  try {
+    ensureClaudeSetup(deps);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-setup: could not apply the Claude Code setup');
+  }
+}
+
+const MODELS_KEY = 'availableModels';
+const ENFORCE_KEY = 'enforceAvailableModels';
+
+export function routeOf(cfg: ModelConfig): string | null {
+  if (cfg.provider === 'anthropic') return null;
+  const model = cfg[cfg.provider].model;
+  return model === '' ? null : `${cfg.provider}:${model}`;
+}
+
+function withAvailableModels(settings: Record<string, unknown>, route: string | null, metroWrote: boolean): Record<string, unknown> {
+  if (route !== null) return { ...settings, [MODELS_KEY]: [route], [ENFORCE_KEY]: true };
+  if (!metroWrote) return settings;
+  return Object.fromEntries(Object.entries(settings).filter(([key]) => key !== MODELS_KEY && key !== ENFORCE_KEY));
+}
+
+export function syncAvailableModels(cfg: ModelConfig, deps: SetupDeps = {}): SettingsOutcome {
+  const dir = deps.dir ?? claudeDir();
+  const agents = deps.agents ?? agentsDir();
+  const route = routeOf(cfg);
+  const state = readJson<unknown>(statePath(agents), null);
+  const metroWrote = isRecord(state) && state.modelsByMetro === true;
+  const path = join(dir, 'settings.json');
+  const current = readSettings(path);
+  if (current === null) return 'unreadable';
+  const next = withAvailableModels(current, route, metroWrote);
+  mkdirSync(agents, { recursive: true });
+  writeJson(statePath(agents), { ...(isRecord(state) ? state : {}), modelsByMetro: route !== null });
+  if (existsSync(path) && JSON.stringify(next) === JSON.stringify(current)) return 'unchanged';
+  const text = `${JSON.stringify(next, null, 2)}\n`;
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o644 });
+  renameSync(tmp, path);
+  return 'written';
+}
+
+export function syncAvailableModelsQuietly(deps: SetupDeps = {}, cfg?: ModelConfig): void {
+  try {
+    syncAvailableModels(cfg ?? readModelConfig(deps.agents ?? agentsDir()), deps);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-setup: could not sync the model allowlist');
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/skills.ts

@@ -0,0 +1,154 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { claudeDir, listClaudeProjects } from './files.js';
+
+export const SKILL_MAX = 256 * 1024;
+export const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const USER_SCOPE = 'user';
+const FILE = 'SKILL.md';
+const DEFAULT_MODE = 0o644;
+const SUMMARY_MAX = 300;
+
+export type SkillScope = 'user' | 'project';
+
+export interface ClaudeSkill {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  scope: SkillScope;
+  where: string;
+  path: string;
+  editable: boolean;
+  updatedAt: string | null;
+}
+
+const frontmatterField = (text: string, field: string): string => {
+  const head = text.startsWith('---') ? text.slice(3, text.indexOf('\n---', 3)) : '';
+  for (const line of head.split('\n')) {
+    const at = line.indexOf(':');
+    if (at > 0 && line.slice(0, at).trim() === field) return line.slice(at + 1).trim().replace(/^["']|["']$/g, '').slice(0, SUMMARY_MAX);
+  }
+  return '';
+};
+
+function entryOf(id: string, name: string, scope: SkillScope, where: string, path: string): ClaudeSkill {
+  const stat = statSync(path);
+  const editable = stat.size <= SKILL_MAX;
+  const text = editable ? readFileSync(path, 'utf8') : '';
+  return {
+    id,
+    name,
+    title: frontmatterField(text, 'name') || name,
+    description: frontmatterField(text, 'description'),
+    scope,
+    where,
+    path,
+    editable,
+    updatedAt: stat.mtime.toISOString(),
+  };
+}
+
+function skillsIn(root: string, prefix: string, scope: SkillScope, where: string): ClaudeSkill[] {
+  if (!existsSync(root)) return [];
+  const out: ClaudeSkill[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !SKILL_NAME_RE.test(entry.name)) continue;
+    const path = join(root, entry.name, FILE);
+    if (existsSync(path)) out.push(entryOf(`${prefix}:${entry.name}`, entry.name, scope, where, path));
+  }
+  return out;
+}
+
+export const userSkillsRoot = (dir: string): string => join(dir, 'skills');
+
+export interface SkillHome {
+  prefix: string;
+  scope: SkillScope;
+  where: string;
+  root: string;
+}
+
+export function skillHomes(dir = claudeDir()): SkillHome[] {
+  const homes: SkillHome[] = [{ prefix: USER_SCOPE, scope: USER_SCOPE, where: 'This machine', root: userSkillsRoot(dir) }];
+  for (const project of listClaudeProjects(dir)) {
+    const cwd = project.cwd;
+    if (cwd === null || !existsSync(cwd)) continue;
+    homes.push({ prefix: project.id, scope: 'project', where: cwd, root: join(cwd, '.claude', 'skills') });
+  }
+  return homes;
+}
+
+export function listClaudeSkills(dir = claudeDir()): ClaudeSkill[] {
+  const out = skillHomes(dir).flatMap((home) => skillsIn(home.root, home.prefix, home.scope, home.where));
+  return out.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? '') || a.name.localeCompare(b.name));
+}
+
+function found(id: string, dir: string): ClaudeSkill {
+  const skill = listClaudeSkills(dir).find((entry) => entry.id === id);
+  if (skill === undefined) throw new ApiError('no such skill', 404);
+  return skill;
+}
+
+export function readClaudeSkill(id: string, dir = claudeDir()): ClaudeSkill & { text: string } {
+  const skill = found(id, dir);
+  return { ...skill, text: skill.editable ? readFileSync(skill.path, 'utf8') : '' };
+}
+
+function writeAtomic(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}`;
+  writeFileSync(tmp, text, { mode: DEFAULT_MODE });
+  renameSync(tmp, path);
+}
+
+function assertText(text: string): void {
+  if (text.length > SKILL_MAX) throw new ApiError('that is more text than a skill may hold', 413);
+  if (text.trim() === '') throw new ApiError('a skill needs some text', 400);
+}
+
+export function writeClaudeSkill(
+  id: string,
+  text: string,
+  seenAt: string | null | undefined,
+  dir = claudeDir(),
+): ClaudeSkill {
+  const skill = found(id, dir);
+  if (!skill.editable) throw new ApiError('that skill is too large to edit here', 409);
+  assertText(text);
+  if (seenAt !== undefined && seenAt !== skill.updatedAt)
+    throw new ApiError('that skill changed on disk since you opened it; reload it before saving', 409);
+  writeAtomic(skill.path, text);
+  return entryOf(skill.id, skill.name, skill.scope, skill.where, skill.path);
+}
+
+export const skillTemplate = (name: string): string =>
+  ['---', `name: ${name}`, 'description: what this skill does, and when Claude should reach for it', '---', '', `# ${name}`, '', 'Write the instructions here.', ''].join('\n');
+
+export function createClaudeSkill(
+  name: string,
+  scope: string | undefined,
+  text: string | undefined,
+  dir = claudeDir(),
+): ClaudeSkill {
+  if (typeof name !== 'string' || !SKILL_NAME_RE.test(name))
+    throw new ApiError('a skill name is lowercase letters, digits and dashes, up to 64 characters', 400);
+  const prefix = scope === undefined || scope === '' ? USER_SCOPE : scope;
+  const home = skillHomes(dir).find((h) => h.prefix === prefix);
+  if (home === undefined) throw new ApiError('no such place to keep a skill', 404);
+  const path = join(home.root, name, FILE);
+  if (existsSync(path)) throw new ApiError('a skill by that name already lives there', 409);
+  const body = text === undefined || text.trim() === '' ? skillTemplate(name) : text;
+  assertText(body);
+  writeAtomic(path, body);
+  return entryOf(`${home.prefix}:${name}`, name, home.scope, home.where, path);
+}
+
+export function deleteClaudeSkill(id: string, dir = claudeDir()): string {
+  const skill = found(id, dir);
+  const folder = dirname(skill.path);
+  if (basename(folder) !== skill.name) throw new ApiError('that skill does not live in its own folder', 409);
+  rmSync(folder, { recursive: true, force: true });
+  return id;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/version.ts

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { sessionRunning, stopSession, type SessionDeps } from './session.js';
+
+const LATEST_URL = 'https://registry.npmjs.org/@anthropic-ai/claude-code/latest';
+const VERSION_RE = /(\d+)\.(\d+)\.(\d+)/;
+const CACHE_MS = 10 * 60_000;
+const INSTALL_TIMEOUT_MS = 5 * 60_000;
+const TAIL = 400;
+
+export interface VersionDeps {
+  claude?: string;
+  fetchImpl?: typeof fetch;
+  session?: SessionDeps;
+  now?: () => number;
+}
+
+export interface ClaudeVersion {
+  installed: string | null;
+  latest: string | null;
+  newer: boolean;
+}
+
+let cached: { latest: string | null; at: number } | null = null;
+
+const candidates = (deps: VersionDeps): string[] => (deps.claude === undefined ? ['claude', join(homedir(), '.local', 'bin', 'claude')] : [deps.claude]);
+
+const parse = (text: string): string | null => {
+  const m = VERSION_RE.exec(text);
+  return m === null ? null : `${m[1] ?? ''}.${m[2] ?? ''}.${m[3] ?? ''}`;
+};
+
+function probe(bin: string): string | null {
+  const run = spawnSync(bin, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return run.error === undefined && run.status === 0 && typeof run.stdout === 'string' ? parse(run.stdout) : null;
+}
+
+function located(deps: VersionDeps): { bin: string; installed: string } | null {
+  for (const bin of candidates(deps)) {
+    const installed = probe(bin);
+    if (installed !== null) return { bin, installed };
+  }
+  return null;
+}
+
+export function newerThan(a: string, b: string): boolean {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (left[i] ?? 0) - (right[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+export async function latestClaudeVersion(deps: VersionDeps = {}): Promise<string | null> {
+  const now = (deps.now ?? Date.now)();
+  if (cached !== null && now - cached.at < CACHE_MS) return cached.latest;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  let latest: string | null = null;
+  try {
+    const res = await fetchImpl(LATEST_URL, { headers: { accept: 'application/json' }, redirect: 'manual' });
+    const body: unknown = res.ok ? await res.json() : null;
+    latest = isRecord(body) && typeof body.version === 'string' ? parse(body.version) : null;
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-version: could not read the latest version from npm');
+  }
+  cached = { latest, at: now };
+  return latest;
+}
+
+export function forgetClaudeVersion(): void {
+  cached = null;
+}
+
+export async function claudeVersion(deps: VersionDeps = {}): Promise<ClaudeVersion> {
+  const installed = located(deps)?.installed ?? null;
+  const latest = await latestClaudeVersion(deps);
+  return { installed, latest, newer: installed !== null && latest !== null && newerThan(latest, installed) };
+}
+
+function install(bin: string): void {
+  const run = spawnSync(bin, ['install', 'latest'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: INSTALL_TIMEOUT_MS });
+  if (run.error !== undefined) throw new ApiError(`claude install latest failed: ${errMsg(run.error)}`, 502);
+  if (run.status === 0) return;
+  const said = `${run.stderr ?? ''}${run.stdout ?? ''}`.trim().slice(-TAIL);
+  throw new ApiError(`claude install latest failed: ${said}`, 502);
+}
+
+function restartIfChanged(changed: boolean, session: SessionDeps): boolean {
+  if (!changed || !sessionRunning(session.tmux ?? 'tmux')) return false;
+  stopSession(session);
+  return true;
+}
+
+export async function updateClaude(deps: VersionDeps = {}): Promise<ClaudeVersion & { restarted: boolean }> {
+  const found = located(deps);
+  if (found === null) throw new ApiError('Claude Code is not installed on this machine', 404);
+  install(found.bin);
+  forgetClaudeVersion();
+  const after = await claudeVersion(deps);
+  const restarted = restartIfChanged(after.installed !== null && after.installed !== found.installed, deps.session ?? {});
+  log.info({ from: found.installed, to: after.installed, restarted }, 'claude-version: Claude Code updated');
+  return { ...after, restarted };
+}