unirepo-cli 0.1.0 → 0.2.1

package/README.md

@@ -4,63 +4,102 @@
 [![CI](https://github.com/Poko18/unirepo/actions/workflows/ci.yml/badge.svg)](https://github.com/Poko18/unirepo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**The workspace for cross-repo coding.**
+### One workspace to refactor your whole stack in one go
 
-unirepo turns a set of GitHub repos into a single unified workspace. Edit code across any of them, commit once, and push updates back to their original repos — all in one branch.
+Work across multiple repos like they’re one. Unirepo turns multiple GitHub repositories into a single unified workspace. Edit backend, frontend, and shared code in one tree, commit from one place, and push changes back to each repo using the same branch.
 
-Built for the era of AI coding agents: give your agent one place to work, and let it refactor, ship features, and update shared APIs across your entire stack.
+### Built for AI coding agents
 
+AI agents need full context to make correct changes—not one repo at a time. Unirepo gives them a single workspace to refactor your entire stack, keep changes consistent, and push updates back to each repo.
 
-## Why unirepo?
+### Example task
 
-**Before unirepo:**
+You need to update:
 
-```
-~/work/api        ← clone, checkout branch, edit
-~/work/web        ← clone, checkout same branch, edit
-~/work/shared     ← clone, checkout same branch, edit
-# remember to push all three, open three PRs
-```
-
-**With unirepo:**
-
-```
-~/work/my-workspace/
-├── api/      ← edit
-├── web/      ← edit
-└── shared/   ← edit
-# one commit, one push — all three repos updated
-```
+- `api/` for a new endpoint
+- `web/` for the UI
+- `shared/` for shared types
 
+<table>
+<tr>
+<td width="50%" valign="top">
 
-## Quick Start
+**Without `unirepo`**
 
 ```bash
-npx unirepo-cli init my-workspace \
-  https://github.com/org/api.git \
-  https://github.com/org/web.git
-```
+# clone and branch in each repo
+git clone git@github.com:org/api.git
+git clone git@github.com:org/web.git
+git clone git@github.com:org/shared.git
+
+cd api
+git checkout -b feature-auth
+cd ../web
+git checkout -b feature-auth
+cd ../shared
+git checkout -b feature-auth
+
+# edit in 3 separate checkouts
+
+# commit in each repo
+cd ../api
+git add .
+git commit -m "feat: add auth"
+cd ../web
+git add .
+git commit -m "feat: add auth UI"
+cd ../shared
+git add .
+git commit -m "feat: add auth types"
+
+# push from each repo
+cd ../api
+git push -u origin feature-auth
+cd ../web
+git push -u origin feature-auth
+cd ../shared
+git push -u origin feature-auth
+```
+
+</td>
+<td width="50%" valign="top">
+
+**With `unirepo`**
 
-This creates:
+```bash
+# create one workspace and one branch
+unirepo init my-workspace <repo...>
+cd my-workspace
+unirepo branch feature-auth
 
-```
-my-workspace/
-├── api/          ← from github.com/org/api
-├── web/          ← from github.com/org/web
-├── AGENTS.md     ← workflow guide for humans and agents
-└── .gitignore
-```
+# edit api/, web/, and shared/ together
 
-Then work across repos as if they were one:
+# commit once from the workspace
+git add .
+git commit -m "feat: add auth flow"
 
-```bash
-cd my-workspace
-# edit files in api/ and web/
-git add . && git commit -m "feat: update shared types"
+# push changed subtrees
 unirepo push
 ```
 
-That's it. Each subtree gets pushed to its upstream repo automatically.
+</td>
+</tr>
+</table>
+
+## Same workflow, fewer commands
+
+`unirepo` keeps your upstream repos separate while removing:
+
+- Repo and branch juggling  
+- Repeated setup and commands  
+- Context switching  
+- Inconsistent cross-repo changes  
+
+It enables:
+
+- One place to see the full change  
+- Safe cross-repo refactors  
+- A single workspace for humans and AI
 
 
 ## Install
@@ -82,6 +121,17 @@ npx unirepo-cli <command>
 ```
 
 
+## Why it works well for agents
+
+AI coding agents work best when they can see the full change at once.
+
+- Update backend, frontend, and shared contracts in one pass
+- Commit coordinated changes from one repo
+- Check affected subtrees with `unirepo status`
+- Push only changed subtrees with `unirepo push`
+- Reuse the generated `AGENTS.md` workflow guide
+
+
 ## Commands
 
 | Command | Description |
@@ -92,40 +142,7 @@ npx unirepo-cli <command>
 | `status` | Show subtrees, branches, and what changed |
 | `branch [name]` | Create or show the current push branch |
 | `push [subtree...]` | Push changed subtrees upstream |
-| `version` | Show CLI version |
-
-
-## Workflow
-
-A typical session looks like this:
-
-```bash
-# 1. Create a branch for your work
-unirepo branch feature-auth
-
-# 2. Pull latest upstream changes
-unirepo pull
-
-# 3. Edit files across repos
-vim api/src/auth.js web/src/login.tsx
-
-# 4. Commit in the monorepo
-git add . && git commit -m "feat: add OAuth flow"
-
-# 5. Check what will be pushed
-unirepo status
-unirepo push --dry-run
-
-# 6. Push to upstream repos
-unirepo push
-
-# 7. Open one PR per upstream repo
-```
-
-The branch name you create in the workspace is reused when pushing to each upstream repo.
-
 
-## Command Reference
 
 ### init
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unirepo-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool for creating and managing git-subtree monorepos — run your agents across repos",
   "type": "module",
   "bin": {
@@ -36,6 +36,8 @@
   "author": "Poko18",
   "license": "MIT",
   "dependencies": {
+    "@inquirer/core": "^10.0.0",
+    "@inquirer/prompts": "^7.0.0",
     "chalk": "^5.3.0"
   }
 }

package/src/github.js

@@ -0,0 +1,113 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Thin wrapper around the `gh` CLI. We shell out rather than hitting the
+ * GitHub API directly so we reuse whatever auth the user already has
+ * configured (`gh auth login`) — no token juggling.
+ */
+
+const REPO_FIELDS = 'nameWithOwner,url,pushedAt,description,isPrivate';
+const DEFAULT_LIMIT = 200;
+const SEARCH_LIMIT = 30;
+
+function runGh(args, { timeout = 30000 } = {}) {
+  try {
+    return execSync(`gh ${args}`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout,
+    });
+  } catch (err) {
+    const stderr = (err.stderr || '').trim();
+    throw new Error(stderr || err.message);
+  }
+}
+
+function runGhJson(args, opts) {
+  const out = runGh(args, opts);
+  if (!out.trim()) return [];
+  try {
+    return JSON.parse(out);
+  } catch (err) {
+    throw new Error(`Failed to parse gh output: ${err.message}`);
+  }
+}
+
+/**
+ * Check whether `gh` is installed AND the user is authenticated.
+ * Returns false (not throws) on either failure so callers can branch cleanly.
+ */
+export function isGhAvailable() {
+  try {
+    execSync('gh --version', { stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    return false;
+  }
+  try {
+    execSync('gh auth status', { stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the authenticated user's login (for display in the source menu).
+ * Returns null on failure.
+ */
+export function getAuthenticatedUser() {
+  try {
+    const out = runGh('api user --jq .login');
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List repositories owned by the authenticated user. `gh repo list` returns
+ * results roughly in recently-updated order by default (no --sort flag).
+ */
+export function listPersonalRepos(limit = DEFAULT_LIMIT) {
+  return runGhJson(`repo list --json ${REPO_FIELDS} --limit ${limit}`);
+}
+
+/**
+ * List organizations the authenticated user belongs to.
+ * Returns an array of `{ login }` objects.
+ */
+export function listOrgs() {
+  try {
+    const out = runGh('api user/orgs --jq "[.[] | {login: .login}]"');
+    return JSON.parse(out);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List repositories for a specific organization.
+ */
+export function listOrgRepos(org, limit = DEFAULT_LIMIT) {
+  return runGhJson(`repo list ${org} --json ${REPO_FIELDS} --limit ${limit}`);
+}
+
+/**
+ * Search GitHub repos by a free-text query.
+ */
+export function searchRepos(query, limit = SEARCH_LIMIT) {
+  // gh search repos uses `url` + `name` + `fullName`, not `nameWithOwner`.
+  // Normalize to the same shape the other listers return.
+  const fields = 'fullName,url,pushedAt,description,isPrivate';
+  const escaped = query.replace(/"/g, '\\"');
+  const raw = runGhJson(
+    `search repos "${escaped}" --json ${fields} --limit ${limit}`
+  );
+  return raw.map((r) => ({
+    nameWithOwner: r.fullName,
+    url: r.url,
+    pushedAt: r.pushedAt,
+    description: r.description,
+    isPrivate: r.isPrivate,
+  }));
+}

package/src/index.js

@@ -2,6 +2,7 @@
 
 import * as ui from './ui.js';
 import { runInit } from './commands/init.js';
+import { runInteractiveInit, CancelError } from './interactive.js';
 import { runAdd } from './commands/add.js';
 import { runPull } from './commands/pull.js';
 import { runStatus } from './commands/status.js';
@@ -70,8 +71,15 @@ export async function main() {
     }
 
     case 'init': {
+      if (positional.length === 0) {
+        // No args → interactive setup flow
+        const result = await runInteractiveInit();
+        await runInit(result);
+        break;
+      }
       if (positional.length < 2) {
         ui.error('Usage: unirepo init <dir> <repo-url> [repo-url...]');
+        ui.info('Or run "unirepo init" with no arguments for interactive setup.');
         process.exit(1);
       }
       const [dir, ...repos] = positional;
@@ -144,6 +152,11 @@ const isDirectRun = isDirectRunCheck();
 
 if (isDirectRun) {
   main().catch((err) => {
+    if (err instanceof CancelError) {
+      ui.blank();
+      ui.info(err.message);
+      process.exit(0);
+    }
     ui.error(err.message);
     process.exit(1);
   });

package/src/interactive.js

@@ -0,0 +1,342 @@
+import { input, select, confirm, Separator } from '@inquirer/prompts';
+import {
+  createPrompt,
+  useState,
+  useKeypress,
+  usePagination,
+  usePrefix,
+  makeTheme,
+  isUpKey,
+  isDownKey,
+  isEnterKey,
+} from '@inquirer/core';
+import chalk from 'chalk';
+import * as ui from './ui.js';
+import * as gh from './github.js';
+import { validateUrls, validateReachable } from './validate.js';
+import { extractRepoName } from './git.js';
+
+/**
+ * Sentinel thrown when the user cancels the flow (Ctrl+C, "Cancel" choice,
+ * or answering "no" at the final confirm). Caught by index.js so we exit
+ * quietly instead of printing a stack trace.
+ */
+export class CancelError extends Error {
+  constructor(message = 'Setup cancelled.') {
+    super(message);
+    this.name = 'CancelError';
+  }
+}
+
+/**
+ * Entry point for `unirepo init` when no positional args are given.
+ */
+export async function runInteractiveInit() {
+  ui.interactiveHeader();
+
+  const ghOk = gh.isGhAvailable();
+  const user = ghOk ? gh.getAuthenticatedUser() : null;
+  const orgs = ghOk ? safeListOrgs() : [];
+
+  if (!ghOk) {
+    ui.warning('GitHub CLI (gh) not detected or not authenticated.');
+    ui.info('Install: https://cli.github.com/   then run: gh auth login');
+    ui.info('Falling back to manual URL entry.');
+    ui.blank();
+  }
+
+  /** @type {Map<string, {nameWithOwner: string, url: string, isPrivate?: boolean}>} */
+  const selected = new Map();
+
+  try {
+    while (true) {
+      const action = await select({
+        message: 'Add repos from',
+        choices: buildSourceMenu({ ghOk, user, orgs, count: selected.size }),
+        pageSize: 10,
+      });
+
+      if (action === 'done') break;
+      if (action === 'cancel') throw new CancelError();
+
+      if (action === 'personal') {
+        await pickFromSource(
+          () => gh.listPersonalRepos(),
+          `Personal repos (@${user || 'you'})`,
+          selected,
+        );
+      } else if (action === 'orgs') {
+        const org = await pickOrg(orgs);
+        if (org) {
+          await pickFromSource(
+            () => gh.listOrgRepos(org),
+            `${org} repos`,
+            selected,
+          );
+        }
+      } else if (action === 'search') {
+        await searchFlow(selected);
+      } else if (action === 'paste') {
+        await pasteUrlLoop(selected);
+      }
+    }
+
+    if (selected.size === 0) {
+      throw new CancelError('No repos selected.');
+    }
+
+    ui.blank();
+    const fullHistory = await confirm({
+      message: 'Import full history? (slower, larger clone)',
+      default: false,
+    });
+
+    const firstRepo = selected.values().next().value;
+    const defaultDir = suggestDir(firstRepo);
+    const dir = await input({
+      message: 'Workspace directory name',
+      default: defaultDir,
+      validate: (v) => (v && v.trim() ? true : 'Required'),
+    });
+
+    ui.blank();
+    reviewSummary(dir.trim(), [...selected.values()], fullHistory);
+    const ok = await confirm({ message: 'Proceed?', default: true });
+    if (!ok) throw new CancelError();
+
+    return {
+      dir: dir.trim(),
+      repos: [...selected.keys()],
+      fullHistory,
+    };
+  } catch (err) {
+    if (err && (err.name === 'ExitPromptError' || err instanceof CancelError)) {
+      throw new CancelError(err.message || 'Setup cancelled.');
+    }
+    throw err;
+  }
+}
+
+// ── Source menu ─────────────────────────────────────────────────────────────
+
+function buildSourceMenu({ ghOk, user, orgs, count }) {
+  const choices = [];
+  if (ghOk) {
+    choices.push({
+      name: `Personal${user ? ` (@${user})` : ''}`,
+      value: 'personal',
+    });
+    if (orgs.length > 0) {
+      choices.push({
+        name: `Organizations (${orgs.length})  →`,
+        value: 'orgs',
+      });
+    }
+    choices.push({ name: 'Search GitHub…', value: 'search' });
+  }
+  choices.push({ name: 'Paste URL', value: 'paste' });
+
+  choices.push(new Separator());
+  if (count > 0) {
+    choices.push({ name: `${chalk.green('✔')} Done (${count} selected)`, value: 'done' });
+  }
+  choices.push({ name: `${chalk.red('✖')} Cancel`, value: 'cancel' });
+  return choices;
+}
+
+// ── Custom toggle-list prompt ───────────────────────────────────────────────
+//
+// @inquirer/prompts' built-in checkbox hardcodes space=toggle / enter=submit
+// and prints a summary line on every resolution, which is why a `select`-in-
+// a-loop implementation left trails of `[x] repo` ghost lines behind. A
+// single custom prompt built on @inquirer/core keeps everything on one
+// persistent frame: enter toggles, esc returns, hint sits below the list.
+
+const repoToggleList = createPrompt((config, done) => {
+  const { message, items: initialItems, pageSize = 15 } = config;
+  const theme = makeTheme(config.theme);
+  const prefix = usePrefix({ theme });
+
+  const [items, setItems] = useState(initialItems);
+  const [cursor, setCursor] = useState(0);
+  const [status, setStatus] = useState('idle');
+
+  useKeypress((key) => {
+    if (status === 'done') return;
+    if (isUpKey(key)) {
+      setCursor(cursor > 0 ? cursor - 1 : items.length - 1);
+    } else if (isDownKey(key)) {
+      setCursor(cursor < items.length - 1 ? cursor + 1 : 0);
+    } else if (isEnterKey(key)) {
+      const next = items.map((it, i) =>
+        i === cursor ? { ...it, checked: !it.checked } : it,
+      );
+      setItems(next);
+    } else if (key.name === 'escape') {
+      setStatus('done');
+      done(items.filter((it) => it.checked).map((it) => it.value));
+    }
+  });
+
+  const page = usePagination({
+    items,
+    active: cursor,
+    renderItem: ({ item, isActive }) => {
+      const box = item.checked ? chalk.green('[x]') : chalk.dim('[ ]');
+      const priv = item.isPrivate ? chalk.dim(' [private]') : '';
+      const line = `${box} ${item.nameWithOwner}${priv}`;
+      return isActive ? chalk.cyan(`❯ ${line}`) : `  ${line}`;
+    },
+    pageSize,
+    loop: false,
+  });
+
+  const count = items.filter((it) => it.checked).length;
+  const countText = chalk.dim(`(${count} selected)`);
+
+  if (status === 'done') {
+    // Single residual line — no ghost spam.
+    return `${prefix} ${chalk.bold(message)} ${countText}`;
+  }
+
+  const header = `${prefix} ${chalk.bold(message)} ${countText}`;
+  const hint = chalk.dim('  ↑↓ navigate • ⏎ toggle • esc back');
+  return [`${header}\n${page}`, hint];
+});
+
+// ── Pickers ─────────────────────────────────────────────────────────────────
+
+async function pickFromSource(fetcher, label, selected) {
+  let repos;
+  try {
+    ui.info(`Fetching ${label}…`);
+    repos = fetcher();
+  } catch (err) {
+    ui.error(`Could not fetch ${label}: ${err.message}`);
+    return;
+  }
+  if (!repos || repos.length === 0) {
+    ui.warning(`No repos found in ${label}.`);
+    return;
+  }
+  await runToggleList(label, repos, selected);
+}
+
+async function runToggleList(label, repos, selected) {
+  const items = repos.map((r) => ({
+    ...r,
+    checked: selected.has(r.url),
+    value: r.url,
+  }));
+
+  const picked = await repoToggleList({
+    message: label,
+    items,
+    pageSize: 15,
+  });
+
+  const sourceUrls = new Set(repos.map((r) => r.url));
+  const pickedSet = new Set(picked);
+  for (const url of sourceUrls) {
+    if (pickedSet.has(url)) {
+      const repo = repos.find((r) => r.url === url);
+      selected.set(url, repo);
+    } else if (selected.has(url)) {
+      selected.delete(url);
+    }
+  }
+}
+
+async function pickOrg(orgs) {
+  if (orgs.length === 0) {
+    ui.warning('You are not a member of any organizations.');
+    return null;
+  }
+  return select({
+    message: 'Choose an organization',
+    choices: orgs.map((o) => ({ name: o.login, value: o.login })),
+    pageSize: 12,
+  });
+}
+
+async function searchFlow(selected) {
+  const query = await input({
+    message: 'Search GitHub repos',
+    validate: (v) => (v && v.trim().length >= 2 ? true : 'Enter at least 2 characters'),
+  });
+  let results;
+  try {
+    ui.info(`Searching for "${query}"…`);
+    results = gh.searchRepos(query.trim());
+  } catch (err) {
+    ui.error(`Search failed: ${err.message}`);
+    return;
+  }
+  if (!results || results.length === 0) {
+    ui.warning('No results.');
+    return;
+  }
+  await runToggleList(`Results for "${query}"`, results, selected);
+}
+
+async function pasteUrlLoop(selected) {
+  while (true) {
+    const url = await input({
+      message: 'Repo URL (https:// or git@)',
+      validate: (v) => {
+        if (!v || !v.trim()) return 'Required';
+        try {
+          validateUrls([v.trim()]);
+          return true;
+        } catch (err) {
+          return err.message;
+        }
+      },
+    });
+    const trimmed = url.trim();
+
+    try {
+      ui.info('Checking reachability…');
+      validateReachable(trimmed);
+    } catch (err) {
+      ui.error(err.message.split('\n')[0]);
+      const retry = await confirm({ message: 'Try another URL?', default: true });
+      if (!retry) return;
+      continue;
+    }
+
+    const name = extractRepoName(trimmed);
+    selected.set(trimmed, { nameWithOwner: name, url: trimmed });
+    ui.success(`Added ${name}`);
+
+    const more = await confirm({ message: 'Add another URL?', default: false });
+    if (!more) return;
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function suggestDir(firstRepo) {
+  if (!firstRepo) return 'my-monorepo';
+  const base = firstRepo.nameWithOwner
+    ? firstRepo.nameWithOwner.split('/').pop()
+    : extractRepoName(firstRepo.url);
+  return `${base}-mono`;
+}
+
+function safeListOrgs() {
+  try {
+    return gh.listOrgs();
+  } catch {
+    return [];
+  }
+}
+
+function reviewSummary(dir, repos, fullHistory) {
+  console.log(chalk.bold(`  Review (${repos.length} repo${repos.length === 1 ? '' : 's'} → ./${dir})`));
+  for (const r of repos) {
+    const mode = fullHistory ? chalk.dim('(full history)') : chalk.dim('(shallow)');
+    console.log(`    ${chalk.cyan(r.nameWithOwner || extractRepoName(r.url))} ${mode}`);
+  }
+  console.log();
+}

package/src/ui.js

@@ -29,6 +29,14 @@ export function header(text) {
   console.log(chalk.dim('  ' + '─'.repeat(50)));
 }
 
+export function interactiveHeader() {
+  console.log();
+  console.log(chalk.bold.cyan(`  ${ICON.git}  Unirepo — Interactive setup`));
+  console.log(chalk.dim('  ' + '─'.repeat(50)));
+  console.log(chalk.dim('  Pick repos to bundle into a new subtree monorepo.'));
+  console.log();
+}
+
 export function step(n, total, text) {
   const prefix = chalk.dim(`  [${n}/${total}]`);
   console.log(`${prefix} ${text}`);
@@ -136,6 +144,8 @@ export function initSummary(dir, count, subtreeNames) {
     console.log(chalk.bold('  Next steps:'));
     console.log(`    ${chalk.dim('$')} cd ${dir.includes(' ') ? `"${dir}"` : dir}`);
     console.log(`    ${chalk.dim('$')} unirepo status`);
+    console.log(`    ${chalk.dim('# create a branch to target when pushing upstream')}`);
+    console.log(`    ${chalk.dim('$')} unirepo branch feature-x`);
     console.log(`    ${chalk.dim('# edit files in')} ${subtreeNames.map(n => chalk.cyan(n + '/')).join(', ')}`);
     console.log(`    ${chalk.dim('$')} git add . && git commit -m "feat: ..."`);
     console.log(`    ${chalk.dim('$')} unirepo push --dry-run`);