Skip to content

git

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

git

README.md

@devframes/plugin-git

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

Git integration for devframe — a repository dashboard with a Next.js App Router + shadcn/ui SPA over type-safe RPC. The host process 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 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 surface

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 host's 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 src/client/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).