@skippercorp/skipper 1.0.1

package/README.md

@@ -0,0 +1,35 @@
+# @skippercorp/skipper
+
+Published npm package: `@skippercorp/skipper`.
+CLI command name stays `skipper`.
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Run locally:
+
+```bash
+bun run cli
+```
+
+Validate source standards:
+
+```bash
+bun run lint
+```
+
+Run e2e issue subscription verification (creates temp issue, waits for ECS task, verifies issue fetch logs, then closes issue + stops task):
+
+```bash
+SKIPPER_E2E_GITHUB_REPO=blntrsz/skipper SKIPPER_E2E_REGION=eu-central-1 bun run test:e2e:issue-subscription
+```
+
+## Release flow (Changesets)
+
+1. Add a 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
+4. Merge version PR: workflow publishes to npm with `NPM_TOKEN`

package/package.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@skippercorp/skipper",
+  "version": "1.0.1",
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "bin": {
+    "skipper": "./src/index.ts"
+  },
+  "scripts": {
+    "cli": "bun run ./src/index.ts",
+    "typecheck": "bun x tsc --noEmit",
+    "lint": "bun run typecheck && bun run ./scripts/check-source-standards.ts",
+    "test": "bun test",
+    "test:e2e:issue-subscription": "bun run ./scripts/verify-issue-subscription-e2e.ts",
+    "build": "bun build ./src/index.ts --compile --outfile bin/skipper",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.0",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@aws-sdk/client-cloudformation": "^3.888.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.1000.0",
+    "@aws-sdk/client-ec2": "^3.1000.0",
+    "@aws-sdk/client-ecs": "^3.1000.0",
+    "@aws-sdk/client-s3": "^3.1000.0",
+    "@aws-sdk/client-sts": "^3.1000.0",
+    "@octokit/webhooks": "^13.7.1",
+    "@octokit/webhooks-types": "^7.6.1",
+    "@pulumi/aws": "^7.20.0",
+    "@pulumi/pulumi": "^3.120.0",
+    "commander": "^14.0.3"
+  }
+}

package/src/app/cli.ts

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import packageJson from "../../package.json";
+import { registerCommands } from "./register-commands.js";
+
+const packageVersion =
+  typeof packageJson.version === "string" && packageJson.version.length > 0
+    ? packageJson.version
+    : "0.0.0";
+
+/**
+ * Build configured CLI program.
+ *
+ * @since 1.0.0
+ * @category CLI
+ */
+export function createProgram(): Command {
+  const program = new Command();
+  program.name("skipper").description("CLI tool").version(packageVersion);
+  registerCommands(program);
+  return program;
+}
+
+/**
+ * Run CLI program with argv.
+ *
+ * @since 1.0.0
+ * @category CLI
+ */
+export async function runCli(argv = process.argv): Promise<void> {
+  await createProgram().parseAsync(argv);
+}

package/src/app/register-commands.ts

@@ -0,0 +1,37 @@
+import type { Command } from "commander";
+import { registerCloneCommand } from "../command/clone.js";
+import { registerAddCommand } from "../command/a.js";
+import { registerRemoveCommand } from "../command/rm.js";
+import { registerRunCommand } from "../command/run.js";
+import { registerAwsCommand } from "../command/aws/index.js";
+
+/**
+ * Register all skipper commands.
+ *
+ * @since 1.0.0
+ * @category CLI
+ */
+export function registerCommands(program: Command): void {
+  registerHelloCommand(program);
+  registerCloneCommand(program);
+  registerAddCommand(program);
+  registerRemoveCommand(program);
+  registerRunCommand(program);
+  registerAwsCommand(program);
+}
+
+/**
+ * Register simple health command.
+ *
+ * @since 1.0.0
+ * @category CLI
+ */
+function registerHelloCommand(program: Command): void {
+  program
+    .command("hello")
+    .description("Say hello")
+    .argument("[name]", "name to greet")
+    .action((name) => {
+      console.log(`Hello ${name || "World"}!`);
+    });
+}

package/src/command/a.ts

@@ -0,0 +1,213 @@
+import type { Command } from "commander";
+import {
+  assertNonEmpty,
+  listDirectory,
+  selectOrQueryWithFzf,
+  selectWithFzf,
+} from "../shared/command/interactive.js";
+
+type WorktreeSelection = {
+  repo: string;
+  worktree: string;
+  targetWorktreePath: string;
+  repoPath: string;
+};
+
+/**
+ * Register add/attach worktree command.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+export function registerAddCommand(program: Command): void {
+  program
+    .command("a")
+    .description("Add/attach to a worktree in a repository")
+    .action(runAddCommand);
+}
+
+/**
+ * Execute add/attach flow.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function runAddCommand(): Promise<void> {
+  const githubDir = `${process.env.HOME}/.local/share/github`;
+  const worktreeBaseDir = `${process.env.HOME}/.local/share/skipper/worktree`;
+  const selection = await selectWorktree(githubDir, worktreeBaseDir);
+  await ensureWorktreeExists(selection);
+  await attachOrStartTmux(selection);
+}
+
+/**
+ * Select repo and worktree names.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function selectWorktree(
+  githubDir: string,
+  worktreeBaseDir: string,
+): Promise<WorktreeSelection> {
+  const repoList = await listDirectory(githubDir);
+  assertNonEmpty(repoList, "No repositories found in ~/.local/share/github");
+  const repo = await selectWithFzf(repoList, "Select repository: ");
+  if (!repo) {
+    console.log("No repository selected");
+    process.exit(0);
+  }
+
+  const worktreeDir = `${worktreeBaseDir}/${repo}`;
+  await Bun.$`mkdir -p ${worktreeDir}`;
+  const existingWorktrees = await listDirectory(worktreeDir);
+  const input = await selectOrQueryWithFzf(
+    existingWorktrees,
+    existingWorktrees.length > 0
+      ? "Select or type new worktree: "
+      : "Enter new worktree name: ",
+  );
+  const worktree = resolveWorktreeName(input);
+  if (!worktree) {
+    console.log("No worktree selected or entered");
+    process.exit(0);
+  }
+
+  return {
+    repo,
+    worktree,
+    targetWorktreePath: `${worktreeDir}/${worktree}`,
+    repoPath: `${githubDir}/${repo}`,
+  };
+}
+
+/**
+ * Ensure selected worktree exists.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function ensureWorktreeExists(selection: WorktreeSelection): Promise<void> {
+  const exists = await directoryExists(selection.targetWorktreePath);
+  if (exists) {
+    console.log(`Attaching to existing worktree: ${selection.targetWorktreePath}`);
+    return;
+  }
+
+  console.log(`Creating new worktree: ${selection.worktree}`);
+  const branchExists = await gitBranchExists(selection.repoPath, selection.worktree);
+  if (branchExists) {
+    await Bun.$`git -C ${selection.repoPath} worktree add ${selection.targetWorktreePath} ${selection.worktree}`;
+    return;
+  }
+  await Bun.$`git -C ${selection.repoPath} worktree add ${selection.targetWorktreePath} -b ${selection.worktree}`;
+}
+
+/**
+ * Attach to existing tmux session or create one.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function attachOrStartTmux(selection: WorktreeSelection): Promise<void> {
+  const sessionName = `${selection.repo}-${selection.worktree}`;
+  const running = await tmuxSessionExists(sessionName);
+  const inTmux = process.env.TMUX !== undefined;
+  if (running) {
+    await switchOrAttachSession(sessionName, inTmux);
+    return;
+  }
+  await createTmuxSession(sessionName, selection.targetWorktreePath, inTmux);
+}
+
+/**
+ * Resolve typed or selected worktree name.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+function resolveWorktreeName(worktreeInput: string | undefined): string | undefined {
+  if (!worktreeInput) return undefined;
+  const lines = worktreeInput.trim().split("\n");
+  const query = lines[0] || "";
+  const selection = lines[1] || "";
+  if (selection && selection !== "[new]") {
+    return selection;
+  }
+  if (query) {
+    return query;
+  }
+  return undefined;
+}
+
+/**
+ * Check whether directory exists.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function directoryExists(path: string): Promise<boolean> {
+  const result = await Bun.$`test -d ${path} && echo "yes" || echo "no"`.text();
+  return result.trim() === "yes";
+}
+
+/**
+ * Check whether git branch exists.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function gitBranchExists(repoPath: string, branch: string): Promise<boolean> {
+  const ref = `refs/heads/${branch}`;
+  const result = await Bun.$`git -C ${repoPath} show-ref --verify --quiet ${ref}`.nothrow();
+  if (result.exitCode === 0) return true;
+  if (result.exitCode === 1) return false;
+  const stderr = result.stderr.toString().trim();
+  throw new Error(stderr || `git show-ref failed with code ${result.exitCode}`);
+}
+
+/**
+ * Check whether tmux session exists.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function tmuxSessionExists(sessionName: string): Promise<boolean> {
+  const output = await Bun.$`tmux has-session -t ${sessionName} 2>/dev/null && echo "yes" || echo "no"`.text();
+  return output.trim() === "yes";
+}
+
+/**
+ * Switch or attach to tmux session.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function switchOrAttachSession(sessionName: string, inTmux: boolean): Promise<void> {
+  if (inTmux) {
+    console.log(`Switching to tmux session: ${sessionName}`);
+    await Bun.$`tmux switch-client -t ${sessionName}`;
+    return;
+  }
+  console.log(`Attaching to existing tmux session: ${sessionName}`);
+  await Bun.$`tmux attach-session -t ${sessionName}`;
+}
+
+/**
+ * Create tmux session and attach/switch.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function createTmuxSession(
+  sessionName: string,
+  worktreePath: string,
+  inTmux: boolean,
+): Promise<void> {
+  console.log(`Starting new tmux session: ${sessionName}`);
+  if (inTmux) {
+    await Bun.$`tmux new-session -s ${sessionName} -c ${worktreePath} -d && tmux switch-client -t ${sessionName}`;
+    return;
+  }
+  await Bun.$`tmux new-session -s ${sessionName} -c ${worktreePath}`;
+}