gwqadd 0.1.0 → 0.3.0

package/README.md

@@ -16,6 +16,25 @@ Create a branch and its [gwq](https://github.com/d-kuro/gwq) worktree in the rep
 One command instead of: `git checkout -b` → realise you wanted a worktree →
 `gwq add -b` → find where it landed → `cd`.
 
+Run it with no branch name and it asks one question:
+
+```console
+~/ghq/github.com/you/api $ gwqadd
+┌ gwqadd api
+│ repo    api /Users/you/ghq/github.com/you/api
+│ base    main 8f2c1a9
+│
+│ what do you want to do? (any language)
+│ > セッションが期限切れでも通ってしまう不具合を直す
+│
+│ bugfix/expired-session-accepted   off main
+│ create it? [Y]es · [n]o, describe again · [e]dit the name
+└ ✓ bugfix/expired-session-accepted → …
+```
+
+No type menu, no list to choose from. Note the prefix: this repository uses
+`bugfix/`, not `fix/`, and the suggestion followed it without being told.
+
 ## Install
 
 ```sh
@@ -76,6 +95,49 @@ So the fix is one flag:
 gwqadd feat/logout --from main
 ```
 
+## Naming help
+
+One question, one confirmation:
+
+| key | |
+| --- | --- |
+| `Y` / Enter | create it |
+| `n` | describe the work again — the rejected name is excluded next time |
+| `e` | edit the suggested name in place |
+| Esc | give up, create nothing |
+
+**Why the suggestions fit.** The prompt is not just your sentence. It carries:
+
+- this repository's branch prefixes with their counts, so the AI picks the one
+  you actually use — `feature/` over `feat/`, `bugfix/` over `fix/`;
+- up to 20 existing branch names, for wording and length;
+- the repository name and the ref being branched from;
+- the paths you have already modified, if the working tree is dirty — often the
+  clearest signal about what the work is.
+
+**The AI** is whichever of these is on your `PATH`:
+
+```
+claude -p    →    codex exec    →    opencode run    →    gemini -p
+```
+
+No API key to obtain, no account to create — it uses what you already have.
+Expect 6–8 seconds, almost all of it the CLI's own start-up; an elapsed counter
+runs while it works.
+
+| | |
+| --- | --- |
+| pick a different CLI | `--ai 'gemini -p'`, or `GWQADD_AI='gemini -p'` |
+| turn it off | `--no-ai`, or `GWQADD_AI=off` — leaves a plain ASCII-name prompt |
+
+**What is sent, and when.** Nothing leaves your machine until you answer the
+question. At that point the sentence, the repository name, its branch names and
+your modified file *paths* (never contents) go to that CLI. Nothing is created
+until you confirm.
+
+None of this happens when you pass a branch name on the command line, or when
+there is no terminal. Scripts and agents keep the plain, silent contract.
+
 ## What it does
 
 1. Work out which repository you are in — any worktree of it will do.
@@ -107,6 +169,8 @@ gwqadd [options] [<branch>]
 | `--cmd <name>` | function name emitted by `--init` (default: `gwqadd`) |
 | `--from <ref>` | branch from this ref instead of the current HEAD |
 | `--expires <dur>` | hand gwq an expiry (`1h`, `7d`, …) for a throwaway worktree |
+| `--ai <cmd>` | AI CLI used to suggest names (default: autodetected) |
+| `--no-ai` | never ask an AI, even when one is installed |
 | `--no-submodules` | skip `git submodule update --init --recursive` |
 | `-f`, `--force` | move a colliding worktree directory aside instead of failing |
 | `-n`, `--no-cd` | do the work and report the path, but do not move the shell |
@@ -116,7 +180,7 @@ gwqadd [options] [<branch>]
 | `-h`, `--help` | show help |
 | `-V`, `--version` | show version |
 
-Run it with no branch name and it asks for one.
+Run it with no branch name and it asks what you want to do, then confirms once.
 
 ## For scripts and AI agents
 

package/bin/gwqadd.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
+import { spawnSync, spawn } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { Buffer } from 'node:buffer';
 import { readFileSync, existsSync, readdirSync, renameSync, realpathSync } from 'node:fs';
@@ -27,6 +27,8 @@ OPTIONS
   --cmd <name>       function name emitted by --init (default: ${PKG})
   --from <ref>       branch from this ref instead of the current HEAD
   --expires <dur>    hand gwq an expiry (1h, 7d, …) for a throwaway worktree
+  --ai <cmd>         AI CLI used to suggest names (default: autodetected)
+  --no-ai            never ask an AI, even when one is installed
   --no-submodules    skip \`git submodule update --init --recursive\`
   -f, --force        move a colliding worktree directory aside instead of failing
   -n, --no-cd        do the work and report the path, but do not move the shell
@@ -40,9 +42,29 @@ EXAMPLES
   ${PKG} feat/login                  branch off HEAD, worktree, cd
   ${PKG} feat/login --from main      branch off main wherever you happen to be
   ${PKG} hotfix/x --expires 1d       gwq will mark it expired after a day
-  ${PKG}                             asks for the branch name
+  ${PKG}                             describe the work, confirm, done
   ${PKG} -n --json feat/login        machine-readable, shell stays put
 
+NAMING HELP
+  Run ${PKG} with no branch name and it asks one question — what you want to do,
+  in any language. An AI CLI turns that into a branch name and you confirm once:
+
+    Y  create it        n  describe it again        e  edit the name
+
+  There is no type menu. The prompt carries this repository's own prefixes and
+  their counts, a sample of its branch names, and the paths you have already
+  modified, so the AI picks the prefix and the wording that match the repo. A
+  rejected suggestion is passed back as an exclusion, so "n" does not return it.
+
+  The AI is whichever of these is on PATH — claude, codex, opencode, gemini —
+  invoked headlessly. Nothing is sent anywhere until you answer the question,
+  and nothing is created until you confirm. Override with --ai '<cmd>' or
+  GWQADD_AI='<cmd>'; disable with --no-ai or GWQADD_AI=off, which leaves a plain
+  prompt for an ASCII name.
+
+  None of this happens with a branch name on the command line, or without a
+  terminal — scripts and agents keep the plain, silent contract.
+
 WHERE IT BRANCHES FROM
   The current HEAD, exactly like \`git checkout -b\` — which means running this
   inside a feature worktree branches off that feature, not off main. ${PKG}
@@ -106,6 +128,8 @@ try {
       cmd: { type: 'string' },
       from: { type: 'string' },
       expires: { type: 'string' },
+      ai: { type: 'string' },
+      'no-ai': { type: 'boolean' },
       'no-submodules': { type: 'boolean' },
       force: { type: 'boolean', short: 'f' },
       'no-cd': { type: 'boolean', short: 'n' },
@@ -447,12 +471,16 @@ async function confirmYesNo(question) {
   return c === 0x0d || c === 0x0a || c === 0x79 || c === 0x59; // Enter, y, Y
 }
 
-// A line, not a keypress — the branch name needs editing and history. The
-// prompt goes to stderr so stdout stays the path channel (I1).
-async function askLine(question) {
+// A line, not a keypress — a description or a branch name needs editing. The
+// prompt goes to stderr so stdout stays the path channel (I1). `initial`
+// pre-fills the line so "edit this suggestion" starts from the suggestion
+// rather than from an empty prompt.
+async function askLine(question, initial = '') {
   const rl = createInterface({ input: process.stdin, output: stderr, terminal: true });
   try {
-    return (await rl.question(question)).trim();
+    const answer = rl.question(question);
+    if (initial) rl.write(initial);
+    return (await answer).trim();
   } finally {
     rl.close();
   }
@@ -531,6 +559,271 @@ function defaultBranch(dir) {
   return head ? head.replace(/^refs\/remotes\/origin\//, '') : '';
 }
 
+// ── naming (interactive only) ────────────────────────────────────────────────
+
+// Everything about the repository worth telling a model that is choosing a
+// branch name. The point of gathering it here is that the model picks the
+// prefix too — there is no menu, so the convention has to travel in the prompt.
+function repoContext(dir, repo, base) {
+  const refs = gitOut(dir, [
+    'for-each-ref', '--format=%(refname:short)', '--sort=-committerdate',
+    '--count=300', 'refs/heads', 'refs/remotes/origin',
+  ]);
+  const names = new Set();
+  for (let b of refs.split('\n')) {
+    b = b.trim();
+    if (!b || b === 'HEAD' || b === 'origin/HEAD') continue;
+    if (b.startsWith('origin/')) b = b.slice('origin/'.length);
+    names.add(b); // a branch on both local and origin must count once
+  }
+  const counts = new Map();
+  for (const b of names) {
+    const i = b.indexOf('/');
+    if (i <= 0) continue;
+    const p = b.slice(0, i);
+    counts.set(p, (counts.get(p) ?? 0) + 1);
+  }
+  const prefixes = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
+
+  // Work already in progress is the strongest hint there is about what the
+  // branch is for. Paths only — never contents.
+  // Not gitOut(): it trims the whole output, which eats the leading space of
+  // porcelain's first line and takes the first character of that path with it.
+  // Every entry is `XY<space>path`, and a rename is `R <space>old -> new`.
+  const status = git(dir, ['status', '--porcelain', '--untracked-files=no']);
+  const dirty = (status.status === 0 ? status.stdout ?? '' : '')
+    .split('\n')
+    .filter((l) => l.length > 3)
+    .map((l) => l.slice(3))
+    .map((l) => (l.includes(' -> ') ? l.slice(l.indexOf(' -> ') + 4) : l))
+    .map((l) => l.replace(/^"(.*)"$/, '$1').trim()) // porcelain quotes odd paths
+    .filter(Boolean)
+    .slice(0, 20);
+
+  return {
+    name: repo.name,
+    base: base.ref,
+    prefixes,
+    examples: [...names].filter((n) => n.includes('/')).slice(0, 20),
+    dirty,
+  };
+}
+
+function namingPrompt(ctx, description, rejected) {
+  const conventions = ctx.prefixes.length
+    ? `This repository's branch prefixes, most used first — pick one of these unless the work clearly does not fit:\n${
+      ctx.prefixes.map(([p, n]) => `  ${p}/  (${n} branches)`).join('\n')}`
+    : 'This repository has no prefix convention yet. Use a Conventional Commits type: feat, fix, docs, refactor, test, chore or perf.';
+
+  return [
+    'You name git branches. Reply with exactly 3 candidate names, one per line.',
+    'No numbering, no bullets, no quotes, no code fences, no explanation.',
+    `Repository: ${ctx.name}. The branch will be cut from: ${ctx.base}.`,
+    conventions,
+    ctx.examples.length
+      ? `Existing branch names — match their wording and length:\n${ctx.examples.map((e) => `  ${e}`).join('\n')}`
+      : '',
+    ctx.dirty.length
+      ? `Files already modified in the working tree, which is what the work touches:\n${ctx.dirty.map((f) => `  ${f}`).join('\n')}`
+      : '',
+    'Include the prefix and a slash. After it use lowercase ASCII words joined by hyphens. Under 40 characters. Be specific about this change, not generic.',
+    rejected.length
+      ? `These were rejected — do not propose them or close variants:\n${rejected.map((r) => `  ${r}`).join('\n')}`
+      : '',
+    `The work to name, written in the author's own language:\n${description}`,
+  ].filter(Boolean).join('\n\n');
+}
+
+// ── the AI layer ─────────────────────────────────────────────────────────────
+
+// Delegate to whatever agent CLI the user already has, rather than embedding an
+// API client. No key to store, no account to create, no new dependency, and it
+// bills to whatever they already pay for. Order is by how reliably each one
+// answers a bare prompt headlessly.
+const AI_CLIS = [
+  { bin: 'claude', args: ['-p'] },
+  { bin: 'codex', args: ['exec'] },
+  { bin: 'opencode', args: ['run'] },
+  { bin: 'gemini', args: ['-p'] },
+];
+
+// GWQADD_AI may be an absolute path; only the command name is worth showing.
+const aiLabel = (ai) => ai.bin.split('/').pop();
+
+function detectAi() {
+  if (values['no-ai']) return null;
+  const override = values.ai ?? process.env.GWQADD_AI;
+  if (override != null && override !== '') {
+    if (['off', '0', 'false', 'none'].includes(override)) return null;
+    // Split on whitespace only: quoting rules would be a shell of our own.
+    const parts = override.split(/\s+/).filter(Boolean);
+    return { bin: parts[0], args: parts.slice(1) };
+  }
+  return AI_CLIS.find((c) => commandExists(c.bin)) ?? null;
+}
+
+// spawnSync would freeze the terminal for the 6-8 seconds these CLIs take to
+// boot, with no sign of life. Async plus an elapsed counter is the difference
+// between "working" and "hung".
+function runAi(ai, prompt) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(ai.bin, [...ai.args, prompt], { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      return resolve({ ok: false, out: '', err: String(err?.message ?? err) });
+    }
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    const kill = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, 60_000);
+    child.on('error', (e) => {
+      clearTimeout(kill);
+      resolve({ ok: false, out: '', err: String(e?.message ?? e) });
+    });
+    child.on('close', (code) => {
+      clearTimeout(kill);
+      resolve({ ok: code === 0, out, err });
+    });
+  });
+}
+
+async function askAi(ai, prompt) {
+  const started = Date.now();
+  let tick;
+  if (stderrTTY) {
+    tick = setInterval(() => {
+      const s = Math.round((Date.now() - started) / 1000);
+      stderr.write(`\r${dim('│')} ${dim('thinking')} ${dim(`(${aiLabel(ai)}, ${s}s)`)}   `);
+    }, 250);
+  } else {
+    log(`${dim('│')} asking ${aiLabel(ai)}…`);
+  }
+  try {
+    return await runAi(ai, prompt);
+  } finally {
+    if (tick) {
+      clearInterval(tick);
+      stderr.write(`\r${' '.repeat(48)}\r`);
+    }
+  }
+}
+
+const validBranchName = (name) =>
+  !!name && spawnSync('git', ['check-ref-format', '--branch', name], { stdio: 'ignore' }).status === 0;
+
+// Models add bullets, backticks and commentary no matter how firmly asked not
+// to. Keep only things that could actually be branch names, and let git have
+// the final say on each one.
+function parseCandidates(text) {
+  const cleaned = text.split('\n')
+    .map((l) => l.trim())
+    .map((l) => l.replace(/^[-*•]\s*/, ''))
+    .map((l) => l.replace(/^\d+[.)]\s*/, ''))
+    .map((l) => l.replace(/^[`'"]+|[`'"]+$/g, ''))
+    .filter(Boolean)
+    .filter((l) => !/\s/.test(l))
+    .filter((l) => /^[A-Za-z0-9._/-]+$/.test(l));
+
+  const seen = new Set();
+  const out = [];
+  for (const name of cleaned) {
+    if (seen.has(name) || !validBranchName(name)) continue;
+    seen.add(name);
+    out.push(name);
+    if (out.length === 3) break;
+  }
+  return out;
+}
+
+function slugify(s) {
+  return s.trim().toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9./-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/(^[-/]+)|([-/]+$)/g, '');
+}
+
+// This prompt is where the AI path lands when it is unavailable or declined, so
+// a user who was mid-way through describing the work in their own language will
+// type that language here. Slugifying it would silently create a branch named
+// in Japanese; git allows it, but no CI, URL or tab-completion wants it. Say so
+// and point at the two things that do work.
+async function typeItYourself(initial = '') {
+  for (;;) {
+    const raw = await askLine(`${dim('│')} branch name ${dim('(ascii)')}: `, initial);
+    if (!raw) die('E_INTERRUPTED', 'cancelled');
+    if (/[^\x00-\x7F]/.test(raw)) {
+      warn('this prompt takes an ASCII name. Describe the work at the previous prompt to have it translated, or pass a name as an argument to use it verbatim.');
+      initial = '';
+      continue;
+    }
+    const name = slugify(raw);
+    if (validBranchName(name)) return name;
+    warn(`'${name}' is not a valid branch name — try again`);
+    initial = raw;
+  }
+}
+
+// The single checkpoint before anything is created. `n` sends the user back to
+// describing the work, which is what they asked for; `e` is there because a
+// suggestion that is one word off should not cost another round trip.
+async function confirmCreate(name, base) {
+  log(`${dim('│')}`);
+  log(`${dim('│')} ${bold(cyan(name))}   ${dim(`off ${base}`)}`);
+  stderr.write(
+    `${dim('│')} create it? ${dim('[Y]es')} ${dim('·')} ${dim('[n]o, describe again')} ` +
+    `${dim('·')} ${dim('[e]dit the name')} `,
+  );
+  for (;;) {
+    const buf = await waitForKey();
+    if (buf.includes(0x03) || buf[0] === 0x1b) { stderr.write('\n'); die('E_INTERRUPTED', 'cancelled'); }
+    const c = buf[0];
+    if (c === 0x79 || c === 0x59 || c === 0x0d || c === 0x0a) { stderr.write('\n'); return { create: true }; }
+    if (c === 0x6e || c === 0x4e) { stderr.write('\n'); return { again: true }; }
+    if (c === 0x65 || c === 0x45) { stderr.write('\n'); return { edit: true }; }
+  }
+}
+
+// The whole interactive path. Returns a branch name git has already accepted;
+// never runs unless there is a terminal and no positional was given.
+async function composeBranchName(dir, repo, base) {
+  const ai = detectAi();
+  if (!ai) return typeItYourself();
+
+  const ctx = repoContext(dir, repo, base);
+  const rejected = [];
+
+  for (;;) {
+    log(`${dim('│')}`);
+    const description = await askLine(
+      `${dim('│')} what do you want to do? ${dim('(any language)')}\n${dim('│')} ${dim('>')} `,
+    );
+    // An empty answer is the escape hatch out of the AI entirely.
+    if (!description) return typeItYourself();
+
+    const res = await askAi(ai, namingPrompt(ctx, description, rejected));
+    if (!res.ok) {
+      warn(`${aiLabel(ai)} failed — name it yourself instead`);
+      const first = (res.err || '').trim().split('\n')[0];
+      if (first) log(`${dim('│')} ${dim(first.slice(0, 120))}`);
+      return typeItYourself();
+    }
+    const candidates = parseCandidates(res.out);
+    if (candidates.length === 0) {
+      warn(`${aiLabel(ai)} returned nothing usable — name it yourself instead`);
+      return typeItYourself();
+    }
+
+    const choice = await confirmCreate(candidates[0], ctx.base);
+    if (choice.create) return candidates[0];
+    if (choice.edit) return typeItYourself(candidates[0]);
+    // Rejected: remember every suggestion from this round so the next prompt
+    // cannot come back with a near-identical name.
+    rejected.push(...candidates);
+  }
+}
 // ── width / box ──────────────────────────────────────────────────────────────
 
 // Rough East Asian Width: 全角 CJK + 全角ラテン + half-symbols treated as wide.
@@ -643,39 +936,41 @@ async function main() {
   const repo = resolveRepo();
   const cwd = process.cwd();
 
-  let branch = positionals[0];
-  if (!branch) {
-    if (isNonInteractive) {
-      die('E_VALIDATION', 'a branch name is required — `gwqadd <branch>`');
-    }
-    log(`${dim('┌')} ${bold(PKG)} ${dim(repo.name)}`);
-    branch = await askLine(`${dim('│')} new branch: `);
-    if (!branch) die('E_INTERRUPTED', 'cancelled');
-  } else {
-    log(`${dim('┌')} ${bold(PKG)} ${dim(repo.name)}`);
-  }
-
-  // git would reject this later with a less obvious message.
-  const check = spawnSync('git', ['check-ref-format', '--branch', branch], { stdio: 'ignore' });
-  if (check.status !== 0) {
-    die('E_VALIDATION', `'${branch}' is not a valid branch name`);
-  }
-
   const base = resolveBase(cwd, values.from);
-  const branchExisted = hasLocalBranch(cwd, branch);
 
+  // Where you are and what you are cutting from come first — before any naming,
+  // because both are things you would want to correct before investing in a
+  // branch name, and the base especially is easy to get silently wrong.
+  log(`${dim('┌')} ${bold(PKG)} ${dim(repo.name)}`);
   log(`${dim('│')} repo    ${cyan(repo.name)} ${dim(repo.root)}`);
   if (repo.inLinkedWorktree) {
     log(`${dim('│')} cwd     ${dim('a linked worktree of it')} ${dim(repo.cwdTop)}`);
   }
-  if (!branchExisted) {
-    log(`${dim('│')} base    ${cyan(base.ref)} ${dim(base.sha.slice(0, 7))}`);
-    // The silent version of this is the whole reason --from exists: running
-    // inside a feature worktree branches off that feature, not off main.
-    const def = defaultBranch(cwd);
-    if (!values.from && def && base.ref !== def && base.ref !== `origin/${def}`) {
-      warn(`branching from ${base.ref}, not the default branch — pass \`--from ${def}\` if that is not what you meant`);
+  log(`${dim('│')} base    ${cyan(base.ref)} ${dim(base.sha.slice(0, 7))}`);
+  // The silent version of this is the whole reason --from exists: running
+  // inside a feature worktree branches off that feature, not off main.
+  const def = defaultBranch(cwd);
+  if (!values.from && def && base.ref !== def && base.ref !== `origin/${def}`) {
+    warn(`branching from ${base.ref}, not the default branch — pass \`--from ${def}\` if that is not what you meant`);
+  }
+
+  let branch = positionals[0];
+  if (branch) {
+    // git would reject this later with a less obvious message.
+    if (!validBranchName(branch)) {
+      die('E_VALIDATION', `'${branch}' is not a valid branch name`);
+    }
+  } else {
+    if (isNonInteractive) {
+      die('E_VALIDATION', 'a branch name is required — `gwqadd <branch>`');
     }
+    // composeBranchName only ever returns a name git has already accepted.
+    branch = await composeBranchName(cwd, repo, base);
+  }
+
+  const branchExisted = hasLocalBranch(cwd, branch);
+  if (branchExisted) {
+    log(`${dim('│')} ${dim(`${branch} already exists — the base above is not used`)}`);
   }
 
   git(cwd, ['worktree', 'prune'], { stdio: 'ignore' }); // clear hand-deleted leftovers
@@ -695,7 +990,7 @@ async function main() {
   let addArgs;
   if (branchExisted) {
     addArgs = [branch];
-    log(`${dim('│')} ${dim('branch exists — creating its worktree only')}`);
+    log(`${dim('│')} ${dim('creating its worktree only')}`);
   } else if (values.from) {
     const made = git(cwd, ['branch', branch, values.from]);
     if (made.status !== 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gwqadd",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Create a branch and its gwq worktree in the repository you are in, and cd there.",
   "type": "module",
   "bin": {