aicodeman 1.34.0 → 1.40.0

package/dist/git-workspace-status.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview "What has this session's workspace not committed or pushed?": a read-only git
+ * snapshot of a session's working directory, for the bottom-bar Git indicator and its panel
+ * (`GET /api/sessions/:id/git-status`). Agents leave work uncommitted and unpushed; this makes that
+ * visible without leaving Codeman.
+ *
+ * Split so the parts that matter test without a repo:
+ *   - pure: `parsePorcelainV2` (status output → branch, upstream, ahead/behind, per-file entries),
+ *     `parseCommitLog`
+ *   - IO: `getGitWorkspaceStatus` (a handful of async, bounded, read-only `git` calls), with a short
+ *     single-flight cache so several tabs polling one repo cost one set of git processes
+ *
+ * WHICH repositories. `getGitWorkspaceOverview` answers for the session's working directory:
+ *   - inside a repository (or at its root): that one repository. git finds it by walking UP, so a
+ *     subfolder reports its whole enclosing repo; a nested repo below it is just an untracked folder
+ *     to the outer one, and is not scanned;
+ *   - NOT inside one (a folder that holds several projects): every repository found up to two levels
+ *     DOWN (the caller's `maxRepos` of them, `MAX_REPOS` by default, skipping dot-folders, `node_modules`
+ *     and the like, never following symlinks), each reported separately;
+ *   - a repository that merely sits ABOVE the workspace and is the home folder or higher (a dotfiles
+ *     repo in `$HOME`, or `/`) is ignored: its dirty files are not this session's work.
+ *
+ * Rules the code keeps and the tests pin:
+ *   - READ-ONLY and OFFLINE. It never fetches, pulls, commits or writes. "Behind" therefore reflects
+ *     the last fetch (the UI says so); "ahead" and the unpushed list are exact against the
+ *     remote-tracking refs already on disk. `--no-optional-locks` keeps `git status` from even
+ *     refreshing the index, so polling cannot contend with the agent's own git commands.
+ *   - Every call is async (`execFile`), bounded by a timeout, and never interpolates a path into a
+ *     shell: the working directory is the process `cwd`, and the only operand-like input is a fixed
+ *     revision range.
+ *   - Output is capped: the counts are exact, the lists are not (`filesTruncated`).
+ *   - git can run helpers a repository configures: a clean filter (`filter.<name>.clean`) still runs
+ *     during `git status` and `git diff`, as it does for any `git status`. A LOCAL session already
+ *     runs as this same OS user, so polling adds no privilege there. What is turned off: the
+ *     filesystem monitor (`core.fsmonitor`), external diff and textconv drivers, and the signature
+ *     program (`log.showSignature`). A repository a container can write to is NOT inspected: a
+ *     Docker session answers `unsupported`, and any repository whose root is, or is inside, a Docker
+ *     case workspace is dropped from the walk-up, the scan below a folder, and the diff route, because
+ *     the container could have planted that config and git here would run it on the host.
+ *   - Remote URLs and git's stderr can embed `user:token@host`; anything that reaches a client goes
+ *     through `redactGitCredentials`.
+ *
+ * @module git-workspace-status
+ */
+/** How long one git command may run, unless the caller passes `timeoutMs` (a slow network share needs more). */
+export declare const DEFAULT_GIT_TIMEOUT_MS = 30000;
+export declare const MIN_GIT_TIMEOUT_MS = 5000;
+export declare const MAX_GIT_TIMEOUT_MS = 120000;
+/** Max file rows returned. The counts stay exact. */
+export declare const MAX_FILES = 300;
+/** Max unpushed commits listed. The count stays exact. */
+export declare const MAX_COMMITS = 50;
+export type GitFileKind = 'staged' | 'unstaged' | 'untracked' | 'conflicted';
+export interface GitFileEntry {
+    /** Path relative to the repository root, as git reports it. */
+    path: string;
+    /** Rename/copy source, when the entry is one. */
+    origPath?: string;
+    /** Status letter in the index (`M`, `A`, `D`, `R`, `C`, `T`, `.`). */
+    index: string;
+    /** Status letter in the working tree (`M`, `D`, `T`, `.`, ...). `?` for untracked. */
+    worktree: string;
+    kind: GitFileKind;
+}
+export interface GitCommitEntry {
+    hash: string;
+    author: string;
+    /** Seconds since the epoch. */
+    time: number;
+    subject: string;
+}
+export interface GitWorkspaceStatus {
+    /**
+     * `ok`: a repository, the rest of the fields are meaningful. `not-a-repo`: nothing to show.
+     * `unsupported`: a remote or Docker session (never inspected). `error`: git failed; see `error`.
+     */
+    state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
+    reason?: 'remote' | 'docker';
+    error?: string;
+    repoRoot?: string;
+    /** Null when HEAD is detached. */
+    branch: string | null;
+    detached: boolean;
+    upstream: string | null;
+    /**
+     * The configured upstream does not exist on the remote (deleted and pruned, or never pushed, as after
+     * cloning an empty repository and committing): nothing is tracked.
+     */
+    upstreamGone: boolean;
+    ahead: number;
+    /** Behind the remote-tracking ref as of the LAST FETCH; this module never fetches. */
+    behind: number;
+    /** Whether the repository has any remote at all. */
+    hasRemote: boolean;
+    counts: {
+        staged: number;
+        unstaged: number;
+        untracked: number;
+        conflicted: number;
+        /** Distinct paths that are not committed. */
+        uncommitted: number;
+        stashes: number;
+    };
+    files: GitFileEntry[];
+    filesTruncated: boolean;
+    /** Commits on this branch that no remote has: exact. */
+    unpushedCount: number;
+    unpushed: GitCommitEntry[];
+    checkedAt: number;
+}
+export declare const emptyStatus: (state: GitWorkspaceStatus["state"], extra?: Partial<GitWorkspaceStatus>) => GitWorkspaceStatus;
+export interface ParsedStatus {
+    branch: string | null;
+    detached: boolean;
+    upstream: string | null;
+    /** `# branch.upstream` was printed but `# branch.ab` was not: no such remote branch (deleted and pruned, or never pushed). */
+    upstreamGone: boolean;
+    ahead: number;
+    behind: number;
+    files: GitFileEntry[];
+}
+/**
+ * Parse `git status --porcelain=v2 --branch -z`. Entries are NUL-separated and paths are NOT quoted,
+ * so a name with spaces, quotes or a newline arrives intact. A rename/copy (`2 ...`) is followed by
+ * one more NUL-terminated token holding the original path.
+ */
+export declare function parsePorcelainV2(text: string): ParsedStatus;
+/** Parse `git log --format=%h%x1f%an%x1f%ct%x1f%s%x1e`. */
+export declare function parseCommitLog(text: string): GitCommitEntry[];
+/** Runs `git <args>` in `cwd` and returns stdout. Injected so the cache and error paths test without git. */
+export type GitRunner = (cwd: string, args: string[], opts?: {
+    timeoutMs?: number;
+}) => Promise<string>;
+export declare const runGit: GitRunner;
+/** For tests. */
+export declare function clearGitStatusCache(): void;
+/**
+ * The git snapshot of `cwd`. Concurrent callers share one in-flight computation, and a result younger
+ * than a few seconds is reused, so several tabs polling one repo cost one set of git processes.
+ * `fresh` skips the reuse but still joins a computation already running (see `singleFlight`).
+ */
+export declare function getGitWorkspaceStatus(cwd: string, opts?: {
+    git?: GitRunner;
+    now?: () => number;
+    fresh?: boolean;
+    timeoutMs?: number;
+}): Promise<GitWorkspaceStatus>;
+/** Repositories reported for one workspace. */
+export declare const MAX_REPOS = 12;
+/** The most repositories a caller may ask for: each one costs several git processes per poll. */
+export declare const MAX_REPOS_LIMIT = 50;
+/** `value` as a whole number within [min, max], else `fallback`. For options that arrive as untrusted query strings. */
+export declare function clampInt(value: unknown, min: number, max: number, fallback: number): number;
+export interface GitRepoEntry {
+    /** Folder name of the repository (its root's basename). */
+    name: string;
+    /** The repository root relative to the working directory: `.`, `..`, `api`, `apps/web`. */
+    path: string;
+    status: GitWorkspaceStatus;
+}
+export interface GitWorkspaceOverview {
+    /** `ok` when at least one repository was found; the other states are as in `GitWorkspaceStatus`. */
+    state: 'ok' | 'not-a-repo' | 'unsupported' | 'error';
+    reason?: 'remote' | 'docker';
+    error?: string;
+    repos: GitRepoEntry[];
+    /** More than `repoLimit` repositories were found; only the first are reported. */
+    reposTruncated: boolean;
+    /** The most repositories this overview would list (the caller's setting, or `MAX_REPOS`). */
+    repoLimit?: number;
+    checkedAt: number;
+}
+export declare const emptyOverview: (state: GitWorkspaceOverview["state"], extra?: Partial<GitWorkspaceOverview>) => GitWorkspaceOverview;
+/**
+ * True when `path` is, or is inside, any of the (already real) `roots`. Used for Docker case
+ * workspaces: a container can write there, so git must not run on its behalf on the host.
+ */
+export declare function isInsideAny(path: string, realRoots: string[]): Promise<boolean>;
+/**
+ * True when `repoRoot` is a repository that merely contains the workspace and is the home folder or
+ * above it (`$HOME` managed as a dotfiles repo, `/`, `/home`): its changes are not the session's work.
+ * A workspace that IS the repository root is never "unrelated", even when that root is the home folder.
+ */
+export declare function isUnrelatedAncestor(repoRoot: string, cwd: string, home: string): Promise<boolean>;
+/** Repositories up to `DISCOVERY_MAX_DEPTH` levels below `cwd`, nearest and alphabetical first. Never follows symlinks. */
+export declare function discoverChildRepos(cwd: string, excludeRealRoots?: string[], maxRepos?: number): Promise<{
+    dirs: string[];
+    truncated: boolean;
+}>;
+export interface GitOverviewOptions {
+    git?: GitRunner;
+    now?: () => number;
+    fresh?: boolean;
+    home?: string;
+    /** Docker case workspaces (host paths): repositories at or inside these are never inspected. */
+    dockerWorkspaces?: string[];
+    /** How many repositories to report below a folder that is not itself a repository (1 to `MAX_REPOS_LIMIT`, default `MAX_REPOS`). */
+    maxRepos?: number;
+    /** How long one git command may run, in ms (`MIN_GIT_TIMEOUT_MS` to `MAX_GIT_TIMEOUT_MS`, default `DEFAULT_GIT_TIMEOUT_MS`). */
+    timeoutMs?: number;
+}
+/** The repository limit and git timeout an overview was computed with, from untrusted options. */
+export declare function resolveOverviewLimits(opts: {
+    maxRepos?: unknown;
+    timeoutMs?: unknown;
+}): {
+    maxRepos: number;
+    timeoutMs: number;
+};
+/**
+ * Everything git knows about the session's workspace: the enclosing repository when there is one,
+ * otherwise each repository found below the working directory. See the module header for the rules.
+ */
+export declare function getGitWorkspaceOverview(cwd: string, opts?: GitOverviewOptions): Promise<GitWorkspaceOverview>;
+/**
+ * `repo` when it is the root of one of the repositories the overview reports for `cwd` (the same rules
+ * and caches, and the Docker roots as they are now), else null. The diff route checks a requested
+ * repository with this rather than recomputing every repository's status.
+ */
+export declare function findWorkspaceRepo(cwd: string, repo: string, opts?: GitOverviewOptions): Promise<string | null>;
+/** Longest diff handed to the browser; beyond this it is cut at a line boundary and flagged. */
+export declare const MAX_DIFF_BYTES: number;
+export interface GitFileDiff {
+    /** Unified diff text (empty when git reports no textual change, e.g. a mode-only edit shows its header). */
+    diff: string;
+    truncated: boolean;
+    binary: boolean;
+}
+/** A repo-relative path git reported, minus anything that could escape the repo. (A leading `-` is fine: every operand follows `--`.) */
+export declare function isSafeRepoRelativePath(p: string): boolean;
+/**
+ * The diff of one changed file, as the panel's rows describe it: `staged` is index vs HEAD,
+ * `unstaged`/`conflicted` is working tree vs index (a conflict shows git's combined diff), and
+ * `untracked` is the whole file as additions. Read-only. `--no-ext-diff --no-textconv` stop the external
+ * diff and textconv drivers a repository configures; a clean filter still runs, as it does for any
+ * `git diff`, which is why a container-writable repository never reaches this function.
+ */
+export declare function getGitFileDiff(repoRoot: string, file: {
+    path: string;
+    origPath?: string;
+    kind: GitFileKind;
+}, opts?: {
+    git?: GitRunner;
+    timeoutMs?: number;
+}): Promise<GitFileDiff>;
+//# sourceMappingURL=git-workspace-status.d.ts.map

package/dist/git-workspace-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-workspace-status.d.ts","sourceRoot":"","sources":["../src/git-workspace-status.ts"],"names":[],"mappings":"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"}