unirepo-cli 0.1.0

package/src/git.js

@@ -0,0 +1,250 @@
+import { execSync } from 'node:child_process';
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Execute a git command and return trimmed stdout.
+ * @param {string} args - git arguments
+ * @param {object} opts - { cwd, silent, allowFailure }
+ * @returns {string} stdout
+ */
+export function git(args, opts = {}) {
+  const { cwd, silent = false, allowFailure = false } = opts;
+  try {
+    return execSync(`git ${args}`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: silent ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'inherit'],
+    }).trim();
+  } catch (err) {
+    if (allowFailure) return '';
+    // Surface git's stderr so users can see what actually went wrong
+    const stderr = (err.stderr || '').trim();
+    const msg = stderr || err.message;
+    throw new Error(msg);
+  }
+}
+
+/**
+ * Execute a git command and return output as array of lines.
+ */
+export function gitLines(args, opts = {}) {
+  const out = git(args, { ...opts, silent: true });
+  if (!out) return [];
+  return out.split('\n').filter(Boolean);
+}
+
+/**
+ * Check if cwd is inside a git work tree.
+ */
+export function isInsideWorkTree(cwd) {
+  try {
+    const result = execSync('git rev-parse --is-inside-work-tree', {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return result === 'true';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the current branch name.
+ */
+export function getCurrentBranch(cwd) {
+  return git('rev-parse --abbrev-ref HEAD', { cwd, silent: true });
+}
+
+/**
+ * Parse `git remote -v` into [{ name, url }] (fetch entries only).
+ */
+export function getRemotes(cwd) {
+  const lines = gitLines('remote -v', { cwd });
+  const remotes = [];
+  const seen = new Set();
+  for (const line of lines) {
+    const match = line.match(/^(\S+)\s+(\S+)\s+\(fetch\)$/);
+    if (match && !seen.has(match[1])) {
+      seen.add(match[1]);
+      remotes.push({ name: match[1], url: match[2] });
+    }
+  }
+  return remotes;
+}
+
+/**
+ * Detect the default branch of a remote repo via ls-remote.
+ * Falls back to 'main' if detection fails.
+ */
+export function detectDefaultBranch(url) {
+  try {
+    const output = execSync(`git ls-remote --symref "${url}" HEAD`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 30000,
+    });
+    const match = output.match(/ref:\s+refs\/heads\/(\S+)/);
+    if (match) return match[1];
+  } catch {
+    // fall through
+  }
+  return 'main';
+}
+
+/**
+ * Check if `git subtree` command is available.
+ */
+export function hasSubtreeCommand() {
+  try {
+    // `git subtree` with no args prints usage and exits non-zero,
+    // but that still means it's available. A missing command would
+    // throw with a different error (e.g. "is not a git command").
+    execSync('git subtree 2>&1', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: true,
+    });
+    return true;
+  } catch (err) {
+    const output = (err.stdout || '') + (err.stderr || '');
+    // If the output contains usage info, subtree is available
+    if (output.includes('git subtree')) return true;
+    return false;
+  }
+}
+
+/**
+ * List top-level directories that match a remote name (i.e. are subtree prefixes).
+ */
+export function getSubtreePrefixes(cwd) {
+  const remotes = getRemotes(cwd);
+  const remoteNames = new Set(remotes.map((r) => r.name));
+  const prefixes = [];
+  try {
+    const entries = readdirSync(cwd);
+    for (const entry of entries) {
+      if (entry.startsWith('.')) continue;
+      const full = join(cwd, entry);
+      try {
+        if (statSync(full).isDirectory() && remoteNames.has(entry)) {
+          const remote = remotes.find((r) => r.name === entry);
+          prefixes.push({ name: entry, url: remote?.url || '' });
+        }
+      } catch {
+        // skip unreadable entries
+      }
+    }
+  } catch {
+    // empty
+  }
+  return prefixes;
+}
+
+/**
+ * Find the SHA of the last subtree add/pull merge commit for a given prefix.
+ * Subtree merges have messages like "Merge commit '...' as '<prefix>'" or
+ * "Merge commit '...' into ...".
+ */
+function findLastSubtreeMerge(cwd, prefixName) {
+  // Look for the merge commit that added/updated this subtree
+  const lines = execSync(
+    `git log --merges --format=%H -- "${prefixName}"`,
+    { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ).trim();
+  if (!lines) return null;
+  // The first (most recent) merge commit touching this prefix
+  return lines.split('\n')[0].trim();
+}
+
+/**
+ * Get subtree prefixes that have changes (uncommitted or committed since last subtree merge).
+ */
+export function getChangedSubtrees(cwd) {
+  const prefixes = getSubtreePrefixes(cwd);
+  const changed = [];
+
+  for (const prefix of prefixes) {
+    // Check 1: uncommitted/unstaged changes in the working tree
+    let hasUncommitted = false;
+    try {
+      execSync(`git diff --quiet -- "${prefix.name}"`, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      // Also check staged but not yet committed
+      execSync(`git diff --quiet --cached -- "${prefix.name}"`, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      hasUncommitted = true;
+    }
+
+    if (hasUncommitted) {
+      changed.push(prefix);
+      continue;
+    }
+
+    // Check 2: committed changes since the last subtree add/pull merge
+    try {
+      const mergeCommit = findLastSubtreeMerge(cwd, prefix.name);
+      if (mergeCommit) {
+        // Are there any commits after the merge that touch this prefix?
+        const commits = execSync(
+          `git log --oneline "${mergeCommit}..HEAD" -- "${prefix.name}"`,
+          { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+        ).trim();
+        if (commits) {
+          changed.push(prefix);
+        }
+      }
+    } catch {
+      // If we can't determine, don't mark as changed
+    }
+  }
+  return changed;
+}
+
+/**
+ * Get the upstream default branch for a remote (from the fetched tracking refs).
+ * Returns the branch name or null if not found.
+ */
+export function getRemoteBranch(cwd, remoteName) {
+  try {
+    const refs = execSync(`git branch -r --list "${remoteName}/*"`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (!refs) return null;
+    // e.g. "Hello-World/master" → "master"
+    const first = refs.split('\n')[0].trim();
+    const slash = first.indexOf('/');
+    return slash >= 0 ? first.slice(slash + 1) : first;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the working tree has uncommitted (staged or unstaged) changes.
+ */
+export function hasUncommittedChanges(cwd) {
+  try {
+    execSync('git diff --quiet', { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    execSync('git diff --quiet --cached', { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Extract repo name from URL (basename without .git suffix).
+ */
+export function extractRepoName(url) {
+  const base = url.replace(/\/$/, '').split('/').pop() || '';
+  return base.replace(/\.git$/, '');
+}

package/src/index.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import * as ui from './ui.js';
+import { runInit } from './commands/init.js';
+import { runAdd } from './commands/add.js';
+import { runPull } from './commands/pull.js';
+import { runStatus } from './commands/status.js';
+import { runPush } from './commands/push.js';
+import { runBranch } from './commands/branch.js';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+// ── Argument Parsing ───────────────────────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const args = argv.slice(2); // skip node + script
+
+  if (args[0] === '--version' || args[0] === '-v' || args[0] === 'version') {
+    return { command: 'version', positional: [], flags: {} };
+  }
+
+  // Handle top-level --help / -h before command
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    return { command: undefined, positional: [], flags: { help: true } };
+  }
+
+  const command = args[0];
+  const positional = [];
+  const flags = {};
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--full-history') {
+      flags.fullHistory = true;
+    } else if (arg === '--json') {
+      flags.json = true;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
+    } else if (arg === '--prefix' && i + 1 < args.length) {
+      flags.prefix = args[++i];
+    } else if (arg === '--branch' && i + 1 < args.length) {
+      flags.branch = args[++i];
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg.startsWith('-')) {
+      ui.error(`Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { command, positional, flags };
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+
+export async function main() {
+  const { command, positional, flags } = parseArgs(process.argv);
+
+  if (!command || command === 'help' || flags.help) {
+    ui.usage();
+    process.exit(0);
+  }
+
+  switch (command) {
+    case 'version': {
+      ui.version();
+      break;
+    }
+
+    case 'init': {
+      if (positional.length < 2) {
+        ui.error('Usage: unirepo init <dir> <repo-url> [repo-url...]');
+        process.exit(1);
+      }
+      const [dir, ...repos] = positional;
+      await runInit({ dir, repos, fullHistory: flags.fullHistory || false });
+      break;
+    }
+
+    case 'add': {
+      if (positional.length < 1) {
+        ui.error('Usage: unirepo add <repo-url> [--prefix <name>] [--branch <name>] [--full-history]');
+        process.exit(1);
+      }
+      await runAdd({
+        url: positional[0],
+        prefix: flags.prefix,
+        branch: flags.branch,
+        fullHistory: flags.fullHistory || false,
+      });
+      break;
+    }
+
+    case 'pull': {
+      await runPull({
+        subtrees: positional.length > 0 ? positional : undefined,
+        branch: flags.branch,
+        fullHistory: flags.fullHistory || false,
+      });
+      break;
+    }
+
+    case 'status': {
+      await runStatus({ json: flags.json || false });
+      break;
+    }
+
+    case 'push': {
+      await runPush({
+        subtrees: positional.length > 0 ? positional : undefined,
+        branch: flags.branch,
+        dryRun: flags.dryRun || false,
+      });
+      break;
+    }
+
+    case 'branch': {
+      await runBranch({ name: positional[0] });
+      break;
+    }
+
+    default:
+      ui.error(`Unknown command: ${command}`);
+      ui.blank();
+      ui.usage();
+      process.exit(1);
+  }
+}
+
+// Resolve symlinks so this works when invoked via an npm-installed bin symlink
+// (e.g. /usr/local/bin/unirepo → /usr/local/lib/node_modules/unirepo/src/index.js).
+function isDirectRunCheck() {
+  if (!process.argv[1]) return false;
+  try {
+    const realArgv = realpathSync(process.argv[1]);
+    return import.meta.url === pathToFileURL(realArgv).href;
+  } catch {
+    return false;
+  }
+}
+const isDirectRun = isDirectRunCheck();
+
+if (isDirectRun) {
+  main().catch((err) => {
+    ui.error(err.message);
+    process.exit(1);
+  });
+}

package/src/templates.js

@@ -0,0 +1,128 @@
+export const AGENTS_MD = `# Monorepo Workflow
+
+## Model
+
+This repository is a git-subtree monorepo.
+
+- Each top-level subtree directory maps to an upstream repository.
+- Subtree directory names often match git remote names, but verify the mapping before manual subtree commands.
+- Run monorepo commands from the repository root.
+
+## Rules
+
+- Never use regular \`git push\` to publish the monorepo itself as a deployment target.
+- Work in a single monorepo branch and reuse that branch name when pushing subtree branches upstream.
+- Keep changes scoped to the subtree or subtrees you intend to update.
+- Edit files inside subtree directories, not in unrelated top-level folders.
+- Prefer separate commits per subtree unless the change is tightly coupled across repos.
+- Push only subtrees that actually changed.
+- Keep subtree directory, remote name, and pushed branch consistent.
+- Do not mix files from different subtrees in a subtree PR.
+
+## CLI
+
+Preferred when the \`unirepo\` CLI is available:
+
+\`\`\`bash
+unirepo version
+unirepo status
+unirepo branch <branch>
+unirepo pull
+unirepo push --dry-run
+unirepo push
+unirepo add <repo-url> --branch <branch>
+\`\`\`
+
+- \`status\` shows tracked subtrees, upstream branches, the current push branch, and changed files.
+- \`branch <name>\` creates the local branch name you should reuse when pushing subtrees upstream.
+- \`pull\` updates one or more tracked subtrees from upstream before or during your work.
+- \`push --dry-run\` is the safe first step before a real push.
+- \`push\` without subtree names auto-detects changed subtrees. \`push <subtree>\` pushes one subtree.
+- \`add\` imports another repository as a subtree. Use \`--branch\` to import from a non-default upstream branch.
+
+## Workflow
+
+1. Create or reuse one branch name for the work.
+CLI:
+\`\`\`bash
+unirepo branch <branch>
+\`\`\`
+Git:
+\`\`\`bash
+git checkout -b <branch>
+\`\`\`
+
+2. Pull upstream updates when needed.
+CLI:
+\`\`\`bash
+unirepo pull
+\`\`\`
+Git:
+\`\`\`bash
+git subtree pull --prefix=<subtree> <remote-or-url> <branch> --squash
+\`\`\`
+
+3. Make changes inside one or more subtree directories.
+
+4. Commit in the monorepo. Prefer one commit per subtree unless the change is intentionally coupled.
+\`\`\`bash
+git add <subtree>/
+git commit -m "feat(<subtree>): ..."
+\`\`\`
+
+5. Inspect what changed before pushing.
+CLI:
+\`\`\`bash
+unirepo status
+\`\`\`
+Git:
+\`\`\`bash
+git diff --name-only HEAD
+\`\`\`
+
+6. Push only changed subtrees.
+CLI:
+\`\`\`bash
+unirepo push --dry-run
+unirepo push
+unirepo push <subtree>
+\`\`\`
+Git:
+\`\`\`bash
+git subtree push --prefix=<subtree> <remote-or-url> <branch>
+\`\`\`
+
+## Raw Git Subtree
+
+Use these when operating without the CLI:
+
+\`\`\`bash
+# Add a subtree
+git subtree add --prefix=libfoo https://github.com/example/libfoo.git main --squash
+
+# Pull updates from upstream
+git subtree pull --prefix=libfoo https://github.com/example/libfoo.git main --squash
+
+# Push local changes upstream
+git subtree push --prefix=libfoo https://github.com/example/libfoo.git <branch>
+\`\`\`
+
+- If subtree directory and remote name match, the remote name often works in place of the full URL.
+- Reuse the same branch name across the monorepo and each upstream subtree repo.
+
+## PRs
+
+- Open one PR per upstream subtree repo.
+- Use the same branch name in each upstream repo.
+- Target the default branch of the upstream repo unless that repo's workflow says otherwise.
+- Ensure each PR contains only changes from its own subtree.
+`;
+
+export const GITIGNORE = `.DS_Store
+
+.idea/
+.vscode/
+
+*.swp
+*.swo
+`;