@gitsheets/core-napi 0.4.0 → 0.6.0

package/binding.cjs

@@ -149,6 +149,10 @@ module.exports = {
   // the filter (equality / nested / `$pred` engine snippets) runs in the core.
   recordQuery: wrap(addon.recordQuery),
   recordQueryCandidates: wrap(addon.recordQueryCandidates),
+  treeReadBlob: wrap(addon.treeReadBlob),
+  treeEntryHash: wrap(addon.treeEntryHash),
+  blobRead: wrap(addon.blobRead),
+  blobHeader: wrap(addon.blobHeader),
   templateFieldNames: wrap(addon.templateFieldNames),
   // Secondary indexing (lazy, in-memory). A unique conflict surfaces as a typed
   // IndexError(index_unique_conflict).
@@ -166,7 +170,12 @@ module.exports = {
   // `mapCoreError` where a typed instance is wanted.
   CoreTransaction: addon.CoreTransaction,
   coreDiscoverSheets: wrap(addon.coreDiscoverSheets),
+  syncBranch: wrap(addon.syncBranch),
+  isAncestor: wrap(addon.isAncestor),
+  mergeSheets: wrap(addon.mergeSheets),
+  mergeRecordTexts: wrap(addon.mergeRecordTexts),
   coreCheckValidators: wrap(addon.coreCheckValidators),
+  sheetConfigCheck: wrap(addon.sheetConfigCheck),
   // Consumer-side contract verification — the two-rung ladder behind
   // `openSheet(name, { contract })` (specs/behaviors/contracts.md "Consumer
   // verification"). A verification failure raises a typed

package/index.d.ts

@@ -235,15 +235,61 @@ export declare function substrateReset(): void
 /**
  * Query records under `base` in the tree `treeRef`, returning each matched
  * `{ path, record }` in sorted path order. The template prunes the walk; the
- * filter (equality / nested / `$pred` snippets) is applied to each candidate.
- * Batch-first: the whole query crosses the FFI once.
+ * filter (equality / nested / `$pred` snippets / `{ $gt, $gte, $lt, $lte }` ranges)
+ * is applied to each candidate; a range on a date-bucket path field prunes
+ * the walk to the bounded span of partitions. Batch-first: the whole query
+ * crosses the FFI once.
+ *
+ * Format-aware: pass `bodyField` (and optionally `titleField`) for a
+ * markdown/mdx sheet (the kind follows `extension`: `.mdx` → mdx, else
+ * markdown) and the core decodes each candidate through the frontmatter
+ * codec — `withBody: false` is the lazy-body switch (default `true`). Without
+ * `bodyField` records are canonical TOML. The binding never fetches record
+ * bytes itself (spec: `rust-core.md` "Query traversal + filtering").
+ */
+export declare function recordQuery(gitDir: string, treeRef: string, base: string, template: string, filter: object, extension?: string | undefined | null, bodyField?: string | undefined | null, titleField?: string | undefined | null, withBody?: boolean | undefined | null): Array<JsRecordEntry>
+/**
+ * A blob read by `treeRef:path` — the bytes plus the blob's object id, or
+ * `null` when nothing (or a subtree) lives at `path`. Backs sheet-config
+ * loading and lazy-body hydration without a `git cat-file` subprocess
+ * (spec: `rust-core.md` "Blob reads").
  */
-export declare function recordQuery(gitDir: string, treeRef: string, base: string, template: string, filter: object, extension?: string | undefined | null): Array<JsRecordEntry>
+export declare function treeReadBlob(gitDir: string, treeRef: string, path: string): JsBlobEntry | null
+/**
+ * The object id of the blob at `treeRef:path`, or `null` when absent or not
+ * a blob. The hash-only lookup (attachment handles, cache keys).
+ */
+export declare function treeEntryHash(gitDir: string, treeRef: string, path: string): string | null
+/**
+ * A blob's bytes by object id, or `null` when no object has that id. Backs
+ * attachment content reads and diff-side record reads.
+ */
+export declare function blobRead(gitDir: string, hash: string): Buffer | null
+/**
+ * An object header: `kind` (`blob` / `tree` / `commit` / `tag`) and `size` in
+ * bytes, read without inflating the object.
+ */
+export interface JsBlobHeader {
+  kind: string
+  size: number
+}
+/**
+ * The object header for `hash`, or `null` when no object has that id. The
+ * metadata behind a host `BlobHandle`'s `size` (specs/behaviors/attachments.md
+ * "Blob metadata and bounded buffering").
+ */
+export declare function blobHeader(gitDir: string, hash: string): JsBlobHeader | null
+/** A blob read by `treeRef:path`: its object id and bytes. */
+export interface JsBlobEntry {
+  hash: string
+  content: Buffer
+}
 /**
  * The pruning candidate set alone (no content filter applied) — the direct
  * parity target for the host `Template.queryTree`. `query` is a (partial)
- * record of the path-template input fields. Returns candidate record paths
- * (relative to `base`, no extension) in sorted order.
+ * record of the path-template input fields; a date-bucket field may carry a
+ * `{ $gte, $lt, … }` range object, which bounds the walk. Returns candidate
+ * record paths (relative to `base`, no extension) in sorted order.
  */
 export declare function recordQueryCandidates(gitDir: string, treeRef: string, base: string, template: string, query: JsValue, extension?: string | undefined | null): Array<string>
 /**
@@ -313,6 +359,12 @@ export interface JsTrailer {
  */
 export interface JsTransactionOptions {
   parent?: string
+  /**
+   * `transact({ parent: null })`: an orphan root commit — empty starting
+   * tree, no parents, always commits; `branch` is created (and must not
+   * already exist). `parent` is ignored when set.
+   */
+  orphan?: boolean
   branch?: string
   author?: JsAuthor
   committer?: JsAuthor
@@ -344,11 +396,100 @@ export interface JsAttachmentEntry {
   name: string
   hash: string
 }
+/** Options for [`sync_branch`]. */
+export interface JsSyncOptions {
+  /** Local branch (bare name or qualified ref). */
+  branch: string
+  /** Remote-tracking ref (or any commit-ish), e.g. `refs/remotes/origin/main`. */
+  remoteRef: string
+  /** `'fail'` (default) or `'preserve-branch'`. */
+  onConflict?: string
+  /** Prefix for the preserved branch; default `conflicts/`. */
+  conflictBranchPrefix?: string
+  /** Committer for replayed commits; default: the repository's identity. */
+  committer?: JsAuthor
+  timeSeconds: number
+  offsetMinutes: number
+}
+/** The result of [`sync_branch`]. */
+export interface JsSyncResult {
+  outcome: string
+  oldCommit: string
+  newCommit: string
+  ahead: number
+  behind: number
+  conflictCommit?: string
+  conflictBranch?: string
+}
+/**
+ * Classify the local branch against the remote-tracking tip and move it
+ * (fast-forward, replay, or preserve-on-conflict). The host fetches first
+ * and holds the write lock. See specs/behaviors/push-sync.md "Sync".
+ */
+export declare function syncBranch(gitDir: string, opts: JsSyncOptions): JsSyncResult
+/** Whether commit `a` is reachable from commit `b` (or equal). */
+export declare function isAncestor(gitDir: string, a: string, b: string): boolean
+export interface JsMergeOptions {
+  ours: string
+  theirs: string
+  openRoot?: string
+  /** `fail` (default) | `ours` | `theirs`. */
+  prefer?: string
+  /** Default true; false writes the tree and moves nothing. */
+  commit?: boolean
+  message?: string
+  author?: JsAuthor
+  committer?: JsAuthor
+  timeSeconds: number
+  offsetMinutes: number
+}
+export interface JsMergeConflict {
+  path: string
+  kind: string
+  field?: string
+  ours?: string
+  theirs?: string
+}
+export interface JsMergeResult {
+  outcome: string
+  oursCommit: string
+  theirsCommit: string
+  base?: string
+  tree?: string
+  commit?: string
+  mergedRecords: Array<string>
+  conflicts: Array<JsMergeConflict>
+}
+/**
+ * Sheet-aware merge of `theirs` into `ours` — record files changed on both
+ * sides are field-merged and written canonically; conflicts follow `prefer`
+ * or are reported. The host holds the write lock.
+ */
+export declare function mergeSheets(gitDir: string, opts: JsMergeOptions): JsMergeResult
+export interface JsRecordMergeOutcome {
+  text?: string
+  conflicts: Array<string>
+}
+/**
+ * Field-merge one record's base / ours / theirs texts through the sheet at
+ * `treeRef` (the merge-driver primitive): canonical text, or the conflicting
+ * field paths.
+ */
+export declare function mergeRecordTexts(gitDir: string, treeRef: string, sheetName: string, configPath: string, openRoot: string, base: string | undefined | null, ours: string, theirs: string, prefer?: string | undefined | null): JsRecordMergeOutcome
 /**
  * Discover every sheet declared in `<openRoot>/.gitsheets/*.toml` in the tree
  * `treeRef`. Sorted bare names. The `Store` discovery half (`openStore`).
  */
 export declare function coreDiscoverSheets(gitDir: string, treeRef: string, openRoot: string): Array<string>
+/**
+ * Open the sheet whose config blob lives at `configPath` in the tree `treeRef`
+ * and discard it — the full open-time validation the core performs
+ * (config parse, contract load/compile, template coherence per
+ * specs/behaviors/path-templates.md "Template fields must be
+ * schema-required") surfaced to the host as typed errors. The host calls it
+ * once per distinct config blob from `repo.openSheet`.
+ */
+export declare function sheetConfigCheck(gitDir: string, treeRef: string, sheetName: string, configPath: string, openRoot: string): void
 /**
  * The `openStore` `config_missing` check: every validator must name a declared
  * sheet. Throws `ConfigError(config_missing)` otherwise.
@@ -470,12 +611,13 @@ export declare class CoreTransaction {
   /** Stage a single attachment *(mutating)* — sugar over [`Self::set_attachments`]. */
   setAttachment(name: string, recordPath: string, attachmentName: string, blobHash: string): void
   /**
-   * Stage a raw text file at `path` in this transaction's private tree
-   * *(mutating)* — the generic file write the CLI uses to commit sheet-config
-   * edits (`init` / `infer` / `migrate-config`) atomically alongside nothing
-   * else. `path` is repo-root-relative. Returns the written blob hash.
+   * Stage a raw file at `path` in this transaction's private tree
+   * *(mutating)* — the public `tx.writeFile` (specs/api/transaction.md
+   * "Raw files"): a sheet config, a contract, a fixture, committed with the
+   * record changes it belongs with. `path` is repo-root-relative; `content`
+   * is UTF-8 text or raw bytes. Returns the written blob hash.
    */
-  writeFile(path: string, content: string): string
+  writeFile(path: string, content: string | Buffer): string
   /**
    * Delete a raw file at `path` (repo-root-relative) in this transaction's
    * private tree *(mutating)* — `write_file`'s inverse. Returns whether a
@@ -510,6 +652,22 @@ export declare class CoreTransaction {
    * Read-only — does not mark the transaction mutated.
    */
   list(name: string, withBody: boolean): Array<JsRecordEntry>
+  /**
+   * Query the sheet's records in the transaction's private tree — pruned by
+   * the path template exactly like a committed-ref query, decoded through
+   * the format codec, `withBody` the lazy-body switch (spec:
+   * `api/transaction.md` "Read isolation"). The filter takes the same forms
+   * as `recordQuery` (equality / nested / `$pred` / ranges). Read-only —
+   * does not mark the transaction mutated.
+   */
+  query(name: string, filter: object, withBody: boolean): Array<JsRecordEntry>
+  /**
+   * Read the one record at `recordPath` (relative to the sheet's base, no
+   * extension) in the transaction's private tree, decoded through the format
+   * codec — the tx-bound `Sheet.get`. `null` when absent; `withBody` is the
+   * lazy-body switch. Read-only.
+   */
+  readRecord(name: string, recordPath: string, withBody: boolean): JsValue | null
   /** The parent commit hash captured at open (null on a fresh repo). */
   parentCommitHash(): string | null
   /**

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { roundtrip, parseRecords, serializeRecords, renderPathsBatch, validateBatch, canonicalContractHash, validateContractName, contractPath, checkContractDocument, contractLoad, verifySheetContract, runComparator, collatorSort, CompiledDefinition, recordRead, recordWrite, recordDelete, recordList, writeBlob, substrateStats, substrateReset, recordQuery, recordQueryCandidates, templateFieldNames, recordIndexUnique, recordIndexMulti, createPatch, applyMergePatch, diffRecords, simulateCoreError, CoreTransaction, coreDiscoverSheets, coreCheckValidators, markdownSerialize, markdownNormalizeBody, markdownParse, markdownParseHeaderOnly, markdownExtractH1, markdownRewriteH1 } = nativeBinding
+const { roundtrip, parseRecords, serializeRecords, renderPathsBatch, validateBatch, canonicalContractHash, validateContractName, contractPath, checkContractDocument, contractLoad, verifySheetContract, runComparator, collatorSort, CompiledDefinition, recordRead, recordWrite, recordDelete, recordList, writeBlob, substrateStats, substrateReset, recordQuery, treeReadBlob, treeEntryHash, blobRead, blobHeader, recordQueryCandidates, templateFieldNames, recordIndexUnique, recordIndexMulti, createPatch, applyMergePatch, diffRecords, simulateCoreError, CoreTransaction, syncBranch, isAncestor, mergeSheets, mergeRecordTexts, coreDiscoverSheets, sheetConfigCheck, coreCheckValidators, markdownSerialize, markdownNormalizeBody, markdownParse, markdownParseHeaderOnly, markdownExtractH1, markdownRewriteH1 } = nativeBinding
 
 module.exports.roundtrip = roundtrip
 module.exports.parseRecords = parseRecords
@@ -334,6 +334,10 @@ module.exports.writeBlob = writeBlob
 module.exports.substrateStats = substrateStats
 module.exports.substrateReset = substrateReset
 module.exports.recordQuery = recordQuery
+module.exports.treeReadBlob = treeReadBlob
+module.exports.treeEntryHash = treeEntryHash
+module.exports.blobRead = blobRead
+module.exports.blobHeader = blobHeader
 module.exports.recordQueryCandidates = recordQueryCandidates
 module.exports.templateFieldNames = templateFieldNames
 module.exports.recordIndexUnique = recordIndexUnique
@@ -343,7 +347,12 @@ module.exports.applyMergePatch = applyMergePatch
 module.exports.diffRecords = diffRecords
 module.exports.simulateCoreError = simulateCoreError
 module.exports.CoreTransaction = CoreTransaction
+module.exports.syncBranch = syncBranch
+module.exports.isAncestor = isAncestor
+module.exports.mergeSheets = mergeSheets
+module.exports.mergeRecordTexts = mergeRecordTexts
 module.exports.coreDiscoverSheets = coreDiscoverSheets
+module.exports.sheetConfigCheck = sheetConfigCheck
 module.exports.coreCheckValidators = coreCheckValidators
 module.exports.markdownSerialize = markdownSerialize
 module.exports.markdownNormalizeBody = markdownNormalizeBody

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitsheets/core-napi",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Node.js native binding for gitsheets-core — the FFI marshalling boundary.",
   "main": "binding.cjs",
   "types": "index.d.ts",
@@ -33,19 +33,19 @@
     "index.d.ts"
   ],
   "optionalDependencies": {
-    "@gitsheets/core-napi-linux-x64-gnu": "0.4.0",
-    "@gitsheets/core-napi-linux-arm64-gnu": "0.4.0",
-    "@gitsheets/core-napi-linux-x64-musl": "0.4.0",
-    "@gitsheets/core-napi-darwin-arm64": "0.4.0",
-    "@gitsheets/core-napi-darwin-x64": "0.4.0",
-    "@gitsheets/core-napi-win32-x64-msvc": "0.4.0"
+    "@gitsheets/core-napi-linux-x64-gnu": "0.6.0",
+    "@gitsheets/core-napi-linux-arm64-gnu": "0.6.0",
+    "@gitsheets/core-napi-linux-x64-musl": "0.6.0",
+    "@gitsheets/core-napi-darwin-arm64": "0.6.0",
+    "@gitsheets/core-napi-darwin-x64": "0.6.0",
+    "@gitsheets/core-napi-win32-x64-msvc": "0.6.0"
   },
   "scripts": {
     "artifacts": "napi artifacts",
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
-    "test": "node --test test/roundtrip.mjs test/errors.mjs test/canonical.mjs test/path-template.mjs test/validation-parity.mjs test/engine-parity.mjs test/collator-parity.mjs test/record-crud.mjs test/record-query.mjs test/record-index.mjs test/sheet-store.mjs test/sheet-markdown.mjs test/sheet-attachments.mjs test/contracts.mjs",
+    "test": "node --test test/roundtrip.mjs test/errors.mjs test/canonical.mjs test/path-template.mjs test/validation-parity.mjs test/engine-parity.mjs test/collator-parity.mjs test/record-crud.mjs test/record-query.mjs test/record-index.mjs test/sheet-store.mjs test/sheet-markdown.mjs test/sheet-attachments.mjs test/contracts.mjs test/sheet-config-check.mjs test/orphan-and-files.mjs",
     "bench": "node bench/query-bench.mjs",
     "version": "napi version"
   },
@@ -54,6 +54,6 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "rfc6902": "^5.2.0",
-    "smol-toml": "^1.7.0"
+    "smol-toml": "^1.8.0"
   }
 }