feega 0.1.3 → 0.1.5

package/README.md

@@ -7,3 +7,5 @@ npx feega my-board.feega
 Starts feega's local mode on http://localhost:5173 and saves the canvas to `my-board.feega` in the current directory. Needs Node 22+. Each start checks for a newer app and downloads it into `~/.feega/app/<version>/`; offline it uses the newest cached one.
 
 Options: `--port <n>`, `--no-open`. `FEEGA_APP_BUNDLE=<path or url>` uses another bundle.
+
+AI keys: put them in the environment or in a `.env` in the folder you run `npx feega` from. Kie.ai, OpenRouter, the text LLM, Higgsfield, Wiro and ElevenLabs are supported; see the local mode docs for the variables.

package/bin/feega.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import { createWriteStream, mkdirSync, realpathSync, rmSync } from 'node:fs';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 
-import { appDir, bundleSource, cachedVersions, isCached, latestAppVersion, markCached, parseArgs, pickVersion } from '../launcher.mjs';
+import { MCP_ENTRY, USAGE, appDir, bundleSource, boundUrl, cachedVersions, freePort, isCached, latestAppVersion, markCached, mcpEnv, parseArgs, pickVersion } from '../launcher.mjs';
 
 const MIN_NODE_MAJOR = 22;
 const WEBSTORAGE_NODE_MAJOR = 25;
@@ -15,6 +15,7 @@ const OPENERS = { darwin: ['open'], win32: ['cmd', '/c', 'start', ''] };
 const RELEASES_API = 'https://api.github.com/repos/andreabuttarelli/feega/releases?per_page=50';
 const CHECK_TIMEOUT_MS = 2000;
 const LOCAL_BUNDLE_VERSION = 'local';
+const TO_STDERR = ['ignore', 2, 2];
 
 const nodeMajor = Number(process.versions.node.split('.')[0]);
 
@@ -51,20 +52,20 @@ async function chooseVersion(home) {
 }
 
 async function install(dir, version) {
-  console.log(`feega: downloading the app ${version} (once per version)…`);
+  console.error(`feega: downloading the app ${version} (once per version)…`);
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
 
   const archive = await download(bundleSource(version, process.env), join(tmpdir(), `feega-app-${version}-${process.pid}.tar.gz`));
-  const untar = spawnSync('tar', ['-xzf', archive, '-C', dir], { stdio: 'inherit' });
+  const untar = spawnSync('tar', ['-xzf', archive, '-C', dir], { stdio: TO_STDERR });
   if (untar.status !== 0) {
     throw new Error('could not extract the app bundle');
   }
 
-  console.log('feega: installing its dependencies for this machine…');
+  console.error('feega: installing its dependencies for this machine…');
   const deps = spawnSync('npm', ['ci', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'], {
     cwd: dir,
-    stdio: 'inherit',
+    stdio: TO_STDERR,
     shell: process.platform === 'win32'
   });
   if (deps.status !== 0) {
@@ -83,29 +84,65 @@ async function openWhenReady(url) {
   spawn(cmd, [...args, url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
 }
 
+async function readyApp() {
+  const { version, action } = await chooseVersion(homedir());
+  const dir = appDir(homedir(), version);
+  if (action === 'download') {
+    await install(dir, version);
+  }
+
+  return dir;
+}
+
+function forward(child) {
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+function serveMcp(dir, port) {
+  const entry = join(dir, MCP_ENTRY);
+  if (!existsSync(entry)) {
+    throw new Error('this app version has no MCP server: run `npx feega@latest mcp`');
+  }
+
+  forward(spawn(process.execPath, [entry], { stdio: 'inherit', env: mcpEnv(port, process.env) }));
+}
+
 async function main() {
   if (nodeMajor < MIN_NODE_MAJOR) {
     throw new Error(`Node ${MIN_NODE_MAJOR}+ is required (found ${process.versions.node})`);
   }
 
-  const { file, port, browser } = parseArgs(process.argv.slice(2), process.cwd());
-  const { version, action } = await chooseVersion(homedir());
-  const dir = appDir(homedir(), version);
-  if (action === 'download') {
-    await install(dir, version);
+  const args = parseArgs(process.argv.slice(2), process.cwd());
+  if (args.command === 'help') {
+    console.log(USAGE);
+    return;
   }
 
-  const url = `http://localhost:${port}`;
+  if (args.command === 'version') {
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+    return;
+  }
+
+  const dir = await readyApp();
+  if (args.command === 'mcp') {
+    serveMcp(dir, args.port);
+    return;
+  }
+
+  const { file, browser } = args;
+  const port = await freePort(args.port);
+
+  const url = boundUrl(port);
   console.log(`feega: saving to ${file}`);
   console.log(`feega: open ${url}`);
 
   const nodeOptions = nodeMajor >= WEBSTORAGE_NODE_MAJOR ? '--no-experimental-webstorage' : '';
   const env = { ...process.env, NODE_OPTIONS: [process.env.NODE_OPTIONS, nodeOptions].filter(Boolean).join(' ') };
   const server = spawn(process.execPath, [realpathSync(join(dir, 'scripts/local.mjs')), file, `--port=${port}`], { stdio: 'inherit', env });
-  for (const signal of ['SIGINT', 'SIGTERM']) {
-    process.on(signal, () => server.kill(signal));
-  }
-  server.on('exit', (code) => process.exit(code ?? 0));
+  forward(server);
 
   if (browser === 'open') {
     await openWhenReady(url);

package/launcher.mjs

@@ -1,8 +1,14 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
 import { join, resolve } from 'node:path';
 
 const DEFAULT_FILE = 'canvas.feega';
-const DEFAULT_PORT = 5173;
+const DEFAULT_PORT = 0;
+export const LOOPBACK = '127.0.0.1';
+export const MCP_PORT = 5173;
+export const MCP_ENTRY = 'mcp.mjs';
+export const USAGE = `usage: feega [file.feega] [--port <n>] [--no-open] [--help] [--version]
+       feega mcp [--port <n>]   MCP server (stdio) for the local feega on that port (default ${MCP_PORT})`;
 const CACHED_MARKER = '.complete';
 const APP_TAG = 'app-v';
 const RELEASES = 'https://github.com/andreabuttarelli/feega/releases/download';
@@ -17,33 +23,74 @@ const portOf = (raw) => {
   return port;
 };
 
+const portFlag = (arg, rest) => {
+  if (arg === '--port') {
+    return portOf(rest.shift());
+  }
+
+  if (arg.startsWith('--port=')) {
+    return portOf(arg.slice('--port='.length));
+  }
+
+  return null;
+};
+
+function parseMcp(rest) {
+  let port = MCP_PORT;
+  while (rest.length) {
+    const arg = rest.shift();
+    const flagged = portFlag(arg, rest);
+    if (flagged === null) {
+      throw new Error(`unknown option: ${arg}\n${USAGE}`);
+    }
+
+    port = flagged;
+  }
+
+  return { command: 'mcp', port };
+}
+
+export const mcpEnv = (port, env) => ({ ...env, PUBLIC_APP_URL: boundUrl(port) });
+
 export function parseArgs(argv, cwd) {
   const rest = [...argv];
+  if (rest[0] === 'mcp') {
+    return parseMcp(rest.slice(1));
+  }
+
   const files = [];
   let port = DEFAULT_PORT;
   let browser = 'open';
 
   while (rest.length) {
     const arg = rest.shift();
+    if (arg === '--help' || arg === '-h') {
+      return { command: 'help' };
+    }
+
+    if (arg === '--version') {
+      return { command: 'version' };
+    }
+
     if (arg === '--no-open') {
       browser = 'skip';
       continue;
     }
 
-    if (arg === '--port') {
-      port = portOf(rest.shift());
+    const flagged = portFlag(arg, rest);
+    if (flagged !== null) {
+      port = flagged;
       continue;
     }
 
-    if (arg.startsWith('--port=')) {
-      port = portOf(arg.slice('--port='.length));
-      continue;
+    if (arg.startsWith('-')) {
+      throw new Error(`unknown option: ${arg}\n${USAGE}`);
     }
 
     files.push(arg);
   }
 
-  return { file: resolve(cwd, files[0] ?? DEFAULT_FILE), port, browser };
+  return { command: 'run', file: resolve(cwd, files[0] ?? DEFAULT_FILE), port, browser };
 }
 
 export const appDir = (home, version) => join(home, '.feega', 'app', version);
@@ -94,3 +141,15 @@ export function pickVersion(latest, cached) {
 
   return { version: cached[0], action: 'cache' };
 }
+
+export const boundUrl = (port) => `http://${LOOPBACK}:${port}`;
+
+export const freePort = (port) =>
+  new Promise((done, fail) => {
+    const probe = createServer();
+    probe.once('error', fail);
+    probe.listen(port, LOOPBACK, () => {
+      const { port: bound } = probe.address();
+      probe.close(() => done(bound));
+    });
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feega",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Run feega's infinite canvas locally, saved to a .feega file. No account, no database.",
   "license": "Apache-2.0",
   "type": "module",