A local-first multi-agent app development platform, built on PenguinHarness
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
inspectSymlinkTarget,
inspectWrapperTarget,
isVolatileAppLocation,
legacyOfferedFlagPath,
readCliCommandState,
stateFilePath,
syncSymlink,
syncWrapper,
writeCliCommandState,
} from "../src/cli-link.js";
import { appImageWrapperScript, posixLauncherScript } from "../src/launcher.js";
/**
* A real directory tree, not a mocked fs: the whole point of these functions is what they
* do to symlinks, modes and dangling targets, none of which a mock would reproduce.
*/
let tmp: string;
/**
* Tests whose assertion is a POSIX fact: the target a dangling symlink stores (Windows
* rewrites it into a backslash path that no longer names the packaged layout), and the exec
* bit, which Windows does not carry. Both belong to forms that only run on macOS and Linux.
*/
const itPosix = it.skipIf(process.platform === "win32");
beforeEach(() => {
tmp = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-cli-link-"));
});
afterEach(() => {
fs.rmSync(tmp, { recursive: true, force: true });
});
/** A packaged app tree with the launcher the installers point at. */
function packApp(name: string): string {
const appDir = path.join(tmp, name, "Contents", "Resources", "app");
fs.mkdirSync(path.join(appDir, "bin"), { recursive: true });
const launcher = path.join(appDir, "bin", "penguin");
fs.writeFileSync(launcher, posixLauncherScript(), { mode: 0o755 });
return launcher;
}
describe("syncSymlink (the macOS form)", () => {
it("installs when nothing is there", () => {
const desired = packApp("Adelie.app");
const link = path.join(tmp, "usr-local-bin", "penguin");
expect(syncSymlink(link, desired, false)).toEqual({
action: "installed",
detail: `${link} does not exist`,
});
expect(fs.readlinkSync(link)).toBe(desired);
});
it("does nothing when it already points at this app", () => {
const desired = packApp("Adelie.app");
const link = path.join(tmp, "bin", "penguin");
syncSymlink(link, desired, false);
const before = fs.lstatSync(link).mtimeMs;
expect(syncSymlink(link, desired, false).action).toBe("current");
expect(fs.lstatSync(link).mtimeMs).toBe(before);
});
itPosix("repairs a link left dangling by a moved or updated app", () => {
// What a launch from the dmg used to leave behind, and what an app moved out of a
// previous location leaves behind: the link is ours, and its target is gone.
const link = path.join(tmp, "bin", "penguin");
fs.mkdirSync(path.dirname(link), { recursive: true });
fs.symlinkSync("/Volumes/Adelie/Adelie.app/Contents/Resources/app/bin/penguin", link);
expect(fs.existsSync(link)).toBe(false); // dangling
const desired = packApp("Adelie.app");
expect(syncSymlink(link, desired, false).action).toBe("installed");
expect(fs.readlinkSync(link)).toBe(desired);
});
it("repairs a link pointing at an older install of this app", () => {
const stale = packApp("Old.app");
const link = path.join(tmp, "bin", "penguin");
fs.mkdirSync(path.dirname(link), { recursive: true });
fs.symlinkSync(stale, link);
const desired = packApp("Adelie.app");
expect(syncSymlink(link, desired, false).action).toBe("installed");
expect(fs.readlinkSync(link)).toBe(desired);
});
it("never replaces a penguin this app did not write", () => {
const desired = packApp("Adelie.app");
const link = path.join(tmp, "bin", "penguin");
fs.mkdirSync(path.dirname(link), { recursive: true });
// A regular file: an npm global install, a Homebrew shim, the user's own script.
fs.writeFileSync(link, "#!/bin/sh\necho not ours\n", { mode: 0o755 });
const result = syncSymlink(link, desired, false);
expect(result.action).toBe("skipped");
expect(result.detail).toContain("not a symlink this app wrote");
expect(fs.readFileSync(link, "utf8")).toBe("#!/bin/sh\necho not ours\n");
expect(fs.lstatSync(link).isSymbolicLink()).toBe(false);
});
it("never follows a foreign symlink either", () => {
const desired = packApp("Adelie.app");
const theirs = path.join(tmp, "dot-penguin", "bin", "penguin");
fs.mkdirSync(path.dirname(theirs), { recursive: true });
fs.writeFileSync(theirs, "#!/bin/sh\necho tarball\n", { mode: 0o755 });
const link = path.join(tmp, "bin", "penguin");
fs.mkdirSync(path.dirname(link), { recursive: true });
fs.symlinkSync(theirs, link);
expect(syncSymlink(link, desired, false).action).toBe("skipped");
expect(fs.readlinkSync(link)).toBe(theirs);
});
it("replaces a foreign command only when forced, which only the menu item does", () => {
const desired = packApp("Adelie.app");
const link = path.join(tmp, "bin", "penguin");
fs.mkdirSync(path.dirname(link), { recursive: true });
fs.writeFileSync(link, "#!/bin/sh\necho not ours\n", { mode: 0o755 });
expect(syncSymlink(link, desired, true).action).toBe("installed");
expect(fs.readlinkSync(link)).toBe(desired);
});
});
describe("syncWrapper (the Linux AppImage form)", () => {
const script = appImageWrapperScript("/home/u/Apps/penguin-desktop-linux-x86_64.AppImage");
it("installs a wrapper when nothing is there", () => {
const target = path.join(tmp, "local-bin", "penguin");
expect(syncWrapper(target, script, false).action).toBe("installed");
expect(fs.readFileSync(target, "utf8")).toBe(script);
// Written through a temporary file; it must not be left behind.
expect(fs.existsSync(`${target}.tmp`)).toBe(false);
});
itPosix("installs it executable, or nothing on PATH can run it", () => {
const target = path.join(tmp, "local-bin", "penguin");
syncWrapper(target, script, false);
expect(fs.statSync(target).mode & 0o111).not.toBe(0);
});
it("does nothing when the wrapper already runs this AppImage", () => {
const target = path.join(tmp, "local-bin", "penguin");
syncWrapper(target, script, false);
expect(syncWrapper(target, script, false).action).toBe("current");
});
it("rewrites its own wrapper when the AppImage moved", () => {
const target = path.join(tmp, "local-bin", "penguin");
syncWrapper(target, appImageWrapperScript("/old/path.AppImage"), false);
expect(syncWrapper(target, script, false).action).toBe("installed");
expect(fs.readFileSync(target, "utf8")).toBe(script);
});
it("never replaces the symlink install.sh puts at this exact path", () => {
// install.sh does `ln -sf ~/.penguin/bin/penguin ~/.local/bin/penguin`, unconditionally,
// at the very path this form uses. Ours is the side that has to give way.
const theirs = path.join(tmp, "dot-penguin", "bin", "penguin");
fs.mkdirSync(path.dirname(theirs), { recursive: true });
fs.writeFileSync(theirs, "#!/bin/sh\necho tarball\n", { mode: 0o755 });
const target = path.join(tmp, "local-bin", "penguin");
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.symlinkSync(theirs, target);
const result = syncWrapper(target, script, false);
expect(result.action).toBe("skipped");
expect(result.detail).toContain("which this app did not write");
expect(fs.readlinkSync(target)).toBe(theirs);
});
it("never replaces a foreign regular file", () => {
const target = path.join(tmp, "local-bin", "penguin");
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, "#!/usr/bin/env node\n// somebody else's penguin\n", { mode: 0o755 });
expect(syncWrapper(target, script, false).action).toBe("skipped");
expect(fs.readFileSync(target, "utf8")).toContain("somebody else's penguin");
});
it("does not read a large binary sitting at the target", () => {
const target = path.join(tmp, "local-bin", "penguin");
fs.mkdirSync(path.dirname(target), { recursive: true });
// The marker sits past the size cap on purpose: what makes this foreign has to be the
// refusal to read the file, not the absence of the text.
fs.writeFileSync(target, Buffer.concat([Buffer.alloc(128 * 1024, 7), Buffer.from(script)]));
expect(syncWrapper(target, script, false).action).toBe("skipped");
expect(fs.statSync(target).size).toBe(128 * 1024 + Buffer.byteLength(script));
});
});
describe("inspect helpers", () => {
it("recognises a launcher from an older release by its marker", () => {
// The marker text has shipped unchanged since 0.2.2, which is what lets an install made
// by an older version be repaired rather than treated as somebody else's command.
const target = path.join(tmp, "penguin");
fs.writeFileSync(target, posixLauncherScript());
expect(inspectWrapperTarget(target, "different script").kind).toBe("ours");
});
it("reports an unreadable target as foreign rather than guessing", () => {
const dir = path.join(tmp, "penguin");
fs.mkdirSync(dir);
expect(inspectSymlinkTarget(dir, "/x/bin/penguin").kind).toBe("foreign");
expect(inspectWrapperTarget(dir, "script").kind).toBe("foreign");
});
});
describe("isVolatileAppLocation", () => {
it("refuses to install from a mounted dmg", () => {
expect(
isVolatileAppLocation("/Volumes/Adelie/Adelie.app/Contents/Resources/app", "darwin"),
).toBe(true);
});
it("refuses to install from a translocated bundle", () => {
// Gatekeeper runs a quarantined bundle from a read-only copy under a random path; a
// link into it dies with the session.
expect(
isVolatileAppLocation(
"/private/var/folders/x/AppTranslocation/1B2C/d/Adelie.app/Contents/Resources/app",
"darwin",
),
).toBe(true);
});
it("installs normally from Applications", () => {
expect(isVolatileAppLocation("/Applications/Adelie.app/Contents/Resources/app", "darwin")).toBe(
false,
);
});
it("is a macOS rule only", () => {
expect(isVolatileAppLocation("/Volumes/whatever/app", "linux")).toBe(false);
expect(isVolatileAppLocation("/Volumes/whatever/app", "win32")).toBe(false);
});
});
describe("recorded state", () => {
it("remembers a declined administrator prompt", () => {
writeCliCommandState(tmp, { version: 1, decision: "declined", lastResult: "failed" });
expect(readCliCommandState(tmp).decision).toBe("declined");
});
it("treats every other outcome as no decision, so the next launch retries", () => {
for (const lastResult of ["foreign", "deferred", "failed"] as const) {
writeCliCommandState(tmp, { version: 1, lastResult });
expect(readCliCommandState(tmp).decision).toBeUndefined();
}
});
it("reads a missing or corrupt file as no decision rather than a decline", () => {
expect(readCliCommandState(tmp).decision).toBeUndefined();
fs.writeFileSync(stateFilePath(tmp), "{ not json");
expect(readCliCommandState(tmp).decision).toBeUndefined();
fs.writeFileSync(stateFilePath(tmp), JSON.stringify({ decision: "whatever" }));
expect(readCliCommandState(tmp).decision).toBeUndefined();
});
it("removes the pre-0.2.7 marker, which recorded the question and not the answer", () => {
const legacy = legacyOfferedFlagPath(tmp);
fs.writeFileSync(legacy, "2026-08-06T00:00:00.000Z\n");
writeCliCommandState(tmp, { version: 1, lastResult: "installed" });
expect(fs.existsSync(legacy)).toBe(false);
});
it("survives an unwritable state directory", () => {
const nested = path.join(tmp, "file-in-the-way", "userData");
fs.writeFileSync(path.join(tmp, "file-in-the-way"), "");
expect(() =>
writeCliCommandState(nested, { version: 1, lastResult: "installed" }),
).not.toThrow();
expect(readCliCommandState(nested).decision).toBeUndefined();
});
});