@bytetrue/byspace 0.1.0

package/node_modules/@bytetrue/byspace-server/dist/server/utils/run-git-command.js

@@ -0,0 +1,232 @@
+import { existsSync } from "node:fs";
+import pLimit from "p-limit";
+import { spawnProcess } from "./spawn.js";
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_OUTPUT_BYTES = 20 * 1024 * 1024; // 20MB
+const DEFAULT_STDERR_LIMIT = 2048;
+const gitConcurrency = parseInt(process.env.BYSPACE_GIT_CONCURRENCY ?? "8", 10) || 8;
+const gitLimit = pLimit(gitConcurrency);
+let gitCommandMetricsState = null;
+export function startGitCommandMetrics() {
+    gitCommandMetricsState = {
+        commands: [],
+        active: 0,
+        maxConcurrent: 0,
+    };
+}
+export function stopGitCommandMetrics() {
+    const state = gitCommandMetricsState;
+    gitCommandMetricsState = null;
+    if (!state) {
+        return {
+            commands: [],
+            total: 0,
+            failed: 0,
+            maxConcurrent: 0,
+        };
+    }
+    return {
+        commands: [...state.commands],
+        total: state.commands.length,
+        failed: state.commands.filter((command) => !command.success).length,
+        maxConcurrent: state.maxConcurrent,
+    };
+}
+function beginGitCommandMetric() {
+    const state = gitCommandMetricsState;
+    if (!state) {
+        return null;
+    }
+    state.active += 1;
+    state.maxConcurrent = Math.max(state.maxConcurrent, state.active);
+    return state;
+}
+function finishGitCommandMetric(state, metric) {
+    if (!state) {
+        return;
+    }
+    state.active = Math.max(0, state.active - 1);
+    state.commands.push(metric);
+}
+function mergeEnvOverlays(env, envOverlay) {
+    if (!env) {
+        return envOverlay;
+    }
+    if (!envOverlay) {
+        return env;
+    }
+    return { ...env, ...envOverlay };
+}
+function getEnvOverlayKeys(envOverlay) {
+    return Object.keys(envOverlay ?? {}).sort();
+}
+export function runGitCommand(args, options) {
+    return gitLimit(() => new Promise((resolve, reject) => {
+        const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+        const acceptExitCodes = options.acceptExitCodes ?? [0];
+        const command = formatGitCommand(args);
+        const envOverlay = mergeEnvOverlays(options.env, options.envOverlay);
+        const startedAt = Date.now();
+        const metricsState = beginGitCommandMetric();
+        const logger = typeof options.logger?.trace === "function" ? options.logger : undefined;
+        const traceContext = logger
+            ? {
+                command: "git",
+                args,
+                cwd: options.cwd,
+                cwdExists: existsSync(options.cwd),
+                timeout,
+                maxOutputBytes,
+                acceptExitCodes,
+                envOverlayKeys: getEnvOverlayKeys(envOverlay),
+            }
+            : null;
+        if (logger && traceContext) {
+            logger.trace(traceContext, "Spawning git command");
+        }
+        // `core.quotepath=false` makes git emit raw UTF-8 paths instead of
+        // octal-escaping non-ASCII bytes (e.g. `测试文件.txt` vs `"\346\265\213..."`).
+        const child = spawnProcess("git", ["-c", "core.quotepath=false", ...args], {
+            cwd: options.cwd,
+            envOverlay,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let settled = false;
+        let metricFinished = false;
+        let truncated = false;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const settle = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            callback();
+        };
+        const finishMetricOnce = (metric) => {
+            if (metricFinished)
+                return;
+            metricFinished = true;
+            finishGitCommandMetric(metricsState, metric);
+        };
+        const timer = setTimeout(() => {
+            const error = new Error(`Git command timed out after ${timeout}ms: ${command}`);
+            child.kill("SIGKILL");
+            finishMetricOnce({
+                args,
+                cwd: options.cwd,
+                startedAtMs: startedAt,
+                durationMs: Date.now() - startedAt,
+                exitCode: null,
+                signal: "SIGKILL",
+                success: false,
+            });
+            settle(() => reject(error));
+        }, timeout);
+        child.stdout.on("data", (chunk) => {
+            if (settled || truncated)
+                return;
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const remainingBytes = maxOutputBytes - stdoutBytes;
+            if (remainingBytes <= 0) {
+                truncated = true;
+                child.kill("SIGKILL");
+                return;
+            }
+            if (buffer.length > remainingBytes) {
+                stdoutChunks.push(buffer.subarray(0, remainingBytes));
+                stdoutBytes += remainingBytes;
+                truncated = true;
+                child.kill("SIGKILL");
+                return;
+            }
+            stdoutChunks.push(buffer);
+            stdoutBytes += buffer.length;
+        });
+        child.stderr.on("data", (chunk) => {
+            if (settled || stderrBytes >= DEFAULT_STDERR_LIMIT)
+                return;
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const remainingBytes = DEFAULT_STDERR_LIMIT - stderrBytes;
+            if (buffer.length > remainingBytes) {
+                stderrChunks.push(buffer.subarray(0, remainingBytes));
+                stderrBytes += remainingBytes;
+                return;
+            }
+            stderrChunks.push(buffer);
+            stderrBytes += buffer.length;
+        });
+        child.on("error", (error) => {
+            finishMetricOnce({
+                args,
+                cwd: options.cwd,
+                startedAtMs: startedAt,
+                durationMs: Date.now() - startedAt,
+                exitCode: null,
+                signal: null,
+                success: false,
+            });
+            if (logger && traceContext) {
+                logger.trace({
+                    ...traceContext,
+                    err: error,
+                    durationMs: Date.now() - startedAt,
+                }, "Git command process error");
+            }
+            settle(() => reject(error));
+        });
+        child.on("close", (exitCode, signal) => {
+            const result = {
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                truncated,
+                exitCode,
+                signal,
+            };
+            if (logger && traceContext) {
+                logger.trace({
+                    ...traceContext,
+                    durationMs: Date.now() - startedAt,
+                    exitCode,
+                    signal,
+                    truncated,
+                    stdoutBytes,
+                    stderrBytes,
+                }, "Git command closed");
+            }
+            if (!truncated && !acceptExitCodes.includes(exitCode ?? -1)) {
+                finishMetricOnce({
+                    args,
+                    cwd: options.cwd,
+                    startedAtMs: startedAt,
+                    durationMs: Date.now() - startedAt,
+                    exitCode,
+                    signal,
+                    success: false,
+                });
+                const stderrPreview = result.stderr.trim() || "(no stderr)";
+                const truncationNote = result.truncated ? " (stdout truncated)" : "";
+                settle(() => reject(new Error(`Git command failed: ${command}${truncationNote} (exit code: ${String(exitCode)}, signal: ${signal ?? "none"})\n${stderrPreview}`)));
+                return;
+            }
+            finishMetricOnce({
+                args,
+                cwd: options.cwd,
+                startedAtMs: startedAt,
+                durationMs: Date.now() - startedAt,
+                exitCode,
+                signal,
+                success: true,
+            });
+            settle(() => resolve(result));
+        });
+    }));
+}
+function formatGitCommand(args) {
+    return ["git", ...args].join(" ");
+}
+//# sourceMappingURL=run-git-command.js.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/spawn.d.ts

@@ -0,0 +1,25 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { type ProcessEnvRecord } from "../server/byspace-env.js";
+interface ExternalEnvOptions {
+    baseEnv?: ProcessEnvRecord;
+    envMode?: "external" | "internal";
+    env?: ProcessEnvRecord;
+    envOverlay?: ProcessEnvRecord;
+}
+export type SpawnProcessOptions = Omit<SpawnOptions, "env"> & ExternalEnvOptions;
+interface ExecCommandOptions extends ExternalEnvOptions {
+    cwd?: string;
+    encoding?: BufferEncoding;
+    killSignal?: NodeJS.Signals;
+    timeout?: number;
+    maxBuffer?: number;
+    shell?: boolean | string;
+}
+interface ExecCommandResult {
+    stdout: string;
+    stderr: string;
+}
+export declare function spawnProcess(command: string, args: string[], options?: SpawnProcessOptions): ChildProcess;
+export declare function execCommand(command: string, args: string[], options?: ExecCommandOptions): Promise<ExecCommandResult>;
+export {};
+//# sourceMappingURL=spawn.d.ts.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/spawn.js

@@ -0,0 +1,59 @@
+import { execFile, spawn } from "node:child_process";
+import { extname } from "node:path";
+import { promisify } from "node:util";
+import { createExternalCommandProcessEnv } from "../server/byspace-env.js";
+import { isWindowsCommandScript, quoteWindowsArgument, quoteWindowsCommand, } from "./windows-command.js";
+const execFileAsync = promisify(execFile);
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function shouldUseWindowsShell(command, requestedShell) {
+    if (isWindowsCommandScript(command)) {
+        return true;
+    }
+    if (requestedShell !== undefined) {
+        return requestedShell;
+    }
+    return process.platform === "win32" && !hasPathSeparator(command) && !extname(command);
+}
+export function spawnProcess(command, args, options) {
+    const { baseEnv, env, envOverlay, ...spawnOptions } = options ?? {};
+    const resolvedBaseEnv = env ?? baseEnv ?? process.env;
+    const isWindows = process.platform === "win32";
+    const shell = shouldUseWindowsShell(command, spawnOptions.shell);
+    const shouldQuoteForShell = isWindows && shell !== false;
+    const resolvedCommand = shouldQuoteForShell ? quoteWindowsCommand(command) : command;
+    const resolvedArgs = shouldQuoteForShell ? args.map(quoteWindowsArgument) : args;
+    const childEnv = options?.envMode === "internal"
+        ? { ...resolvedBaseEnv, ...envOverlay }
+        : createExternalCommandProcessEnv(command, resolvedBaseEnv, ...(envOverlay ? [envOverlay] : []));
+    return spawn(resolvedCommand, resolvedArgs, {
+        ...spawnOptions,
+        env: childEnv,
+        shell,
+        windowsHide: true,
+    });
+}
+export async function execCommand(command, args, options) {
+    const { baseEnv, env, envOverlay } = options ?? {};
+    const resolvedBaseEnv = env ?? baseEnv ?? process.env;
+    const isWindows = process.platform === "win32";
+    const shell = shouldUseWindowsShell(command, options?.shell);
+    const shouldQuoteForShell = isWindows && shell !== false;
+    const resolvedCommand = shouldQuoteForShell ? quoteWindowsCommand(command) : command;
+    const resolvedArgs = shouldQuoteForShell ? args.map(quoteWindowsArgument) : args;
+    const childEnv = options?.envMode === "internal"
+        ? { ...resolvedBaseEnv, ...envOverlay }
+        : createExternalCommandProcessEnv(command, resolvedBaseEnv, ...(envOverlay ? [envOverlay] : []));
+    return execFileAsync(resolvedCommand, resolvedArgs, {
+        cwd: options?.cwd,
+        env: childEnv,
+        encoding: options?.encoding ?? "utf8",
+        killSignal: options?.killSignal,
+        timeout: options?.timeout,
+        maxBuffer: options?.maxBuffer,
+        shell,
+        windowsHide: true,
+    });
+}
+//# sourceMappingURL=spawn.js.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/string-command-shell.d.ts

@@ -0,0 +1,13 @@
+export interface BuildStringCommandShellInvocationOptions {
+    command: string;
+    platform?: NodeJS.Platform;
+    windowsShell?: "powershell" | "cmd";
+}
+export interface StringCommandShellInvocation {
+    shell: string;
+    args: string[];
+}
+export declare function createStringCommandShellEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function createStringCommandShellEnvOverlay(): Record<string, string | undefined>;
+export declare function buildStringCommandShellInvocation(options: BuildStringCommandShellInvocationOptions): StringCommandShellInvocation;
+//# sourceMappingURL=string-command-shell.d.ts.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/string-command-shell.js

@@ -0,0 +1,37 @@
+export function createStringCommandShellEnv(env) {
+    const sanitized = { ...env };
+    delete sanitized.BASH_ENV;
+    return sanitized;
+}
+export function createStringCommandShellEnvOverlay() {
+    return { BASH_ENV: undefined };
+}
+export function buildStringCommandShellInvocation(options) {
+    const platform = options.platform ?? process.platform;
+    // Project-authored command strings use a stable script shell. The caller supplies
+    // the environment; shell startup files should not rewrite it behind our back.
+    if (platform === "win32") {
+        if (options.windowsShell === "cmd") {
+            return {
+                shell: "cmd.exe",
+                args: ["/c", options.command],
+            };
+        }
+        return {
+            shell: "powershell",
+            args: [
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                options.command,
+            ],
+        };
+    }
+    return {
+        shell: "bash",
+        args: ["-c", options.command],
+    };
+}
+//# sourceMappingURL=string-command-shell.js.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/tree-kill.d.ts

@@ -0,0 +1,18 @@
+export interface TreeKillTarget {
+    pid?: number;
+    exitCode?: number | null;
+    signalCode?: NodeJS.Signals | null;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once?(event: "exit", listener: () => void): unknown;
+}
+export interface TerminateWithTreeKillOptions {
+    gracefulSignal?: NodeJS.Signals;
+    forceSignal?: NodeJS.Signals;
+    gracefulTimeoutMs: number;
+    forceTimeoutMs?: number;
+    onForceSignal?: () => void;
+}
+export type TerminateWithTreeKillResult = "already-exited" | "terminated" | "killed" | "kill-timeout";
+export type ProcessTerminator = (child: TreeKillTarget, options: TerminateWithTreeKillOptions) => Promise<TerminateWithTreeKillResult>;
+export declare function terminateWithTreeKill(child: TreeKillTarget, options: TerminateWithTreeKillOptions): Promise<TerminateWithTreeKillResult>;
+//# sourceMappingURL=tree-kill.d.ts.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/tree-kill.js

@@ -0,0 +1,77 @@
+import treeKill from "tree-kill";
+export async function terminateWithTreeKill(child, options) {
+    if (isProcessExited(child)) {
+        return "already-exited";
+    }
+    const exitPromise = waitForProcessExit(child);
+    await signalTreeOrChild(child, options.gracefulSignal ?? "SIGTERM");
+    if (await waitForExitOrTimeout(exitPromise, options.gracefulTimeoutMs)) {
+        return "terminated";
+    }
+    options.onForceSignal?.();
+    await signalTreeOrChild(child, options.forceSignal ?? "SIGKILL");
+    if (options.forceTimeoutMs === undefined) {
+        return "killed";
+    }
+    return (await waitForExitOrTimeout(exitPromise, options.forceTimeoutMs))
+        ? "killed"
+        : "kill-timeout";
+}
+function signalTreeOrChild(child, signal) {
+    if (isProcessExited(child)) {
+        return Promise.resolve();
+    }
+    const pid = child.pid;
+    if (typeof pid !== "number" || pid <= 0) {
+        signalDirectChild(child, signal);
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        treeKill(pid, signal, (error) => {
+            if (error) {
+                signalDirectChild(child, signal);
+            }
+            resolve();
+        });
+    });
+}
+function signalDirectChild(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Ignore cleanup races.
+    }
+}
+function isProcessExited(child) {
+    return ((child.exitCode !== null && child.exitCode !== undefined) ||
+        (child.signalCode !== null && child.signalCode !== undefined));
+}
+function waitForProcessExit(child) {
+    if (isProcessExited(child)) {
+        return Promise.resolve();
+    }
+    if (!child.once) {
+        return new Promise(() => undefined);
+    }
+    return new Promise((resolve) => {
+        child.once?.("exit", resolve);
+    });
+}
+async function waitForExitOrTimeout(exitPromise, timeoutMs) {
+    let timer = null;
+    try {
+        return await Promise.race([
+            exitPromise.then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=tree-kill.js.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/windows-command.d.ts

@@ -0,0 +1,15 @@
+export declare function isWindowsCommandScript(executablePath: string): boolean;
+/**
+ * When spawning with `shell: true` on Windows, the command is passed to
+ * `cmd.exe /d /s /c "command args"`. The `/s` strips outer quotes, so a
+ * command path with spaces (e.g. `C:\Program Files\...`) is split at the
+ * space. Wrapping it in quotes produces the correct `"C:\Program Files\..." args`.
+ */
+export declare function quoteWindowsCommand(command: string): string;
+/**
+ * `spawn(..., { shell: true })` on Windows also passes argv through `cmd.exe`.
+ * Any argument containing spaces must be quoted or it will be split before the
+ * child process sees it.
+ */
+export declare function quoteWindowsArgument(argument: string): string;
+//# sourceMappingURL=windows-command.d.ts.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/windows-command.js

@@ -0,0 +1,41 @@
+import { extname } from "node:path";
+export function isWindowsCommandScript(executablePath) {
+    const extension = extname(executablePath).toLowerCase();
+    return process.platform === "win32" && (extension === ".cmd" || extension === ".bat");
+}
+function escapeWindowsCmdValue(value) {
+    if (process.platform !== "win32")
+        return value;
+    const isQuoted = value.startsWith('"') && value.endsWith('"');
+    const unquoted = isQuoted ? value.slice(1, -1) : value;
+    // Do NOT double `%` here. cmd.exe only collapses `%%` → `%` inside batch
+    // files; on the command line / `cmd /c "..."` `%%` stays literal, which
+    // breaks args like git's `--format=%(refname)` (git treats `%%` as the
+    // escape for a literal `%`, so the format atoms become literals).
+    const escaped = unquoted.replace(/([&|^<>()!])/g, "^$1");
+    if (isQuoted || /[\s"]/u.test(unquoted)) {
+        const quoted = escaped
+            .replace(/(\\*)"/g, (_match, slashes) => `${slashes}${slashes}\\"`)
+            .replace(/\\+$/u, (slashes) => `${slashes}${slashes}`);
+        return `"${quoted}"`;
+    }
+    return escaped;
+}
+/**
+ * When spawning with `shell: true` on Windows, the command is passed to
+ * `cmd.exe /d /s /c "command args"`. The `/s` strips outer quotes, so a
+ * command path with spaces (e.g. `C:\Program Files\...`) is split at the
+ * space. Wrapping it in quotes produces the correct `"C:\Program Files\..." args`.
+ */
+export function quoteWindowsCommand(command) {
+    return escapeWindowsCmdValue(command);
+}
+/**
+ * `spawn(..., { shell: true })` on Windows also passes argv through `cmd.exe`.
+ * Any argument containing spaces must be quoted or it will be split before the
+ * child process sees it.
+ */
+export function quoteWindowsArgument(argument) {
+    return escapeWindowsCmdValue(argument);
+}
+//# sourceMappingURL=windows-command.js.map

package/node_modules/@bytetrue/byspace-server/dist/server/utils/worktree-metadata.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+declare const BySpaceWorktreeMetadataSchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    baseRefName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    baseRefName: z.ZodString;
+    firstAgentBranchAutoName: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"pending">;
+        placeholderBranchName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        status: z.ZodLiteral<"attempted">;
+        placeholderBranchName: z.ZodString;
+        attemptedAt: z.ZodString;
+    }, z.core.$strip>], "status">>;
+    runtime: z.ZodOptional<z.ZodObject<{
+        worktreePort: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export type BySpaceWorktreeMetadata = z.infer<typeof BySpaceWorktreeMetadataSchema>;
+export declare function getBySpaceWorktreeMetadataPath(worktreeRoot: string): string;
+export declare function normalizeBaseRefName(input: string): string;
+export declare function writeBySpaceWorktreeMetadata(worktreeRoot: string, options: {
+    baseRefName: string;
+}): void;
+export declare function writeBySpaceWorktreeRuntimeMetadata(worktreeRoot: string, options: {
+    worktreePort: number;
+}): void;
+export declare function writeBySpaceWorktreeFirstAgentBranchAutoNameMetadata(worktreeRoot: string, options: {
+    placeholderBranchName: string;
+}): void;
+export declare function markBySpaceWorktreeFirstAgentBranchAutoNameAttempted(worktreeRoot: string, options?: {
+    attemptedAt?: string;
+}): BySpaceWorktreeMetadata | null;
+export declare function readBySpaceWorktreeMetadata(worktreeRoot: string): BySpaceWorktreeMetadata | null;
+export declare function requireBySpaceWorktreeBaseRefName(worktreeRoot: string): string;
+export declare function readBySpaceWorktreeRuntimePort(worktreeRoot: string): number | null;
+export {};
+//# sourceMappingURL=worktree-metadata.d.ts.map