@skippercorp/skipper 1.0.1 → 1.0.3

package/README.md

@@ -1,27 +1,157 @@
-# @skippercorp/skipper
+<p align="center">
+  <img src="docs/skipper-logo.png" alt="Skipper logo" width="220" />
+</p>
 
-Published npm package: `@skippercorp/skipper`.
-CLI command name stays `skipper`.
+<h1 align="center">@skippercorp/skipper</h1>
 
-Install dependencies:
+<p align="center">
+  Fast local worktree flow + GitHub event automation in one CLI.
+</p>
+
+<p align="center">
+  <a href="#quick-ramp-up">Quick ramp-up</a>
+  <span> | </span>
+  <a href="#command-cheat-sheet">Command cheat sheet</a>
+  <span> | </span>
+  <a href="#aws-worker-flow">AWS worker flow</a>
+  <span> | </span>
+  <a href="#development">Development</a>
+</p>
+
+Published package: `@skippercorp/skipper`  
+CLI command: `skipper`
+
+## Why skipper
+
+- Keep repo cloning, worktree setup, and tmux session switching fast.
+- Run prompt-based repo automation locally or in AWS.
+- Wire GitHub webhooks to worker definitions in `.skipper/worker/*.ts`.
+
+## Quick ramp-up
+
+### Prerequisites
+
+- `bun`
+- `git`
+- `gh` (GitHub CLI)
+- `fzf`
+- `tmux`
+- For AWS commands: valid AWS credentials/profile with CloudFormation, ECS, EventBridge, S3, and IAM access.
+
+### Install
+
+Run without global install:
 
 ```bash
-bun install
+bunx @skippercorp/skipper hello
 ```
 
-Run locally:
+Or install globally:
 
 ```bash
-bun run cli
+bun add -g @skippercorp/skipper
+skipper hello
+```
+
+### Local workflow in 60 seconds
+
+```bash
+# 1) Clone a repo into ~/.local/share/github/<repo>
+skipper clone owner/repo
+
+# 2) Create/attach a worktree and jump into tmux
+skipper a
+
+# 3) Pull latest + run prompt automation in selected repo
+skipper run "fix flaky tests and update CI"
+
+# 4) Remove a worktree and its tmux session
+skipper rm
+```
+
+Skipper manages:
+
+- Repositories: `~/.local/share/github/<repo>`
+- Worktrees: `~/.local/share/skipper/worktree/<repo>/<worktree>`
+- Tmux sessions: `<repo>-<worktree>`
+
+## Command cheat sheet
+
+| Command | What it does |
+| --- | --- |
+| `skipper clone <owner/repo-or-url>` | Clones repo using `gh` into `~/.local/share/github` |
+| `skipper a` | Selects repo/worktree with `fzf`, creates if missing, then attaches tmux |
+| `skipper rm [--force]` | Removes selected worktree and kills matching tmux session (`--force` discards local worktree changes) |
+| `skipper run "<prompt>"` | Selects repo, pulls latest, runs `opencode run` |
+| `skipper aws bootstrap ...` | Deploys shared AWS ingress stack + optional GitHub webhook |
+| `skipper aws deploy ...` | Deploys repository-scoped subscription stack |
+| `skipper aws run "<prompt>"` | Starts ECS task from bootstrap stack for prompt execution |
+
+## AWS worker flow
+
+Use this when you want GitHub events to trigger remote agent runs.
+
+### 1) Add worker definitions
+
+Create `.skipper/worker/review.ts`:
+
+```ts
+export default {
+  metadata: {
+    id: "review",
+    type: "code-review",
+    description: "Review new pull requests",
+    enabled: true,
+    version: "1",
+  },
+  triggers: [
+    {
+      provider: "github",
+      event: "pull_request",
+      actions: ["opened", "reopened", "ready_for_review", "synchronize"],
+    },
+  ],
+  runtime: {
+    mode: "comment-only",
+    allowPush: false,
+    prompt: "Review this pull request. Focus on correctness and regression risk.",
+  },
+};
+```
+
+### 2) Bootstrap shared infrastructure (once per service/env)
+
+```bash
+skipper aws bootstrap myservice sandbox --github-repo owner/repo
+```
+
+### 3) Deploy repo-scoped subscription stack
+
+```bash
+skipper aws deploy myservice sandbox --github-repo owner/repo
 ```
 
-Validate source standards:
+### 4) Trigger one-off remote run
 
 ```bash
+skipper aws run --service myservice --env sandbox --wait "triage new issues"
+```
+
+Useful safety flags:
+
+- `--dry-run-template` for `aws bootstrap` and `aws deploy`
+- `--dry-run` for `aws run`
+
+## Development
+
+```bash
+bun install
+bun run cli
 bun run lint
+bun test
 ```
 
-Run e2e issue subscription verification (creates temp issue, waits for ECS task, verifies issue fetch logs, then closes issue + stops task):
+Run e2e issue subscription verification:
 
 ```bash
 SKIPPER_E2E_GITHUB_REPO=blntrsz/skipper SKIPPER_E2E_REGION=eu-central-1 bun run test:e2e:issue-subscription
@@ -29,7 +159,7 @@ SKIPPER_E2E_GITHUB_REPO=blntrsz/skipper SKIPPER_E2E_REGION=eu-central-1 bun run
 
 ## Release flow (Changesets)
 
-1. Add a release note: `bun run changeset`
+1. Add release note: `bun run changeset`
 2. Check pending releases: `bunx changeset status`
-3. Push to `main`: `.github/workflows/release.yml` opens/updates a version PR
+3. Push to `main`: `.github/workflows/release.yml` opens/updates version PR
 4. Merge version PR: workflow publishes to npm with `NPM_TOKEN`

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@skippercorp/skipper",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "private": false,
   "publishConfig": {
@@ -12,7 +12,7 @@
     "!src/**/*.test.ts"
   ],
   "bin": {
-    "skipper": "./src/index.ts"
+    "sk": "./src/index.ts"
   },
   "scripts": {
     "cli": "bun run ./src/index.ts",

package/src/command/rm.ts

@@ -11,6 +11,10 @@ type WorktreeRef = {
   path: string;
 };
 
+type RemoveCommandOptions = {
+  force?: boolean;
+};
+
 /**
  * Register remove worktree command.
  *
@@ -21,6 +25,7 @@ export function registerRemoveCommand(program: Command): void {
   program
     .command("rm")
     .description("Remove a worktree (repo+worktree)")
+    .option("-f, --force", "Force remove worktree with uncommitted changes")
     .action(runRemoveCommand);
 }
 
@@ -30,7 +35,8 @@ export function registerRemoveCommand(program: Command): void {
  * @since 1.0.0
  * @category Worktree
  */
-async function runRemoveCommand(): Promise<void> {
+async function runRemoveCommand(options: RemoveCommandOptions = {}): Promise<void> {
+  const force = options.force === true;
   const worktreeBaseDir = `${process.env.HOME}/.local/share/skipper/worktree`;
   const allWorktrees = await collectWorktrees(worktreeBaseDir);
   assertNonEmpty(allWorktrees, "No worktrees found");
@@ -39,7 +45,7 @@ async function runRemoveCommand(): Promise<void> {
     console.log("No worktree selected");
     process.exit(0);
   }
-  await removeWorktree(selected);
+  await removeWorktree(selected, force);
 }
 
 /**
@@ -85,13 +91,13 @@ async function selectWorktree(worktrees: WorktreeRef[]): Promise<WorktreeRef | u
  * @since 1.0.0
  * @category Worktree
  */
-async function removeWorktree(target: WorktreeRef): Promise<void> {
+async function removeWorktree(target: WorktreeRef, force: boolean): Promise<void> {
   const githubDir = `${process.env.HOME}/.local/share/github`;
   const repoPath = `${githubDir}/${target.repo}`;
   const sessionName = `${target.repo}-${target.worktree}`;
   const name = `${target.repo}/${target.worktree}`;
   console.log(`Removing worktree: ${name}`);
-  await removeGitWorktree(repoPath, target.path);
+  await removeGitWorktree(repoPath, target.path, force);
   await Bun.$`rm -rf ${target.path}`;
   if (await tmuxSessionExists(sessionName)) {
     await Bun.$`tmux kill-session -t ${sessionName}`;
@@ -106,11 +112,18 @@ async function removeWorktree(target: WorktreeRef): Promise<void> {
  * @since 1.0.0
  * @category Worktree
  */
-async function removeGitWorktree(repoPath: string, worktreePath: string): Promise<void> {
-  const result = await Bun.$`git -C ${repoPath} worktree remove ${worktreePath}`.nothrow();
+async function removeGitWorktree(
+  repoPath: string,
+  worktreePath: string,
+  force: boolean,
+): Promise<void> {
+  const result = force
+    ? await Bun.$`git -C ${repoPath} worktree remove --force ${worktreePath}`.nothrow()
+    : await Bun.$`git -C ${repoPath} worktree remove ${worktreePath}`.nothrow();
   if (result.exitCode === 0) return;
   const stderr = result.stderr.toString().trim();
-  const fallback = `git worktree remove failed with code ${result.exitCode}`;
+  const command = force ? "git worktree remove --force" : "git worktree remove";
+  const fallback = `${command} failed with code ${result.exitCode}`;
   throw new Error(stderr || fallback);
 }