@osdlc/typed-gh 0.9.5 → 0.9.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @osdlc/typed-gh
 
+## 0.9.6
+
+### Patch Changes
+
+- 3d6d087: Document that a `Repository`'s `owner` and `name`, and a `PrSearchHit`'s `repository`, come back in GitHub's casing, not as the caller wrote them. The `Repository` and `PrSearchHit` type docs, the `repoList` and `repoView` doc comments and the README say so.
+- f013f38: The default runners now find `git` and `gh` on absolute `PATH` entries only, and spawn the absolute path found. Before, a bare `git` or `gh` was spawned by name with the child's `cwd` set to the checkout, so a file of that name in the checkout could run in place of the real binary: on Windows, where a bare name is searched in `cwd` first, and on every platform through a relative or empty `PATH` entry. A binary that is not found on an absolute entry fails as a missing binary (`not-installed`). typed-gh's `defaultRunnerFactory` does the same lookup. An injected runner is unchanged.
+- Updated dependencies [f013f38]
+- Updated dependencies [f013f38]
+  - @osdlc/command-seam@0.12.1
+  - @osdlc/typed-git@0.8.2
+
 ## 0.9.5
 
 ### Patch Changes

package/README.md

@@ -384,7 +384,8 @@ The awaitable form of `Gh`, with the same methods, for code that runs many calls
 not block the event loop. It has the same three call styles, as Promises. The plain method rejects
 with the classified failure. `try` resolves to a `Result<T, GhFailure>`. `soft` resolves `null` for
 a failed query. `raw` and `rawChecked` run any `gh` call. Both clients use the same verb table, so
-they cannot drift apart. It takes an `AsyncCommandRunner` and defaults to `spawnRunnerAsync("gh")`.
+they cannot drift apart. It takes an `AsyncCommandRunner` and defaults to
+`spawnRunnerAsync("gh", { absolutePathOnly: true })`.
 
 ```ts
 import { AsyncGh } from '@osdlc/typed-gh'
@@ -450,9 +451,14 @@ const hits: ListResult<PrSearchHit> = gh.searchPrs('TICKET-123', { owner: 'acme'
 ```
 
 A `Repository` carries `nameWithOwner`, `owner`, `name`, `description`, `defaultBranch`,
-`visibility`, `isArchived` and `url`. `gh search prs` has its own field set. A `PrSearchHit` names
-its `repository` but has no head or base branch, so it is not a `PullRequest`. Its `state` is
-upper-cased to match. The query takes GitHub's search syntax and may start with `-`.
+`visibility`, `isArchived` and `url`. `owner` and `name` are cut from `nameWithOwner`, so they
+come back in GitHub's casing, not as you wrote them: `repoList('ACME')` gives `owner: 'acme'` when
+the account is `acme`, and `repoView` works the same way. To build paths that match your own
+config, use your own value.
+
+`gh search prs` has its own field set. A `PrSearchHit` names its `repository`, also in GitHub's
+casing, but has no head or base branch, so it is not a `PullRequest`. Its `state` is upper-cased to
+match. The query takes GitHub's search syntax and may start with `-`.
 
 ## Passing your own runner
 
@@ -469,7 +475,9 @@ new Gh('/repo', { runner: empty }).prList() // { rows: [], truncated: false }
 This package re-exports `CommandFailed` and the runner and result types (`CommandRunner`,
 `AsyncCommandRunner`, `CommandResult`, `CommandRunOptions`), since they appear in its signatures.
 Import the runners themselves, such as `spawnRunner` and `spawnRunnerAsync`, from
-`@osdlc/command-seam`.
+`@osdlc/command-seam`. The default runners find `gh` on absolute `PATH` entries only, so a file
+named `gh` in the working directory cannot run in its place. Pass `{ absolutePathOnly: true }` when
+you build a real runner yourself.
 
 ## API
 

package/dist/async.d.ts

@@ -106,9 +106,15 @@ export declare class AsyncGh {
     issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<ListResult<IssueRow>>;
     /** One issue with its labels, or null when there is no such issue. */
     issueView(number: number, opts?: AsyncCallOptions): Promise<IssueRow | null>;
-    /** An owner's repositories. Rejects when gh fails. See `Gh.repoList`. */
+    /**
+     * An owner's repositories. Rejects when gh fails. Each row's `owner` is in
+     * GitHub's casing, not as passed. See `Gh.repoList`.
+     */
     repoList(owner: string, opts?: v.RepoListOptions & AsyncCallOptions): Promise<ListResult<Repository>>;
-    /** One repository, or null when there is no such repository. See `Gh.repoView`. */
+    /**
+     * One repository, or null when there is no such repository. `owner` and
+     * `name` are in GitHub's casing, not as passed. See `Gh.repoView`.
+     */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<Repository | null>;

package/dist/async.js

@@ -10,7 +10,7 @@
  * two cannot differ on argv or parsing. Use it where the sync client would
  * block the event loop, such as many per-PR queries at once.
  */
-import { resolveRunnerAsync, } from '@osdlc/command-seam';
+import { spawnRunnerAsync } from '@osdlc/command-seam';
 import { runCheckedGhAsync, softAsync, triedAsync } from "./doors.js";
 import { runVerbAsync } from "./run.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
@@ -35,7 +35,7 @@ export class AsyncGh {
         this.repo = opts.repo;
         this.hostname = opts.hostname;
         this.target = { repo: opts.repo, hostname: opts.hostname };
-        this.runner = resolveRunnerAsync('gh', opts.runner);
+        this.runner = opts.runner ?? spawnRunnerAsync('gh', { absolutePathOnly: true });
     }
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
@@ -154,11 +154,17 @@ export class AsyncGh {
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts);
     }
-    /** An owner's repositories. Rejects when gh fails. See `Gh.repoList`. */
+    /**
+     * An owner's repositories. Rejects when gh fails. Each row's `owner` is in
+     * GitHub's casing, not as passed. See `Gh.repoList`.
+     */
     repoList(owner, opts = {}) {
         return this.read(v.repoList(owner, opts, this.target), opts);
     }
-    /** One repository, or null when there is no such repository. See `Gh.repoView`. */
+    /**
+     * One repository, or null when there is no such repository. `owner` and
+     * `name` are in GitHub's casing, not as passed. See `Gh.repoView`.
+     */
     repoView(repo, opts = {}) {
         return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts);
     }

package/dist/sync.d.ts

@@ -22,11 +22,15 @@ import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, L
 import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
  * Makes a runner for a binary. A CLI passes one factory to every place that
- * runs a command. Real code uses `spawnRunner`. Tests pass a factory that
- * records calls, so the CLI runs offline.
+ * runs a command. Real code uses {@link defaultRunnerFactory}. Tests pass a
+ * factory that records calls, so the CLI runs offline.
  */
 export type RunnerFactory = (binary: string) => CommandRunner;
-/** The default factory: real runners that use `spawnSync`. */
+/**
+ * The default factory: real runners that use `spawnSync`. A bare name is
+ * found on absolute `PATH` entries only, so a file of that name in the
+ * working directory cannot run in its place.
+ */
 export declare const defaultRunnerFactory: RunnerFactory;
 /** What a client is built with: the runner, and the repository and host it talks to. */
 export interface GhOptions extends GhTarget {
@@ -178,11 +182,18 @@ export declare class Gh {
     issueView(number: number, opts?: {
         timeoutMs?: number | undefined;
     }): IssueRow | null;
-    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
+    /**
+     * An owner's repositories (up to `opts.limit`, default 100). Throws when gh
+     * fails. Each row's `owner` is in GitHub's casing, not as passed.
+     */
     repoList(owner: string, opts?: v.RepoListOptions & {
         timeoutMs?: number | undefined;
     }): ListResult<Repository>;
-    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when there is no such repository. */
+    /**
+     * One repository: `repo`, else the client's repo, else the clone at `cwd`.
+     * Null when there is no such repository. `owner` and `name` are in
+     * GitHub's casing, not as passed.
+     */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
         timeoutMs?: number | undefined;

package/dist/sync.js

@@ -15,13 +15,17 @@
  * the failure as a `Result<T, GhFailure>`. `gh.soft.*` returns `null` for it.
  * `raw` and `rawChecked` run any `gh` call.
  */
-import { resolveRunner, spawnRunner, } from '@osdlc/command-seam';
+import { spawnRunner } from '@osdlc/command-seam';
 import { runCheckedGh, softSync, triedSync } from "./doors.js";
 import { runVerb } from "./run.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
-/** The default factory: real runners that use `spawnSync`. */
-export const defaultRunnerFactory = spawnRunner;
+/**
+ * The default factory: real runners that use `spawnSync`. A bare name is
+ * found on absolute `PATH` entries only, so a file of that name in the
+ * working directory cannot run in its place.
+ */
+export const defaultRunnerFactory = (binary) => spawnRunner(binary, { absolutePathOnly: true });
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
 /**
@@ -52,7 +56,7 @@ export class Gh {
         this.repo = opts.repo;
         this.hostname = opts.hostname;
         this.target = { repo: opts.repo, hostname: opts.hostname };
-        this.runner = resolveRunner('gh', opts.runner);
+        this.runner = opts.runner ?? defaultRunnerFactory('gh');
     }
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
@@ -210,11 +214,18 @@ export class Gh {
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts.timeoutMs);
     }
-    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
+    /**
+     * An owner's repositories (up to `opts.limit`, default 100). Throws when gh
+     * fails. Each row's `owner` is in GitHub's casing, not as passed.
+     */
     repoList(owner, opts = {}) {
         return this.read(v.repoList(owner, opts, this.target), opts.timeoutMs);
     }
-    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when there is no such repository. */
+    /**
+     * One repository: `repo`, else the client's repo, else the clone at `cwd`.
+     * Null when there is no such repository. `owner` and `name` are in
+     * GitHub's casing, not as passed.
+     */
     repoView(repo, opts = {}) {
         return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts.timeoutMs);
     }

package/dist/types.d.ts

@@ -156,9 +156,14 @@ export type RepositoryVisibility = 'PUBLIC' | 'PRIVATE' | 'INTERNAL' | (string &
  * without one: a row without it is dropped.
  */
 export interface Repository {
-    /** `owner/name`. */
+    /** `owner/name`, in GitHub's casing. */
     nameWithOwner: string;
+    /**
+     * Cut from `nameWithOwner`, so in GitHub's casing, not as the caller wrote
+     * it: `repoList('ACME')` gives `owner: 'acme'` when the account is `acme`.
+     */
     owner: string;
+    /** Cut from `nameWithOwner`, so in GitHub's casing. */
     name: string;
     description: string;
     /** The default branch. Null when not asked for, or when the repository is empty. */
@@ -178,6 +183,7 @@ export interface PrSearchHit {
     state: PullRequestState;
     url: string;
     isDraft: boolean;
+    /** Cut from the hit's `nameWithOwner`, so in GitHub's casing. */
     repository: OwnerRepo | null;
     author: Actor | null;
     labels: Label[];

package/dist/verbs.d.ts

@@ -284,12 +284,15 @@ export interface RepoListOptions {
 }
 /**
  * `gh repo list <owner> --json …`: an owner's repositories. The host comes
- * from the target (`GH_HOST`). The target's repo is not used.
+ * from the target (`GH_HOST`). The target's repo is not used. Each row's
+ * `owner` is in GitHub's casing, not as passed. To build paths that match
+ * your config, use your own value.
  */
 export declare function repoList(owner: string, opts?: RepoListOptions, target?: GhTarget): GhVerb<ListResult<Repository> | null>;
 /**
  * `gh repo view [<[host/]owner/name>] --json …`: one repository. That is `repo`,
- * else the target's repo, else the clone at the client's cwd.
+ * else the target's repo, else the clone at the client's cwd. The result's
+ * `owner` and `name` are in GitHub's casing, not as passed.
  */
 export declare function repoView(repo?: string | undefined, fields?: readonly string[], target?: GhTarget): GhVerb<Repository | null>;
 /** What to narrow a pull request search to. Every filter is optional. */

package/dist/verbs.js

@@ -657,7 +657,9 @@ function rowsOrNull(r, parse) {
 }
 /**
  * `gh repo list <owner> --json …`: an owner's repositories. The host comes
- * from the target (`GH_HOST`). The target's repo is not used.
+ * from the target (`GH_HOST`). The target's repo is not used. Each row's
+ * `owner` is in GitHub's casing, not as passed. To build paths that match
+ * your config, use your own value.
  */
 export function repoList(owner, opts = {}, target) {
     notAFlag('repoList owner', owner);
@@ -682,7 +684,8 @@ export function repoList(owner, opts = {}, target) {
 }
 /**
  * `gh repo view [<[host/]owner/name>] --json …`: one repository. That is `repo`,
- * else the target's repo, else the clone at the client's cwd.
+ * else the target's repo, else the clone at the client's cwd. The result's
+ * `owner` and `name` are in GitHub's casing, not as passed.
  */
 export function repoView(repo, fields = REPO_FIELDS, target) {
     checkTarget(target);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "A typed GitHub client for TypeScript over the gh CLI. A total PullRequest/Review/CheckRun model, pure argv builders and parsers, and a tri-modal client — queries return parsed values, mutations throw, raw() is the escape hatch. Uses gh's own credentials; reads no token.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",
@@ -22,9 +22,9 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.12.0",
-    "@osdlc/typed-git": "^0.8.1",
-    "@osdlc/result": "^0.1.0"
+    "@osdlc/command-seam": "^0.12.1",
+    "@osdlc/result": "^0.1.0",
+    "@osdlc/typed-git": "^0.8.2"
   },
   "engines": {
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"