@finchip.ai/foga 0.6.1 → 0.6.2

package/dist/demo/anvil.js

@@ -62,6 +62,17 @@ export async function waitForRpc(rpc, timeoutMs, giveUp) {
     throw new Error(`RPC at ${rpc} did not come up within ${timeoutMs} ms`);
 }
 /** Why a port cannot be used for a new anvil: another RPC already answers there, or something else holds it. */
+/**
+ * The first port from `from` (inclusive) that nothing on 127.0.0.1 accepts connections on, trying `tries` ports in a
+ * row; null when all are taken. For the defaults a quickstart falls back on when its usual port is busy — the next
+ * one up rather than an ephemeral one, so the URL it prints is still one a person can remember.
+ */
+export async function nextFreePort(from, tries = 20) {
+    for (let p = from; p < from + tries; p++)
+        if (!(await portInUse(p)))
+            return p;
+    return null;
+}
 export async function portProblem(port) {
     if (!(await portInUse(port)))
         return null;

package/dist/demo/quickstart.js

@@ -12,7 +12,7 @@ import { defaultCatalog, OPERATOR_CALLER } from "../tools/index.js";
 import { ensureWallet, ensuredKey, walletDir } from "../node/wallet.js";
 import { repoRoot } from "../util/fs.js";
 import { deployWorld } from "../world/deploy.js";
-import { ANVIL_INSTALL_HINT, anvilBinary, anvilVersion, launchAnvil, portInUse, portProblem, stopChild } from "./anvil.js";
+import { ANVIL_INSTALL_HINT, anvilBinary, anvilVersion, launchAnvil, nextFreePort, portInUse, portProblem, stopChild } from "./anvil.js";
 import { birthCell } from "./birth.js";
 import { mintCases } from "./demander.js";
 import { cleanEnv, ownCli, waitForHttp } from "./loop-d.js";
@@ -49,29 +49,48 @@ export async function runQuickstart(o = {}) {
     const out = o.out ?? ((text) => console.log(text));
     const root = repoRoot();
     const dir = resolve(o.dir ?? defaultQuickstartDir());
-    const port = o.port ?? 8545;
-    const listen = o.listen === undefined ? "127.0.0.1:8787" : o.listen;
     const name = o.name ?? "quick";
-    const rpc = `http://127.0.0.1:${port}`;
     const walletPath = resolve(o.wallet ?? walletDir());
-    const nodeUrlPlanned = listen ? (() => {
-        const i = listen.lastIndexOf(":");
-        const host = listen.slice(0, i) || "127.0.0.1";
-        return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
-    })() : null;
     // --- say what is wrong before touching anything
     const anvilBin = anvilBinary();
     const version = anvilVersion(anvilBin.path);
     if (!version)
         throw new Error(ANVIL_INSTALL_HINT);
-    const problem = await portProblem(port);
-    if (problem)
-        throw new Error(problem);
+    // The default ports give way when something else holds them — a served cell on 8787 (the reference cell's own box,
+    // or a node of yours), another chain on 8545 — so the bare command works on any machine; the next free port up is
+    // taken and said so. A port asked for by name (--port, --listen) is not moved: that one is refused as before.
+    let port = o.port ?? 8545;
+    if (o.port === undefined && (await portInUse(port))) {
+        const next = await nextFreePort(port + 1);
+        if (next === null)
+            throw new Error(`ports ${port}-${port + 20} are all in use; pass --port <n> for the chain`);
+        log(`quickstart: port ${port} is in use (another chain or node); anvil takes ${next} instead`);
+        port = next;
+    }
+    else {
+        const problem = await portProblem(port);
+        if (problem)
+            throw new Error(problem);
+    }
+    let listen = o.listen === undefined ? "127.0.0.1:8787" : o.listen;
     if (listen) {
         const lp = Number(listen.slice(listen.lastIndexOf(":") + 1));
-        if (await portInUse(lp))
-            throw new Error(`port ${lp} is in use; pass --listen <host:port> for the node (or --no-serve to run no node)`);
+        if (await portInUse(lp)) {
+            if (o.listen !== undefined)
+                throw new Error(`port ${lp} is in use; pass --listen <host:port> for the node (or --no-serve to run no node)`);
+            const next = await nextFreePort(lp + 1);
+            if (next === null)
+                throw new Error(`ports ${lp}-${lp + 20} are all in use; pass --listen <host:port> for the node (or --no-serve)`);
+            log(`quickstart: port ${lp} is in use (a served cell, perhaps); the node listens on ${next} instead`);
+            listen = `127.0.0.1:${next}`;
+        }
     }
+    const rpc = `http://127.0.0.1:${port}`;
+    const nodeUrlPlanned = listen ? (() => {
+        const i = listen.lastIndexOf(":");
+        const host = listen.slice(0, i) || "127.0.0.1";
+        return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
+    })() : null;
     if (walletPath === dir || walletPath.startsWith(dir + sep))
         throw new Error(`the wallet (${walletPath}) must live outside the quickstart directory (${dir}), which is cleared on every run`);
     if (existsSync(dir)) {

package/docs/quickstart.md

@@ -8,6 +8,8 @@ npx -y @finchip.ai/foga quickstart
 
 `npx -y @finchtech.ai/foga quickstart` is the same command: `@finchtech.ai/foga` is an alias package (`alias/finchtech.ai`) whose only content is a launcher for `@finchip.ai/foga` at the same version.
 
+When its default ports are taken — 8787 by a served cell on the same machine (the reference cell's own box, a node of yours), 8545 by another chain — the quickstart takes the next free port up for each and says so; the URLs it prints are the ones it used. A port asked for by name (`--port`, `--listen`) is not moved: it is refused when busy, as before.
+
 Run it from any directory except a checkout of this repository itself: inside one, `npx` takes the checkout for the package already present (same name, same version) and looks for the `foga` command among its installed binaries, where a project's own binaries never are — `'foga' is not recognized` on Windows, `foga: not found` elsewhere. From a checkout the command is `node bin/foga.js quickstart` after `npm run build`.
 
 What it does, in order (about twenty-five seconds on a laptop): makes the default wallet — one key, the agent's identity, under `~/.foga/wallet` — when there is none, and reuses it when there is (docs/wallet.md: the wallet is the first step, and never a reason to stop; a disk that refuses the write gets keys made in memory for the run); starts `anvil` on port 8545; deploys the local world — the ten reference implementations and the FOGA contracts, 47 contracts (`worlds/local.json`); births a cell (`quick`) with the wallet's keys, funded by anvil's first account, which also registers the attested standing scheme and attests the cell's level-2 standing; mints the cell's two skills (`foga-probe`, `finch-extract-verify`) and offers them; builds the cell's documents and commits them on chain (the registration, the AID document, the ARD descriptor, the AUF unit; docs/documents.md); mints two tenders for the cell to find (a probe of the cell itself, an extraction over the fixture); serves the node — the watchers, the HTTP API, MCP over Streamable HTTP, A2A and the documents on `127.0.0.1:8787` — on the operator key alone, read from the wallet's file; checks that the entrances answer (health, a public read, the agent key's pre-check of the first tender, the MCP handshake and the 37-tool list over HTTP, the agent card naming `/a2a` and an A2A quote; the stdio server's handshake and its 44 tools with the operator key); and prints the summary below, with every path filled in. Then it waits: the chain lives as long as the process, and Ctrl-C ends both.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finchip.ai/foga",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/garyyang-finchip/foga.git"

package/server.json

@@ -8,13 +8,13 @@
     "source": "github"
   },
   "websiteUrl": "https://foga.finchip.ai",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@finchip.ai/foga",
-      "version": "0.6.1",
+      "version": "0.6.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"