@fapost/jig-ui 0.2.0-next.20 → 0.2.0-next.22

package/dist/http/app.js

@@ -4,7 +4,10 @@ import { isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { secureHeaders } from 'hono/secure-headers';
 import { streamSSE } from 'hono/streaming';
+import { validator } from 'hono/validator';
 import { columns, placeOf } from '../board/columns.js';
 import { RegistryUnreadable } from '../source/project-source.js';
 import { localOnly, tokenAccess } from './access.js';
@@ -29,61 +32,58 @@ function absolute(path) {
     const expanded = path.trim().replace(/^~(?=$|[\\/])/, homedir());
     return isAbsolute(expanded) ? expanded : undefined;
 }
-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 }));
-    app.onError((error, c) => {
-        if (error instanceof RegistryUnreadable)
-            return refuse(c, 500, 'registry-unreadable', error.message);
-        console.error(error);
-        return c.text('Internal Server Error', 500);
-    });
-    app.get('/api/instance', (c) => c.json({ version }));
-    app.get('/api/workspace', async (c) => c.json({ projects: await source.workspace() }));
-    app.get('/api/projects/:id/board', async (c) => {
+/**
+ * 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) {
+    return (new Hono()
+        .get('/api/instance', (c) => c.json({ version }, 200))
+        .get('/api/workspace', async (c) => c.json({ projects: await source.workspace() }, 200))
+        .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) => {
+            return c.json({ board: read }, 200);
+        return c.json({ board: { id, state: read.state, columns: columns(read.tasks), finished: read.finished } }, 200);
+    })
+        .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 });
+            return c.json({ task: read }, 200);
         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) => {
+        return c.json({ task: { state: read.state, ...read.task, column: placeOf(read.task) } }, 200);
+    })
+        .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);
+        return c.json({ specs: read }, 200);
+    })
+        .post('/api/projects', validator('json', (body) => ({
+        path: absolute(body?.path),
+    })), async (c) => {
+        const { path } = c.req.valid('json');
         if (path === undefined)
             return refuse(c, 422, 'usage', 'Give the absolute path of a project.');
         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) => {
+        return result.created ? c.json({ project: result.project }, 201) : c.json({ project: result.project }, 200);
+    })
+        .delete('/api/projects/:id', async (c) => {
         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) => {
+    })
+        // A signal, not data: the page re-fetches what it shows (adr-20261014-project-source-port-keeps-hosting-open).
+        .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 }) });
         });
@@ -93,7 +93,25 @@ export function createApp({ port, token, source, version = readPackageVersion(),
             if (!stream.aborted)
                 await stream.write(': ping\n\n');
         }
-    }));
+    })));
+}
+export function createApp({ port, token, source, version = readPackageVersion(), webRoot = DEFAULT_WEB_ROOT }) {
+    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 }));
+    app.use(localOnly(port));
+    app.use(tokenAccess({ port, token }));
+    app.onError((error, c) => {
+        if (error instanceof RegistryUnreadable)
+            return refuse(c, 500, 'registry-unreadable', error.message);
+        // Hono's own refusals, such as a body that is no JSON: their status, in the API's form.
+        if (error instanceof HTTPException)
+            return c.json({ error: { code: 'usage', message: error.message } }, error.status);
+        // Only the terminal hears what failed: the message may name a path.
+        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.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

@@ -2,6 +2,7 @@ import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
+import { z } from 'zod';
 const run = promisify(execFile);
 /** The oldest Jig whose reads Jig UI understands: 0.29.0 is the first that prints JSON. */
 export const MIN_JIG_VERSION = '0.29.0';
@@ -17,6 +18,7 @@ export const watchDir = (root) => join(root, '.ai');
  * (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');
+let gitBash;
 /**
  * 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.
@@ -24,8 +26,12 @@ export const writtenByReads = (path) => (path === 'runtime' || path.startsWith('
 async function bash(platform) {
     if (platform !== 'win32')
         return 'bash';
-    const { stdout } = await run('git', ['--exec-path'], { timeout: TIMEOUT_MS });
-    return resolve(stdout.trim(), '..', '..', '..', 'bin', 'bash.exe');
+    // Asked once per process; a failed ask is forgotten, so the next run asks again.
+    gitBash ??= run('git', ['--exec-path'], { timeout: TIMEOUT_MS }).then(({ stdout }) => resolve(stdout.trim(), '..', '..', '..', 'bin', 'bash.exe'), (error) => {
+        gitBash = undefined;
+        throw error;
+    });
+    return gitBash;
 }
 /** Runs the project's own Jig in its main checkout, without a shell. */
 async function jig(root, args, platform) {
@@ -60,8 +66,6 @@ export class JigShapeError extends Error {
     }
 }
 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
@@ -87,159 +91,157 @@ async function readJson(root, args, platform) {
         throw new JigShapeError();
     if (isObject(envelope.error)) {
         const code = envelope.error.code;
-        throw new JigRefusal(isString(code) && CODES.has(code) ? code : 'failed');
+        throw new JigRefusal(typeof code === 'string' && 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);
+/** `data` read through `schema`, the shape its contract test pins; anything else is a Jig this Jig UI does not read. */
+function parsed(schema, data) {
+    const result = schema.safeParse(data);
+    if (!result.success)
+        throw new JigShapeError();
+    return result.data;
+}
+// Each shape of Jig's output once: what Jig prints (snake_case, every field Jig UI reads present —
+// `null` where Jig has nothing, never left out), turned into what Jig UI's types say. Keys Jig adds
+// without raising `schema` are dropped.
+const text = z.string();
+const maybe = z.string().nullable();
+const count = z.int().nonnegative();
+/** Something that needs the person, as `jig status --json` reports it; a kind this Jig UI does not know is shown by its texts. */
+const Attention = z.object({
+    kind: text,
+    subject: z.object({ type: text, id: maybe }),
+    tasks: z.array(text),
+    title: text,
+    detail: maybe,
+    todo: text,
+    url: maybe,
+});
+const Status = z.object({
+    attention: z.array(Attention),
+    housekeeping: z.object({ stale: z.boolean() }).nullable(),
+});
 /** 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 { attention, housekeeping } = parsed(Status, data);
+    return { revision, attention, 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 })),
-    };
-}
+/** What a person may do next with a task, as Jig decides it from the task's state. */
+const TaskAction = z.object({
+    id: text,
+    /** The Jig command that takes it; a word in `<…>` is a value the person supplies. */
+    command: text,
+    offered: z.boolean(),
+    /** Jig's refusal, word for word, when not offered; it may name a path. */
+    reason: maybe,
+});
+/** A task as `jig task list --json` reports it, as far as Jig UI reads it; the statuses are Jig's (schemas/state.md). */
+const TaskRow = z
+    .object({
+    id: text,
+    class: maybe,
+    status: z.enum(['active', 'ready', 'consolidated', 'abandoned']),
+    issue: maybe,
+    goal: maybe,
+    knowledge_consolidated: z.boolean(),
+    paused: z.boolean(),
+    created_at: maybe,
+    updated_at: maybe,
+    /** `null` while the task has not been started. */
+    branch: maybe,
+    base_branch: text,
+    /** The worktree that has the task's branch checked out: only how many files differ there, never where it is. */
+    worktree: z.object({ uncommitted: z.number() }).nullable(),
+    gate: z.object({ state: text, by: maybe }).nullable(),
+    autopilot: z
+        .object({ state: text, mode: maybe, stage: maybe, stage_at: maybe, stop_reason: maybe, stop_at: maybe, phase: maybe })
+        .nullable(),
+    pull_request: z.object({ url: text, state: maybe, ci: maybe, fetched_at: maybe }).nullable(),
+    housekeeping_flags: z.array(text),
+    actions: z.array(TaskAction),
+})
+    .transform(({ autopilot: run, pull_request: pr, ...t }) => ({
+    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,
+    gate: t.gate,
+    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)),
+}));
+const TaskList = z.object({ tasks: z.array(TaskRow), hidden: z.number() });
 /** 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 };
+    return { revision, ...parsed(TaskList, data) };
 }
-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 });
+/** How far a roadmap or one of its phases is: items checked, all items, items with a task filed, fog items. */
+const SpecProgress = z.object({ done: count, total: count, filed: count, fog: count });
+/** A roadmap item: its words as the roadmap has them, and the task it names, if any. */
+const SpecItem = z.object({ text, checked: z.boolean(), task: maybe, fog: z.boolean() });
+/** A roadmap phase; `phase` and `title` are `null` for items before any phase heading. */
+const SpecPhase = SpecProgress.extend({ phase: count.nullable(), title: maybe, items: z.array(SpecItem) });
+/** A spec as `jig spec list --json` reports it; the roadmap is read from the epic while one is open. */
+const SpecRow = z
+    .object({
+    id: text,
+    title: maybe,
+    /** The spec's own files that are not there: `spec.md`, `roadmap.md`. */
+    missing_files: z.array(text),
+    /** The version level the epic's release raises, as the roadmap records it. */
+    release: maybe,
+    epic: z
+        .object({ branch: text, state: z.enum(['open', 'finished']), checked_out: z.boolean(), missing: z.boolean(), ref: maybe })
+        .nullable(),
+    /** `null` when the roadmap could not be read. */
+    progress: SpecProgress.nullable(),
+    phases: z.array(SpecPhase),
+})
+    .transform(({ missing_files, epic, ...s }) => ({
+    id: s.id,
+    title: s.title,
+    missingFiles: missing_files,
+    release: s.release,
+    // `fetched`: the roadmap was read from the remote branch as of the last fetch; `missing`: the branch is nowhere.
+    epic: epic && {
+        branch: epic.branch,
+        state: epic.state,
+        checkedOut: epic.checked_out,
+        missing: epic.missing,
+        fetched: epic.ref?.startsWith('refs/remotes/') === true,
+    },
+    progress: s.progress,
+    phases: s.phases,
+}));
+const SpecList = z.object({ specs: z.array(SpecRow) });
 /** 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 })),
-        })),
-    }));
+    return parsed(SpecList, data).specs;
 }
 /** True when `version` is at least the minimum Jig UI reads. */
 export function supports(version, minimum = MIN_JIG_VERSION) {

package/dist/registry/instance.js

@@ -1,6 +1,9 @@
 import { randomBytes } from 'node:crypto';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { z } from 'zod';
+/** What a running instance records so that a second start can find it. */
+const InstanceInfo = z.object({ port: z.int(), token: z.string(), pid: z.int(), version: z.string() });
 const FILE = 'instance.json';
 /** The page that sends the browser on to the instance; it carries the token, so it lives here too. */
 export const OPEN_FILE = 'open.html';
@@ -8,10 +11,7 @@ export const OPEN_FILE = 'open.html';
 export const cookieName = (port) => `jig-ui-${port}`;
 export async function readInstance(dir) {
     try {
-        const info = JSON.parse(await readFile(join(dir, FILE), 'utf8'));
-        if (typeof info.port !== 'number' || typeof info.token !== 'string')
-            return undefined;
-        return info;
+        return InstanceInfo.safeParse(JSON.parse(await readFile(join(dir, FILE), 'utf8'))).data;
     }
     catch {
         return undefined;
@@ -48,6 +48,11 @@ export async function probeInstance(info, timeoutMs = 1000) {
         return false;
     }
 }
+// An instance before 0.2.0 answers a failure it did not foresee in plain text: neither of these.
+const Answer = z.union([
+    z.object({ project: z.object({ id: z.string() }) }),
+    z.object({ error: z.object({ code: z.string(), message: z.string() }) }),
+]);
 /** 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 {
@@ -57,13 +62,10 @@ export async function connectThrough(info, path, timeoutMs = 15_000) {
             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)
+        const body = Answer.safeParse(await res.json().catch(() => undefined)).data;
+        if (body && 'project' in body)
             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}.` };
+        return body?.error ?? { code: 'unexpected', message: `Jig UI answered ${res.status}.` };
     }
     catch (error) {
         return { code: 'unreachable', message: error instanceof Error ? error.message : String(error) };

package/dist/registry/projects.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
+import { z } from 'zod';
 import { writeConfigFile } from './instance.js';
 const FILE = 'projects.json';
 /** The registry file exists but cannot be read; it is never overwritten then, so the list is not lost. */
@@ -8,7 +9,8 @@ export class RegistryUnreadable extends Error {
         super(`${FILE} in Jig UI's config directory cannot be read; fix or remove it.`);
     }
 }
-const isProject = (p) => typeof p === 'object' && p !== null && typeof p.id === 'string' && typeof p.path === 'string';
+// A row keeps the fields it does not know, so a later version's additions survive this one's writes.
+const Registry = z.object({ projects: z.array(z.looseObject({ id: z.string(), path: z.string() })) });
 /** The connected projects in the order they were connected; none when there is no registry yet. */
 export async function readProjects(dir) {
     let text;
@@ -20,21 +22,23 @@ export async function readProjects(dir) {
             return [];
         throw new RegistryUnreadable();
     }
+    let json;
     try {
-        const { projects } = JSON.parse(text);
-        if (Array.isArray(projects) && projects.every(isProject))
-            return projects;
+        json = JSON.parse(text);
     }
     catch {
-        // falls through
+        throw new RegistryUnreadable();
     }
-    throw new RegistryUnreadable();
+    const registry = Registry.safeParse(json);
+    if (!registry.success)
+        throw new RegistryUnreadable();
+    return registry.data.projects;
 }
 /** The id for a checkout: its directory name as a slug, with `-2`, `-3`… when that is taken. */
 export function slugFor(root, taken) {
     const base = basename(root)
         .normalize('NFKD')
-        .replace(/[̀-ͯ]/g, '')
+        .replace(/\p{M}/gu, '')
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '') || 'project';