feega 0.1.29 → 0.1.31

package/README.md

@@ -6,9 +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.
 
-Run it inside a project with a `dev` script and it asks once to import the folder: its home page lands on the canvas as an editable frame. `--import` imports without asking, `--no-import` never asks.
+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.
 
-Options: `--port <n>`, `--no-open`, `--import`, `--no-import`. `FEEGA_APP_BUNDLE=<path or url>` uses another bundle.
+`--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

@@ -8,7 +8,7 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 
 import { sendTelemetry, telemetryEnv } from '../telemetry.mjs';
-import { ImportStep, MCP_ENTRY, USAGE, appDir, bundleSource, boundUrl, cachedVersions, folderApp, freePort, importAsk, importStep, isCached, latestAppVersion, markCached, mcpEnv, parseArgs, pickVersion, placeOf, readyProbe, served } 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;
@@ -17,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]);
@@ -54,6 +56,7 @@ async function chooseVersion(home) {
 }
 
 async function install(dir, version) {
+  console.log(eventLine({ event: 'step', step: 'download' }));
   console.error(`feega: downloading the app ${version} (once per version)…`);
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
@@ -64,6 +67,7 @@ async function install(dir, version) {
     throw new Error('could not extract the app bundle');
   }
 
+  console.log(eventLine({ event: 'step', step: 'install' }));
   console.error('feega: installing its dependencies for this machine…');
   const deps = spawnSync('npm', ['ci', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'], {
     cwd: dir,
@@ -100,6 +104,10 @@ async function readyApp() {
 
 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.NoApp) {
+    throw new Error(`nothing to import: ${process.cwd()} has no package.json with a "dev" script`);
+  }
+
   if (step !== ImportStep.Ask) {
     return step === ImportStep.Import;
   }
@@ -110,23 +118,68 @@ async function wantsImport(app, file, mode) {
   return answer === '' || answer.startsWith('y');
 }
 
-async function importFolder(url, folder) {
+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: importing ${basename(folder)} (starts its dev server, can take a minute)…`);
-  const { path, body } = importAsk(place, folder);
-  const res = await fetch(new URL(path, url), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  console.log(eventLine({ event: 'step', step: 'find', state: 'active' }));
+  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(eventLine({ event: 'step', step: 'find', state: 'done', pages: plan.routes.length }));
+  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) {
-    const { error, detail } = await res.json().catch(() => ({}));
-    throw new Error(`folder import failed: ${detail ?? error ?? res.status}`);
+    throw new Error(`folder import failed: ${done.detail ?? done.error ?? res.status}`);
   }
 
-  const { pages = [] } = await res.json();
-  console.log(`feega: imported ${basename(folder)} (${pages.length} pages)`);
+  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) {
@@ -167,7 +220,7 @@ async function main() {
     return;
   }
 
-  const { file, browser, folderImport } = 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'));
@@ -180,6 +233,7 @@ async function main() {
   const port = await freePort(args.port);
 
   const url = boundUrl(port);
+  console.log(eventLine({ event: 'step', step: 'start' }));
   console.log(`feega: saving to ${file}`);
   console.log(`feega: open ${url}`);
 
@@ -194,7 +248,10 @@ async function main() {
   }
 
   if (importing) {
-    await importFolder(url, app).catch((error) => console.error(`feega: ${error.message}`));
+    await importFolder(url, app, { routes, app: chosenApp, file }).catch((error) => {
+      console.error(`feega: ${error.message}`);
+      console.log(eventLine({ event: 'import-failed', message: error.message }));
+    });
   }
 }
 

package/launcher.mjs

@@ -7,13 +7,14 @@ 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] [--import | --no-import] [--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' };
+export const ImportStep = { Ask: 'ask', Import: 'import', Skip: 'skip', NoApp: 'no-app' };
 
 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';
@@ -42,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) {
@@ -69,6 +85,8 @@ export function parseArgs(argv, cwd) {
   let port = DEFAULT_PORT;
   let browser = 'open';
   let folderImport = FolderImport.Ask;
+  let routes;
+  let app;
 
   while (rest.length) {
     const arg = rest.shift();
@@ -96,6 +114,18 @@ export function parseArgs(argv, cwd) {
       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}`);
     }
@@ -103,7 +133,7 @@ export function parseArgs(argv, cwd) {
     files.push(arg);
   }
 
-  return { command: 'run', file: resolve(cwd, files[0] ?? DEFAULT_FILE), port, browser, folderImport };
+  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);
@@ -188,7 +218,7 @@ const STEPS = {
 
 export function importStep({ mode, app, fileExists, tty }) {
   if (!app) {
-    return ImportStep.Skip;
+    return mode === FolderImport.Yes ? ImportStep.NoApp : ImportStep.Skip;
   }
 
   return STEPS[mode]({ fileExists, tty });
@@ -199,11 +229,53 @@ export function placeOf(location) {
   return found ? { projectId: found[1], canvasId: found[2] } : null;
 }
 
-export const importAsk = (place, folder) => ({
-  path: `/api/v1/projects/${place.projectId}/code-import`,
-  body: { canvasId: place.canvasId, folder, routes: [HOME_ROUTE], x: 0, y: 0 }
+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' };

package/package.json

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