getownit 0.1.2 → 0.1.4

package/dist/commands/interview.js

@@ -31,12 +31,21 @@ export async function interviewCommand(argv) {
 function exitCode(outcome) {
     return outcome && (outcome.status === 'verified' || outcome.reason === LATER) ? 0 : 1;
 }
+/** 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.`);
+    }
+}
 /** A range "A..B", or a single commit, which means just that commit. */
 function parseRange(range) {
     const match = range.match(/^(.+?)\.\.(.+)$/);
     if (match)
-        return { base: resolveCommit(match[1]), head: resolveCommit(match[2]) };
-    const head = resolveCommit(range);
+        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) {

package/dist/commands/settings.js

@@ -1,7 +1,7 @@
 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]\n';
+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) {
@@ -18,8 +18,8 @@ function note(s, changed, 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 && !s.show_answers)
-        return 'Saved answers, if any, are deleted.';
+    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).';
@@ -32,6 +32,10 @@ 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;

package/dist/debrief.js

@@ -19,6 +19,32 @@ async function withSpinner(out, text, work) {
         spin.stop();
     }
 }
+/** A provider error worth retrying: the model did not answer in time or failed on its side. */
+const isUnavailable = (error) => error instanceof ApiError && error.isProviderError && error.body.reason === 'unavailable';
+/**
+ * Runs a model request. When the model doesn't answer, it tries once more by
+ * itself, then asks before each further try, so a slow moment never throws
+ * away a debrief in progress.
+ */
+async function withRetry(prompter, request) {
+    const c = paint(prompter.out);
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (!isUnavailable(error))
+                throw error;
+            if (attempt === 1) {
+                prompter.out.write(c.dim('The model did not answer in time. Trying again…\n'));
+                continue;
+            }
+            const again = await prompter.ask(`${c.yellow(error.message)} Try again? [Y/n] `);
+            if (again === null || /^n/i.test(again.trim()))
+                throw error;
+        }
+    }
+}
 function printQuestion(out, question, total, followUp) {
     const c = paint(out);
     const label = `Question ${question.idx + 1}/${total}`;
@@ -55,12 +81,12 @@ async function askUntilPassed(debrief, first) {
             return later(out);
         let result;
         try {
-            result = await withSpinner(out, 'Checking your answer…', () => api.request('POST', '/api/interview/answer', {
+            result = await withRetry(prompter, () => withSpinner(out, 'Checking your answer…', () => api.request('POST', '/api/interview/answer', {
                 session: debrief.session,
                 idx: question.idx,
                 answer: answer.slice(0, MAX_ANSWER_CHARS),
                 ...debrief.payload,
-            }));
+            })));
         }
         catch (error) {
             return failure(out, error);
@@ -92,14 +118,14 @@ export async function runDebrief(api, prompter, target) {
     };
     let start;
     try {
-        start = await withSpinner(out, 'Nemotron is reading your push…', () => api.request('POST', '/api/interview/start', {
+        start = await withRetry(prompter, () => withSpinner(out, 'Nemotron is reading your push…', () => api.request('POST', '/api/interview/start', {
             repo: target.repo,
             base_sha: target.baseSha,
             head_sha: target.headSha,
             changed_lines: target.diff.changedLines,
             push_id: target.pushId,
             ...payload,
-        }));
+        })));
     }
     catch (error) {
         return failure(out, error);

package/dist/index.js

@@ -10,16 +10,36 @@ 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', '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: {
@@ -27,9 +47,21 @@ 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"],
@@ -37,29 +69,63 @@ const COMMANDS = {
             ['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 = { page: 'settings', 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).
 `;
 }
@@ -74,16 +140,21 @@ function print(text) {
 async function main(argv) {
     const [name = 'help', ...args] = argv;
     const command = findCommand(name);
-    if (!command) {
-        // 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;
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getownit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Debrief the code you just pushed, in your terminal, with NVIDIA Nemotron.",
   "license": "MIT",
   "repository": {