unirepo-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tadej Satler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# unirepo
+
+[![npm version](https://img.shields.io/npm/v/unirepo-cli)](https://www.npmjs.com/package/unirepo-cli)
+[![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.**
+
+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.
+
+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.
+
+
+## Why unirepo?
+
+**Before unirepo:**
+
+```
+~/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
+```
+
+
+## Quick Start
+
+```bash
+npx unirepo-cli init my-workspace \
+  https://github.com/org/api.git \
+  https://github.com/org/web.git
+```
+
+This creates:
+
+```
+my-workspace/
+├── api/          ← from github.com/org/api
+├── web/          ← from github.com/org/web
+├── AGENTS.md     ← workflow guide for humans and agents
+└── .gitignore
+```
+
+Then work across repos as if they were one:
+
+```bash
+cd my-workspace
+# edit files in api/ and web/
+git add . && git commit -m "feat: update shared types"
+unirepo push
+```
+
+That's it. Each subtree gets pushed to its upstream repo automatically.
+
+
+## Install
+
+```bash
+npm install -g unirepo-cli
+```
+
+Once installed, the command is just `unirepo`:
+
+```bash
+unirepo --version
+```
+
+Or use without installing:
+
+```bash
+npx unirepo-cli <command>
+```
+
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `init <dir> <repo...>` | Create a new workspace from one or more repos |
+| `add <repo>` | Add another repo to the workspace |
+| `pull [subtree...]` | Pull upstream changes into tracked subtrees |
+| `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
+
+```bash
+unirepo init <dir> <repo-url> [repo-url...]
+```
+
+Creates a new git repo at `<dir>`, imports each URL as a subtree, and generates an `AGENTS.md` workflow guide.
+
+| Flag | Effect |
+| --- | --- |
+| `--full-history` | Import full git history (default: squash) |
+
+### add
+
+```bash
+unirepo add <repo-url> [--prefix <name>] [--branch <name>]
+```
+
+Adds a repo to an existing workspace. The directory name defaults to the repo name.
+
+| Flag | Effect |
+| --- | --- |
+| `--prefix <name>` | Override the subtree directory name |
+| `--branch <name>` | Import from a specific upstream branch |
+| `--full-history` | Import full git history |
+
+### pull
+
+```bash
+unirepo pull [subtree...]
+```
+
+Pulls upstream changes. Without arguments, pulls all tracked subtrees.
+
+| Flag | Effect |
+| --- | --- |
+| `--branch <name>` | Pull a specific upstream branch |
+| `--full-history` | Pull full history instead of squash |
+
+### status
+
+```bash
+unirepo status [--json]
+```
+
+Shows tracked subtrees, their upstream branches, the current push branch, and which subtrees have changes.
+
+### branch
+
+```bash
+unirepo branch [name]
+```
+
+With a name: creates and switches to a new branch. Without: shows the current branch and push targets.
+
+### push
+
+```bash
+unirepo push [subtree...] [--dry-run]
+```
+
+Pushes changed subtrees upstream. Without arguments, auto-detects which subtrees have changes.
+
+| Flag | Effect |
+| --- | --- |
+| `--branch <name>` | Override the upstream branch name |
+| `--dry-run` | Show what would run without executing |
+
+
+## How It Works
+
+unirepo is a thin wrapper around [`git subtree`](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_subtree_merge). Each repo you add becomes a directory in your workspace with a matching git remote. When you push, unirepo splits your commits per subtree and pushes each to its upstream.
+
+There's no lock-in — the workspace is a standard git repo. You can always fall back to raw `git subtree` commands.
+
+
+## Development
+
+```bash
+npm test        # run tests
+npm run build   # syntax check
+```
+
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "unirepo-cli",
+  "version": "0.1.0",
+  "description": "CLI tool for creating and managing git-subtree monorepos — run your agents across repos",
+  "type": "module",
+  "bin": {
+    "unirepo": "./src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test",
+    "build": "node --check src/*.js src/commands/*.js"
+  },
+  "keywords": [
+    "git",
+    "subtree",
+    "monorepo",
+    "cli",
+    "developer-tools",
+    "agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Poko18/unirepo.git"
+  },
+  "homepage": "https://github.com/Poko18/unirepo#readme",
+  "bugs": {
+    "url": "https://github.com/Poko18/unirepo/issues"
+  },
+  "author": "Poko18",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,45 @@
+import { git, detectDefaultBranch, extractRepoName } from '../git.js';
+import { validateGitSubtree, validateUrls, validateInsideMonorepo, validateNameAvailable, validateReachable } from '../validate.js';
+import * as ui from '../ui.js';
+
+export async function runAdd({ url, prefix, branch, fullHistory }) {
+  const cwd = process.cwd();
+
+  // ── Preflight ────────────────────────────────────────────────────────────
+  ui.header('Adding repository');
+  ui.blank();
+
+  ui.step(1, 4, 'Running preflight checks...');
+  validateGitSubtree();
+  validateInsideMonorepo(cwd);
+  validateUrls([url]);
+
+  const name = prefix || extractRepoName(url);
+  validateNameAvailable(name, cwd);
+  ui.info(`Checking ${url}...`);
+  validateReachable(url);
+  ui.success('All checks passed');
+
+  // ── Detect branch ────────────────────────────────────────────────────────
+  ui.step(2, 4, branch ? `Using upstream branch for ${name}...` : `Detecting default branch for ${name}...`);
+  const upstreamBranch = branch || detectDefaultBranch(url);
+  ui.repoDetail('Branch', upstreamBranch);
+
+  // ── Add remote + fetch ───────────────────────────────────────────────────
+  ui.step(3, 4, 'Adding remote and fetching...');
+  git(`remote add "${name}" "${url}"`, { cwd, silent: true });
+
+  if (fullHistory) {
+    ui.repoDetail('Mode', 'full history');
+    git(`fetch --no-tags "${name}" "${upstreamBranch}"`, { cwd });
+    git(`subtree add --prefix="${name}" "${name}" "${upstreamBranch}"`, { cwd });
+  } else {
+    ui.repoDetail('Mode', 'shallow + squash');
+    git(`fetch --no-tags --depth 1 "${name}" "${upstreamBranch}"`, { cwd });
+    git(`subtree add --squash --prefix="${name}" "${name}" "${upstreamBranch}"`, { cwd });
+  }
+
+  // ── Done ─────────────────────────────────────────────────────────────────
+  ui.step(4, 4, 'Done!');
+  ui.addSummary(name, url);
+}

package/src/commands/branch.js

@@ -0,0 +1,54 @@
+import { git, getCurrentBranch, getSubtreePrefixes, getRemoteBranch } from '../git.js';
+import { validateInsideMonorepo } from '../validate.js';
+import * as ui from '../ui.js';
+
+export async function runBranch({ name }) {
+  const cwd = process.cwd();
+
+  validateInsideMonorepo(cwd);
+
+  const subtrees = getSubtreePrefixes(cwd);
+  const currentBranch = getCurrentBranch(cwd);
+
+  if (!name) {
+    // No name given — show current state
+    ui.header('Branch');
+    ui.blank();
+    ui.info(`Current branch: ${currentBranch}`);
+    ui.blank();
+    for (const s of subtrees) {
+      const upstream = getRemoteBranch(cwd, s.name) || 'unknown';
+      ui.info(`  ${s.name}  upstream: ${upstream}  push target: ${currentBranch}`);
+    }
+    ui.blank();
+    ui.info('Use "unirepo branch <name>" to switch all subtrees to a new branch.');
+    ui.blank();
+    return;
+  }
+
+  ui.header('Branch');
+  ui.blank();
+
+  if (currentBranch === name) {
+    ui.info(`Already on branch "${name}"`);
+    ui.blank();
+    return;
+  }
+
+  // Create and switch to the new branch locally
+  git(`checkout -b "${name}"`, { cwd, silent: true });
+  ui.success(`Switched to new branch "${name}"`);
+  ui.blank();
+
+  for (const s of subtrees) {
+    ui.success(`${s.name} → push will target "${name}" upstream`);
+  }
+
+  ui.blank();
+  ui.info('Next steps:');
+  ui.info('  1. Make changes in subtree directories');
+  ui.info('  2. Commit in the monorepo');
+  ui.info(`  3. unirepo push`);
+  ui.info('  4. Open one PR per upstream repo');
+  ui.blank();
+}

package/src/commands/init.js

@@ -0,0 +1,95 @@
+import { mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { git, detectDefaultBranch, extractRepoName } from '../git.js';
+import { validateGitSubtree, validateUrls, validateNoDuplicateNames, validateReachable } from '../validate.js';
+import { AGENTS_MD, GITIGNORE } from '../templates.js';
+import * as ui from '../ui.js';
+
+export async function runInit({ dir, repos, fullHistory }) {
+  const absDir = resolve(dir);
+
+  if (existsSync(absDir)) {
+    throw new Error(`Directory "${dir}" already exists. Choose a different name or remove it first.`);
+  }
+
+  // ── Preflight ────────────────────────────────────────────────────────────
+  ui.header('Creating monorepo');
+  ui.blank();
+
+  ui.step(1, 3 + repos.length, 'Running preflight checks...');
+  validateGitSubtree();
+  validateUrls(repos);
+  validateNoDuplicateNames(repos);
+  for (const url of repos) {
+    ui.info(`Checking ${url}...`);
+    validateReachable(url);
+  }
+  ui.success('All checks passed');
+
+  // From here on, clean up the directory if anything fails
+  let created = false;
+  try {
+    // ── Initialize repo ──────────────────────────────────────────────────────
+    ui.step(2, 3 + repos.length, 'Initializing git repository...');
+    mkdirSync(absDir, { recursive: true });
+    created = true;
+    git('init', { cwd: absDir, silent: true });
+    git('commit --allow-empty -m "chore: initial commit"', { cwd: absDir, silent: true });
+    ui.repoDetail('Location', absDir);
+
+    // ── Scaffold files ───────────────────────────────────────────────────────
+    ui.step(3, 3 + repos.length, 'Writing scaffold files...');
+    const scaffoldFiles = [];
+
+    writeFileSync(join(absDir, 'AGENTS.md'), AGENTS_MD);
+    scaffoldFiles.push('AGENTS.md');
+
+    writeFileSync(join(absDir, '.gitignore'), GITIGNORE);
+    scaffoldFiles.push('.gitignore');
+
+    git(`add ${scaffoldFiles.join(' ')}`, { cwd: absDir, silent: true });
+    git('commit -m "chore: add monorepo scaffolding"', { cwd: absDir, silent: true });
+    ui.success(`Wrote ${scaffoldFiles.join(', ')}`);
+
+    // ── Import repos ─────────────────────────────────────────────────────────
+    for (let i = 0; i < repos.length; i++) {
+      const url = repos[i];
+      const name = extractRepoName(url);
+      const stepNum = 4 + i;
+
+      ui.blank();
+      ui.repoStep(stepNum, 3 + repos.length, name, 'Importing');
+      ui.repoDetail('URL', url);
+
+      // Detect default branch
+      const branch = detectDefaultBranch(url);
+      ui.repoDetail('Branch', branch);
+
+      // Add remote
+      git(`remote add "${name}" "${url}"`, { cwd: absDir, silent: true });
+
+      // Fetch
+      if (fullHistory) {
+        ui.repoDetail('Mode', 'full history');
+        git(`fetch --no-tags "${name}" "${branch}"`, { cwd: absDir });
+        git(`subtree add --prefix="${name}" "${name}" "${branch}"`, { cwd: absDir });
+      } else {
+        ui.repoDetail('Mode', 'shallow + squash');
+        git(`fetch --no-tags --depth 1 "${name}" "${branch}"`, { cwd: absDir });
+        git(`subtree add --squash --prefix="${name}" "${name}" "${branch}"`, { cwd: absDir });
+      }
+
+      ui.success(`${name} imported`);
+    }
+  } catch (err) {
+    // Clean up partially created directory so the user can retry
+    if (created) {
+      try { rmSync(absDir, { recursive: true, force: true }); } catch {}
+    }
+    throw err;
+  }
+
+  // ── Summary ──────────────────────────────────────────────────────────────
+  const subtreeNames = repos.map((url) => extractRepoName(url));
+  ui.initSummary(absDir, repos.length, subtreeNames);
+}

package/src/commands/pull.js

@@ -0,0 +1,65 @@
+import { git, getRemoteBranch, getSubtreePrefixes } from '../git.js';
+import { validateGitSubtree, validateInsideMonorepo } from '../validate.js';
+import * as ui from '../ui.js';
+
+export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory }) {
+  const cwd = process.cwd();
+
+  ui.header('Pulling subtrees');
+  ui.blank();
+
+  validateGitSubtree();
+  validateInsideMonorepo(cwd);
+
+  const allPrefixes = getSubtreePrefixes(cwd);
+  let toPull;
+
+  if (requestedSubtrees && requestedSubtrees.length > 0) {
+    const prefixNames = new Set(allPrefixes.map((prefix) => prefix.name));
+    for (const name of requestedSubtrees) {
+      if (!prefixNames.has(name)) {
+        throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
+      }
+    }
+    toPull = allPrefixes.filter((prefix) => requestedSubtrees.includes(prefix.name));
+  } else {
+    toPull = allPrefixes;
+  }
+
+  if (toPull.length === 0) {
+    ui.info('No tracked subtrees found. Nothing to pull.');
+    ui.blank();
+    return;
+  }
+
+  let succeeded = 0;
+  let failed = 0;
+
+  for (let i = 0; i < toPull.length; i++) {
+    const prefix = toPull[i];
+    const upstreamBranch = branch || getRemoteBranch(cwd, prefix.name) || 'main';
+    const squashFlag = fullHistory ? '' : '--squash ';
+
+    ui.repoStep(i + 1, toPull.length, prefix.name, 'Pulling');
+    ui.repoDetail('Branch', upstreamBranch);
+    ui.repoDetail('Mode', fullHistory ? 'full history' : 'squash');
+
+    try {
+      git(`subtree pull ${squashFlag}--prefix="${prefix.name}" "${prefix.name}" "${upstreamBranch}"`, { cwd });
+      ui.success(`${prefix.name} pulled`);
+      succeeded++;
+    } catch (err) {
+      ui.error(`Failed to pull ${prefix.name}: ${err.message}`);
+      failed++;
+    }
+
+    ui.blank();
+  }
+
+  if (failed === 0) {
+    ui.success(`All ${succeeded} subtree(s) pulled`);
+  } else {
+    ui.warning(`${succeeded} pulled, ${failed} failed`);
+  }
+  ui.blank();
+}

package/src/commands/push.js

@@ -0,0 +1,90 @@
+import { git, getCurrentBranch, getSubtreePrefixes, getChangedSubtrees, hasUncommittedChanges } from '../git.js';
+import { validateGitSubtree, validateInsideMonorepo } from '../validate.js';
+import * as ui from '../ui.js';
+
+export async function runPush({ subtrees: requestedSubtrees, branch, dryRun }) {
+  const cwd = process.cwd();
+
+  // ── Preflight ────────────────────────────────────────────────────────────
+  ui.header('Pushing subtrees');
+  ui.blank();
+
+  validateGitSubtree();
+  validateInsideMonorepo(cwd);
+
+  const currentBranch = getCurrentBranch(cwd);
+  const pushBranch = branch || currentBranch;
+
+  // ── Check for uncommitted work ────────────────────────────────────────────
+  const hasUncommitted = hasUncommittedChanges(cwd);
+  if (hasUncommitted) {
+    ui.warning('You have uncommitted changes. Only committed work will be pushed upstream.');
+    ui.info('Commit your changes first, then run push again.');
+    ui.blank();
+  }
+
+  // ── Determine which subtrees to push ─────────────────────────────────────
+  let toPush;
+
+  if (requestedSubtrees && requestedSubtrees.length > 0) {
+    // Validate that requested subtrees exist
+    const allPrefixes = getSubtreePrefixes(cwd);
+    const prefixNames = new Set(allPrefixes.map((p) => p.name));
+    for (const name of requestedSubtrees) {
+      if (!prefixNames.has(name)) {
+        throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
+      }
+    }
+    toPush = allPrefixes.filter((p) => requestedSubtrees.includes(p.name));
+  } else {
+    // Auto-detect changed subtrees
+    toPush = getChangedSubtrees(cwd);
+    if (toPush.length === 0) {
+      ui.info('No changed subtrees detected. Nothing to push.');
+      if (!hasUncommitted) {
+        ui.info('Make changes inside subtree directories and commit before pushing.');
+      }
+      ui.blank();
+      return;
+    }
+  }
+
+  ui.info(`Branch: ${pushBranch}`);
+  ui.info(`Subtrees to push: ${toPush.map((p) => p.name).join(', ')}`);
+  ui.blank();
+
+  // ── Dry run ──────────────────────────────────────────────────────────────
+  if (dryRun) {
+    const commands = toPush.map(
+      (p) => `git subtree push --prefix="${p.name}" "${p.name}" "${pushBranch}"`
+    );
+    ui.dryRun(commands);
+    return;
+  }
+
+  // ── Push each subtree serially ───────────────────────────────────────────
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const prefix of toPush) {
+    ui.pushStart(prefix.name, pushBranch);
+    ui.pushSlow();
+    try {
+      git(`subtree push --prefix="${prefix.name}" "${prefix.name}" "${pushBranch}"`, { cwd });
+      ui.success(`${prefix.name} pushed`);
+      succeeded++;
+    } catch (err) {
+      ui.error(`Failed to push ${prefix.name}: ${err.message}`);
+      failed++;
+    }
+  }
+
+  // ── Summary ──────────────────────────────────────────────────────────────
+  ui.blank();
+  if (failed === 0) {
+    ui.success(`All ${succeeded} subtree(s) pushed to branch "${pushBranch}"`);
+  } else {
+    ui.warning(`${succeeded} pushed, ${failed} failed`);
+  }
+  ui.blank();
+}

package/src/commands/status.js

@@ -0,0 +1,29 @@
+import { getCurrentBranch, getSubtreePrefixes, getChangedSubtrees, getRemoteBranch } from '../git.js';
+import { validateInsideMonorepo } from '../validate.js';
+import * as ui from '../ui.js';
+
+export async function runStatus({ json }) {
+  const cwd = process.cwd();
+
+  validateInsideMonorepo(cwd);
+
+  const branch = getCurrentBranch(cwd);
+  const prefixes = getSubtreePrefixes(cwd);
+  const changed = getChangedSubtrees(cwd);
+  const changedNames = new Set(changed.map((c) => c.name));
+
+  const subtrees = prefixes.map((p) => ({
+    name: p.name,
+    url: p.url,
+    upstream: getRemoteBranch(cwd, p.name) || 'unknown',
+    pushBranch: branch,
+    changed: changedNames.has(p.name),
+  }));
+
+  if (json) {
+    console.log(JSON.stringify({ pushBranch: branch, subtrees }, null, 2));
+    return;
+  }
+
+  ui.subtreeTable(subtrees, branch);
+}