@nuanst-one/ngitdb 0.1.0

package/plugins/ngitdb/skills/ngitdb-integrator/references/api.md

@@ -0,0 +1,93 @@
+# API
+
+Use:
+
+```ts
+import { createGitDB } from "ngitdb";
+```
+
+Core workflow:
+
+```ts
+const db = createGitDB(config);
+
+await db.startSession("acme-gmbh");
+
+await db.patch("companies/acme-gmbh", {
+  "machine.summary": "Updated summary",
+});
+
+await db.commit("Update company enrichment");
+
+const pullRequest = await db.createPullRequest({
+  title: "Update company enrichment",
+});
+```
+
+Resource config:
+
+```ts
+const config = {
+  repositoryRoot: process.cwd(),
+  baseBranch: "main",
+  resourceRoot: "data",
+  resources: {
+    companies: {
+      fileName: "company.json",
+      ownership: {
+        legalName: "human-owned",
+        machine: "machine-owned",
+      },
+      validate: validateCompany,
+    },
+  },
+};
+```
+
+GitHub Action workflow for Python/non-TypeScript producers:
+
+```yaml
+permissions:
+  contents: write
+  pull-requests: write
+
+steps:
+  - uses: actions/checkout@v4
+  - run: python scripts/build_ngitdb_batch.py --output tmp/ngitdb.batch.json
+  - 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
+      resource-config: |
+        {
+          "baseBranch": "main",
+          "resources": {
+            "companies": {
+              "fileName": "company.json",
+              "ownership": {
+                "legalName": "human-owned",
+                "machine": "machine-owned"
+              }
+            }
+          }
+        }
+```
+
+Batch file:
+
+```json
+{
+  "resources": [
+    {
+      "resourcePath": "companies/acme-gmbh",
+      "patch": {
+        "machine.summary": "Updated summary"
+      }
+    }
+  ]
+}
+```
+
+Action `resource-config` is JSON and cannot include validator functions.

package/plugins/ngitdb/skills/ngitdb-integrator/references/migration-patterns.md

@@ -0,0 +1,44 @@
+# Migration Patterns
+
+Replace this pattern:
+
+```ts
+const file = JSON.parse(await readFile(filePath, "utf8"));
+file.machine.summary = summary;
+await writeFile(filePath, JSON.stringify(file, null, 2));
+```
+
+with:
+
+```ts
+await db.startSession(sessionKey);
+await db.patch(resourcePath, {
+  "machine.summary": summary,
+});
+await db.commit(message);
+```
+
+When the old code updates many fields, split them by ownership:
+
+- Move machine-safe generated fields into one `db.patch(...)`.
+- Leave human-owned fields out of automated workflows.
+- Add tests that prove human-owned fields are rejected.
+
+If the existing file layout does not match `data/<collection>/<id>/<fileName>`, prefer configuring `resourceRoot` and `fileName` before moving files.
+
+For Python or non-TypeScript workflows, replace direct JSON writes with a batch file for the nGitDB GitHub Action:
+
+```json
+{
+  "resources": [
+    {
+      "resourcePath": "companies/acme-gmbh",
+      "patch": {
+        "machine.summary": "Updated summary"
+      }
+    }
+  ]
+}
+```
+
+Then call `nuanst-gmbh/nGitDB@v0` after the generator step. Keep the batch limited to machine-owned fields.

package/plugins/ngitdb/skills/ngitdb-integrator/references/testing.md

@@ -0,0 +1,12 @@
+# Testing
+
+For retrofit work, add tests around the migrated path:
+
+- existing resource can still be read
+- migrated machine-owned patch writes the expected staged document
+- default source file is not changed by session commit artifacts
+- human-owned field patch is rejected
+- invalid staged state is rejected on commit
+- workflow returns pull request draft metadata
+
+Keep tests close to the existing test style. Avoid adding a new test framework.

package/plugins/ngitdb/skills/ngitdb-reviewer/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ngitdb-reviewer
+description: Review an existing nGitDB integration for safety, correctness, and test coverage. Use when users ask for a review, audit, risk assessment, or critique of code that uses nGitDB, db.patch, ownership maps, validators, sessions, commits, or pull request draft workflows.
+---
+
+# nGitDB Reviewer
+
+Use this skill in code-review mode. Findings should lead, ordered by severity, with file and line references.
+
+## Review Flow
+
+1. Locate `createGitDB(...)` configuration and all `db.read`, `db.startSession`, `db.patch`, `db.commit`, and `db.createPullRequest` calls.
+2. Trace each write workflow from user or machine input to patch document.
+3. Check ownership maps against the actual JSON shape.
+4. Check validators and when they run.
+5. Check tests for ownership, validation, and session misuse.
+6. For GitHub Action integrations, check batch schema, workflow permissions, resource-config ownership, and whether Python emits only machine-owned patches.
+7. Report concrete risks before summaries.
+
+## High-Severity Patterns
+
+- Direct full-file JSON writes replacing nGitDB patch workflow.
+- Machine workflows patching human-owned fields.
+- Missing ownership on write-enabled resources.
+- Validators missing for write-enabled resources.
+- `commit(...)` or `createPullRequest(...)` called without a controlled session flow.
+- GitHub Action workflows missing `contents: write` or `pull-requests: write`.
+- Batch files that contain full documents, raw file paths, or human-owned fields.
+- JSON Action config that assumes function validators will run.
+
+## References
+
+- Read `references/checklist.md` for the full review checklist.
+- Read `references/risk-patterns.md` for common unsafe patterns.

package/plugins/ngitdb/skills/ngitdb-reviewer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "nGitDB Reviewer"
+  short_description: "Review nGitDB integrations for unsafe writes and missing safety checks"
+  default_prompt: "Review this nGitDB integration for safety and test coverage."

package/plugins/ngitdb/skills/ngitdb-reviewer/references/checklist.md

@@ -0,0 +1,17 @@
+# Review Checklist
+
+Check:
+
+- Resource paths use `<collection>/<id>`.
+- Resource definitions exist for every write-enabled collection.
+- Ownership maps are present for resources modified by automation.
+- Human-owned fields include identity, legal, source, approval, and manually curated fields.
+- Machine-owned fields are limited to generated or derived data.
+- Patch documents only target machine-owned fields.
+- Validators return actionable issue strings.
+- Commits cannot happen with invalid staged documents.
+- Pull request draft metadata has clear title and body when useful.
+- Tests cover read, patch, ownership rejection, validation failure, session misuse, and pull request draft creation.
+- GitHub Action workflows grant `contents: write` and `pull-requests: write`.
+- GitHub Action batches use `resources: [{ resourcePath, patch }]`, not full-file replacement.
+- GitHub Action `resource-config` includes ownership and does not rely on validator functions.

package/plugins/ngitdb/skills/ngitdb-reviewer/references/risk-patterns.md

@@ -0,0 +1,35 @@
+# Risk Patterns
+
+Unsafe full-file replacement:
+
+```ts
+await writeFile(filePath, JSON.stringify(nextDocument, null, 2));
+```
+
+Uncontrolled machine ownership:
+
+```ts
+ownership: {
+  "*": "machine-owned",
+}
+```
+
+Vague validation:
+
+```ts
+return ["invalid"];
+```
+
+Patch outside explicit workflow:
+
+```ts
+await db.patch(resourcePath, patch);
+```
+
+without a preceding controlled `startSession(...)`.
+
+Weak review metadata:
+
+```ts
+await db.createPullRequest({ title: "Update" });
+```

package/plugins/ngitdb/skills/ngitdb-starter/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ngitdb-starter
+description: Set up nGitDB from the beginning in a new TypeScript project or a project without an established JSON resource model. Use when users ask to start with nGitDB, create a Git-backed JSON data layout, define initial resource collections, ownership rules, validators, example workflows, or tests for a greenfield nGitDB setup.
+---
+
+# nGitDB Starter
+
+Use this skill to create a conservative greenfield nGitDB setup.
+
+## Workflow
+
+1. Inspect the project structure, package manager, TypeScript config, and test framework.
+2. Propose a minimal resource model before adding code when the domain is unclear.
+3. Create JSON resources under `data/<collection>/<id>/<fileName>` unless the project already has a stronger convention.
+4. Configure `createGitDB(...)` with explicit `resources`.
+5. Define ownership before writing workflow code.
+6. Add validators for every write-enabled resource.
+7. Add one end-to-end workflow using `startSession -> patch -> commit -> createPullRequest`.
+8. Add tests for read, patch success, ownership rejection, validation failure, and session misuse.
+9. If data is produced outside Node, prefer the nGitDB GitHub Action: generate a batch file with `resources: [{ resourcePath, patch }]`, then use `nuanst-gmbh/nGitDB@v0`.
+
+## Guardrails
+
+- Use `db.patch(...)` for writes. Do not add direct full-file JSON replacement APIs.
+- Keep human-authored identity, legal, approval, and canonical source fields `human-owned`.
+- Put machine enrichment, extraction, scoring, generated summaries, and metadata under machine-owned fields.
+- Keep resource paths in `<collection>/<id>` format.
+- Keep initial data and tests small.
+- For GitHub Action config, remember JSON `resource-config` supports ownership but not function validators.
+
+## References
+
+- Read `references/resource-model.md` when designing the initial files.
+- Read `references/safety-model.md` when defining ownership and validators.
+- Read `references/testing.md` before adding tests.

package/plugins/ngitdb/skills/ngitdb-starter/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "nGitDB Starter"
+  short_description: "Start new TypeScript projects with safe nGitDB JSON workflows"
+  default_prompt: "Set up nGitDB from the beginning in this TypeScript project."

package/plugins/ngitdb/skills/ngitdb-starter/references/resource-model.md

@@ -0,0 +1,36 @@
+# Resource Model
+
+Use this default layout:
+
+```txt
+data/<collection>/<id>/<fileName>
+```
+
+Example:
+
+```txt
+data/companies/acme-gmbh/company.json
+```
+
+Use resource paths in code:
+
+```txt
+companies/acme-gmbh
+```
+
+Start with one collection unless the user explicitly needs more. Prefer plural collection names and stable lowercase identifiers.
+
+Minimal resource definition:
+
+```ts
+resources: {
+  companies: {
+    fileName: "company.json",
+    ownership: {
+      legalName: "human-owned",
+      machine: "machine-owned",
+    },
+    validate: validateCompany,
+  },
+}
+```

package/plugins/ngitdb/skills/ngitdb-starter/references/safety-model.md

@@ -0,0 +1,40 @@
+# Safety Model
+
+Default ownership policy:
+
+- Human-owned: canonical identity, legal names, approval status, manually curated source fields.
+- Machine-owned: generated summaries, enrichment timestamps, extraction output, analysis, scores.
+
+Prefer this document shape:
+
+```json
+{
+  "legalName": "ACME GmbH",
+  "machine": {
+    "summary": "Legacy summary",
+    "lastEnrichedAt": "2026-04-20"
+  }
+}
+```
+
+Validation must return specific issue strings:
+
+```ts
+const validateCompany = (document: JsonObject): readonly string[] => {
+  const issues: string[] = [];
+
+  if (typeof document.legalName !== "string" || document.legalName.length === 0) {
+    issues.push("legalName must be a non-empty string");
+  }
+
+  if (
+    document.machine === null ||
+    typeof document.machine !== "object" ||
+    Array.isArray(document.machine)
+  ) {
+    issues.push("machine must be an object");
+  }
+
+  return issues;
+};
+```

package/plugins/ngitdb/skills/ngitdb-starter/references/testing.md

@@ -0,0 +1,13 @@
+# Testing
+
+Add focused tests for:
+
+- reading a resource by resource path
+- deterministic session branch naming when `currentDate` is set
+- rejecting `patch(...)` outside a session
+- allowing patches to machine-owned fields
+- rejecting patches to human-owned fields
+- rejecting invalid staged documents during `commit(...)`
+- creating pull request draft metadata after commit
+
+Use temporary repositories or fixtures. Avoid tests that depend on a real remote GitHub repository.