@nuanst-one/ngitdb 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# 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
+
+```bash
+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.
+
+```yaml
+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:
+
+```json
+{
+  "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
+
+```ts
+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:
+
+```yaml
+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](docs/wiki/github-actions.md) for a minimal workflow, reusable workflow notes, and current resource-creation limits.
+
+## Documentation
+
+- [Documentation wiki](docs/wiki/index.md)
+- [Getting started](docs/wiki/getting-started.md)
+- [GitHub Actions](docs/wiki/github-actions.md)
+- [API reference](docs/wiki/api-reference.md)
+- [Prompt recipes](docs/wiki/prompt-recipes.md)
+- [Roadmap and limits](docs/wiki/roadmap-and-limits.md)
+
+## 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
+
+```bash
+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.