canopycms 0.0.60 → 0.0.61-int.75

package/dist/api/admin-branch-health.js

@@ -0,0 +1,448 @@
+/**
+ * Admin branch-health observability + recovery (PR-A3): a scan listing every
+ * directory under the branches root (healthy/corrupt-metadata/orphan), plus
+ * two recovery actions -- purge (reversible trash-rename) and repair-metadata
+ * (recreate defaults for a corrupt branch.json). Split out of admin.ts to
+ * keep that file under its size budget; ADMIN_ROUTES in admin.ts re-exports
+ * these routes so the router and generate-client keep a single import.
+ *
+ * See docs/concurrency.md's "Who uses what" table for the locking rationale
+ * (double-hold on purge, release-then-save ordering on repair).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { simpleGit } from 'simple-git';
+import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
+import { scanBranchHealth } from '../branch-health.js';
+import { getDefaultBranchBase, sanitizeBranchName } from '../paths/index.js';
+import { withOccFileLock } from '../utils/occ-json-write.js';
+import { tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
+import { getErrorMessage, isNodeError, isNotFoundError } from '../utils/error.js';
+import { defineEndpoint } from './route-builder.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** [H1] A fresh (< 5 min old) init lock blocks purge -- provisioning may be running. */
+const PROVISIONING_LOCK_FRESH_MS = 5 * 60_000;
+/** An orphan dir younger than this may still be a clone in progress; corrupt dirs are exempt. */
+const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
+const BRANCH_META_DIR = '.canopy-meta';
+const BRANCH_META_FILE = 'branch.json';
+// ============================================================================
+// Zod schemas
+// ============================================================================
+// Mirrors deleteTaskHandler's fileName pattern in admin.ts: conservative
+// charset plus explicit traversal/dot-prefix refinements (the regex alone
+// technically excludes '/' already, but the refinements keep intent explicit
+// and self-documenting at the validation layer).
+const dirNameSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9._-]{1,100}$/)
+    .refine((v) => !v.includes('..'), { message: 'dirName must not contain ..' })
+    .refine((v) => !v.startsWith('.'), { message: 'dirName must not be dot-prefixed' });
+const branchDirParamsSchema = z.object({ dirName: dirNameSchema });
+// ============================================================================
+// Shared helpers
+// ============================================================================
+/** Compact UTC stamp for trash/archive names: `YYYYMMDDTHHMMSSZ` (no colons -- portability). */
+function formatTrashStamp(date) {
+    return date
+        .toISOString()
+        .replace(/[-:]/g, '')
+        .replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Re-resolve dirName under baseRoot and enforce containment (belt-and-
+ * suspenders on top of the zod regex, matching deleteTaskHandler's pattern
+ * in admin.ts).
+ */
+function resolveDirWithinBase(baseRoot, dirName) {
+    const resolvedBase = path.resolve(baseRoot);
+    const baseWithSep = resolvedBase.endsWith(path.sep) ? resolvedBase : resolvedBase + path.sep;
+    const dirPath = path.resolve(resolvedBase, dirName);
+    if (dirPath !== resolvedBase && !dirPath.startsWith(baseWithSep))
+        return null;
+    return dirPath;
+}
+/** Control-flow error for repair's precondition checks made INSIDE the lock hold. */
+class RepairPreconditionError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = 'RepairPreconditionError';
+        this.status = status;
+    }
+}
+// ============================================================================
+// Handlers
+// ============================================================================
+const getBranchHealthHandler = async (_gc, ctx, _req) => {
+    // Same derivation services.ts uses to construct the BranchRegistry --
+    // admin handlers must agree with it or the scan silently looks at the
+    // wrong directory.
+    const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
+    const baseBranchName = ctx.services.config.defaultBaseBranch ?? 'main';
+    try {
+        const entries = await scanBranchHealth(baseRoot, { baseBranchName });
+        return {
+            ok: true,
+            status: 200,
+            data: { entries, generatedAt: new Date().toISOString() },
+        };
+    }
+    catch (err) {
+        return { ok: false, status: 500, error: getErrorMessage(err) };
+    }
+};
+/**
+ * Purge a corrupt-metadata or orphan branch directory by renaming it into a
+ * dot-prefixed trash name (reversible -- nothing is deleted here; the worker
+ * sweeps trash older than 30 days, see cleanupTrashedBranchDirs in
+ * worker/cms-worker.ts).
+ *
+ * Safety rails (see the PR's design review for the finding IDs):
+ * - [always] the base branch directory can never be purged.
+ * - Server re-derives live/corrupt/orphan state itself -- never trusts the
+ *   client's view of the world.
+ * - [H1] a fresh provisioning init-lock blocks purge; a stale one does not.
+ * - an orphan (not corrupt) dir younger than 15 minutes is presumed to be a
+ *   clone in progress and is not purgeable yet.
+ * - [H2] the purge itself runs under a zero-retry provisioning lock, so a
+ *   real in-flight provisioner (whose lock is therefore fresh, and would
+ *   already have 409'd above) can never race the rename; a same-instant
+ *   contender simply 409s.
+ * - [M3] ALSO runs under the branch.json lockfile -- the same lock every
+ *   metadata save() takes -- closing the window where a concurrent
+ *   repair-metadata save() resurrects a ghost branch.json mid-purge.
+ */
+const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
+    const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
+    const baseBranchName = ctx.services.config.defaultBaseBranch ?? 'main';
+    const sanitizedBaseBranchName = sanitizeBranchName(baseBranchName);
+    if (params.dirName === sanitizedBaseBranchName) {
+        return { ok: false, status: 400, error: 'The base branch directory can never be purged' };
+    }
+    const dirPath = resolveDirWithinBase(baseRoot, params.dirName);
+    if (!dirPath) {
+        return { ok: false, status: 400, error: 'Invalid directory name' };
+    }
+    // [MEDIUM-1 rider] The directory must actually exist -- otherwise
+    // withOccFileLock's `mkdir -p` below would CREATE it, and purge would
+    // "succeed" with a phantom `.trash-*` entry for a directory that was
+    // never there. Must run before anything below treats "no branch.json" as
+    // orphan classification.
+    const dirExists = await fs
+        .stat(dirPath)
+        .then(() => true)
+        .catch(() => false);
+    if (!dirExists) {
+        return { ok: false, status: 404, error: 'Directory not found' };
+    }
+    const branchJsonPath = path.join(dirPath, BRANCH_META_DIR, BRANCH_META_FILE);
+    // Re-derive state server-side -- never trust the client's classification.
+    let meta = null;
+    let hadLoadError = false;
+    try {
+        meta = await BranchMetadataFileManager.loadOnly(dirPath);
+    }
+    catch {
+        hadLoadError = true;
+    }
+    if (meta) {
+        return { ok: false, status: 409, error: 'Directory holds a live branch; use branch delete' };
+    }
+    // True orphan (no branch.json, no load error) vs. corrupt-metadata
+    // (loadOnly threw). Only true orphans are subject to the youth rail below.
+    const isTrueOrphan = !hadLoadError;
+    // [H1] freshness rail: a fresh init lock means provisioning may genuinely
+    // be in progress; a stale one is just crash debris and does not block.
+    const lockPath = path.join(baseRoot, `.${params.dirName}.init.lock`);
+    const lockStat = await fs.stat(lockPath).catch(() => null);
+    if (lockStat && Date.now() - lockStat.mtimeMs < PROVISIONING_LOCK_FRESH_MS) {
+        return { ok: false, status: 409, error: 'Provisioning may be in progress' };
+    }
+    // Youth rail: a brand-new orphan dir may be a clone that just hasn't
+    // written branch.json yet. Corrupt-metadata dirs are exempt -- a
+    // parseable-then-corrupted file is not a mid-clone signature.
+    if (isTrueOrphan) {
+        const dirStat = await fs.stat(dirPath).catch(() => null);
+        if (dirStat && Date.now() - dirStat.mtimeMs < ORPHAN_YOUTH_THRESHOLD_MS) {
+            return {
+                ok: false,
+                status: 409,
+                error: 'Directory too young -- may be a clone in progress',
+            };
+        }
+    }
+    // [H2] Zero-retry provisioning lock: fails fast (409) on genuine live
+    // contention instead of hanging the request for ~5 minutes.
+    let releaseProvisioningLock;
+    try {
+        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, `.${params.dirName}.init.lock`);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ELOCKED') {
+            return { ok: false, status: 409, error: 'Provisioning lock contention, try again' };
+        }
+        return { ok: false, status: 500, error: getErrorMessage(err) };
+    }
+    try {
+        return await withOccFileLock(branchJsonPath, async () => {
+            // [M3] Re-verify classification inside the double hold: a concurrent
+            // repair-metadata save() could have resurrected branch.json between
+            // our pre-lock check and now.
+            let recheckMeta = null;
+            try {
+                recheckMeta = await BranchMetadataFileManager.loadOnly(dirPath);
+            }
+            catch {
+                // Still corrupt (or now corrupt) -- fine, proceed with the purge.
+            }
+            if (recheckMeta) {
+                return { ok: false, status: 409, error: 'Directory holds a live branch; use branch delete' };
+            }
+            // [C1] The timestamp lives in the NAME, not the dir's mtime: rename()
+            // preserves the original mtime, so mtime-based retention would delete
+            // a months-stale orphan's trash on the very first cleanup pass.
+            const trashName = `.trash-${params.dirName}-${formatTrashStamp(new Date())}`;
+            const trashPath = path.join(baseRoot, trashName);
+            try {
+                await fs.rename(dirPath, trashPath);
+            }
+            catch (err) {
+                // Rename failure: the directory stays exactly where it was --
+                // nothing evaporates, and the next scan still lists it.
+                return { ok: false, status: 500, error: getErrorMessage(err) };
+            }
+            await ctx.services.registry?.invalidate();
+            return { ok: true, status: 200, data: { trashedAs: trashName } };
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Could not lock branch metadata: ${getErrorMessage(err)}`,
+        };
+    }
+    finally {
+        if (releaseProvisioningLock) {
+            await releaseProvisioningLock().catch(() => { });
+        }
+    }
+};
+/**
+ * Repair a corrupt branch.json by archiving it (forensics preserved as
+ * `branch.json.corrupt-{STAMP}`, ignored by future scans since it doesn't
+ * match the exact `branch.json` name) and recreating defaults via the
+ * normal save() path. Unlike purge, the base branch IS a valid target here
+ * -- a corrupt BASE branch.json is exactly the degraded-service scenario
+ * this handler exists to fix.
+ *
+ * [M4] Lock sequence: withOccFileLock is NOT reentrant, and save() takes it
+ * internally, so the rename must happen and the lock must be RELEASED
+ * (exiting the withOccFileLock callback) before save() runs -- calling
+ * save() while still holding the lock would deadlock against itself.
+ *
+ * [MEDIUM-1] The provisioning lock is held across the ENTIRE archive+save
+ * sequence (acquired before withOccFileLock, released only after save()
+ * completes), same lock order as purge (provisioning -> branch.json) so the
+ * two can never deadlock against each other. Without this, a concurrent
+ * purge could trash the directory in the window between this handler
+ * releasing withOccFileLock (required before save(), per [M4] above) and
+ * save() actually running -- save() would then resurrect a metadata-only
+ * ghost of a directory purge just moved to trash.
+ */
+const repairBranchDirHandler = async (_gc, ctx, req, params) => {
+    const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
+    const dirPath = resolveDirWithinBase(baseRoot, params.dirName);
+    if (!dirPath) {
+        return { ok: false, status: 400, error: 'Invalid directory name' };
+    }
+    // [MEDIUM-1 rider] Same stat guard as purge: the directory must actually
+    // exist, otherwise withOccFileLock's `mkdir -p` below would CREATE it.
+    const dirExists = await fs
+        .stat(dirPath)
+        .then(() => true)
+        .catch(() => false);
+    if (!dirExists) {
+        return { ok: false, status: 404, error: 'Directory not found' };
+    }
+    const branchJsonPath = path.join(dirPath, BRANCH_META_DIR, BRANCH_META_FILE);
+    // Pre-lock precondition check: fail fast on the common cases without
+    // paying for a lock acquisition on a doomed request.
+    const precheck = await checkStillCorrupt(dirPath);
+    if (precheck !== 'corrupt') {
+        return precheck === 'healthy'
+            ? { ok: false, status: 409, error: 'Metadata is healthy' }
+            : { ok: false, status: 409, error: 'No metadata file -- use purge for orphans' };
+    }
+    // [MEDIUM-1] Zero-retry provisioning lock, mirroring purge's [H2]: fails
+    // fast (409) on genuine live contention instead of hanging the request.
+    // Held until the `finally` below, AFTER save() completes.
+    let releaseProvisioningLock;
+    try {
+        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, `.${params.dirName}.init.lock`);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ELOCKED') {
+            return { ok: false, status: 409, error: 'Provisioning lock contention, try again' };
+        }
+        return { ok: false, status: 500, error: getErrorMessage(err) };
+    }
+    try {
+        let archivedAs;
+        try {
+            archivedAs = await withOccFileLock(branchJsonPath, async () => {
+                // Re-verify still-corrupt under the lock (a concurrent repair could
+                // have already fixed this, or the file could have been purged out
+                // from under us).
+                const recheck = await checkStillCorrupt(dirPath);
+                if (recheck === 'healthy') {
+                    throw new RepairPreconditionError('Metadata is healthy', 409);
+                }
+                if (recheck === 'missing') {
+                    throw new RepairPreconditionError('No metadata file -- use purge for orphans', 409);
+                }
+                const archivedName = `${BRANCH_META_FILE}.corrupt-${formatTrashStamp(new Date())}`;
+                await fs.rename(branchJsonPath, path.join(dirPath, BRANCH_META_DIR, archivedName));
+                return archivedName;
+            });
+        }
+        catch (err) {
+            if (err instanceof RepairPreconditionError) {
+                return { ok: false, status: err.status, error: err.message };
+            }
+            return {
+                ok: false,
+                status: 409,
+                error: `Could not lock branch metadata: ${getErrorMessage(err)}`,
+            };
+        }
+        // [MEDIUM-3] Prefer the clone's actual checked-out branch over the
+        // (possibly sanitized) directory name -- see resolveRepairedBranchName.
+        const branchName = await resolveRepairedBranchName(dirPath, params.dirName);
+        // Lock released above (we're outside the withOccFileLock callback now) --
+        // save() takes its own hold on the same lock internally. Its defaults
+        // path fabricates the rest of BranchMetadata and invalidates the
+        // registry. Still under the provisioning lock acquired above -- see
+        // [MEDIUM-1] in the docstring.
+        const manager = getBranchMetadataFileManager(dirPath, baseRoot);
+        const saved = await manager.save({
+            branch: { name: branchName, status: 'editing', createdBy: req.user.userId },
+        });
+        return { ok: true, status: 200, data: { branch: saved.branch, archivedAs } };
+    }
+    finally {
+        if (releaseProvisioningLock) {
+            await releaseProvisioningLock().catch(() => { });
+        }
+    }
+};
+/**
+ * [MEDIUM-3] Best-effort read of the branch actually checked out in the
+ * clone at `dirPath`, falling back to `dirName` on any failure (no `.git`,
+ * detached HEAD, corrupt repo, etc.). Workspace directory names are
+ * sanitized (slashes stripped, see paths/branch.ts's `sanitizeBranchName`),
+ * so a branch named `feature/foo` lives in a directory named `feature-foo`
+ * -- writing `dirName` as `branch.name` would make later push/PR tasks
+ * target the wrong ref.
+ */
+async function resolveRepairedBranchName(dirPath, dirName) {
+    const hasGitDir = await fs
+        .stat(path.join(dirPath, '.git'))
+        .then(() => true)
+        .catch(() => false);
+    if (!hasGitDir)
+        return dirName;
+    try {
+        const current = await simpleGit({ baseDir: dirPath }).revparse(['--abbrev-ref', 'HEAD']);
+        const trimmed = current.trim();
+        return trimmed || dirName;
+    }
+    catch {
+        return dirName;
+    }
+}
+/** Classify branch.json's current state for repair's precondition checks. */
+async function checkStillCorrupt(dirPath) {
+    try {
+        const meta = await BranchMetadataFileManager.loadOnly(dirPath);
+        return meta ? 'healthy' : 'missing';
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return 'missing';
+        return 'corrupt';
+    }
+}
+// ============================================================================
+// Route definitions
+// ============================================================================
+/**
+ * Branch directory health scan (healthy/corrupt-metadata/orphan)
+ * GET /admin/branch-health
+ */
+const getBranchHealth = defineEndpoint({
+    namespace: 'admin',
+    name: 'branchHealth',
+    method: 'GET',
+    path: '/admin/branch-health',
+    responseType: 'BranchHealthResponse',
+    response: {},
+    defaultMockData: { entries: [], generatedAt: '2024-01-01T00:00:00.000Z' },
+    guards: ['admin'],
+    handler: getBranchHealthHandler,
+});
+/**
+ * Purge a corrupt-metadata or orphan branch directory (reversible trash-rename)
+ * POST /admin/branch-dirs/:dirName/purge
+ */
+const purgeBranchDir = defineEndpoint({
+    namespace: 'admin',
+    name: 'purgeBranchDir',
+    method: 'POST',
+    path: '/admin/branch-dirs/:dirName/purge',
+    params: branchDirParamsSchema,
+    responseType: 'PurgeBranchDirResponse',
+    response: {},
+    defaultMockData: { trashedAs: '.trash-example-branch-20240101T000000Z' },
+    guards: ['admin'],
+    handler: purgeBranchDirHandler,
+});
+/**
+ * Repair a corrupt branch.json by archiving it and recreating defaults
+ * POST /admin/branch-dirs/:dirName/repair-metadata
+ */
+const repairBranchDir = defineEndpoint({
+    namespace: 'admin',
+    name: 'repairBranchDir',
+    method: 'POST',
+    path: '/admin/branch-dirs/:dirName/repair-metadata',
+    params: branchDirParamsSchema,
+    responseType: 'RepairBranchDirResponse',
+    response: {},
+    defaultMockData: {
+        branch: {
+            name: 'example-branch',
+            status: 'editing',
+            access: {},
+            createdBy: 'admin',
+            createdAt: '2024-01-01T00:00:00.000Z',
+            updatedAt: '2024-01-01T00:00:00.000Z',
+        },
+        archivedAs: 'branch.json.corrupt-20240101T000000Z',
+    },
+    guards: ['admin'],
+    handler: repairBranchDirHandler,
+});
+/**
+ * Exported routes, merged into ADMIN_ROUTES in admin.ts for a single
+ * router/generate-client import.
+ */
+export const ADMIN_BRANCH_HEALTH_ROUTES = {
+    branchHealth: getBranchHealth,
+    purgeBranchDir,
+    repairBranchDir,
+};
+//# sourceMappingURL=admin-branch-health.js.map

package/dist/api/admin-branch-health.js.map

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

package/dist/api/admin.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Admin observability endpoints: task queue stats/listing and worker
+ * liveness (PR-A1), plus task recovery actions — retry a failed task or
+ * delete a stuck/corrupt task file (PR-A2) — for an admin-only dashboard.
+ * Branch-health scan + purge/repair actions (PR-A3) live in
+ * admin-branch-health.ts and are merged into ADMIN_ROUTES below.
+ */
+import { z } from 'zod';
+import type { ApiResponse } from './types';
+import type { Task, QueueStats, CorruptTaskFile } from '../worker/task-queue';
+import type { WorkerStatusReport } from '../types';
+import type { OperatingMode } from '../operating-mode';
+export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, } from './admin-branch-health';
+export type WorkerLivenessState = 'alive' | 'stale' | 'absent';
+export interface WorkerLiveness {
+    /**
+     * 'absent' — the lock dir is removed on clean release, so this also covers
+     * "never started". 'alive' — heartbeat fresher than the threshold. 'stale'
+     * — heartbeat older than the threshold (the holder likely crashed).
+     */
+    state: WorkerLivenessState;
+    lockMtime?: string;
+    lockAgeMs?: number;
+}
+export interface AdminStatusData {
+    generatedAt: string;
+    mode: OperatingMode;
+    queue: QueueStats & {
+        oldestPendingAgeMs?: number;
+    };
+    worker: WorkerLiveness;
+    workerStatus: WorkerStatusReport | null;
+    statusReadError?: string;
+}
+/** Response type for GET /admin/status */
+export type AdminStatusResponse = ApiResponse<AdminStatusData>;
+export interface AdminTasksData {
+    tasks?: Task[];
+    corruptFiles?: CorruptTaskFile[];
+}
+/** Response type for GET /admin/tasks/:status */
+export type AdminTasksResponse = ApiResponse<AdminTasksData>;
+export interface AdminRetryTaskData {
+    newTaskId: string;
+}
+/** Response type for POST /admin/tasks/:taskId/retry */
+export type AdminRetryTaskResponse = ApiResponse<AdminRetryTaskData>;
+export interface AdminDeleteTaskData {
+    deleted: true;
+}
+/** Response type for DELETE /admin/tasks/:status/:fileName */
+export type AdminDeleteTaskResponse = ApiResponse<AdminDeleteTaskData>;
+declare const listAdminTasksParamsSchema: z.ZodObject<{
+    status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+    limit?: number | undefined;
+}, {
+    status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+    limit?: number | undefined;
+}>;
+export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
+declare const retryTaskParamsSchema: z.ZodObject<{
+    taskId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    taskId: string;
+}, {
+    taskId: string;
+}>;
+export type RetryTaskParams = z.infer<typeof retryTaskParamsSchema>;
+declare const deleteTaskParamsSchema: z.ZodObject<{
+    status: z.ZodEnum<["pending", "failed", "corrupt"]>;
+    fileName: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "failed" | "corrupt";
+    fileName: string;
+}, {
+    status: "pending" | "failed" | "corrupt";
+    fileName: string;
+}>;
+export type DeleteTaskParams = z.infer<typeof deleteTaskParamsSchema>;
+/**
+ * Exported routes for router registration.
+ *
+ * Branch-health scan + purge/repair (PR-A3) live in admin-branch-health.ts
+ * (kept out of this file to stay under its size budget) and are merged in
+ * here so the router (http/router.ts) and generate-client.ts keep a single
+ * `ADMIN_ROUTES` import.
+ */
+export declare const ADMIN_ROUTES: {
+    readonly branchHealth: import("./route-builder").RouteDefinition<undefined, undefined, import("./admin-branch-health").BranchHealthResponse>;
+    readonly purgeBranchDir: import("./route-builder").RouteDefinition<z.ZodObject<{
+        dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        dirName: string;
+    }, {
+        dirName: string;
+    }>, undefined, import("./admin-branch-health").PurgeBranchDirResponse>;
+    readonly repairBranchDir: import("./route-builder").RouteDefinition<z.ZodObject<{
+        dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        dirName: string;
+    }, {
+        dirName: string;
+    }>, undefined, import("./admin-branch-health").RepairBranchDirResponse>;
+    readonly status: import("./route-builder").RouteDefinition<undefined, undefined, AdminStatusResponse>;
+    readonly listTasks: import("./route-builder").RouteDefinition<z.ZodObject<{
+        status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+        limit?: number | undefined;
+    }, {
+        status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+        limit?: number | undefined;
+    }>, undefined, AdminTasksResponse>;
+    readonly retryTask: import("./route-builder").RouteDefinition<z.ZodObject<{
+        taskId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        taskId: string;
+    }, {
+        taskId: string;
+    }>, undefined, AdminRetryTaskResponse>;
+    readonly deleteTask: import("./route-builder").RouteDefinition<z.ZodObject<{
+        status: z.ZodEnum<["pending", "failed", "corrupt"]>;
+        fileName: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "failed" | "corrupt";
+        fileName: string;
+    }, {
+        status: "pending" | "failed" | "corrupt";
+        fileName: string;
+    }>, undefined, AdminDeleteTaskResponse>;
+};
+//# sourceMappingURL=admin.d.ts.map

package/dist/api/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/api/admin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAA0B,WAAW,EAAE,MAAM,SAAS,CAAA;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAS7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAUtD,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAoB9B,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE9D,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,mBAAmB,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAgFD,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,aAAa,CAAA;IACnB,KAAK,EAAE,UAAU,GAAG;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnD,MAAM,EAAE,cAAc,CAAA;IACtB,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAA;IACvC,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,eAAe,CAAC,CAAA;AAE9D,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,IAAI,EAAE,CAAA;IACd,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC;AAED,iDAAiD;AACjD,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,cAAc,CAAC,CAAA;AAE5D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wDAAwD;AACxD,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,kBAAkB,CAAC,CAAA;AAEpE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,IAAI,CAAA;CACd;AAED,8DAA8D;AAC9D,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,mBAAmB,CAAC,CAAA;AAQtE,QAAA,MAAM,0BAA0B;;;;;;;;;EAK9B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAI7E,QAAA,MAAM,qBAAqB;;;;;;EAEzB,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAOnE,QAAA,MAAM,sBAAsB;;;;;;;;;EAM1B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAkOrE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMf,CAAA"}