@fapost/jig-ui 0.1.0-next.8 → 0.1.0

package/dist/board/columns.js

@@ -0,0 +1,29 @@
+/** The board's order: what waits for the person first, then what moves, what is done, what is not begun, what is set aside. */
+const COLUMNS = [
+    { id: 'needs-you', title: 'Needs you' },
+    { id: 'in-progress', title: 'In progress' },
+    { id: 'ready', title: 'Ready' },
+    { id: 'backlog', title: 'Backlog' },
+    { id: 'paused', title: 'Paused' },
+];
+/** Where a task stands, from Jig's state alone; the first rule that fits wins. */
+export function columnOf(task) {
+    if (task.paused)
+        return 'paused';
+    if (!task.started)
+        return 'backlog';
+    if (task.gate === 'waiting' || task.gate === 'changed' || task.autopilot === 'stopped')
+        return 'needs-you';
+    if (task.status === 'ready')
+        return 'ready';
+    return 'in-progress';
+}
+/** The column a task sits in, with its title. */
+export function placeOf(task) {
+    const id = columnOf(task);
+    return { id, title: COLUMNS.find((c) => c.id === id)?.title ?? id };
+}
+/** The board: every column, in a fixed order, its cards in the order Jig listed them. Computed on every read, never stored. */
+export function columns(tasks) {
+    return COLUMNS.map((c) => ({ ...c, cards: tasks.filter((t) => columnOf(t) === c.id) }));
+}

package/dist/http/app.js

@@ -4,8 +4,9 @@ import { isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { Hono } from 'hono';
-import { addProject, readProjects, RegistryUnreadable, removeProject } from '../registry/projects.js';
-import { connectable, projectState } from '../source/local.js';
+import { streamSSE } from 'hono/streaming';
+import { columns, placeOf } from '../board/columns.js';
+import { RegistryUnreadable } from '../source/project-source.js';
 import { localOnly, tokenAccess } from './access.js';
 /**
  * Reads the version from the package's own package.json. The relative path is the same from
@@ -18,6 +19,8 @@ export function readPackageVersion() {
 }
 /** The built page: `dist/web`, next to `dist/http` where this file runs when published. */
 export const DEFAULT_WEB_ROOT = fileURLToPath(new URL('../web', import.meta.url));
+/** How often an idle stream sends a comment, so a closed tab is noticed and its subscription ends. */
+const PING_MS = 30_000;
 const refuse = (c, status, code, message) => c.json({ error: { code, message } }, status);
 /** The path the person typed, absolute; `~/` stands for their home. */
 function absolute(path) {
@@ -26,7 +29,7 @@ function absolute(path) {
     const expanded = path.trim().replace(/^~(?=$|[\\/])/, homedir());
     return isAbsolute(expanded) ? expanded : undefined;
 }
-export function createApp({ port, token, configDir, version = readPackageVersion(), webRoot = DEFAULT_WEB_ROOT }) {
+export function createApp({ port, token, source, version = readPackageVersion(), webRoot = DEFAULT_WEB_ROOT }) {
     const app = new Hono();
     app.use(localOnly(port));
     app.use(tokenAccess({ port, token }));
@@ -37,27 +40,60 @@ export function createApp({ port, token, configDir, version = readPackageVersion
         return c.text('Internal Server Error', 500);
     });
     app.get('/api/instance', (c) => c.json({ version }));
-    app.get('/api/projects', async (c) => {
-        const projects = await readProjects(configDir);
-        return c.json({ projects: await Promise.all(projects.map(projectState)) });
+    app.get('/api/workspace', async (c) => c.json({ projects: await source.workspace() }));
+    app.get('/api/projects/:id/board', async (c) => {
+        const id = c.req.param('id');
+        const read = await source.tasks(id);
+        if (read === undefined)
+            return refuse(c, 404, 'not-connected', 'No connected project has this id.');
+        if (read.state !== 'ready')
+            return c.json({ board: read });
+        return c.json({ board: { id, state: 'ready', columns: columns(read.tasks), finished: read.finished } });
+    });
+    app.get('/api/projects/:id/tasks/:task', async (c) => {
+        const read = await source.task(c.req.param('id'), c.req.param('task'));
+        if (read === undefined)
+            return refuse(c, 404, 'not-connected', 'No connected project has this id.');
+        if (read.state !== 'ready')
+            return c.json({ task: read });
+        if (read.task === null)
+            return refuse(c, 404, 'not-found', 'This project has no live task with this id.');
+        return c.json({ task: { state: 'ready', ...read.task, column: placeOf(read.task) } });
+    });
+    app.get('/api/projects/:id/specs', async (c) => {
+        const read = await source.specs(c.req.param('id'));
+        if (read === undefined)
+            return refuse(c, 404, 'not-connected', 'No connected project has this id.');
+        return c.json({ specs: read });
     });
     app.post('/api/projects', async (c) => {
         const body = await c.req.json().catch(() => undefined);
         const path = absolute(body?.path);
         if (path === undefined)
             return refuse(c, 422, 'usage', 'Give the absolute path of a project.');
-        const found = await connectable(path);
-        if ('code' in found)
-            return refuse(c, 422, found.code, found.message);
-        const { project, created } = await addProject(configDir, found.root);
-        return c.json({ project: await projectState(project) }, created ? 201 : 200);
+        const result = await source.connect(path);
+        if ('code' in result)
+            return refuse(c, 422, result.code, result.message);
+        return c.json({ project: result.project }, result.created ? 201 : 200);
     });
     app.delete('/api/projects/:id', async (c) => {
-        if (!(await removeProject(configDir, c.req.param('id')))) {
+        if (!(await source.disconnect(c.req.param('id')))) {
             return refuse(c, 404, 'not-connected', 'No connected project has this id.');
         }
         return c.body(null, 204);
     });
+    // A signal, not data: the page re-fetches what it shows (adr-20261014-project-source-port-keeps-hosting-open).
+    app.get('/api/events', (c) => streamSSE(c, async (stream) => {
+        const unsubscribe = source.subscribe(({ id, revision }) => {
+            void stream.writeSSE({ event: 'changed', data: JSON.stringify({ project: id, revision }) });
+        });
+        stream.onAbort(unsubscribe);
+        while (!stream.aborted) {
+            await stream.sleep(PING_MS);
+            if (!stream.aborted)
+                await stream.write(': ping\n\n');
+        }
+    }));
     app.all('/api/*', (c) => c.json({ error: 'not found' }, 404));
     if (existsSync(join(webRoot, 'index.html'))) {
         app.use('/*', serveStatic({ root: webRoot }));

package/dist/jig/client.js

@@ -7,6 +7,16 @@ const run = promisify(execFile);
 export const MIN_JIG_VERSION = '0.29.0';
 const SCRIPT = join('.ai', 'scripts', 'jig');
 const TIMEOUT_MS = 10_000;
+/** The directory whose changes may change what Jig reports: the main checkout's `.ai/`. */
+export const watchDir = (root) => join(root, '.ai');
+/**
+ * True for a path under `.ai/` (with `/` separators) that Jig writes while it only reads — its
+ * records of what it is doing under `runtime/` — so a change there is no sign of a change, and
+ * watching it would make every read trigger the next. `runtime/revision/` is where the clone's
+ * revision rises on each Jig write, and stays a sign. Jig names no such path in its contract
+ * (Jig 0.29.0, found by watching which files its reads touch).
+ */
+export const writtenByReads = (path) => (path === 'runtime' || path.startsWith('runtime/')) && !path.startsWith('runtime/revision');
 /**
  * The bash that runs `.ai/scripts/jig`. On Windows it is Git's, found next to git itself
  * (`<git>/mingw64/libexec/git-core` → `<git>/bin/bash.exe`): a `bash` on PATH may be WSL's.
@@ -34,6 +44,203 @@ export async function jigVersion(root, platform = process.platform) {
         throw new Error('jig --version did not print a version');
     return match[1];
 }
+/** Why a JSON read was refused: Jig's failure code (`failed` for one this Jig UI does not know, or a shape it cannot read). */
+export class JigRefusal extends Error {
+    code;
+    constructor(code) {
+        super(`jig refused: ${code}`);
+        this.code = code;
+    }
+}
+const CODES = new Set(['usage', 'not-a-repository', 'not-initialised', 'failed']);
+/** Jig answered in a shape this Jig UI does not read: a Jig newer than the contract its tests pin. */
+export class JigShapeError extends Error {
+    constructor() {
+        super('jig answered in a shape this Jig UI does not read');
+    }
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isString = (v) => typeof v === 'string';
+const isNullableString = (v) => v === null || typeof v === 'string';
+/**
+ * Runs a `--json` read and returns its `data` and the clone's revision. Jig's refusal throws
+ * JigRefusal, as does output that is no JSON at all (a crash); an envelope of another shape throws
+ * JigShapeError.
+ */
+async function readJson(root, args, platform) {
+    let stdout;
+    try {
+        stdout = await jig(root, [...args, '--json'], platform);
+    }
+    catch (error) {
+        // A refusal is an envelope too, printed before the non-zero exit.
+        stdout = error.stdout ?? '';
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(stdout);
+    }
+    catch {
+        throw new JigRefusal('failed');
+    }
+    if (!isObject(envelope) || envelope.schema !== 1 || typeof envelope.revision !== 'number')
+        throw new JigShapeError();
+    if (isObject(envelope.error)) {
+        const code = envelope.error.code;
+        throw new JigRefusal(isString(code) && CODES.has(code) ? code : 'failed');
+    }
+    if (!isObject(envelope.data))
+        throw new JigShapeError();
+    return { revision: envelope.revision, data: envelope.data };
+}
+const isAttention = (v) => isObject(v) &&
+    isString(v.kind) &&
+    isObject(v.subject) &&
+    isString(v.subject.type) &&
+    isNullableString(v.subject.id) &&
+    Array.isArray(v.tasks) &&
+    v.tasks.every(isString) &&
+    isString(v.title) &&
+    isNullableString(v.detail) &&
+    isString(v.todo) &&
+    isNullableString(v.url);
+/** What needs the person in a project, most urgent first, and whether the pull request facts behind it may be missing. */
+export async function readStatus(root, platform = process.platform) {
+    const { revision, data } = await readJson(root, ['status'], platform);
+    const { attention, housekeeping } = data;
+    if (!Array.isArray(attention) || !attention.every(isAttention))
+        throw new JigShapeError();
+    if (housekeeping !== null && !(isObject(housekeeping) && typeof housekeeping.stale === 'boolean'))
+        throw new JigShapeError();
+    return {
+        revision,
+        attention: attention.map(({ kind, subject, tasks, title, detail, todo, url }) => ({
+            kind,
+            subject: { type: subject.type, id: subject.id },
+            tasks: [...tasks],
+            title,
+            detail,
+            todo,
+            url,
+        })),
+        housekeepingStale: housekeeping?.stale === true,
+    };
+}
+const STATUSES = new Set(['active', 'ready', 'consolidated', 'abandoned']);
+/** Jig's action ids this Jig UI knows; Jig may add ids without raising `schema`, and a consumer ignores those. */
+const ACTIONS = new Set(['start', 'pause', 'resume', 'approve-gate', 'answer-stop', 'set-class', 'ship', 'close', 'abandon', 'reopen']);
+const nullableStrings = (v, keys) => keys.every((k) => isNullableString(v[k]));
+const isGate = (v) => v === null || (isObject(v) && isString(v.state) && isNullableString(v.by));
+const isAutopilot = (v) => v === null || (isObject(v) && isString(v.state) && nullableStrings(v, ['mode', 'stage', 'stage_at', 'stop_reason', 'stop_at', 'phase']));
+const isPullRequest = (v) => v === null || (isObject(v) && isString(v.url) && nullableStrings(v, ['state', 'ci', 'fetched_at']));
+const isWorktree = (v) => v === null || (isObject(v) && typeof v.uncommitted === 'number');
+const isAction = (v) => isObject(v) && isString(v.id) && isString(v.command) && typeof v.offered === 'boolean' && isNullableString(v.reason);
+const isTaskRow = (v) => isObject(v) &&
+    isString(v.id) &&
+    isString(v.status) &&
+    STATUSES.has(v.status) &&
+    nullableStrings(v, ['class', 'issue', 'goal', 'created_at', 'updated_at', 'branch']) &&
+    typeof v.knowledge_consolidated === 'boolean' &&
+    typeof v.paused === 'boolean' &&
+    isString(v.base_branch) &&
+    isWorktree(v.worktree) &&
+    isGate(v.gate) &&
+    isAutopilot(v.autopilot) &&
+    isPullRequest(v.pull_request) &&
+    Array.isArray(v.housekeeping_flags) &&
+    v.housekeeping_flags.every(isString) &&
+    Array.isArray(v.actions) &&
+    v.actions.every(isAction);
+function summary(t) {
+    const { gate, autopilot: run, pull_request: pr } = t;
+    return {
+        id: t.id,
+        class: t.class,
+        status: t.status,
+        issue: t.issue,
+        goal: t.goal,
+        knowledgeConsolidated: t.knowledge_consolidated,
+        paused: t.paused,
+        createdAt: t.created_at,
+        updatedAt: t.updated_at,
+        branch: t.branch,
+        baseBranch: t.base_branch,
+        worktree: t.worktree && { uncommitted: t.worktree.uncommitted },
+        gate: gate && { state: gate.state, by: gate.by },
+        autopilot: run && {
+            state: run.state,
+            mode: run.mode,
+            stage: run.stage,
+            stageAt: run.stage_at,
+            stopReason: run.stop_reason,
+            stopAt: run.stop_at,
+            phase: run.phase,
+        },
+        pullRequest: pr && { url: pr.url, state: pr.state, ci: pr.ci, fetchedAt: pr.fetched_at },
+        housekeepingFlags: [...t.housekeeping_flags],
+        actions: t.actions.filter((a) => ACTIONS.has(a.id)).map(({ id, command, offered, reason }) => ({ id, command, offered, reason })),
+    };
+}
+/** The project's live tasks (`jig task list --json`) and how many finished ones it left out. */
+export async function readTasks(root, platform = process.platform) {
+    const { revision, data } = await readJson(root, ['task', 'list'], platform);
+    if (!Array.isArray(data.tasks) || !data.tasks.every(isTaskRow) || typeof data.hidden !== 'number')
+        throw new JigShapeError();
+    return { revision, tasks: data.tasks.map(summary), hidden: data.hidden };
+}
+const isCount = (v) => Number.isInteger(v) && v >= 0;
+const isProgress = (v) => isObject(v) && isCount(v.done) && isCount(v.total) && isCount(v.filed) && isCount(v.fog);
+const isItem = (v) => isObject(v) && isString(v.text) && typeof v.checked === 'boolean' && isNullableString(v.task) && typeof v.fog === 'boolean';
+const isPhase = (v) => isObject(v) &&
+    isProgress(v) &&
+    (v.phase === null || isCount(v.phase)) &&
+    isNullableString(v.title) &&
+    Array.isArray(v.items) &&
+    v.items.every(isItem);
+const isEpic = (v) => v === null ||
+    (isObject(v) &&
+        isString(v.branch) &&
+        (v.state === 'open' || v.state === 'finished') &&
+        typeof v.checked_out === 'boolean' &&
+        typeof v.missing === 'boolean' &&
+        isNullableString(v.ref));
+const isSpecRow = (v) => isObject(v) &&
+    isString(v.id) &&
+    isNullableString(v.title) &&
+    Array.isArray(v.missing_files) &&
+    v.missing_files.every(isString) &&
+    isNullableString(v.release) &&
+    isEpic(v.epic) &&
+    (v.progress === null || isProgress(v.progress)) &&
+    Array.isArray(v.phases) &&
+    v.phases.every(isPhase);
+const progress = ({ done, total, filed, fog }) => ({ done, total, filed, fog });
+/** The project's specs (`jig spec list --json`), in Jig's order. */
+export async function readSpecs(root, platform = process.platform) {
+    const { data } = await readJson(root, ['spec', 'list'], platform);
+    if (!Array.isArray(data.specs) || !data.specs.every(isSpecRow))
+        throw new JigShapeError();
+    return data.specs.map((s) => ({
+        id: s.id,
+        title: s.title,
+        missingFiles: [...s.missing_files],
+        release: s.release,
+        epic: s.epic && {
+            branch: s.epic.branch,
+            state: s.epic.state,
+            checkedOut: s.epic.checked_out,
+            missing: s.epic.missing,
+            fetched: s.epic.ref?.startsWith('refs/remotes/') === true,
+        },
+        progress: s.progress && progress(s.progress),
+        phases: s.phases.map((p) => ({
+            ...progress(p),
+            phase: p.phase,
+            title: p.title,
+            items: p.items.map(({ text, checked, task, fog }) => ({ text, checked, task, fog })),
+        })),
+    }));
+}
 /** True when `version` is at least the minimum Jig UI reads. */
 export function supports(version, minimum = MIN_JIG_VERSION) {
     const a = version.split('.').map(Number);

package/dist/main.js

@@ -6,7 +6,9 @@ import { DEFAULT_PORT, parseCliArgs } from './args.js';
 import { createApp, readPackageVersion } from './http/app.js';
 import { openBrowser } from './open-browser.js';
 import { configDir } from './registry/config-dir.js';
-import { probeInstance, readInstance, removeInstance, writeInstance } from './registry/instance.js';
+import { connectThrough, probeInstance, readInstance, removeInstance, writeInstance } from './registry/instance.js';
+import { mainCheckout } from './source/checkout.js';
+import { localSource } from './source/local.js';
 const HOST = '127.0.0.1';
 const HELP = `Usage: jig-ui [options]
 
@@ -20,12 +22,40 @@ function fail(message) {
     console.error(message);
     process.exit(1);
 }
-const link = ({ port, token }) => `http://${HOST}:${port}/?token=${token}`;
-async function show(info, open, dir) {
-    console.log(`Open it at ${link(info)}`);
-    if (open && !(await openBrowser(link(info), dir)))
+// The token swap redirects to `/` with no fragment, so the browser keeps this one: the board opens.
+const link = ({ port, token }, project) => `http://${HOST}:${port}/?token=${token}${project ? `#/projects/${project}` : ''}`;
+async function show(info, open, dir, project) {
+    console.log(`Open it at ${link(info, project)}`);
+    if (open && !(await openBrowser(link(info, project), dir)))
         console.log('Could not open a browser; open the link above.');
 }
+/** The folder this command runs in, as a checkout to connect: a worktree stands for its clone's main checkout. */
+async function here() {
+    const checkout = await mainCheckout(process.cwd());
+    if (checkout.kind === 'main')
+        return { path: checkout.root, worktree: false };
+    // A bare clone's worktree has no main checkout: nothing to connect, said as outside a project.
+    if (checkout.kind === 'worktree' && checkout.main)
+        return { path: checkout.main, worktree: true };
+    return undefined;
+}
+/**
+ * Connects the folder through the instance and returns the project's id. Outside a Jig project it says
+ * nothing: the command then only starts, as it always did.
+ */
+async function connectHere(info, place) {
+    if (!place)
+        return undefined;
+    const result = await connectThrough(info, place.path);
+    if ('id' in result) {
+        const what = place.worktree ? `the main checkout of this worktree, ${place.path}` : place.path;
+        console.log(result.created ? `Connected ${result.id}: ${what}.` : `${result.id} is connected: ${what}.`);
+        return result.id;
+    }
+    if (result.code !== 'not-a-repository' && result.code !== 'no-jig')
+        console.log(`Could not connect this folder: ${result.message}`);
+    return undefined;
+}
 /** The instance recorded in the config directory, if it still answers with its token. */
 async function runningInstance(dir) {
     const info = await readInstance(dir);
@@ -55,22 +85,23 @@ export async function main() {
     }
     const { port, open } = command;
     const dir = configDir(process.env, process.platform, homedir());
+    const place = await here();
     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 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, configDir: dir, version }).fetch, hostname: HOST, port }, () => {
+    const server = serve({ fetch: createApp({ port, token, source: localSource(dir), version }).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}/`);
-            await show({ port, token }, open, dir);
+            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)}`));
     });
@@ -82,7 +113,7 @@ 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 show(winner, open, dir, await connectHere(winner, place));
             process.exit(0);
         });
     });

package/dist/node-version.js

@@ -8,7 +8,6 @@ export function checkNodeVersion(version) {
     }
     return {
         ok: false,
-        message: 'Jig UI needs Node.js ' + MINIMUM_NODE_MAJOR + ' or later, but this is ' + version +
-            '. Install a newer Node.js and run it again.',
+        message: 'Jig UI needs Node.js ' + MINIMUM_NODE_MAJOR + ' or later, but this is ' + version + '. Install a newer Node.js and run it again.',
     };
 }

package/dist/registry/instance.js

@@ -48,3 +48,24 @@ export async function probeInstance(info, timeoutMs = 1000) {
         return false;
     }
 }
+/** Asks the instance to connect `path`, as the page does: the instance owns the registry, so no second process writes it. */
+export async function connectThrough(info, path, timeoutMs = 15_000) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${info.port}/api/projects`, {
+            method: 'POST',
+            headers: { cookie: `${cookieName(info.port)}=${info.token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ path }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        // A failure the instance did not foresee answers in plain text.
+        const body = (await res.json().catch(() => ({})));
+        if (body.project)
+            return { id: body.project.id, created: res.status === 201 };
+        if (typeof body.error === 'object')
+            return body.error;
+        return { code: 'unexpected', message: `Jig UI answered ${res.status}.` };
+    }
+    catch (error) {
+        return { code: 'unreachable', message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/source/checkout.js

@@ -21,5 +21,23 @@ export async function mainCheckout(path) {
     const [top, own, common] = stdout.trim().split(/\r?\n/);
     if (!top || !own || !common)
         return { kind: 'not-a-repository' };
-    return (await realpath(own)) === (await realpath(common)) ? { kind: 'main', root: await realpath(top) } : { kind: 'worktree' };
+    if ((await realpath(own)) === (await realpath(common)))
+        return { kind: 'main', root: await realpath(top) };
+    return { kind: 'worktree', main: await mainWorktree(path) };
+}
+/**
+ * The main working tree, which `git worktree list` names first — not `dirname(--git-common-dir)`, which
+ * misses for a worktree of a submodule. A bare clone's first entry is the repository itself.
+ */
+async function mainWorktree(path) {
+    try {
+        const { stdout } = await run('git', ['worktree', 'list', '--porcelain'], { cwd: path, timeout: 10_000 });
+        const [first, second] = stdout.split(/\r?\n/);
+        if (!first?.startsWith('worktree ') || second === 'bare')
+            return null;
+        return await realpath(first.slice('worktree '.length));
+    }
+    catch {
+        return null;
+    }
 }