@tsuzuku/arise 0.2.0

package/README.md

@@ -0,0 +1,125 @@
+# Arise (`arise`)
+
+Unified, workplace-agnostic Git worktree and Herdr workspace orchestrator with pluggable project presets.
+
+---
+
+## Features
+
+- **Unified Lifecycle**: Handles git worktree creation, branch resolution, Herdr workspace orchestration, 4-pane quadrant terminal setup, and safe teardown/nuke.
+- **Pluggable Presets**: Built-in support for **Node.js** (`npm`/`yarn`/`pnpm`), **Laravel/PHP** (`composer`, logs, permissions), and **Generic** projects.
+- **Zero-Config Auto-Detection**: Automatically detects project types based on directory markers (`package.json`, `composer.json`, `artisan`, etc.).
+- **Workplace & Repo Agnostic**: Supports standard Git repos and bare repositories (`--git-dir`). Custom environment paths and symlinks are completely configurable via `.ariserc.json` / `.worktreerc.json` / `arise.config.js`.
+- **Full Feature Parity**: Both Node and PHP projects get full `--nuke` / `--cleanup` suites with protected branch safety and Herdr workspace auto-closing.
+
+---
+
+## Installation
+
+```bash
+# Install globally via npm
+npm install -g arise
+
+# Or run directly without installing via npx
+npx arise --branch <branch-name>
+```
+
+Aliases provided: `arise`, `herdr-worktree`, `herder-worktree`, and `hwk`.
+
+---
+
+## Quick Start
+
+### 1. Create a Worktree Session
+```bash
+# Auto-detects project type (Node, Laravel, etc.)
+arise --branch feature/login
+
+# Explicitly specify a preset
+arise --branch feature/login --preset laravel
+
+# Choose your AI CLI agent (e.g. Claude Code, Aider, Antigravity, or Copilot)
+arise --branch feature/login --agent claude
+arise --branch feature/login -a aider
+
+# Specify base branch, custom workspace name, or focus pane
+arise --branch feature/login --source develop --focus claude
+```
+
+### 2. Nuke / Clean Up a Worktree
+```bash
+# Inside a worktree directory (auto-detects current worktree):
+arise --nuke
+
+# From anywhere, by branch or directory name:
+arise --nuke feature-login
+
+# Keep branches, only remove directory:
+arise --nuke feature-login --dir-only
+
+# Delete local branch, keep remote on origin:
+arise --nuke feature-login --keep-remote
+```
+
+### 3. Install AI Agent Skill (Antigravity `agy`, Claude Code, etc.)
+```bash
+# Install globally to ~/.agents/skills and link to ~/.gemini/skills:
+arise --install-skill
+
+# Install locally to workspace (.agents/skills/arise):
+arise --install-skill --local
+```
+
+---
+
+## Customizing via `.ariserc.json` or `arise.config.js`
+
+Place a `.ariserc.json` in your repository root, worktrees base directory, or `~/.config/arise/config.js` (also supports `.worktreerc.json` / `~/.config/herdr-worktree/` for backwards compatibility):
+
+```json
+{
+  "preset": "laravel",
+  "repo": {
+    "bareRepo": "/path/to/bare/repo.git",
+    "worktreesBase": "/path/to/worktrees",
+    "defaultBaseBranch": "main"
+  },
+  "workspace": {
+    "labelPrefix": "[API] ",
+    "agent": "claude",
+    "defaultFocus": "claude"
+  },
+  "scaffold": {
+    "envSource": "/path/to/shared/.env",
+    "symlink": "/var/www/my-app"
+  }
+}
+```
+
+---
+
+## Architecture & Modular Structure
+
+```
+arise/
+├── package.json
+├── index.js               # Main runner module
+├── bin/
+│   └── cli.js             # Executable CLI
+├── lib/
+│   ├── cli.js             # CLI argument parsing & help output
+│   ├── config.js          # Config discovery & preset merging
+│   ├── git.js             # Git worktree & branch operations
+│   ├── herdr.js           # Herdr workspace & pane operations
+│   ├── layout.js          # Declarative terminal layout renderer
+│   ├── context.js         # Lifecycle execution context & helpers
+│   ├── skill.js           # Agent skill installer for agy/claude
+│   └── lifecycle/
+│       ├── create.js      # Worktree creation & layout pipeline
+│       └── nuke.js        # Safe teardown & branch deletion pipeline
+└── presets/
+    ├── index.js           # Preset registry & auto-detection
+    ├── node.js            # Node / JS project preset
+    ├── laravel.js         # Laravel / PHP project preset
+    └── generic.js         # Fallback generic preset
+```

package/arise.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AriseConfig",
+  "description": "Configuration schema for Arise (.ariserc.json / .worktreerc.json)",
+  "type": "object",
+  "properties": {
+    "preset": {
+      "type": "string",
+      "description": "Preset name to use ('node', 'laravel', 'generic' or custom registered preset)"
+    },
+    "repo": {
+      "type": "object",
+      "description": "Repository topology and branch configuration",
+      "properties": {
+        "bareRepo": {
+          "type": ["string", "null"],
+          "description": "Path to bare git repository (e.g. '/path/to/bare/repo.git')"
+        },
+        "worktreesBase": {
+          "type": ["string", "null"],
+          "description": "Base directory where worktrees should be placed (e.g. '/path/to/worktrees')"
+        },
+        "defaultBaseBranch": {
+          "type": "string",
+          "description": "Default base branch to branch off (e.g. 'develop', 'prod', 'main')"
+        },
+        "protectedBranches": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Array of branch names protected against deletion during --nuke"
+        }
+      },
+      "additionalProperties": false
+    },
+    "workspace": {
+      "type": "object",
+      "description": "Herdr workspace naming, agent, and focus configuration",
+      "properties": {
+        "labelPrefix": {
+          "type": "string",
+          "description": "Prefix added to Herdr workspace labels (e.g. '[BE] ')"
+        },
+        "agent": {
+          "type": ["string", "object", "null"],
+          "description": "CLI AI agent to run in the workspace pane ('agy', 'claude', 'aider', 'copilot', 'none', or custom command object)",
+          "properties": {
+            "cmd": {
+              "type": ["string", "null"],
+              "description": "Command to execute the agent"
+            },
+            "title": {
+              "type": "string",
+              "description": "Display title for the agent pane in Herdr"
+            }
+          }
+        },
+        "defaultFocus": {
+          "type": "string",
+          "description": "Default pane to focus upon creation ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell')"
+        }
+      },
+      "additionalProperties": false
+    },
+    "layout": {
+      "type": "array",
+      "description": "Declarative 4-pane quadrant layout definitions",
+      "items": {
+        "type": "object",
+        "required": ["id", "title"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for this pane within the layout"
+          },
+          "title": {
+            "type": "string",
+            "description": "Title displayed on the Herdr pane"
+          },
+          "cmd": {
+            "type": ["string", "null"],
+            "description": "Command to run when pane is opened (e.g. 'vim .', 'npm run dev', 'tail -f ...')"
+          },
+          "position": {
+            "type": "string",
+            "enum": ["root"],
+            "description": "Set to 'root' for the initial root pane"
+          },
+          "from": {
+            "type": "string",
+            "description": "ID of parent pane to split from"
+          },
+          "split": {
+            "type": "string",
+            "enum": ["right", "down"],
+            "description": "Split direction ('right' or 'down')"
+          },
+          "focus": {
+            "type": "boolean",
+            "description": "Whether this pane should receive focus by default"
+          },
+          "isAgent": {
+            "type": "boolean",
+            "description": "Whether this pane is designated as the AI CLI agent pane"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "scaffold": {
+      "type": "object",
+      "description": "Scaffolding options (environment files, symlinks, dependency installation, etc.)",
+      "properties": {
+        "envSource": {
+          "type": ["string", "null"],
+          "description": "Path to .env source file to copy into new worktree"
+        },
+        "symlink": {
+          "type": ["string", "null"],
+          "description": "Path to web server symlink to update to active worktree"
+        },
+        "install": {
+          "type": ["string", "boolean", "null"],
+          "description": "Command to run to install dependencies upon creation (e.g. 'npm install --legacy-peer-deps', 'pnpm install', 'composer install --no-interaction'), or false/null to skip installation."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { run } = require('../index');
+
+run(process.argv.slice(2), process.cwd()).catch(err => {
+  console.error(`Fatal error: ${err.message}`);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,37 @@
+const pkg = require('./package.json');
+const { parseArgs, showUsage } = require('./lib/cli');
+const { resolveConfiguration } = require('./lib/config');
+const { executeCreate } = require('./lib/lifecycle/create');
+const { executeNuke } = require('./lib/lifecycle/nuke');
+
+async function run(argv = process.argv.slice(2), cwd = process.cwd()) {
+  const flags = parseArgs(argv);
+
+  if (flags.showHelp) {
+    showUsage();
+    process.exit(0);
+  }
+
+  if (flags.showVersion) {
+    console.log(`arise v${pkg.version}`);
+    process.exit(0);
+  }
+
+  if (flags.installSkill) {
+    const { installSkill } = require('./lib/skill');
+    installSkill({ scope: flags.skillScope, cwd });
+    process.exit(0);
+  }
+
+  const config = resolveConfiguration(flags, cwd);
+
+  if (flags.isCleanup) {
+    await executeNuke(flags, config, cwd);
+  } else {
+    await executeCreate(flags, config, cwd);
+  }
+}
+
+module.exports = {
+  run,
+};

package/lib/cli.js

@@ -0,0 +1,129 @@
+const path = require('path');
+
+function showUsage() {
+  console.log(`
+Arise - Unified Worktree & Herdr Workspace Orchestrator
+
+Usage:
+  arise --branch <branch> [options]
+  arise --nuke [<worktree dir or branch>] [nuke-options]
+  arise --cleanup [<worktree dir or branch>] [nuke-options]
+
+Creation Arguments:
+  --branch, -b <branch>       (Required for creation) Git branch to create or boot into.
+  --dirname, -d <dirname>     (Optional) Directory name of the worktree. Defaults to sanitized branch name.
+  --workspace, -w <name>      (Optional) Custom Herdr workspace name.
+  --source, -s, --base <src>  (Optional) Base branch if creating a new branch. Defaults to preset default (e.g. 'develop' / 'prod').
+  --preset, -p <preset>       (Optional) Project preset ('node', 'laravel', 'generic', or custom). Auto-detected if omitted.
+  --agent, -a <agent>         (Optional) AI CLI agent to run in workspace ('agy', 'claude', 'aider', 'copilot', etc.).
+  --focus, -f <pane>          (Optional) Pane to focus ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell'). Defaults to active agent or 'agy'.
+
+Nuke / Cleanup Arguments:
+  --nuke, -n [<target>]       Nuke the worktree: closes Herdr workspace, removes worktree directory,
+                              deletes local branch, and deletes remote branch on origin.
+                              (Auto-detects current worktree if omitted inside a worktree directory).
+  --cleanup, -c [<target>]    Alias for --nuke.
+  --dir-only, --keep-branch   (Optional) Only remove the worktree directory; keep local and remote branches.
+  --keep-remote, --local-only (Optional) Delete local branch, but keep remote branch on origin.
+  --force, -f                 (Optional) Force worktree removal even if changes are uncommitted.
+
+Agent Skill Arguments:
+  --install-skill, -i         Install the agent skill for Antigravity (agy), Claude Code, and other AI agents.
+  --global                    (Default) Install skill globally to ~/.agents/skills and ~/.gemini/skills.
+  --local, --workspace        Install skill locally to current workspace (.agents/skills).
+
+General Arguments:
+  --yes, -y                   (Optional) Automatically answer yes to confirmation prompts (e.g. installing Herdr).
+  --help, -h                  Show this help message.
+  --version, -v               Show version information.
+`);
+}
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const flags = {
+    isCleanup: false,
+    cleanupTarget: null,
+    dirOnly: false,
+    keepRemote: false,
+    force: false,
+    yes: false,
+    branch: null,
+    dirname: null,
+    workspaceName: null,
+    source: null,
+    presetName: null,
+    agent: null,
+    focusTarget: null,
+    installSkill: false,
+    skillScope: 'global',
+    showHelp: false,
+    showVersion: false,
+    rawArgs: argv,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === '--help' || arg === '-h') {
+      flags.showHelp = true;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.showVersion = true;
+    } else if (arg === '--install-skill' || arg === '--install-agent-skill' || arg === '--setup-skill' || arg === '-i') {
+      flags.installSkill = true;
+    } else if (arg === '--global') {
+      flags.skillScope = 'global';
+    } else if (arg === '--local' || arg === '--workspace') {
+      flags.skillScope = 'local';
+    } else if (arg === '--nuke' || arg === '-n' || arg === 'nuke' || arg === '--cleanup' || arg === '-c' || arg === 'cleanup') {
+      flags.isCleanup = true;
+      if (argv[i + 1] && !argv[i + 1].startsWith('-')) {
+        flags.cleanupTarget = argv[i + 1];
+        i++;
+      }
+    } else if (arg === '--dir-only' || arg === '--only-dir' || arg === '--keep-branch' || arg === '--keep-branches') {
+      flags.dirOnly = true;
+    } else if (arg === '--keep-remote' || arg === '--local-only') {
+      flags.keepRemote = true;
+    } else if (arg === '--force' || arg === '-f') {
+      flags.force = true;
+    } else if (arg === '--yes' || arg === '-y') {
+      flags.yes = true;
+    } else if (arg === '--branch' || arg === '-b') {
+      flags.branch = argv[i + 1];
+      i++;
+    } else if (arg === '--dirname' || arg === '-d') {
+      flags.dirname = argv[i + 1];
+      i++;
+    } else if (arg === '--workspace' || arg === '--workspace-name' || arg === '-w' || arg === '--name') {
+      flags.workspaceName = argv[i + 1];
+      i++;
+    } else if (arg === '--source' || arg === '--base' || arg === '-s') {
+      flags.source = argv[i + 1];
+      i++;
+    } else if (arg === '--preset' || arg === '-p') {
+      flags.presetName = argv[i + 1];
+      i++;
+    } else if (arg === '--agent' || arg === '-a') {
+      flags.agent = argv[i + 1];
+      i++;
+    } else if (arg.startsWith('--agent=')) {
+      flags.agent = arg.slice(8);
+    } else if (arg === '--focus') {
+      flags.focusTarget = argv[i + 1];
+      i++;
+    } else if (!arg.startsWith('-')) {
+      if (flags.isCleanup && !flags.cleanupTarget) {
+        flags.cleanupTarget = arg;
+      } else if (!flags.branch) {
+        flags.branch = arg;
+      }
+    }
+  }
+
+  return flags;
+}
+
+module.exports = {
+  parseArgs,
+  showUsage,
+};

package/lib/config.js

@@ -0,0 +1,229 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { getPreset, detectPreset } = require('../presets');
+const git = require('./git');
+
+function findConfigFile(searchDirs = []) {
+  const configNames = [
+    '.ariserc.js',
+    'arise.config.js',
+    '.ariserc.json',
+    '.ariserc',
+    '.worktreerc.js',
+    'worktree.config.js',
+    '.worktreerc.json',
+    '.worktreerc',
+  ];
+
+  for (const dir of searchDirs) {
+    if (!dir || !fs.existsSync(dir)) continue;
+    for (const name of configNames) {
+      const fullPath = path.join(dir, name);
+      if (fs.existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+  }
+
+  // Check home directory ~/.config/arise then ~/.config/herdr-worktree
+  const homeConfigDirs = [
+    path.join(os.homedir(), '.config', 'arise'),
+    path.join(os.homedir(), '.config', 'herdr-worktree'),
+  ];
+  for (const homeDir of homeConfigDirs) {
+    for (const name of configNames) {
+      const fullPath = path.join(homeDir, name);
+      if (fs.existsSync(fullPath)) {
+        return fullPath;
+      }
+    }
+  }
+
+  const homeRcFiles = [
+    path.join(os.homedir(), '.ariserc.json'),
+    path.join(os.homedir(), '.worktreerc.json'),
+  ];
+  for (const rcFile of homeRcFiles) {
+    if (fs.existsSync(rcFile)) {
+      return rcFile;
+    }
+  }
+
+  return null;
+}
+
+function loadConfigFile(filePath) {
+  if (!filePath) return {};
+  try {
+    if (filePath.endsWith('.json') || filePath.endsWith('.worktreerc') || filePath.endsWith('.ariserc')) {
+      const content = fs.readFileSync(filePath, 'utf8');
+      return JSON.parse(content);
+    } else {
+      return require(path.resolve(filePath));
+    }
+  } catch (err) {
+    console.warn(`Warning: Failed to load config from "${filePath}": ${err.message}`);
+    return {};
+  }
+}
+
+function resolveConfiguration(flags = {}, cwd = process.cwd()) {
+  const repoRoot = git.getRepoRootDir(cwd);
+  const isBare = git.isBareRepo(repoRoot);
+  const searchDirs = [];
+
+  const addSearchDir = (dir) => {
+    if (dir && !searchDirs.includes(dir)) {
+      searchDirs.push(dir);
+    }
+  };
+
+  let worktrees = [];
+  try {
+    worktrees = git.getWorktrees({ repoDir: repoRoot, bareRepo: isBare ? repoRoot : null });
+  } catch (e) {}
+
+  // 1. Explicit directory if --dirname / -d is passed
+  if (flags.dirname) {
+    const resolvedDir = path.isAbsolute(flags.dirname)
+      ? flags.dirname
+      : path.resolve(repoRoot || cwd, flags.dirname);
+    addSearchDir(resolvedDir);
+  }
+
+  // 2. Directory for the specified branch (--branch / -b)
+  if (flags.branch) {
+    const matchingWt = worktrees.find((wt) => wt.branch === flags.branch);
+    if (matchingWt && matchingWt.path) {
+      addSearchDir(matchingWt.path);
+    }
+    const branchDir = path.resolve(repoRoot || cwd, flags.branch.replace(/\//g, '-'));
+    addSearchDir(branchDir);
+  }
+
+  // 3. Current working directory
+  addSearchDir(cwd);
+
+  // 4. Repository root directory
+  if (repoRoot) {
+    addSearchDir(repoRoot);
+    if (isBare) {
+      addSearchDir(path.dirname(repoRoot));
+    }
+  }
+
+  // 5. Fallback to existing worktrees (prioritizing primary branches like main, master, develop)
+  const primaryBranches = ['main', 'master', 'develop', 'prod', 'staging'];
+  const primaryWts = worktrees.filter((wt) => !wt.isBare && wt.branch && primaryBranches.includes(wt.branch));
+  for (const wt of primaryWts) {
+    if (wt.path) addSearchDir(wt.path);
+  }
+  for (const wt of worktrees) {
+    if (wt.path && !wt.isBare) addSearchDir(wt.path);
+  }
+
+  const configFile = findConfigFile(searchDirs);
+  const fileConfig = loadConfigFile(configFile);
+
+  // 1. Resolve Preset
+  let presetName = flags.presetName || fileConfig.preset;
+  let preset = null;
+  if (presetName) {
+    preset = getPreset(presetName);
+  }
+  if (!preset) {
+    const detectDir = (configFile && path.dirname(configFile)) || cwd;
+    preset = detectPreset(detectDir);
+    if (preset.name === 'generic' && detectDir !== cwd) {
+      preset = detectPreset(cwd);
+    }
+  }
+
+  // 2. Merge Repo Settings
+  const repoConfig = {
+    bareRepo: (fileConfig.repo && fileConfig.repo.bareRepo) || (preset.repo && preset.repo.bareRepo) || (isBare ? repoRoot : null),
+    worktreesBase: (fileConfig.repo && fileConfig.repo.worktreesBase) || (preset.repo && preset.repo.worktreesBase) || null,
+    defaultBaseBranch: (fileConfig.repo && fileConfig.repo.defaultBaseBranch) || (preset.repo && preset.repo.defaultBaseBranch) || 'develop',
+    protectedBranches: (fileConfig.repo && fileConfig.repo.protectedBranches) || (preset.repo && preset.repo.protectedBranches) || ['main', 'master', 'develop', 'prod', 'staging'],
+  };
+
+  // 3. Resolve AI CLI Agent
+  const resolvedAgent = flags.agent
+    || process.env.ARISE_AGENT
+    || (fileConfig.workspace && fileConfig.workspace.agent)
+    || (preset.workspace && preset.workspace.agent)
+    || 'agy';
+
+  // 4. Merge Workspace Settings
+  const defaultFocus = (fileConfig.workspace && fileConfig.workspace.defaultFocus)
+    || (preset.workspace && preset.workspace.defaultFocus)
+    || 'agy';
+
+  const workspaceConfig = {
+    labelPrefix: (fileConfig.workspace && fileConfig.workspace.labelPrefix !== undefined)
+      ? fileConfig.workspace.labelPrefix
+      : (preset.workspace && preset.workspace.labelPrefix !== undefined ? preset.workspace.labelPrefix : ''),
+    agent: resolvedAgent,
+    defaultFocus,
+  };
+
+  // 5. Merge & Customize Layout for Active Agent
+  const baseLayout = fileConfig.layout || preset.layout || [];
+  const layout = baseLayout.map((pane) => {
+    const isAgentPane = pane.isAgent || pane.id === 'agy' || pane.id === 'agent' || pane.id === 'ai';
+    if (!isAgentPane) return { ...pane };
+
+    let agentCmd = pane.cmd;
+    let agentTitle = pane.title;
+
+    if (typeof resolvedAgent === 'string') {
+      const lower = resolvedAgent.toLowerCase().trim();
+      if (lower === 'none' || lower === 'false' || lower === 'null' || lower === 'disabled') {
+        agentCmd = null;
+        agentTitle = 'shell';
+      } else {
+        agentCmd = resolvedAgent;
+        agentTitle = resolvedAgent;
+      }
+    } else if (typeof resolvedAgent === 'object' && resolvedAgent !== null) {
+      agentCmd = resolvedAgent.cmd !== undefined ? resolvedAgent.cmd : (resolvedAgent.command || null);
+      agentTitle = resolvedAgent.title || resolvedAgent.cmd || pane.title;
+    }
+
+    return {
+      ...pane,
+      cmd: agentCmd,
+      title: agentTitle,
+      isAgent: true,
+    };
+  });
+
+  // 5. Merge Scaffolding Settings
+  const scaffoldConfig = {
+    ...(preset.scaffold || {}),
+    ...(fileConfig.scaffold || {}),
+  };
+
+  // 6. Merge Hooks
+  const hooks = {
+    ...(preset.hooks || {}),
+    ...(fileConfig.hooks || {}),
+  };
+
+  return {
+    preset,
+    repo: repoConfig,
+    workspace: workspaceConfig,
+    layout,
+    scaffold: scaffoldConfig,
+    hooks,
+    configFile,
+  };
+}
+
+module.exports = {
+  findConfigFile,
+  loadConfigFile,
+  resolveConfiguration,
+};