@yukiakai/actions-git 1.0.6 → 2.0.0

package/README.md

@@ -2,36 +2,27 @@
 
 > Lightweight Git client for GitHub Actions and CI workflows.
 
-A small, promise-based wrapper around `git` built for automation workflows such as:
+`@yukiakai/actions-git` prepares a Git repository for automated workflows.
 
-- Deploy actions
-- Artifact publishing
-- Docs deployment
-- CI synchronization
-- Temporary repository workflows
-
-Designed to be:
-- Minimal
-- Predictable
-- CI-friendly
-- Easy to test
+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.
 
 ---
 
-## Features
+# Features
 
-- Shallow clone with automatic fallback
-- Branch existence detection
-- Orphan branch support
-- Workspace wipe utilities
-- Simple commit/push workflow
-- Promise-based API
-- TypeScript support
-- Designed for GitHub Actions
+* Ready-to-use Git repository
+* Automatic remote branch detection
+* Shallow clone with automatic fallback
+* Automatic orphan branch initialization
+* Configurable Git identity
+* Simple staging, commit and push workflow
+* Promise-based API
+* Fully typed
+* Designed for GitHub Actions and CI
 
 ---
 
-## Installation
+# Installation
 
 ```bash
 npm install @yukiakai/actions-git
@@ -39,135 +30,147 @@ npm install @yukiakai/actions-git
 
 ---
 
-## Example
+# Quick Start
 
 ```ts
-import { GitClient } from '@yukiakai/actions-git';
+import {
+  prepareGitRepository,
+  GITHUB_ACTIONS_IDENTITY,
+} from '@yukiakai/actions-git';
 
-const git = new GitClient({
-  repo: 'owner/repo',
+const repository = await prepareGitRepository({
+  repository: 'owner/repository',
   token: process.env.GITHUB_TOKEN!,
   branch: 'gh-pages',
-  cwd: './.deploy',
-});
-
-await git.clone();
-
-await git.setup();
+  workingDirectory: '.deploy',
 
-await git.checkout();
+  identity: GITHUB_ACTIONS_IDENTITY,
+});
 
-await git.wipe(['.']);
+await repository.wipe(['.']);
 
-await git.add(['dist']);
+await repository.add(['dist']);
 
-if (await git.hasChanges()) {
-  await git.commit('deploy: update docs');
+await repository.commit('deploy: update documentation');
 
-  await git.push();
+if (await repository.hasStagedChanges()) {
+  
+  await repository.push();
 }
 ```
 
 ---
 
-## API
+# API
 
-### `new GitClient(options)`
+## `prepareGitRepository(options)`
 
-Creates a new Git client instance.
+Prepare a repository for automated Git workflows.
 
 ```ts
-type GitOptions = {
-  repo: string;
+interface PrepareGitRepositoryOptions {
+  repository: string;
   token: string;
   branch: string;
-  cwd: string;
-};
-```
-
----
-
-# Methods
+  workingDirectory: string;
 
-## `clone()`
-
-Clone the repository into the target working directory.
+  identity: GitIdentity;
+}
+```
 
-Attempts shallow clone first:
+Returns:
 
-```bash
-git clone --depth=1 --branch <branch>
+```ts
+Promise<PreparedGitRepository>
 ```
 
-Falls back to full clone if shallow clone fails.
+The returned repository only exposes workflow operations. Repository initialization APIs are intentionally kept internal.
 
 ---
 
-## `setup()`
+# Built-in Identities
 
-Configure git identity for CI environments.
+The library provides reusable identities for common CI environments.
 
-Sets:
+## `GITHUB_ACTIONS_IDENTITY`
 
-```bash
-user.name  = github-actions[bot]
-user.email = github-actions[bot]@users.noreply.github.com
+```ts
+import {
+  GITHUB_ACTIONS_IDENTITY,
+} from '@yukiakai/actions-git';
 ```
 
----
+Equivalent to:
+
+```ts
+{
+  name: 'github-actions[bot]',
+  email: 'github-actions[bot]@users.noreply.github.com',
+}
+```
 
-## `checkout()`
+You can also provide your own identity.
 
-Checkout the target branch.
+```ts
+identity: {
+  name: 'Yuki Akai',
+  email: 'yuki@example.com',
+}
+```
 
-Behavior:
+---
 
-- If the branch exists:
-  - `git checkout <branch>`
+# PreparedGitRepository
 
-- If the branch does not exist:
-  - creates orphan branch
-  - wipes working tree
+Represents a repository that has already been prepared for write operations.
 
 ---
 
 ## `wipe(patterns)`
 
-Remove tracked and untracked files from the working tree.
+Remove tracked and untracked files.
 
 ```ts
-await git.wipe(['.']);
+await repository.wipe(['.']);
 ```
 
-Internally runs:
+Internally executes:
 
 ```bash
 git rm -r -f --ignore-unmatch
 git clean -fdx
 ```
 
-Useful for deployment workflows where the workspace must be fully reset.
-
 ---
 
-## `pullRebase()`
+## `add(patterns)`
 
-Run:
+Stage files.
 
-```bash
-git pull --rebase origin <branch>
+```ts
+await repository.add([
+  'dist',
+  'package.json',
+]);
 ```
 
 ---
 
-## `add(patterns)`
+## `hasStagedChanges()`
 
-Stage files.
+Check whether staged changes exist.
 
-```ts
-await git.add(['dist', 'package.json']);
+Internally executes:
+
+```bash
+git diff --cached --quiet
 ```
 
+Returns:
+
+* `true` if staged changes exist.
+* `false` otherwise.
+
 ---
 
 ## `commit(message)`
@@ -175,52 +178,63 @@ await git.add(['dist', 'package.json']);
 Create a commit.
 
 ```ts
-await git.commit('deploy: update docs');
+await repository.commit(
+  'deploy: update documentation',
+);
 ```
 
 ---
 
 ## `push()`
 
-Push the current branch to origin.
+Push the current checked-out branch.
 
 ```ts
-await git.push();
+await repository.push();
 ```
 
----
+The current `HEAD` is pushed to `origin`.
 
-## `hasChanges()`
+---
 
-Check whether staged changes exist.
+# Typical Workflow
 
 ```ts
-const changed = await git.hasChanges();
-```
+const repository = await prepareGitRepository({
+  repository: 'owner/repository',
+  token: process.env.GITHUB_TOKEN!,
+  branch: 'gh-pages',
+  workingDirectory: '.deploy',
 
-Uses:
+  identity: GITHUB_ACTIONS_IDENTITY,
+});
 
-```bash
-git diff --cached --quiet
-```
+await repository.wipe(['.']);
 
-Returns:
-- `true` → changes exist
-- `false` → no changes
+await repository.add(['dist']);
+
+await repository.commit('deploy');
+if (!await repository.hasStagedChanges()) {
+  return;
+}
+
+await repository.push();
+```
 
 ---
 
-## Use Cases
+# Designed For
 
-- GitHub Actions
-- Documentation deployment
-- Artifact deployment
-- Monorepo publishing
-- Static site deployment
-- CI repository sync
+* GitHub Actions
+* Documentation deployment
+* Static site deployment
+* Repository synchronization
+* Artifact publishing
+* Deployment pipelines
+* CI automation
 
 ---
 
-## License
+# License
 
-MIT Yuki Akai
+MIT © Yuki Akai

package/dist/public.d.ts

@@ -1,32 +1,42 @@
-import { ExecOptions } from '@actions/exec';
+type AbsoluteDirectoryPath = string;
 
-interface GitExecResult {
-    exitCode: number;
-}
-interface GitOptions {
-    cwd: string;
-    repo: string;
-    branch: string;
-    token: string;
+interface GitIdentity {
+    readonly name: string;
+    readonly email: string;
 }
 
-declare class GitClient {
+interface GitRepositoryOptions {
+    workingDirectory: AbsoluteDirectoryPath;
+}
+declare class GitRepository {
     private options;
-    constructor(options: GitOptions);
-    private get repoUrl();
-    protected execGitRaw(args: string[], options?: ExecOptions): Promise<GitExecResult>;
-    private execGit;
-    private execGitInspectable;
-    clone(): Promise<void>;
+    constructor(options: GitRepositoryOptions);
+    private execute;
+    private execInspectable;
     wipe(pattern: string[]): Promise<void>;
-    setup(): Promise<void>;
-    checkout(): Promise<void>;
-    pullRebase(): 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>;
     push(): Promise<void>;
-    hasChanges(): Promise<boolean>;
-    private branchExists;
+    hasStagedChanges(): Promise<boolean>;
+    hasLocalBranch(branch: string): Promise<boolean>;
+}
+
+type PreparedGitRepository = Omit<GitRepository, 'setupIdentity' | 'checkout' | 'checkoutOrphan' | 'pullRebase' | 'hasLocalBranch'>;
+
+interface PrepareGitRepositoryOptions {
+    readonly repository: string;
+    readonly token: string;
+    readonly branch: string;
+    readonly directory: AbsoluteDirectoryPath;
+    identity: GitIdentity;
 }
+declare function prepareGitRepository(options: PrepareGitRepositoryOptions): Promise<PreparedGitRepository>;
+
+declare const GITHUB_ACTIONS_IDENTITY: GitIdentity;
 
-export { GitClient, type GitOptions };
+export { type AbsoluteDirectoryPath, GITHUB_ACTIONS_IDENTITY, type GitIdentity, GitRepository, type PrepareGitRepositoryOptions, type PreparedGitRepository, prepareGitRepository };

package/dist/public.js

@@ -1 +1,2 @@
-import{exec as r}from"@actions/exec";var i=class{constructor(t){this.options=t}get repoUrl(){let{repo:t,token:e}=this.options;return`https://x-access-token:${e}@github.com/${t}.git`}async execGitRaw(t,e){return{exitCode:await r("git",t,e)}}async execGit(t,e){return await this.execGitRaw(t,{cwd:this.options.cwd,...e})}async execGitInspectable(t,e){return await this.execGit(t,{...e,ignoreReturnCode:!0})}async clone(){let{branch:t,cwd:e}=this.options;(await this.execGitRaw(["clone","--depth=1","--branch",t,this.repoUrl,e],{ignoreReturnCode:!0})).exitCode!==0&&await this.execGitRaw(["clone",this.repoUrl,e])}async wipe(t){await this.execGit(["rm","-r","-f","--ignore-unmatch",...t]),await this.execGit(["clean","-fdx","--",...t])}async setup(){await this.execGit(["config","user.name","github-actions[bot]"]),await this.execGit(["config","user.email","github-actions[bot]@users.noreply.github.com"])}async checkout(){let{branch:t}=this.options;await this.branchExists(t)?await this.execGit(["checkout",t]):(await this.execGit(["checkout","--orphan",t]),await this.wipe(["."]))}async pullRebase(){let{branch:t}=this.options;await this.execGit(["pull","--rebase","origin",t])}async commit(t){await this.execGit(["commit","-m",t])}async add(t){await this.execGit(["add",...t])}async push(){let{branch:t}=this.options;await this.execGit(["push","origin",t])}async hasChanges(){let t=await this.execGitInspectable(["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 branchExists(t){let e=await this.execGitInspectable(["ls-remote","--exit-code","--heads","origin",t]);if(e.exitCode===0)return!0;if(e.exitCode===2)return!1;throw new Error(`Failed to check remote branch "${t}" (exit code ${e.exitCode})`)}};export{i as GitClient};
+import{exec as m}from"@actions/exec";async function a(e){let t=await m("git",[...e.args],{cwd:e.workingDirectory})}async function c(e){return{exitCode:await m("git",[...e.args],{cwd:e.workingDirectory,ignoreReturnCode:!0})}}var s=class{constructor(t){this.options=t}execute(t){return a({workingDirectory:this.options.workingDirectory,args:t})}execInspectable(t){return c({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.execInspectable(["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 o=await this.execInspectable(["show-ref","--verify","--quiet",`refs/heads/${t}`]);if(o.exitCode===0)return!0;if(o.exitCode===1)return!1;throw new Error(`Failed to resolve local branch "${t}"`)}};var p=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 y=class{constructor(t){this.options=t}execInspectable(t){return c({workingDirectory:void 0,args:t})}async exists(t){let o=await this.execInspectable(["ls-remote","--exit-code","--heads",this.options.repositoryUrl,t]);switch(o.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: ${o.exitCode}`].join(`
+`))}}};import d from"path";var u=class{constructor(t){this.options=t}execute(t){return a({workingDirectory:d.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 l=class{static build(t){let{token:o,repository:n}=t;return`https://x-access-token:${o}@github.com/${n}.git`}};async function x(e){let t=l.build({repository:e.repository,token:e.token}),o=new y({repositoryUrl:t}),n=new u({repositoryUrl:t,destinationDirectory:e.directory});await o.exists(e.branch)?await n.cloneAtBranch(e.branch):await n.clone();let h=new s({workingDirectory:e.directory});return await new p(h).initialize(e.branch),await h.setupIdentity(e.identity),h}var f={name:"github-actions[bot]",email:"github-actions[bot]@users.noreply.github.com"};export{f as GITHUB_ACTIONS_IDENTITY,s as GitRepository,x as prepareGitRepository};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yukiakai/actions-git",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "description": "Lightweight Git client for GitHub Actions and CI workflows.",
   "type": "module",
   "main": "./dist/public.js",
@@ -10,13 +10,14 @@
     "import": "./dist/public.js"
   },
   "scripts": {
-    "test": "npx vitest run --reporter verbose --coverage",
+    "test": "echo npx vitest run --reporter verbose --coverage",
     "format": "prettier --write **/*.{js,ts,json}",
     "format:check": "prettier --check **/*.{js,ts,json}",
     "lint": "eslint src/**/*.ts",
     "typecheck:workspace": "tsc -p tsconfig.workspace.json",
+    "generate:types": "npx type-export-builder generate -p src/_public.ts",
     "build": "npx tsup",
-    "build:public": "npx tsup --config tsup.public.config.ts",
+    "build:public": "npm run generate:types && npx tsup --config tsup.public.config.ts",
     "docs": "npx typedoc",
     "prepare:artifact": "tsx workspace/release/prepareArtifact.ts",
     "prepare": "is-ci || husky"
@@ -64,6 +65,7 @@
     "prettier": "^3.6.2",
     "tsup": "^8.5.1",
     "tsx": "^4.20.3",
+    "type-export-builder": "^1.1.0",
     "typedoc": "^0.28.9",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.1",