@timqi/pier 0.0.3 → 0.0.5

package/README.md

@@ -26,7 +26,7 @@ versioned from `0.0.1` on — earlier databases are not migrated. Read
 
 ```sh
 npm install -g @timqi/pier
-pier
+pier serve
 ```
 
 It listens on `127.0.0.1:3141` (`PORT`, `HOST`) and keeps everything under
@@ -57,7 +57,7 @@ installation. By default it is `$PIER_HOME/pi` (`~/.pier/pi`). Set
 an existing Pi setup:
 
 ```sh
-PI_CODING_AGENT_DIR="$HOME/.pi/agent" pier
+PI_CODING_AGENT_DIR="$HOME/.pi/agent" pier serve
 ```
 
 Console → Settings is the normal setup path:
@@ -68,8 +68,9 @@ Console → Settings is the normal setup path:
 - **Agent files** edits `SYSTEM.md`, `AGENTS.md`, `settings.json`, and advanced
   `models.json` structure in the Pi agent directory — globally, or per project
   scope, where it also shows that project's `.pi/skills` and `.pi/extensions`
-  resources. Changes apply when a session next opens; `pier reload` recycles
-  idle, unwatched sessions so their next message uses the current files.
+  resources. Changes apply when a session next opens; saving here recycles the
+  idle ones for you, and **Settings → Instance → Reload** does it for files
+  something else changed — an agent, or an editor on the box.
 
 On first credential access, Pier imports an existing `auth.json` into its sealed
 store and renames the source to `auth.json.imported`. Literal provider keys left
@@ -109,8 +110,9 @@ find a version-managed one), a memory drop-in it never rewrites afterwards, and
 turns on linger so scheduled tasks survive your logout. Install also records the
 exact npm executable in a separate updater unit. Re-run `pier service install
 --force` after changing the service settings or its Node/npm installation; this
-rewrites both units and restarts Pier. On macOS run `pier` in a terminal, or
-under whatever supervisor you already use.
+rewrites both units and restarts Pier. On macOS run `pier serve` in a terminal,
+or under whatever supervisor you already use — `pier` on its own only prints
+the usage.
 
 `docs/deploy.md` is the same thing written out by hand, plus what the memory
 limits mean, how updates work (and why the updater is a second unit), how to
@@ -154,13 +156,15 @@ time to finish, whatever the deadline still had to cut off written to the chat
 it belonged to — and only then hand over. The automatic path additionally waits
 for an idle instance: no turn streaming, no task run in flight.
 
-Either way the updater writes `~/.pier/db/pier.db.release.bak` before npm
-touches the package, updates the npm installation recorded when the service was
-installed, and starts Pier again.
+Either way the updater writes `~/.pier/db/backups/pier.db.release-<version>.bak`
+before npm touches the package — named for the release being replaced, which is
+the one to reinstall beside it; the three newest are kept. Then it updates the
+npm installation recorded when the service was installed, and starts Pier again.
 
-`main` is the only development line. `npm version patch` writes the tag, the
-tag builds and publishes a GitHub Release, and the version in the web footer is
-the one from `package.json` — so the number on screen always names a commit.
+`main` is the only development line. `just release [patch|minor|major]` runs the
+checks, writes the tag and pushes it; the tag builds and publishes to npm and as
+a GitHub Release. The version in the web footer is the one from `package.json`
+— so the number on screen always names a commit.
 Schema upgrades are one-way: a database migrated by a newer Pier is refused by
 an older one. The release backup above is the way back; `docs/deploy.md` has the
 restore procedure and the additional snapshots taken before schema migrations.

package/dist/cli.js

@@ -15,7 +15,7 @@ const version = currentVersion();
 const HELP = `pier ${version} — a self-hosted workspace for coding agents
 
 Usage
-  pier                        run the workbench in this terminal
+  pier serve                  run the workbench in this terminal
   pier service install        write and start a systemd user unit (Linux)
   pier service uninstall      stop it and remove the unit
   pier service status         what systemd thinks of it
@@ -76,7 +76,15 @@ else if (values.version || command === "version") {
     process.stdout.write(`${version}\n`);
 }
 else if (!command) {
-    allowOnly([], "pier");
+    // Typing the bare name is how someone finds out what this is, so it answers
+    // that and nothing else: it used to start a server, which is a surprising
+    // amount to have done by accident.
+    process.stdout.write(HELP);
+}
+else if (command === "serve") {
+    if (subcommand)
+        fail(`unexpected argument "${subcommand}"`);
+    allowOnly([], "pier serve");
     // The server starts on import; this file stays a dispatcher.
     await import("./main.js");
 }
@@ -170,7 +178,9 @@ async function signalService(command) {
 }
 async function backup() {
     const [{ backupDb }, { PIER_DB }] = await Promise.all([import("./db.js"), import("./paths.js")]);
-    const path = backupDb(PIER_DB);
+    // This tree's version: the updater runs `backup` before npm replaces it, so
+    // it is the release the copy pairs with.
+    const path = backupDb(version, PIER_DB);
     process.stdout.write(path ? `backed up ${path}\n` : `no database yet — nothing to back up.\n`);
 }
 function commandPath(name) {
@@ -191,8 +201,8 @@ async function service(action = "status") {
     const systemdAction = action === "install" || action === "uninstall";
     if (systemdAction && process.platform !== "linux") {
         process.stderr.write(`pier service is systemd, so Linux only — this is ${process.platform}.\n` +
-            `Run "pier" in a terminal, or under whatever supervisor you already use;\n` +
-            `it needs no arguments and keeps its state in $PIER_HOME (~/.pier).\n`);
+            `Run "pier serve" in a terminal, or under whatever supervisor you already\n` +
+            `use; it takes no arguments and keeps its state in $PIER_HOME (~/.pier).\n`);
         process.exit(2);
     }
     switch (action) {
@@ -211,6 +221,9 @@ async function service(action = "status") {
             if (!install({
                 execPath: process.execPath,
                 npmPath: commandPath("npm"),
+                // This command is typed in the operator's shell, so its PATH is the one
+                // they expect a turn's commands to see; the unit records it.
+                shellPath: process.env.PATH,
                 entry: fileURLToPath(new URL("./main.js", import.meta.url)),
                 host,
                 port,

package/dist/db.js

@@ -11,15 +11,16 @@
 // So: one connection, one ordered list of migrations, applied in one
 // transaction before any store exists. A store receives the handle and owns
 // only its queries.
-import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { logger } from "./log.js";
 import { PIER_DB } from "./paths.js";
 const log = logger("db");
-/** Pre-migration snapshots to keep. Three is two upgrades of regret plus one:
+/** Snapshots to keep *of each kind*. Three is two upgrades of regret plus one:
  *  they are full copies of the database, and the one that matters is the
- *  newest. */
+ *  newest. Counted per kind because the two kinds answer different questions —
+ *  a run of releases must not evict the pre-migration copies. */
 const KEEP_BACKUPS = 3;
 /** How long a second process may wait for the write lock before failing. Two
  *  Pier processes on one PIER_HOME contend exactly once — at boot, when both
@@ -147,14 +148,25 @@ let shared;
  */
 export const pierDb = () => (shared ??= openDb(PIER_DB));
 /** A release-level restore point, taken while the service is stopped even when
- * the release has no schema migration. The previous complete copy stays put if
- * writing its replacement fails. */
-export function backupDb(path = PIER_DB) {
+ * the release has no schema migration. The previous complete copies stay put if
+ * writing this one fails.
+ *
+ * `version` is the Pier that produced this database, not the one being
+ * installed: the updater runs this from the tree it is about to replace, and
+ * restoring a database means reinstalling the code that speaks its schema
+ * (`migrate` refuses one from a newer Pier). So the name carries the other half
+ * of the pair. Backing up twice at one version replaces that version's copy —
+ * the pairing is identical, so a second name for it would say nothing. */
+export function backupDb(version, path = PIER_DB) {
     if (!existsSync(path))
         return undefined;
-    const bak = `${path}.release.bak`;
+    // In a filename, so it may not carry a separator or a traversal; a version
+    // this malformed is a broken install, not something to guess at.
+    const safe = version.replaceAll(/[^0-9A-Za-z.+-]/g, "_") || "unknown";
+    const bak = join(backupsDir(path, true), `${basename(path)}.release-${safe}.bak`);
     copyDatabase(path, bak);
     log.info(`pre-update backup: ${bak}`);
+    prune(releases(path));
     return bak;
 }
 /** Open a database, bring it to the current schema, and lock down its files.
@@ -186,9 +198,9 @@ function migrate(db, path, migrations) {
     if (at > target) {
         // Name the snapshot that exists rather than a pattern: the operator is
         // reading this because the service will not start.
-        const newest = path === ":memory:" ? undefined : backups(path)[0]?.file;
+        const newest = path === ":memory:" ? undefined : snapshots(path)[0]?.file;
         throw new Error(`${path} is at schema ${at}, this Pier speaks ${target}: a database is ` +
-            `never downgraded. Restore ${newest ?? `${path}.v*.bak`}, or run the newer Pier.`);
+            `never downgraded. Restore ${newest ?? `a copy from ${backupsDir(path)}`}, or run the newer Pier.`);
     }
     // Version 0 with tables is a database from before versioning existed.
     // Migration 1 assumes an empty file, so the collision it would hit says
@@ -244,7 +256,7 @@ function migrate(db, path, migrations) {
     }
     log.info(locked === 0 ? `schema created at version ${target}` : `schema ${locked} → ${target}`);
     if (path !== ":memory:")
-        prune(path);
+        prune(snapshots(path).map(({ file }) => file));
 }
 /**
  * The copy that exists because `user_version` only counts up: the transaction
@@ -259,7 +271,7 @@ function migrate(db, path, migrations) {
  * ever refers to a finished copy.
  */
 function snapshot(path, at) {
-    const bak = `${path}.v${at}.bak`;
+    const bak = join(backupsDir(path, true), `${basename(path)}.v${at}.bak`);
     copyDatabase(path, bak);
     log.info(`pre-migration backup: ${bak}`);
 }
@@ -276,22 +288,64 @@ function copyDatabase(path, bak) {
     chmodSync(tmp, 0o600); // it holds everything the 0600 database holds
     renameSync(tmp, bak);
 }
-/** Snapshots beside the database, newest schema first. */
-function backups(path) {
+/**
+ * One directory for every copy of this database, `db/backups/`. Beside the
+ * database was fine while there was one snapshot per schema; a restore point
+ * per release turns that into a listing where the live file and its sidecars
+ * are hard to pick out, and "which of these do I not delete" is the wrong
+ * question to make an operator answer under pressure.
+ *
+ * `create` also adopts what an older Pier wrote next to the database, so the
+ * restore procedure names one location instead of two forever.
+ */
+function backupsDir(path, create = false) {
+    const dir = join(dirname(path), "backups");
+    if (!create)
+        return dir;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const prefix = `${basename(path)}.`;
+    for (const name of readdirSync(dirname(path))) {
+        if (!name.startsWith(prefix) || !name.endsWith(".bak"))
+            continue;
+        renameSync(join(dirname(path), name), join(dir, name));
+        log.info(`moved ${name} into ${dir}`);
+    }
+    return dir;
+}
+/** The copies of one kind: `v<schema>` or `release-<version>`. Disjoint
+ *  prefixes, so each kind is counted and pruned on its own. */
+function listBackups(path, kind) {
+    const dir = backupsDir(path);
+    if (!existsSync(dir))
+        return [];
+    const prefix = `${basename(path)}.${kind}`;
+    return readdirSync(dir).filter((name) => name.startsWith(prefix) && name.endsWith(".bak"));
+}
+/** Pre-migration snapshots, newest schema first — the number in the name is an
+ *  ordinal, so it orders them without asking the filesystem. */
+function snapshots(path) {
     const prefix = `${basename(path)}.v`;
-    return readdirSync(dirname(path))
-        .filter((name) => name.startsWith(prefix) && name.endsWith(".bak"))
+    return listBackups(path, "v")
         .map((name) => ({
         version: Number(name.slice(prefix.length, -".bak".length)),
-        file: join(dirname(path), name),
+        file: join(backupsDir(path), name),
     }))
         .filter(({ version }) => Number.isInteger(version))
         .sort((a, b) => b.version - a.version);
 }
-/** Keep the newest few. Nobody restores a database from four upgrades ago, and
- *  every one of these is the size of the whole database. */
-function prune(path) {
-    for (const { file } of backups(path).slice(KEEP_BACKUPS)) {
+/** Release restore points, newest copy first. Ordered by mtime: the name holds
+ *  a Pier version, and comparing those means reimplementing semver here — while
+ *  two updates of one instance are never in flight at the same moment. Legacy
+ *  `pier.db.release.bak` shares the prefix, so it ages out like the rest. */
+function releases(path) {
+    return listBackups(path, "release")
+        .map((name) => join(backupsDir(path), name))
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+}
+/** Keep the newest few, oldest first out. Nobody restores a database from four
+ *  upgrades ago, and every one of these is the size of the whole database. */
+function prune(newestFirst) {
+    for (const file of newestFirst.slice(KEEP_BACKUPS)) {
         rmSync(file, { force: true });
         log.info(`removed superseded backup: ${file}`);
     }
@@ -311,4 +365,7 @@ function restrict(path) {
             chmodSync(file, 0o600);
     }
     chmodSync(dirname(path), 0o700);
+    // Full copies of the same secrets, one directory down.
+    if (existsSync(backupsDir(path)))
+        chmodSync(backupsDir(path), 0o700);
 }

package/dist/main.js

@@ -135,6 +135,16 @@ const startChannels = async () => {
     await deliverLedger(restartLedger, (entry) => channels.notify(entry.channelId, entry.conversationId, entry.note))
         .catch((err) => log.error("restart-note delivery failed", err));
 };
+/** What "reload" means, in one place: the adapters re-read their configuration
+ * and sessions are let go, so the next message re-opens them with the current
+ * skills, extensions, prompts and credentials — all applied at attach, none
+ * stored in a transcript. SIGHUP (`pier reload`) and the Console's Reload are
+ * both this call; `includeWatched` is the only difference, and only because the
+ * Console knows a person asked from the session they are looking at. */
+const reloadInstance = async (includeWatched = false) => {
+    await channels.reload();
+    return router.evictIdle(0, Date.now(), { includeWatched });
+};
 void secrets.unlock().then(startChannels, (err) => log.error("secrets locked — channels not started; unlock from Console → Settings → Security, or repair master.key", err));
 // Replacing Pier is systemd's job, not this process's: the oneshot unit stops
 // the service, snapshots the database, installs and starts it again. Without
@@ -261,6 +271,7 @@ app.route("/", createServer({
     updater,
     // Unlocked from the Console: start the channels boot held back.
     onUnlocked: () => void startChannels(),
+    reload: () => reloadInstance(true),
     backgroundRuns: (id) => tasks.backgroundRuns(id),
 }));
 const port = Number(process.env.PORT ?? 3141);
@@ -327,19 +338,16 @@ process.on("SIGUSR2", () => {
         .catch((err) => log.error("drain failed — shutting down anyway", err))
         .then(() => shutdown(false));
 });
-// Reload without a restart (`pier reload`): adapters re-read their config, and
-// idle sessions are let go so the next message re-opens them with the current
-// skills, extensions and prompts — all applied at attach, none stored in a
-// transcript. Streaming or watched sessions pick the change up at their next
-// natural eviction. Only under systemd (the CLI signals through systemctl):
-// a foreground `pier` keeps SIGHUP's default, dying with its terminal instead
-// of surviving as an orphan that holds the port.
+// Reload without a restart (`pier reload`): reloadInstance above, leaving the
+// sessions someone is watching alone — nobody asked from a browser here.
+// Only under systemd (the CLI signals through systemctl): a foreground `pier
+// serve` keeps SIGHUP's default, dying with its terminal instead of surviving
+// as an orphan that holds the port.
 if (process.env.INVOCATION_ID) {
     process.on("SIGHUP", () => {
         log.info("SIGHUP received, reloading channels and recycling idle sessions");
-        void channels.reload();
-        void router.evictIdle(0)
+        void reloadInstance()
             .then((n) => log.info(`recycled ${String(n)} idle session(s)`))
-            .catch((err) => log.error("session recycle failed", err));
+            .catch((err) => log.error("reload failed", err));
     });
 }

package/dist/service.js

@@ -36,8 +36,22 @@ function quote(value, command = false) {
     return `"${escaped}"`;
 }
 const environment = (key, value) => `Environment=${quote(`${key}=${value}`)}`;
+/** The PATH both units carry: the recorded node first, then the shell that ran
+ * the install (`pier service install` is typed in that shell, so its own PATH
+ * *is* the login one), with the standard directories as a floor.
+ *
+ * Recorded at install rather than sourced from a login shell at start, which
+ * would hand a dotfile the power to decide whether Pier boots and which node
+ * npm installs into. Relative entries are dropped: they would resolve against
+ * WorkingDirectory, which is not where the operator was standing. */
+function pathEnv(execPath, shellPath) {
+    const seen = new Set();
+    return [dirname(execPath), ...(shellPath ?? "").split(":"), "/usr/local/bin", "/usr/bin", "/bin"]
+        .filter((dir) => dir.startsWith("/") && !/[\0\r\n]/.test(dir) && !seen.has(dir) && seen.add(dir))
+        .join(":");
+}
 export function renderUnit(options) {
-    const { execPath, entry, host, port, pierHome } = options;
+    const { execPath, entry, host, port, pierHome, shellPath } = options;
     return `[Unit]
 Description=Pier — agent workspace
 Documentation=https://github.com/timqi/pier
@@ -51,6 +65,10 @@ WorkingDirectory=%h
 # that installed Pier is usually not on it.
 ExecStart=${quote(execPath, true)} ${quote(entry, true)}
 ${environment("NODE_ENV", "production")}
+# Inherited by every command a turn runs, which is why it is here and not just
+# in the updater: an agent typing "npm test" on systemd's minimal PATH would be
+# told node does not exist on a machine that installed Pier with it.
+${environment("PATH", pathEnv(execPath, shellPath))}
 # Loopback by default. Put a reverse proxy in front before widening this —
 # whoever reaches this port can drive an agent that runs a shell.
 ${environment("HOST", host)}
@@ -89,7 +107,7 @@ function legacyOptions(home) {
 /** A separate cgroup stops Pier, takes a consistent backup, updates the exact
  * npm installation recorded at install time, and always starts Pier again. */
 export function renderUpdateUnit(options) {
-    const { execPath, npmPath, entry, pierHome } = options;
+    const { execPath, npmPath, entry, pierHome, shellPath } = options;
     const cli = join(dirname(entry), "cli.js");
     return `[Unit]
 Description=Update Pier to the latest published version
@@ -97,10 +115,14 @@ Documentation=https://github.com/timqi/pier
 
 [Service]
 Type=oneshot
+# The absolute node below answers npm's own shebang and nothing else: a
+# dependency's postinstall runs as "sh -c node scripts/postinstall", which
+# resolves node from PATH, and systemd's minimal PATH has no fnm/nvm node —
+# the install then dies with "node: not found" with the tree half written.
+${environment("PATH", pathEnv(execPath, shellPath))}
 ${pierHome ? `${environment("PIER_HOME", pierHome)}\n` : ""}ExecStart=systemctl --user stop ${UNIT_NAME}
 ExecStart=${quote(execPath, true)} ${quote(cli, true)} backup
-# npm runs under the recorded node: its shebang needs a node on PATH, and
-# systemd's minimal PATH has none for fnm/nvm installs.
+# npm runs under the recorded node: its shebang needs a node on PATH too.
 ExecStart=${quote(execPath, true)} ${quote(npmPath, true)} install -g @timqi/pier@latest
 # ExecStopPost runs on success and failure, so a failed backup or npm install
 # does not leave the previously working service stopped.
@@ -278,7 +300,7 @@ export function startUpdate(options) {
     if (!run(["systemctl", "--user", "start", "--no-block", UPDATE_UNIT_NAME]))
         return "failed";
     say(`updating in the background — follow it with: journalctl --user -u ${UPDATE_UNIT_NAME} -f`);
-    say(`Pier stops, snapshots pier.db.release.bak, installs, then starts again.`);
+    say(`Pier stops, snapshots the database into db/backups/, installs, then starts again.`);
     return "started";
 }
 export function uninstall(home = homedir(), say = console.log, exec) {

package/dist/web/explorer.js

@@ -92,13 +92,13 @@ export function registerExplorerRoutes(app) {
             return { name: line.slice(0, tab), subject: line.slice(tab + 1) };
         });
         // Unit/record separators, because a body is multi-line by nature.
-        const commits = (await git(root, "log", "-20", "--format=%h\u001f%at\u001f%an\u001f%s\u001f%b\u001e"))
+        const commits = (await git(root, "log", "-20", "--format=%h\u001f%at\u001f%an\u001f%ae\u001f%s\u001f%b\u001e"))
             .split("\u001e")
             .map((r) => r.trimStart())
             .filter(Boolean)
             .map((r) => {
-            const [hash = "", at = "", author = "", subject = "", body = ""] = r.split("\u001f");
-            return { hash, at: Number(at) * 1000, author, subject, body: body.trim() };
+            const [hash = "", at = "", author = "", email = "", subject = "", body = ""] = r.split("\u001f");
+            return { hash, at: Number(at) * 1000, author, email, subject, body: body.trim() };
         });
         return c.json({ branch, refs, commits });
     });