feat(plugins): add @devframes/plugin-git Git dashboard (#38)

Author: antfubot

examples/next-runtime-snapshot/package.json

@@ -10,7 +10,7 @@
     "next-runtime-snapshot": "./bin.mjs"
   },
   "scripts": {
-    "build": "next build src/client && rm -rf dist/client && mkdir -p dist && cp -r src/client/out dist/client",
+    "build": "next build src/client && node scripts/build-spa.mjs",
     "cli:build": "node bin.mjs build --out-dir dist/static",
     "dev": "node bin.mjs",
     "next:dev": "next dev src/client",

examples/next-runtime-snapshot/scripts/build-spa.mjs

@@ -0,0 +1,5 @@
+import { cpSync, mkdirSync, rmSync } from 'node:fs'
+
+rmSync('dist/client', { recursive: true, force: true })
+mkdirSync('dist', { recursive: true })
+cpSync('src/client/out', 'dist/client', { recursive: true })

plugins/code-server/package.json

@@ -42,6 +42,7 @@
   "scripts": {
     "build": "tsdown && vite build --config src/spa/vite.config.ts",
     "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
     "dev": "vite --config src/spa/vite.config.ts --host 0.0.0.0",
     "storybook": "storybook dev -p 6006 --host 0.0.0.0",
     "build-storybook": "storybook build",

plugins/code-server/tsconfig.json

@@ -1,7 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "composite": true,
     "lib": ["esnext", "dom"]
-  }
+  },
+  "include": ["src", "test", "tsdown.config.ts"],
+  "exclude": ["dist", "src/spa/dist", ".next", "out", "node_modules"]
 }

plugins/git/.gitignore

@@ -0,0 +1,7 @@
+.next
+dist
+next-env.d.ts
+node_modules
+out
+.turbo
+storybook-static

plugins/git/.storybook/main.ts

@@ -0,0 +1,22 @@
+import type { StorybookConfig } from '@storybook/react-vite'
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react-oxc'
+
+const config: StorybookConfig = {
+  stories: ['../src/client/**/*.stories.@(ts|tsx)'],
+  addons: ['@storybook/addon-docs', '@storybook/addon-a11y'],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+  viteFinal(viteConfig) {
+    viteConfig.plugins ??= []
+    // Vite 8 bundles with rolldown/oxc, which doesn't transform JSX on its
+    // own; the React plugin wires up the automatic runtime so `.tsx` stories
+    // and views parse.
+    viteConfig.plugins.push(react(), tailwindcss())
+    return viteConfig
+  },
+}
+
+export default config

plugins/git/.storybook/preview.tsx

@@ -0,0 +1,42 @@
+import type { Decorator, Preview } from '@storybook/react-vite'
+import { useEffect } from 'react'
+import '../src/client/app/globals.css'
+
+const withTheme: Decorator = (Story, context) => {
+  const theme = context.globals.theme ?? 'dark'
+  useEffect(() => {
+    document.documentElement.classList.toggle('dark', theme === 'dark')
+  }, [theme])
+  return (
+    <div className="bg-background text-foreground flex h-svh justify-center p-6">
+      <div className="flex h-full w-full max-w-2xl flex-col overflow-hidden rounded-lg border p-3">
+        <Story />
+      </div>
+    </div>
+  )
+}
+
+const preview: Preview = {
+  parameters: {
+    layout: 'fullscreen',
+    controls: { expanded: true },
+  },
+  globalTypes: {
+    theme: {
+      description: 'Color theme',
+      defaultValue: 'dark',
+      toolbar: {
+        title: 'Theme',
+        icon: 'contrast',
+        items: [
+          { value: 'light', title: 'Light', icon: 'sun' },
+          { value: 'dark', title: 'Dark', icon: 'moon' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  decorators: [withTheme],
+}
+
+export default preview

plugins/git/.storybook/shims.d.ts

@@ -0,0 +1,3 @@
+// Storybook config files live outside the app's tsconfig, so declare the CSS
+// side-effect import used by `preview.tsx`.
+declare module '*.css'

plugins/git/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-PRESENT Anthony Fu <https://github.com/antfu>
+
+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.

plugins/git/README.md

@@ -0,0 +1,90 @@
+# @devframes/plugin-git
+
+Git integration for [devframe](https://github.com/devframes/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 are read-only;
+staging, unstaging, and committing are available when write mode is enabled. The
+UI follows the system **light/dark** preference with a manual toggle.
+
+## Install
+
+```sh
+npm i -D @devframes/plugin-git
+```
+
+## Standalone CLI
+
+Run the dashboard against the current repository:
+
+```sh
+npx devframe-git              # dev server (live RPC over WebSocket)
+npx devframe-git --write      # also enable staging / committing from the UI
+npx devframe-git build        # static deploy → dist-static/
+npx devframe-git --port 4000
+```
+
+## Programmatic
+
+`createGitDevframe(options)` returns a devframe definition you can mount into
+any host with devframe's adapters, or drive yourself.
+
+```ts
+import { createGitDevframe } from '@devframes/plugin-git'
+import { createCli } from 'devframe/adapters/cli'
+
+await createCli(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. |
+| `write` | `false` | Enable staging, unstaging, and committing from the UI. |
+
+## RPC surface
+
+The read functions are each a `query` with `snapshot: true`: resolved live over
+WebSocket in dev, and served from a snapshot baked at build time for static
+deploys. Each degrades to an empty, `isRepo: false` result outside a git
+repository.
+
+- `git:status` — branch, upstream tracking (ahead/behind), staged / unstaged /
+  untracked files, parsed from `git status --porcelain=v2`. Reports `canWrite`.
+- `git:log` — paginated commit history (`limit` / `skip`) including parent
+  hashes, which drive the commit graph.
+- `git:branches` — local branches with SHA, upstream, ahead/behind, tip subject.
+- `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, registered only when write mode is enabled
+(`createGitDevframe({ write: true })` or the `--write` flag) and gated behind
+`status.canWrite` in the UI. Each returns fresh status (commit returns a result):
+
+- `git:stage` — `git add` the given paths.
+- `git:unstage` — `git restore --staged` the given paths.
+- `git:commit` — commit the staged changes with a message.
+
+## Develop
+
+```sh
+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).