@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/utils/git-command-runtime-metrics.js

@@ -0,0 +1,126 @@
+export class GitCommandRuntimeMetricsWindow {
+    constructor(limits, clock = Date.now) {
+        this.limits = limits;
+        this.clock = clock;
+        this.pendingCommands = new Set();
+        this.activeCommands = new Set();
+        this.active = 0;
+        this.peakActive = 0;
+        this.peakPending = 0;
+        this.submittedCount = 0;
+        this.startedCount = 0;
+        this.completedCount = 0;
+        this.failedCount = 0;
+        this.timedOutCount = 0;
+        this.queueWaitSamples = [];
+        this.executionSamples = [];
+        this.operationCounts = new Map();
+        this.provenanceCounts = new Map();
+    }
+    submit(operation, provenance = "unattributed") {
+        const metric = { queuedAtMs: this.clock(), startedAtMs: null, provenance };
+        this.pendingCommands.add(metric);
+        this.submittedCount += 1;
+        this.operationCounts.set(operation, (this.operationCounts.get(operation) ?? 0) + 1);
+        this.provenanceCounts.set(provenance, (this.provenanceCounts.get(provenance) ?? 0) + 1);
+        return metric;
+    }
+    observeLimiter(active, pending) {
+        this.peakActive = Math.max(this.peakActive, active);
+        this.peakPending = Math.max(this.peakPending, pending);
+    }
+    start(metric) {
+        if (!this.pendingCommands.delete(metric)) {
+            return;
+        }
+        const now = this.clock();
+        metric.startedAtMs = now;
+        this.activeCommands.add(metric);
+        this.active += 1;
+        this.startedCount += 1;
+        this.peakActive = Math.max(this.peakActive, this.active);
+        this.queueWaitSamples.push(Math.max(0, now - metric.queuedAtMs));
+    }
+    finish(metric, outcome) {
+        if (metric.startedAtMs === null) {
+            return;
+        }
+        const startedAtMs = metric.startedAtMs;
+        metric.startedAtMs = null;
+        this.activeCommands.delete(metric);
+        this.active = Math.max(0, this.active - 1);
+        this.completedCount += 1;
+        if (!outcome.success) {
+            this.failedCount += 1;
+        }
+        if (outcome.timedOut) {
+            this.timedOutCount += 1;
+        }
+        this.executionSamples.push(Math.max(0, this.clock() - startedAtMs));
+    }
+    snapshotAndReset(limiter = { active: this.active, pending: this.pendingCommands.size }) {
+        const now = this.clock();
+        const oldestPendingAtMs = Math.min(...Array.from(this.pendingCommands, (metric) => metric.queuedAtMs));
+        const snapshot = {
+            concurrencyLimit: this.limits.concurrencyLimit,
+            maxProcessesPerSecond: this.limits.maxProcessesPerSecond,
+            active: limiter.active,
+            pending: limiter.pending,
+            peakActive: this.peakActive,
+            peakPending: this.peakPending,
+            oldestPendingMs: limiter.pending > 0 && Number.isFinite(oldestPendingAtMs)
+                ? Math.max(0, now - oldestPendingAtMs)
+                : 0,
+            submitted: this.submittedCount,
+            started: this.startedCount,
+            completed: this.completedCount,
+            failed: this.failedCount,
+            timedOut: this.timedOutCount,
+            queueWaitMs: summarizeDurations(this.queueWaitSamples),
+            executionMs: summarizeDurations(this.executionSamples),
+            operationsTop: [...this.operationCounts.entries()]
+                .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+                .slice(0, 12),
+            provenanceTop: topCounts(this.provenanceCounts),
+            pendingProvenanceTop: topProvenance(this.pendingCommands),
+            activeProvenanceTop: topProvenance(this.activeCommands),
+        };
+        this.peakActive = limiter.active;
+        this.peakPending = limiter.pending;
+        this.submittedCount = 0;
+        this.startedCount = 0;
+        this.completedCount = 0;
+        this.failedCount = 0;
+        this.timedOutCount = 0;
+        this.queueWaitSamples.length = 0;
+        this.executionSamples.length = 0;
+        this.operationCounts.clear();
+        this.provenanceCounts.clear();
+        return snapshot;
+    }
+}
+function topProvenance(commands) {
+    const counts = new Map();
+    for (const command of commands) {
+        counts.set(command.provenance, (counts.get(command.provenance) ?? 0) + 1);
+    }
+    return topCounts(counts);
+}
+function topCounts(counts) {
+    return [...counts.entries()]
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .slice(0, 12);
+}
+function summarizeDurations(samples) {
+    if (samples.length === 0) {
+        return { count: 0, p50Ms: 0, p95Ms: 0, maxMs: 0 };
+    }
+    const sorted = [...samples].sort((left, right) => left - right);
+    return {
+        count: sorted.length,
+        p50Ms: Math.round(sorted[Math.floor(sorted.length / 2)] ?? 0),
+        p95Ms: Math.round(sorted[Math.ceil(sorted.length * 0.95) - 1] ?? 0),
+        maxMs: Math.round(sorted[sorted.length - 1] ?? 0),
+    };
+}
+//# sourceMappingURL=git-command-runtime-metrics.js.map

package/dist/server/utils/git-command-trace.d.ts

@@ -0,0 +1,29 @@
+interface GitCommandTraceContext {
+    id: string;
+    args: string[];
+    cwd: string;
+    submittedAtMs: number;
+    startedAtMs: number | null;
+    spawnedAtMs: number | null;
+    pid: number | null;
+    submittedQueue: GitCommandTraceQueueState;
+    startedQueue: GitCommandTraceQueueState | null;
+    settled: boolean;
+}
+interface GitCommandTraceQueueState {
+    active: number;
+    pending: number;
+}
+interface GitCommandTraceSettlement {
+    outcome: "closed" | "spawn_error" | "timed_out";
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    truncated?: boolean;
+}
+export declare function flushGitCommandTrace(): Promise<void>;
+export declare function submitGitCommandTrace(args: string[], cwd: string, queue: GitCommandTraceQueueState): GitCommandTraceContext | null;
+export declare function startGitCommandTrace(context: GitCommandTraceContext | null, queue: GitCommandTraceQueueState): void;
+export declare function spawnGitCommandTrace(context: GitCommandTraceContext | null, pid: number | undefined): void;
+export declare function settleGitCommandTrace(context: GitCommandTraceContext | null, settlement: GitCommandTraceSettlement): void;
+export {};
+//# sourceMappingURL=git-command-trace.d.ts.map

package/dist/server/utils/git-command-trace.js

@@ -0,0 +1,74 @@
+import { appendFile } from "node:fs/promises";
+let nextTraceId = 1;
+let pendingTraceWrite = Promise.resolve();
+function appendTrace(event) {
+    const tracePath = process.env.PASEO_GIT_TRACE_FILE?.trim();
+    if (!tracePath)
+        return;
+    pendingTraceWrite = pendingTraceWrite
+        .then(() => appendFile(tracePath, `${JSON.stringify(event)}\n`, "utf8"))
+        .catch(() => {
+        // Diagnostic tracing must never change command execution.
+    });
+}
+export async function flushGitCommandTrace() {
+    await pendingTraceWrite;
+}
+export function submitGitCommandTrace(args, cwd, queue) {
+    if (!process.env.PASEO_GIT_TRACE_FILE?.trim())
+        return null;
+    const submittedAtMs = Date.now();
+    const context = {
+        id: `${process.pid}:${nextTraceId++}`,
+        args: [...args],
+        cwd,
+        submittedAtMs,
+        startedAtMs: null,
+        spawnedAtMs: null,
+        pid: null,
+        submittedQueue: { ...queue },
+        startedQueue: null,
+        settled: false,
+    };
+    return context;
+}
+export function startGitCommandTrace(context, queue) {
+    if (!context)
+        return;
+    context.startedAtMs = Date.now();
+    context.startedQueue = { ...queue };
+}
+export function spawnGitCommandTrace(context, pid) {
+    if (!context)
+        return;
+    context.spawnedAtMs = Date.now();
+    context.pid = pid ?? null;
+}
+export function settleGitCommandTrace(context, settlement) {
+    if (!context || context.settled)
+        return;
+    context.settled = true;
+    const atMs = Date.now();
+    appendTrace({
+        kind: "git_command",
+        event: "settled",
+        id: context.id,
+        atMs,
+        submittedAtMs: context.submittedAtMs,
+        startedAtMs: context.startedAtMs,
+        args: context.args,
+        cwd: context.cwd,
+        queueWaitMs: context.startedAtMs === null ? null : context.startedAtMs - context.submittedAtMs,
+        spawnCallMs: context.startedAtMs === null || context.spawnedAtMs === null
+            ? null
+            : context.spawnedAtMs - context.startedAtMs,
+        pid: context.pid,
+        queue: {
+            submitted: context.submittedQueue,
+            started: context.startedQueue,
+        },
+        durationMs: atMs - context.submittedAtMs,
+        ...settlement,
+    });
+}
+//# sourceMappingURL=git-command-trace.js.map

package/dist/server/utils/git-process-scheduler.d.ts

@@ -0,0 +1,34 @@
+export interface GitProcessPolicy {
+    maxProcessesPerSecond: number;
+    maxProcessConcurrency: number;
+}
+export declare const DEFAULT_GIT_PROCESS_POLICY: GitProcessPolicy;
+export interface ScheduledGitProcess<T> {
+    result: Promise<T>;
+    exited: Promise<void>;
+}
+export type GitProcessPriority = "normal" | "high";
+export declare function resolveGitProcessPolicy(input: {
+    env: NodeJS.ProcessEnv;
+    persisted?: Partial<GitProcessPolicy>;
+}): GitProcessPolicy;
+export declare class GitProcessScheduler {
+    readonly policy: GitProcessPolicy;
+    private readonly startThrottled;
+    private readonly highPriorityQueue;
+    private readonly normalPriorityQueue;
+    private admitted;
+    private running;
+    private waiting;
+    private drainScheduled;
+    constructor(policy: GitProcessPolicy);
+    get activeCount(): number;
+    get pendingCount(): number;
+    run<T>(start: () => ScheduledGitProcess<T>, options?: {
+        priority?: GitProcessPriority;
+    }): Promise<T>;
+    private scheduleDrain;
+    private drainOne;
+    private execute;
+}
+//# sourceMappingURL=git-process-scheduler.d.ts.map

package/dist/server/utils/git-process-scheduler.js

@@ -0,0 +1,112 @@
+import { setImmediate as scheduleImmediate } from "node:timers";
+import pThrottle from "p-throttle";
+export const DEFAULT_GIT_PROCESS_POLICY = {
+    maxProcessesPerSecond: 64,
+    maxProcessConcurrency: 8,
+};
+function parsePositiveInteger(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+export function resolveGitProcessPolicy(input) {
+    return {
+        maxProcessesPerSecond: parsePositiveInteger(input.env.PASEO_GIT_MAX_PROCESSES_PER_SECOND) ??
+            input.persisted?.maxProcessesPerSecond ??
+            DEFAULT_GIT_PROCESS_POLICY.maxProcessesPerSecond,
+        maxProcessConcurrency: parsePositiveInteger(input.env.PASEO_GIT_MAX_PROCESS_CONCURRENCY) ??
+            // COMPAT(gitConcurrencyEnv): renamed in v0.2.6; remove after 2027-02-02.
+            parsePositiveInteger(input.env.PASEO_GIT_CONCURRENCY) ??
+            input.persisted?.maxProcessConcurrency ??
+            DEFAULT_GIT_PROCESS_POLICY.maxProcessConcurrency,
+    };
+}
+export class GitProcessScheduler {
+    constructor(policy) {
+        this.policy = policy;
+        this.highPriorityQueue = [];
+        this.normalPriorityQueue = [];
+        this.admitted = 0;
+        this.running = 0;
+        this.waiting = 0;
+        this.drainScheduled = false;
+        const throttle = pThrottle({
+            limit: policy.maxProcessesPerSecond,
+            interval: 1000,
+            strict: true,
+        });
+        this.startThrottled = throttle((start) => start());
+    }
+    get activeCount() {
+        return this.running;
+    }
+    get pendingCount() {
+        return this.waiting;
+    }
+    run(start, options) {
+        this.waiting += 1;
+        return new Promise((resolve, reject) => {
+            const admit = () => {
+                void this.startThrottled(() => this.execute(start, resolve, reject)).catch((error) => {
+                    this.waiting = Math.max(0, this.waiting - 1);
+                    this.admitted = Math.max(0, this.admitted - 1);
+                    reject(error);
+                    this.scheduleDrain();
+                });
+            };
+            const queue = options?.priority === "high" ? this.highPriorityQueue : this.normalPriorityQueue;
+            queue.push(admit);
+            if (this.admitted === 0 && !this.drainScheduled) {
+                this.drainOne();
+            }
+            else {
+                this.scheduleDrain();
+            }
+        });
+    }
+    scheduleDrain() {
+        if (this.drainScheduled || this.admitted >= this.policy.maxProcessConcurrency) {
+            return;
+        }
+        if (this.highPriorityQueue.length === 0 && this.normalPriorityQueue.length === 0) {
+            return;
+        }
+        this.drainScheduled = true;
+        scheduleImmediate(() => this.drainOne());
+    }
+    drainOne() {
+        this.drainScheduled = false;
+        if (this.admitted >= this.policy.maxProcessConcurrency) {
+            return;
+        }
+        const admit = this.highPriorityQueue.shift() ?? this.normalPriorityQueue.shift();
+        if (!admit) {
+            return;
+        }
+        this.admitted += 1;
+        admit();
+        // Spawning can be synchronous and expensive on a throttled host. Let timers,
+        // sockets, and child exits run before admitting another Git process.
+        this.scheduleDrain();
+    }
+    async execute(start, resolve, reject) {
+        this.waiting = Math.max(0, this.waiting - 1);
+        this.running += 1;
+        try {
+            const process = start();
+            void process.result.then(resolve, reject);
+            await process.exited;
+        }
+        catch (error) {
+            reject(error);
+        }
+        finally {
+            this.running = Math.max(0, this.running - 1);
+            this.admitted = Math.max(0, this.admitted - 1);
+            this.scheduleDrain();
+        }
+    }
+}
+//# sourceMappingURL=git-process-scheduler.js.map

package/dist/server/utils/git-rev-parse-path.d.ts

@@ -0,0 +1,3 @@
+export declare function parseGitRevParsePath(stdout: string): string | null;
+export declare function resolveGitRevParsePath(cwd: string, stdout: string): string | null;
+//# sourceMappingURL=git-rev-parse-path.d.ts.map

package/dist/server/utils/git-rev-parse-path.js

@@ -0,0 +1,21 @@
+import { resolve } from "node:path";
+export function parseGitRevParsePath(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const lines = trimmed.split(/\r?\n/);
+    if (lines.length !== 1) {
+        return null;
+    }
+    const path = lines[0]?.trim() ?? "";
+    if (!path || path.startsWith("--")) {
+        return null;
+    }
+    return path;
+}
+export function resolveGitRevParsePath(cwd, stdout) {
+    const parsed = parseGitRevParsePath(stdout);
+    return parsed ? resolve(cwd, parsed) : null;
+}
+//# sourceMappingURL=git-rev-parse-path.js.map

package/dist/server/utils/paseo-config-file.d.ts

@@ -0,0 +1,30 @@
+import { type PaseoConfigRaw, type PaseoConfigRevision, type ProjectConfigRpcError } from "@camerontaylor/paseo-protocol/paseo-config-schema";
+export { PaseoConfigRevisionSchema, ProjectConfigRpcErrorSchema, type PaseoConfigRevision, type ProjectConfigRpcError, } from "@camerontaylor/paseo-protocol/paseo-config-schema";
+export declare const PASEO_CONFIG_FILE_NAME = "paseo.json";
+export type ReadPaseoConfigForEditResult = {
+    ok: true;
+    config: PaseoConfigRaw | null;
+    revision: PaseoConfigRevision | null;
+} | {
+    ok: false;
+    error: ProjectConfigRpcError;
+};
+export type WritePaseoConfigForEditResult = {
+    ok: true;
+    config: PaseoConfigRaw;
+    revision: PaseoConfigRevision;
+} | {
+    ok: false;
+    error: ProjectConfigRpcError;
+};
+export interface WritePaseoConfigForEditInput {
+    repoRoot: string;
+    config: PaseoConfigRaw;
+    expectedRevision: PaseoConfigRevision | null;
+}
+export declare function resolvePaseoConfigPath(repoRoot: string): string;
+export declare function statPaseoConfigPath(repoRoot: string): PaseoConfigRevision | null;
+export declare function readPaseoConfigJson(repoRoot: string): unknown;
+export declare function readPaseoConfigForEdit(repoRoot: string): ReadPaseoConfigForEditResult;
+export declare function writePaseoConfigForEdit(input: WritePaseoConfigForEditInput): WritePaseoConfigForEditResult;
+//# sourceMappingURL=paseo-config-file.d.ts.map

package/dist/server/utils/paseo-config-file.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { PaseoConfigRawSchema, } from "@camerontaylor/paseo-protocol/paseo-config-schema";
+export { PaseoConfigRevisionSchema, ProjectConfigRpcErrorSchema, } from "@camerontaylor/paseo-protocol/paseo-config-schema";
+export const PASEO_CONFIG_FILE_NAME = "paseo.json";
+export function resolvePaseoConfigPath(repoRoot) {
+    return join(repoRoot, PASEO_CONFIG_FILE_NAME);
+}
+export function statPaseoConfigPath(repoRoot) {
+    const configPath = resolvePaseoConfigPath(repoRoot);
+    if (!existsSync(configPath)) {
+        return null;
+    }
+    const stats = statSync(configPath);
+    return {
+        mtimeMs: stats.mtimeMs,
+        size: stats.size,
+    };
+}
+export function readPaseoConfigJson(repoRoot) {
+    const configPath = resolvePaseoConfigPath(repoRoot);
+    if (!existsSync(configPath)) {
+        return null;
+    }
+    return JSON.parse(readFileSync(configPath, "utf8"));
+}
+export function readPaseoConfigForEdit(repoRoot) {
+    try {
+        const json = readPaseoConfigJson(repoRoot);
+        if (json === null) {
+            return { ok: true, config: null, revision: null };
+        }
+        return {
+            ok: true,
+            config: PaseoConfigRawSchema.parse(json),
+            revision: statPaseoConfigPath(repoRoot),
+        };
+    }
+    catch {
+        return {
+            ok: false,
+            error: { code: "invalid_project_config" },
+        };
+    }
+}
+export function writePaseoConfigForEdit(input) {
+    const parsed = PaseoConfigRawSchema.safeParse(input.config);
+    if (!parsed.success) {
+        return { ok: false, error: { code: "invalid_project_config" } };
+    }
+    const configPath = resolvePaseoConfigPath(input.repoRoot);
+    const tempPath = join(input.repoRoot, `.${PASEO_CONFIG_FILE_NAME}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(parsed.data, null, 2)}\n`);
+        const currentRevision = statPaseoConfigPath(input.repoRoot);
+        if (!paseoConfigRevisionsEqual(currentRevision, input.expectedRevision)) {
+            removeTempPaseoConfig(tempPath);
+            return {
+                ok: false,
+                error: { code: "stale_project_config", currentRevision },
+            };
+        }
+        renameSync(tempPath, configPath);
+        const revision = statPaseoConfigPath(input.repoRoot);
+        if (!revision) {
+            return { ok: false, error: { code: "write_failed" } };
+        }
+        return { ok: true, config: parsed.data, revision };
+    }
+    catch {
+        removeTempPaseoConfig(tempPath);
+        return { ok: false, error: { code: "write_failed" } };
+    }
+}
+function paseoConfigRevisionsEqual(left, right) {
+    if (left === null || right === null) {
+        return left === right;
+    }
+    return left.mtimeMs === right.mtimeMs && left.size === right.size;
+}
+function removeTempPaseoConfig(tempPath) {
+    try {
+        rmSync(tempPath, { force: true });
+    }
+    catch {
+        // Best-effort cleanup only; callers need the original write outcome.
+    }
+}
+//# sourceMappingURL=paseo-config-file.js.map

package/dist/server/utils/path.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Expand tilde in path to home directory
+ */
+export declare function expandTilde(path: string): string;
+/**
+ * Compare two path strings as filesystem-equivalent for cwd filtering.
+ *
+ * This is a string-only comparison: it normalizes separators and dot segments,
+ * ignores trailing separators, strips Windows namespace prefixes, and
+ * case-folds only when comparing as Windows. It does not resolve symlinks or
+ * check whether either path exists.
+ */
+export declare function areEquivalentPaths(left: string, right: string): boolean;
+export declare function createPathEquivalenceMatcher(target: string): (candidate: string) => boolean;
+export declare function createRealpathAwarePathMatcher(target: string): (candidate: string) => boolean;
+export declare function isPathInsideRoot(root: string, candidate: string): boolean;
+export declare function normalizePathForIdentity(value: string): string;
+/**
+ * Returns the candidate's relative suffix when it is inside root.
+ *
+ * The suffix is derived from the same lexical path pair used to prove
+ * containment. Callers that map an existing filesystem path into a new root
+ * must keep those two operations coupled.
+ */
+export declare function getRealpathAwareRelativePath(root: string, candidate: string): string | null;
+export declare function isRealpathInsideRoot(root: string, candidate: string): boolean;
+//# sourceMappingURL=path.d.ts.map