@makerstufferupper/flypi 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@makerstufferupper/flypi",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"type": "module",
 	"description": "Local multi-model agent tool with a browser UI and a personal knowledge wiki, built on the pi SDK.",
 	"license": "MIT",
@@ -24,10 +24,12 @@
 	},
 	"scripts": {
 		"probe": "tsx scripts/probe.ts",
+		"probe:pi": "tsx scripts/probe-pi.ts",
 		"probe:turn": "tsx scripts/probe-turn-boundary.ts",
 		"probe:boundary": "tsx scripts/turn-boundary.ts",
 		"start": "node scripts/start.mjs",
 		"dev": "vite",
+		"dev:container": "node scripts/dev-container.mjs",
 		"models:warm": "tsx scripts/warm-models.ts",
 		"build": "vite build",
 		"prepublishOnly": "npm run typecheck && npm test && npm run build",
@@ -43,20 +45,21 @@
 		"serve": "tsx scripts/serve.ts",
 		"daemon": "tsx scripts/serve-daemon.ts",
 		"flypi": "node scripts/flypi.mjs",
-		"release": "node scripts/release.mjs"
+		"release": "node scripts/release.mjs",
+		"release:check": "node scripts/release-check.mjs"
 	},
 	"dependencies": {
-		"@earendil-works/pi-coding-agent": "^1.0.4",
+		"@earendil-works/pi-coding-agent": "^1.4.0",
 		"@huggingface/transformers": "^4.3.1",
 		"@modelcontextprotocol/sdk": "^1.32.1",
-		"tsx": "^4.23.15",
 		"marked": "18.0.11",
+		"tsx": "^4.23.15",
 		"typebox": "^1.3.27",
 		"ws": "^8.22.0",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "^1.0.4",
+		"@earendil-works/pi-ai": "^1.4.0",
 		"@modelcontextprotocol/server-filesystem": "^1.0.0",
 		"@sveltejs/vite-plugin-svelte": "^7.3.1",
 		"@testing-library/svelte": "^5.4.2",
@@ -68,5 +71,12 @@
 		"typescript": "^7.0.2",
 		"vite": "^8.3.3",
 		"vitest": "^5.0.3"
+	},
+	"allowScripts": {
+		"@google/genai@2.21.0": true,
+		"esbuild@0.28.2": true,
+		"fsevents@2.3.3": true,
+		"onnxruntime-node@1.30.0": true,
+		"protobufjs@7.6.6": true
 	}
 }

package/scripts/dev-container.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * The local dev container, rebuilt from the working tree (docs/release.md, "Deploying something that is
+ * *not* released"). One command for what used to be four.
+ *
+ *   npm run dev:container
+ *
+ * build → pack → `docker build` with `docker/Dockerfile.local` and the tarball's directory as the build
+ * context (the repo's `.dockerignore` excludes `*.tgz`, so the repo is never the context) → replace the
+ * `flypi` container with one off the new image → wait for `/healthz`.
+ *
+ * It removes the `flypi` container and the `flypi:local-*` images older than the one it built. It never
+ * removes the `flypi-data` volume: that holds the memory models (~933 MB), and re-downloading them is the
+ * slowest part of the next start — which is also why the healthcheck gets a 15-minute start period.
+ *
+ * No gates here; `npm run release:check` is the rehearsal that runs them. This is the fast path, and it
+ * touches only the names above: never a published image, never a container this script did not build.
+ */
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const NAME = "flypi";
+const PORT = 8791;
+const VOLUME = "flypi-data";
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+	console.log(`flypi dev container — docs/release.md "Deploying something that is *not* released"
+
+  npm run dev:container        build → pack → image → replace the ${NAME} container on 127.0.0.1:${PORT}
+
+Removes: the ${NAME} container, and flypi:local-* images older than the one it just built.
+Keeps:   the ${VOLUME} volume — the memory models live there, and this script never deletes a volume.
+Tags:    flypi:local-<commit sha>, plus -dirty if the tree is not clean, because the package version
+         inside such an image collides with the published one.
+Stages:  build → pack → image → replace → serve → prune`);
+	process.exit(0);
+}
+
+const version = JSON.parse(readFileSync("package.json", "utf8")).version;
+const die = (message) => {
+	console.error(`dev:container: ${message}`);
+	process.exit(1);
+};
+function git(args) {
+	const result = spawnSync("git", args, { encoding: "utf8" });
+	if (result.status !== 0) die(`git ${args.join(" ")}: ${result.stderr.trim()}`);
+	return result.stdout.trim();
+}
+/** One step. It stops at the first failure: a half-replaced dev container is worse than an old one. */
+function run(command, args, { quiet = false } = {}) {
+	const result = spawnSync(command, args, { encoding: "utf8" });
+	if (result.status !== 0) {
+		die(`${command} ${args.join(" ")} exited ${result.status}${result.stderr ? `: ${result.stderr.trim().split("\n").slice(-3).join(" ")}` : ""}`);
+	}
+	if (!quiet && result.stdout) process.stdout.write(result.stdout);
+	return result;
+}
+const step = (what) => console.log(`\n${what}`);
+
+const sha = git(["rev-parse", "--short", "HEAD"]);
+const tag = `flypi:local-${sha}${git(["status", "--porcelain"]) ? "-dirty" : ""}`;
+const packDir = mkdtempSync(join(tmpdir(), "flypi-dev-"));
+
+try {
+	step("build — dist/ui, which the tarball ships");
+	run("npm", ["run", "build"]);
+
+	step("pack — the same artifact npm would publish, installed by the image");
+	run("npm", ["pack", "--pack-destination", packDir]);
+	const tgz = `makerstufferupper-flypi-${version}.tgz`;
+	copyFileSync("docker/Dockerfile.local", join(packDir, "Dockerfile"));
+
+	step(`image — ${tag} from ${tgz}`);
+	run("docker", ["build", "-q", "--build-arg", `FLYPI_TGZ=${tgz}`, "-t", tag, packDir]);
+
+	step(`replace — container ${NAME} on 127.0.0.1:${PORT}, volume ${VOLUME} kept`);
+	// `rm -f` on a name that is not there exits 1; that is the normal first run, not a failure.
+	spawnSync("docker", ["rm", "-f", NAME], { encoding: "utf8" });
+	run("docker", [
+		"run",
+		"-d",
+		"--name",
+		NAME,
+		"-p",
+		`127.0.0.1:${PORT}:${PORT}`,
+		"-v",
+		`${VOLUME}:/data`,
+		"-e",
+		"FLYPI_ROOT=/data",
+		// The image's own CMD downloads the memory models on a fresh state root, so "unhealthy" for the
+		// first quarter hour is the download, not a broken build.
+		"--health-cmd",
+		`node -e "fetch('http://127.0.0.1:${PORT}/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"`,
+		"--health-interval",
+		"30s",
+		"--health-timeout",
+		"5s",
+		"--health-start-period",
+		"900s",
+		"--health-retries",
+		"3",
+		tag,
+	]);
+
+	step(`serve — waiting on http://127.0.0.1:${PORT}/healthz`);
+	const deadline = Date.now() + 180_000;
+	let body = null;
+	while (Date.now() < deadline && !body) {
+		try {
+			const response = await fetch(`http://127.0.0.1:${PORT}/healthz`);
+			if (response.ok) body = await response.json();
+		} catch {}
+		if (!body) await new Promise((resolve) => setTimeout(resolve, 2000));
+	}
+	if (!body) die(`${NAME} never answered /healthz — docker logs ${NAME}`);
+	console.log(`  ok    flypi ${body.version} · pi ${body.pi?.version ?? "?"} · ${tag}`);
+
+	step("prune — the flypi:local-* images this replaces");
+	const stale = run("docker", ["image", "ls", "flypi:local-*", "--format", "{{.Repository}}:{{.Tag}}"], { quiet: true }).stdout
+		.split("\n")
+		.map((image) => image.trim())
+		.filter((image) => image && image !== tag);
+	for (const image of stale) run("docker", ["rmi", image], { quiet: true });
+	console.log(stale.length ? `  removed ${stale.join(", ")}` : "  nothing older to remove");
+
+	console.log(`\n${NAME} is on http://127.0.0.1:${PORT} — docker logs -f ${NAME} to watch it`);
+} finally {
+	rmSync(packDir, { recursive: true, force: true });
+}

package/scripts/flypi.mjs

@@ -10,13 +10,14 @@
  *   node scripts/flypi.mjs start --foreground --port 8791 --host 0.0.0.0   # the container entry point
  *   node scripts/flypi.mjs status | stop | restart | logs [-n 50] [-f]
  *   node scripts/flypi.mjs update [--check]        # the newest published flypi (docs/architecture.md Phase 7)
+ *   node scripts/flypi.mjs pi [list | available | use <v> | rollback | unpin]   # which pi it runs (docs/pi-upgrades.md Phase 8.3)
  *
  * `--root DIR` (or FLYPI_ROOT) picks which `.flypi/` the CLI owns; in a checkout it defaults to the cwd,
  * and the installed `bin/flypi.mjs` sets FLYPI_ROOT to the home directory before importing this.
  */
 import { mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 const argv = process.argv.slice(2);
@@ -32,6 +33,7 @@ const checkout = resolve(fileURLToPath(import.meta.url), "..", "..");
 const serveDaemon = resolve(fileURLToPath(import.meta.url), "..", "serve-daemon.ts");
 const secretCli = resolve(fileURLToPath(import.meta.url), "..", "secret.ts");
 const updateCli = resolve(fileURLToPath(import.meta.url), "..", "update.ts");
+const piCli = resolve(fileURLToPath(import.meta.url), "..", "pi.ts");
 const infoPath = resolve(root, ".flypi", "daemon.json");
 const logPath = resolve(root, ".flypi", "daemon.log");
 /**
@@ -161,6 +163,8 @@ function report(info, status) {
 	console.log(`flypi: agent   http://${info.host}:${info.port}  (token ${info.token})`);
 	console.log(`flypi: memory  http://127.0.0.1:${info.memoryPort}/mcp`);
 	if (status) console.log(`flypi: started ${status.startedAt}, version ${status.version}, ${status.jobs} job(s) queued`);
+	// Which pi it loaded (src/daemon/pi.ts) — not the range package.json declares, which is the point.
+	if (status?.pi) console.log(`flypi: pi       ${status.pi.version}${status.pi.pinned ? " (pinned)" : ""}${status.pi.bundled ? ` — the installed tree holds ${status.pi.bundled}` : ""}`);
 	// The daemon's own daily answer (src/daemon/update.ts) — `status` does not reach the network itself.
 	if (status?.updateAvailable) console.log(`flypi: ${status.updateAvailable} is available — \`flypi update\` installs it`);
 	if (status?.updateReady) console.log(`flypi: ${status.updateReady} is downloaded — it installs once the daemon has been idle`);
@@ -186,6 +190,13 @@ async function start({ foreground = false, previous } = {}) {
 	// sticky — and it merges, so naming just `--port` does not drop an `--host` that is still in force.
 	const namedFlags = { ...(flagValue("--port") ? { port: Number(flagValue("--port")) } : {}), ...(flagValue("--host") ? { host: flagValue("--host") } : {}) };
 	if (Object.keys(namedFlags).length > 0) writeFileSync(flagsPath, `${JSON.stringify({ ...readJson(flagsPath), ...namedFlags })}\n`);
+	// Which pi the daemon is about to resolve (src/daemon/pi.ts). A flypi upgrade can replace the package
+	// directory and take the pointer with it, so a pin whose tree exists is re-applied here — in this process,
+	// which has not imported pi, and before the daemon exists, because a daemon resolves its module graph at
+	// import and cannot re-pick its own pi.
+	const relink = spawnSync(process.execPath, ["--import", "tsx", piCli, "--root", root, "relink"], { cwd: checkout, encoding: "utf8" });
+	if (relink.stdout?.trim()) console.log(relink.stdout.trim());
+	if (relink.status !== 0) console.error(`flypi: the pi pin could not be applied: ${(relink.stderr ?? "").trim() || `it exited ${relink.status}`}`);
 	if (foreground) {
 		const child = spawn(process.execPath, ["--import", "tsx", serveDaemon, "--root", root, ...flags], { cwd: checkout, stdio: "inherit" });
 		// Ctrl-C and `docker stop` reach this process, not the daemon. PID 1 in a pid namespace drops a signal it
@@ -288,6 +299,12 @@ const flagNumber = (name) => {
 	const i = argv.indexOf(name);
 	return i === -1 ? undefined : Number(argv[i + 1]);
 };
+/** `flypi pi …` (docs/pi-upgrades.md Phase 8.3): which pi this flypi runs, and moving it. */
+async function pi(args) {
+	const child = spawn(process.execPath, ["--import", "tsx", piCli, "--root", root, ...args], { cwd: checkout, stdio: "inherit" });
+	return new Promise((done) => child.on("exit", (code) => done(code ?? 0)));
+}
+
 const result = await {
 	start: () => start({ foreground: argv.includes("--foreground") }),
 	stop,
@@ -302,9 +319,10 @@ const result = await {
 	logs: () => logs({ ...(flagNumber("-n") ? { lines: flagNumber("-n") } : {}), follow: argv.includes("-f") || argv.includes("--follow") }),
 	secret: () => secret(argv.slice(1)),
 	update: () => update(argv.slice(1)),
+	pi: () => pi(argv.slice(1)),
 }[command]?.();
 if (result === undefined) {
-	console.log("usage: flypi [--root DIR] start [--foreground] [--port N] [--host H] [--embeddings none] [--judge none] | stop | restart | status | logs [-n N] [-f] | update [--check] | secret …");
+	console.log("usage: flypi [--root DIR] start [--foreground] [--port N] [--host H] [--embeddings none] [--judge none] | stop | restart | status | logs [-n N] [-f] | update [--check] | pi [list | available | use <version> | rollback | unpin] | secret …");
 	process.exit(2);
 }
 process.exit(result);

package/scripts/pi.ts

@@ -0,0 +1,150 @@
+/**
+ * `flypi pi …` — which pi this flypi runs, and how to move it (docs/pi-upgrades.md Phase 8.3).
+ *
+ *   flypi pi list                       the loaded version, the pin, and the trees on disk
+ *   flypi pi available                  what the registry publishes, one rung at a time
+ *   flypi pi use <version>              probe it, flip the pointer, restart, keep it only if it answers
+ *   flypi pi rollback                   back to the pinned predecessor or the tree flypi shipped with
+ *   flypi pi unpin                      put the installed pi back where npm put it
+ *   flypi pi relink                     re-apply the pin after an upgrade dropped the link (run by `start`)
+ *
+ * Run through the CLI (`scripts/flypi.mjs` spawns this the way it spawns `update.ts`), because the flip has
+ * to happen in a process that has not imported pi yet — the daemon resolves its module graph at import, so
+ * it cannot re-pick its own pi.
+ */
+import { readFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { readDaemonInfo } from "../src/daemon/index.ts";
+import {
+	bundledPiVersion,
+	loadedPi,
+	piTrees,
+	readPiPin,
+	piScope,
+	scopeVersion,
+	restoreBundledScope,
+	relinkFromPin,
+	switchPiVersion,
+	PI_PACKAGE,
+} from "../src/daemon/pi.ts";
+import { checkForUpdate } from "../src/daemon/update.ts";
+
+const argv = process.argv.slice(2);
+const rootAt = argv.indexOf("--root");
+const root = resolve(rootAt === -1 ? process.env.FLYPI_ROOT ?? process.cwd() : argv.splice(rootAt, 2)[1]!);
+const command = argv[0] ?? "list";
+const cli = resolve(import.meta.dirname, "flypi.mjs");
+
+/**
+ * Stop and start the daemon through the CLI, so the port and interface carry over as they always do — but
+ * only when one is running. `flypi restart` on a stopped daemon *starts* it, which would turn "move pi" into
+ * a first run: a new `.flypi/`, a model download, a server on a port nobody asked for.
+ */
+const restart = async (): Promise<void> => {
+	if (!(await piFromHealth())) return;
+	await new Promise<void>((done) => {
+		const child = spawn(process.execPath, [cli, "--root", root, "restart"], { stdio: "inherit" });
+		child.on("exit", () => done());
+	});
+};
+
+/** What `/healthz` says about pi — null when no daemon is answering. */
+const piFromHealth = async () => {
+	const info = readDaemonInfo(root);
+	if (!info) return null;
+	try {
+		return ((await (await fetch(`http://127.0.0.1:${info.port}/healthz`)).json()) as { pi?: { version: string; pinned: boolean; bundled?: string } }).pi ?? null;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * What the switch should believe about what is running: the daemon's own answer when one is up, and otherwise
+ * what the pointer now says — the version the next process will load. Without the second half a switch made
+ * while the daemon was stopped would be judged a failure and reverted.
+ */
+const piAfterSwitch = async (): Promise<{ version: string; pinned: boolean; bundled?: string } | null> => {
+	const health = await piFromHealth();
+	if (health) return health;
+	const loaded = scopeVersion(piScope());
+	return loaded ? { version: loaded, pinned: true } : null;
+};
+
+const logTail = () => {
+	try {
+		return readFileSync(resolve(root, ".flypi", "daemon.log"), "utf8").trimEnd().split("\n").slice(-20).join("\n");
+	} catch {
+		return "";
+	}
+};
+
+const report = async ({ ok, message }: { ok: boolean; message: string }): Promise<number> => {
+	console.log(message);
+	return ok ? 0 : 1;
+};
+
+switch (command) {
+	case "relink": {
+		// `flypi start` runs this before it spawns the daemon: the daemon resolves pi at import, so the link
+		// has to be right before it starts, not after.
+		// Silent when there is nothing to say: `flypi start` runs this every time, and a line about a pin that
+		// did nothing would be noise on every start of every machine that never pinned pi.
+		const line = relinkFromPin(root, piScope());
+		if (line) console.log(`flypi: ${line}`);
+		break;
+	}
+	case "list": {
+		const pi = loadedPi(root);
+		const pin = readPiPin(root);
+		console.log(`flypi: pi ${pi.version}${pi.pinned ? " (pinned)" : ""}${pi.bundled ? `, installed tree holds ${pi.bundled}` : ""}`);
+		console.log(`flypi: trees on disk: ${piTrees(root).join(", ") || "none"}${bundledPiVersion(root) ? `; bundled ${bundledPiVersion(root)}` : ""}`);
+		if (pin) console.log(`flypi: pinned to ${pin.version} since ${pin.pinnedAt}${pin.verified ? "" : " — never confirmed to have started"}`);
+		break;
+	}
+	case "available": {
+		// The same registry answer flypi's own ladder is built from, pointed at pi's package name: one rung at
+		// a time, because a jump runs one version's session/config format change over a file the intermediate
+		// version would have stepped.
+		const current = loadedPi(root).version;
+		const check = await checkForUpdate({ current, name: PI_PACKAGE });
+		if (check.error) {
+			console.log(`flypi: ${check.error}`);
+			break;
+		}
+		console.log(`flypi: pi ${current} is running; the newest published is ${check.latest}`);
+		console.log(`flypi: one rung at a time — ${check.next ? `flypi pi use ${check.next}` : "nothing newer than what is running"}`);
+		break;
+	}
+	case "use": {
+		const version = argv[1];
+		if (!version) {
+			console.log("flypi: `flypi pi use <version>` — `flypi pi available` lists what is published");
+			process.exit(2);
+		}
+		process.exit(await report(await switchPiVersion(version, { root, scope: piScope(), restart, pi: piFromHealth, logTail })));
+	}
+	case "rollback": {
+		const pin = readPiPin(root);
+		const back = pin?.from ?? bundledPiVersion(root);
+		if (!back) {
+			console.log("flypi: nothing to roll back to — no pin, and the tree flypi was installed with is not on disk");
+			process.exit(1);
+		}
+		process.exit(await report(await switchPiVersion(back, { root, scope: piScope(), restart, pi: piFromHealth, logTail })));
+	}
+	case "unpin": {
+		const restored = restoreBundledScope(root, piScope());
+		if (!restored.ok) {
+			console.log(`flypi: ${restored.message}`);
+			process.exit(1);
+		}
+		if (await piFromHealth()) spawnSync(process.execPath, [cli, "--root", root, "restart"], { stdio: "inherit" });
+		console.log(`flypi: ${restored.message}; the pin is gone`);
+		break;
+	}
+	default:
+		console.log("usage: flypi pi [list | available | use <version> | rollback | unpin]");
+		process.exit(2);
+}

package/scripts/probe-pi.ts

@@ -0,0 +1,18 @@
+/**
+ * Stage 1 of the pi upgrade probe (docs/pi-upgrades.md Phase 8.2): does a candidate pi still offer the
+ * surface flypi imports? Imports, deep paths and the Node floor, in a child process, with nothing restarted.
+ *
+ * Run: `npm run probe:pi -- --candidate DIR` — DIR is a tree built by `npm install --prefix` (Phase 8.3), or
+ * this repo's own root to check the pi that is already installed. Exit 0 clean, 1 with one line per problem.
+ *
+ * A clean run means "nothing renamed, moved or raised a floor", not "flypi works on it". The behavioural
+ * half of pi's API is only covered by `npm test` and `npm run smoke` (docs/risks.md risk 14).
+ */
+import { checkPiCompat } from "../src/agent/pi-compat.ts";
+
+const argv = process.argv.slice(2);
+const candidate = argv[argv.indexOf("--candidate") + 1] ?? process.cwd();
+const failures = await checkPiCompat(candidate);
+for (const failure of failures) console.error(`pi compat: ${failure}`);
+console.log(failures.length ? `pi compat: ${failures.length} problem(s) in ${candidate}` : `pi compat: ok — ${candidate}`);
+process.exit(failures.length ? 1 : 0);