@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/closeout-repository.js

@@ -0,0 +1,84 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Repository identities for closeout branch records (BUG-218). External submodule worktrees
+ * require both a shared Git common directory and registered membership; durable records use
+ * the contained checkout so removing a session worktree does not invalidate its identity.
+ */
+import { realpathSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { tryGit } from './closeout-git.js';
+import { listSubmodules, rawWorktrees } from './closeout-worktrees.js';
+import { isInsideRoot } from './path-guard.js';
+const ACCEPTED_FORMS = 'Use ".", a contained repository root (relative or absolute), or a registered worktree ' +
+    'of a contained initialized submodule';
+function canonical(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return null;
+    }
+}
+function samePath(left, right) {
+    return relative(left, right) === '';
+}
+function gitRoot(directory) {
+    const actual = canonical(directory);
+    if (!actual)
+        return null;
+    const top = tryGit(['rev-parse', '--show-toplevel'], { cwd: actual });
+    const root = top.ok ? canonical(top.stdout.trim()) : null;
+    return root && samePath(root, actual) ? actual : null;
+}
+function commonDirectory(directory) {
+    const result = tryGit(['rev-parse', '--git-common-dir'], { cwd: directory });
+    return result.ok ? canonical(resolve(directory, result.stdout.trim())) : null;
+}
+function containedIdentity(root, directory) {
+    return { directory, repository: relative(root, directory).split(sep).join('/') || '.' };
+}
+function owningSubmodule(root, worktree) {
+    const common = commonDirectory(worktree);
+    if (!common)
+        return null;
+    for (const submodule of listSubmodules(root)) {
+        const directory = gitRoot(submodule.path);
+        if (!directory || !isInsideRoot(root, directory))
+            continue;
+        const submoduleCommon = commonDirectory(directory);
+        if (!submoduleCommon || !samePath(common, submoduleCommon))
+            continue;
+        // A copied .git file can share the common directory without registering this checkout.
+        const registered = rawWorktrees(directory).some((entry) => {
+            const path = canonical(entry.path);
+            return path !== null && samePath(path, worktree);
+        });
+        if (registered)
+            return containedIdentity(root, directory);
+    }
+    return null;
+}
+/** Resolve native paths and reject roots outside the served checkout unless Git proves ownership. */
+export function resolveRecordRepository(repoPath, repository) {
+    const requested = resolve(repoPath, repository);
+    const root = canonical(repoPath);
+    const directory = gitRoot(requested);
+    if (!root || !directory) {
+        const reason = isInsideRoot(resolve(repoPath), requested)
+            ? 'is not the root of a git repository'
+            : 'lies outside the served checkout';
+        throw new Error(`Repository ${repository} ${reason}. ${ACCEPTED_FORMS}`);
+    }
+    if (isInsideRoot(root, directory))
+        return containedIdentity(root, directory);
+    // A contained link must never turn the external-worktree exception into an escape route.
+    if (!isInsideRoot(resolve(repoPath), requested)) {
+        const owner = owningSubmodule(root, directory);
+        if (owner)
+            return owner;
+    }
+    throw new Error(`Repository ${repository} lies outside the served checkout. ${ACCEPTED_FORMS}`);
+}
+//# sourceMappingURL=closeout-repository.js.map

package/dist/core/closeout-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-repository.js","sourceRoot":"","sources":["../../src/core/closeout-repository.ts"],"names":[],"mappings":"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"}

package/dist/core/closeout-rescue-refs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Ref-name handling for the close-out rescue: safe names and names no existing ref blocks.
+ */
+/** A clean filter or prompt must not hang the run. */
+export declare const GIT_TIMEOUT_MS = 120000;
+export declare function refExists(repoPath: string, ref: string): string | null;
+/** Ref-safe form of a branch or folder name. */
+export declare function refSafe(name: string): string;
+/**
+ * Runs `attempt` with a ref name no existing ref blocks. A segment that clashes with a parent ref
+ * or with refs below it gets the next `-N` suffix; `attempt` returns undefined when the exact name
+ * is taken, and a failure that git blames on the name retries with the next suffix, bounded.
+ */
+export declare function withFreeName<T>(repoPath: string, namespace: string, base: string, attempt: (name: string, existing: string | null) => T | undefined): T;
+//# sourceMappingURL=closeout-rescue-refs.d.ts.map

package/dist/core/closeout-rescue-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-rescue-refs.d.ts","sourceRoot":"","sources":["../../src/core/closeout-rescue-refs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,sDAAsD;AACtD,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMtE;AAED,gDAAgD;AAChD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS5C;AA+BD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,CAAC,GAAG,SAAS,GAChE,CAAC,CA4BH"}

package/dist/core/closeout-rescue-refs.js

@@ -0,0 +1,90 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Ref-name handling for the close-out rescue: safe names and names no existing ref blocks.
+ */
+import { tryGit } from './closeout-git.js';
+/** A clean filter or prompt must not hang the run. */
+export const GIT_TIMEOUT_MS = 120_000;
+export function refExists(repoPath, ref) {
+    const result = tryGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+        cwd: repoPath,
+        timeoutMs: GIT_TIMEOUT_MS,
+    });
+    return result.ok ? result.stdout.trim() : null;
+}
+/** Ref-safe form of a branch or folder name. */
+export function refSafe(name) {
+    const cleaned = name
+        .replace(/[^A-Za-z0-9._/-]+/g, '-')
+        .replace(/\.{2,}/g, '.')
+        .replace(/\/{2,}/g, '/')
+        .replace(/\/\.+/g, '/')
+        .replace(/(^[/.-]+|[/.]+$)/g, '')
+        .replace(/\.lock(\/|$)/g, '-lock$1');
+    return cleaned || 'worktree';
+}
+const NAME_RETRIES = 20;
+const NAME_CLASH = /cannot lock ref|exists|directory|not a directory/i;
+function refPresent(repoPath, ref) {
+    return tryGit(['show-ref', '--verify', '--quiet', ref], {
+        cwd: repoPath,
+        timeoutMs: GIT_TIMEOUT_MS,
+    }).ok;
+}
+function refsBelow(repoPath, ref) {
+    const listed = tryGit(['for-each-ref', '--count=1', '--format=%(refname)', `${ref}/`], {
+        cwd: repoPath,
+        timeoutMs: GIT_TIMEOUT_MS,
+    });
+    return listed.ok && listed.stdout.trim() !== '';
+}
+/** The first path segment whose ref blocks the name: a parent that is a ref, or refs below it. */
+function blockedSegment(repoPath, namespace, segments) {
+    for (let index = 0; index < segments.length; index++) {
+        const ref = `${namespace}/${segments.slice(0, index + 1).join('/')}`;
+        if (index < segments.length - 1 ? refPresent(repoPath, ref) : refsBelow(repoPath, ref)) {
+            return index;
+        }
+    }
+    return -1;
+}
+/**
+ * Runs `attempt` with a ref name no existing ref blocks. A segment that clashes with a parent ref
+ * or with refs below it gets the next `-N` suffix; `attempt` returns undefined when the exact name
+ * is taken, and a failure that git blames on the name retries with the next suffix, bounded.
+ */
+export function withFreeName(repoPath, namespace, base, attempt) {
+    const original = base.split('/');
+    const counters = original.map(() => 1);
+    const nameOf = () => original.map((s, i) => ((counters[i] ?? 1) > 1 ? `${s}-${counters[i]}` : s));
+    const bump = (index) => {
+        counters[index] = (counters[index] ?? 1) + 1;
+    };
+    let lastError;
+    for (let tries = 0; tries < NAME_RETRIES * 4; tries++) {
+        const segments = nameOf();
+        const blocked = blockedSegment(repoPath, namespace, segments);
+        // The leaf is checked against refs below it above; a plain existing leaf is the caller's call.
+        const parentBlock = blocked >= 0 && blocked < segments.length - 1 ? blocked : -1;
+        if (parentBlock >= 0 || blocked === segments.length - 1) {
+            bump(blocked);
+            continue;
+        }
+        const name = segments.join('/');
+        try {
+            const result = attempt(name, refExists(repoPath, `${namespace}/${name}`));
+            if (result !== undefined)
+                return result;
+        }
+        catch (error) {
+            lastError = error;
+            if (!(error instanceof Error && NAME_CLASH.test(error.message)))
+                throw error;
+        }
+        bump(original.length - 1);
+    }
+    throw lastError instanceof Error ? lastError : new Error(`No free ref name below ${base}`);
+}
+//# sourceMappingURL=closeout-rescue-refs.js.map

package/dist/core/closeout-rescue-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-rescue-refs.js","sourceRoot":"","sources":["../../src/core/closeout-rescue-refs.ts"],"names":[],"mappings":"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"}

package/dist/core/closeout-rescue-run.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Turns an inventory into the rescue the CLI and MCP adapters both run: archive tags for every
+ * in-scope branch that is not contained in the mainline (and for branches named explicitly),
+ * rescue refs for every in-scope worktree with changed entries (EPIC-061).
+ */
+import { type RescueOptions, type RescueResult } from './closeout-rescue.js';
+import type { CloseoutInventory } from './closeout-types.js';
+export interface CloseoutRescueRun {
+    repository: string;
+    result: RescueResult;
+}
+/** One line per tag or rescue ref that failed; empty when the whole rescue was written. */
+export declare function rescueErrors(runs: readonly CloseoutRescueRun[]): string[];
+/** True when the rescue wrote at least one tag or ref. */
+export declare function rescueWroteSomething(runs: readonly CloseoutRescueRun[]): boolean;
+/** yyyymmdd in the local time zone, the date format of archive tags and rescue refs. */
+export declare function closeoutCompactDate(date: Date): string;
+/** One rescue plan per repository of the inventory; a repository with nothing to do is left out. */
+export declare function planCloseoutRescue(inventory: CloseoutInventory, date: string, secretPatterns: readonly string[], explicitBranches?: readonly string[]): {
+    path: string;
+    name: string;
+    options: RescueOptions;
+}[];
+/** Runs the plan; adds only `archive/` tags and `rescue/` refs. */
+export declare function runCloseoutRescue(inventory: CloseoutInventory, date: string, secretPatterns: readonly string[], explicitBranches?: readonly string[]): CloseoutRescueRun[];
+//# sourceMappingURL=closeout-rescue-run.d.ts.map

package/dist/core/closeout-rescue-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-rescue-run.d.ts","sourceRoot":"","sources":["../../src/core/closeout-rescue-run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAWzE;AAED,0DAA0D;AAC1D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAMhF;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAGtD;AAED,oGAAoG;AACpG,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,gBAAgB,GAAE,SAAS,MAAM,EAAO,GACvC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,EAAE,CAoB1D;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,gBAAgB,GAAE,SAAS,MAAM,EAAO,GACvC,iBAAiB,EAAE,CAKrB"}

package/dist/core/closeout-rescue-run.js

@@ -0,0 +1,66 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Turns an inventory into the rescue the CLI and MCP adapters both run: archive tags for every
+ * in-scope branch that is not contained in the mainline (and for branches named explicitly),
+ * rescue refs for every in-scope worktree with changed entries (EPIC-061).
+ */
+import { basename } from 'node:path';
+import { closeoutRescue } from './closeout-rescue.js';
+/** One line per tag or rescue ref that failed; empty when the whole rescue was written. */
+export function rescueErrors(runs) {
+    const errors = [];
+    for (const { repository, result } of runs) {
+        for (const tag of result.tags) {
+            if (tag.error)
+                errors.push(`tag ${tag.name} (${repository}): ${tag.error}`);
+        }
+        for (const ref of result.refs) {
+            if (ref.error)
+                errors.push(`rescue ${ref.worktree}: ${ref.error}`);
+        }
+    }
+    return errors;
+}
+/** True when the rescue wrote at least one tag or ref. */
+export function rescueWroteSomething(runs) {
+    return runs.some(({ result }) => result.tags.some((tag) => tag.created && !tag.error) ||
+        result.refs.some((ref) => ref.ref && !ref.error));
+}
+/** yyyymmdd in the local time zone, the date format of archive tags and rescue refs. */
+export function closeoutCompactDate(date) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`;
+}
+/** One rescue plan per repository of the inventory; a repository with nothing to do is left out. */
+export function planCloseoutRescue(inventory, date, secretPatterns, explicitBranches = []) {
+    const plans = [];
+    for (const repository of inventory.repositories) {
+        const tagBranches = repository.branches
+            .filter((branch) => branch.class !== 'contained' || explicitBranches.includes(branch.name))
+            .map((branch) => ({ name: branch.name, head: branch.head }));
+        const worktrees = repository.worktrees
+            .filter((worktree) => worktree.exists && worktree.changed.length > 0)
+            .map((worktree) => ({
+            path: worktree.path,
+            name: worktree.branch ?? basename(worktree.path),
+        }));
+        if (tagBranches.length === 0 && worktrees.length === 0)
+            continue;
+        plans.push({
+            path: repository.path,
+            name: repository.name,
+            options: { date, secretPatterns, tagBranches, worktrees },
+        });
+    }
+    return plans;
+}
+/** Runs the plan; adds only `archive/` tags and `rescue/` refs. */
+export function runCloseoutRescue(inventory, date, secretPatterns, explicitBranches = []) {
+    return planCloseoutRescue(inventory, date, secretPatterns, explicitBranches).map((plan) => ({
+        repository: plan.name,
+        result: closeoutRescue(plan.path, plan.options),
+    }));
+}
+//# sourceMappingURL=closeout-rescue-run.js.map

package/dist/core/closeout-rescue-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-rescue-run.js","sourceRoot":"","sources":["../../src/core/closeout-rescue-run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAyC,MAAM,sBAAsB,CAAC;AAQ7F,2FAA2F;AAC3F,MAAM,UAAU,YAAY,CAAC,IAAkC;IAC7D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,GAAG,CAAC,KAAK;gBAAE,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,GAAG,CAAC,KAAK;gBAAE,MAAM,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,oBAAoB,CAAC,IAAkC;IACrE,OAAO,IAAI,CAAC,IAAI,CACd,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CACb,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CACnD,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,IAAU;IAC5C,MAAM,GAAG,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtE,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,kBAAkB,CAChC,SAA4B,EAC5B,IAAY,EACZ,cAAiC,EACjC,gBAAgB,GAAsB,EAAE;IAExC,MAAM,KAAK,GAA6D,EAAE,CAAC;IAC3E,KAAK,MAAM,UAAU,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;QAChD,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ;aACpC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,WAAW,IAAI,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;aAC1F,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS;aACnC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;aACpE,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAClB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,IAAI,EAAE,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;SACjD,CAAC,CAAC,CAAC;QACN,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACjE,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAC/B,SAA4B,EAC5B,IAAY,EACZ,cAAiC,EACjC,gBAAgB,GAAsB,EAAE;IAExC,OAAO,kBAAkB,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1F,UAAU,EAAE,IAAI,CAAC,IAAI;QACrB,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC;KAChD,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/core/closeout-rescue.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Archive tags and rescue refs for the session close-out (EPIC-061). The rescue changes no
+ * worktree file, no worktree index and no branch: it builds a commit from a temporary index file
+ * and stores it under `refs/heads/rescue/<date>/<name>`, and it tags branch tips under
+ * `archive/<date>/<branch>`. Besides the new refs and tags its only write is the blobs and trees
+ * that `git add` and `commit-tree` put into the object store. Paths that match a secret pattern
+ * never enter the rescue commit.
+ */
+export interface RescueBranchInput {
+    name: string;
+    head: string;
+}
+export interface RescueWorktreeInput {
+    path: string;
+    /** Branch name or worktree folder name; it names the rescue ref. */
+    name: string;
+}
+export interface RescueOptions {
+    /** yyyymmdd */
+    date: string;
+    secretPatterns: readonly string[];
+    tagBranches: RescueBranchInput[];
+    worktrees: RescueWorktreeInput[];
+}
+export interface RescueResult {
+    tags: {
+        name: string;
+        sha: string;
+        created: boolean;
+        error?: string;
+    }[];
+    refs: {
+        worktree: string;
+        ref: string | null;
+        commit: string | null;
+        files: number;
+        /** The tree equals HEAD: only line endings differed. */
+        empty: boolean;
+        error?: string;
+    }[];
+    skipped: {
+        worktree: string;
+        path: string;
+        reason: 'secret' | 'secret-tree' | 'nested-repository' | 'vanished' | 'staged-only-missing';
+    }[];
+}
+type Skipped = RescueResult['skipped'][number];
+export declare function createArchiveTags(repoPath: string, date: string, branches: readonly RescueBranchInput[]): RescueResult['tags'];
+/** Splits paths into groups that stay under the count and the character limit. */
+export declare function chunkPaths(paths: readonly string[], baseChars: number, maxChars?: number, maxCount?: number): string[][];
+/**
+ * Adds the paths to the temporary index in chunks. When a chunk fails, its paths go in one by one
+ * so a file deleted since the selection is skipped as vanished instead of failing the rescue.
+ */
+export declare function addPaths(worktree: string, paths: readonly string[], run: {
+    cwd: string;
+    timeoutMs: number;
+    env: Record<string, string>;
+}): Skipped[];
+/** Tags the given branch tips and rescues the uncommitted work of the given worktrees. */
+export declare function closeoutRescue(repoPath: string, options: RescueOptions): RescueResult;
+export {};
+//# sourceMappingURL=closeout-rescue.d.ts.map

package/dist/core/closeout-rescue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout-rescue.d.ts","sourceRoot":"","sources":["../../src/core/closeout-rescue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxE,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,wDAAwD;QACxD,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,EAAE,CAAC;IACJ,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,aAAa,GAAG,mBAAmB,GAAG,UAAU,GAAG,qBAAqB,CAAC;KAC7F,EAAE,CAAC;CACL;AAED,KAAK,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAO/C,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,SAAS,iBAAiB,EAAE,GACrC,YAAY,CAAC,MAAM,CAAC,CAyBtB;AAkED,kFAAkF;AAClF,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAgB,EACxB,QAAQ,SAAY,GACnB,MAAM,EAAE,EAAE,CAgBZ;AAWD;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACnE,OAAO,EAAE,CAiBX;AA8HD,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,YAAY,CA0BrF"}