@mbluemer_2/gittyup 0.1.2

package/README.md

@@ -0,0 +1,265 @@
+# gittyup
+
+`gittyup` is a filesystem-driven CLI for managing bare Git repositories and linked worktrees under a shared root such as `~/src`.
+
+## Install
+
+From npm:
+
+```bash
+npm install -g @mbluemer_2/gittyup
+```
+
+Or with `pnpm`:
+
+```bash
+pnpm add -g @mbluemer_2/gittyup
+```
+
+From a GitHub release tarball:
+
+```bash
+npm install -g "https://github.com/mbluemer/gittyup/releases/download/vX.Y.Z/gittyup-X.Y.Z.tgz"
+```
+
+Or with `pnpm`:
+
+```bash
+pnpm add -g "https://github.com/mbluemer/gittyup/releases/download/vX.Y.Z/gittyup-X.Y.Z.tgz"
+```
+
+That installs the `gu` binary from the packaged `dist/` output attached to each GitHub release.
+The npm package exposes the same `gu` binary.
+
+## Requirements
+
+- `git` 2.17+
+- `tmux` for `gittyup tmux ...`
+- `fzf` for interactive worktree and tmux pickers
+
+## Root directory
+
+By default, `gittyup` manages projects under `~/src`.
+
+- Override it per command with `--root ~/somewhere`
+- Or set `GITTYUP_ROOT=~/somewhere` to make a different default
+
+## Layout
+
+Each project is stored as:
+
+```text
+~/src/myrepo/
+  repo.git/
+  main/
+  feature-login/
+```
+
+`repo.git` is the canonical bare repository. Linked worktrees live beside it.
+
+## Commands
+
+```bash
+gittyup project list
+gu pl
+gittyup project doctor
+gu pd
+gittyup project init get myrepo
+gu pg myrepo
+gittyup project init set myrepo "pnpm install"
+gu ps myrepo "pnpm install"
+gittyup project init clear myrepo
+gu px myrepo
+gittyup project create myrepo
+gu pc myrepo
+gittyup project clone git@github.com:owner/myrepo.git
+gu pcl git@github.com:owner/myrepo.git
+gittyup project import ~/code/existing-repo existing-repo-managed
+gu pi ~/code/existing-repo existing-repo-managed
+gittyup project rename some-repo-managed some-repo
+gu pr some-repo-managed some-repo
+
+gittyup worktree list
+gu wl
+gittyup worktree list myrepo
+gittyup worktree add
+gu wa
+gittyup worktree add myrepo feature/login --alias feature-login
+gittyup worktree add myrepo fix/bug --from main
+gittyup worktree remove
+gu wr
+gittyup worktree remove myrepo feature-login
+
+gittyup status
+gu st
+gittyup status myrepo
+gu s myrepo
+
+gittyup tmux launch myrepo
+gu tl myrepo
+gittyup tmux launch
+gu tl
+gittyup tmux switch
+gu ts
+```
+
+## Shortcuts
+
+`gu` supports flattened shortcuts for common commands:
+
+```text
+p     -> project
+pl    -> project list
+pd    -> project doctor
+pg    -> project init get
+ps    -> project init set
+px    -> project init clear
+pc    -> project create
+pcl   -> project clone
+pi    -> project import
+pr    -> project rename
+w     -> worktree
+wl    -> worktree list
+wa    -> worktree add
+wr    -> worktree remove
+s/st  -> status
+t     -> tmux
+tl    -> tmux launch
+ts    -> tmux switch
+```
+
+## Options
+
+```bash
+gittyup --root ~/src
+gittyup --json
+```
+
+## Project diagnostics
+
+`gittyup project doctor` inspects every directory under the managed root and
+reports both healthy projects and broken entries that are missing `repo.git` or
+have invalid worktree metadata.
+
+## Project init commands
+
+You can configure a per-project shell command to run whenever `gittyup worktree add`
+creates a new linked worktree.
+
+Example:
+
+```bash
+gittyup project init set gittyup "pnpm install"
+gittyup project init get gittyup
+gittyup project init clear gittyup
+```
+
+- The command runs with the new worktree as its working directory.
+- If the init command fails, the worktree is kept and `gittyup` reports the error.
+- The command is stored in `.gittyup.json` inside the managed project root.
+
+## Interactive worktree add
+
+`gittyup worktree add` can run interactively when arguments are omitted.
+
+- With no arguments, it opens `fzf` to select a project and then prompts for a branch name.
+- With only a project name, it prompts for the branch name.
+- The worktree alias is still derived automatically unless you pass `--alias`.
+
+Example:
+
+```bash
+gittyup worktree add
+gittyup worktree add myrepo
+```
+
+## Interactive worktree remove
+
+`gittyup worktree remove` can also run interactively when arguments are omitted.
+
+- With no arguments, it opens a single `fzf` picker showing worktrees as `<project>:<worktree>`.
+- With only a project name, it opens `fzf` for that project's worktrees using the same `<project>:<worktree>` format.
+- The canonical `main` worktree is protected and cannot be removed.
+
+Example:
+
+```bash
+gittyup worktree remove
+gittyup worktree remove myrepo
+```
+
+## Interactive tmux launch
+
+`gittyup tmux launch` can also run interactively when arguments are omitted.
+
+- With no arguments, it opens `fzf` for all linked worktrees as `<project>:<worktree>`.
+- With only a project name, it opens `fzf` for that project's worktrees using the same format.
+
+Example:
+
+```bash
+gittyup tmux launch
+gittyup tmux launch myrepo
+gu tl
+gu tl myrepo
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm lint
+pnpm dev --help
+pnpm dev project list
+pnpm dev -- project list
+```
+
+Both `pnpm dev project list` and `pnpm dev -- project list` are supported.
+
+## Releases
+
+Updating `package.json` to a new version and merging that change to `main`
+automatically runs the release workflow.
+
+- CI runs lint, tests, and build
+- The workflow creates and pushes the matching `vX.Y.Z` tag
+- `pnpm pack` creates an installable tarball
+- GitHub Releases gets the tarball and `SHA256SUMS.txt` attached automatically
+- The same workflow publishes `@mbluemer_2/gittyup` to npm
+
+You can still create a release manually by pushing a tag like `v0.1.0` yourself.
+
+Version bump policy for agents is documented in `AGENTS.md`.
+
+## Local project bootstrap
+
+`gittyup project create <name>` bootstraps a new local project by:
+
+```text
+1. Creating repo.git
+2. Seeding an initial empty commit on main
+3. Creating the linked main/ worktree
+```
+
+That makes new local projects immediately usable with additional worktrees.
+
+## Import existing repos
+
+`gittyup project import <source> [name]` creates a new managed project from an
+existing local non-bare Git repository.
+
+Example:
+
+```bash
+gittyup project import ~/src/some-repo some-repo-managed
+```
+
+This does not rewrite the source repository in place. It creates a new managed
+project directory under your configured root with `repo.git` and `main/`.
+
+## Rename managed projects
+
+`gittyup project rename <project> <name>` renames the managed project folder and
+repairs the linked worktree metadata for the new paths.

package/dist/aliases.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeArgv = normalizeArgv;
+const COMMAND_ALIASES = {
+    p: ['project'],
+    pl: ['project', 'list'],
+    pd: ['project', 'doctor'],
+    pg: ['project', 'init', 'get'],
+    ps: ['project', 'init', 'set'],
+    px: ['project', 'init', 'clear'],
+    pc: ['project', 'create'],
+    pcl: ['project', 'clone'],
+    pi: ['project', 'import'],
+    pr: ['project', 'rename'],
+    w: ['worktree'],
+    wl: ['worktree', 'list'],
+    wa: ['worktree', 'add'],
+    wr: ['worktree', 'remove'],
+    s: ['status'],
+    st: ['status'],
+    t: ['tmux'],
+    tl: ['tmux', 'launch'],
+    ts: ['tmux', 'switch'],
+};
+function normalizeArgv(argv) {
+    const normalized = argv[2] === '--' ? [argv[0], argv[1], ...argv.slice(3)] : [...argv];
+    const alias = normalized[2] ? COMMAND_ALIASES[normalized[2]] : undefined;
+    if (!alias) {
+        return normalized;
+    }
+    return [normalized[0], normalized[1], ...alias, ...normalized.slice(3)];
+}

package/dist/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const program_1 = require("./program");
+void (0, program_1.runCli)();

package/dist/config.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT_METADATA_FILENAME = exports.MAIN_WORKTREE_ALIAS = exports.BARE_REPO_DIRNAME = exports.DEFAULT_ROOT_DIR = void 0;
+exports.expandHome = expandHome;
+exports.resolveRootDir = resolveRootDir;
+exports.validateProjectName = validateProjectName;
+exports.validateAlias = validateAlias;
+exports.deriveAlias = deriveAlias;
+exports.inferProjectName = inferProjectName;
+exports.validateBranchName = validateBranchName;
+exports.validateRemoteUrl = validateRemoteUrl;
+exports.buildProjectPaths = buildProjectPaths;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+exports.DEFAULT_ROOT_DIR = node_path_1.default.join(node_os_1.default.homedir(), 'src');
+exports.BARE_REPO_DIRNAME = 'repo.git';
+exports.MAIN_WORKTREE_ALIAS = 'main';
+exports.PROJECT_METADATA_FILENAME = '.gittyup.json';
+function expandHome(value) {
+    if (value === '~') {
+        return node_os_1.default.homedir();
+    }
+    if (value.startsWith('~/')) {
+        return node_path_1.default.join(node_os_1.default.homedir(), value.slice(2));
+    }
+    if (value.startsWith('$HOME/')) {
+        return node_path_1.default.join(node_os_1.default.homedir(), value.slice(6));
+    }
+    return value;
+}
+function resolveRootDir(input) {
+    return node_path_1.default.resolve(expandHome(input ?? process.env.GITTYUP_ROOT ?? exports.DEFAULT_ROOT_DIR));
+}
+function validateProjectName(name) {
+    if (name.trim().length === 0) {
+        throw new errors_1.CliError('Project name cannot be empty.');
+    }
+    if (name !== name.trim()) {
+        throw new errors_1.CliError('Project name cannot start or end with whitespace.');
+    }
+    if (/[/\\]/.test(name)) {
+        throw new errors_1.CliError('Project name must be a single directory name.');
+    }
+    if (name === '.' || name === '..') {
+        throw new errors_1.CliError("Project name must not be '.' or '..'.");
+    }
+    return name;
+}
+function validateAlias(alias) {
+    if (alias.trim().length === 0) {
+        throw new errors_1.CliError('Worktree alias cannot be empty.');
+    }
+    if (alias !== alias.trim()) {
+        throw new errors_1.CliError('Worktree alias cannot start or end with whitespace.');
+    }
+    if (/[/\\]/.test(alias)) {
+        throw new errors_1.CliError('Worktree alias must be a single directory name.');
+    }
+    if (alias === '.' || alias === '..') {
+        throw new errors_1.CliError("Worktree alias must not be '.' or '..'.");
+    }
+    return alias;
+}
+function deriveAlias(branch) {
+    const alias = branch
+        .replace(/[/\\]+/g, '-')
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return validateAlias(alias || 'worktree');
+}
+function inferProjectName(remote) {
+    const trimmed = remote.trim().replace(/\/$/, '');
+    const scpTail = trimmed.includes(':') && !trimmed.includes('://')
+        ? trimmed.slice(trimmed.lastIndexOf(':') + 1)
+        : trimmed;
+    const tail = scpTail.split('/').pop() ?? scpTail;
+    const name = tail.endsWith('.git') ? tail.slice(0, -4) : tail;
+    return validateProjectName(name);
+}
+// eslint-disable-next-line no-control-regex
+const INVALID_BRANCH_CHARS = /[\x00-\x1f\x7f~^:?*[\\]/;
+const INVALID_BRANCH_START = /^[./]/;
+const INVALID_BRANCH_END = /[./]$/;
+const INVALID_BRANCH_SEQUENCE = /(\.\.)|(\/\/)|(@\{)/;
+function validateBranchName(branch) {
+    const trimmed = branch.trim();
+    if (trimmed.length === 0) {
+        throw new errors_1.CliError('Branch name cannot be empty.');
+    }
+    if (INVALID_BRANCH_CHARS.test(trimmed)) {
+        throw new errors_1.CliError('Branch name contains invalid characters (control chars, ~, ^, :, ?, *, [, \\).');
+    }
+    if (INVALID_BRANCH_START.test(trimmed)) {
+        throw new errors_1.CliError('Branch name cannot start with . or /.');
+    }
+    if (INVALID_BRANCH_END.test(trimmed)) {
+        throw new errors_1.CliError('Branch name cannot end with . or /.');
+    }
+    if (INVALID_BRANCH_SEQUENCE.test(trimmed)) {
+        throw new errors_1.CliError('Branch name cannot contain "..", "//", or "@{".');
+    }
+    return trimmed;
+}
+function validateRemoteUrl(remote) {
+    const trimmed = remote.trim();
+    if (trimmed.length === 0) {
+        throw new errors_1.CliError('Remote URL cannot be empty.');
+    }
+    return trimmed;
+}
+function buildProjectPaths(rootDir, projectName) {
+    const name = validateProjectName(projectName);
+    const rootPath = node_path_1.default.join(rootDir, name);
+    const gitDir = node_path_1.default.join(rootPath, exports.BARE_REPO_DIRNAME);
+    const metadataPath = node_path_1.default.join(rootPath, exports.PROJECT_METADATA_FILENAME);
+    return {
+        name,
+        rootPath,
+        gitDir,
+        metadataPath,
+    };
+}

package/dist/errors.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliError = void 0;
+exports.toErrorMessage = toErrorMessage;
+class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+exports.CliError = CliError;
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}