@tsuzuku/arise 1.0.0

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,151 @@
+/**
+ * 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;
+  branch: string | null;
+  dirname: string | null;
+  workspaceName: string | null;
+  source: string | null;
+  presetName: 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;
+}
+
+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;
+  /** Default pane to focus ('agy', '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;
+}

package/worktree.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "HerdrWorktreeConfig",
+  "description": "Configuration schema for Herdr Worktree (.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
+}