@scolladon/tsgit 1.3.0 → 2.0.1

package/dist/types/primitives/index.d.cts

@@ -1,9 +1,17 @@
-import { G as GitIndex, I as IndexEntry } from '../chunks/write-tree-CuhpWKFo.cjs';
-export { H as HookInput, c as catFileBatch, a as createCommit, d as diffTrees, g as getRepoRoot, m as mergeBase, r as readBlob, b as readIndex, e as readObject, f as readTree, h as recordRefUpdate, i as resolveRef, j as runHook, s as sparseCheckoutPath, u as updateRef, w as walkCommits, k as walkSubmodules, l as walkTree, n as walkWorkingTree, o as writeObject, p as writeSymbolicRef, q as writeTree } from '../chunks/write-tree-CuhpWKFo.cjs';
-import { d as FilePath, O as ObjectId, b as Context, R as RefName } from '../chunks/context-CMrHCVwK.cjs';
-import { F as FileMode, A as AuthorIdentity, q as ReflogEntry } from '../chunks/reflog-entry-DNvSz7S5.cjs';
-export { C as CatFileBatchEntry, a as CatFileBatchOptions, c as CreateCommitInput, D as DiffTreesInput, d as DiffTreesOptions, M as MAX_COMMIT_MESSAGE_BYTES, e as MAX_GITIGNORE_BYTES, f as MAX_GITMODULES_BYTES, g as MAX_HAVES, h as MAX_INDEX_BYTES, i as MAX_PEEL_DEPTH, j as MAX_PUSH_OBJECTS, k as MAX_REFLOG_BYTES, l as MAX_SUBMODULE_DEPTH, m as MAX_SYMBOLIC_REF_DEPTH, n as MAX_WALK_QUEUE_SIZE, o as MAX_WALK_SEEDS, p as MAX_WORKING_TREE_BLOB_BYTES, R as ReadObjectOptions, r as ResolveRefOptions, S as SubmoduleEntry, s as TreeDiff, U as UpdateRefOptions, W as WalkCommitsOptions, u as WalkIgnorePredicate, v as WalkSubmodulesOptions, w as WalkTreeEntry, x as WalkTreeOptions, y as WalkWorkingTreeEntry, z as WalkWorkingTreeOptions } from '../chunks/reflog-entry-DNvSz7S5.cjs';
-import { b as HttpTransport } from '../chunks/http-transport-DirKfK2S.cjs';
+import { G as GitIndex, I as IndexEntry } from '../chunks/index-entry-DtEbVpOG.cjs';
+import { c as FilePath, O as ObjectId, b as Context, j as RefName } from '../chunks/context-YDw6qicq.cjs';
+import { F as FileMode, b as ConfigScope, c as ConfigKey, A as AuthorIdentity, R as ReflogEntry } from '../chunks/reflog-entry-BbNnXCTC.cjs';
+export { C as CatFileBatchEntry, d as CatFileBatchOptions, e as CreateCommitInput, D as DiffTreesInput, f as DiffTreesOptions, M as MAX_COMMIT_MESSAGE_BYTES, g as MAX_GITIGNORE_BYTES, h as MAX_GITMODULES_BYTES, i as MAX_HAVES, j as MAX_INDEX_BYTES, k as MAX_PEEL_DEPTH, l as MAX_PUSH_OBJECTS, m as MAX_REFLOG_BYTES, n as MAX_SUBMODULE_DEPTH, o as MAX_SYMBOLIC_REF_DEPTH, p as MAX_WALK_QUEUE_SIZE, q as MAX_WALK_SEEDS, r as MAX_WORKING_TREE_BLOB_BYTES, s as ReadObjectOptions, t as ResolveRefOptions, S as SubmoduleEntry, T as TreeDiff, U as UpdateRefOptions, W as WalkCommitsOptions, u as WalkIgnorePredicate, v as WalkSubmodulesOptions, w as WalkTreeEntry, x as WalkTreeOptions, y as WalkWorkingTreeEntry, z as WalkWorkingTreeOptions } from '../chunks/reflog-entry-BbNnXCTC.cjs';
+export { H as HashBlobOptions, z as HookInput, I as IsIgnoredMatch, A as IsIgnoredMatchSource, B as IsIgnoredQuery, S as SetEntryFlagsOptions, C as StageEntryOptions, D as StageEntrySource, U as UnstageEntryOptions, c as catFileBatch, a as createCommit, d as diffTrees, g as getRepoRoot, h as hashBlob, i as isIgnored, m as mergeBase, r as readBlob, b as readIndex, e as readObject, f as readTree, j as recordRefUpdate, k as resolveRef, l as runHook, s as setEntryFlags, E as sparseCheckoutPath, n as stageEntry, u as unstageEntry, o as updateRef, w as walkCommits, p as walkSubmodules, q as walkTree, t as walkWorkingTree, v as writeObject, x as writeSymbolicRef, y as writeTree } from '../chunks/write-tree-C3oNxOlX.cjs';
+import { H as HttpTransport } from '../chunks/http-transport--_NdQOiw.cjs';
+
+interface FlatTreeEntry {
+    readonly id: ObjectId;
+    readonly mode: FileMode;
+}
+interface FlatTree {
+    readonly entries: ReadonlyMap<FilePath, FlatTreeEntry>;
+}
 
 /** `true` ⇒ the path is in the sparse set (materialise it). */
 type SparseMatcher = (path: FilePath) => boolean;
@@ -107,6 +115,22 @@ interface BuildPackResult {
 }
 declare const buildPack: (ctx: Context, input: BuildPackInput) => Promise<BuildPackResult>;
 
+/**
+ * Single source of truth for "is this index entry dirty in the working tree?".
+ *
+ * Compares the working file at `entry.path` against the entry's `(id, mode)`:
+ * `absent` when no working file exists, `modified` when the derived working
+ * mode or the content hash differs, else `unchanged`. Content is hashed via the
+ * uncapped `serializeAndHash` core (never the size-capped `hashBlob` write path),
+ * so a read-only comparison never throws on a large working file. Symlink
+ * content is its target (`readlink`), not the followed file.
+ *
+ * Consumed by `status` (reporting) and `rm` (the local-modification valve).
+ */
+
+type WorkingTreeComparison = 'absent' | 'unchanged' | 'modified';
+declare const compareWorkingTreeEntry: (ctx: Context, entry: IndexEntry) => Promise<WorkingTreeComparison>;
+
 /**
  * Subset of `.git/config` that v1 commands consume. Only fields actually used by
  * commands are typed — the parser ignores everything else (lenient, like git itself).
@@ -126,6 +150,8 @@ interface ParsedConfig {
     };
     readonly remote?: ReadonlyMap<string, {
         readonly url?: string;
+        /** `remote.<name>.pushurl` — push-only URL; `push` reads `pushUrl ?? url`. */
+        readonly pushUrl?: string;
         readonly fetch?: ReadonlyArray<string>;
         /** `remote.<name>.promisor` — true when this is a partial-clone promisor remote. */
         readonly promisor?: boolean;
@@ -156,6 +182,98 @@ declare const readConfig: (ctx: Context) => Promise<ParsedConfig>;
  * stale parse.
  */
 declare const invalidateConfigCache: (ctx: Context) => void;
+/**
+ * One `[section "subsection"]` block of a git-config-format INI file: the
+ * section name, an optional quoted subsection, and its key/value entries.
+ * Exported so `.gitmodules` parsing — byte-identical grammar — reuses one
+ * tokenizer (ADR-086).
+ */
+interface IniSection {
+    readonly section: string;
+    readonly subsection: string | undefined;
+    readonly entries: ReadonlyArray<{
+        readonly key: string;
+        readonly value: string;
+    }>;
+}
+/**
+ * Tokenize git-config-format INI text into its sections. Lenient, like git:
+ * orphan and malformed lines are skipped; comments and backslash
+ * continuations are honored.
+ */
+declare const parseIniSections: (text: string) => ReadonlyArray<IniSection>;
+
+/**
+ * Drop the per-scope sections cache for a single `Context`. Called by
+ * `invalidateConfigCache` in `config-read.ts` so writers can invalidate both
+ * caches atomically.
+ */
+declare const invalidateScopedConfigCache: (ctx: Context) => void;
+/**
+ * Read the raw IniSection array for a single config scope, or a scope-tagged
+ * flat array merged in precedence order (`system → global → local → worktree`)
+ * when `scope` is omitted.
+ *
+ * Per-Context, per-scope cached: a second call with the same `(ctx, scope)`
+ * shares the in-flight promise of the first. `invalidateConfigCache(ctx)` (from
+ * `config-read.ts`) drops the cached entries here too.
+ *
+ * In the merged-read path (`scope` omitted), scopes that are unavailable on
+ * the current adapter (`CONFIG_SCOPE_NOT_AVAILABLE`, `CONFIG_SYSTEM_PATH_UNRESOLVED`)
+ * are silently skipped — the caller gets whatever scopes the adapter can
+ * actually surface. Single-scope calls raise instead, so the caller can react
+ * to a missing scope explicitly.
+ */
+declare const readConfigSections: ({ ctx, scope, }: {
+    readonly ctx: Context;
+    readonly scope?: ConfigScope;
+}) => Promise<ReadonlyArray<{
+    readonly scope: ConfigScope;
+    readonly section: IniSection;
+}>>;
+/**
+ * Look up a single value for a fully-qualified key (`section.name` or
+ * `section.subsection.name`). Behaviour:
+ *
+ * - When `scope` is provided, reads only that scope. If the key has more than
+ *   one match in that scope, throws `CONFIG_MULTIPLE_VALUES` (carries `scope`).
+ * - When `scope` is omitted, merges across the four scopes. Same multi-value
+ *   throw if more than one entry matches anywhere across the merged view
+ *   (without the `scope` discriminator).
+ * - Absent key: returns `{ key, value: undefined }`; never throws.
+ *
+ * Branding: the returned `key` is the caller's input cast to `ConfigKey`;
+ * `parseConfigKey` validates the string before this cast, so the brand is
+ * load-bearing only at the type level.
+ */
+declare const getConfigValue: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<{
+    readonly key: ConfigKey;
+    readonly value: string;
+    readonly scope: ConfigScope;
+} | {
+    readonly key: ConfigKey;
+    readonly value: undefined;
+}>;
+/**
+ * Look up every value for a key. Returns matches in scope-precedence order
+ * (and physical-file order within each scope). Empty array when the key is
+ * absent. Never throws on multi-value.
+ */
+declare const getAllConfigValues: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<{
+    readonly key: ConfigKey;
+    readonly values: ReadonlyArray<{
+        readonly value: string;
+        readonly scope: ConfigScope;
+    }>;
+}>;
 
 interface EnumeratePushObjectsInput {
     /**
@@ -221,6 +339,21 @@ interface FetchPackResult {
 }
 declare const fetchPack: (ctx: Context, transport: HttpTransport, input: FetchPackInput) => Promise<FetchPackResult>;
 
+/**
+ * Flatten a nested `Tree` object into the `FlatTree` shape that the
+ * `mergeTrees` domain primitive consumes.
+ *
+ * Bridges `walkTree`'s iterator into the `FlatTree` Map of
+ * `path → { id, mode }`. Consumed by `merge.ts`'s clean-merge tree walk
+ * and by `rm`'s HEAD-vs-index staged-change check (the safety valve), so
+ * it is exported from the primitives barrel.
+ *
+ * Pure with respect to the working tree — only reads git objects via
+ * `walkTree`.
+ */
+
+declare const flattenTree: (ctx: Context, treeId: ObjectId) => Promise<FlatTree>;
+
 /**
  * Compose `walkTree → computeChangeset → applyChangeset` to update the
  * working tree to a target tree's contents.
@@ -393,6 +526,18 @@ declare const updateShallow: (ctx: Context, updates: ShallowUpdate) => Promise<v
  */
 declare const synthesizeTreeFromIndex: (ctx: Context, entries: ReadonlyArray<IndexEntry>) => Promise<ObjectId>;
 
+/**
+ * Targeted `.git/config` writer (ADR-082). tsgit has no general INI writer;
+ * this performs line surgery that preserves comments, blank lines, key order,
+ * casing of unrelated keys, and every other section byte-for-byte. It writes
+ * one `key = value` per call under any `[section]` / `[section "subsection"]`.
+ *
+ * @writes
+ *   surface: config
+ *   kind:    readback-only
+ *   format:  git-config-text
+ */
+
 /**
  * Set `key` under `[section]` / `[section "subsection"]`, preserving every
  * other byte verbatim.
@@ -402,9 +547,9 @@ declare const synthesizeTreeFromIndex: (ctx: Context, entries: ReadonlyArray<Ind
  *   inserted right after the header;
  * - no such section ⇒ `[section]\n\t<key> = <value>\n` is appended.
  */
-declare const setConfigEntry: (text: string, section: string, subsection: string | undefined, key: string, value: string) => string;
-/** `setConfigEntry` bound to the `[core]` section — kept for legacy callers. */
-declare const setCoreConfigEntry: (text: string, key: string, value: string) => string;
+declare const setConfigEntryInText: (text: string, section: string, subsection: string | undefined, key: string, value: string) => string;
+/** `setConfigEntryInText` bound to the `[core]` section — kept for legacy callers. */
+declare const setCoreConfigEntryInText: (text: string, key: string, value: string) => string;
 /** One `key = value` write under `[section]` / `[section "subsection"]`. */
 interface ConfigEntry {
     readonly section: string;
@@ -414,12 +559,115 @@ interface ConfigEntry {
 }
 /**
  * Read `${gitDir}/config` (a missing file is treated as `''`), fold
- * `setConfigEntry` over `entries`, write the result, and invalidate the
+ * `setConfigEntryInText` over `entries`, write the result, and invalidate the
  * per-`Context` `readConfig` cache so a later read sees the new values.
  */
 declare const updateConfigEntries: (ctx: Context, entries: ReadonlyArray<ConfigEntry>) => Promise<void>;
 /** Fold a batch of `[core]` `key = value` writes via `updateConfigEntries`. */
 declare const updateCoreConfig: (ctx: Context, entries: Record<string, string>) => Promise<void>;
+/**
+ * Mixed-operation batch entry. Folded over the on-disk text in order in
+ * a single `writeUtf8`. Use this when `remote` CRUD needs a section-
+ * remove paired with branch-referrer key removals in one atomic write.
+ */
+type ConfigOperation = {
+    readonly kind: 'set';
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+    readonly value: string;
+} | {
+    /**
+     * Insert a fresh `key = value` line after the section header WITHOUT
+     * replacing any existing entry with the same key. Use for multi-value
+     * keys (`fetch`) where every call must yield an additional line.
+     */
+    readonly kind: 'appendEntry';
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+    readonly value: string;
+} | {
+    readonly kind: 'removeEntry';
+    readonly section: string;
+    readonly subsection?: string;
+    readonly key: string;
+} | {
+    readonly kind: 'removeSection';
+    readonly section: string;
+    readonly subsection?: string;
+} | {
+    readonly kind: 'renameSection';
+    readonly section: string;
+    readonly from: string;
+    readonly to: string;
+};
+declare const applyConfigOpInText: (text: string, op: ConfigOperation) => string;
+/**
+ * Write a single `key = value` entry into the config file for the given scope
+ * (default `'local'`). Re-runs of the same call with a different value
+ * overwrite the existing entry in place (preserving comments and surrounding
+ * content). The key is validated via `parseConfigKey` (throws
+ * `CONFIG_KEY_INVALID` on a malformed input) and the value is validated by
+ * `assertValueSafe` (throws `CONFIG_VALUE_INVALID` on a banned control char)
+ * BEFORE any I/O — a rejected input never touches the file system.
+ *
+ * The branding on `ConfigKey` is enforced at the type level; this primitive
+ * accepts a raw string and parses it internally so it can be used directly
+ * from porcelain wrappers that hold un-branded callers' input.
+ */
+declare const setConfigEntry: ({ ctx, key, value, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly value: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Remove a single `key = value` entry from the given scope. Idempotent — if
+ * the key is absent the call is a no-op (no I/O). If the key appears more
+ * than once in the targeted scope, throws `CONFIG_MULTIPLE_VALUES` with
+ * `requested: 'remove'` (the caller should use `unsetAllConfigEntries` to
+ * clear every occurrence).
+ */
+declare const unsetConfigEntry: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Remove every occurrence of `key` from the targeted scope. Idempotent — a
+ * missing key produces no I/O. Unlike `unsetConfigEntry`, multi-valued keys
+ * are explicitly supported: all matching lines are removed in a single
+ * read-modify-write pass.
+ */
+declare const unsetAllConfigEntries: ({ ctx, key, scope, }: {
+    readonly ctx: Context;
+    readonly key: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Rename `[<section> "<oldSubsection>"]` to `[<section> "<newSubsection>"]`.
+ * Both inputs are dotted (`'remote.origin'`). The two section families MUST
+ * match — renaming across families (e.g. `remote.origin` → `branch.main`) is
+ * rejected with `INVALID_OPTION`. Throws `CONFIG_SECTION_NOT_FOUND` if the
+ * source section does not exist in the targeted scope.
+ */
+declare const renameConfigSection: ({ ctx, oldName, newName, scope, }: {
+    readonly ctx: Context;
+    readonly oldName: string;
+    readonly newName: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
+/**
+ * Delete `[<section> "<subsection>"]` and its body. `sectionName` is dotted
+ * (`'remote.origin'`). Throws `CONFIG_SECTION_NOT_FOUND` when the section is
+ * absent in the targeted scope.
+ */
+declare const removeConfigSection: ({ ctx, sectionName, scope, }: {
+    readonly ctx: Context;
+    readonly sectionName: string;
+    readonly scope?: ConfigScope;
+}) => Promise<void>;
 
 /**
  * Write the `.git/info/sparse-checkout` pattern file. The command tier
@@ -440,5 +688,5 @@ declare const updateCoreConfig: (ctx: Context, entries: Record<string, string>)
  */
 declare const writeSparsePatternText: (ctx: Context, text: string) => Promise<void>;
 
-export { MAX_SPARSE_PATTERN_FILE_BYTES, appendReflog, applyChangeset, buildIndexFromTree, buildPack, computeChangeset, deleteReflog, enumeratePushObjects, enumerateRefs, fetchPack, invalidateConfigCache, isWorkingTreeDirty, listReflogs, loadSparseMatcher, materializeTree, readConfig, readReflog, readShallow, readSparsePatternText, reflogExists, resolveReflogIdentity, setConfigEntry, setCoreConfigEntry, synthesizeTreeFromIndex, updateConfigEntries, updateCoreConfig, updateShallow, writeReflog, writeSparsePatternText };
-export type { ApplyChangesetOpts, ApplyChangesetResult, BuildIndexFromTreeOpts, BuildPackInput, BuildPackResult, Changeset, ChangesetEntry, ChangesetStats, ConfigEntry, EnumeratePushObjectsInput, FetchPackInput, FetchPackResult, MaterializeTreeOpts, MaterializeTreeResult, ParsedConfig };
+export { MAX_SPARSE_PATTERN_FILE_BYTES, appendReflog, applyChangeset, applyConfigOpInText, buildIndexFromTree, buildPack, compareWorkingTreeEntry, computeChangeset, deleteReflog, enumeratePushObjects, enumerateRefs, fetchPack, flattenTree, getAllConfigValues, getConfigValue, invalidateConfigCache, invalidateScopedConfigCache, isWorkingTreeDirty, listReflogs, loadSparseMatcher, materializeTree, parseIniSections, readConfig, readConfigSections, readReflog, readShallow, readSparsePatternText, reflogExists, removeConfigSection, renameConfigSection, resolveReflogIdentity, setConfigEntry, setConfigEntryInText, setCoreConfigEntryInText, synthesizeTreeFromIndex, unsetAllConfigEntries, unsetConfigEntry, updateConfigEntries, updateCoreConfig, updateShallow, writeReflog, writeSparsePatternText };
+export type { ApplyChangesetOpts, ApplyChangesetResult, BuildIndexFromTreeOpts, BuildPackInput, BuildPackResult, Changeset, ChangesetEntry, ChangesetStats, ConfigEntry, EnumeratePushObjectsInput, FetchPackInput, FetchPackResult, IniSection, MaterializeTreeOpts, MaterializeTreeResult, ParsedConfig, WorkingTreeComparison };