getownit 0.1.1 → 0.1.3

package/README.md

@@ -11,9 +11,9 @@ ownit key set     # pick Nebius or NVIDIA, then paste your key; stored only in ~
 ownit init        # in a repo: installs the pre-push hook
 ```
 
-On each push: `Debrief now? [Y/n/s=skip]`. Ownit never blocks a push. Pending debriefs can be
-finished any time with `ownit interview`.
+On each push: `Debrief now? [Y/n]`. Ownit never blocks a push. Pending debriefs can be
+finished any time with `ownit interview`, which lets you pick the push.
 
-Your code and answers are never stored, and your key is never stored or logged by the server.
+Your code is never stored, your answers only if the repo's admins choose to show them on its page, and your key is never stored or logged by the server.
 
 Full documentation: [github.com/Yoosseph/ownit](https://github.com/Yoosseph/ownit).

package/dist/commands/hook.js

@@ -38,22 +38,13 @@ async function readStdin() {
         text += chunk;
     return text;
 }
+/** Yes (or Enter) debriefs now; anything else, including the old "s", leaves it for later. */
 export function interpretChoice(answer) {
-    if (answer === null)
-        return 'later';
-    const value = answer.trim().toLowerCase();
-    if (value === '' || value === 'y' || value === 'yes')
-        return 'debrief';
-    if (value === 's' || value === 'skip')
-        return 'skip';
-    return 'later';
-}
-async function record(api, repo, push, status) {
-    const res = await api.request('POST', '/api/pushes', { repo, base_sha: push.base, head_sha: push.head, commits: push.commits.map((c) => ({ sha: c.sha })), status }, { timeoutMs: QUICK_TIMEOUT_MS });
-    return res.status;
+    const value = answer?.trim().toLowerCase();
+    return value === '' || value === 'y' || value === 'yes' ? 'debrief' : 'later';
 }
 async function recordPending(api, repo, push, out) {
-    await record(api, repo, push, 'pending');
+    await api.request('POST', '/api/pushes', { repo, base_sha: push.base, head_sha: push.head, commits: push.commits.map((c) => ({ sha: c.sha })), status: 'pending' }, { timeoutMs: QUICK_TIMEOUT_MS });
     out.write(`Ownit: push recorded as pending. ${RESUME_HINT}\n`);
     return 0;
 }
@@ -71,20 +62,14 @@ async function knownStatus(api, repo, push) {
     });
     return known.status;
 }
-/** Asks whether to debrief now, then debriefs, records a skip, or leaves the push pending. */
+/** Asks whether to debrief now, then debriefs or leaves the push pending for `ownit interview`. */
 async function askAndDebrief(api, terminal, repo, push, out) {
     const c = paint(out);
     const prompter = createPrompter(terminal, out);
     try {
         const n = push.commits.length;
-        const answer = await prompter.ask(`${c.bold('Ownit')} ${c.dim(`(${n} ${plural(n, 'commit')} to ${repo})`)} Debrief now? [Y/n/s=skip] `, PROMPT_TIMEOUT_MS);
-        const choice = interpretChoice(answer);
-        if (choice === 'skip') {
-            await record(api, repo, push, 'skipped');
-            out.write(c.dim('Ownit: skipped. Push continues.\n'));
-            return 0;
-        }
-        if (choice === 'later')
+        const answer = await prompter.ask(`${c.bold('Ownit')} ${c.dim(`(${n} ${plural(n, 'commit')} to ${repo})`)} Debrief now? [Y/n] `, PROMPT_TIMEOUT_MS);
+        if (interpretChoice(answer) === 'later')
             return await recordPending(api, repo, push, out);
         await runDebrief(api, prompter, {
             repo,

package/dist/commands/interview.js

@@ -1,14 +1,14 @@
 import { parseArgs } from 'node:util';
 import { createApi } from '../api.js';
 import { buildDiff } from '../diff.js';
-import { runDebrief } from '../debrief.js';
-import { githubRepo, listCommits, objectExists, resolveCommit } from '../git.js';
+import { LATER, runDebrief } from '../debrief.js';
+import { githubRepo, listCommits, objectExists, resolveCommit, tryGit } from '../git.js';
 import { rangeForRecordedPush } from '../pushRange.js';
 import { createPrompter, paint, plural } from '../ui.js';
 export async function interviewCommand(argv) {
     const { values } = parseArgs({
         args: argv,
-        options: { range: { type: 'string' }, repo: { type: 'string' } },
+        options: { range: { type: 'string' }, repo: { type: 'string' }, all: { type: 'boolean' } },
         allowPositionals: false,
     });
     const out = process.stderr;
@@ -22,32 +22,92 @@ export async function interviewCommand(argv) {
     try {
         if (values.range)
             return exitCode(await debriefRange(api, prompter, repo, values.range));
-        return await debriefOpenPushes(api, prompter, repo);
+        return await debriefOpenPushes(api, prompter, repo, Boolean(values.all));
     }
     finally {
         prompter.close();
     }
 }
 function exitCode(outcome) {
-    return outcome && (outcome.status === 'verified' || outcome.status === 'skipped') ? 0 : 1;
+    return outcome && (outcome.status === 'verified' || outcome.reason === LATER) ? 0 : 1;
 }
-async function debriefRange(api, prompter, repo, range) {
-    const match = range.match(/^(.+?)\.\.(.+)$/);
-    if (!match) {
-        prompter.out.write('Ownit: --range must look like A..B.\n');
-        return null;
+/** A commit ID or ref, with a hint on where to find one when git does not know it. */
+function commitFor(rev) {
+    try {
+        return resolveCommit(rev);
+    }
+    catch {
+        throw new Error(`"${rev}" is not a commit in this repo. Find commit IDs with "git log --oneline", for example --range 7a9e3f1..f3c9a12.`);
     }
-    const base = resolveCommit(match[1]);
-    const head = resolveCommit(match[2]);
-    const commits = listCommits([`${base}..${head}`]);
+}
+/** A range "A..B", or a single commit, which means just that commit. */
+function parseRange(range) {
+    const match = range.match(/^(.+?)\.\.(.+)$/);
+    if (match)
+        return { base: commitFor(match[1]), head: commitFor(match[2]) };
+    const head = commitFor(range);
+    return { base: tryGit(['rev-parse', '--verify', '--quiet', `${head}^`])?.trim() || null, head };
+}
+async function debriefRange(api, prompter, repo, range) {
+    const { base, head } = parseRange(range);
+    const commits = base ? listCommits([`${base}..${head}`]) : listCommits(['-1', head]);
     if (!commits.length) {
         prompter.out.write(`Ownit: no commits in ${range}.\n`);
         return null;
     }
     return runDebrief(api, prompter, { repo, baseSha: base, headSha: head, commits, diff: buildDiff([{ base, head }]) });
 }
-/** Resolves pending and provider_error pushes, newest first. */
-async function debriefOpenPushes(api, prompter, repo) {
+function toChoice(push) {
+    if (![push.head_sha, ...push.commits].every((sha) => objectExists(sha)))
+        return { push, commits: [] };
+    const range = rangeForRecordedPush(push.base_sha, push.head_sha, push.commits);
+    const known = new Set(push.commits);
+    const commits = listCommits([range.base ? `${range.base}..${range.head}` : range.head]).filter((x) => known.has(x.sha));
+    return { push, commits: commits.length ? commits : listCommits(['-1', range.head]) };
+}
+const shortDate = (iso) => new Date(iso).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+/** One line per push: number, status, head commit, date and what the commits say. */
+function printChoices(out, choices) {
+    const c = paint(out);
+    const width = Math.min(process.stderr.columns || 80, 100);
+    choices.forEach(({ push, commits }, i) => {
+        const status = push.status === 'provider_error' ? 'error' : push.status;
+        const head = `${String(i + 1).padStart(3)}  ${status.padEnd(7)}  ${push.head_sha.slice(0, 7)}  ${shortDate(push.created_at).padEnd(6)}  `;
+        let title;
+        if (!commits.length)
+            title = c.yellow('not in this clone, run "git fetch"');
+        else {
+            const subject = commits.at(-1).message.split('\n')[0];
+            const more = commits.length > 1 ? ` (+${commits.length - 1} more)` : '';
+            const room = Math.max(20, width - head.length - more.length);
+            title = (subject.length > room ? `${subject.slice(0, room - 1)}…` : subject) + c.dim(more);
+        }
+        out.write(`${c.dim(head)}${title}\n`);
+    });
+}
+/** What the developer picked: a list index, every push, quit (also on end of input), or null when unclear. */
+export function parsePick(answer, count) {
+    const text = answer?.trim().toLowerCase() ?? 'q';
+    if (text === '')
+        return 0;
+    if (text === 'q' || text === 'quit')
+        return 'quit';
+    if (text === 'a' || text === 'all')
+        return 'all';
+    const n = Number(text);
+    return Number.isInteger(n) && n >= 1 && n <= count ? n - 1 : null;
+}
+async function debriefChoice(api, prompter, repo, { push, commits }) {
+    const range = rangeForRecordedPush(push.base_sha, push.head_sha, push.commits);
+    return runDebrief(api, prompter, { repo, baseSha: range.base, headSha: range.head, commits, diff: buildDiff([range]), pushId: push.id });
+}
+/** The debrief was cut off or failed, so stop. "s" (later) is not a stop: it moves on to the next push. */
+const stopped = (outcome) => outcome.reason !== LATER && (outcome.status === 'pending' || outcome.status === 'provider_error');
+/**
+ * Lists the pushes still waiting for a debrief, newest first, and debriefs the
+ * ones the developer picks, one at a time. `all` keeps going without asking.
+ */
+async function debriefOpenPushes(api, prompter, repo, all) {
     const out = prompter.out;
     const c = paint(out);
     const { pushes } = await api.request('GET', `/api/pushes/open?repo=${encodeURIComponent(repo)}`);
@@ -55,28 +115,46 @@ async function debriefOpenPushes(api, prompter, repo) {
         out.write(`${c.green('✓')} Nothing to debrief for ${repo}.\n`);
         return 0;
     }
-    out.write(`${pushes.length} ${plural(pushes.length, 'push', 'pushes')} waiting for a debrief in ${repo}.\n`);
-    let code = 0;
-    for (const push of pushes) {
-        const missing = [push.head_sha, ...push.commits].find((sha) => !objectExists(sha));
-        if (missing) {
-            out.write(c.yellow(`Ownit: commit ${missing.slice(0, 7)} is not in this clone. Run "git fetch" and try again.\n`));
-            code = 1;
+    let choices = pushes.map(toChoice);
+    if (all)
+        return debriefInOrder(api, prompter, repo, choices);
+    while (choices.length) {
+        out.write(`\n${choices.length} ${plural(choices.length, 'push', 'pushes')} waiting for a debrief in ${repo}:\n\n`);
+        printChoices(out, choices);
+        const pick = parsePick(await prompter.ask(`\nDebrief which one? ${c.dim('[number, Enter for 1, a = all, q = quit]')} `), choices.length);
+        if (pick === 'quit') {
+            out.write(c.dim('Run "ownit interview" any time to come back.\n'));
+            return 0;
+        }
+        if (pick === null) {
+            out.write(c.yellow(`Pick a number from 1 to ${choices.length}, a or q.\n`));
             continue;
         }
-        const range = rangeForRecordedPush(push.base_sha, push.head_sha, push.commits);
-        const known = new Set(push.commits);
-        const commits = listCommits([range.base ? `${range.base}..${range.head}` : range.head]).filter((x) => known.has(x.sha));
-        const outcome = await runDebrief(api, prompter, {
-            repo,
-            baseSha: range.base,
-            headSha: range.head,
-            commits: commits.length ? commits : listCommits(['-1', range.head]),
-            diff: buildDiff([range]),
-            pushId: push.id,
-        });
-        if (outcome.status === 'pending' || outcome.status === 'provider_error')
+        if (pick === 'all')
+            return debriefInOrder(api, prompter, repo, choices);
+        const choice = choices[pick];
+        if (!choice.commits.length) {
+            out.write(c.yellow(`Commit ${choice.push.head_sha.slice(0, 7)} is not in this clone. Run "git fetch" and try again.\n`));
+            continue;
+        }
+        const outcome = await debriefChoice(api, prompter, repo, choice);
+        if (stopped(outcome))
+            return 1;
+        if (outcome.reason !== LATER)
+            choices = choices.filter((x) => x !== choice);
+    }
+    out.write(`\n${c.green('✓')} Nothing left to debrief for ${repo}.\n`);
+    return 0;
+}
+/** Debriefs every push in the list, newest first, until one is paused or fails. */
+async function debriefInOrder(api, prompter, repo, choices) {
+    for (const choice of choices.filter((x) => x.commits.length)) {
+        if (stopped(await debriefChoice(api, prompter, repo, choice)))
             return 1;
     }
-    return code;
+    const missing = choices.filter((x) => !x.commits.length).length;
+    if (missing) {
+        prompter.out.write(paint(prompter.out).yellow(`Ownit: ${missing} ${plural(missing, 'push', 'pushes')} not in this clone. Run "git fetch" and try again.\n`));
+    }
+    return missing ? 1 : 0;
 }

package/dist/commands/settings.js

@@ -0,0 +1,58 @@
+import { createApi } from '../api.js';
+import { githubRepo } from '../git.js';
+import { paint } from '../ui.js';
+const USAGE = 'Usage: ownit settings [questions|answers|earlier] [on|off]\nFor example: ownit settings answers on. Run "ownit help settings" for details.\n';
+/** The setting each name changes on the server. */
+const SETTING = { questions: 'show_questions', answers: 'show_answers', earlier: 'allow_backfill' };
+function describe(s) {
+    const page = s.private
+        ? 'Questions and answers: hidden (private repo)'
+        : `Questions:       ${s.show_questions ? 'shown' : 'hidden'}\nAnswers:         ${s.show_answers ? 'shown' : 'hidden'}`;
+    return `${page}\nEarlier commits: ${s.allow_backfill ? 'count once debriefed' : 'not counted'}`;
+}
+/** A line about what just changed, or how to change things. */
+function note(s, changed, on) {
+    if (changed === 'answers' && on)
+        return 'From now on, passing answers are saved and shown. Developers see a note before they answer.';
+    if (changed === 'earlier' && on)
+        return 'Debrief older commits with "ownit interview --range A..B" (or a single commit SHA). They count once verified, never as unverified.';
+    if (changed === 'earlier')
+        return 'New debriefs of older commits no longer count. Ones already verified stay.';
+    if ((changed === 'answers' || changed === 'questions') && !on && !s.show_answers)
+        return 'Answers are hidden, and saved ones are deleted.';
+    if (changed)
+        return '';
+    return 'Change with "ownit settings questions|answers|earlier on|off" (repo admins and maintainers).';
+}
+/**
+ * `ownit settings`: shows this repo's Ownit settings and page link.
+ * `ownit settings questions|answers|earlier on|off` changes one (admins and maintainers).
+ */
+export async function settingsCommand(args) {
+    const out = process.stderr;
+    const [what, value, ...rest] = args;
+    const changed = what;
+    if (changed !== undefined && Object.hasOwn(SETTING, changed) && value === undefined) {
+        out.write(`Add on or off: "ownit settings ${changed} on" or "ownit settings ${changed} off".\n`);
+        return 1;
+    }
+    if (changed !== undefined && (!Object.hasOwn(SETTING, changed) || (value !== 'on' && value !== 'off') || rest.length)) {
+        out.write(USAGE);
+        return 1;
+    }
+    const repo = githubRepo();
+    if (!repo) {
+        out.write('Ownit: no GitHub remote found. Run this in a repo set up with "ownit init".\n');
+        return 1;
+    }
+    const api = createApi();
+    const settings = changed
+        ? await api.request('PUT', '/api/repos/settings', { repo, [SETTING[changed]]: value === 'on' })
+        : await api.request('GET', `/api/repos/settings?repo=${encodeURIComponent(repo)}`);
+    const c = paint(out);
+    out.write(`${c.bold(settings.page_url)}\n${describe(settings)}\n`);
+    const line = note(settings, changed, value === 'on');
+    if (line)
+        out.write(`${c.dim(line)}\n`);
+    return 0;
+}

package/dist/debrief.js

@@ -3,9 +3,12 @@ import { errorMessage, paint, plural, sentence, spinner, wrap } from './ui.js';
 const MAX_ANSWER_CHARS = 2000;
 export const RESUME_HINT = 'Run "ownit interview" when you\'re ready.';
 const KIND_LABEL = { why: 'why', how: 'how', next: "what's next" };
-function isSkip(answer) {
+/** "s" (or the older "skip") stops the debrief for now. */
+function isLater(answer) {
     return /^(s|skip|:skip)$/i.test(answer.trim());
 }
+/** The reason on a debrief the developer stopped with "s", as opposed to one that was cut off. */
+export const LATER = 'later';
 /** Shows a spinner while `work` runs. */
 async function withSpinner(out, text, work) {
     const spin = spinner(out, text);
@@ -48,8 +51,8 @@ async function askUntilPassed(debrief, first) {
             out.write(`\n${c.yellow('Debrief paused.')} ${RESUME_HINT}\n`);
             return { status: 'pending', reason: 'debrief paused' };
         }
-        if (isSkip(answer))
-            return skip(api, out, debrief.session);
+        if (isLater(answer))
+            return later(out);
         let result;
         try {
             result = await withSpinner(out, 'Checking your answer…', () => api.request('POST', '/api/interview/answer', {
@@ -63,6 +66,7 @@ async function askUntilPassed(debrief, first) {
             return failure(out, error);
         }
         debrief.session = result.session;
+        debrief.earlierCredited = result.earlier_credited ?? 0;
         if (result.pass) {
             out.write(`${c.green('✓ Passed.')}\n${c.dim(wrap(result.feedback))}\n`);
             return null;
@@ -100,25 +104,25 @@ export async function runDebrief(api, prompter, target) {
     catch (error) {
         return failure(out, error);
     }
-    out.write(c.dim(`Answer in your own words, up to 5 sentences. Rough is fine. Type "s" to skip.\n`));
-    const debrief = { api, prompter, total: start.total, payload, session: start.session };
+    out.write(c.dim(`Answer in your own words, up to 5 sentences. Rough is fine. Type "s" to stop and finish later.\n`));
+    if (start.answers_public)
+        out.write(c.yellow('Note: this repo shows passing answers on its public Ownit page.\n'));
+    const debrief = { api, prompter, total: start.total, payload, session: start.session, earlierCredited: 0 };
     for (const question of start.questions) {
         const ended = await askUntilPassed(debrief, question);
         if (ended)
             return ended;
     }
     out.write(`\n${c.green(c.bold('✓ Push verified.'))} ${c.dim(`${target.commits.length} ${commitWord} owned. Nice work.`)}\n`);
+    const earlier = debrief.earlierCredited;
+    if (earlier)
+        out.write(c.dim(`${earlier} earlier ${plural(earlier, 'commit')} now ${earlier === 1 ? 'counts' : 'count'} as verified.\n`));
     return { status: 'verified' };
 }
-async function skip(api, out, session) {
-    try {
-        await api.request('POST', '/api/interview/skip', { session });
-    }
-    catch (error) {
-        return failure(out, error);
-    }
-    out.write(`${paint(out).dim('Skipped. This push is recorded as skipped.')}\n`);
-    return { status: 'skipped' };
+/** "s" stops for now. Nothing is recorded: the push stays pending, so it waits in `ownit interview`. */
+function later(out) {
+    out.write(`${paint(out).dim(`Stopped. This push stays unverified until you debrief it. ${RESUME_HINT}`)}\n`);
+    return { status: 'pending', reason: LATER };
 }
 /** Prints a one-line reason. Provider problems stay out of the stats until retried. */
 function failure(out, error) {

package/dist/index.js

@@ -6,18 +6,40 @@ import { initCommand, uninstallCommand } from './commands/init.js';
 import { interviewCommand } from './commands/interview.js';
 import { keyCommand } from './commands/key.js';
 import { loginCommand, logoutCommand, whoamiCommand } from './commands/login.js';
-import { errorMessage } from './ui.js';
+import { settingsCommand } from './commands/settings.js';
+import { closestMatch, errorMessage } from './ui.js';
 /** Every command, in the order `ownit help` lists them. */
 const COMMANDS = {
-    login: { help: [['ownit login [--server URL]', 'Sign in with GitHub (device flow)']], run: loginCommand },
+    login: {
+        help: [['ownit login [--server URL]', 'Sign in with GitHub (device flow)']],
+        details: `Shows a code and opens GitHub. Approve there, and you're signed in.
+Use --server URL only for a self-hosted Ownit server.`,
+        run: loginCommand,
+    },
     logout: { help: [['ownit logout', 'Sign out']], run: logoutCommand },
     whoami: { help: [['ownit whoami', 'Show server, login, and key status']], run: whoamiCommand },
-    init: { help: [['ownit init [--repo owner/name]', 'Install the pre-push hook in this repo']], run: initCommand },
+    init: {
+        help: [['ownit init [--repo owner/name]', 'Install the pre-push hook in this repo']],
+        details: `Run it inside a clone of your GitHub repo. It installs the pre-push hook, registers the
+repo with Ownit, and prints the README badge. The Ownit GitHub App must be installed on the
+repo; if it isn't, init prints the link. Use --repo owner/name when the remote isn't GitHub.`,
+        run: initCommand,
+    },
     interview: {
         help: [
-            ['ownit interview', 'Debrief pushes that are still pending'],
-            ['ownit interview --range A..B', 'Debrief a commit range'],
+            ['ownit interview', 'List waiting pushes and debrief the one you pick'],
+            ['ownit interview --all', 'Debrief every waiting push in turn'],
+            ['ownit interview --range A..B', 'Debrief a commit range, or one commit (SHA)'],
         ],
+        details: `With no options, it lists the pushes waiting for a debrief and asks which one to do:
+  a number   that push           Enter   the newest
+  a          all, one by one     q       quit
+During a debrief, type "s" to stop and finish later.
+
+Older commits (count once verified, if "ownit settings earlier on"):
+  ownit interview --range 8d21b07            just that commit
+  ownit interview --range 7a9e3f1..f3c9a12   every commit after 7a9e3f1, up to f3c9a12
+Find commit IDs with "git log --oneline". Keep ranges small, about the size of a normal push.`,
         run: interviewCommand,
     },
     key: {
@@ -25,30 +47,85 @@ const COMMANDS = {
             ['ownit key set [nebius|nvidia]', 'Save your model API key (stored locally)'],
             ['ownit key clear|status', 'Remove or show it'],
         ],
+        details: `  ownit key set           asks for the provider, then the key at a hidden prompt
+  ownit key set nvidia    an nvapi- key from build.nvidia.com
+  ownit key set nebius    a key from tokenfactory.nebius.com
+Never type the key after the command: it would end up in your shell history.
+NVIDIA_API_KEY or NEBIUS_API_KEY in the environment work too.`,
         run: keyCommand,
     },
-    badge: { help: [['ownit badge', "Print this repo's badge Markdown for your README"]], run: badgeCommand },
+    badge: {
+        help: [['ownit badge', "Print this repo's badge Markdown for your README"]],
+        details: `Paste the output into your README. To copy it straight away:
+  ownit badge | clip      (Windows)
+  ownit badge | pbcopy    (macOS)
+The repo page also has a Copy button.`,
+        run: badgeCommand,
+    },
+    settings: {
+        help: [
+            ['ownit settings', "Show this repo's settings and page link"],
+            ['ownit settings questions on|off', 'Show debrief questions on the page (admins)'],
+            ['ownit settings answers on|off', 'Show passing answers on the page (admins)'],
+            ['ownit settings earlier on|off', 'Count older commits once debriefed (admins)'],
+        ],
+        details: `Anyone who can push sees the settings; admins and maintainers change them.
+  questions   show debrief questions on the repo page (default on)
+  answers     show passing answers there too (default off; off deletes saved ones)
+  earlier     count commits from before Ownit once someone debriefs them (default off)
+Examples:
+  ownit settings answers on
+  ownit settings earlier on
+Private repos never show questions or answers.`,
+        run: settingsCommand,
+    },
     uninstall: { help: [['ownit uninstall', 'Remove the pre-push hook']], run: uninstallCommand },
-    help: { help: [['ownit help', 'Show this help']], run: () => print(helpText()) },
+    help: { help: [['ownit help [command]', 'Show this help, or details for one command']], run: (args) => helpCommand(args) },
     // Not listed: the installed git hook calls `ownit hook pre-push`.
     hook: { run: (args) => hookCommand(args) },
     version: { run: () => print(`${version()}\n`) },
 };
-const ALIASES = { status: 'whoami', '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version' };
+const ALIASES = { interviews: 'interview', setting: 'settings', page: 'settings', status: 'whoami', '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version' };
+const commandName = (name) => (Object.hasOwn(ALIASES, name) ? ALIASES[name] : name);
 function findCommand(name) {
-    const key = Object.hasOwn(ALIASES, name) ? ALIASES[name] : name;
+    const key = commandName(name);
     return Object.hasOwn(COMMANDS, key) ? COMMANDS[key] : undefined;
 }
+const usageLines = (lines) => lines.map(([line, description]) => `  ${line.padEnd(33)}${description}`).join('\n');
+/** One command's usage lines and details. */
+function commandHelp(command) {
+    return `Usage:\n${usageLines(command.help ?? [])}\n${command.details ? `\n${command.details}\n` : ''}`;
+}
+function helpCommand(args) {
+    const [name] = args;
+    if (!name)
+        return print(helpText());
+    const command = findCommand(name);
+    if (!command?.help)
+        return unknownCommand(name);
+    return print(commandHelp(command));
+}
+/** Points a typo at the closest listed command, or prints the full help. */
+function unknownCommand(name) {
+    // Suggest only listed commands, so a typo never points at the hidden hook command.
+    const listed = Object.keys(COMMANDS).filter((key) => COMMANDS[key].help);
+    const guess = closestMatch(name, listed);
+    process.stderr.write(guess
+        ? `Unknown command "${name}". Did you mean "ownit ${guess}"?\nRun "ownit help" to see every command.\n`
+        : `Unknown command "${name}".\n\n${helpText()}`);
+    return 1;
+}
 function helpText() {
-    const usage = Object.values(COMMANDS)
-        .flatMap((command) => command.help ?? [])
-        .map(([line, description]) => `  ${line.padEnd(33)}${description}`)
-        .join('\n');
+    const usage = usageLines(Object.values(COMMANDS).flatMap((command) => command.help ?? []));
     return `ownit: debrief the code you just pushed.
 
+Get started:  ownit login, then ownit key set, then ownit init in your repo.
+After that, just git push: Ownit asks "Debrief now? [Y/n]".
+
 Usage:
 ${usage}
 
+Run "ownit help <command>" (or "ownit <command> --help") for details and examples.
 Set OWNIT_SKIP=1 to push once without a debrief prompt (the push is pending).
 `;
 }
@@ -63,11 +140,21 @@ function print(text) {
 async function main(argv) {
     const [name = 'help', ...args] = argv;
     const command = findCommand(name);
-    if (!command) {
-        process.stderr.write(`Unknown command "${name}".\n\n${helpText()}`);
-        return 1;
+    if (!command)
+        return unknownCommand(name);
+    if (command.help && (args.includes('--help') || args.includes('-h')))
+        return print(commandHelp(command));
+    try {
+        return await command.run(args);
+    }
+    catch (error) {
+        // A mistyped option, e.g. --rnage: say where the right ones are listed.
+        if (error.code?.startsWith('ERR_PARSE_ARGS')) {
+            process.stderr.write(`Ownit: ${errorMessage(error)}\nRun "ownit help ${commandName(name)}" for the options.\n`);
+            return 1;
+        }
+        throw error;
     }
-    return command.run(args);
 }
 main(process.argv.slice(2)).then((code) => {
     process.exitCode = code;

package/dist/ui.js

@@ -95,3 +95,26 @@ export function wrap(text, indent = '  ', width = Math.min(process.stderr.column
         lines.push(line);
     return lines.map((l) => indent + l).join('\n');
 }
+/** Edit distance between two short strings (insert, delete, or replace one character). */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** The candidate a typo most likely meant, or null when none is close. */
+export function closestMatch(typed, candidates) {
+    const word = typed.toLowerCase();
+    let best = null;
+    for (const name of candidates) {
+        const distance = editDistance(word, name);
+        if (distance <= 2 && distance < (best?.distance ?? Infinity))
+            best = { name, distance };
+    }
+    return best?.name ?? null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getownit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Debrief the code you just pushed, in your terminal, with NVIDIA Nemotron.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },