@skippercorp/skipper 1.0.1

package/src/command/clone.ts

@@ -0,0 +1,67 @@
+import type { Command } from "commander";
+
+/**
+ * Register clone command.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+export function registerCloneCommand(program: Command): void {
+  program
+    .command("clone")
+    .description("Clone a GitHub repository using SSH")
+    .argument("<url>", "GitHub repository URL or owner/repo")
+    .action(runClone);
+}
+
+/**
+ * Execute clone command.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function runClone(url: string): Promise<void> {
+  const repo = normalizeRepoInput(url);
+  const targetDir = buildTargetDir(repo);
+  await Bun.$`mkdir -p ${targetDir}`;
+  await Bun.$`gh repo clone ${repo} ${targetDir} -- --recursive`;
+}
+
+/**
+ * Normalize clone input to owner/repo.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+function normalizeRepoInput(url: string): string {
+  if (url.startsWith("https://github.com/")) {
+    return parseRepo(url, /github\.com\/([^\/]+\/[^\/]+?)(?:\.git)?$/);
+  }
+  if (url.startsWith("git@github.com:")) {
+    return parseRepo(url, /github\.com:([^\/]+\/[^\/]+?)(?:\.git)?$/);
+  }
+  return url;
+}
+
+/**
+ * Parse repo with regex fallback.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+function parseRepo(url: string, matcher: RegExp): string {
+  const match = url.match(matcher);
+  return match?.[1] ?? url;
+}
+
+/**
+ * Build clone target directory path.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+function buildTargetDir(repo: string): string {
+  const baseDir = `${process.env.HOME}/.local/share/github`;
+  const repoName = repo.split("/")[1] ?? repo;
+  return `${baseDir}/${repoName}`;
+}

package/src/command/rm.ts

@@ -0,0 +1,126 @@
+import type { Command } from "commander";
+import {
+  assertNonEmpty,
+  listDirectory,
+  selectWithFzf,
+} from "../shared/command/interactive.js";
+
+type WorktreeRef = {
+  repo: string;
+  worktree: string;
+  path: string;
+};
+
+/**
+ * Register remove worktree command.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+export function registerRemoveCommand(program: Command): void {
+  program
+    .command("rm")
+    .description("Remove a worktree (repo+worktree)")
+    .action(runRemoveCommand);
+}
+
+/**
+ * Execute remove command flow.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function runRemoveCommand(): Promise<void> {
+  const worktreeBaseDir = `${process.env.HOME}/.local/share/skipper/worktree`;
+  const allWorktrees = await collectWorktrees(worktreeBaseDir);
+  assertNonEmpty(allWorktrees, "No worktrees found");
+  const selected = await selectWorktree(allWorktrees);
+  if (!selected) {
+    console.log("No worktree selected");
+    process.exit(0);
+  }
+  await removeWorktree(selected);
+}
+
+/**
+ * Collect all worktrees under base path.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function collectWorktrees(worktreeBaseDir: string): Promise<WorktreeRef[]> {
+  const repos = await listDirectory(worktreeBaseDir);
+  if (repos.length === 0) {
+    console.error("No worktrees found in ~/.local/share/skipper/worktree");
+    process.exit(1);
+  }
+  const allWorktrees: WorktreeRef[] = [];
+  for (const repo of repos) {
+    const repoDir = `${worktreeBaseDir}/${repo}`;
+    const worktrees = await listDirectory(repoDir);
+    for (const worktree of worktrees) {
+      allWorktrees.push({ repo, worktree, path: `${repoDir}/${worktree}` });
+    }
+  }
+  return allWorktrees;
+}
+
+/**
+ * Select worktree with fzf.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function selectWorktree(worktrees: WorktreeRef[]): Promise<WorktreeRef | undefined> {
+  const labels = worktrees.map((item) => `${item.repo}/${item.worktree}`);
+  const selected = await selectWithFzf(labels, "Select worktree to remove: ");
+  const trimmed = selected?.trim();
+  if (!trimmed) return undefined;
+  return worktrees.find((item) => `${item.repo}/${item.worktree}` === trimmed);
+}
+
+/**
+ * Remove worktree and tmux session.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function removeWorktree(target: WorktreeRef): 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 Bun.$`rm -rf ${target.path}`;
+  if (await tmuxSessionExists(sessionName)) {
+    await Bun.$`tmux kill-session -t ${sessionName}`;
+    console.log(`Killed tmux session: ${sessionName}`);
+  }
+  console.log(`Removed worktree: ${name}`);
+}
+
+/**
+ * Remove git worktree from repository.
+ *
+ * @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();
+  if (result.exitCode === 0) return;
+  const stderr = result.stderr.toString().trim();
+  const fallback = `git worktree remove failed with code ${result.exitCode}`;
+  throw new Error(stderr || fallback);
+}
+
+/**
+ * Check tmux session existence.
+ *
+ * @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";
+}

package/src/command/run.ts

@@ -0,0 +1,43 @@
+import type { Command } from "commander";
+import {
+  assertNonEmpty,
+  listDirectory,
+  selectWithFzf,
+} from "../shared/command/interactive.js";
+
+/**
+ * Register run command.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+export function registerRunCommand(program: Command): void {
+  program
+    .command("run")
+    .description("Pull changes and run opencode with a prompt")
+    .argument("<prompt>", "The prompt to pass to opencode")
+    .action(runCommand);
+}
+
+/**
+ * Execute run command flow.
+ *
+ * @since 1.0.0
+ * @category Worktree
+ */
+async function runCommand(prompt: string): Promise<void> {
+  const baseDir = `${process.env.HOME}/.local/share/github`;
+  const repoList = await listDirectory(baseDir);
+  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 repoPath = `${baseDir}/${repo}`;
+  console.log(`Selected: ${repo}`);
+  console.log("Pulling latest changes...");
+  await Bun.$`git -C ${repoPath} pull`;
+  console.log("Running opencode...");
+  await Bun.$`opencode run ${prompt}`.cwd(repoPath);
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+import { runCli } from "./app/cli.js";
+
+/**
+ * Process entrypoint.
+ *
+ * @since 1.0.0
+ * @category CLI
+ */
+try {
+  await runCli();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+}

package/src/shared/command/interactive.ts

@@ -0,0 +1,120 @@
+import { Glob } from "bun";
+import type { $ } from "bun";
+
+const DIRECTORY_GLOB = new Glob("*");
+const FZF_NO_MATCH_EXIT_CODE = 1;
+const FZF_CANCELLED_EXIT_CODES = new Set([130]);
+
+/**
+ * List direct directory entries.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+export async function listDirectory(path: string): Promise<string[]> {
+  try {
+    const entries = await Array.fromAsync(
+      DIRECTORY_GLOB.scan({ cwd: path, onlyFiles: false }),
+    );
+    return entries
+      .filter((entry) => entry.trim().length > 0)
+      .sort((a, b) => a.localeCompare(b));
+  } catch (error) {
+    if (isMissingDirectoryError(error)) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Exit when values list is empty.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+export function assertNonEmpty<T>(values: T[], message: string): void {
+  if (values.length > 0) return;
+  console.error(message);
+  process.exit(1);
+}
+
+/**
+ * Select one value with fzf.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+export async function selectWithFzf(
+  values: string[],
+  prompt: string,
+): Promise<string | undefined> {
+  const output = await runFzf(values, ["--prompt", prompt]);
+  const trimmed = output?.trim();
+  if (!trimmed) return undefined;
+  return trimmed;
+}
+
+/**
+ * Select one value or return typed query with fzf.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+export async function selectOrQueryWithFzf(
+  values: string[],
+  prompt: string,
+): Promise<string | undefined> {
+  const output = await runFzf(values, ["--prompt", prompt, "--print-query"]);
+  if (!output) return undefined;
+  return output.trim();
+}
+
+/**
+ * Run fzf with values as stdin.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+async function runFzf(values: string[], args: string[]): Promise<string | undefined> {
+  const input = values.join("\n");
+  const result = await Bun.$`echo ${input} | fzf ${args}`.nothrow();
+  const output = result.stdout.toString();
+  if (result.exitCode === 0) {
+    return output;
+  }
+  if (result.exitCode === FZF_NO_MATCH_EXIT_CODE) {
+    if (output.trim().length > 0) return output;
+    return undefined;
+  }
+  if (FZF_CANCELLED_EXIT_CODES.has(result.exitCode)) {
+    return undefined;
+  }
+  throw new Error(`fzf failed: ${formatShellFailure(result)}`);
+}
+
+/**
+ * Format shell output for error reporting.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+function formatShellFailure(result: $.ShellOutput): string {
+  const stderr = result.stderr.toString().trim();
+  if (stderr.length > 0) return stderr;
+  const stdout = result.text().trim();
+  if (stdout.length > 0) return stdout;
+  return `exit code ${result.exitCode}`;
+}
+
+/**
+ * Check if directory is missing.
+ *
+ * @since 1.0.0
+ * @category Shared.Command
+ */
+function isMissingDirectoryError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const maybe = error as { code?: string };
+  return maybe.code === "ENOENT" || maybe.code === "ENOTDIR";
+}

package/src/shared/validation/parse-json.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime validator function.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export type Validator<T> = (value: unknown) => value is T;
+
+/**
+ * Parse JSON and validate with type guard.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function parseJson<T>(raw: string, validate: Validator<T>, ctx: string): T {
+  const parsed = parseUnknownJson(raw, ctx);
+  if (!validate(parsed)) {
+    throw new Error(`invalid ${ctx}`);
+  }
+  return parsed;
+}
+
+/**
+ * Parse unknown JSON safely.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function parseUnknownJson(raw: string, ctx: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`invalid JSON for ${ctx}`);
+  }
+}
+
+/**
+ * Check plain object shape.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Read string field from object.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function readOptionalString(
+  value: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const found = value[key];
+  return typeof found === "string" ? found : undefined;
+}

package/src/worker/aws-params.ts

@@ -0,0 +1,54 @@
+export const WORKER_SCHEMA_VERSION = "1";
+export const WORKER_CHUNK_COUNT = 12;
+export const WORKER_CHUNK_SIZE = 3500;
+
+export const WORKERS_ENCODING_PARAM = "WorkersEncoding";
+export const WORKERS_SHA256_PARAM = "WorkersSha256";
+export const WORKERS_SCHEMA_VERSION_PARAM = "WorkersSchemaVersion";
+export const WORKERS_CHUNK_COUNT_PARAM = "WorkersChunkCount";
+export const WORKERS_ENCODING = "gzip-base64-v1";
+
+/**
+ * Build worker chunk parameter key from index.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function getWorkerChunkParameterKey(index: number): string {
+  return `WorkersChunk${index.toString().padStart(2, "0")}`;
+}
+
+/**
+ * List worker chunk parameter keys.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function listWorkerChunkParameterKeys(count = WORKER_CHUNK_COUNT): string[] {
+  const keys: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    keys.push(getWorkerChunkParameterKey(index));
+  }
+  return keys;
+}
+
+/**
+ * Build empty/default worker parameter values.
+ *
+ * @since 1.0.0
+ * @category Shared
+ */
+export function createDefaultWorkerParameterValues(
+  count = WORKER_CHUNK_COUNT,
+): Record<string, string> {
+  const values: Record<string, string> = {
+    [WORKERS_ENCODING_PARAM]: "",
+    [WORKERS_SHA256_PARAM]: "",
+    [WORKERS_SCHEMA_VERSION_PARAM]: WORKER_SCHEMA_VERSION,
+    [WORKERS_CHUNK_COUNT_PARAM]: "0",
+  };
+  for (const key of listWorkerChunkParameterKeys(count)) {
+    values[key] = "";
+  }
+  return values;
+}