Skip to content

sykk/ircx / scripts/run-ircx

run-ircx

Verified

Build, run, and drive ircx. Use when asked to start ircx, run its tests, build it, take a screenshot of its UI, click through the app, or check that a frontend change works in the running client.

FileKindSize
SKILL.mdskill md20.7 KB
driver.mjsscript14.2 KB
quickserver.mjsscript4.5 KB
seed.mjsscript13.0 KB
shift.pyscript2.1 KB
soak.mjsscript10.2 KB
startup.mjsscript11.2 KB
vite.browser.config.mjsscript2.7 KB
window.mjsscript16.9 KB
xsend.cother5.2 KB

window.mjs

View on GitHub
#!/usr/bin/env node
// Drives the assembled app — Rust backend, WebKitGTK window — on its own Xvfb,
// and answers on stdin the way driver.mjs does.
//
// driver.mjs is the one to reach for. It runs the frontend in Chrome, where a
// selector reaches an element and the DevTools Protocol answers questions. This
// one is for what only the real app can show: a live socket, the delivery
// states behind it, and anything the Rust side decides.
//
// What it cannot do, because nothing answers for WebKitGTK here:
//
//   * No selectors. The window is read by screenshot and clicked by coordinate.
//   * A coordinate goes stale. The timeline moves under a control while you are
//     aiming at it — take the shot, click, and let nothing arrive in between.
//
// Commands, one per line on stdin, one `ok`/`err` line back:
//
//   type <text>          insert text at the focus, a keystroke at a time
//   key <combo>          Return, Escape, ctrl+k, shift+Return
//   click <x> <y>        window coordinates, the window being at the origin
//   wheel <x> <y> <n>    scroll there, n notches, up when negative
//   ss <file>            screenshot the display to <file> (PNG)
//   wait <ms>
//   quit
//
// Options:
//
//   --server <host:port>   default 127.0.0.1:6667
//   --nick <nick>          default walker
//   --join <#channel>      seeded as a connect command, repeatable
//   --tls                  the seeded network uses TLS, off by default
//   --sasl <account:pass>  the seeded network logs in with SASL PLAIN, which is
//                          what a walk needs to be two sessions of one account
//   --release              drive the release app, built by `npm run tauri build`,
//                          which is what a figure has to be measured on
//   --keep                 leave the profile behind and print where it is
//   --profile <dir>        launch on a profile a --keep run left, as it stands,
//                          which is how "does it survive a restart" is asked
//
// Needs `gcc`, `libXtst`, `Xvfb`, `xprop` and ImageMagick's `import`.
import { spawn, spawnSync } from "node:child_process";
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { createInterface } from "node:readline";
import { DatabaseSync } from "node:sqlite";

const SKILL_DIR = fileURLToPath(new URL(".", import.meta.url));
const ROOT = join(SKILL_DIR, "..", "..");
/* The default, which is this worktree's own. `CARGO_TARGET_DIR` is still
 * honoured for anyone who has set one, but SKILL.md no longer tells callers to
 * point it at another checkout — a shared target directory hands this script
 * whichever checkout built last, and the binary it launches is then not the
 * tree being walked. */
const TARGET = process.env.CARGO_TARGET_DIR ?? join(ROOT, "target");

const say = (line) => process.stdout.write(`${line}\n`);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

function flag(name, fallback) {
  const at = process.argv.indexOf(`--${name}`);
  return at === -1 ? fallback : process.argv[at + 1];
}
function flags(name) {
  return process.argv.flatMap((arg, at) => (arg === `--${name}` ? [process.argv[at + 1]] : []));
}

const [HOST, PORT] = (flag("server", "127.0.0.1:6667") ?? "").split(":");
const NICK = flag("nick", "walker");
const CHANNELS = flags("join");
const TLS = process.argv.includes("--tls");
/* The password does not go in the seed: the app keeps it in the OS keyring and
 * reads it from there, so a walk has to put it where the app will look — the
 * `ircx` service, under the network's id. */
const [SASL_ACCOUNT, SASL_PASSWORD] = (flag("sasl", "") ?? "").split(":");
const KEEP = process.argv.includes("--keep");
/* A release app carries the frontend inside it and needs no dev server, so this
 * drives what people actually run rather than a debug binary against Vite. Any
 * figure — memory, startup, size — has to come from it; the debug build is for
 * behaviour only. */
const RELEASE = process.argv.includes("--release");
const BINARY = join(TARGET, RELEASE ? "release" : "debug", "ircx");

/* The window is 1200x800 in src-tauri/tauri.conf.json and there is no window
 * manager to place it, so it sits at the origin. A screen of the same size
 * makes a screenshot the window and a click coordinate the window's own. */
const WIDTH = 1200;
const HEIGHT = 800;

function need(binary) {
  if (spawnSync("sh", ["-c", `command -v ${binary}`]).status !== 0) {
    throw new Error(`${binary} is not installed`);
  }
}
["gcc", "Xvfb", "xprop", "import"].forEach(need);
if (SASL_ACCOUNT) need("secret-tool");

/* `npm run tauri build`, and not `cargo build --release`: what decides whether
 * the frontend is inside the binary or fetched from the dev server is the tauri
 * CLI rather than the cargo profile, and both land at this same path. A window
 * driven against the cargo one shows `Could not connect to localhost` on a
 * white page — nothing here can tell them apart, since the embedded assets are
 * compressed, so the first screenshot is what says which you have. */
const BUILD_RELEASE = "run: npm run tauri build -- --no-bundle";

if (RELEASE) {
  if (!existsSync(BINARY)) throw new Error(`no release binary at ${BINARY} — ${BUILD_RELEASE}`);
} else {
  /* Built rather than demanded — it is a minute the first time and nothing
   * after it. Built on every run rather than only when the file is missing,
   * because a binary left by an earlier run is not necessarily this one: the
   * feature list below changed once, and a walk that skipped the build kept
   * launching the old binary and failing the way it failed before.
   *
   * `walk` drops the single-instance plugin. Without it a machine already
   * running ircx makes every launch hand off to that one and exit 0, so no
   * window ever maps here and the run dies on a timeout with nothing on
   * stderr to say why. */
  say("ok building the app, which takes a while the first time");
  const built = spawnSync(
    "cargo",
    [
      "build",
      "--manifest-path",
      join(ROOT, "src-tauri", "Cargo.toml"),
      "--no-default-features",
      "--features",
      "walk",
    ],
    { stdio: ["ignore", "ignore", "inherit"] },
  );
  if (built.status !== 0) throw new Error("cargo build failed");
}


/* A profile from an earlier `--keep` run, launched again as it stands. Whether
 * something survives a restart — a draft, a pane layout, a theme and its edits
 * — cannot be asked of a profile that is seeded fresh every time, and that is
 * the shape half of `docs/manual-verification.md` is written in. */
const REUSE = flag("profile", null);

const run = mkdtempSync(join(tmpdir(), "ircx-window-"));
const XSEND = join(run, "xsend");
const compiled = spawnSync("gcc", ["-O2", "-o", XSEND, join(SKILL_DIR, "xsend.c"), "-lX11", "-lXtst"], {
  stdio: ["ignore", "ignore", "inherit"],
});
if (compiled.status !== 0) throw new Error("could not build xsend — is libXtst installed?");

/** A display number nothing else is holding. */
function freeDisplay() {
  for (let n = 90; n < 130; n++) if (!existsSync(`/tmp/.X11-unix/X${n}`)) return n;
  throw new Error("no free X display between :90 and :130");
}
const DISPLAY = `:${freeDisplay()}`;
const xvfb = spawn("Xvfb", [DISPLAY, "-screen", "0", `${WIDTH}x${HEIGHT}x24`], {
  stdio: ["ignore", "ignore", "pipe"],
});
/* Nothing here wants Xvfb's warnings, but a pipe nobody reads is not the same
 * as a closed one: node backs stdio pipes with socketpairs, so the warnings sit
 * in a buffer that fills. Xvfb starts by running xkbcomp and waiting for it,
 * and xkbcomp's own keymap warnings are enough to fill it on a host that also
 * has something to say about its GPU. It then blocks in a write forever, Xvfb
 * waits on it forever, and the display accepts no connections — so every later
 * `xprop` hangs rather than failing, and the run makes no progress and no
 * error. Drained, not ignored: an Xvfb that dies still says why. */
xvfb.stderr.resume();
await sleep(700);

/* GTK prefers Wayland when WAYLAND_DISPLAY is set, so an app started with
 * DISPLAY alone opens on the operator's real desktop while this Xvfb stays
 * black and nothing says why. #347. */
const { WAYLAND_DISPLAY: _wayland, ...inherited } = process.env;
const HOME_DIR = REUSE ?? join(run, "data");
const appEnv = { ...inherited, DISPLAY, GDK_BACKEND: "x11", XDG_DATA_HOME: HOME_DIR };
const ARCHIVE = join(HOME_DIR, "chat.ircx.app", "ircx.sqlite3");

const children = [];
/** The app's own complaints, kept so a launch that never draws a window can
 * report what it said instead of only that it timed out — it refuses a dev
 * server belonging to another checkout, and says so on the way out. #233. */
let appSaid = "";
function startApp() {
  const app = spawn(BINARY, [], { env: appEnv, stdio: ["ignore", "ignore", "pipe"] });
  appSaid = "";
  app.stderr.on("data", (chunk) => (appSaid += chunk.toString()));
  children.push(app);
  return app;
}

/** Whether the window has mapped. Polled rather than waited on: the app says
 * nothing on stdout when its window appears. */
function windowUp() {
  return spawnSync("xprop", ["-name", "ircx"], { env: { ...process.env, DISPLAY } }).status === 0;
}
async function waitForWindow(what, timeoutMs = 90_000) {
  const until = Date.now() + timeoutMs;
  while (Date.now() < until) {
    if (windowUp()) return;
    await sleep(500);
  }
  throw new Error(`timed out waiting for ${what}\n${appSaid.trim()}`);
}

/* Vite serves the frontend a debug binary loads: tauri.conf.json pins the port
 * with strictPort, so a dev server from another checkout fails this outright
 * rather than serving somebody else's working tree. #233. A release build reads
 * none of this — the frontend is inside it.
 *
 * The number is read out of `tauri.conf.json` rather than written here, the way
 * `vite.config.ts` reads it: another session holding 5183 is the reason to move
 * `devUrl`, and a harness that has the old number in it cannot be moved with
 * everything else. */
const DEV_PORT = Number(
  new URL(JSON.parse(readFileSync(join(ROOT, "src-tauri/tauri.conf.json"), "utf8")).build.devUrl)
    .port,
);
if (!RELEASE) {
  const vite = spawn("npm", ["run", "dev"], { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] });
  children.push(vite);
  await new Promise((resolve, reject) => {
    let buffer = "";
    const timer = setTimeout(() => reject(new Error("timed out waiting for the Vite dev server")), 60_000);
    const onData = (chunk) => {
      buffer += chunk.toString();
      /* The served URL rather than the port number: "Port 5183 is already in
       * use" carries the port too, and matching that reports a dev server
       * belonging to another checkout as this one starting up. */
      if (!buffer.includes(`http://localhost:${DEV_PORT}/`)) return;
      clearTimeout(timer);
      resolve();
    };
    vite.stdout.on("data", onData);
    vite.stderr.on("data", onData);
    vite.once("exit", (code) => reject(new Error(`the dev server exited with ${code}\n${buffer}`)));
  });
}

/* A reused profile has its archive and its network already, and seeding a
 * second one would answer a different question than the one being asked. */
if (!REUSE) {
  /* The archive has to exist before a network can go in it, and the app is what
   * creates and migrates it. So: launch once, let it write the file, and stop it
   * again. Onboarding is on screen for those few seconds and is never answered. */
  const first = startApp();
  await waitForWindow("the app to create its profile");
  await waitForSchema();
  first.kill();
  await seedWhenUnlocked();
}

/* The app does not drop its SQLite lock the instant it is killed, and the seed
 * is the next thing that wants the file. The 1500ms this replaced was covering
 * that as well as the migration, so shortening it to a schema check moved the
 * failure rather than fixing it: `database is locked`, one run in ten, under
 * load. Both halves are conditions now and neither is a duration. */
async function seedWhenUnlocked() {
  const deadline = Date.now() + 30_000;
  for (;;) {
    try {
      seedNetwork();
      return;
    } catch (e) {
      if (!/locked|busy/i.test(String(e)) || Date.now() > deadline) throw e;
      await sleep(250);
    }
  }
}

/* The window is up before the archive is migrated, so the wait above does not
 * say the table is there. A fixed 1500ms stood in for it and held on an idle
 * machine; under sixteen spinners every walk died on `no such table: networks`
 * before it reached the server, which reads as the app failing under load and
 * is the harness guessing. Waiting for the table rather than for a duration is
 * what makes a loaded walk mean anything.
 *
 * It waits with the app still up, which is the whole of it: the app is what
 * writes the table, so a wait after the kill is a wait on nothing and times out
 * however long it is given. */
async function waitForSchema() {
  const deadline = Date.now() + 30_000;
  for (;;) {
    try {
      const db = new DatabaseSync(ARCHIVE);
      const [table] = db
        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'networks'")
        .all();
      db.close();
      if (table) return;
    } catch {
      /* The file is not there yet, or is mid-migration. Both are "not ready". */
    }
    if (Date.now() > deadline) throw new Error(`no networks table in ${ARCHIVE} after 30s`);
    await sleep(250);
  }
}

function seedNetwork() {
  const db = new DatabaseSync(ARCHIVE);
  db.prepare(
    `INSERT INTO networks (id, name, host, port, tls, tls_verify, nick, alt_nicks, username,
                           realname, sasl_mechanism, sasl_account, connect_commands, autojoin,
                           auto_connect)
     VALUES (?, ?, ?, ?, ?, ?, ?, '[]', ?, ?, ?, ?, ?, '[]', 1)`,
  ).run(
    "walk",
    "walk",
    HOST,
    Number(PORT),
    TLS ? 1 : 0,
    0,
    NICK,
    NICK,
    NICK,
    /* JSON, and not the bare word: the column holds a serialised
     * `SaslMechanism`, so `PLAIN` deserialises into nothing and takes the whole
     * network list down with it — the app comes up saying it has no networks
     * configured, with the row sitting in the table. */
    SASL_ACCOUNT ? JSON.stringify("PLAIN") : null,
    SASL_ACCOUNT || null,
    JSON.stringify(CHANNELS.map((channel) => `/join ${channel}`)),
  );
  db.close();
  if (SASL_ACCOUNT) seedPassword();
}

/* `keyring` 3.x names an entry by four attributes and finds it by three of
 * them, so a password written under anything else is a password the app cannot
 * see — and SASL then fails in a way that reads as the server refusing it.
 * `crates/ircx-store/src/credentials.rs` is where `ircx` and the id come from. */
function seedPassword() {
  const stored = spawnSync(
    "secret-tool",
    ["store", "--label=ircx walk", "service", "ircx", "username", "walk",
     "target", "default", "application", "rust-keyring"],
    { input: SASL_PASSWORD },
  );
  if (stored.status !== 0) {
    throw new Error(String(stored.stderr).trim() || "secret-tool store failed");
  }
}

startApp();
await waitForWindow(REUSE ? "the app to come back up on that profile" : "the app to come back with its network");

const xsend = (...args) => {
  const done = spawnSync(XSEND, args, { env: { ...process.env, DISPLAY } });
  if (done.status !== 0) throw new Error(String(done.stderr).trim() || "xsend failed");
};

async function command(line) {
  const [verb, ...rest] = line.trim().split(/\s+/);
  const argument = rest.join(" ");
  switch (verb) {
    case "type":
      xsend("type", argument);
      await sleep(200);
      return "ok typed";
    case "key":
      xsend("key", argument);
      await sleep(250);
      return "ok pressed";
    case "click":
      xsend("click", rest[0], rest[1]);
      await sleep(250);
      return "ok clicked";
    case "move":
      xsend("move", rest[0], rest[1]);
      await sleep(250);
      return "ok moved";
    case "wheel":
      xsend("wheel", rest[0], rest[1], rest[2]);
      await sleep(250);
      return "ok scrolled";
    case "ss": {
      const shot = spawnSync("import", ["-window", "root", argument], {
        env: { ...process.env, DISPLAY },
      });
      if (shot.status !== 0) throw new Error(String(shot.stderr).trim() || "import failed");
      return `ok screenshot ${argument}`;
    }
    case "wait":
      await sleep(Number(argument) || 250);
      return "ok waited";
    default:
      throw new Error(`unknown command ${verb}`);
  }
}

say(`ok ready ${DISPLAY} profile ${HOME_DIR}`);

const lines = createInterface({ input: process.stdin });
for await (const line of lines) {
  if (!line.trim() || line.trim().startsWith("#")) continue;
  if (line.trim() === "quit") break;
  try {
    say(await command(line));
  } catch (reason) {
    say(`err ${String(reason.message ?? reason).split("\n")[0]}`);
  }
}

for (const child of children) child.kill();
xvfb.kill();
if (SASL_ACCOUNT && !KEEP) {
  spawnSync("secret-tool", ["clear", "service", "ircx", "username", "walk"]);
}
if (KEEP) say(`ok profile kept at ${HOME_DIR}`);
else rmSync(run, { recursive: true, force: true });
process.exit(0);
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall