@fapost/jig-ui 0.3.1-next.62 → 0.3.1-next.64

package/dist/args.js

@@ -1,13 +1,17 @@
 import { parseArgs } from 'node:util';
 export const DEFAULT_PORT = 4870;
+const SUBCOMMANDS = ['start', 'stop', 'status', 'open', 'serve'];
+/** Subcommands that listen on a port; the others only talk to the instance that does. */
+const TAKES_PORT = new Set(['run', 'start', 'serve']);
 /** Parses the command line (without the node and script entries). Pure: it never exits or prints. */
 export function parseCliArgs(argv) {
+    let positionals;
     let values;
     try {
-        ({ values } = parseArgs({
+        ({ values, positionals } = parseArgs({
             args: argv,
             strict: true,
-            allowPositionals: false,
+            allowPositionals: true,
             options: {
                 port: { type: 'string' },
                 'no-open': { type: 'boolean' },
@@ -23,12 +27,35 @@ export function parseCliArgs(argv) {
         return { kind: 'help' };
     if (values.version)
         return { kind: 'version' };
-    const open = !values['no-open'];
-    if (values.port === undefined)
-        return { kind: 'run', port: DEFAULT_PORT, open };
-    const port = /^\d+$/.test(values.port) ? Number(values.port) : Number.NaN;
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        return { kind: 'error', message: `Invalid --port value: ${values.port}. Use a number from 1 to 65535.` };
+    const [name, ...rest] = positionals;
+    if (rest.length > 0)
+        return { kind: 'error', message: `Unexpected argument: ${rest[0]}` };
+    if (name !== undefined && !SUBCOMMANDS.includes(name)) {
+        return { kind: 'error', message: `Unknown command: ${name}. Run jig-ui --help.` };
+    }
+    const command = name ?? 'run';
+    if (values.port !== undefined && !TAKES_PORT.has(command)) {
+        return { kind: 'error', message: `--port does not apply to ${command}.` };
+    }
+    if (values['no-open'] && command !== 'run') {
+        return { kind: 'error', message: `--no-open does not apply to ${command}.` };
+    }
+    let port = DEFAULT_PORT;
+    if (values.port !== undefined) {
+        port = /^\d+$/.test(values.port) ? Number(values.port) : Number.NaN;
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            return { kind: 'error', message: `Invalid --port value: ${values.port}. Use a number from 1 to 65535.` };
+        }
+    }
+    switch (command) {
+        case 'start':
+        case 'serve':
+            return { kind: command, port };
+        case 'stop':
+        case 'status':
+        case 'open':
+            return { kind: command };
+        default:
+            return { kind: 'run', port, open: !values['no-open'] };
     }
-    return { kind: 'run', port, open };
 }

package/dist/http/app.js

@@ -79,9 +79,16 @@ function upgradeRefused(c, code) {
  * The API, chained so that its type carries every route's answers: the page derives its types
  * from `AppType` and never declares them a second time.
  */
-function apiRoutes(source, version) {
+function apiRoutes(source, version, stop) {
     return (new Hono()
         .get('/api/instance', (c) => c.json({ version }, 200))
+        .post('/api/instance/stop', (c) => {
+        if (!stop)
+            return refuse(c, 404, 'not-found', 'This instance cannot be stopped from here.');
+        // After the reply is written, or the caller sees a cut connection instead of the 202.
+        setTimeout(stop, 50);
+        return c.json({ stopping: true }, 202);
+    })
         .get('/api/workspace', async (c) => c.json({ projects: await source.workspace(), machine: source.machine() }, 200))
         // Moves this machine's Jig to its newest release and answers once it has: a git fetch, not minutes.
         .post('/api/self-update', async (c) => {
@@ -283,7 +290,7 @@ function apiRoutes(source, version) {
         }
     })));
 }
-export function createApp({ port, token, source, version = readPackageVersion(), webRoot = DEFAULT_WEB_ROOT }) {
+export function createApp({ port, token, source, version = readPackageVersion(), webRoot = DEFAULT_WEB_ROOT, stop }) {
     const app = new Hono();
     // Before the guard, so its refusals carry them too; HSTS means nothing on http://127.0.0.1.
     app.use(secureHeaders({ strictTransportSecurity: false }));
@@ -299,7 +306,7 @@ export function createApp({ port, token, source, version = readPackageVersion(),
         console.error(error);
         return refuse(c, 500, 'internal', 'Jig UI hit an error it did not expect; its terminal says what.');
     });
-    app.route('/', apiRoutes(source, version));
+    app.route('/', apiRoutes(source, version, stop));
     app.all('/api/*', (c) => c.json({ error: 'not found' }, 404));
     if (existsSync(join(webRoot, 'index.html'))) {
         app.use('/*', serveStatic({ root: webRoot }));

package/dist/main.js

@@ -8,16 +8,32 @@ import { openBrowser } from './open-browser.js';
 import { configDir } from './registry/config-dir.js';
 import { connectThrough, probeInstance, readInstance, removeInstance, writeInstance } from './registry/instance.js';
 import { mainCheckout } from './source/checkout.js';
+import { instanceStatus, startInstance, stopInstance } from './service.js';
 import { localSource } from './source/local.js';
 const HOST = '127.0.0.1';
 const HELP = `Usage: jig-ui [options]
+       jig-ui start [--port <n>]
+       jig-ui stop | status | open
+
+Run without a command, Jig UI runs in this terminal and opens the browser.
+
+Commands:
+  start          Start Jig UI in the background
+  stop           Stop the running Jig UI
+  status         Say whether Jig UI is running (exit code 3 when it is not)
+  open           Open the running Jig UI in the browser
+  serve          Run in this terminal without a browser or a folder: what start runs
 
 Options:
-  --port <n>     Port to listen on (default 4870)
-  --no-open      Print the link instead of opening the browser
+  --port <n>     Port to listen on (default 4870); run, start and serve
+  --no-open      Print the link instead of opening the browser; run only
   -v, --version  Print the version and exit
   -h, --help     Print this help and exit
 `;
+/** The exit code of `status` and `open` when Jig UI is not running. */
+const NOT_RUNNING = 3;
+/** An instance whose port stays silent: maybe busy, so nothing is removed or started in its place. */
+const silent = ({ port, pid }) => `Jig UI on port ${port} (pid ${pid}) does not answer. Try again; if it stays silent, end that process yourself.`;
 function fail(message) {
     console.error(message);
     process.exit(1);
@@ -71,36 +87,40 @@ async function winnerOfRace(dir) {
     }
     return undefined;
 }
-export async function main() {
-    const command = parseCliArgs(process.argv.slice(2));
-    if (command.kind === 'error')
-        fail(command.message);
-    if (command.kind === 'help') {
-        process.stdout.write(HELP);
-        return;
-    }
-    if (command.kind === 'version') {
-        console.log(readPackageVersion());
-        return;
-    }
-    const { port, open } = command;
-    const dir = configDir(process.env, process.platform, homedir());
-    const place = await here();
+/**
+ * Runs the server in this process. `run` also connects the folder and opens the browser; `serve`
+ * (what `start` runs in the background) does neither and keeps quiet about Ctrl+C.
+ */
+async function runServer(command, dir) {
+    const { port } = command;
+    const foreground = command.kind === 'run';
+    const open = foreground && command.open;
+    const place = foreground ? await here() : undefined;
     const running = await runningInstance(dir);
     if (running) {
         console.log(`Jig UI is already running on port ${running.port}.`);
         // ponytail: a --port equal to the default is indistinguishable from no flag; no note then.
         if (port !== running.port && port !== DEFAULT_PORT)
             console.log(`--port ${port} is ignored.`);
-        await show(running, open, dir, await connectHere(running, place));
+        if (foreground)
+            await show(running, open, dir, await connectHere(running, place));
         return;
     }
     const version = readPackageVersion();
     const token = randomBytes(32).toString('base64url');
-    const server = serve({ fetch: createApp({ port, token, source: localSource(dir), version }).fetch, hostname: HOST, port }, () => {
+    const shutdown = () => {
+        void removeInstance(dir, token).finally(() => {
+            server.close(() => process.exit(0));
+            if ('closeAllConnections' in server)
+                server.closeAllConnections();
+        });
+    };
+    const server = serve({ fetch: createApp({ port, token, source: localSource(dir), version, stop: shutdown }).fetch, hostname: HOST, port }, () => {
         void (async () => {
             await writeInstance(dir, { port, token, pid: process.pid, version });
             console.log(`Jig UI ${version} is running at http://${HOST}:${port}/`);
+            if (!foreground)
+                return;
             await show({ port, token }, open, dir, await connectHere({ port, token }, place));
             console.log('Press Ctrl+C to stop.');
         })().catch((error) => fail(`Could not start: ${error instanceof Error ? error.message : String(error)}`));
@@ -113,17 +133,104 @@ export async function main() {
             if (!winner)
                 fail(`Port ${port} is already in use. Stop the other process or choose another port with --port.`);
             console.log(`Jig UI is already running on port ${winner.port}.`);
-            await show(winner, open, dir, await connectHere(winner, place));
+            if (foreground)
+                await show(winner, open, dir, await connectHere(winner, place));
             process.exit(0);
         });
     });
-    const shutdown = () => {
-        void removeInstance(dir, token).finally(() => {
-            server.close(() => process.exit(0));
-            if ('closeAllConnections' in server)
-                server.closeAllConnections();
-        });
-    };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+async function startBackground(port, dir) {
+    const result = await startInstance(dir, port);
+    if (result.kind === 'failed') {
+        console.error(`Could not start Jig UI. The end of ${result.log}:\n${result.tail}`);
+        process.exit(1);
+    }
+    if (result.kind === 'not-answering')
+        fail(silent(result.info));
+    if (result.kind === 'already-running') {
+        console.log(`Jig UI is already running on port ${result.info.port}.`);
+        if (port !== result.info.port && port !== DEFAULT_PORT)
+            console.log(`--port ${port} is ignored.`);
+        console.log(`Open it at ${link(result.info)}`);
+        return;
+    }
+    console.log(`Jig UI ${result.info.version} is running at http://${HOST}:${result.info.port}/ in the background.`);
+    console.log(`Open it at ${link(result.info)}`);
+    console.log(`Log: ${result.log}`);
+}
+async function stopBackground(dir) {
+    const result = await stopInstance(dir);
+    switch (result.kind) {
+        case 'not-running':
+            console.log('Jig UI is not running.');
+            return;
+        case 'stale':
+            console.log(`Jig UI is not running: the file of an instance on port ${result.info.port} was left behind and is removed. No process was signalled.`);
+            return;
+        case 'stopped':
+            console.log(`Stopped Jig UI on port ${result.info.port}.`);
+            return;
+        case 'not-answering':
+            console.error(silent(result.info));
+            process.exitCode = 1;
+            return;
+        case 'timeout':
+            console.error(`Jig UI on port ${result.info.port} (pid ${result.info.pid}) did not stop in time.`);
+            process.exitCode = 1;
+    }
+}
+async function statusOf(dir) {
+    const status = await instanceStatus(dir);
+    if (status.kind === 'running') {
+        const { info } = status;
+        console.log(`Jig UI ${info.version} is running at http://${HOST}:${info.port}/ (pid ${info.pid}).`);
+        console.log(`Open it at ${link(info)}`);
+        return;
+    }
+    if (status.kind === 'not-answering') {
+        console.error(silent(status.info));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(status.kind === 'stale'
+        ? `Jig UI is not running; the file of an instance on port ${status.info.port} was left behind. jig-ui stop removes it.`
+        : 'Jig UI is not running. Start it with jig-ui start.');
+    process.exitCode = NOT_RUNNING;
+}
+async function openRunning(dir) {
+    const status = await instanceStatus(dir);
+    if (status.kind === 'running')
+        return show(status.info, true, dir);
+    if (status.kind === 'not-answering')
+        fail(silent(status.info));
+    console.log('Jig UI is not running. Start it with jig-ui start.');
+    process.exitCode = NOT_RUNNING;
+}
+export async function main() {
+    const command = parseCliArgs(process.argv.slice(2));
+    if (command.kind === 'error')
+        fail(command.message);
+    if (command.kind === 'help') {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (command.kind === 'version') {
+        console.log(readPackageVersion());
+        return;
+    }
+    const dir = configDir(process.env, process.platform, homedir());
+    switch (command.kind) {
+        case 'start':
+            return startBackground(command.port, dir);
+        case 'stop':
+            return stopBackground(dir);
+        case 'status':
+            return statusOf(dir);
+        case 'open':
+            return openRunning(dir);
+        default:
+            return runServer(command, dir);
+    }
+}

package/dist/registry/instance.js

@@ -35,21 +35,37 @@ export async function removeInstance(dir, token) {
     await rm(join(dir, OPEN_FILE), { force: true });
     await rm(join(dir, FILE), { force: true });
 }
+const causeCode = (error) => error.cause?.code;
+/** A connection refused outright: nothing listens on the port. */
+const refused = (error) => causeCode(error) === 'ECONNREFUSED';
+export async function askInstance(info, timeoutMs = 1000) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${info.port}/api/instance`, {
+                headers: { cookie: `${cookieName(info.port)}=${info.token}` },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            // An unread body holds the connection, and the next probe of a stop's wait would queue behind it.
+            await res.body?.cancel();
+            return res.ok ? 'up' : 'gone';
+        }
+        catch (error) {
+            if (refused(error))
+                return 'gone';
+            // A kept-alive connection to a server that has since stopped breaks (reset, or closed as it
+            // is used, as on Linux); only a timeout means silence, and a new connection tells the rest.
+            if (error.name !== 'TimeoutError' && attempt === 0)
+                continue;
+            return 'silent';
+        }
+    }
+}
 /** True when an instance answers on its port with its token; a crash leaves the file behind. */
 export async function probeInstance(info, timeoutMs = 1000) {
-    try {
-        const res = await fetch(`http://127.0.0.1:${info.port}/api/instance`, {
-            headers: { cookie: `${cookieName(info.port)}=${info.token}` },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
+    return (await askInstance(info, timeoutMs)) === 'up';
 }
 // An instance before 0.2.0 answers a failure it did not foresee in plain text: neither of these.
-const Answer = z.union([
+const Reply = z.union([
     z.object({ project: z.object({ id: z.string() }) }),
     z.object({ error: z.object({ code: z.string(), message: z.string() }) }),
 ]);
@@ -62,7 +78,7 @@ export async function connectThrough(info, path, timeoutMs = 15_000) {
             body: JSON.stringify({ path }),
             signal: AbortSignal.timeout(timeoutMs),
         });
-        const body = Answer.safeParse(await res.json().catch(() => undefined)).data;
+        const body = Reply.safeParse(await res.json().catch(() => undefined)).data;
         if (body && 'project' in body)
             return { id: body.project.id, created: res.status === 201 };
         return body?.error ?? { code: 'unexpected', message: `Jig UI answered ${res.status}.` };
@@ -71,3 +87,19 @@ export async function connectThrough(info, path, timeoutMs = 15_000) {
         return { code: 'unreachable', message: error instanceof Error ? error.message : String(error) };
     }
 }
+/** Asks the instance to shut down, as `connectThrough` asks it to connect: the token proves the instance is ours. */
+export async function requestStop(info, timeoutMs = 5000) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${info.port}/api/instance/stop`, {
+            method: 'POST',
+            headers: { cookie: `${cookieName(info.port)}=${info.token}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        await res.body?.cancel();
+        return res.status === 404 ? 'unsupported' : 'stopping';
+    }
+    catch (error) {
+        // A timeout or reset after the request was sent may still be a server going down; a refusal is not.
+        return refused(error) ? 'unreachable' : 'stopping';
+    }
+}

package/dist/service.js

@@ -0,0 +1,130 @@
+import { spawn as spawnProcess } from 'node:child_process';
+import { mkdir, open, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { askInstance, readInstance, removeInstance, requestStop, } from './registry/instance.js';
+/** The log of the background instance; overwritten at each start, but it grows while the instance runs (task server-log-rotation). */
+export const LOG_FILE = 'server.log';
+/** How long the instance gets to answer a probe; one that stays silent is busy, never stale. */
+const PROBE_MS = 3000;
+/** How long a start waits for the new instance, and a stop for the old one to go. */
+const WAIT_MS = 10_000;
+const POLL_MS = 100;
+const TAIL_LINES = 20;
+/** The program that runs the instance: this very CLI, next to this file in `dist` and in `server`. */
+const CLI_PATH = fileURLToPath(new URL('./cli.js', import.meta.url));
+export const realDeps = {
+    probe: askInstance,
+    requestStop: (info) => requestStop(info),
+    kill: (pid, signal) => process.kill(pid, signal),
+    spawn(command, args, { cwd, fd }) {
+        const child = spawnProcess(command, args, { detached: true, stdio: ['ignore', fd, fd], windowsHide: true, cwd });
+        const exit = new Promise((resolve) => {
+            // A process that cannot start never exits and writes no log: its error is all there is to say.
+            child.on('error', (error) => resolve({ code: -1, error: error.message }));
+            child.on('exit', (code) => resolve({ code }));
+        });
+        return { exit, unref: () => child.unref(), kill: () => child.kill() };
+    },
+    delay: (ms) => sleep(ms),
+    now: () => Date.now(),
+};
+/**
+ * Reads the instance file and asks the instance. A file whose port refuses, or answers as someone
+ * else, is stale; one whose port stays silent is `not-answering`: maybe alive and busy. It deletes nothing.
+ */
+export async function instanceStatus(dir, deps = realDeps) {
+    const info = await readInstance(dir);
+    if (!info)
+        return { kind: 'not-running' };
+    const answer = await deps.probe(info, PROBE_MS);
+    return { kind: answer === 'up' ? 'running' : answer === 'gone' ? 'stale' : 'not-answering', info };
+}
+async function logTail(log) {
+    try {
+        return (await readFile(log, 'utf8')).trimEnd().split('\n').slice(-TAIL_LINES).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Starts the instance in the background and waits until it answers. The child is the CLI itself
+ * as `serve`: detached from this terminal, its output in the log, its working directory the
+ * config directory, so it holds no folder of the person's.
+ */
+export async function startInstance(dir, port, deps = realDeps) {
+    const status = await instanceStatus(dir, deps);
+    if (status.kind === 'running')
+        return { kind: 'already-running', info: status.info };
+    // A second server would only lose the port to it, and the log would be overwritten for nothing.
+    if (status.kind === 'not-answering')
+        return status;
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const log = join(dir, LOG_FILE);
+    const handle = await open(log, 'w', 0o600);
+    let child;
+    try {
+        child = deps.spawn(process.execPath, [CLI_PATH, 'serve', '--port', String(port)], { cwd: dir, fd: handle.fd });
+    }
+    finally {
+        // The child has its own copy of the descriptor.
+        await handle.close();
+    }
+    child.unref();
+    let ended;
+    void child.exit.then((value) => {
+        ended = value;
+    });
+    const deadline = deps.now() + WAIT_MS;
+    while (deps.now() < deadline) {
+        await deps.delay(POLL_MS);
+        const info = await readInstance(dir);
+        if (info && (await deps.probe(info, PROBE_MS)) === 'up')
+            return { kind: 'started', info, log };
+        // A child that exited with 0 found another instance already there: the next poll sees it.
+        if (ended && ended.code !== 0)
+            break;
+    }
+    // Too slow is a failure too: end the child rather than let it come up after we said it did not.
+    if (!ended)
+        child.kill();
+    return { kind: 'failed', log, tail: ended?.error ?? (await logTail(log)) };
+}
+/**
+ * Stops the instance the file names. An instance that answers is asked over HTTP, with its token:
+ * that works on every system and cannot hit a process that merely reused the pid. A stale file
+ * only goes away, and no signal is sent, because its pid may belong to anything by now. A silent
+ * port changes nothing: removing the file of a busy instance would leave it running unseen.
+ */
+export async function stopInstance(dir, deps = realDeps) {
+    const status = await instanceStatus(dir, deps);
+    if (status.kind === 'not-running' || status.kind === 'not-answering')
+        return status;
+    const { info } = status;
+    if (status.kind === 'stale') {
+        await removeInstance(dir, info.token);
+        return status;
+    }
+    const requested = await deps.requestStop(info);
+    // An instance from before the endpoint existed: the probe just proved that its pid is the one that answers.
+    if (requested === 'unsupported') {
+        try {
+            deps.kill(info.pid, 'SIGTERM');
+        }
+        catch {
+            // Gone between the probe and the signal: the wait below sees it.
+        }
+    }
+    const deadline = deps.now() + WAIT_MS;
+    while (deps.now() < deadline) {
+        if ((await deps.probe(info, PROBE_MS)) === 'gone') {
+            // The server removes its files itself; this covers a hard exit.
+            await removeInstance(dir, info.token);
+            return { kind: 'stopped', info };
+        }
+        await deps.delay(POLL_MS);
+    }
+    return { kind: 'timeout', info };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fapost/jig-ui",
-  "version": "0.3.1-next.62",
+  "version": "0.3.1-next.64",
   "description": "A local web interface for Jig, the agent SDLC framework.",
   "license": "MIT",
   "type": "module",