feega 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# feega
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+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.

package/bin/feega.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { createWriteStream, mkdirSync, 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';
+
+const MIN_NODE_MAJOR = 22;
+const WEBSTORAGE_NODE_MAJOR = 25;
+const READY_POLL_MS = 300;
+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 nodeMajor = Number(process.versions.node.split('.')[0]);
+
+async function download(source, target) {
+  if (!source.startsWith('http')) {
+    return source;
+  }
+
+  const res = await fetch(source);
+  if (!res.ok) {
+    throw new Error(`download failed (${res.status}): ${source}`);
+  }
+
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(target));
+  return target;
+}
+
+async function latestRelease() {
+  try {
+    const res = await fetch(RELEASES_API, { signal: AbortSignal.timeout(CHECK_TIMEOUT_MS), headers: { accept: 'application/vnd.github+json' } });
+    return res.ok ? latestAppVersion(await res.json()) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function chooseVersion(home) {
+  if (process.env.FEEGA_APP_BUNDLE) {
+    const cached = isCached(appDir(home, LOCAL_BUNDLE_VERSION)) ? [LOCAL_BUNDLE_VERSION] : [];
+    return pickVersion(LOCAL_BUNDLE_VERSION, cached);
+  }
+
+  return pickVersion(await latestRelease(), cachedVersions(home));
+}
+
+async function install(dir, version) {
+  console.log(`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' });
+  if (untar.status !== 0) {
+    throw new Error('could not extract the app bundle');
+  }
+
+  console.log('feega: installing its dependencies for this machine…');
+  const deps = spawnSync('npm', ['ci', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'], {
+    cwd: dir,
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+  if (deps.status !== 0) {
+    throw new Error('could not install the app dependencies');
+  }
+
+  markCached(dir);
+}
+
+async function openWhenReady(url) {
+  while (!(await fetch(url).then((r) => r.ok, () => false))) {
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+
+  const [cmd, ...args] = OPENERS[process.platform] ?? ['xdg-open'];
+  spawn(cmd, [...args, url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+}
+
+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 url = `http://localhost:${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));
+
+  if (browser === 'open') {
+    await openWhenReady(url);
+  }
+}
+
+main().catch((error) => {
+  console.error(`feega: ${error.message}`);
+  process.exit(1);
+});

package/launcher.mjs

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const DEFAULT_FILE = 'canvas.feega';
+const DEFAULT_PORT = 5173;
+const CACHED_MARKER = '.complete';
+const APP_TAG = 'app-v';
+const RELEASES = 'https://github.com/andreabuttarelli/feega/releases/download';
+export const BUNDLE_NAME = 'feega-app.tar.gz';
+
+const portOf = (raw) => {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error(`invalid --port: ${raw}`);
+  }
+
+  return port;
+};
+
+export function parseArgs(argv, cwd) {
+  const rest = [...argv];
+  const files = [];
+  let port = DEFAULT_PORT;
+  let browser = 'open';
+
+  while (rest.length) {
+    const arg = rest.shift();
+    if (arg === '--no-open') {
+      browser = 'skip';
+      continue;
+    }
+
+    if (arg === '--port') {
+      port = portOf(rest.shift());
+      continue;
+    }
+
+    if (arg.startsWith('--port=')) {
+      port = portOf(arg.slice('--port='.length));
+      continue;
+    }
+
+    files.push(arg);
+  }
+
+  return { file: resolve(cwd, files[0] ?? DEFAULT_FILE), port, browser };
+}
+
+export const appDir = (home, version) => join(home, '.feega', 'app', version);
+
+export const isCached = (dir) => existsSync(join(dir, CACHED_MARKER));
+
+export function markCached(dir) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, CACHED_MARKER), '');
+}
+
+export const bundleSource = (version, env) => env.FEEGA_APP_BUNDLE ?? `${RELEASES}/${APP_TAG}${version}/${BUNDLE_NAME}`;
+
+const semver = (v) => v.split('.').map(Number);
+
+const newestFirst = (a, b) => {
+  const [x, y] = [semver(a), semver(b)];
+  const diff = x.map((n, i) => y[i] - n).find((d) => d !== 0);
+  return diff ?? 0;
+};
+
+export function latestAppVersion(releases) {
+  const versions = releases
+    .filter((r) => !r.draft && !r.prerelease && r.tag_name.startsWith(APP_TAG))
+    .map((r) => r.tag_name.slice(APP_TAG.length));
+  return versions.sort(newestFirst)[0] ?? null;
+}
+
+export function cachedVersions(home) {
+  const root = join(home, '.feega', 'app');
+  if (!existsSync(root)) {
+    return [];
+  }
+
+  return readdirSync(root)
+    .filter((v) => /^\d+\.\d+\.\d+$/.test(v) && isCached(join(root, v)))
+    .sort(newestFirst);
+}
+
+export function pickVersion(latest, cached) {
+  if (latest) {
+    return { version: latest, action: cached.includes(latest) ? 'cache' : 'download' };
+  }
+
+  if (!cached.length) {
+    throw new Error('offline and no cached app: connect once to download it');
+  }
+
+  return { version: cached[0], action: 'cache' };
+}

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "feega",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "Run feega's infinite canvas locally, saved to a .feega file. No account, no database.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "feega": "bin/feega.mjs"
+  },
+  "files": [
+    "bin",
+    "launcher.mjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreabuttarelli/feega.git",
+    "directory": "npx"
+  },
+  "homepage": "https://feega.app"
+}