nGitDB

nGitDB is a TypeScript library for teams that keep structured JSON data in Git repositories and need safe, reviewable updates.

It provides a small workflow-aware API for:

• reading JSON resources by canonical resource path
• applying deterministic partial patches
• validating staged changes before commit
• protecting human-owned fields from machine overwrite
• isolating edits in branch-backed sessions
• creating GitHub commits and pull requests for review workflows

Install

npm install @nuanst-one/ngitdb

GitHub Action

For Python-first or non-TypeScript workflows, run your generator first and let the nGitDB Action publish the review PR.

permissions:
  contents: write
  pull-requests: write

steps:
  - uses: actions/checkout@v4

  - name: Build nGitDB batch
    run: python scripts/build_ngitdb_batch.py --output tmp/ngitdb.batch.json

  - name: Publish nGitDB updates
    uses: nuanst-gmbh/nGitDB@v0
    with:
      batch-file: tmp/ngitdb.batch.json
      session-key: company-enrichment
      commit-message: Update generated company data
      pr-title: Update generated company data
      pr-body: Generated by nGitDB.
      resource-config: |
        {
          "baseBranch": "main",
          "resourceRoot": "data",
          "resources": {
            "companies": {
              "fileName": "company.json",
              "ownership": {
                "legalName": "human-owned",
                "machine": "machine-owned"
              }
            }
          }
        }

The batch file contains patch operations:

{
  "resources": [
    {
      "resourcePath": "companies/acme-gmbh",
      "patch": {
        "machine.summary": "Industrial supplier with operations in Berlin"
      }
    }
  ]
}

When this repository is private, enable GitHub Actions access for same-organization client repositories before using nuanst-gmbh/nGitDB@v0.

Example

import { createGitDB } from "@nuanst-one/ngitdb";

const db = createGitDB({
  repositoryRoot: process.cwd(),
  backend: { type: "github" },
  baseBranch: "main",
  resources: {
    companies: {
      fileName: "company.json",
      ownership: {
        legalName: "human-owned",
        machine: "machine-owned",
      },
    },
  },
});

await db.startSession("acme-gmbh");

await db.patch("companies/acme-gmbh", {
  "machine.summary": "Industrial supplier with operations in Berlin",
  "machine.lastEnrichedAt": "2026-04-21",
});

await db.commit("Enrich company profile for acme-gmbh");

const pullRequest = await db.createPullRequest({
  title: "Enrich acme-gmbh company profile",
});

In GitHub Actions, backend: { type: "github" } reads GITHUB_REPOSITORY and GITHUB_TOKEN by default. The workflow needs:

permissions:
  contents: write
  pull-requests: write

Install nGitDB as a package dependency in consumer repositories and run npm ci in CI. Directly cloning this repository is for nGitDB development, not the supported consumer install path. See the GitHub Actions guide for a minimal workflow, reusable workflow notes, and current resource-creation limits.

Documentation

• Documentation wiki
• Getting started
• GitHub Actions
• API reference
• Prompt recipes
• Roadmap and limits

AI Assistant Support

nGitDB ships consumer prompt recipes and a Codex plugin with reusable skills:

• ngitdb-starter: start a new TypeScript project with nGitDB
• ngitdb-integrator: add nGitDB to an existing JSON workflow
• ngitdb-reviewer: review an nGitDB integration for safety gaps

The plugin source is available under plugins/ngitdb.

Current Status

The current implementation provides the V1 library surface with two supported backends:

• backend: { type: "github" } creates or resumes a GitHub session branch, creates commits with the Git database API, and creates or updates a pull request.
• backend: { type: "local" } or an omitted backend writes committed session artifacts under .ngitdb/sessions/... for offline development and tests.

Development

npm install
npm run build
npm run build:action
npm test

The package build emits TypeScript declarations plus an obfuscated/minified runtime bundle. The GitHub Action bundle is minified and verified before publish.