Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.4 KB
Raw Blame
#!/usr/bin/env node
/**
 * portos-api — call this machine's PortOS API from an agent PortOS did not
 * spawn (a Claude Code or Codex session in a terminal), without the password.
 *
 *   node scripts/portos-api.js whoami
 *   node scripts/portos-api.js get /api/cos/tasks
 *   node scripts/portos-api.js post /api/image-gen/generate '{"prompt":"a lighthouse at dusk"}'
 *   node scripts/portos-api.js post /api/music-video/autonomous @brief.json
 *   echo '{"description":"…"}' | node scripts/portos-api.js post /api/cos/tasks -
 *   node scripts/portos-api.js task "Fix the flaky upload test" --app portos --priority HIGH
 *
 * Credentials, first match wins:
 *   1. `PORTOS_API_TOKEN` — what PortOS injects into the agents it spawns
 *   2. the agent API key file the server keeps when Settings > Security >
 *      Agent API key is on (`~/.portos/agent-key.json`, or
 *      `$PORTOS_AGENT_KEY_FILE`; see lib/agentKeyFile.js)
 * The base URL is `$PORTOS_URL`, else the key file's `url`, else
 * the configured local HTTP listener (the loopback mirror when TLS is usable).
 * A path without a leading `/api/` or `/data/` gets
 * `/api` prepended. The response body goes to stdout (JSON pretty-printed);
 * a non-2xx status exits 1 with the body on stderr.
 *
 * Builtins only, so it runs from any checkout without `npm install`.
 */

import { readFile, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { PORTS } from '../server/lib/ports.js';
import { resolveInstallRoot } from '../server/lib/dataRoot.js';
import { certPaths } from '../lib/certPaths.js';
import { hasTailscaleCert } from '../lib/tailscale-https.js';
import { parseEnvFile, resolveHttpMirrorPort } from './lib/envFile.js';
import { request as httpRequest } from 'node:http';
import { request as httpsRequest } from 'node:https';
import { resolveAgentKeyFile } from '../lib/agentKeyFile.js';
import { isDirectlyInvoked } from './lib/directInvocation.js';

const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');

const localConnection = (env) => {
  const root = resolveInstallRoot(ROOT);
  const { PORTOS_HTTP_PORT } = parseEnvFile(join(root, '.env'));
  const apiPort = PORTS.API;
  const mirrorPort = resolveHttpMirrorPort({ env, dotenv: { PORTOS_HTTP_PORT } });
  const tls = hasTailscaleCert(certPaths(join(root, 'data')).dir);
  return { apiPort, mirrorPort, tls, url: `http://127.0.0.1:${tls ? mirrorPort : apiPort}` };
};
export const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete']);
const PRIORITIES = new Set(['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']);

export const USAGE = `Usage:
  portos-api whoami [--timeout <seconds>]
  portos-api <get|post|put|patch|delete> <path> [json | @file | -] [--timeout <seconds>]
  portos-api fableloom-export <preflight|start|status|watch|download> <loom-id> [job-id] [--episodes id1,id2] [--player true|false] [--characters true|false] [--voice true|false] [--allow-draft true|false] [--profile source|web-720p|web-1080p] [--webm true|false] [--output file.zip] [--timeout seconds]
  portos-api task "<description>" [--app <id>] [--priority LOW|MEDIUM|HIGH|CRITICAL] [--context "<note>"] [--timeout <seconds>]

Requests wait up to 30 minutes by default, including the response body.
Discover endpoints: portos-api get /api/api-docs/catalog.json`;

/** `/cos/tasks` → `/api/cos/tasks`; `/api/...` and `/data/...` pass through. */
export const normalizePath = (path) => {
  const withSlash = path.startsWith('/') ? path : `/${path}`;
  return /^\/(api|data)(\/|$)/.test(withSlash) ? withSlash : `/api${withSlash}`;
};

/** Pull `--flag value` pairs out of argv; everything else stays positional. */
const splitFlags = (args) => {
  const flags = {};
  const positional = [];
  for (let i = 0; i < args.length; i += 1) {
    const arg = args[i];
    if (arg.startsWith('--')) {
      if (i + 1 >= args.length) throw new Error(`${arg} needs a value`);
      flags[arg.slice(2)] = args[i + 1];
      i += 1;
    } else {
      positional.push(arg);
    }
  }
  return { flags, positional };
};

/**
 * argv (after `node script`) → `{ method, path, body }`, where `body` is a JSON
 * string, `{ file }`, `{ stdin: true }`, or null. Throws on anything it cannot
 * read.
 */
export const parseArgs = (argv) => {
  const [command, ...args] = argv;
  if (!command || command === '--help' || command === '-h' || command === 'help') return { help: true };
  const { flags, positional: rest } = splitFlags(args);
  const timeout = {};
  if (flags.timeout !== undefined) {
    const seconds = Number(flags.timeout);
    if (!Number.isFinite(seconds) || seconds <= 0 || seconds * 1000 > 2 ** 31 - 1) throw new Error('--timeout must be positive seconds within the timer limit');
    timeout.timeoutMs = seconds * 1000;
  }
  if (command === 'fableloom-export') {
    const [action, loomId, jobId] = rest;
    if (!['preflight', 'start', 'status', 'watch', 'download'].includes(action) || !loomId) throw new Error('fableloom-export needs an action and loom ID');
    const allowed = new Set(['timeout', 'episodes', 'player', 'characters', 'voice', 'allow-draft', 'profile', 'webm', 'output']);
    if (Object.keys(flags).some(key => !allowed.has(key))) throw new Error('Unknown fableloom-export flag');
    const options = {};
    for (const [flag, key] of Object.entries({ player: 'includePlayer', characters: 'includeCharacters', voice: 'includeVoice', 'allow-draft': 'allowDraft', webm: 'includeWebm' })) {
      if (flags[flag] === undefined) continue;
      if (!['true', 'false'].includes(flags[flag])) throw new Error(`--${flag} must be true or false`);
      options[key] = flags[flag] === 'true';
    }
    if (options.includeVoice && !options.includeCharacters) throw new Error('--voice true needs --characters true');
    if (flags.episodes !== undefined) options.episodeIds = flags.episodes.split(',');
    if (flags.profile !== undefined) {
      if (!['source', 'web-720p', 'web-1080p'].includes(flags.profile)) throw new Error('--profile must be source, web-720p or web-1080p');
      options.mediaProfile = flags.profile;
    }
    const starts = ['preflight', 'start'].includes(action);
    if (rest.length !== (starts ? 2 : 3)) throw new Error('Unexpected fableloom-export arguments');
    if (flags.output && action !== 'download') throw new Error('--output must be used with download');
    if (!starts && !jobId) throw new Error(`${action} needs a job ID`);
    if (action === 'download' && !flags.output) throw new Error('download needs --output file.zip');
    if (!starts && Object.keys(options).length) throw new Error('Export options must be supplied to preflight or start');
    const path = `/api/fableloom/${encodeURIComponent(loomId)}/export`;
    return { method: starts ? 'POST' : 'GET', path: starts ? `${path}${action === 'preflight' ? '/preflight' : ''}`
      : `${path}/${encodeURIComponent(jobId)}${action === 'download' ? '/download' : ''}`,
      body: starts ? JSON.stringify(options) : null, ...(action === 'download' ? { output: flags.output } : {}),
      ...(action === 'watch' ? { watch: true } : {}), ...timeout };
  }
  if (command === 'whoami') return { method: 'GET', path: '/api/auth/whoami', body: null, ...timeout };
  if (command === 'task') {
    const description = rest.join(' ').trim();
    if (!description) throw new Error('task needs a description');
    const task = { description };
    if (flags.app) task.app = flags.app;
    if (flags.context) task.context = flags.context;
    if (flags.priority) {
      const priority = flags.priority.toUpperCase();
      if (!PRIORITIES.has(priority)) throw new Error(`--priority must be one of ${[...PRIORITIES].join(', ')}`);
      task.priority = priority;
    }
    return { method: 'POST', path: '/api/cos/tasks', body: JSON.stringify(task), ...timeout };
  }
  if (!METHODS.has(command.toLowerCase())) throw new Error(`Unknown command: ${command}`);
  const [path, payload] = rest;
  if (!path) throw new Error(`${command} needs a path`);
  let body = null;
  if (payload === '-') body = { stdin: true };
  else if (payload?.startsWith('@')) body = { file: payload.slice(1) };
  else if (payload !== undefined) body = payload;
  return { method: command.toUpperCase(), path: normalizePath(path), body, ...timeout };
};

/** `{ url, token }` from the environment and the key file (see header). */
export const resolveCredentials = async (env = process.env) => {
  const keyFile = await readFile(resolveAgentKeyFile(env), 'utf8')
    .then((raw) => JSON.parse(raw))
    .catch(() => null);
  const url = (env.PORTOS_URL || keyFile?.url || localConnection(env).url).replace(/\/+$/, '');
  const token = env.PORTOS_API_TOKEN || (typeof keyFile?.token === 'string' ? keyFile.token : null);
  return { url, token };
};

const readStdin = async () => {
  const chunks = [];
  for await (const chunk of process.stdin) chunks.push(chunk);
  return Buffer.concat(chunks).toString('utf8');
};

const resolveBody = async (body) => {
  if (body === null) return null;
  const text = typeof body === 'string' ? body
    : body.stdin ? await readStdin()
      : await readFile(body.file, 'utf8');
  JSON.parse(text); // fail here with a clear message, not as a 400 from the server
  return text;
};

// Builtin HTTP has no hidden five-minute headers limit. One deadline covers
// connection, headers and body, and destroying the request also closes its socket.
export const requestApi = (url, { method, headers, body, timeoutMs }) => {
  const target = new URL(url);
  if (!['http:', 'https:'].includes(target.protocol)) throw new Error('PORTOS_URL must use HTTP or HTTPS');
  let timer;
  return new Promise((resolve, reject) => {
    const request = (target.protocol === 'https:' ? httpsRequest : httpRequest)(target, { method, headers }, (response) => {
      const chunks = [];
      response.on('data', (chunk) => chunks.push(chunk));
      response.on('error', reject);
      response.on('end', () => resolve({ status: response.statusCode, text: Buffer.concat(chunks).toString('utf8'), bytes: Buffer.concat(chunks) }));
    });
    request.on('error', reject);
    timer = setTimeout(() => request.destroy(new Error(`Request timed out after ${timeoutMs / 1000} seconds; server work may still be running.`)), timeoutMs);
    request.end(body);
  }).finally(() => clearTimeout(timer));
};

export const main = async (argv = process.argv.slice(2), env = process.env) => {
  const parsed = parseArgs(argv);
  if (parsed.help) {
    console.log(USAGE);
    return 0;
  }
  const { url, token } = await resolveCredentials(env);
  const body = await resolveBody(parsed.body);
  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;
  if (parsed.path === '/api/cos/merge-admission/external' && env.PORTOS_ADMISSION_SESSION) {
    if (!/^[a-f0-9]{64}$/.test(env.PORTOS_ADMISSION_SESSION)) throw new Error('PORTOS_ADMISSION_SESSION must be 32 random bytes encoded as lowercase hex');
    headers['X-PortOS-Admission-Session'] = env.PORTOS_ADMISSION_SESSION;
  }
  if (body !== null) headers['Content-Type'] = 'application/json';
  const deadline = Date.now() + (parsed.timeoutMs ?? DEFAULT_TIMEOUT_MS);
  let { status, text, bytes } = await requestApi(`${url}${parsed.path}`, { method: parsed.method, headers, body, timeoutMs: parsed.timeoutMs ?? DEFAULT_TIMEOUT_MS })
    .catch((error) => {
      const target = new URL(url);
      if (error.code === 'ECONNRESET' && target.protocol === 'http:'
        && ['127.0.0.1', 'localhost', '[::1]'].includes(target.hostname)) {
        const local = localConnection(env);
        if (local.tls && Number(target.port || 80) === local.apiPort) {
          throw new Error(`Connection reset: this local API port is configured for HTTPS. Use PORTOS_URL=http://127.0.0.1:${local.mirrorPort} for its HTTP mirror.`, { cause: error });
        }
      }
      throw error;
    });
  if (parsed.watch) {
    while (status >= 200 && status < 300) {
      const job = JSON.parse(text);
      console.log(JSON.stringify(job, null, 2));
      if (['completed', 'failed', 'cancelled'].includes(job.status)) return job.status === 'completed' ? 0 : 1;
      const remaining = deadline - Date.now();
      if (remaining <= 0) throw new Error('Export watch timed out; job may still be running.');
      await new Promise(resolve => setTimeout(resolve, Math.min(1000, remaining)));
      const left = deadline - Date.now();
      if (left <= 0) throw new Error('Export watch timed out; job may still be running.');
      ({ status, text } = await requestApi(`${url}${parsed.path}`, { method: 'GET', headers, body: null, timeoutMs: left }));
    }
  }
  if (parsed.output && status >= 200 && status < 300) {
    await writeFile(parsed.output, bytes, { flag: 'wx', mode: 0o600 });
    console.log(`Saved ZIP to ${parsed.output}`);
    return 0;
  }
  let out = text;
  try { out = JSON.stringify(JSON.parse(text), null, 2); } catch { /* not JSON: print as-is */ }
  if (status >= 200 && status < 300) {
    if (out) console.log(out);
    return 0;
  }
  console.error(`❌ ${parsed.method} ${parsed.path} → ${status}`);
  if (out) console.error(out);
  if (status === 401 && !token) {
    console.error('No credential found. Turn on Settings > Security > Agent API key in PortOS, or set PORTOS_API_TOKEN.');
  }
  return 1;
};

if (isDirectlyInvoked(import.meta.url)) {
  main()
    .then((code) => { process.exitCode = code; })
    .catch((err) => {
      console.error(`❌ ${err.message}`);
      if (/needs|Unknown command|must be/.test(err.message)) console.error(USAGE);
      process.exitCode = 1;
    });
}