@dbx-tools/core 0.1.2

package/README.md

@@ -0,0 +1,82 @@
+# @dbx-tools/node-core
+
+Node-only core helpers for process execution and project discovery.
+
+Import this package when code needs `node:child_process`, `node:fs`, or
+`node:path`. Browser-safe utilities live in
+[`@dbx-tools/shared-core`](../../shared/core).
+
+Key features:
+
+- Async and sync process execution with consistent stdio handling.
+- AbortSignal support for long-running subprocesses.
+- Small shell-like argument splitting for command strings that must become argv
+  arrays.
+- Workspace/project root discovery from package-manager files, git metadata, and
+  the current working directory.
+- Safe filesystem stat and project naming helpers for CLIs and projen synth.
+
+## Run Commands
+
+```ts
+import { exec } from "@dbx-tools/node-core";
+
+const result = await exec.spawn("git", ["status", "--short"], {
+  stdout: "capture",
+  stderr: "capture",
+});
+
+if (result.exitCode !== 0) {
+  throw new Error(result.stderr);
+}
+```
+
+`exec.spawn()` supports inherited, piped, ignored, captured, and line-callback
+stdio. It accepts string stdin and abort signals, making it useful for CLIs and
+watch tasks.
+
+Prefer `spawn()` over ad hoc `child_process` calls when command output needs to
+be captured, streamed line-by-line, or aborted consistently from higher-level
+tooling.
+
+## Run Synchronously
+
+```ts
+const rev = exec
+  .spawnSync("git", ["rev-parse", "HEAD"], {
+    stdout: "capture",
+  })
+  .stdout.trim();
+```
+
+Use `spawnSync()` during projen synthesis or config discovery where async
+control flow is not available.
+
+## Split Shell-Like Commands
+
+```ts
+const argv = exec.shlex('pnpm exec prettier --write "README.md"');
+```
+
+`shlex()` is a small parser for command strings that need to become argv arrays.
+Prefer explicit argv arrays when possible.
+
+## Discover Project Roots
+
+```ts
+import { project } from "@dbx-tools/node-core";
+
+const root = project.root();
+const name = project.name();
+const origins = [...project.resolveProjectRoots(process.cwd())];
+```
+
+`project.root()` checks npm/pnpm workspace roots, git top-level, and cwd.
+`project.name()` prefers package metadata, then git remote name, then directory
+basename. `project.stat()` returns `undefined` instead of throwing.
+
+## Modules
+
+- `exec` - async/sync process spawning, stdio handling, abort wiring, and shlex.
+- `project` - root discovery, project naming, git-remote parsing, and safe
+  filesystem stat.

package/index.ts

@@ -0,0 +1,7 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as exec from "./src/exec";
+export * as project from "./src/project";
+export type { ExecStdio, LineHandler, StdioOption, ExecResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@dbx-tools/core",
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@dbx-tools/shared-core": "0.1.2"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.2",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/exec.ts

@@ -0,0 +1,643 @@
+/**
+ * Portable subprocess helper built on `child_process.spawn` and line streaming.
+ *
+ * Ported from `dbx-tools-js/packages/cli/src/exec.ts`. Each stdio fd defaults to
+ * `"inherit"`. {@link spawn} streams output line-by-line into {@link ExecResult.stdoutLines}
+ * / {@link ExecResult.stderrLines}; its `stdout` / `stderr` getters join those lines.
+ * {@link spawnSync} keeps the captured string; its `stdout` / `stderr` getters read
+ * that string directly (line arrays split lazily on read).
+ * Omitted `trim` (default) applies adaptive normalization: {@link spawnSync} drops
+ * at most one trailing empty line / newline `spawnSync` adds; {@link spawn} does
+ * not (readline never emits that extra line). `trim: true` strips all leading/
+ * trailing whitespace in both modes; `trim: false` leaves output unchanged.
+ *
+ * @example Capture command output
+ * ```ts
+ * const { stdout } = await exec("git", ["rev-parse", "--show-toplevel"], {
+ *   stdout: "capture",
+ *   stderr: "ignore",
+ *   stdin: "ignore",
+ * });
+ * ```
+ *
+ * @example Stream and capture together
+ * ```ts
+ * await exec("pnpm", ["install"], {
+ *   stdout: [(line) => console.log(line), "capture"],
+ *   check: true,
+ * });
+ * ```
+ *
+ * @example Synchronous capture (no line callbacks)
+ * ```ts
+ * const { stdout } = execSync("git", ["rev-parse", "--show-toplevel"], {
+ *   stdout: "capture",
+ *   stderr: "ignore",
+ *   stdin: "ignore",
+ * });
+ * ```
+ */
+import { type ChildProcess, type SpawnOptions, spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
+import * as readline from "node:readline";
+import { Readable } from "node:stream";
+
+/** Stdio mode for a subprocess fd. */
+export type ExecStdio = "inherit" | "pipe" | "ignore";
+
+/** Invoked once per output line when a fd is piped. */
+export type LineHandler = (line: string) => void;
+
+/**
+ * Stdio config for one fd.
+ *
+ * - `"inherit"` / `"pipe"` / `"ignore"` — pass through to `spawn`
+ * - `"capture"` — pipe the fd and append each line to the result
+ * - {@link LineHandler} — pipe and invoke the handler per line (lines are still captured)
+ * - `(LineHandler | "capture")[]` — pipe; `"capture"` is a no-op marker, handlers run per line
+ */
+export type StdioOption = ExecStdio | LineHandler | "capture" | (LineHandler | "capture")[];
+
+/** Outcome of {@link spawn} / {@link spawnSync}: exit code, captured output, and line views. */
+export type ExecResult = {
+  exitCode: number;
+  /**
+   * Captured stdout lines. For {@link spawn} these are built while the process runs;
+   * for {@link spawnSync} they are split from the captured string on first read.
+   */
+  readonly stdoutLines: string[];
+  /**
+   * Captured stderr lines. For {@link spawn} these are built while the process runs;
+   * for {@link spawnSync} they are split from the captured string on first read.
+   */
+  readonly stderrLines: string[];
+  /**
+   * Captured stdout text. {@link spawnSync} reads the captured string;
+   * {@link spawn} joins {@link stdoutLines}. See `trim` for normalization.
+   */
+  readonly stdout: string;
+  /**
+   * Captured stderr text. {@link spawnSync} reads the captured string;
+   * {@link spawn} joins {@link stderrLines}. See `trim` for normalization.
+   */
+  readonly stderr: string;
+};
+
+/** Options for {@link spawn}. Extends `SpawnOptions` except `stdio`, which is driven by `stdin` / `stdout` / `stderr`. */
+export type ExecOptions = Omit<SpawnOptions, "stdio"> & {
+  /** `"inherit"` by default, or a string written to the process stdin. */
+  stdin?: ExecStdio | string;
+  stdout?: StdioOption;
+  stderr?: StdioOption;
+  /** Throw when the process exits with a non-zero code. */
+  check?: boolean;
+  /**
+   * Omitted — adaptive trim ({@link spawnSync} drops one spawn trailing newline,
+   * {@link spawn} does not); `true` — strip all leading/trailing whitespace;
+   * `false` — leave captured output unchanged.
+   */
+  trim?: boolean;
+};
+
+/** Stdio mode for {@link spawnSync} (no per-line callbacks). */
+export type SyncExecStdio = ExecStdio | "capture";
+
+/** Options for {@link spawnSync}. Same shape as {@link ExecOptions} but without line-handler stdio. */
+export type SyncExecOptions = Omit<SpawnOptions, "stdio"> & {
+  /** `"inherit"` by default, or a string written to the process stdin. */
+  stdin?: ExecStdio | string;
+  stdout?: SyncExecStdio;
+  stderr?: SyncExecStdio;
+  /** Throw when the process exits with a non-zero code. */
+  check?: boolean;
+  /**
+   * Omitted — adaptive trim ({@link spawnSync} drops one spawn trailing newline,
+   * {@link spawn} does not); `true` — strip all leading/trailing whitespace;
+   * `false` — leave captured output unchanged.
+   */
+  trim?: boolean;
+};
+
+/**
+ * Spawn stdio mode plus an optional per-line callback after {@link resolveStdio}
+ * maps a {@link StdioOption} into something `spawn` can consume.
+ */
+type ResolvedStdio = {
+  /** Value passed to `spawn`'s `stdio` tuple for this fd. */
+  mode: ExecStdio;
+  /** When set, each output line is appended to the capture buffer and forwarded here. */
+  onLine?: LineHandler;
+};
+
+export type SpawnArgs<T extends SpawnOptions> =
+  | [command: string, ...args: string[]]
+  | [command: string, args: readonly string[]]
+  | [command: string, args: readonly string[], options: T]
+  | [command: string, ...argsAndOptions: [...string[], T]];
+
+
+interface ParsedSpawnArgs<T extends SpawnOptions> {
+  command: string;
+  commandArgs: string[];
+  options?: T;
+}
+
+
+function parseSpawnArgs<T extends SpawnOptions>(input: SpawnArgs<T>): ParsedSpawnArgs<T> {
+  let [value, ...values] = input;
+  const [command, ...commandArgs] = shlex(value);
+  if (commandArgs.length == 1 && values.length === 0) {
+    return {
+      command,
+      commandArgs: [],
+    };
+  }
+
+  const last = values.at(-1);
+  const options = (
+    last !== null &&
+    typeof last === "object" &&
+    !Array.isArray(last)
+  ) ? last : undefined;
+  const argumentValues = options ? values.slice(0, -1) : values;
+  const valueArgs: string[] = (
+    argumentValues.length === 1 &&
+    Array.isArray(argumentValues[0])
+  ) ? [...argumentValues[0]] : argumentValues
+
+
+  return {
+    command,
+    commandArgs: [...commandArgs, ...valueArgs],
+    options: options as T,
+  };
+}
+
+/**
+ * Drop the single trailing empty entry `spawnSync` adds when splitting on a final
+ * newline (`"hi\n"` -> `["hi", ""]`). Does not remove multiple trailing empties.
+ */
+function withoutSpawnTrailingEmptyLine(lines: readonly string[]): string[] {
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    return lines.slice(0, -1);
+  }
+  return lines as string[];
+}
+
+/** Remove at most one trailing newline from captured spawn stdout/stderr text. */
+function trimSingleTrailingNewline(text: string): string {
+  if (text.endsWith("\r\n")) return text.slice(0, -2);
+  if (text.endsWith("\n")) return text.slice(0, -1);
+  return text;
+}
+
+/** Line-array view of async-captured output. */
+function normalizedAsyncLines(lines: readonly string[], trim: boolean | undefined): string[] {
+  if (trim === true) return linesFromCapturedOutput(lines.join("\n").trim());
+  return lines as string[];
+}
+
+/** Join async-captured lines into stdout/stderr text. */
+function formatAsyncCapturedLines(lines: readonly string[], trim: boolean | undefined): string {
+  const joined = lines.join("\n");
+  return trim === true ? joined.trim() : joined;
+}
+
+/** Line-array view of sync-captured output. */
+function normalizedSyncLines(lines: readonly string[], trim: boolean | undefined): string[] {
+  if (trim === false) return lines as string[];
+  if (trim === true) return linesFromCapturedOutput(lines.join("\n").trim());
+  return withoutSpawnTrailingEmptyLine(lines);
+}
+
+/** Format sync-captured stdout/stderr text. */
+function formatSyncCapturedText(
+  text: string | undefined,
+  trim: boolean | undefined,
+): string | undefined {
+  if (text === undefined) return undefined;
+  if (trim === false) return text;
+  if (trim === true) return text.trim();
+  return trimSingleTrailingNewline(text);
+}
+
+/**
+ * Human-readable label for a spawned command, used in error messages.
+ *
+ * @param command - Executable name or path
+ * @param args - Arguments passed to the executable
+ * @returns Backtick-wrapped `command arg1 arg2 ...` string
+ */
+function commandLabel(command: string, args: string[]): string {
+  return `\`${command} ${args.join(" ")}\``;
+}
+
+/**
+ * Build the object returned from {@link spawn} with live line arrays and lazy
+ * trimmed `stdout` / `stderr` getters derived from those lines.
+ */
+function createExecResult(
+  exitCode: number,
+  stdoutLines: string[],
+  stderrLines: string[],
+  trim: boolean | undefined,
+): ExecResult {
+  return {
+    exitCode,
+    get stdoutLines() {
+      return normalizedAsyncLines(stdoutLines, trim);
+    },
+    get stderrLines() {
+      return normalizedAsyncLines(stderrLines, trim);
+    },
+    get stdout() {
+      return formatAsyncCapturedLines(stdoutLines, trim);
+    },
+    get stderr() {
+      return formatAsyncCapturedLines(stderrLines, trim);
+    },
+  };
+}
+
+/**
+ * Build the object returned from {@link spawnSync}. Captured strings are stored
+ * as-is; `stdout` / `stderr` trim directly, and line arrays split only on read.
+ */
+function createSyncExecResult(
+  exitCode: number,
+  stdoutText: string | undefined,
+  stderrText: string | undefined,
+  trim: boolean | undefined,
+): ExecResult {
+  let stdoutLinesCache: string[] | undefined;
+  let stderrLinesCache: string[] | undefined;
+
+  const syncLines = (text: string | undefined): string[] | undefined => {
+    if (text === undefined) return undefined;
+    return normalizedSyncLines(linesFromCapturedOutput(text), trim);
+  };
+
+  return {
+    exitCode,
+    get stdoutLines() {
+      if (stdoutText === undefined) return [];
+      stdoutLinesCache ??= syncLines(stdoutText) ?? [];
+      return stdoutLinesCache;
+    },
+    get stderrLines() {
+      if (stderrText === undefined) return [];
+      stderrLinesCache ??= syncLines(stderrText) ?? [];
+      return stderrLinesCache;
+    },
+    get stdout() {
+      return formatSyncCapturedText(stdoutText, trim) ?? "";
+    },
+    get stderr() {
+      return formatSyncCapturedText(stderrText, trim) ?? "";
+    },
+  };
+}
+
+/**
+ * Extract user-supplied line handlers from a {@link StdioOption}.
+ *
+ * The `"capture"` marker is filtered out; capture itself is always handled by
+ * pushing into the line buffer inside {@link resolveStdio}.
+ *
+ * @param option - Stdio option that may embed one or more handlers
+ * @returns Handlers to invoke after each captured line (may be empty)
+ */
+function lineHandlers(option: StdioOption): LineHandler[] {
+  if (typeof option === "function") return [option];
+  if (Array.isArray(option)) {
+    return option.filter((item): item is LineHandler => item !== "capture");
+  }
+  return [];
+}
+
+/**
+ * True when a stdio option is a string spawn mode rather than capture/handlers.
+ *
+ * {@link resolveStdio} still treats `"pipe"` as pipe-and-capture; only
+ * `"inherit"` and `"ignore"` return without a line callback.
+ *
+ * @param option - Stdio option to classify
+ * @returns Whether `option` is `"inherit"`, `"pipe"`, or `"ignore"`
+ */
+function isPassthroughMode(option: StdioOption): option is ExecStdio {
+  return option === "inherit" || option === "pipe" || option === "ignore";
+}
+
+/**
+ * Map a {@link StdioOption} into a spawn stdio mode and optional line callback.
+ *
+ * Piped modes (`"capture"`, `"pipe"`, handlers, arrays) append every line to
+ * `lines` and invoke any embedded handlers. Omitted options use `defaultMode`.
+ *
+ * @param option - Caller stdio preference for one fd
+ * @param lines - Mutable buffer that receives each piped line
+ * @param defaultMode - Spawn mode when `option` is omitted (`"inherit"` by default)
+ * @returns Resolved spawn mode and optional per-line callback
+ */
+function resolveStdio(
+  option: StdioOption | undefined,
+  lines: string[],
+  defaultMode: ExecStdio = "inherit",
+): ResolvedStdio {
+  if (option === undefined) return { mode: defaultMode };
+  if (isPassthroughMode(option) && option !== "pipe") return { mode: option };
+
+  const handlers = lineHandlers(option);
+  return {
+    mode: "pipe",
+    onLine: (line) => {
+      lines.push(line);
+      for (const handler of handlers) handler(line);
+    },
+  };
+}
+
+/**
+ * Read a readable stream line-by-line and invoke `onLine` for each chunk.
+ *
+ * Uses `readline` so `\r\n` and bare `\n` are normalized. The interface is
+ * always closed in a `finally` block.
+ *
+ * @param stream - Subprocess stdout or stderr stream
+ * @param onLine - Callback invoked once per output line
+ */
+async function readLines(stream: Readable, onLine: LineHandler): Promise<void> {
+  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) onLine(line);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Start a background line read when the resolved handler pipes a stream.
+ *
+ * @param reads - Promise list awaited before returning the {@link ExecResult}
+ * @param stream - Subprocess stream for this fd (`null` when unavailable)
+ * @param handler - Resolved stdio config from {@link resolveStdio}
+ */
+function queueLineReads(
+  reads: Promise<void>[],
+  stream: Readable | null,
+  handler: ResolvedStdio,
+): void {
+  if (handler.onLine && stream) reads.push(readLines(stream, handler.onLine));
+}
+
+/**
+ * Write string stdin to a spawned process and close the stream.
+ *
+ * No-op unless `stdin` is a string and `proc.stdin` is available.
+ *
+ * @param proc - Child process returned from `spawn`
+ * @param stdin - Stdio mode or string payload from {@link ExecOptions}
+ */
+function writeStdin(proc: ChildProcess, stdin: ExecStdio | string | undefined): void {
+  if (typeof stdin === "string" && proc.stdin) {
+    proc.stdin.write(stdin);
+    proc.stdin.end();
+  }
+}
+
+/**
+ * Await process exit and normalize a missing exit code to `1`.
+ *
+ * Rejects when spawn fails before `close` (e.g. executable not found).
+ *
+ * @param proc - Child process returned from `spawn`
+ * @returns Resolved exit code
+ */
+function waitForExit(proc: ChildProcess): Promise<number> {
+  return new Promise((resolve, reject) => {
+    proc.once("error", reject);
+    proc.once("close", (code) => resolve(code ?? 1));
+  });
+}
+
+/**
+ * Build an `Error` for a non-zero exit when {@link ExecOptions.check} is set.
+ *
+ * Prefers trimmed stderr text, then stdout, in the message body.
+ *
+ * @param command - Executable name or path
+ * @param args - Arguments passed to the executable
+ * @param result - Completed exec outcome with captured output
+ * @returns Error suitable for throwing from {@link spawn}
+ */
+function execError(command: string, args: string[], result: ExecResult): Error {
+  const detail = result.stderr || result.stdout;
+  return new Error(
+    `${commandLabel(command, args)} failed (exit ${result.exitCode})${detail ? `: ${detail}` : ""}`,
+  );
+}
+
+/**
+ * Map a {@link SyncExecStdio} option to a `spawnSync` stdio mode.
+ *
+ * `"capture"` pipes the fd so output can be read into the {@link ExecResult}.
+ *
+ * @param option - Caller stdio preference for one fd
+ * @param defaultMode - Spawn mode when `option` is omitted (`"inherit"` by default)
+ * @returns Value for the `spawnSync` stdio tuple
+ */
+function resolveSyncStdio(
+  option: SyncExecStdio | undefined,
+  defaultMode: ExecStdio = "inherit",
+): ExecStdio {
+  if (option === undefined) return defaultMode;
+  if (option === "capture") return "pipe";
+  return option;
+}
+
+/**
+ * Normalize raw `spawnSync` output to a UTF-8 string when capture is enabled.
+ */
+function capturedText(output: string | Buffer | null | undefined): string | undefined {
+  if (output === null || output === undefined) return undefined;
+  return typeof output === "string" ? output : output.toString("utf8");
+}
+
+/**
+ * Split captured process output into lines for {@link ExecResult.stdoutLines} /
+ * {@link ExecResult.stderrLines} ({@link spawnSync} only; invoked lazily).
+ */
+function linesFromCapturedOutput(output: string): string[] {
+  return output.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+}
+
+/**
+ * Spawn a subprocess and wait for exit.
+ *
+ * @param command - Executable to run (resolved on `PATH` when `shell` is set on options)
+ * @param args - Arguments passed verbatim to the executable
+ * @param options - Spawn, stdio, and check options
+ * @returns Exit code, captured line arrays, and trimmed `stdout` / `stderr` getters
+ * @throws When spawn fails, line reads fail, or `check` is true and exit code is non-zero
+ */
+export async function spawn(
+  ...args: SpawnArgs<ExecOptions>
+): Promise<ExecResult> {
+  const { command, commandArgs, options = {} } = parseSpawnArgs(args);
+  const { stdin, stdout, stderr, check, trim, ...spawnOpts } = options
+  const stdoutLines: string[] = [];
+  const stderrLines: string[] = [];
+  const stdoutHandler = resolveStdio(stdout, stdoutLines);
+  const stderrHandler = resolveStdio(stderr, stderrLines);
+  const stdinMode: ExecStdio = typeof stdin === "string" ? "pipe" : (stdin ?? "inherit");
+
+  const proc = nodeSpawn(command, commandArgs, {
+    ...spawnOpts,
+    stdio: [stdinMode, stdoutHandler.mode, stderrHandler.mode],
+  });
+
+  writeStdin(proc, stdin);
+
+  const reads: Promise<void>[] = [];
+  queueLineReads(reads, proc.stdout, stdoutHandler);
+  queueLineReads(reads, proc.stderr, stderrHandler);
+
+  let exitCode = 1;
+  try {
+    exitCode = await waitForExit(proc);
+    await Promise.all(reads);
+  } catch (err) {
+    await Promise.allSettled(reads);
+    throw err;
+  }
+
+  const result = createExecResult(exitCode, stdoutLines, stderrLines, trim);
+  if (check && result.exitCode !== 0) throw execError(command, commandArgs, result);
+  return result;
+}
+
+/**
+ * Spawn a subprocess synchronously and wait for exit.
+ *
+ * Unlike {@link spawn}, stdio options are limited to `"inherit"`, `"pipe"`,
+ * `"ignore"`, and `"capture"` — no per-line callbacks.
+ *
+ * @param command - Executable to run (resolved on `PATH` when `shell` is set on options)
+ * @param args - Arguments passed verbatim to the executable
+ * @param spawnSync - Spawn, stdio, and check options
+ * @returns Exit code, captured line arrays, and trimmed `stdout` / `stderr` getters
+ * @throws When spawn fails or `check` is true and exit code is non-zero
+ */
+export function spawnSync(
+  ...args: SpawnArgs<SyncExecOptions>
+): ExecResult {
+  const { command, commandArgs, options = {} } = parseSpawnArgs(args);
+  const { stdin, stdout, stderr, check, trim, ...spawnOpts } = options;
+  const stdinMode: ExecStdio = typeof stdin === "string" ? "pipe" : (stdin ?? "inherit");
+  const captureStdout = stdout === "capture";
+  const captureStderr = stderr === "capture";
+  const stdoutMode = resolveSyncStdio(stdout);
+  const stderrMode = resolveSyncStdio(stderr);
+
+  const result = nodeSpawnSync(command, commandArgs, {
+    ...spawnOpts,
+    encoding: captureStdout || captureStderr ? "utf8" : undefined,
+    stdio: [stdinMode, stdoutMode, stderrMode],
+    input: typeof stdin === "string" ? stdin : undefined,
+  });
+
+  const exitCode = result.status ?? 1;
+  const stdoutText = captureStdout ? capturedText(result.stdout) : undefined;
+  const stderrText = captureStderr ? capturedText(result.stderr) : undefined;
+  const execResult = createSyncExecResult(exitCode, stdoutText, stderrText, trim);
+
+  if (result.error) {
+    if (check || execResult.exitCode !== 0) {
+      const err = execError(command, commandArgs, execResult);
+      err.cause = result.error;
+      throw err;
+    }
+  }
+
+  if (check && execResult.exitCode !== 0) throw execError(command, commandArgs, execResult);
+  return execResult;
+}
+
+/**
+ * Splits a shell-like command into argv.
+ *
+ * Supports:
+ *   - whitespace separators
+ *   - single and double quotes
+ *   - backslash escaping
+ *   - escaped spaces
+ *   - empty quoted strings
+ *
+ * If the input is malformed (for example, an unterminated quote),
+ * returns the original string as a single argument.
+ */
+export function shlex(command: string): string[] {
+  const args: string[] = [];
+
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  let escaped = false;
+  let quoted = false;
+
+  const push = () => {
+    if (quoted || current.length > 0) {
+      args.push(current);
+    }
+    current = "";
+    quoted = false;
+  };
+
+  for (const ch of command) {
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+
+    if (quote) {
+      if (ch === quote) {
+        quote = undefined;
+        quoted = true;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      quoted = true;
+      continue;
+    }
+
+    if (/\s/.test(ch)) {
+      push();
+      continue;
+    }
+
+    current += ch;
+  }
+
+  // Malformed input: treat as a literal command.
+  if (quote) {
+    return [command];
+  }
+
+  // Trailing backslash is literal.
+  if (escaped) {
+    current += "\\";
+  }
+
+  push();
+
+  return args.length ? args : [command];
+}

package/src/project.ts

@@ -0,0 +1,214 @@
+import { spawnSync } from "node:child_process";
+import { Stats, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+const ROOT_MARKERS = [
+  ".projenrc.ts",
+  ".projenrc.js",
+  ".projenrc.mjs",
+  ".projenrc.cjs",
+  "package.json",
+] as const;
+
+function statPath(path: string): Stats | undefined {
+  if (path) {
+    try {
+      return statSync(path);
+    } catch {}
+  }
+  return undefined;
+}
+
+/**
+ * because this is crucial do not use exec.spawnSync
+ */
+function directoryCommand(command: string, args: string[], cwd: string): string | undefined {
+  const result = spawnSync(command, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+  if (result.status === 0) {
+    const output = result.stdout.toString().trim();
+    return statPath(output)?.isDirectory() ? output : undefined;
+  }
+  return undefined;
+}
+
+const rootDirectoryCommands: Record<string, [string, string[]]> = {
+  npm: ["npm", ["prefix"]] as const,
+  git: ["git", ["rev-parse", "--show-toplevel"]] as const,
+} as const;
+
+const rootDirectoryDefaultCache = new Map<
+  keyof typeof rootDirectoryCommands,
+  { cwd: string; path?: string }
+>();
+
+function rootDirectory(name: keyof typeof rootDirectoryCommands, cwd?: string): string | undefined {
+  const [command, args] = rootDirectoryCommands[name];
+  let cache: boolean;
+  if (cwd === undefined) {
+    cwd = process.cwd();
+    cache = true;
+  } else {
+    cache = cwd === process.cwd();
+  }
+  if (cache) {
+    const cached = rootDirectoryDefaultCache.get(name);
+    if (cached?.cwd === cwd) {
+      return cached!.path;
+    }
+  }
+  const path = directoryCommand(command, args, cwd);
+  if (cache) {
+    rootDirectoryDefaultCache.set(name, { cwd, path });
+  }
+  return path;
+}
+function npmRoot(cwd?: string): string | undefined {
+  return rootDirectory("npm", cwd);
+}
+
+function gitRoot(cwd?: string): string | undefined {
+  return rootDirectory("git", cwd);
+}
+
+export function root(cwd: string = process.cwd()): string | undefined {
+  let current = resolve(cwd);
+
+  if (!statPath(current)?.isDirectory()) {
+    current = dirname(current);
+  }
+  const boundaries = new Set(
+    [npmRoot(cwd), gitRoot(cwd)]
+      .filter((path): path is string => path !== undefined)
+      .map((path) => resolve(path)),
+  );
+  const hasBoundary = boundaries.size > 0;
+  let best: { dir: string; priority: number } | undefined;
+  while (true) {
+    for (const [priority, marker] of ROOT_MARKERS.entries()) {
+      if (statPath(join(current, marker))?.isFile()) {
+        if (
+          best === undefined ||
+          priority < best.priority ||
+          (priority === best.priority && current.length < best.dir.length)
+        ) {
+          best = { dir: current, priority };
+        }
+        break;
+      }
+    }
+    if (!hasBoundary && best) {
+      return best.dir;
+    }
+    if (boundaries.has(current)) {
+      return best?.dir;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return best?.dir;
+    }
+    current = parent;
+  }
+}
+
+/** Best-effort `fs.stat` (sync). Returns `undefined` when `path` can't be stat'd. */
+export function stat(path: string): Stats | undefined {
+  return statPath(path);
+}
+
+/**
+ * Parse a git remote URL (`https://...`, `git@host:owner/repo.git`, etc.) and
+ * return the repo segment, stripping any `.git` suffix. Returns `undefined` for
+ * empty or unparsable input.
+ */
+export function parseGitRemote(url: string): string | undefined {
+  const trimmed = url.trim();
+  if (!trimmed) return undefined;
+
+  const scp = /^[^@]+@[^:]+:(.+)$/i.exec(trimmed);
+  if (scp) return lastPathSegment(scp[1] ?? "");
+
+  try {
+    const normalized = trimmed.replace(/\.git$/i, "");
+    const pathname = new URL(normalized).pathname;
+    const segment = pathname.split("/").filter(Boolean).at(-1);
+    return segment ? lastPathSegment(segment) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function lastPathSegment(path: string): string {
+  const segment = path.split("/").filter(Boolean).at(-1) ?? path;
+  return segment.replace(/\.git$/i, "");
+}
+
+/**
+ * Yield candidate project-root directories for `cwd`, in priority order: the
+ * `npm prefix`, the git top-level, then `cwd` itself. Duplicates are skipped;
+ * only existing directories are yielded (except the final `cwd` fallback).
+ */
+export function* resolveProjectRoots(cwd: string = process.cwd()): Generator<string> {
+  const base = resolve(cwd);
+  const seen = new Set<string>();
+  for (const candidate of [npmRoot(base), gitRoot(base)]) {
+    if (!candidate) continue;
+    const dir = resolve(candidate);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    if (statPath(dir)?.isDirectory()) yield dir;
+  }
+  if (!seen.has(base)) yield base;
+}
+
+/** The nearest ancestor of `cwd` (from {@link resolveProjectRoots}) with a `package.json`. */
+function workspaceRoot(cwd: string = process.cwd()): string {
+  let last: string | undefined;
+  for (const dir of resolveProjectRoots(cwd)) {
+    if (statPath(resolve(dir, "package.json"))?.isFile()) return dir;
+    last = dir;
+  }
+  return last ?? resolve(cwd);
+}
+
+/**
+ * Resolve a human-friendly project name for the repo rooted at `cwd`:
+ * `package.json` `name`, then the git remote's repo name, then the root
+ * directory's basename.
+ */
+export function name(cwd: string = process.cwd()): string {
+  const rootDir = workspaceRoot(cwd);
+
+  const fromPackage = readPackageName(resolve(rootDir, "package.json"));
+  if (fromPackage) return fromPackage;
+
+  const remote = commandOutput("git", ["-C", rootDir, "remote", "get-url", "origin"], rootDir);
+  const fromGit = remote ? parseGitRemote(remote) : undefined;
+  if (fromGit) return fromGit;
+
+  return basename(rootDir);
+}
+
+/** Trimmed stdout of a command, or `undefined` when it fails or prints nothing. */
+function commandOutput(command: string, args: string[], cwd: string): string | undefined {
+  const result = spawnSync(command, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+  if (result.status !== 0) return undefined;
+  return result.stdout.toString().trim() || undefined;
+}
+
+function readPackageName(pkgPath: string): string | undefined {
+  if (!statPath(pkgPath)?.isFile()) return undefined;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+    return pkg.name?.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+if (import.meta.main) {
+  console.log("npm root:", npmRoot());
+  console.log("repo root:", gitRoot());
+  console.log("package root:", root());
+  console.log("project name:", name());
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}