@instafy/cli 0.4.1 → 0.5.1

package/README.md

@@ -59,6 +59,8 @@ Run Instafy spaces locally and connect them back to Instafy Studio — from any
 - `instafy web read <url…> --json` — read up to 6 public pages over plain HTTP and get their text, links and structured data with provenance, wrapped as untrusted page content. robots.txt (including AI-agent user agents), the web-research skill's `no-agents` link-only sites (built in, plus the space's additions) and translators', caches' and archives' copies of them, private-address checks at every redirect, stop rules and per-turn caps are enforced; a `no-reuse` site is read and marked `noReuse`; see [docs/CLI.md](https://github.com/instafy-dev/instafy/blob/main/docs/CLI.md#reading-web-pages-instafy-web-read).
 - `instafy web search "<query>" --json` — find links to read, in Octo's turns only, with the space's own search key (the web-research skill's providers: Brave, then Kagi). Results are untrusted leads: a link-only site's result keeps only its link and site name, keys go only to their provider's host, nothing is cached, and the room keeps only the query and the count; see [docs/CLI.md](https://github.com/instafy-dev/instafy/blob/main/docs/CLI.md#searching-for-links-instafy-web-search).
 - `instafy web link <site> [name=value…] --json` — the link the person opens in their own tab for a `no-agents` site (guided mode): the site's search template from the web-research skill's list, filled with checked, URL-encoded values, or its home page and what to type there when it bars deep links. Reads nothing.
+- `instafy web budget --json` — inspect remaining fresh-page reads shared by the current task and its helpers. Cached pages are free.
+- `instafy web settings --interactive` — space managers configure total and per-site page allowances for new tasks; running tasks retain their original budget. Use `--max-page-loads` and `--max-page-loads-per-site` for scripts.
 - `instafy secrets list` — list space secret metadata (names/descriptions, never values).
 - `instafy secrets get <name-or-id>` — inspect one space secret metadata entry.
 - `instafy secrets put <name> --value ...` — create/update a space secret.

package/dist/bind/bin/instafy-bind.mjs

@@ -48,7 +48,8 @@ serve      Serve the site (or every subfolder with a bound.json) with the binder
            given). --agent-conversation <id> uses an existing conversation instead. --agent-budget caps Octo
            turns per site per hour (repairs included). --dry-run prints those prompts instead.
            --detach: start the binder in the background (its own session, output to --log, default
-           <tmp>/instafy-bind-<port>.log), wait until it answers, print where it serves and exit. A server
+           <tmp>/instafy-bind-<port>.log), wait until it answers as itself, print where it serves and exit. A
+           binder of this folder already serving on the port is kept; another server there is refused. A server
            started in an agent turn without it stops when the turn ends.
            In a folder of an Instafy space, the binder saves the data files it writes for clicks (records,
            data/version.json): it commits them to the space's checkout a few seconds after the last write, and
@@ -119,6 +120,15 @@ function detachedServeArgs(argv) {
   return out;
 }
 
+/** The folder's real path, or the path itself when it cannot be resolved. */
+function realOr(dir) {
+  try {
+    return fs.realpathSync(path.resolve(String(dir)));
+  } catch {
+    return path.resolve(String(dir));
+  }
+}
+
 async function serveDetached(dir, flags) {
   const port = flags.port === undefined ? 4180 : Number(flags.port);
   if (!Number.isInteger(port) || port < 1 || port > 65535) fail("--detach needs a fixed --port");
@@ -132,16 +142,39 @@ async function serveDetached(dir, flags) {
   fs.closeSync(fd);
   child.unref();
   const host = flags.host || "127.0.0.1";
+  const folder = realOr(dir);
+  // A gallery answers under each site's folder: ask the first one.
+  let prefix = "";
+  try {
+    prefix = discoverSites(dir, { plain: true })[0]?.prefix ?? "";
+  } catch {
+    // the binder says why in its log
+  }
+  const running = () => child.exitCode === null && child.signalCode === null;
   const deadline = Date.now() + 20_000;
   let up = false;
-  while (Date.now() < deadline) {
-    if (child.exitCode !== null) break;
+  // Whether something else answered on the port: another site's server, or another binder.
+  let other = false;
+  // A binder of this same folder that was already serving on the port (an earlier --detach): it is kept.
+  let earlier = null;
+  while (Date.now() < deadline && running()) {
     try {
-      const response = await fetch(`http://${host.includes(":") ? `[${host}]` : host}:${port}/__bind/health`);
-      if (response.status < 500) {
-        up = true;
-        break;
+      const response = await fetch(`http://${host.includes(":") ? `[${host}]` : host}:${port}${prefix}/__bind/health`, { signal: AbortSignal.timeout(2_000) });
+      // Only this site's own binder counts: the folder it serves and the process it runs in. The child started here
+      // while it still runs, or a binder of this same folder that already held the port, whose answer is never taken
+      // for the child's. Any other answer on the port is another server, never this site being served.
+      const binder = (await response.json().catch(() => null))?.binder;
+      if (response.ok && binder && realOr(binder.root) === folder && Number.isInteger(binder.pid)) {
+        if (binder.pid === child.pid && running()) {
+          up = true;
+          break;
+        }
+        if (binder.pid !== child.pid) {
+          earlier = binder.pid;
+          break;
+        }
       }
+      other = true;
     } catch {
       // not listening yet
     }
@@ -154,7 +187,22 @@ async function serveDetached(dir, flags) {
       return "";
     }
   };
-  if (!up) fail(`the background binder did not start (log ${logFile}):\n${tail()}`);
+  if (!up) {
+    // A binder that never answered as itself is not left running in the background.
+    if (running()) {
+      try {
+        process.kill(child.pid, "SIGTERM");
+      } catch {
+        // already gone
+      }
+    }
+    if (earlier !== null) {
+      process.stdout.write(`instafy-bind already serves ${dir} on port ${port} in the background (pid ${earlier}); it keeps running after this turn.\n`);
+      return;
+    }
+    if (other) fail(`port ${port} is in use by another server, so ${dir} is not served there; pick another --port (log ${logFile}):\n${tail()}`);
+    fail(`the background binder did not start (log ${logFile}):\n${tail()}`);
+  }
   process.stdout.write(`instafy-bind serving ${dir} on port ${port} in the background (pid ${child.pid}; log ${logFile}); it keeps running after this turn.\n`);
   const shown = tail().split("\n").filter((line) => /show it in Studio|public link|agent executor|intents:/.test(line));
   for (const line of shown) process.stdout.write(`${line}\n`);

package/dist/bind/src/check.mjs

@@ -4,8 +4,8 @@
 // every string in its data files (data.json, data/**/*.json, records included). Items come from --expect and from
 // an "expect" array in data.json. Text that only says an item is unavailable ("Not found yet: Tokyo", a data file's
 // "missing" list) does not count as showing it: builders are told to say on the page what they could not add, and
-// that line must not pass the check. On a page of options it also checks the values (below). Pure helpers are
-// exported for the tests.
+// that line must not pass the check. On a page of options it also checks the values and where each row comes from
+// (below). Pure helpers are exported for the tests.
 // SPDX-License-Identifier: AGPL-3.0-only
 import fs from "node:fs";
 import path from "node:path";
@@ -162,7 +162,9 @@ export function checkSite(dir, expect = []) {
 // Each value on such a page names the page it was read on and the day ("checked 27 Oct on maker.com"), and a value
 // nobody found says so with why; a dash or "n/a" is not a value. A filter from a stated limit ("under €600") counts
 // only values the page shows: the starters' site.byFilter lists a row whose value is unknown apart ("Price
-// unknown"), never as within the limit. These rules read the data the same way site.js draws it.
+// unknown"), never as within the limit. A row of a comparison is a candidate a page read names (a value's or a
+// "sources" page), or only a search result ("found": its site, drawn "Not checked"). These rules read the data the
+// same way site.js and the compare starter draw it.
 
 /** A value that only says nothing is known: blank, dashes, "?", "n/a", "unknown", "TBD" (site.js: no value). */
 export const NO_VALUE = /^(?:[\s\-\u2010-\u2015?.\u00b7\u2026/]*|n\s*\/\s*a|unknown|tb[ad])$/i;
@@ -269,7 +271,38 @@ function liveValue(records, key) {
   return NO_VALUE.test(String(newest.value).trim()) ? null : numberIn(String(newest.value));
 }
 
-/** The values of a site's page of options: problems to fix before the card, and notes for the reply. */
+/** A page a row cites: a value with its source and https page, or a "sources" entry with an https page. */
+const citesPage = (fact) => !!(fact && typeof fact === "object" && !fact.est && fact.src && httpsUrl(fact.url));
+
+/** A site as a search result names it ("reviews.example.net"): a host name, not a word or an address. */
+const SITE_NAME = /^(?=.{1,253}$)(?:[\p{L}\p{N}](?:[\p{L}\p{N}-]*[\p{L}\p{N}])?\.)+\p{L}[\p{L}\p{N}-]*$/u;
+
+/** The rows of a comparison (the compare starter's data: "columns" and "items") that say nowhere where they come from:
+ *  no value or "sources" entry cites a page that was read, and no "found" names the site of the search result that
+ *  alone names them. Such a row is a guess or a placeholder ("Model 1"): [{item, problem}]. Judged by the data's
+ *  shape, never by the row's words. A list of names the same turn writes (`--expect`, data.json's "expect") only says
+ *  what the page must show; it never vouches for a row. */
+export function uncitedRows(data) {
+  if (!isOptionsData(data) || !Array.isArray(data.columns)) return [];
+  const out = [];
+  for (const item of data.items) {
+    if (!item || typeof item !== "object") continue;
+    const name = String(item.name ?? item.ref ?? "");
+    const facts = [...Object.values(item.facts && typeof item.facts === "object" ? item.facts : {}), ...(Array.isArray(item.more) ? item.more.map((m) => m?.fact) : [])];
+    const sources = Array.isArray(item.sources) ? item.sources : [];
+    if (facts.some(citesPage) || sources.some((s) => s && typeof s === "object" && s.name && httpsUrl(s.url))) continue;
+    if (typeof item.found === "string" && SITE_NAME.test(item.found.trim())) continue;
+    const label = name || "a row";
+    out.push({
+      item: label,
+      problem: `${label}: nothing says where this row comes from. Cite the page you read that names it (a value's "src" and "url", or "sources": [{"name", "url"}]). When only a search result names it, put that result's site in "found" ("found": "example.com"): the page then says it is not checked. Naming it in --expect or "expect" does not count. A row nothing named (a guess, "Model 1") does not belong on the page.`,
+    });
+  }
+  return out;
+}
+
+/** The values of a site's page of options, and where its rows come from: problems to fix before the card, and notes
+ *  for the reply. */
 export function checkValues(dir) {
   const root = path.resolve(dir);
   const problems = [];
@@ -294,6 +327,7 @@ export function checkValues(dir) {
     const list = lacks.length > 1 ? `${lacks.slice(0, -1).join(", ")} or ${lacks[lacks.length - 1]}` : lacks[0];
     if (lacks.length) problems.push(`${where}: "${valueOf(fact)}" has no ${list}: add where you read it and when ("checked 27 Oct on maker.com"), or leave the value out.${fact.src ? "" : " Without a source the page shows it as not checked."}`);
   }
+  for (const row of uncitedRows(data)) problems.push(row.problem);
 
   const filter = data.filter;
   if (filter && typeof filter === "object") {

package/dist/bind/src/server.mjs

@@ -698,6 +698,10 @@ export function createBinder(options) {
           site: { title: site.title }, token: tokenNeeded(site, req),
           viewer: viewerOk(site, req, url), parentOrigins: parentOriginsFor(site, req),
           executors: { script: "ready", agent: agentState },
+          // Which folder this binder serves and its process, told only to this machine (a loopback socket and name, no
+          // proxy; a tunnel's client connects from here but keeps the viewer's host): `serve --detach` checks that the
+          // answer on the port is its own binder's, not another server's.
+          ...(adminLocal(req) ? { binder: { root, pid: process.pid } } : {}),
         });
       case "session": {
         // The client trades #k= for an HttpOnly cookie once, so EventSource, polling and the page's own fetches

package/dist/bind/src/starters/compare/app.js

@@ -14,10 +14,13 @@
  *                          unknown?: "Price unknown"}. Only a value the page shows counts: a row whose value is
  *                          unknown is never listed as under $160; it is listed apart, under "Price unknown".
  *   items: [{ref: "option:a", name, why (one short line), badge?: "Previous model", note?, facts: {key: fact},
- *            store: {name, url, readable}, more?: [{label, fact}], sources?: [{name, url}]}]
+ *            store: {name, url, readable}, more?: [{label, fact}], sources?: [{name, url}], found?: "example.com"}]
  *                          every candidate a page you read named, also one nothing could be read for: its cells say
  *                          "Unknown" (a table of unknowns). Empty only when no page named any: it reads "No options yet".
- *   unchecked: ["what was not checked", …]     listed once in the footer
+ *                          A row cites a page you read that names it (a value's or a "sources" page). When only a
+ *                          search result names it, "found" is that result's site instead, and the row says "Not
+ *                          checked". `instafy bind check` fails a row with neither: a guess or a placeholder.
+ *   unchecked: ["what was not checked", …]     listed once in the footer, on an empty page too
  *   fact: {"v": "$145", "src": "Example Store", "url": "https://…", "date": "2026-10-17", "asof"?: "2026-08-05", "est": false}
  *   Each value cites its page and day ("checked 17 Oct on maker.com ↗"), and no cell is blank: a source you read that
  *   does not give the value is the fact without "v" ({"src", "url", "date"}): "Not listed · checked 17 Oct on
@@ -126,7 +129,9 @@
     }
     return site.trust(valueOf(item, col), { shared: isShared(src.cols, item, col) || ownRow(src.rows, item, col), label: label, unknown: "Unknown" });
   }
-  function hasMore(item) { return !!(item.note || (item.more && item.more.length) || (item.sources && item.sources.length)); }
+  function hasMore(item) { return !!(item.note || found(item) || (item.more && item.more.length) || (item.sources && item.sources.length)); }
+  /** The site of the search result that alone names this row ("found"), or "". */
+  function found(item) { return typeof item.found === "string" ? item.found.trim().slice(0, 100) : ""; }
 
   /** The "Sort by" select shows (and rows are sorted) only with 5 or more options and more than one way to sort. */
   function sortShown(data) { return (data.sort || []).length > 1 && (data.items || []).length >= 5; }
@@ -235,8 +240,8 @@
     sources = sources.filter(function (s) {
       return !named.some(function (f) { return f.src === s.name || (site.host(f.url) && site.host(f.url) === site.host(s.url)); });
     });
-    // the footer belongs to a list: an empty page has nothing to confirm
-    site.notes(items.length ? data.unchecked : [], items.length ? sources : []);
+    // what was not checked is said on an empty page too: it is why the page is empty
+    site.notes(data.unchecked, sources);
   }
 
   /** "2 without a price are listed last." when the sort key is missing for some rows. */
@@ -275,7 +280,8 @@
 
   function nameBlock(item) {
     return [
-      h("div", { "class": "name-line" }, h("span", { "class": "name", text: item.name }), item.badge ? h("span", { "class": "badge", text: item.badge }) : null),
+      h("div", { "class": "name-line" }, h("span", { "class": "name", text: item.name }), item.badge ? h("span", { "class": "badge", text: item.badge }) : null,
+        found(item) ? h("span", { "class": "badge", text: "Not checked" }) : null),
       item.why ? h("p", { "class": "cap", text: item.why }) : null
     ];
   }
@@ -296,6 +302,7 @@
     var sources = (item.sources || []).filter(function (s) { return s && !linked[s.url]; });
     return h("div", { "class": "more" },
       item.note ? h("p", { text: item.note }) : null,
+      found(item) ? h("p", { "class": "cap", text: "Named in a search result on " + found(item) + "." }) : null,
       facts.length ? h("dl", { "class": "facts" }, facts.map(function (f) {
         return h("div", null, h("dt", { text: f.label }), h("dd", null, site.trust(f.fact)));
       })) : null,