@genoventures-labs/deckhand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bobby Backlogs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# Deckhand
+
+<p align="center">
+<img src="./assets/lockup.png" alt="Deckhand" width="400" height="350">
+</p>
+
+![Vercel AI Gateway](https://img.shields.io/badge/AI_Gateway-000000?style=for-the-badge&logo=vercel&logoColor=white)
+![Vercel Eve](https://img.shields.io/badge/Eve-000000?style=for-the-badge&logo=vercel&logoColor=white)
+![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
+![GitHub](https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white)
+![GitHub CLI](https://img.shields.io/badge/GitHub_CLI-2088FF?style=for-the-badge&logo=github&logoColor=white)
+
+> An intelligent CLI automation framework bridging Vercel Eve and AI Gateway directly to the GitHub CLI (`gh`).
+
+The npm package is **`@genoventures-labs/deckhand`**. The CLI binary is **`deckhand`**.
+
+---
+
+## Overview
+
+**Deckhand** orchestrates local repository management and automated GitHub workflows. Built on Vercel's Eve framework, it routes model calls through [AI Gateway](https://vercel.com/docs/ai-gateway) and uses the official GitHub CLI (`gh`) for version control, issue triage, and CI/CD triggers.
+
+---
+
+## Install
+
+Requires Node.js 20+ (Node 24+ for `deckhand agent` / Eve), plus `git` and `gh`.
+
+```bash
+npm install
+npm run build
+```
+
+That puts `deckhand` on `./node_modules/.bin`. From another machine or a global install:
+
+```bash
+npm install -g @genoventures-labs/deckhand
+# or, without publishing yet:
+npm install -g .
+```
+
+Authenticate GitHub and AI Gateway:
+
+```bash
+gh auth login
+cp .env.example .env.local
+# Put your AI Gateway key in .env.local, or:
+# vercel link && vercel env pull .env.local
+```
+
+Copy `deckhand.example.json` to `deckhand.json` to pin workspaces and the `provider/model` slug (default `openai/gpt-5.6-luna-fast`).
+
+---
+
+## CLI
+
+```bash
+deckhand                      # overview + command tables
+deckhand help                 # same overview
+deckhand help topics          # help catalog
+deckhand help runs            # gated-run guide
+deckhand doctor               # dependency table
+deckhand status               # repo + change tables
+deckhand watch                # directory monitoring
+deckhand sync                 # add + Gateway commit message + push
+deckhand pull                 # git pull --ff-only
+deckhand branch <name>
+deckhand conflicts            # conflict list + model guidance
+deckhand pr create -t "..."
+deckhand issue create -t "..."
+deckhand repo create <name>
+deckhand project create -t "..." -o <owner>
+deckhand checks
+deckhand actions list
+deckhand actions watch [runId]
+deckhand actions run <workflow>
+deckhand runs list            # gated YAML templates
+deckhand agent                # Eve terminal session
+```
+
+`deckhand sync` writes a commit message through AI Gateway from the current diff. Pass `-m` to skip generation, or `--no-push` to commit only.
+
+---
+
+## Gated runs
+
+YAML templates declare *what* runs and *when*. GitHub Environments (`deckhand-gate`) hold the execute job until a reviewer approves.
+
+```bash
+deckhand runs list
+deckhand runs init morning-pull
+deckhand runs install-workflow morning-pull
+deckhand runs apply morning-pull --approve
+```
+
+| Template | Cron (local TZ) | Action | Gate |
+| :--- | :--- | :--- | :--- |
+| `morning-pull` | `0 5 * * *` America/Los_Angeles | `git pull --ff-only` | `deckhand-gate` |
+| `weekday-status` | `0 8 * * 1-5` | `status` | off |
+| `gated-sync` | `0 18 * * 1-5` | commit, no push | `deckhand-gate` |
+| `nightly-checks` | `0 23 * * *` | PR checks | `deckhand-gate` |
+
+Copy the YAML into `.deckhand/runs/` and the matching workflow into `.github/workflows/`. Then in the GitHub repo: **Settings → Environments → `deckhand-gate` → Required reviewers**.
+
+GitHub Actions cron is UTC (`0 13 * * *` ≈ 5am PST). Self-hosted or `deckhand runs apply` honor the YAML `timezone` as documentation of intent; wire a local scheduler (Task Scheduler, cron) if you want true local 5am without GitHub.
+
+Schema: `templates/schema/gated-run.v1.json`.
+
+
+---
+
+## Features
+
+### Automated Change Detection & Sync
+
+- **Directory Monitoring:** Scans configured local workspaces to detect file updates and status changes (`deckhand watch`).
+- **Intelligent Git Operations:** Stages, commits, pushes, and fast-forward pulls from detected diffs (`deckhand sync` / `pull`).
+- **Status Reporting:** Prints whether the tree is clean and when a sync finishes.
+
+### Repository & Workflow Management
+
+- **Entity Generation:** Branches, pull requests, issues, repositories, and GitHub Projects via `gh`.
+- **Assisted Resolution:** Conflict listing plus a gateway-model write-up of resolution options.
+- **CI/CD Integration:** Trigger, list, watch, and surface GitHub Actions runs and PR checks.
+- **Gated runs:** YAML templates for scheduled pulls, status, sync, and checks, with a GitHub Environment approval gate.
+
+### Eve agent
+
+`agent/` is a filesystem-first Eve app. Tools wrap the same git/`gh` helpers as the CLI. `deckhand agent` starts `eve dev` with `DECKHAND_CWD` pointed at your repo. Push, repo creation, and workflow triggers ask for approval.
+
+---
+
+## Architecture & Dependencies
+
+| Tool | Role | Reference |
+| :--- | :--- | :--- |
+| **Vercel Eve** | Core AI Framework | [eve.dev/docs](https://eve.dev/docs) |
+| **Vercel AI Gateway** | Model routing | [vercel.com/docs/ai-gateway](https://vercel.com/docs/ai-gateway) |
+| **GitHub CLI (`gh`)** | GitHub Interface Layer | [cli.github.com](https://cli.github.com/) |
+| **GitHub Actions** | CI/CD Pipeline Automation | [github.com/features/actions](https://github.com/features/actions) |
+
+---
+
+## Scripts
+
+| Script | What it does |
+| :--- | :--- |
+| `npm install` | Install CLI + Eve runtime dependencies |
+| `npm run build` | Compile `src/` to `dist/` |
+| `npm run dev` | Run the CLI through `tsx` |
+| `npm run eve:dev` | Start Eve against `./agent` |

package/agent/agent.ts

@@ -0,0 +1,5 @@
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "openai/gpt-5.6-luna-fast",
+});

package/agent/instructions.md

@@ -0,0 +1,23 @@
+# Deckhand
+
+You are Deckhand (CLI: `deckhand`), a Git and GitHub operator.
+
+## Runtime
+
+- The user's workspace is `DECKHAND_CWD` when set, otherwise the process working directory.
+- Prefer the authored tools over guessing shell flags.
+- GitHub work goes through `gh`. Do not invent API tokens or curl GitHub REST yourself.
+- Models route through Vercel AI Gateway. If a model call fails, tell the user to run `deckhand doctor` and set `AI_GATEWAY_API_KEY` or refresh `VERCEL_OIDC_TOKEN` with `vercel env pull`.
+
+## Git safety
+
+- Never force-push, never skip hooks, never rewrite published history.
+- Prefer `--ff-only` pulls.
+- Require a clear user request before `push`, `repo create`, or triggering workflows.
+- For merge conflicts, list files, explain options, and do not overwrite conflict markers unless the user asked to apply a specific resolution.
+
+## Style
+
+- Be concise in the terminal.
+- After git operations, report whether the tree is clean and whether the branch is ahead or behind.
+- When creating issues, PRs, or projects, draft a short title and body, then call the matching tool.

package/agent/schedules/workspace_scan.md

@@ -0,0 +1,5 @@
+---
+cron: "*/15 * * * *"
+---
+
+Scan the user workspace git status. If the tree is dirty, summarize changed files. If it is clean, say so in one line. Do not commit or push unless the session was started for a sync.

package/agent/skills/conflict-triage.md

@@ -0,0 +1,7 @@
+---
+description: Analyze merge conflicts and issue workflows without destroying local work.
+---
+
+# Conflict and issue triage
+
+Call `git_conflicts` first. Explain resolution order. Do not recommend `git push --force`. For issues, read `gh` output and propose labels or next commands without closing anything unless asked.

package/agent/skills/git-sync.md

@@ -0,0 +1,11 @@
+---
+description: Detect diffs and run add, commit, push, or pull with safe git defaults.
+---
+
+# Git sync
+
+1. Call `git_status`. If clean, stop.
+2. Summarize changes for the user.
+3. On explicit sync: `git_add`, draft a conventional commit with `draft_commit_message`, then `git_commit`.
+4. Push only when asked. If push needs an upstream, say so and use setUpstream.
+5. Pull with fast-forward only.

package/agent/skills/github-entities.md

@@ -0,0 +1,7 @@
+---
+description: Create branches, pull requests, issues, repositories, and GitHub Projects through gh.
+---
+
+# GitHub entities
+
+Use `gh_*` tools. Confirm titles before create calls. Draft bodies with the draft tool when the user did not supply one. For CI, use `gh_actions_list`, `gh_actions_watch`, `gh_actions_run`, and `gh_checks`.

package/agent/tools/draft_commit_message.ts

@@ -0,0 +1,12 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { generateCommitMessage } from "../../src/lib/model.js";
+
+export default defineTool({
+  description: "Ask the AI Gateway model to draft a conventional commit message from the current diff.",
+  inputSchema: z.object({}),
+  label: { start: () => "Draft commit message" },
+  async execute() {
+    return { message: await generateCommitMessage() };
+  },
+});

package/agent/tools/gh_actions_list.ts

@@ -0,0 +1,12 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { listRuns } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "List recent GitHub Actions workflow runs.",
+  inputSchema: z.object({}),
+  label: { start: () => "List Actions runs" },
+  async execute() {
+    return { result: await listRuns() };
+  },
+});

package/agent/tools/gh_actions_run.ts

@@ -0,0 +1,17 @@
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+import { triggerWorkflow } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Trigger a GitHub Actions workflow with gh workflow run.",
+  inputSchema: z.object({
+    workflow: z.string().min(1),
+    ref: z.string().optional(),
+  }),
+  approval: always(),
+  label: { start: ({ workflow }) => `Trigger ${workflow}` },
+  async execute(input) {
+    return { result: await triggerWorkflow(input) };
+  },
+});

package/agent/tools/gh_actions_watch.ts

@@ -0,0 +1,14 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { watchRun } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Watch a GitHub Actions run until it completes.",
+  inputSchema: z.object({
+    runId: z.string().optional(),
+  }),
+  label: { start: ({ runId }) => (runId ? `Watch run ${runId}` : "Watch latest run") },
+  async execute({ runId }) {
+    return { result: await watchRun(runId) };
+  },
+});

package/agent/tools/gh_checks.ts

@@ -0,0 +1,12 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { listChecks } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Show GitHub Actions / status checks for the current pull request.",
+  inputSchema: z.object({}),
+  label: { start: () => "Read PR checks" },
+  async execute() {
+    return { result: await listChecks() };
+  },
+});

package/agent/tools/gh_issue_create.ts

@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { createIssue } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Create a GitHub issue with gh issue create.",
+  inputSchema: z.object({
+    title: z.string().min(1),
+    body: z.string().min(1),
+    labels: z.array(z.string()).default([]),
+  }),
+  label: { start: ({ title }) => `Open issue: ${title}` },
+  async execute(input) {
+    return { result: await createIssue(input) };
+  },
+});

package/agent/tools/gh_pr_create.ts

@@ -0,0 +1,17 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { createPullRequest } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Create a GitHub pull request with gh pr create.",
+  inputSchema: z.object({
+    title: z.string().min(1),
+    body: z.string().min(1),
+    base: z.string().optional(),
+    draft: z.boolean().default(false),
+  }),
+  label: { start: ({ title }) => `Open PR: ${title}` },
+  async execute(input) {
+    return { result: await createPullRequest(input) };
+  },
+});

package/agent/tools/gh_project_create.ts

@@ -0,0 +1,15 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { createProject } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Create a GitHub Project with gh project create.",
+  inputSchema: z.object({
+    title: z.string().min(1),
+    owner: z.string().min(1),
+  }),
+  label: { start: ({ title }) => `Create project ${title}` },
+  async execute(input) {
+    return { result: await createProject(input) };
+  },
+});

package/agent/tools/gh_repo_create.ts

@@ -0,0 +1,18 @@
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+import { createRepo } from "../../src/lib/gh.js";
+
+export default defineTool({
+  description: "Create a GitHub repository from the current directory with gh repo create.",
+  inputSchema: z.object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+    privateRepo: z.boolean().default(false),
+  }),
+  approval: always(),
+  label: { start: ({ name }) => `Create repo ${name}` },
+  async execute(input) {
+    return { result: await createRepo(input) };
+  },
+});

package/agent/tools/git_add.ts

@@ -0,0 +1,15 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { gitAdd } from "../../src/lib/git.js";
+
+export default defineTool({
+  description: "Stage files with git add. Pass an empty list to stage the whole workspace.",
+  inputSchema: z.object({
+    paths: z.array(z.string()).default([]),
+  }),
+  label: { start: ({ paths }) => (paths.length ? `Stage ${paths.join(", ")}` : "Stage all changes") },
+  async execute({ paths }) {
+    await gitAdd(paths);
+    return { staged: paths.length ? paths : ["."] };
+  },
+});

package/agent/tools/git_branch.ts

@@ -0,0 +1,15 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { gitCheckoutBranch } from "../../src/lib/git.js";
+
+export default defineTool({
+  description: "Create or switch a git branch.",
+  inputSchema: z.object({
+    name: z.string().min(1),
+    create: z.boolean().default(true),
+  }),
+  label: { start: ({ name, create }) => (create ? `Create branch ${name}` : `Switch to ${name}`) },
+  async execute({ name, create }) {
+    return { result: await gitCheckoutBranch(name, create) };
+  },
+});

package/agent/tools/git_commit.ts

@@ -0,0 +1,14 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { gitCommit } from "../../src/lib/git.js";
+
+export default defineTool({
+  description: "Create a git commit with the given message. Does not skip hooks.",
+  inputSchema: z.object({
+    message: z.string().min(1),
+  }),
+  label: { start: ({ message }) => `Commit: ${message.split("\n")[0]}` },
+  async execute({ message }) {
+    return { result: await gitCommit(message) };
+  },
+});

package/agent/tools/git_conflicts.ts

@@ -0,0 +1,15 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { gitConflictFiles } from "../../src/lib/git.js";
+import { suggestConflictResolution } from "../../src/lib/model.js";
+
+export default defineTool({
+  description: "List conflicted files and return AI Gateway guidance for resolving them.",
+  inputSchema: z.object({}),
+  label: { start: () => "Inspect merge conflicts" },
+  async execute() {
+    const files = await gitConflictFiles();
+    const guidance = files.length ? await suggestConflictResolution(files) : "No merge conflicts.";
+    return { files, guidance };
+  },
+});

package/agent/tools/git_pull.ts

@@ -0,0 +1,12 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { gitPull } from "../../src/lib/git.js";
+
+export default defineTool({
+  description: "Fast-forward pull from the remote tracking branch.",
+  inputSchema: z.object({}),
+  label: { start: () => "Pull --ff-only" },
+  async execute() {
+    return { result: await gitPull() };
+  },
+});

package/agent/tools/git_push.ts

@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+import { gitPush } from "../../src/lib/git.js";
+
+export default defineTool({
+  description: "Push the current branch to origin. Never force-pushes.",
+  inputSchema: z.object({
+    setUpstream: z.boolean().default(false),
+  }),
+  approval: always(),
+  label: { start: () => "Push to origin" },
+  async execute({ setUpstream }) {
+    return { result: await gitPush(undefined, setUpstream) };
+  },
+});

package/agent/tools/git_status.ts

@@ -0,0 +1,13 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { formatStatus, gitStatus } from "../../src/lib/git.js";
+
+export default defineTool({
+  description: "Read git status for the Deckhand workspace, including branch tracking and file changes.",
+  inputSchema: z.object({}),
+  label: { start: () => "Check git status" },
+  async execute() {
+    const status = await gitStatus();
+    return { ...status, summary: formatStatus(status) };
+  },
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};