@yukiakai/actions-git 2.0.2 → 6.0.0

package/README.md

@@ -6,6 +6,8 @@
 
 The library handles repository setup for you—including cloning, branch initialization, and Git identity configuration—then returns a repository that is ready to commit and push.
 
+> It is designed for GitHub Actions and other CI environments, but it does not hard-code a Git hosting provider.
+
 ---
 
 # Features
@@ -18,6 +20,7 @@ The library handles repository setup for you—including cloning, branch initial
 * Simple staging, commit and push workflow
 * Promise-based API
 * Fully typed
+* Absolute, relative, and glob pathspec inputs for staging and cleanup
 * Designed for GitHub Actions and CI
 
 ---
@@ -34,24 +37,25 @@ npm install @yukiakai/actions-git
 
 ```ts
 import {
-  prepareGitRepository,
   GITHUB_ACTIONS_IDENTITY,
+  prepareGitRepository,
 } from '@yukiakai/actions-git';
 
 const repository = await prepareGitRepository({
-  repository: 'owner/repository',
-  token: process.env.GITHUB_TOKEN!,
+  remote: {
+    url: 'https://github.com/owner/repository.git',
+    authentication: {
+      username: 'x-access-token',
+      password: process.env.GITHUB_TOKEN!,
+    },
+  },
   branch: 'gh-pages',
-  workingDirectory: '.deploy',
-
+  destinationDirectory: path.resolve('.deploy'),
   identity: GITHUB_ACTIONS_IDENTITY,
 });
 
 await repository.wipe(['.']);
-
 await repository.add(['dist']);
-
-
 if (await repository.hasStagedChanges()) {
   await repository.commit('deploy: update documentation');
   await repository.push();
@@ -68,83 +72,76 @@ Prepare a repository for automated Git workflows.
 
 ```ts
 interface PrepareGitRepositoryOptions {
-  repository: string;
-  token: string;
-  branch: string;
-  workingDirectory: string;
-
-  identity: GitIdentity;
+  readonly remote: {
+    readonly url: string;
+    readonly authentication: {
+      readonly username: string;
+      readonly password: string;
+    };
+  };
+  readonly branch: string;
+  readonly destinationDirectory: string;
+  readonly identity: {
+    readonly name: string;
+    readonly email: string;
+  };
 }
 ```
 
-Returns:
+| Option | Description |
+| --- | --- |
+| `remote.url` | Complete HTTP or HTTPS Git repository URL, without embedded credentials. |
+| `remote.authentication` | HTTP Basic credentials used to access the remote. A token can be supplied as `password`. |
+| `branch` | Branch to prepare for the workflow. |
+| `destinationDirectory` | Absolute local directory where the repository is cloned. |
+| `identity` | Git `user.name` and `user.email` written to the prepared repository. |
 
-```ts
-Promise<PreparedGitRepository>
-```
+If `branch` exists on the remote, the package shallow-clones that branch. Otherwise, it clones the remote's default branch, creates an orphan branch with the requested name, and removes the inherited files.
 
-The returned repository only exposes workflow operations. Repository initialization APIs are intentionally kept internal.
+The function returns `Promise<PreparedGitRepository>`. Initialization operations stay internal; the returned repository is ready for workflow operations such as `wipe`, `add`, `commit`, and `push`.
 
----
+## Authentication and security
 
-# Built-in Identities
+`prepareGitRepository` supports HTTP(S) remotes with HTTP Basic authentication. The input URL must be a complete URL without a username or password; authentication is supplied separately so it can be encoded safely.
 
-The library provides reusable identities for common CI environments.
+For GitHub, a common configuration is `x-access-token` as the username and a `GITHUB_TOKEN` or personal access token as the password. Other Git hosts can use their own HTTP Basic username and password/token convention.
 
-## `GITHUB_ACTIONS_IDENTITY`
+The prepared repository uses the authenticated remote URL so that later `pull()` and `push()` operations can authenticate. Treat its `.git/config` as sensitive:
 
-```ts
-import {
-  GITHUB_ACTIONS_IDENTITY,
-} from '@yukiakai/actions-git';
-```
+- Do not print `git remote -v` or Git configuration in CI logs.
+- Do not upload the checkout or its `.git` directory as an artifact.
+- Keep the checkout in an ephemeral or cleaned-up workspace when possible.
 
-Equivalent to:
+## Pathspec inputs
 
-```ts
-{
-  name: 'github-actions[bot]',
-  email: 'github-actions[bot]@users.noreply.github.com',
-}
-```
+`wipe()` and `add()` accept repository pathspec inputs. These may be:
 
-You can also provide your own identity.
+- Absolute file or directory paths inside the prepared repository.
+- Paths relative to the prepared repository root.
+- Absolute or relative glob patterns, such as `dist/**` or `packages/*/coverage/**`.
 
-```ts
-identity: {
-  name: 'Yuki Akai',
-  email: 'yuki@example.com',
-}
-```
-
----
+Inputs are normalized to Git-compatible repository-relative pathspecs. A pathspec that resolves outside the repository is rejected.
 
-# PreparedGitRepository
+## `PreparedGitRepository`
 
-Represents a repository that has already been prepared for write operations.
-
----
+### `wipe(pathspecInputs)`
 
-## `wipe(patterns)`
-
-Remove tracked and untracked files.
+Removes tracked and untracked files matching the supplied pathspecs.
 
 ```ts
 await repository.wipe(['.']);
 ```
 
-Internally executes:
+Internally, it runs the equivalent of:
 
 ```bash
-git rm -r -f --ignore-unmatch
-git clean -fdx
+git rm -r -f --ignore-unmatch -- <pathspecs>
+git clean -fdx -- <pathspecs>
 ```
 
----
-
-## `add(patterns)`
+### `add(pathspecInputs)`
 
-Stage files.
+Stages files matching the supplied pathspecs.
 
 ```ts
 await repository.add([
@@ -153,38 +150,31 @@ await repository.add([
 ]);
 ```
 
----
-
-## `hasStagedChanges()`
-
-Check whether staged changes exist.
-
-Internally executes:
+Internally, it runs:
 
 ```bash
-git diff --cached --quiet
+git add -- <pathspecs>
 ```
 
-Returns:
+### `hasStagedChanges()`
 
-* `true` if staged changes exist.
-* `false` otherwise.
+Returns `true` when the index contains staged changes.
 
----
+```ts
+if (await repository.hasStagedChanges()) {
+  // Commit and push.
+}
+```
 
-## `commit(message)`
+### `commit(message)`
 
-Create a commit.
+Creates a commit with the configured identity.
 
 ```ts
-await repository.commit(
-  'deploy: update documentation',
-);
+await repository.commit('deploy: update documentation');
 ```
 
----
-
-## `push()`
+### `push()`
 
 Push the current checked-out branch.
 
@@ -193,32 +183,35 @@ await repository.push();
 ```
 
 The current `HEAD` is pushed to `origin`.
-
+	
 ---
 
-# Typical Workflow
-
-```ts
-const repository = await prepareGitRepository({
-  repository: 'owner/repository',
-  token: process.env.GITHUB_TOKEN!,
-  branch: 'gh-pages',
-  workingDirectory: '.deploy',
+# Built-in Identities
 
-  identity: GITHUB_ACTIONS_IDENTITY,
-});
+`GITHUB_ACTIONS_IDENTITY` configures the standard GitHub Actions bot identity.
 
-await repository.wipe(['.']);
+```ts
+import {
+  GITHUB_ACTIONS_IDENTITY,
+} from '@yukiakai/actions-git';
+```
 
-await repository.add(['dist']);
+Equivalent to:
 
-if (!await repository.hasStagedChanges()) {
-  return;
+```ts
+{
+  name: 'github-actions[bot]',
+  email: 'github-actions[bot]@users.noreply.github.com',
 }
+```
 
-await repository.commit('deploy');
+You can also provide your own identity.
 
-await repository.push();
+```ts
+identity: {
+  name: 'Yuki Akai',
+  email: 'yuki@example.com',
+}
 ```
 
 ---

package/dist/public.d.ts

@@ -1,42 +1,92 @@
 type AbsoluteDirectoryPath = string;
+type AbsoluteFilePath = string;
+type RelativeFilePath = string;
+type RelativeDirectoryPath = string;
+type AbsoluteGlobPattern = string;
+type RelativeGlobPattern = string;
 
+interface GitInspectionResult {
+    exitCode: number;
+}
 interface GitIdentity {
     readonly name: string;
     readonly email: string;
 }
+declare enum GitInspectionOperation {
+    StagedChangesPresence = "stagedChangesPresence",
+    LocalBranchPresence = "localBranchPresence",
+    RemoteBranchPresence = "remoteBranchPresence"
+}
+type GitRepositoryPathspecInput = AbsoluteDirectoryPath | AbsoluteFilePath | RelativeFilePath | RelativeDirectoryPath | AbsoluteGlobPattern | RelativeGlobPattern;
+type GitRepositoryPathspec = string;
+interface GitHttpBasicAuthentication {
+    readonly username: string;
+    readonly password: string;
+}
+interface GitRemoteOptions {
+    readonly url: string;
+    readonly authentication: GitHttpBasicAuthentication;
+}
 
-interface GitRepositoryOptions {
-    workingDirectory: AbsoluteDirectoryPath;
+interface GitRepositoryCommandExecutorOptions {
+    readonly workingDirectory: AbsoluteDirectoryPath;
 }
-declare class GitRepository {
+declare class GitRepositoryCommandExecutor {
+    private readonly options;
+    constructor(options: GitRepositoryCommandExecutorOptions);
+    execute(args: readonly string[]): Promise<void>;
+    inspect(args: readonly string[]): Promise<GitInspectionResult>;
+}
+
+interface GitRepositoryPathspecResolverOptions {
+    readonly repositoryDirectory: AbsoluteDirectoryPath;
+}
+declare class GitRepositoryPathspecResolver {
     private options;
-    constructor(options: GitRepositoryOptions);
-    private execute;
-    private executeInspectable;
-    wipe(pattern: string[]): Promise<void>;
+    constructor(options: GitRepositoryPathspecResolverOptions);
+    resolve(pathspec: GitRepositoryPathspecInput): GitRepositoryPathspec;
+    resolveAll(pathspecs: GitRepositoryPathspecInput[]): GitRepositoryPathspec[];
+    private isOutsideRepository;
+}
+
+declare class GitRepository {
+    private readonly commandExecutor;
+    private readonly pathspecResolver;
+    constructor(commandExecutor: GitRepositoryCommandExecutor, pathspecResolver: GitRepositoryPathspecResolver);
+    wipe(pathspecInputs: GitRepositoryPathspecInput[]): Promise<void>;
     setupIdentity(identity: GitIdentity): Promise<void>;
     checkout(branch: string): Promise<void>;
     checkoutOrphan(branch: string): Promise<void>;
     pull(): Promise<void>;
     pullRebase(branch: string): Promise<void>;
     commit(message: string): Promise<void>;
-    add(pattern: string[]): Promise<void>;
+    add(pathspecInputs: GitRepositoryPathspecInput[]): Promise<void>;
     push(): Promise<void>;
     hasStagedChanges(): Promise<boolean>;
     hasLocalBranch(branch: string): Promise<boolean>;
 }
 
-type PreparedGitRepository = Omit<GitRepository, 'setupIdentity' | 'checkout' | 'checkoutOrphan' | 'pullRebase' | 'hasLocalBranch'>;
+type PreparedGitRepository = Omit<GitRepository, 'setupIdentity' | 'checkout' | 'checkoutOrphan' | 'pullRebase' | 'hasLocalBranch' | 'pull'>;
 
 interface PrepareGitRepositoryOptions {
-    readonly repository: string;
-    readonly token: string;
+    readonly remote: GitRemoteOptions;
     readonly branch: string;
-    readonly directory: AbsoluteDirectoryPath;
+    readonly destinationDirectory: AbsoluteDirectoryPath;
     identity: GitIdentity;
 }
 declare function prepareGitRepository(options: PrepareGitRepositoryOptions): Promise<PreparedGitRepository>;
 
 declare const GITHUB_ACTIONS_IDENTITY: GitIdentity;
 
-export { type AbsoluteDirectoryPath, GITHUB_ACTIONS_IDENTITY, type GitIdentity, GitRepository, type PrepareGitRepositoryOptions, type PreparedGitRepository, prepareGitRepository };
+interface UnexpectedGitInspectionResultErrorOptions {
+    readonly result: GitInspectionResult;
+    readonly operation: GitInspectionOperation;
+}
+type UnexpectedGitInspectionResultErrorDetails = UnexpectedGitInspectionResultErrorOptions;
+declare class UnexpectedGitInspectionResultError extends Error {
+    private options;
+    readonly details: UnexpectedGitInspectionResultErrorDetails;
+    constructor(options: UnexpectedGitInspectionResultErrorOptions);
+}
+
+export { type AbsoluteDirectoryPath, type AbsoluteFilePath, type AbsoluteGlobPattern, GITHUB_ACTIONS_IDENTITY, type GitHttpBasicAuthentication, type GitIdentity, GitInspectionOperation, type GitInspectionResult, type GitRemoteOptions, GitRepository, type GitRepositoryPathspecInput, type PrepareGitRepositoryOptions, type PreparedGitRepository, type RelativeDirectoryPath, type RelativeFilePath, type RelativeGlobPattern, UnexpectedGitInspectionResultError, type UnexpectedGitInspectionResultErrorDetails, type UnexpectedGitInspectionResultErrorOptions, prepareGitRepository };

package/dist/public.js

@@ -1,2 +1,2 @@
-import{exec as m}from"@actions/exec";var s=class{static async execute(t){let r=await m("git",[...t.args],{cwd:t.workingDirectory})}static async inspect(t){return{exitCode:await m("git",[...t.args],{cwd:t.workingDirectory,ignoreReturnCode:!0})}}};var n=class{constructor(t){this.options=t}execute(t){return s.execute({workingDirectory:this.options.workingDirectory,args:t})}executeInspectable(t){return s.inspect({workingDirectory:this.options.workingDirectory,args:t})}async wipe(t){await this.execute(["rm","-r","-f","--ignore-unmatch",...t]),await this.execute(["clean","-fdx","--",...t])}async setupIdentity(t){await this.execute(["config","user.name",t.name]),await this.execute(["config","user.email",t.email])}async checkout(t){await this.execute(["checkout",t])}async checkoutOrphan(t){await this.execute(["checkout","--orphan",t])}async pull(){await this.execute(["pull"])}async pullRebase(t){await this.execute(["pull","--rebase","origin",t])}async commit(t){await this.execute(["commit","-m",t])}async add(t){await this.execute(["add",...t])}async push(){await this.execute(["push","--set-upstream","origin","HEAD"])}async hasStagedChanges(){let t=await this.executeInspectable(["diff","--cached","--quiet"]);if(t.exitCode===0)return!1;if(t.exitCode===1)return!0;throw new Error(`git diff failed with exit code ${t.exitCode}`)}async hasLocalBranch(t){let r=await this.executeInspectable(["show-ref","--verify","--quiet",`refs/heads/${t}`]);if(r.exitCode===0)return!0;if(r.exitCode===1)return!1;throw new Error(`Failed to resolve local branch "${t}"`)}};var c=class{constructor(t){this.git=t}async initialize(t){if(await this.git.hasLocalBranch(t)){await this.git.checkout(t);return}await this.git.checkoutOrphan(t),await this.git.wipe(["."])}};var p=class{constructor(t){this.options=t}execInspectable(t){return s.inspect({workingDirectory:void 0,args:t})}async exists(t){let r=await this.execInspectable(["ls-remote","--exit-code","--heads",this.options.repositoryUrl,t]);switch(r.exitCode){case 0:return!0;case 2:return!1;default:throw new Error([`Failed to check remote branch "${t}"`,`Repository: ${this.options.repositoryUrl}`,`Exit code: ${r.exitCode}`].join(`
-`))}}};import h from"path";var y=class{constructor(t){this.options=t}execute(t){return s.execute({workingDirectory:h.dirname(this.options.destinationDirectory),args:t})}async clone(){await this.execute(["clone",this.options.repositoryUrl,this.options.destinationDirectory])}async cloneAtBranch(t){await this.execute(["clone","--depth=1","--branch",t,this.options.repositoryUrl,this.options.destinationDirectory])}};var u=class{static build(t){let{token:r,repository:a}=t;return`https://x-access-token:${r}@github.com/${a}.git`}};async function d(e){let t=u.build({repository:e.repository,token:e.token}),r=new p({repositoryUrl:t}),a=new y({repositoryUrl:t,destinationDirectory:e.directory});await r.exists(e.branch)?await a.cloneAtBranch(e.branch):await a.clone();let l=new n({workingDirectory:e.directory});return await new c(l).initialize(e.branch),await l.setupIdentity(e.identity),l}var x={name:"github-actions[bot]",email:"github-actions[bot]@users.noreply.github.com"};export{x as GITHUB_ACTIONS_IDENTITY,n as GitRepository,d as prepareGitRepository};
+var a=class r extends Error{constructor(e){super(["Unexpected git inspection result.",`Operation: ${e.operation}`,`Exit code: ${e.result.exitCode}`].join(`
+`));this.options=e;this.name=r.name,this.details=e}details};var P=(n=>(n.StagedChangesPresence="stagedChangesPresence",n.LocalBranchPresence="localBranchPresence",n.RemoteBranchPresence="remoteBranchPresence",n))(P||{});var c=class{static hasStagedChanges(t){switch(t.exitCode){case 0:return!1;case 1:return!0;default:throw new a({result:t,operation:"stagedChangesPresence"})}}static hasLocalBranch(t){switch(t.exitCode){case 0:return!0;case 1:return!1;default:throw new a({result:t,operation:"localBranchPresence"})}}static hasRemoteBranch(t){switch(t.exitCode){case 0:return!0;case 2:return!1;default:throw new a({result:t,operation:"remoteBranchPresence"})}}};var l=class{constructor(t,e){this.commandExecutor=t;this.pathspecResolver=e}async wipe(t){let e=this.pathspecResolver.resolveAll(t);await this.commandExecutor.execute(["rm","-r","-f","--ignore-unmatch","--",...e]),await this.commandExecutor.execute(["clean","-fdx","--",...e])}async setupIdentity(t){await this.commandExecutor.execute(["config","user.name",t.name]),await this.commandExecutor.execute(["config","user.email",t.email])}async checkout(t){await this.commandExecutor.execute(["checkout",t])}async checkoutOrphan(t){await this.commandExecutor.execute(["checkout","--orphan",t])}async pull(){await this.commandExecutor.execute(["pull"])}async pullRebase(t){await this.commandExecutor.execute(["pull","--rebase","origin",t])}async commit(t){await this.commandExecutor.execute(["commit","-m",t])}async add(t){let e=this.pathspecResolver.resolveAll(t);await this.commandExecutor.execute(["add","--",...e])}async push(){await this.commandExecutor.execute(["push","--set-upstream","origin","HEAD"])}async hasStagedChanges(){let t=await this.commandExecutor.inspect(["diff","--cached","--quiet"]);return c.hasStagedChanges(t)}async hasLocalBranch(t){let e=await this.commandExecutor.inspect(["show-ref","--verify","--quiet",`refs/heads/${t}`]);return c.hasLocalBranch(e)}};var u=class{constructor(t){this.git=t}async initialize(t){if(await this.git.hasLocalBranch(t)){await this.git.checkout(t);return}await this.git.checkoutOrphan(t),await this.git.wipe(["."])}};import{exec as g}from"@actions/exec";var s=class{static async execute(t){let e=await g("git",[...t.args],{cwd:t.workingDirectory})}static async inspect(t){return{exitCode:await g("git",[...t.args],{cwd:t.workingDirectory,ignoreReturnCode:!0})}}};var m=class{constructor(t){this.options=t}execInspectable(t){return s.inspect({workingDirectory:void 0,args:t})}async exists(t){let e=await this.execInspectable(["ls-remote","--exit-code","--heads",this.options.repositoryUrl,t]);return c.hasRemoteBranch(e)}};import I from"path";var h=class{constructor(t){this.options=t}execute(t){return s.execute({workingDirectory:I.dirname(this.options.destinationDirectory),args:t})}async clone(){await this.execute(["clone",this.options.repositoryUrl,this.options.destinationDirectory])}async cloneAtBranch(t){await this.execute(["clone","--depth=1","--branch",t,this.options.repositoryUrl,this.options.destinationDirectory])}};var d=class{constructor(t){this.repositoryUrl=t}withAuthentication(t){let e=new URL(this.repositoryUrl);if(e.protocol!=="http:"&&e.protocol!=="https:")throw new Error("Git repository URL must use HTTP or HTTPS.");if(e.username||e.password)throw new Error("Git repository URL must not include authentication.");return e.username=t.username,e.password=t.password,e.toString()}};var R=class{constructor(t){this.options=t}async execute(t){return s.execute({workingDirectory:this.options.workingDirectory,args:t})}async inspect(t){return s.inspect({workingDirectory:this.options.workingDirectory,args:t})}};import y from"path";var x=class r extends Error{constructor(e){super(`Git path "${e.pathspec}" is outside repository "${e.repositoryDirectory}".`);this.options=e;this.name=r.name}};var G=class{constructor(t){this.options=t}resolve(t){let{repositoryDirectory:e}=this.options,n=y.resolve(e,t),p=y.relative(e,n);if(this.isOutsideRepository(p))throw new x({repositoryDirectory:e,pathspec:t});return p===""?".":p.split(y.sep).join("/")}resolveAll(t){return t.map(e=>this.resolve(e))}isOutsideRepository(t){return t===".."||t.startsWith(`..${y.sep}`)||y.isAbsolute(t)}};async function b(r){let t=new d(r.remote.url).withAuthentication(r.remote.authentication),e=new m({repositoryUrl:t}),n=new h({repositoryUrl:t,destinationDirectory:r.destinationDirectory});await e.exists(r.branch)?await n.cloneAtBranch(r.branch):await n.clone();let p=new R({workingDirectory:r.destinationDirectory}),w=new G({repositoryDirectory:r.destinationDirectory}),f=new l(p,w);return await new u(f).initialize(r.branch),await f.setupIdentity(r.identity),f}var v={name:"github-actions[bot]",email:"github-actions[bot]@users.noreply.github.com"};export{v as GITHUB_ACTIONS_IDENTITY,P as GitInspectionOperation,l as GitRepository,a as UnexpectedGitInspectionResultError,b as prepareGitRepository};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yukiakai/actions-git",
-  "version": "2.0.2",
+  "version": "6.0.0",
   "description": "Lightweight Git client for GitHub Actions and CI workflows.",
   "type": "module",
   "main": "./dist/public.js",
@@ -11,8 +11,8 @@
   },
   "scripts": {
     "test": "echo npx vitest run --reporter verbose --coverage",
-    "format": "prettier --write **/*.{js,ts,json}",
-    "format:check": "prettier --check **/*.{js,ts,json}",
+    "format": "prettier --write **/*.{ts,json,yml}",
+    "format:check": "prettier --check **/*.{ts,json,yml}",
     "lint": "eslint src/**/*.ts",
     "typecheck:workspace": "tsc -p tsconfig.workspace.json",
     "generate:types": "npx type-export-builder generate -p src/_public.ts",
@@ -57,7 +57,7 @@
     "@eslint/js": "^9.30.1",
     "@types/node": "^24.0.10",
     "@vitest/coverage-v8": "^4.0.15",
-    "@yukiakai/artifact": "^1.0.1",
+    "@yukiakai/artifact": "^2.0.1",
     "dotenv": "^17.0.1",
     "eslint": "^9.30.0",
     "husky": "^9.1.7",