git-chopstick-core 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.8] — 2026-06-13
+
+### Added
+- **Test files included in package**: Added `src/__tests__/` to the `files` array in `package.json`. Integration tests ship with the installed package so consumers can run `npm test` to verify the package works for their environment.
+
+---
+
+## [0.1.7] — 2026-06-13
+
+### Added
+- **Documentation included in package**: Added `docs/` to the `files` array in `package.json`. The migration guide (`docs/exec-to-git-migration.md`) and release skill (`docs/skills/release.md`) now ship with the installed package.
+
+---
+
 ## [0.1.6] — 2026-06-13
 
 ### Fixed
@@ -115,11 +129,8 @@
 
 ---
 
-[0.1.4]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.4
-[0.1.3]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.3
-[0.1.2]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.2
-[0.1.1]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.1
-[0.1.0]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.0
+[0.1.8]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.8
+[0.1.7]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.7
 [0.1.6]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.6
 [0.1.5]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.5
 [0.1.4]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.4
@@ -127,4 +138,4 @@
 [0.1.2]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.2
 [0.1.1]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.1
 [0.1.0]: https://github.com/parkiyong/git-chopstick-core/releases/tag/v0.1.0
-[Unreleased]: https://github.com/parkiyong/git-chopstick-core/compare/v0.1.5...HEAD
+[Unreleased]: https://github.com/parkiyong/git-chopstick-core/compare/v0.1.8...HEAD

package/README.md

@@ -26,7 +26,7 @@ npm install file:../path/to/git-chopstick-core
 ```typescript
 import { Repository, getStatus, GitError } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 
 try {
   const status = await getStatus(repo)
@@ -46,7 +46,7 @@ try {
 ```typescript
 import { Repository, getStatus } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 const status = await getStatus(repo)
 
 if (!status) {
@@ -81,7 +81,7 @@ if (status.rebaseInternalState) {
 ```typescript
 import { Repository, getStatus, createCommit } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 const status = await getStatus(repo)
 
 // Stage and commit all tracked files
@@ -98,7 +98,7 @@ import {
   deleteLocalBranch, renameBranch, getBranches
 } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 
 // Create a branch
 await createBranch(repo, 'feature/new-feature', 'main')
@@ -125,7 +125,7 @@ import {
   abortMerge, getMergeBase, isMergeHeadSet
 } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 
 const result = await merge(repo, 'feature/new-feature')
 
@@ -149,7 +149,7 @@ import {
   Repository, push, pull, getRemotes, getStatus
 } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 const [remote] = await getRemotes(repo)
 const status = await getStatus(repo)
 
@@ -167,7 +167,7 @@ import {
   Repository, merge, GitError, GitErrorCodes
 } from 'git-chopstick-core'
 
-const repo = new Repository('/path/to/repo', 1)
+const repo = new Repository('/path/to/repo')
 
 try {
   await merge(repo, 'other-branch')
@@ -328,11 +328,14 @@ src/
 # Type-check
 npm run typecheck
 
+# Run integration tests (uses vitest, creates temp git repos)
+npm test
+
 # Build (compile TypeScript → dist/)
 npm run build
 
-# Clean rebuild (build already cleans automatically)
-npm run build
+# Package contents dry-run (verify files before publish)
+npm pack --dry-run
 
 # Run examples (uses tsx for source-level execution)
 npx tsx examples/get-status.ts /path/to/repo

package/docs/exec-to-git-migration.md

@@ -0,0 +1,75 @@
+# Migration Guide: `exec` → `git()`
+
+> **Applies to:** Upgrading from `git-chopstick-core@0.1.4` to `0.1.5+`
+
+In v0.1.4, `exec()` was briefly exposed as a public function. Starting in **v0.1.5**, `exec()` is no longer part of the public API — `git()` is the single function for running Git commands.
+
+## Why?
+
+`exec()` and `git()` did the same thing with different semantics:
+
+| Aspect | `exec()` | `git()` |
+|--------|----------|---------|
+| `successExitCodes` | ❌ No — raw exit code | ✅ Yes — configurable set |
+| Error parsing | ❌ No | ✅ Yes — 50-code `GitError` enum |
+| Throws on bad exit | ❌ No — returns raw result | ✅ Yes — throws `GitError` |
+| Hook interception | ❌ No | ✅ Yes — `interceptHooks` option |
+| Buffer output | ✅ Yes — `encoding: 'buffer'` | ✅ Yes — `{ encoding: 'buffer' }` |
+
+`git()` does everything `exec()` did, plus error handling, typed error codes, and hook support. Maintaining both was confusing.
+
+## Before → After
+
+### Raw git execution (basic)
+
+```typescript
+// Before (v0.1.4)
+import { exec } from 'git-chopstick-core/git'
+const result = await exec(['rev-parse', '--show-toplevel'], '/path/to/repo')
+
+// After (v0.1.5+)
+import { git } from 'git-chopstick-core'
+const result = await git(['rev-parse', '--show-toplevel'], '/path/to/repo', 'my-op')
+```
+
+### Buffer output (binary diffs)
+
+```typescript
+// Before
+import { exec } from 'git-chopstick-core/git'
+const result = await exec(['diff', '--binary', sha], path, { encoding: 'buffer' })
+
+// After
+import { git } from 'git-chopstick-core'
+const result = await git(['diff', '--binary', sha], path, 'my-op', { encoding: 'buffer' })
+```
+
+### Ignoring non-zero exit codes
+
+```typescript
+// Before — exec doesn't filter, so you check exitCode manually
+const result = await exec(['symbolic-ref', '--short', 'HEAD'], path)
+const branch = result.exitCode === 0 ? result.stdout.toString().trim() : undefined
+
+// After — git() accepts successExitCodes, returns result or throws
+const result = await git(['symbolic-ref', '--short', 'HEAD'], path, 'getBranch', {
+  successExitCodes: new Set([0, 128]),
+})
+const branch = result.exitCode === 0 ? result.stdout.trim() : undefined
+
+// Or just use the built-in helper:
+import { getCurrentBranch } from 'git-chopstick-core'
+const branch = await getCurrentBranch(path)
+```
+
+## What stayed public?
+
+The following from `exec.ts` remain in the public API because they serve different purposes:
+
+| Export | Purpose |
+|--------|---------|
+| `spawnGit(args, path, options?)` | Returns a `ChildProcess` for streaming git access — useful for long-running operations where you want direct process control |
+| `parseError(stderr)` | Parse git stderr into a `GitError` enum value for manual error inspection |
+| `parseBadConfigValueErrorInfo(stderr)` | Extract key/value from bad config value errors |
+| `ExecError` (class) | Error thrown when maxBuffer is exceeded |
+| `GitError` (enum) | 50+ typed error codes (available as `GitErrorCodes` from root barrel) |

package/docs/skills/release.md

@@ -0,0 +1,82 @@
+---
+name: release
+description: Automated release workflow for git-chopstick-core — version bump, changelog, build, validation, and npm publish.
+---
+
+# Release: git-chopstick-core
+
+> Loaded via `skill("release")`. Run this whenever you need to publish a new release.
+
+## Process
+
+### 1. Read current state
+
+Read `package.json`, `CHANGELOG.md`, and run `git log --oneline -5` to understand what has changed since the last release.
+
+### 2. Determine version bump
+
+Check what has changed:
+
+- **Breaking API changes** (removed exports, changed signatures) → minor bump (0.x.0)
+- **New features** (new functions, new exports) → patch bump (0.0.x)
+- **Bug fixes, docs, internal refactoring** → patch bump (0.0.x)
+
+Current version: read from `package.json`. Bump accordingly.
+
+### 3. Update `CHANGELOG.md`
+
+Insert a new `## [VERSION] — YYYY-MM-DD` section at the top (below the `# Changelog` heading) with:
+
+- `### Added` — new features, exports, helpers
+- `### Changed` — behavioral changes, renames, config changes
+- `### Fixed` — bug fixes
+
+Then update the link references at the bottom:
+
+- Add `[VERSION]: https://github.com/parkiyong/git-chopstick-core/releases/tag/vVERSION`
+- Update `[Unreleased]: .../compare/vVERSION...HEAD`
+
+### 4. Bump `package.json`
+
+Update `"version"` field.
+
+### 5. Build and validate
+
+Run all of these (use parallel agents):
+
+- `npm run typecheck` — must pass with zero errors
+- `npm run build` — must produce a clean `dist/`
+- `npm test` — all integration tests must pass
+- `npm pack --dry-run` — confirm all of:
+  - `dist/` is included (expect ~351 files, ~700kB)
+  - `CHANGELOG.md`, `docs/`, and `src/__tests__/integration.test.ts` appear in the file list
+  - `package.json`, `README.md`, `LICENSE` are present (npm includes these automatically)
+  - No unexpected files are leaking through (check for test artifacts, `.ts` sources outside `dist/`)
+
+If any fail, fix before proceeding.
+
+### 6. Stage and commit
+
+```
+git add -A
+git commit -m "vVERSION: <short summary of changes>"
+```
+
+### 7. Push and publish
+
+```
+git push origin main
+npm publish
+```
+
+### 8. Verify
+
+- Confirm npm shows the new version: `npm view git-chopstick-core version`
+- Confirm the tag exists on GitHub: `git tag -l`
+- Suggest followup tasks
+
+## Notes
+
+- `prepublishOnly` runs `npm run typecheck && npm test && npm run build` automatically — integration tests must pass before publish can proceed. This catches API regressions, broken imports, and test failures before they ship.
+  You still validate in step 5 beforehand rather than relying solely on `prepublishOnly`.
+- If this is the first release in a session, run `setup-matt-pocock-skills` first to configure issue tracker context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-chopstick-core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,7 +32,9 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs",
+    "src/__tests__"
   ],
   "description": "Git backend library extracted from GitHub Desktop",
   "scripts": {
@@ -40,7 +42,7 @@
     "build": "npm run clean && tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
     "byline": "^5.0.0",

package/src/__tests__/integration.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { mkdtempSync, writeFileSync } from 'fs'
+import { execSync } from 'child_process'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  Repository, getStatus, getCommits, getBranches,
+  createCommit, createBranch, deleteLocalBranch, renameBranch,
+  getCurrentBranch, getRepositoryType,
+} from '../index.js'
+
+let repoPath: string
+let repo: Repository
+
+function git(args: string) {
+  execSync(`git ${args}`, { cwd: repoPath, stdio: 'pipe' })
+}
+
+function writeFile(path: string, content: string) {
+  writeFileSync(join(repoPath, path), content)
+}
+
+beforeAll(() => {
+  repoPath = mkdtempSync(join(tmpdir(), 'gcctest-'))
+  git('init -q')
+  git('config user.email test@test.test')
+  git('config user.name Test')
+
+  // Create an initial commit so we have history for detached HEAD tests
+  writeFile('README.md', '# test')
+  git('add README.md')
+  git('commit -m "initial"')
+
+  repo = new Repository(repoPath)
+})
+
+describe('getRepositoryType', () => {
+  it('returns regular for a valid repo', async () => {
+    const type = await getRepositoryType(repoPath)
+    expect(type.kind).toBe('regular')
+    if (type.kind === 'regular') {
+      expect(type.topLevelWorkingDirectory).toBe(repoPath)
+    }
+  })
+
+  it('returns missing for a non-existent path', async () => {
+    const type = await getRepositoryType('/nonexistent/path')
+    expect(type.kind).toBe('missing')
+  })
+})
+
+describe('getCurrentBranch', () => {
+  it('returns the current branch name', async () => {
+    const branch = await getCurrentBranch(repoPath)
+    expect(branch).toBeTruthy()
+    expect(typeof branch).toBe('string')
+  })
+
+  it('returns undefined when HEAD is detached', async () => {
+    git('checkout --detach')
+    const branch = await getCurrentBranch(repoPath)
+    expect(branch).toBeUndefined()
+    // Reset back to a branch for subsequent tests
+    git('checkout -')
+  })
+})
+
+describe('getStatus', () => {
+  it('returns a status with branch info', async () => {
+    const status = await getStatus(repo)
+    expect(status).toBeTruthy()
+    expect(status!.currentBranch).toBeTruthy()
+    expect(typeof status!.currentBranch).toBe('string')
+  })
+
+  it('detects untracked files', async () => {
+    writeFile('untracked.txt', 'hello')
+    const status = await getStatus(repo)
+    expect(status!.workingDirectory.files.length).toBeGreaterThanOrEqual(1)
+    const untracked = status!.workingDirectory.files.find(
+      f => f.path === 'untracked.txt'
+    )
+    expect(untracked).toBeTruthy()
+  })
+
+  it('returns null for a path that exists but is not a git repo', async () => {
+    const nonRepoPath = mkdtempSync(join(tmpdir(), 'gcctest-nonrepo-'))
+    const result = await getStatus(new Repository(nonRepoPath))
+    expect(result).toBeNull()
+    execSync(`rm -rf ${nonRepoPath}`)
+  })
+})
+
+describe('getCommits', () => {
+  it('returns commits in order', async () => {
+    // Create another commit so we have history to read
+    writeFile('commits-test.txt', 'data')
+    git('add commits-test.txt')
+    git('commit -m "test commit for getCommits"')
+
+    const commits = await getCommits(repo, 'HEAD', 10)
+    expect(commits.length).toBeGreaterThanOrEqual(1)
+    expect(commits[0].summary).toBe('test commit for getCommits')
+    expect(commits[0].sha).toBeTruthy()
+    expect(commits[0].author).toBeTruthy()
+  })
+})
+
+describe('Branch operations', () => {
+  it('creates, lists, renames, and deletes branches', async () => {
+    // Create a branch
+    await createBranch(repo, 'test-feature', 'HEAD')
+    let branches = await getBranches(repo)
+    const names = branches.map(b => b.name)
+    expect(names).toContain('test-feature')
+
+    // Rename the branch
+    const featureBranch = branches.find(b => b.name === 'test-feature')!
+    await renameBranch(repo, featureBranch, 'test-feature-renamed')
+    branches = await getBranches(repo)
+    expect(branches.map(b => b.name)).toContain('test-feature-renamed')
+    expect(branches.map(b => b.name)).not.toContain('test-feature')
+
+    // Delete the branch
+    await deleteLocalBranch(repo, 'test-feature-renamed')
+    branches = await getBranches(repo)
+    expect(branches.map(b => b.name)).not.toContain('test-feature-renamed')
+  })
+})
+
+describe('createCommit', () => {
+  it('creates a commit with files', async () => {
+    writeFile('commit-test.txt', 'commit data')
+    git('add commit-test.txt')
+
+    const status = await getStatus(repo)
+    const files = status!.workingDirectory.files.filter(
+      f => f.path === 'commit-test.txt'
+    )
+
+    const sha = await createCommit(repo, 'feat: add commit-test.txt', files)
+    expect(sha).toBeTruthy()
+    // createCommit returns the abbreviated SHA from git commit output (7+ chars)
+    expect(sha.length).toBeGreaterThanOrEqual(7)
+
+    // Verify the commit exists — the full SHA from getCommits should start
+    // with the abbreviated SHA returned by createCommit
+    const commits = await getCommits(repo, 'HEAD', 5)
+    expect(commits[0].sha.startsWith(sha)).toBe(true)
+    expect(commits[0].summary).toBe('feat: add commit-test.txt')
+  })
+})
+
+afterAll(() => {
+  execSync(`rm -rf ${repoPath}`)
+})