@tsuzuku/arise 0.2.0

package/presets/generic.js

@@ -0,0 +1,33 @@
+const fs = require('fs');
+const path = require('path');
+
+module.exports = {
+  name: 'generic',
+
+  detect(cwd) {
+    return true; // Fallback preset
+  },
+
+  repo: {
+    defaultBaseBranch: 'main',
+    protectedBranches: ['main', 'master', 'develop', 'prod', 'staging', 'production'],
+  },
+
+  workspace: {
+    labelPrefix: '',
+    defaultFocus: 'agy',
+  },
+
+  layout: [
+    { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
+    { id: 'shell', title: 'shell', cmd: null, split: 'right', from: 'vim' },
+    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'shell', focus: true, isAgent: true },
+  ],
+
+  hooks: {
+    async onScaffold(ctx) {
+      // Copy .env from root if available
+      ctx.copyFromRoot('.env', '.env');
+    },
+  },
+};

package/presets/index.js

@@ -0,0 +1,39 @@
+const nodePreset = require('./node');
+const laravelPreset = require('./laravel');
+const genericPreset = require('./generic');
+
+const builtInPresets = [
+  laravelPreset, // Check Laravel/PHP before generic
+  nodePreset,    // Check Node before generic
+  genericPreset, // Catch-all fallback
+];
+
+function getPreset(name) {
+  if (!name) return null;
+  const normalized = name.toLowerCase().trim();
+  if (normalized === 'php' || normalized === 'laravel' || normalized === 'api' || normalized === 'be') {
+    return laravelPreset;
+  }
+  if (normalized === 'node' || normalized === 'js' || normalized === 'ts' || normalized === 'fe' || normalized === 'react') {
+    return nodePreset;
+  }
+  if (normalized === 'generic' || normalized === 'default') {
+    return genericPreset;
+  }
+  return null;
+}
+
+function detectPreset(cwd = process.cwd()) {
+  for (const preset of builtInPresets) {
+    if (typeof preset.detect === 'function' && preset.detect(cwd)) {
+      return preset;
+    }
+  }
+  return genericPreset;
+}
+
+module.exports = {
+  getPreset,
+  detectPreset,
+  builtInPresets,
+};

package/presets/laravel.js

@@ -0,0 +1,115 @@
+const fs = require('fs');
+const path = require('path');
+const git = require('../lib/git');
+
+module.exports = {
+  name: 'laravel',
+
+  detect(cwd) {
+    return fs.existsSync(path.join(cwd, 'artisan')) || fs.existsSync(path.join(cwd, 'composer.json'));
+  },
+
+  repo: {
+    defaultBaseBranch: 'main',
+    protectedBranches: ['staging', 'prod', 'master', 'main', 'develop'],
+  },
+
+  workspace: {
+    labelPrefix: '',
+    defaultFocus: 'agy',
+  },
+
+  layout: [
+    { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
+    { id: 'logs', title: 'logs', cmd: 'tail -f storage/logs/laravel.log', split: 'right', from: 'vim' },
+    { id: 'shell', title: 'shell', cmd: null, split: 'down', from: 'vim' },
+    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'logs', focus: true, isAgent: true },
+  ],
+
+  hooks: {
+    async onSyncPrimary(ctx) {
+      git.syncPrimaryBranch({
+        branch: ctx.branch,
+        worktreePath: ctx.worktreePath,
+        repoDir: ctx.repoRoot,
+        bareRepo: ctx.bareRepo,
+        protectedBranches: ['staging', 'prod', 'master', 'main', 'develop'],
+      });
+    },
+
+    async onScaffold(ctx) {
+      // 1. Environment (.env) Setup
+      console.log('==> Ensuring .env file...');
+      const rootEnv = ctx.repoRoot ? path.join(ctx.repoRoot, '.env') : null;
+      const targetEnv = path.join(ctx.worktreePath, '.env');
+
+      if (!fs.existsSync(targetEnv)) {
+        if (ctx.config.scaffold && ctx.config.scaffold.envSource && fs.existsSync(ctx.config.scaffold.envSource)) {
+          ctx.copyFile(ctx.config.scaffold.envSource, targetEnv);
+        } else if (rootEnv && fs.existsSync(rootEnv)) {
+          ctx.copyFile(rootEnv, targetEnv);
+        } else {
+          console.warn('==> No .env source found to copy.');
+        }
+      }
+
+      // 2. Dependencies & Initialization
+      console.log('==> Initializing repository (permissions, composer, etc.)...');
+      try {
+        const installCmd = (ctx.config.scaffold && ctx.config.scaffold.install !== undefined)
+          ? ctx.config.scaffold.install
+          : 'composer install --no-interaction';
+
+        if (installCmd) {
+          console.log(`Running dependency installation: "${installCmd}" in "${ctx.worktreePath}"...`);
+          ctx.exec(installCmd);
+        } else {
+          console.log('Skipping composer installation (scaffold.install is disabled).');
+        }
+
+        const permissionsScript = `
+mkdir -p storage/logs
+chmod 777 storage/logs
+touch storage/logs/laravel.log
+chmod 666 storage/logs/laravel.log
+mkdir -p storage/framework/sessions
+chmod o+w storage/framework/sessions
+mkdir -p storage/framework/data
+chmod o+w storage/framework/data
+mkdir -p storage/framework/cache/data
+chmod 777 storage/framework/cache/data
+mkdir -p bootstrap/cache
+chmod 777 bootstrap/cache
+mkdir -p storage/temp
+chmod 777 storage/temp
+if [ -d .githooks ]; then git config core.hooksPath .githooks; fi
+`;
+        ctx.exec(permissionsScript);
+      } catch (err) {
+        console.warn(`==> Warning during repository initialization: ${err.message}`);
+      }
+
+      // 3. Update Web Server Symlink if configured
+      const symlinkPath = ctx.config.scaffold && ctx.config.scaffold.symlink;
+      if (symlinkPath) {
+        ctx.setSymlink(symlinkPath, ctx.worktreePath);
+      }
+    },
+
+    async onPreNuke(ctx) {
+      const symlinkPath = ctx.config.scaffold && ctx.config.scaffold.symlink;
+      if (symlinkPath && fs.existsSync(symlinkPath)) {
+        try {
+          const lstat = fs.lstatSync(symlinkPath);
+          if (lstat.isSymbolicLink()) {
+            const currentTarget = fs.realpathSync(symlinkPath);
+            if (path.resolve(currentTarget) === path.resolve(ctx.worktreePath)) {
+              console.log(`==> Unlinking active web symlink "${symlinkPath}" pointing to nuked worktree...`);
+              fs.unlinkSync(symlinkPath);
+            }
+          }
+        } catch (e) {}
+      }
+    },
+  },
+};

package/presets/node.js

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const path = require('path');
+
+module.exports = {
+  name: 'node',
+
+  detect(cwd) {
+    return fs.existsSync(path.join(cwd, 'package.json'));
+  },
+
+  repo: {
+    defaultBaseBranch: 'develop',
+    protectedBranches: ['main', 'master', 'develop', 'prod', 'staging', 'production'],
+  },
+
+  workspace: {
+    labelPrefix: '',
+    defaultFocus: 'agy',
+  },
+
+  layout: [
+    { id: 'vim', title: 'vim', cmd: 'vim .', position: 'root' },
+    { id: 'server', title: 'npm server', cmd: 'npm run dev', split: 'right', from: 'vim' },
+    { id: 'shell', title: 'shell', cmd: null, split: 'down', from: 'vim' },
+    { id: 'agy', title: 'agy', cmd: 'agy', split: 'down', from: 'server', focus: true, isAgent: true },
+  ],
+
+  hooks: {
+    async onScaffold(ctx) {
+      // 1. Copy .env from root if available
+      ctx.copyFromRoot('.env', '.env');
+
+      // 2. Install dependencies
+      const installCmd = (ctx.config.scaffold && ctx.config.scaffold.install !== undefined)
+        ? ctx.config.scaffold.install
+        : 'npm install';
+
+      if (installCmd) {
+        console.log(`Running dependency installation: "${installCmd}" in "${ctx.worktreePath}"...`);
+        try {
+          ctx.exec(installCmd);
+        } catch (err) {
+          console.warn(`Warning: Dependency installation exited with an error: ${err.message}`);
+        }
+      } else {
+        console.log('Skipping dependency installation (scaffold.install is disabled).');
+      }
+    },
+  },
+};

package/skills/arise/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: arise
+description: User guide, CLI reference, and command executor for the `arise` utility (Git worktree and Herdr workspace orchestrator). Activate this skill whenever the user asks questions about how to use arise, how worktree orchestration works, how to configure `.ariserc.json` or `.worktreerc.json`, or asks the assistant to create, switch to, or nuke/clean up Git worktrees and Herdr workspaces on their behalf.
+---
+
+# Arise Operator & Assistant Guide
+
+Use this skill to answer questions about `arise` and run worktree management commands on the user's behalf.
+
+---
+
+## 1. CLI Quick Reference & Cheatsheet
+
+### Creating Worktrees
+```bash
+# Create or open a worktree for a branch (auto-detects preset, boots Herdr workspace)
+arise --branch <branch-name>
+
+# Create worktree based off a specific base branch (e.g. develop, prod, main)
+arise --branch <branch-name> --base <base-branch>
+
+# Custom directory name or workspace name
+arise -b <branch-name> -d <dir-name> -w <workspace-name>
+
+# Explicit preset or pane focus ('agy', 'vim', 'logs', 'server', 'shell')
+arise -b <branch-name> --preset laravel --focus agy
+```
+
+### Nuking / Teardown
+```bash
+# Nuke active worktree (when run inside a worktree directory)
+arise --nuke
+
+# Nuke specific worktree by branch or directory name
+arise --nuke <branch-or-dir>
+
+# Remove directory only (keep local and remote git branches)
+arise --nuke <target> --dir-only
+
+# Delete local branch and directory, but keep remote branch on origin
+arise --nuke <target> --keep-remote
+
+# Force removal even if uncommitted changes exist
+arise --nuke <target> --force
+```
+
+---
+
+## 2. Configuration (`.ariserc.json` / `.worktreerc.json` / `arise.config.js`)
+
+Projects can configure custom topology, bare repos, and layouts via `.ariserc.json` or `.worktreerc.json` in the repository root or base directory:
+
+```json
+{
+  "preset": "laravel",
+  "repo": {
+    "bareRepo": "/path/to/bare.git",
+    "worktreesBase": "/path/to/worktrees",
+    "defaultBaseBranch": "develop",
+    "protectedBranches": ["main", "master", "develop", "prod", "staging"]
+  },
+  "workspace": {
+    "labelPrefix": "[API] ",
+    "defaultFocus": "agy"
+  },
+  "scaffold": {
+    "envSource": "/path/to/shared/.env",
+    "symlink": "/path/to/webserver/symlink",
+    "install": "composer install --no-interaction"
+  }
+}
+```
+
+---
+
+## 3. How to Assist the User
+
+### When the User Asks Questions:
+1. Consult the CLI options and configuration schema above.
+2. If working inside a repository with local documentation or `.ariserc.json` / `.worktreerc.json`, inspect those files.
+3. Provide clear explanations with executable CLI examples and config snippets.
+
+### When the User Asks You to Perform an Action:
+1. Formulate the appropriate `arise` CLI command.
+2. Execute the command on behalf of the user using the available command runner.
+3. Confirm the status of the created or nuked worktree and Herdr workspace.

package/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Arise - Type Definitions
+ * 
+ * Provides strict structural contracts for presets, configuration,
+ * declarative layouts, execution context, and lifecycle hooks.
+ */
+
+export interface CliFlags {
+  isCleanup: boolean;
+  cleanupTarget: string | null;
+  dirOnly: boolean;
+  keepRemote: boolean;
+  force: boolean;
+  yes: boolean;
+  branch: string | null;
+  dirname: string | null;
+  workspaceName: string | null;
+  source: string | null;
+  presetName: string | null;
+  agent: string | null;
+  focusTarget: string | null;
+  installSkill: boolean;
+  skillScope: 'global' | 'local' | null;
+  showHelp: boolean;
+  showVersion: boolean;
+  rawArgs: string[];
+}
+
+export type SplitDirection = 'right' | 'down';
+
+export interface PaneDefinition {
+  /** Unique ID for the pane within this layout */
+  id: string;
+  /** Display title for the pane in Herdr */
+  title: string;
+  /** Command to execute upon creation (or null for empty shell) */
+  cmd: string | null;
+  /** Position if this is the root pane ('root') */
+  position?: 'root';
+  /** ID of parent pane from which to split */
+  from?: string;
+  /** Direction to split ('right' | 'down') */
+  split?: SplitDirection;
+  /** Whether to focus this pane by default */
+  focus?: boolean;
+  /** Whether this pane is designated as the AI CLI agent pane */
+  isAgent?: boolean;
+}
+
+export interface RepoConfig {
+  /** Path to bare repository (if using bare git topology) */
+  bareRepo?: string | null;
+  /** Base directory where worktrees should be placed */
+  worktreesBase?: string | null;
+  /** Default base branch to branch off (e.g. 'develop', 'prod', 'main') */
+  defaultBaseBranch?: string;
+  /** Array of branch names protected against deletion */
+  protectedBranches?: string[];
+}
+
+export interface WorkspaceConfig {
+  /** Prefix added to Herdr workspace labels (e.g. '[BE] ') */
+  labelPrefix?: string;
+  /** CLI AI agent to run in the workspace pane ('agy', 'claude', 'aider', 'copilot', 'none', etc.) */
+  agent?: string | { cmd: string; title?: string; [key: string]: any } | null;
+  /** Default pane to focus ('agent', 'agy', 'claude', 'vim', 'logs', 'server', 'shell') */
+  defaultFocus?: string;
+}
+
+export interface ScaffoldConfig {
+  /** Path to environment file (.env) to copy */
+  envSource?: string | null;
+  /** Target symlink path to point to the active worktree (e.g. '/var/www/my-app') */
+  symlink?: string | null;
+  /** Command to run to install dependencies upon creation, or false/null to skip installation */
+  install?: string | boolean | null;
+  [key: string]: any;
+}
+
+export interface ExecutionContext {
+  /** Target worktree absolute directory */
+  worktreePath: string;
+  /** Repository root directory */
+  repoRoot: string | null;
+  /** Bare repo directory (if applicable) */
+  bareRepo: string | null;
+  /** Target branch name */
+  branch: string;
+  /** Base source branch */
+  source: string;
+  /** Parsed CLI flags */
+  flags: CliFlags;
+  /** Active preset */
+  preset: Preset;
+  /** Merged configuration */
+  config: WorktreeConfig;
+
+  log(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+
+  /** Execute a shell command synchronously */
+  exec(command: string, options?: import('child_process').ExecSyncOptions): Buffer | string;
+  /** Spawn a process synchronously with stdio inherit */
+  spawn(command: string, args?: string[], options?: import('child_process').SpawnSyncOptions): import('child_process').SpawnSyncReturns<Buffer>;
+  /** Copy file from src to dst */
+  copyFile(src: string, dst: string): boolean;
+  /** Copy file from repository root to worktree destination */
+  copyFromRoot(relativeSrc: string, relativeDst?: string): boolean;
+  /** Safely create or replace a symlink */
+  setSymlink(symlinkPath: string, target?: string): boolean;
+}
+
+export interface PresetHooks {
+  /** Called to sync/reset primary branches before creation */
+  onSyncPrimary?(ctx: ExecutionContext): Promise<void> | void;
+  /** Called to scaffold environment, dependencies, and permissions */
+  onScaffold?(ctx: ExecutionContext): Promise<void> | void;
+  /** Called before deleting worktree and closing workspaces */
+  onPreNuke?(ctx: ExecutionContext): Promise<void> | void;
+  /** Called after all worktree and branch deletions complete */
+  onPostNuke?(ctx: ExecutionContext): Promise<void> | void;
+}
+
+export interface Preset {
+  /** Unique name of the preset ('node', 'laravel', 'generic') */
+  name: string;
+  /** Detection rule to determine if this preset applies to a directory */
+  detect?(cwd: string): boolean;
+  /** Repository defaults */
+  repo?: RepoConfig;
+  /** Workspace defaults */
+  workspace?: WorkspaceConfig;
+  /** Declarative terminal layout */
+  layout?: PaneDefinition[];
+  /** Scaffolding defaults */
+  scaffold?: ScaffoldConfig;
+  /** Lifecycle hook implementations */
+  hooks?: PresetHooks;
+}
+
+export interface WorktreeConfig {
+  /** Name of preset or preset object */
+  preset?: string | Preset;
+  /** Repository configuration */
+  repo: RepoConfig;
+  /** Workspace configuration */
+  workspace: WorkspaceConfig;
+  /** Declarative terminal layout */
+  layout: PaneDefinition[];
+  /** Scaffolding configuration */
+  scaffold: ScaffoldConfig;
+  /** Lifecycle hook overrides */
+  hooks: PresetHooks;
+  /** Path to config file that was loaded (if any) */
+  configFile?: string | null;
+}