@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 fromgit 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 addthe given paths.devframes:service:git:unstage:git restore --stagedthe 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).