@tsuzuku/arise 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# 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
+
+# Specify base branch or custom workspace name
+arise --branch feature/login --source develop --focus agy
+```
+
+### 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] ",
+    "defaultFocus": "agy"
+  },
+  "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,112 @@
+{
+  "$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 and focus configuration",
+      "properties": {
+        "labelPrefix": {
+          "type": "string",
+          "description": "Prefix added to Herdr workspace labels (e.g. '[BE] ')"
+        },
+        "defaultFocus": {
+          "type": "string",
+          "description": "Default pane to focus upon creation ('agy', '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"
+          }
+        },
+        "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,36 @@
+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 v1.0.0');
+    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,118 @@
+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.
+  --focus, -f <pane>          (Optional) Pane to focus ('agy', 'vim', 'logs', 'server', 'shell'). Defaults to '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:
+  --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,
+    branch: null,
+    dirname: null,
+    workspaceName: null,
+    source: null,
+    presetName: 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 === '--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 === '--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,134 @@
+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 configFile = findConfigFile([cwd, repoRoot]);
+  const fileConfig = loadConfigFile(configFile);
+
+  // 1. Resolve Preset
+  let presetName = flags.presetName || fileConfig.preset;
+  let preset = null;
+  if (presetName) {
+    preset = getPreset(presetName);
+  }
+  if (!preset) {
+    preset = detectPreset(cwd);
+  }
+
+  // 2. Merge Repo Settings
+  const repoConfig = {
+    bareRepo: (fileConfig.repo && fileConfig.repo.bareRepo) || (preset.repo && preset.repo.bareRepo) || 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. Merge Workspace Settings
+  const workspaceConfig = {
+    labelPrefix: (fileConfig.workspace && fileConfig.workspace.labelPrefix !== undefined)
+      ? fileConfig.workspace.labelPrefix
+      : (preset.workspace && preset.workspace.labelPrefix !== undefined ? preset.workspace.labelPrefix : ''),
+    defaultFocus: (fileConfig.workspace && fileConfig.workspace.defaultFocus)
+      || (preset.workspace && preset.workspace.defaultFocus)
+      || 'agy',
+  };
+
+  // 4. Merge Layout
+  const layout = fileConfig.layout || preset.layout || [];
+
+  // 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,
+};

package/lib/context.js

@@ -0,0 +1,113 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawnSync } = require('child_process');
+
+function createContext({
+  worktreePath,
+  repoRoot,
+  bareRepo,
+  branch,
+  source,
+  flags = {},
+  preset = {},
+  config = {},
+}) {
+  const ctx = {
+    worktreePath,
+    repoRoot,
+    bareRepo,
+    branch,
+    source,
+    flags,
+    preset,
+    config,
+
+    log(msg) {
+      console.log(msg);
+    },
+
+    warn(msg) {
+      console.warn(msg);
+    },
+
+    error(msg) {
+      console.error(msg);
+    },
+
+    exec(command, options = {}) {
+      const cwd = options.cwd || worktreePath;
+      const shell = options.shell || '/bin/bash';
+      return execSync(command, {
+        cwd,
+        stdio: 'inherit',
+        shell,
+        ...options,
+      });
+    },
+
+    spawn(command, args = [], options = {}) {
+      const cwd = options.cwd || worktreePath;
+      const shell = options.shell !== undefined ? options.shell : true;
+      return spawnSync(command, args, {
+        cwd,
+        stdio: 'inherit',
+        shell,
+        ...options,
+      });
+    },
+
+    copyFile(src, dst) {
+      const resolvedDst = path.isAbsolute(dst) ? dst : path.join(worktreePath, dst);
+      if (fs.existsSync(src)) {
+        console.log(`Copying from "${src}" to "${resolvedDst}"...`);
+        const dstDir = path.dirname(resolvedDst);
+        if (!fs.existsSync(dstDir)) {
+          fs.mkdirSync(dstDir, { recursive: true });
+        }
+        fs.copyFileSync(src, resolvedDst);
+        return true;
+      } else {
+        console.warn(`Source file "${src}" does not exist to copy.`);
+        return false;
+      }
+    },
+
+    copyFromRoot(relativeSrc, relativeDst = relativeSrc) {
+      if (!repoRoot) {
+        console.warn(`Cannot copy from root: no repo root identified.`);
+        return false;
+      }
+      const src = path.join(repoRoot, relativeSrc);
+      const dst = path.join(worktreePath, relativeDst);
+      return ctx.copyFile(src, dst);
+    },
+
+    setSymlink(symlinkPath, target = worktreePath) {
+      console.log(`==> Updating symlink "${symlinkPath}" -> "${target}"...`);
+      try {
+        if (fs.existsSync(symlinkPath) || fs.lstatSync(symlinkPath).isSymbolicLink()) {
+          const lstat = fs.lstatSync(symlinkPath);
+          if (lstat.isSymbolicLink()) {
+            fs.unlinkSync(symlinkPath);
+          } else {
+            const backupPath = `${symlinkPath}_BAK_${Date.now()}`;
+            console.warn(`==> Warning: "${symlinkPath}" is a directory, not a symlink. Backing up to "${backupPath}"`);
+            fs.renameSync(symlinkPath, backupPath);
+          }
+        }
+        fs.symlinkSync(target, symlinkPath);
+        console.log(`==> Symlink updated: ${symlinkPath} -> ${target}`);
+        return true;
+      } catch (err) {
+        console.error(`==> Failed to update symlink: ${err.message}`);
+        return false;
+      }
+    },
+  };
+
+  return ctx;
+}
+
+module.exports = {
+  createContext,
+};