feega 0.1.28 → 0.1.30

package/README.md

@@ -6,7 +6,11 @@ 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.
+Run it inside a project with a `dev` script and it asks once to import the folder: every static page of its router (up to 20) lands on the canvas as editable frames; dynamic pages are skipped and listed, and with no router found only the home page is imported. `--import` imports without asking, `--no-import` never asks.
+
+`--routes <list|all>` picks pages (`/,/about`, default `all`) and `--app <path>` picks the app in a monorepo; without it a terminal asks.
+
+Options: `--port <n>`, `--no-open`, `--import`, `--no-import`, `--routes`, `--app`. `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

@@ -2,12 +2,13 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 
 import { sendTelemetry, telemetryEnv } from '../telemetry.mjs';
-import { MCP_ENTRY, USAGE, appDir, bundleSource, boundUrl, cachedVersions, freePort, isCached, latestAppVersion, markCached, mcpEnv, parseArgs, pickVersion } from '../launcher.mjs';
+import { ImportStep, MCP_ENTRY, USAGE, appDir, bundleSource, boundUrl, cachedVersions, folderApp, freePort, importAsk, discoverAsk, importReport, routePlan, eventLine, importStep, isCached, latestAppVersion, markCached, mcpEnv, parseArgs, pickVersion, placeOf, readyProbe, served } from '../launcher.mjs';
 
 const MIN_NODE_MAJOR = 22;
 const WEBSTORAGE_NODE_MAJOR = 25;
@@ -16,6 +17,8 @@ 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 HTTP_CONFLICT = 409;
+const CHOOSE_APP_TIMEOUT_MS = 120_000;
 const TO_STDERR = ['ignore', 2, 2];
 
 const nodeMajor = Number(process.versions.node.split('.')[0]);
@@ -76,11 +79,13 @@ async function install(dir, version) {
   markCached(dir);
 }
 
-async function openWhenReady(url) {
-  while (!(await fetch(url).then((r) => r.ok, () => false))) {
+async function whenReady(url) {
+  while (!(await fetch(url, readyProbe).then((r) => served(r.status), () => false))) {
     await new Promise((r) => setTimeout(r, READY_POLL_MS));
   }
+}
 
+function openBrowser(url) {
   const [cmd, ...args] = OPENERS[process.platform] ?? ['xdg-open'];
   spawn(cmd, [...args, url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
 }
@@ -95,6 +100,80 @@ async function readyApp() {
   return dir;
 }
 
+async function wantsImport(app, file, mode) {
+  const step = importStep({ mode, app, fileExists: existsSync(file), tty: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+  if (step !== ImportStep.Ask) {
+    return step === ImportStep.Import;
+  }
+
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await prompt.question(`feega: import the current folder (${basename(app)}) into the canvas? (Y/n) `)).trim().toLowerCase();
+  prompt.close();
+  return answer === '' || answer.startsWith('y');
+}
+
+async function fetchJson(url, path, init) {
+  const res = await fetch(new URL(path, url), init);
+  return { res, body: await res.json().catch(() => ({})) };
+}
+
+async function pickApp(apps) {
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (interactive) {
+    apps.forEach((app, i) => console.log(`  ${i + 1}) ${app}`));
+  } else {
+    console.log(eventLine({ event: 'choose-app', apps }));
+  }
+
+  const question = interactive ? input.question('feega: which app to import? (number) ') : new Promise((done) => input.once('line', done));
+  const closed = new Promise((done) => input.once('close', () => done('')));
+  const timeout = new Promise((done) => setTimeout(() => done(''), CHOOSE_APP_TIMEOUT_MS).unref());
+  const answer = String(await Promise.race([question, closed, timeout])).trim();
+  input.close();
+  return apps.find((app, i) => answer === app || answer === String(i + 1));
+}
+
+async function discover(url, place, folder, app) {
+  const { res, body } = await fetchJson(url, discoverAsk(place, folder, app));
+  if (res.status === HTTP_CONFLICT && body.apps?.length && !app) {
+    const chosen = await pickApp(body.apps);
+    if (!chosen) {
+      throw new Error(`this folder holds several apps (${body.apps.join(', ')}): pass --app <path>`);
+    }
+
+    return discover(url, place, folder, chosen);
+  }
+
+  return { found: res.ok ? { ok: true, ...body } : { ok: false }, app: app ?? body.app };
+}
+
+async function importFolder(url, folder, { routes, app, file }) {
+  const home = await fetch(url, readyProbe);
+  const place = placeOf(home.headers.get('location'));
+  if (!place) {
+    throw new Error('could not find the local canvas');
+  }
+
+  console.log(`feega: looking for the pages of ${basename(folder)}…`);
+  const discovered = await discover(url, place, folder, app);
+  const plan = routePlan(discovered.found, routes);
+  if (plan.fallback) {
+    console.log('feega: no router found, importing the home page only');
+  }
+
+  console.log(`feega: importing ${basename(folder)}: ${plan.routes.length} pages (starts its dev server, can take a minute)…`);
+  const { path, body } = importAsk(place, folder, { routes: plan.routes, app: discovered.app });
+  const { res, body: done } = await fetchJson(url, path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  if (!res.ok) {
+    throw new Error(`folder import failed: ${done.detail ?? done.error ?? res.status}`);
+  }
+
+  const report = importReport(plan, done);
+  report.lines.forEach((line) => console.log(line));
+  console.log(eventLine({ event: 'imported', pages: report.imported.length, needsValue: report.needsValue, leftOut: report.leftOut.length, file }));
+}
+
 function forward(child) {
   for (const signal of ['SIGINT', 'SIGTERM']) {
     process.on(signal, () => child.kill(signal));
@@ -133,7 +212,9 @@ async function main() {
     return;
   }
 
-  const { file, browser } = args;
+  const { file, browser, folderImport, routes, app: chosenApp } = args;
+  const app = folderApp(process.cwd());
+  const importing = await wantsImport(app, file, folderImport);
   const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
   void sendTelemetry({
     home: homedir(),
@@ -152,8 +233,13 @@ async function main() {
   const server = spawn(process.execPath, [realpathSync(join(dir, 'scripts/local.mjs')), file, `--port=${port}`], { stdio: 'inherit', env });
   forward(server);
 
+  await whenReady(url);
   if (browser === 'open') {
-    await openWhenReady(url);
+    openBrowser(url);
+  }
+
+  if (importing) {
+    await importFolder(url, app, { routes, app: chosenApp, file }).catch((error) => console.error(`feega: ${error.message}`));
   }
 }
 

package/launcher.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { join, resolve } from 'node:path';
 
@@ -7,8 +7,16 @@ 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]
+export const USAGE = `usage: feega [file.feega] [--port <n>] [--no-open] [--import | --no-import] [--routes <list|all>] [--app <path>] [--help] [--version]
        feega mcp [--port <n>]   MCP server (stdio) for the local feega on that port (default ${MCP_PORT})`;
+export const FolderImport = { Ask: 'ask', Yes: 'yes', No: 'no' };
+export const ImportStep = { Ask: 'ask', Import: 'import', Skip: 'skip' };
+
+const IMPORT_FLAGS = { '--import': FolderImport.Yes, '--no-import': FolderImport.No };
+const HOME_ROUTE = '/';
+const ALL_ROUTES = 'all';
+const PLACE = /\/p\/([^/]+)\/c\/([^/?#]+)/;
+
 const CACHED_MARKER = '.complete';
 const APP_TAG = 'app-v';
 const RELEASES = 'https://github.com/andreabuttarelli/feega/releases/download';
@@ -35,6 +43,21 @@ const portFlag = (arg, rest) => {
   return null;
 };
 
+const valueFlag = (name, arg, rest) => {
+  if (arg === name) {
+    const value = rest.shift();
+    if (!value || value.startsWith('-')) {
+      throw new Error(`${name} needs a value\n${USAGE}`);
+    }
+
+    return value;
+  }
+
+  return arg.startsWith(`${name}=`) ? arg.slice(name.length + 1) : null;
+};
+
+const routesOf = (raw) => (raw === ALL_ROUTES ? ALL_ROUTES : raw.split(/[\s,]+/).filter(Boolean));
+
 function parseMcp(rest) {
   let port = MCP_PORT;
   while (rest.length) {
@@ -61,6 +84,9 @@ export function parseArgs(argv, cwd) {
   const files = [];
   let port = DEFAULT_PORT;
   let browser = 'open';
+  let folderImport = FolderImport.Ask;
+  let routes;
+  let app;
 
   while (rest.length) {
     const arg = rest.shift();
@@ -77,12 +103,29 @@ export function parseArgs(argv, cwd) {
       continue;
     }
 
+    if (IMPORT_FLAGS[arg]) {
+      folderImport = IMPORT_FLAGS[arg];
+      continue;
+    }
+
     const flagged = portFlag(arg, rest);
     if (flagged !== null) {
       port = flagged;
       continue;
     }
 
+    const routesRaw = valueFlag('--routes', arg, rest);
+    if (routesRaw !== null) {
+      routes = routesOf(routesRaw);
+      continue;
+    }
+
+    const appRaw = valueFlag('--app', arg, rest);
+    if (appRaw !== null) {
+      app = appRaw;
+      continue;
+    }
+
     if (arg.startsWith('-')) {
       throw new Error(`unknown option: ${arg}\n${USAGE}`);
     }
@@ -90,7 +133,7 @@ export function parseArgs(argv, cwd) {
     files.push(arg);
   }
 
-  return { command: 'run', file: resolve(cwd, files[0] ?? DEFAULT_FILE), port, browser };
+  return { command: 'run', file: resolve(cwd, files[0] ?? DEFAULT_FILE), port, browser, folderImport, routes, app };
 }
 
 export const appDir = (home, version) => join(home, '.feega', 'app', version);
@@ -153,3 +196,88 @@ export const freePort = (port) =>
       probe.close(() => done(bound));
     });
   });
+
+export function folderApp(dir) {
+  const manifest = join(dir, 'package.json');
+  if (!existsSync(manifest)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(manifest, 'utf8')).scripts?.dev ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+const STEPS = {
+  [FolderImport.No]: () => ImportStep.Skip,
+  [FolderImport.Yes]: () => ImportStep.Import,
+  [FolderImport.Ask]: ({ fileExists, tty }) => (!fileExists && tty ? ImportStep.Ask : ImportStep.Skip)
+};
+
+export function importStep({ mode, app, fileExists, tty }) {
+  if (!app) {
+    return ImportStep.Skip;
+  }
+
+  return STEPS[mode]({ fileExists, tty });
+}
+
+export function placeOf(location) {
+  const found = PLACE.exec(location ?? '');
+  return found ? { projectId: found[1], canvasId: found[2] } : null;
+}
+
+const CODE_IMPORT = (projectId) => `/api/v1/projects/${projectId}/code-import`;
+
+export const importAsk = (place, folder, { routes, app }) => ({
+  path: CODE_IMPORT(place.projectId),
+  body: { canvasId: place.canvasId, folder, routes, ...(app ? { app } : {}), x: 0, y: 0 }
+});
+
+export const discoverAsk = (place, folder, app) => `${CODE_IMPORT(place.projectId)}/routes?${new URLSearchParams({ folder, ...(app ? { app } : {}) })}`;
+
+const NEEDS_VALUE = 'needs a value';
+const DID_NOT_OPEN = 'did not open';
+const NOT_OPENED = 'not_opened';
+
+export function routePlan(found, spec) {
+  if (Array.isArray(spec)) {
+    return { routes: spec, leftOut: [], fallback: false };
+  }
+
+  if (!found.ok) {
+    return { routes: [HOME_ROUTE], leftOut: [], fallback: true };
+  }
+
+  const wanted = found.routes.filter((route) => route.selected);
+  const dynamic = found.routes.filter((route) => !route.selected).map(({ path }) => ({ path, reason: NEEDS_VALUE }));
+  const over = wanted.slice(found.max).map(({ path }) => ({ path, reason: `over the ${found.max}-page limit` }));
+  return { routes: wanted.slice(0, found.max).map(({ path }) => path), leftOut: [...dynamic, ...over], fallback: false };
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+export function importReport(plan, done) {
+  const imported = done.pages ?? [];
+  const known = new Set(plan.leftOut.map(({ path }) => path));
+  const failed = (done.routes?.leftOut ?? []).filter((o) => o.reason === NOT_OPENED && !known.has(o.path)).map(({ path }) => ({ path, reason: DID_NOT_OPEN }));
+  const leftOut = [...plan.leftOut, ...failed];
+  const lines = [`feega: imported ${plural(imported.length, 'page')}: ${imported.join(', ')}`];
+  if (leftOut.length) {
+    lines.push(`feega: left out ${leftOut.length}: ${leftOut.map((o) => `${o.path} (${o.reason})`).join(', ')}`);
+  }
+
+  return { imported, leftOut, needsValue: leftOut.filter((o) => o.reason === NEEDS_VALUE).length, lines };
+}
+
+export const EVENT_PREFIX = 'feega:event ';
+
+export const eventLine = (event) => `${EVENT_PREFIX}${JSON.stringify(event)}`;
+
+const HTTP_ERROR_MIN = 400;
+
+export const readyProbe = { redirect: 'manual' };
+
+export const served = (status) => status < HTTP_ERROR_MIN;

package/package.json

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