@devframes/plugin-git

[!WARNING] Experimental This devframe is experimental and may change without a major version bump until it stabilizes.

A git devframe built on devframe: a repository dashboard with a Next.js App Router + shadcn/ui SPA over type-safe RPC. The node side shells out to git and exposes the repository; the same bundle runs as a live dev server or a fully static deployment.

Status, a SourceTree-style commit graph, branches, and diffs, plus staging, unstaging, and committing, all through the shared @devframes/service-git wire service. The UI follows the system light/dark preference with a manual toggle.

Install

npm i -D @devframes/plugin-git

Standalone CLI

Run the dashboard against the current repository:

pnpx @devframes/plugin-git         # dev server (live RPC over WebSocket)
pnpx @devframes/plugin-git build   # static deploy → dist-static/
pnpx @devframes/plugin-git --port 4000

Programmatic

createGitDevframe(options) returns a devframe definition you can mount into any host framework with devframe's adapters, or drive yourself.

import { createGitDevframe } from '@devframes/plugin-git'
import { createCac } from 'devframe/adapters/cac'

await createCac(createGitDevframe({ repoRoot: process.cwd() })).parse()

| Option | Default | Description | |--------|---------|-------------| | repoRoot | the devframe cwd | Repository directory to inspect. | | basePath | adapter-resolved | Mount path (/ standalone, /__git/ hosted). | | distDir | bundled SPA | Override the served SPA directory. | | port | 9710 | Preferred dev-server port. |

RPC

All git work runs through the @devframes/service-git wire service, which this devframe declares (services) and its SPA calls directly over devframes:service:git:*. The read functions are query functions that degrade to an empty, isRepo: false result outside a git repository; the definition opts them into the static build via rpc.snapshot (resolved live over WebSocket in dev, served from a build-time snapshot for static deploys).

• devframes:service:git:status: branch, upstream tracking (ahead/behind), staged / unstaged / untracked files, parsed from git status --porcelain=v2.
• devframes:service:git:log: paginated commit history (limit / skip) including parent hashes, which drive the commit graph.
• devframes:service:git:branches: local branches with SHA, upstream, ahead/behind, tip subject.
• devframes:service:git:diff: per-file added/deleted counts for the working tree or index, plus a unified patch for a selected file.

Write actions are action functions, always exposed by the service, with write authorization governed by the connection-trust boundary. Each returns fresh status (commit returns a result):

• devframes:service:git:stage: git add the given paths.
• devframes:service:git:unstage: git restore --staged the given paths.
• devframes:service:git:commit: commit the staged changes with a message.

Develop

pnpm -C plugins/git dev     # client (Next.js HMR) + RPC backend together
pnpm -C plugins/git build   # tsdown (node) + next build (SPA) → dist/

pnpm dev starts the Next.js dev server (with hot-reload) and the devframe RPC/WebSocket backend at the same time, then prints both URLs; open the UI one. The SPA connects to the backend over the WebSocket port carried in NEXT_PUBLIC_DEVFRAME_WS. Override ports with PORT (UI) and DEVFRAME_GIT_PORT (backend). Run a single side with dev:client or dev:server.

The SPA is a standard shadcn/ui setup (Tailwind v4, components/ui/*). Three Next.js settings in app/next.config.mjs keep it portable: output: 'export' (devframe owns the server), assetPrefix: '.' (relative assets so the same bundle works at any base), and trailingSlash: true (composes with devframe's static directory-with-index resolution).