hacklab 0.12.8 → 0.13.1

package/dist/commands/essay.js

@@ -1,35 +1,79 @@
 import { readFile } from 'node:fs/promises';
 import * as clack from '@clack/prompts';
+import { emitJsonError, requireSession } from '../api-client.js';
 import { captureEvent } from '../posthog.js';
+import { resolveCommand } from '../resolve-command.js';
 import { loadSession, resolveAppUrl, unauthorizedHint, } from '../session.js';
-import { bold, dim, error, info, linkBlue, success } from '../ui.js';
-import { openBrowser } from '../utils/openBrowser.js';
-// `hacklab essay` — post and manage the essays on your profile. Thin wrappers
-// over the /api/essays routes: the markdown file is read locally but all real
-// validation (title, size, rendering, sanitization) happens on the backend.
-// Every subcommand takes --json so agents can drive it programmatically.
+import { bold, dim, error, info, link, stripControl, success } from '../ui.js';
+// `hacklab essay` — agent help on the bare command. `post` publishes markdown
+// the agent already has (`--content`) or a file on disk (`--file`, or a bare
+// path). `update` replaces the body at a stable URL. `view` reads one essay by
+// id. `list` reads yours, a hacker's, or an org's. `delete` removes yours.
+const SUBCOMMANDS = ['post', 'update', 'view', 'list', 'delete'];
 const ESSAYS_BASE = '/api/essays';
+// Same rule as the server: 4..36 chars of a lowercased uuid / prefix.
+const ID_PREFIX_RE = /^[0-9a-f][0-9a-f-]{3,35}$/;
+/**
+ * `view` takes an essay id only. Anything that can't be an id prefix is a
+ * usage error pointing at `essay list <handle>` — a handle and a short hex id
+ * are indistinguishable, so guessing between them silently reads the wrong
+ * thing.
+ */
+export function parseViewTarget(token) {
+    if (!token)
+        return { kind: 'missing' };
+    const raw = token.replace(/^@/, '');
+    if (!raw)
+        return { kind: 'missing' };
+    if (ID_PREFIX_RE.test(raw.toLowerCase())) {
+        return { kind: 'one', id: raw.toLowerCase() };
+    }
+    return { kind: 'not-an-id', token: raw };
+}
+/**
+ * The `essay list` target grammar, decided by argument count so a user
+ * literally named "org" still works as the bare one-arg form:
+ *   (none)      → your essays
+ *   <handle>    → that user's essays
+ *   org <slug>  → that org's essays
+ *   org/<slug>  → same, mirroring the web URL /org/<slug>
+ */
+export function parseListTarget(positionals) {
+    if (positionals.length === 0)
+        return { kind: 'self' };
+    if (positionals.length === 1) {
+        const arg = positionals[0];
+        if (arg.startsWith('org/')) {
+            const slug = arg.slice('org/'.length);
+            return slug ? { kind: 'org', slug } : { kind: 'invalid' };
+        }
+        return { kind: 'user', handle: arg.replace(/^@/, '') };
+    }
+    if (positionals.length === 2 && positionals[0] === 'org') {
+        return { kind: 'org', slug: positionals[1] };
+    }
+    return { kind: 'invalid' };
+}
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
-async function requireSession() {
-    const session = await loadSession();
-    if (!session) {
-        error('not logged in');
-        info(`run ${dim('hacklab login')} first`);
-        process.exit(1);
-    }
-    return session;
+function printHelp() {
+    console.log(`hacklab essay post --title <t> --content <md> [--json]`);
+    console.log(dim('  or --file <path.md>, or a bare <path.md>'));
+    console.log(`hacklab essay update <id> --content <md> [--json]`);
+    console.log(dim('  same URL'));
+    console.log('');
+    console.log(`hacklab essay list [<handle> | org <slug>] [--page N] [--json]`);
+    console.log(dim('  yours with no argument'));
+    console.log(`hacklab essay view <id> [--json]`);
+    console.log(dim('  one essay, full text'));
+    console.log('');
+    console.log(`hacklab essay delete <id> [--yes] [--json]`);
+    console.log(dim('  yours only; --yes skips the confirm'));
 }
-// A 401 here is nearly always a per-backend token mismatch rather than a real
-// auth failure, and the server's bare "Unauthorized" can't say so — only the
-// client knows which backend the session was minted against. Swap in the hint
-// that names the fix. Public reads pass no session and keep the server's text.
-export async function readError(res, session) {
-    if (res.status === 401 && session)
-        return unauthorizedHint(session);
-    const data = (await res.json().catch(() => null));
-    return data?.error ?? `request failed (${res.status})`;
+function usage(exitCode = 1) {
+    printHelp();
+    process.exit(exitCode);
 }
 function flagValue(args, ...names) {
     for (const name of names) {
@@ -42,21 +86,51 @@ function flagValue(args, ...names) {
     }
     return undefined;
 }
-/** Drop a flag and (when it isn't `--flag=value`) its value from args. */
-function stripFlag(args, withValue, ...names) {
-    const out = [];
+// Flags that take a following value. Every arg-walker has to skip that value,
+// or a legitimate `--content "- bullet"` reads as a flag of its own.
+function unknownFlag(args, allowed, valueFlags) {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        if (names.includes(arg)) {
-            if (withValue)
-                i++;
+        if (!arg)
+            continue;
+        if (valueFlags.has(arg)) {
+            i++;
             continue;
         }
-        if (names.some((name) => arg.startsWith(`${name}=`)))
+        if (!arg.startsWith('-'))
+            continue;
+        const name = arg.split('=')[0];
+        if (!name)
             continue;
-        out.push(arg);
+        if (!allowed.has(name))
+            return name;
     }
-    return out;
+    return undefined;
+}
+/** Non-flag arguments, in order, skipping the values that belong to a flag. */
+function positionals(args, valueFlags) {
+    const found = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg || arg === '--json')
+            continue;
+        if (valueFlags.has(arg)) {
+            i++;
+            continue;
+        }
+        if ([...valueFlags].some((name) => arg.startsWith(`${name}=`)))
+            continue;
+        if (arg.startsWith('-'))
+            continue;
+        found.push(arg);
+    }
+    return found;
+}
+export async function readError(res, session) {
+    if (res.status === 401 && session)
+        return unauthorizedHint(session);
+    const data = (await res.json().catch(() => null));
+    return data?.error ?? `request failed (${res.status})`;
 }
 const MONTHS = [
     'jan',
@@ -72,21 +146,21 @@ const MONTHS = [
     'nov',
     'dec',
 ];
-// Essays get absolute dates ("jul 12 2026"), not chat's relative prefixes —
-// a list of long-lived posts reads like an archive, not a conversation.
 export function formatEssayDate(iso) {
     const d = new Date(iso);
     if (Number.isNaN(d.getTime()))
         return iso;
     return `${MONTHS[d.getMonth()]} ${d.getDate()} ${d.getFullYear()}`;
 }
-/** The short id shown in human output. Full ids stay in --json. */
 function shortId(id) {
     return id.slice(0, 8);
 }
-async function readMarkdownFile(path) {
+async function readMarkdownFile(path, json) {
     if (!/\.(md|markdown)$/i.test(path)) {
-        error(`expected a markdown file (.md), got: ${path}`);
+        const message = `expected a markdown file (.md), got: ${path}`;
+        if (json)
+            emitJsonError('invalid_fields', message);
+        error(message);
         process.exit(1);
     }
     try {
@@ -94,341 +168,484 @@ async function readMarkdownFile(path) {
     }
     catch (err) {
         const code = err.code;
-        error(code === 'ENOENT' ? `file not found: ${path}` : `could not read ${path}`);
+        const message = code === 'ENOENT' ? `file not found: ${path}` : `could not read ${path}`;
+        if (json)
+            emitJsonError('read_failed', message);
+        error(message);
         process.exit(1);
     }
 }
-/** Meta line under a list entry: id · date · reading time (· synced) (· by author). */
-function metaLine(item, withAuthor) {
-    const parts = [];
-    if (withAuthor && item.authorHandle)
-        parts.push(`by ${item.authorHandle}`);
-    parts.push(shortId(item.id));
-    parts.push(formatEssayDate(item.publishedAt));
-    if (item.readingTimeMinutes)
-        parts.push(`${item.readingTimeMinutes} min`);
-    if (item.source === 'sync')
-        parts.push('synced');
-    return dim(`  ${parts.join(' · ')}`);
+/**
+ * The markdown body, from `--content`, `--file`, or the positional path the
+ * pre-flag CLI took (`essay post note.md`). Exactly one source.
+ */
+async function resolveMarkdown(args, json, file) {
+    const content = flagValue(args, '--content');
+    const fileFlag = flagValue(args, '--file');
+    const sources = [content, fileFlag, file].filter((v) => v !== undefined);
+    if (sources.length > 1) {
+        const message = content !== undefined && fileFlag !== undefined
+            ? 'use either --content or --file, not both'
+            : 'use one markdown source: --content, --file, or a <file.md> path';
+        if (json)
+            emitJsonError('invalid_fields', message);
+        error(message);
+        process.exit(1);
+    }
+    if (content !== undefined) {
+        if (!content.trim()) {
+            const message = 'an essay needs --content or --file';
+            if (json)
+                emitJsonError('missing_content', message);
+            error(message);
+            process.exit(1);
+        }
+        return content;
+    }
+    const path = fileFlag ?? file;
+    if (path)
+        return readMarkdownFile(path, json);
+    const message = 'an essay needs --content or --file';
+    if (json)
+        emitJsonError('missing_content', message);
+    error(message);
+    process.exit(1);
 }
-// ── post / update ───────────────────────────────────────────────────────────
-async function essayPost(args, json) {
-    const title = flagValue(args, '--title', '-t');
-    const positionals = stripFlag(args, true, '--title', '-t').filter((a) => !a.startsWith('-'));
-    const file = positionals[0];
-    if (!file || positionals.length > 1) {
-        error('usage: hacklab essay post <file.md> [--title "..."]');
+const BODY_FLAGS = new Set(['--title', '--content', '--file', '--json']);
+const BODY_VALUE_FLAGS = new Set(['--title', '--content', '--file']);
+async function essayPost(args) {
+    const json = args.includes('--json');
+    const unknown = unknownFlag(args, BODY_FLAGS, BODY_VALUE_FLAGS);
+    if (unknown) {
+        if (json)
+            emitJsonError('invalid_fields', `unknown flag: ${unknown}`);
+        error(`unknown flag: ${unknown}`);
+        process.exit(1);
+    }
+    const rest = positionals(args, BODY_VALUE_FLAGS);
+    if (rest.length > 1) {
+        const message = 'usage: hacklab essay post --title <t> --content <md>';
+        if (json)
+            emitJsonError('usage', message);
+        error(message);
+        process.exit(1);
+    }
+    const title = flagValue(args, '--title');
+    if (!title) {
+        const message = 'an essay needs a title: --title "Why I built this"';
+        if (json)
+            emitJsonError('missing_title', message);
+        error(message);
+        process.exit(1);
+    }
+    const markdown = await resolveMarkdown(args, json, rest[0]);
+    const session = await requireSession(json);
+    let res;
+    try {
+        res = await fetch(`${resolveAppUrl(session)}${ESSAYS_BASE}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${session.token}`,
+            },
+            body: JSON.stringify({ markdown, title }),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json)
+            emitJsonError('network', message);
+        error(message);
         process.exit(1);
     }
-    const session = await requireSession();
-    const markdown = await readMarkdownFile(file);
-    const res = await fetch(`${resolveAppUrl(session)}${ESSAYS_BASE}`, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${session.token}`,
-        },
-        body: JSON.stringify({ markdown, ...(title ? { title } : {}) }),
-    });
     if (!res.ok) {
-        error(await readError(res, session));
+        const message = await readError(res, session);
+        if (json)
+            emitJsonError('error', message);
+        error(message);
         process.exit(1);
     }
     const data = (await res.json());
     const url = `${resolveAppUrl(session)}${data.path}`;
+    await captureEvent(session.handle, 'cli_essay_published', {
+        essay_id: data.id,
+        has_custom_title: true,
+    });
     if (json) {
-        printJson({ ...data, url });
+        printJson({ schemaVersion: 1, ...data, url });
         return;
     }
-    success(`published ${bold(`"${data.title}"`)}`);
-    info(`id  ${bold(shortId(data.id))}`);
-    info(linkBlue(url));
-    console.log(dim(`\n  update it later: hacklab essay update ${shortId(data.id)} <file.md>`));
-    const publishSession = await loadSession();
-    await captureEvent(publishSession?.handle, 'cli_essay_published', {
-        essay_id: data.id,
-        has_custom_title: title !== undefined,
-    });
+    success(`published ${bold(stripControl(data.title))}`);
+    info(`${dim('id')}  ${bold(shortId(data.id))}`);
+    info(link(url));
 }
-async function essayUpdate(args, json) {
-    const title = flagValue(args, '--title', '-t');
-    const positionals = stripFlag(args, true, '--title', '-t').filter((a) => !a.startsWith('-'));
-    const [id, file] = positionals;
-    if (!id || !file || positionals.length > 2) {
-        error('usage: hacklab essay update <id> <file.md> [--title "..."]');
+async function essayUpdate(args) {
+    const json = args.includes('--json');
+    const unknown = unknownFlag(args, BODY_FLAGS, BODY_VALUE_FLAGS);
+    if (unknown) {
+        if (json)
+            emitJsonError('invalid_fields', `unknown flag: ${unknown}`);
+        error(`unknown flag: ${unknown}`);
+        process.exit(1);
+    }
+    const rest = positionals(args, BODY_VALUE_FLAGS);
+    const id = rest[0];
+    if (!id || rest.length > 2) {
+        const message = 'usage: hacklab essay update <id> --content <md>';
+        if (json)
+            emitJsonError('usage', message);
+        error(message);
+        process.exit(1);
+    }
+    const title = flagValue(args, '--title');
+    const markdown = await resolveMarkdown(args, json, rest[1]);
+    const session = await requireSession(json);
+    let res;
+    try {
+        res = await fetch(`${resolveAppUrl(session)}${ESSAYS_BASE}/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${session.token}`,
+            },
+            body: JSON.stringify({ markdown, ...(title ? { title } : {}) }),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json)
+            emitJsonError('network', message);
+        error(message);
         process.exit(1);
     }
-    const session = await requireSession();
-    const markdown = await readMarkdownFile(file);
-    const res = await fetch(`${resolveAppUrl(session)}${ESSAYS_BASE}/${encodeURIComponent(id)}`, {
-        method: 'PATCH',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${session.token}`,
-        },
-        body: JSON.stringify({ markdown, ...(title ? { title } : {}) }),
-    });
     if (!res.ok) {
-        error(await readError(res, session));
+        const message = await readError(res, session);
+        if (json)
+            emitJsonError('error', message);
+        error(message);
         process.exit(1);
     }
     const data = (await res.json());
     const url = `${resolveAppUrl(session)}${data.path}`;
-    if (json) {
-        printJson({ ...data, url });
-        return;
-    }
-    success(`updated ${bold(`"${data.title}"`)}`);
-    info(linkBlue(url));
     await captureEvent(session.handle, 'cli_essay_updated', {
         essay_id: data.id,
         has_custom_title: title !== undefined,
     });
+    if (json) {
+        printJson({ schemaVersion: 1, ...data, url });
+        return;
+    }
+    success(`updated ${bold(stripControl(data.title))}`);
+    info(link(url));
 }
-// ── delete ──────────────────────────────────────────────────────────────────
-async function essayDelete(args, json) {
-    const yes = args.includes('--yes') || args.includes('-y');
-    const positionals = stripFlag(args, false, '--yes', '-y').filter((a) => !a.startsWith('-'));
-    const id = positionals[0];
-    if (!id || positionals.length > 1) {
-        error('usage: hacklab essay delete <id> [--yes]');
+async function essayDelete(args) {
+    const json = args.includes('--json');
+    const unknown = unknownFlag(args, new Set(['--json', '--yes', '-y']), new Set());
+    if (unknown) {
+        if (json)
+            emitJsonError('invalid_fields', `unknown flag: ${unknown}`);
+        error(`unknown flag: ${unknown}`);
         process.exit(1);
     }
-    const session = await requireSession();
-    const base = resolveAppUrl(session);
-    // Fetch first so the confirmation names the essay, not just an id.
-    const viewRes = await fetch(`${base}${ESSAYS_BASE}/${encodeURIComponent(id)}`);
-    if (!viewRes.ok) {
-        error(await readError(viewRes));
+    const yes = args.includes('--yes') || args.includes('-y');
+    const id = args.find((a) => !a.startsWith('-'));
+    if (!id) {
+        const message = 'usage: hacklab essay delete <id> [--yes]';
+        if (json)
+            emitJsonError('usage', message);
+        error(message);
         process.exit(1);
     }
-    const { essay } = (await viewRes.json());
+    const session = await requireSession(json);
+    const base = resolveAppUrl(session);
+    // Deletion is irreversible and `essay d <id>` resolves here by prefix, so a
+    // typo must not be enough on its own. The prompt names the essay, which
+    // costs one read — skipped entirely on the --yes and agent paths.
     if (!yes) {
-        if (!process.stdin.isTTY) {
-            error('refusing to delete without confirmation — pass --yes');
+        if (json || !process.stdin.isTTY) {
+            const message = 'refusing to delete without confirmation — pass --yes';
+            if (json)
+                emitJsonError('confirm', message);
+            error(message);
             process.exit(1);
         }
-        const confirmed = await clack.confirm({
-            message: `delete "${essay.title}"? this cannot be undone.`,
+        const preview = await fetch(`${base}${ESSAYS_BASE}/${encodeURIComponent(id)}`);
+        if (!preview.ok) {
+            error(await readError(preview, session));
+            process.exit(1);
+        }
+        const { essay: found } = (await preview.json());
+        const ok = await clack.confirm({
+            message: `delete ${bold(stripControl(found.title))}? this cannot be undone.`,
             initialValue: false,
         });
-        if (clack.isCancel(confirmed) || !confirmed) {
+        if (clack.isCancel(ok) || !ok) {
             info('kept.');
             return;
         }
     }
-    const res = await fetch(`${base}${ESSAYS_BASE}/${encodeURIComponent(id)}`, {
-        method: 'DELETE',
-        headers: { Authorization: `Bearer ${session.token}` },
-    });
+    let res;
+    try {
+        res = await fetch(`${base}${ESSAYS_BASE}/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${session.token}` },
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json)
+            emitJsonError('network', message);
+        error(message);
+        process.exit(1);
+    }
     if (!res.ok) {
-        error(await readError(res, session));
+        const message = await readError(res, session);
+        if (json)
+            emitJsonError('error', message);
+        error(message);
         process.exit(1);
     }
     const data = (await res.json());
-    if (json) {
-        printJson(data);
-        return;
-    }
-    success(`deleted ${bold(`"${data.title}"`)}`);
     await captureEvent(session.handle, 'cli_essay_deleted', {
         essay_id: data.id,
     });
-}
-// ── view ────────────────────────────────────────────────────────────────────
-async function essayView(args, json) {
-    const web = args.includes('--web') || args.includes('-w');
-    const positionals = stripFlag(args, false, '--web', '-w').filter((a) => !a.startsWith('-'));
-    const id = positionals[0];
-    if (!id || positionals.length > 1) {
-        error('usage: hacklab essay view <id> [--web]');
-        process.exit(1);
-    }
-    // Viewing is public — a session only improves the base URL resolution.
-    const session = await loadSession();
-    const base = resolveAppUrl(session);
-    const res = await fetch(`${base}${ESSAYS_BASE}/${encodeURIComponent(id)}`);
-    if (!res.ok) {
-        error(await readError(res));
-        process.exit(1);
-    }
-    const { essay } = (await res.json());
-    const url = `${base}${essay.path}`;
     if (json) {
-        printJson({ essay: { ...essay, url } });
-        return;
-    }
-    if (web) {
-        const opened = await openBrowser(url);
-        if (opened) {
-            info(`opened ${linkBlue(url)}`);
-            return;
-        }
-        info(`could not open a browser — ${linkBlue(url)}`);
+        printJson({ schemaVersion: 1, deleted: true, id: data.id });
         return;
     }
+    success(`deleted ${bold(stripControl(data.title))}`);
+}
+function renderEssay(essay, url) {
     const byline = [
         essay.authorDisplayName ?? essay.authorHandle,
         formatEssayDate(essay.publishedAt),
         essay.readingTimeMinutes ? `${essay.readingTimeMinutes} min` : null,
     ].filter(Boolean);
-    console.log('');
-    console.log(`  ${bold(essay.title)}`);
+    console.log(`  ${bold(stripControl(essay.title))}`);
     console.log(dim(`  ${byline.join(' · ')}`));
-    console.log('');
     if (essay.contentText) {
-        for (const line of essay.contentText.split('\n')) {
-            console.log(`  ${line}`);
+        console.log('');
+        console.log(stripControl(essay.contentText).trimEnd());
+    }
+    console.log('');
+    info(link(url));
+}
+/** Meta line under a list entry: (by author ·) id · date · reading time (· synced). */
+function metaLine(item, withAuthor) {
+    const parts = [];
+    if (withAuthor && item.authorHandle)
+        parts.push(`by ${item.authorHandle}`);
+    parts.push(shortId(item.id));
+    parts.push(formatEssayDate(item.publishedAt));
+    if (item.readingTimeMinutes)
+        parts.push(`${item.readingTimeMinutes} min`);
+    if (item.source === 'sync')
+        parts.push('synced');
+    return dim(`  ${stripControl(parts.join(' · '))}`);
+}
+function renderList(data, subject, appUrl, self) {
+    const isOrg = data.kind === 'org';
+    if (data.items.length === 0) {
+        info(isOrg ? `no essays on ${subject}` : `no essays on @${subject}`);
+        if (self) {
+            info(`run ${dim('hacklab essay post --title "…" --content <md>')} to publish one`);
         }
+        return;
+    }
+    for (const item of data.items) {
+        console.log(`  ${bold(stripControl(item.title))}`);
+        console.log(metaLine(item, isOrg));
+    }
+    console.log('');
+    if (data.page < data.totalPages) {
+        const target = isOrg ? `org ${subject}` : subject;
+        console.log(dim(`  next → hacklab essay list ${target} --page ${data.page + 1}`));
         console.log('');
     }
-    console.log(`  ${linkBlue(url)}`);
+    info(link(`${appUrl}${isOrg ? `/org/${subject}` : `/${subject}`}`));
 }
-// ── list ────────────────────────────────────────────────────────────────────
-/**
- * The `essay list` target grammar, decided by argument count so a user
- * literally named "org" still works as the bare one-arg form:
- *   (none)      → your essays
- *   <handle>    → that user's essays
- *   org <slug>  → that org's essays
- *   org/<slug>  → same, mirroring the web URL /org/<slug>
- */
-export function parseListTarget(positionals) {
-    if (positionals.length === 0)
-        return { kind: 'self' };
-    if (positionals.length === 1) {
-        const arg = positionals[0];
-        if (arg.startsWith('org/')) {
-            const slug = arg.slice('org/'.length);
-            return slug ? { kind: 'org', slug } : { kind: 'invalid' };
+async function essayView(args) {
+    const json = args.includes('--json');
+    const unknown = unknownFlag(args, new Set(['--json']), new Set());
+    if (unknown) {
+        if (json)
+            emitJsonError('invalid_fields', `unknown flag: ${unknown}`);
+        error(`unknown flag: ${unknown}`);
+        process.exit(1);
+    }
+    const rest = positionals(args, new Set());
+    const target = parseViewTarget(rest.length === 1 ? rest[0] : undefined);
+    if (target.kind === 'missing') {
+        const message = 'usage: hacklab essay view <id>';
+        if (json)
+            emitJsonError('usage', message);
+        error(message);
+        process.exit(1);
+    }
+    if (target.kind === 'not-an-id') {
+        const message = `not an essay id: "${target.token}" — for a hacker's essays run: hacklab essay list ${target.token}`;
+        if (json)
+            emitJsonError('usage', message);
+        error(message);
+        process.exit(1);
+    }
+    // Viewing is public — a session only improves the base URL resolution.
+    const session = await loadSession();
+    const appUrl = resolveAppUrl(session);
+    let res;
+    try {
+        res = await fetch(`${appUrl}${ESSAYS_BASE}/${encodeURIComponent(target.id)}`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json)
+            emitJsonError('network', message);
+        error(message);
+        process.exit(1);
+    }
+    if (!res.ok) {
+        if (res.status === 404) {
+            const message = `no essay named "${target.id}"`;
+            if (json)
+                emitJsonError('not_found', message);
+            error(message);
+            info(`if that's a handle, run ${dim(`hacklab essay list ${target.id}`)} instead`);
+            process.exit(1);
         }
-        return { kind: 'user', handle: arg };
+        const message = await readError(res);
+        if (json)
+            emitJsonError('error', message);
+        error(message);
+        process.exit(1);
     }
-    if (positionals.length === 2 && positionals[0] === 'org') {
-        return { kind: 'org', slug: positionals[1] };
+    const body = (await res.json());
+    const url = `${appUrl}${body.essay.path}`;
+    if (json) {
+        printJson({ schemaVersion: 1, essay: { ...body.essay, url } });
+        return;
     }
-    return { kind: 'invalid' };
+    renderEssay(body.essay, url);
 }
-async function essayList(args, json) {
-    const rawPage = flagValue(args, '--page', '-p');
+async function essayList(args) {
+    const json = args.includes('--json');
+    const unknown = unknownFlag(args, new Set(['--json', '--page']), new Set(['--page']));
+    if (unknown) {
+        if (json)
+            emitJsonError('invalid_fields', `unknown flag: ${unknown}`);
+        error(`unknown flag: ${unknown}`);
+        process.exit(1);
+    }
+    const rawPage = flagValue(args, '--page');
     const page = rawPage ? Number.parseInt(rawPage, 10) : 1;
-    if (!Number.isInteger(page) || page < 1) {
-        error(`--page must be a positive integer, got: ${rawPage}`);
+    if (rawPage !== undefined && (!Number.isInteger(page) || page < 1)) {
+        const message = `--page must be a positive integer, got: ${rawPage}`;
+        if (json)
+            emitJsonError('invalid_fields', message);
+        error(message);
         process.exit(1);
     }
-    const positionals = stripFlag(args, true, '--page', '-p').filter((a) => !a.startsWith('-'));
-    const target = parseListTarget(positionals);
+    const target = parseListTarget(positionals(args, new Set(['--page'])));
     if (target.kind === 'invalid') {
-        error('usage: hacklab essay list [<handle> | org <slug>] [--page N]');
+        const message = 'usage: hacklab essay list [<handle> | org <slug>] [--page N]';
+        if (json)
+            emitJsonError('usage', message);
+        error(message);
         process.exit(1);
     }
-    let query;
+    let session;
     let subject;
+    let query;
     if (target.kind === 'self') {
-        const session = await requireSession();
+        session = await requireSession(json);
         if (!session.handle) {
-            error('no username on this session');
-            info(`run ${dim('hacklab login')} (or pass a username explicitly)`);
+            const message = 'no username on this session';
+            if (json)
+                emitJsonError('unauthorized', message);
+            error(message);
+            info(`run ${dim('hacklab login')} (or pass a handle explicitly)`);
             process.exit(1);
         }
-        query = { user: session.handle };
         subject = session.handle;
-    }
-    else if (target.kind === 'user') {
-        query = { user: target.handle };
-        subject = target.handle;
+        query = { key: 'user', value: session.handle };
     }
     else {
-        query = { org: target.slug };
-        subject = target.slug;
+        session = await loadSession();
+        subject = target.kind === 'user' ? target.handle : target.slug;
+        query = { key: target.kind === 'user' ? 'user' : 'org', value: subject };
     }
-    const session = await loadSession();
-    const url = new URL(`${resolveAppUrl(session)}${ESSAYS_BASE}`);
-    if ('user' in query)
-        url.searchParams.set('user', query.user);
-    else
-        url.searchParams.set('org', query.org);
+    const appUrl = resolveAppUrl(session);
+    const url = new URL(`${appUrl}${ESSAYS_BASE}`);
+    url.searchParams.set(query.key, query.value);
     if (page > 1)
         url.searchParams.set('page', String(page));
-    const res = await fetch(url);
+    let res;
+    try {
+        res = await fetch(url);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json)
+            emitJsonError('network', message);
+        error(message);
+        process.exit(1);
+    }
     if (!res.ok) {
-        error(await readError(res));
+        if (res.status === 404) {
+            const message = query.key === 'org'
+                ? `no org named "${subject}"`
+                : `no hacker named "${subject}"`;
+            if (json)
+                emitJsonError('not_found', message);
+            error(message);
+            process.exit(1);
+        }
+        const message = await readError(res, session);
+        if (json)
+            emitJsonError('error', message);
+        error(message);
         process.exit(1);
     }
     const data = (await res.json());
     if (json) {
-        printJson(data);
-        return;
-    }
-    const isOrg = data.kind === 'org';
-    const heading = isOrg
-        ? `essays from ${bold(data.org.name)} (${data.total})`
-        : `essays by ${bold(data.author.handle)} (${data.total})`;
-    const pageSuffix = data.totalPages > 1 ? dim(` — page ${data.page}/${data.totalPages}`) : '';
-    console.log('');
-    console.log(`  ${heading}${pageSuffix}`);
-    if (data.items.length === 0) {
-        console.log('');
-        info('no essays yet.');
-        if (!isOrg && session?.handle === data.author?.handle) {
-            info(`post one: ${dim('hacklab essay post <file.md>')}`);
-        }
+        printJson({ schemaVersion: 1, ...data });
         return;
     }
-    for (const item of data.items) {
-        console.log('');
-        console.log(`  ${bold(item.title)}`);
-        console.log(metaLine(item, isOrg));
-    }
-    if (data.page < data.totalPages) {
-        const target = isOrg ? `org ${subject}` : subject;
-        console.log('');
-        console.log(dim(`  next → hacklab essay list ${target} --page ${data.page + 1}`));
-    }
-    console.log('');
-}
-// ── dispatch ────────────────────────────────────────────────────────────────
-function printEssayHelp() {
-    console.log(`
-${bold('hacklab essay')} — essays on your profile
-
-  ${bold('post')} <file.md> [--title "..."]     publish a markdown file as an essay
-  ${bold('update')} <id> <file.md>              replace an essay's content (URL stays stable)
-  ${bold('delete')} <id> [--yes]                delete your essay
-  ${bold('view')} <id> [--web]                  read an essay (--web opens the browser)
-  ${bold('list')} [<handle> | org <slug>]       your essays, a user's, or an org's
-       [--page N]                     12 per page
-
-  all subcommands take ${bold('--json')} for machine-readable output.
-  ids are shown by post/list — any unique prefix works (e.g. 3f9c).
-`);
+    renderList(data, data.kind === 'org'
+        ? (data.org?.slug ?? subject)
+        : (data.author?.handle ?? subject), appUrl, target.kind === 'self');
 }
 export async function essay(args) {
     const json = args.includes('--json');
     const rest = args.filter((a) => a !== '--json');
-    const sub = rest[0];
-    const subArgs = rest.slice(1);
-    switch (sub) {
-        case 'post':
-            return essayPost(subArgs, json);
-        case 'update':
-            return essayUpdate(subArgs, json);
-        case 'delete':
-            return essayDelete(subArgs, json);
-        case 'view':
-            return essayView(subArgs, json);
-        case 'list':
-            return essayList(subArgs, json);
-        case undefined:
-        case 'help':
-        case '--help':
-        case '-h':
-            printEssayHelp();
-            return;
-        default:
-            error(`unknown subcommand: ${sub}`);
-            printEssayHelp();
-            process.exit(1);
+    const [subToken, ...subArgs] = rest;
+    if (json)
+        subArgs.push('--json');
+    if (!subToken ||
+        subToken === '--help' ||
+        subToken === '-h' ||
+        subToken === 'help') {
+        usage(0);
+    }
+    if (subToken.startsWith('-'))
+        usage();
+    const resolved = resolveCommand(subToken, SUBCOMMANDS);
+    if (resolved.kind === 'ambiguous') {
+        error(`ambiguous: essay ${subToken} (${resolved.matches.join(', ')})`);
+        process.exit(1);
     }
+    if (resolved.kind === 'unknown') {
+        error(`unknown subcommand: essay ${subToken}`);
+        usage();
+    }
+    if (resolved.name === 'post')
+        return essayPost(subArgs);
+    if (resolved.name === 'update')
+        return essayUpdate(subArgs);
+    if (resolved.name === 'view')
+        return essayView(subArgs);
+    if (resolved.name === 'list')
+        return essayList(subArgs);
+    if (resolved.name === 'delete')
+        return essayDelete(subArgs);
 }
 //# sourceMappingURL=essay.js.map