git-chopstick-core 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+## [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
+- **CHANGELOG.md included in package**: Added `CHANGELOG.md` to the `files` array in `package.json` so consumers can read release notes from the installed package.
+
+---
+
+## [0.1.5] — 2026-06-13
+
+### Added
+- **Progress reporting**: Real `parse()` methods on all progress parsers (Checkout, Fetch, Pull, Push, Clone). Progress callbacks now receive percentage updates during long-running operations.
+- **`getCurrentBranch(path)`**: New helper in `rev-parse.ts` that returns the current branch name or `undefined` for detached HEAD.
+- **Integration tests**: 10 tests covering repository type detection, branch lookup, status parsing, commit history, branch CRUD, createCommit, and non-repo error handling. Run with `npm test`.
+- **Migration guide**: Added `docs/exec-to-git-migration.md` documenting the transition from `exec()` to `git()` with before/after examples.
+
+### Changed
+- **`exec()` removed from public API**: `exec()` is now an internal function used only by `core.ts`. Use `git()` instead — it's a strict superset with error handling, typed error codes, `successExitCodes`, and hook support.
+- **README**: Updated architecture diagram (progress 🟢), consumption patterns (no `exec`), known limitations (progress now real, tests now exist).
+
+### Fixed
+- **RevertProgressParser**: Now returns proper `IGitOutput | null` type.
+
+---
+
+## [0.1.4] — 2026-06-13
+
+### Added
+- **Public exec API**: Exported `exec`, `spawnGit`, `parseError`, `parseBadConfigValueErrorInfo`, `ExecError` from the git barrel for low-level Git execution.
+- **Repository.id default**: `Repository` constructor `id` parameter now defaults to `0` — no longer requires a placeholder value.
+- **Consumption patterns**: Documented 4 import patterns in README: root barrel, git subpath, models only, and granular subpath imports.
+- **Status section**: Added pre-1.0 status note with TypeScript 5.7+ compatibility to README.
+
+### Changed
+- **TypeScript strictness**: Enabled `noUnusedLocals` and `noUnusedParameters` in `tsconfig.json` to catch dead code. Fixed 5 newly detected unused variables.
+- **prepublishOnly**: Now runs `npm run typecheck && npm run build` to prevent shipping type-broken packages.
+- **README**: Removed stale "Not Published on npm" section (package is published).
+
+### Fixed
+- **Unused variables**: Fixed 5 TS6133 errors caught by new strict settings in `apply.ts`, `environment.ts`, `gitignore.ts`, `progress/revert.ts`.
+
+---
+
+## [0.1.3] — 2026-06-13
+
+### Changed
+- **Build pipeline**: Added `clean` script; `build` now runs `npm run clean && tsc` for deterministic fresh builds.
+- **Exports**: Switched `exports` map from raw `./src/*.ts` to compiled `./dist/*.js` / `./dist/*.d.ts` with explicit directory barrel entries.
+- **Package files**: Reduced npm package size to only `dist/` (removed `src/` from `files`).
+- **Peer dependencies**: Moved `@types/node` and `@types/byline` from `dependencies`/`devDependencies` to optional `peerDependencies` to avoid version conflicts with consumers.
+- **`.npmignore`**: Added as safety net alongside `"files": ["dist"]`.
+
+### Fixed
+- **TypeScript compilation**: Resolved 10 TS6133 errors (unused variables) across `fatal-error.ts`, `progress/`, and `status-parser.ts`.
+- **Missing type declarations**: Added `@types/byline` to fix TS7016.
+- **Buffer type mismatch**: Fixed TS2345 in `exec.ts` for `Buffer.concat()` compatibility with newer `@types/node`.
+
+### Cleanup
+- **Removed GitHub Desktop branding**: Renamed Desktop-branded symbols in `stash.ts` (`DesktopStashEntryMarker` → `StashEntryMarker`, etc.). Stripped 13 unused feature flags. Updated comments in 9 source files.
+
+### Documentation
+- **README**: Added Known Limitations section, full API reference table, error handling guide, updated architecture diagram.
+- **Examples**: Created `examples/branch-operations.ts` and `examples/create-commit.ts`. Updated imports to use `'../src/index.js'`.
+- **CHANGELOG.md**: Created with full version history since 0.1.0.
+
+---
+
+## [0.1.2] — 2026-06-13
+
+### Added
+- **Public API expansion**: `src/index.ts` now exports all 40+ git operations and all domain models through barrel files.
+- **New barrel file**: `src/models/index.ts` with explicit type-only re-exports (handles naming conflicts like `ComputedAction` and `SubmoduleStatus`).
+- **Missing git operations**: Added `add`, `cherry-pick`, `clean`, `lfs`, `merge-tree`, `reorder`, `squash`, `stage`, `stash`, `update-index`, `worktree-include` to the git barrel.
+- **Documentation**: Rewrote README with full API reference, usage examples, and architecture docs.
+- **Examples**: Added branch operations and commit creation examples.
+
+### Changed
+- **ESM imports**: Added `.js` extensions to all 150+ relative imports across 71 source files for full Node.js ESM compatibility.
+- **Git barrel** (`src/git/index.ts`): Expanded from 35 to 46 module exports with `.js` extensions.
+
+### Fixed
+- **Runtime crash**: Fixed `localStorage.getItem('git-trace')` → `process.env.GIT_TRACE ?? '0'` in `authentication.ts` which was blocking all remote operations (push, pull, fetch, clone) in Node.js/Bun.
+
+### Build
+- **tsconfig.json**: Added `outDir: "dist"` and `rootDir: "src"` settings.
+- **package.json**: Added deep import paths via `"./*"` export pattern, `types` field, and build/prepublish scripts.
+
+---
+
+## [0.1.1] — 2026-06-07
+
+### Added
+- Initial public release extracted from GitHub Desktop.
+- Git operations: status, commit, log, branch, merge, rebase, push, pull, fetch, stash, cherry-pick, reset, diff, and more.
+- Domain models: Repository, Commit, Branch, Status, Diff, StashEntry, Merge, Rebase, and more.
+- Authentication support for HTTPS and SSH.
+- LFS support stubs.
+- Proxy resolution.
+- Submodule support.
+
+### Notes
+- This is a fork of [desktop/desktop](https://github.com/desktop/desktop)'s Git backend, extracted and adapted as a standalone library.
+- Several subsystems are stubbed: progress callbacks, hook interception, and the LFS trampoline environment.
+
+---
+
+## [0.1.0] — 2026-06-07
+
+### Added
+- Initial setup: package scaffolding, tsconfig, and project structure.
+- Core Git execution layer (`git/exec.ts`, `git/core.ts`, `git/spawn.ts`).
+- Authentication, proxy resolution, and environment helpers.
+- MIT license.
+
+---
+
+[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.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
+[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
+[Unreleased]: https://github.com/parkiyong/git-chopstick-core/compare/v0.1.7...HEAD

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,81 @@
+---
+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` and `docs/` 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 run build` automatically, so no need to build before publish — but validate first anyway.
+- 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.5",
+  "version": "0.1.7",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,7 +31,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md",
+    "docs"
   ],
   "description": "Git backend library extracted from GitHub Desktop",
   "scripts": {