Merge pull request #6 from morluto/feat/npm-onboarding

feat(onboarding): add npm setup and release flow

Author: morluto

.github/workflows/ci.yml

@@ -249,3 +249,15 @@ jobs:
           cache: true
       - name: Run integration tests
         run: go test -v -race -count=1 -tags=integration -timeout 300s ./...
+
+  npm:
+    name: npm launcher and package metadata
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npm run test:npm
+      - run: npm pack --dry-run

.github/workflows/release.yml

@@ -6,24 +6,80 @@ on:
       - "v*"
 
 permissions:
-  contents: write
-  packages: write
+  contents: read
 
 jobs:
+  validate:
+    name: Validate release commit
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: go test ./...
+      - run: go vet ./...
+      - run: test -z "$(gofmt -l .)"
+      - run: npm run test:npm
+
+  build-npm-binaries:
+    name: Build npm binary ${{ matrix.target }}
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { target: darwin-arm64, goos: darwin, goarch: arm64, binary: gitcontribute }
+          - { target: darwin-x64, goos: darwin, goarch: amd64, binary: gitcontribute }
+          - { target: linux-arm64, goos: linux, goarch: arm64, binary: gitcontribute }
+          - { target: linux-x64, goos: linux, goarch: amd64, binary: gitcontribute }
+          - { target: win32-x64, goos: windows, goarch: amd64, binary: gitcontribute.exe }
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Build native binary
+        shell: bash
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: "0"
+          TARGET: ${{ matrix.target }}
+          BINARY: ${{ matrix.binary }}
+          VERSION: ${{ github.ref_name }}
+        run: |
+          mkdir -p "dist/$TARGET"
+          go build -trimpath -ldflags "-s -w -X main.version=${VERSION#v}" -o "dist/$TARGET/$BINARY" ./cmd/gitcontribute
+      - uses: actions/upload-artifact@v7
+        with:
+          name: native-${{ matrix.target }}
+          path: dist/${{ matrix.target }}/${{ matrix.binary }}
+          if-no-files-found: error
+
   goreleaser:
     name: Build and release
+    needs: validate
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-
       - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
           cache: true
-
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v7
         with:
@@ -33,24 +89,79 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  publish-npm:
+    name: Publish npm package
+    needs: [validate, build-npm-binaries, goreleaser]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment: npm
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: native-*
+          path: dist
+      - name: Normalize downloaded artifact layout
+        shell: bash
+        run: |
+          for directory in dist/native-*; do
+            target=${directory##*/native-}
+            mkdir -p "dist/$target"
+            cp "$directory"/* "dist/$target/"
+            if [[ $target != win32-* ]]; then chmod +x "dist/$target/gitcontribute"; fi
+          done
+      - name: Verify release version
+        shell: bash
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: node scripts/verify-release-version.mjs "${VERSION#v}"
+      - run: npm run test:npm
+      - run: npm run build:npm
+      - name: Build and inspect npm tarball
+        shell: bash
+        run: |
+          npm pack --pack-destination dist
+          tarball=$(find dist -maxdepth 1 -name 'gitcontribute-*.tgz' -print -quit)
+          test -n "$tarball"
+          test "$(stat -c %s "$tarball")" -le 100000000
+          sha256sum "$tarball" | sed 's#  dist/#  #' > dist/npm-SHA256SUMS
+          npm install --prefix "$RUNNER_TEMP/npm-smoke" --ignore-scripts --no-audit --no-fund "$tarball"
+          "$RUNNER_TEMP/npm-smoke/node_modules/.bin/gitcontribute" metadata --json
+      - name: Publish npm package
+        run: npm publish --provenance --access public
+      - name: Attach npm package to GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          tarball=$(find dist -maxdepth 1 -name 'gitcontribute-*.tgz' -print -quit)
+          gh release upload "${{ github.ref_name }}" "$tarball" dist/npm-SHA256SUMS --clobber
+
   release-notes:
     name: Generate release notes
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    needs: goreleaser
+    needs: [goreleaser, publish-npm]
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-
       - name: Generate changelog
         uses: orhun/git-cliff-action@v4
         with:
           config: cliff.toml
           args: --latest --strip all
         env:
           OUTPUT: CHANGELOG.md
-
       - name: Upload release notes
         uses: softprops/action-gh-release@v2
         with:

.gitignore

@@ -1,6 +1,7 @@
 # === Binaries ===
 /bin/
 /dist/
+/npm/bin/native/
 *.exe
 *.exe~
 *.dll

README.md

@@ -14,16 +14,37 @@ persistence invariants, and side-effect rules. See
 
 ## Install
 
-GitContribute requires Go 1.26 or newer. A C toolchain is not required because
-the SQLite driver is pure Go.
+The recommended installation and onboarding command requires Node.js 18 or
+newer. It runs the native GitContribute binary bundled in the npm package; Go
+and a C toolchain are not required.
 
 ```sh
-go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest
+npx gitcontribute@latest setup
+```
+
+Install a persistent shell command instead:
+
+```sh
+npm install --global gitcontribute@latest
+gitcontribute setup
 ```
 
-Or build a checkout:
+Projects that want to pin the CLI version can install it as a development
+dependency and invoke it through `npx` or package scripts:
 
 ```sh
+npm install --save-dev gitcontribute
+npx gitcontribute setup --codex --yes
+```
+
+The npm package has no install lifecycle and does not download an executable at
+install time. It contains native binaries for macOS ARM64/x64, Linux
+ARM64/x64, and Windows x64.
+
+Developers with Go 1.26 or newer can install from source or build a checkout:
+
+```sh
+go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest
 go build -o gitcontribute ./cmd/gitcontribute
 ```
 
@@ -35,18 +56,40 @@ You also need a `git` executable. Optional helpers that the CLI can use:
 ## Quick start
 
 ```sh
-gitcontribute init
-gitcontribute configure --token-source=env --token-source-key=GITHUB_TOKEN
-gitcontribute sync owner/repo
-gitcontribute search threads "connection timeout" --repo owner/repo --json
-gitcontribute dossier build owner/repo --json
+npx gitcontribute@latest setup
+npx gitcontribute@latest sync owner/repo
+npx gitcontribute@latest search threads "connection timeout" --repo owner/repo --json
+npx gitcontribute@latest dossier build owner/repo --json
 ```
 
 Run `gitcontribute --help` and `gitcontribute <command> --help` for full flag
 reference.
 
 ## Initialization, configuration, and authentication
 
+`gitcontribute setup` is the normal entry point. It initializes the local
+corpus, selects a GitHub authentication source, and registers the MCP server
+with Codex and/or Claude Code. It remains local-only: adding `--repo owner/repo`
+creates a discovery source but does not contact GitHub or start a sync.
+
+```sh
+gitcontribute setup                              # interactive
+gitcontribute setup --codex --yes               # configure Codex
+gitcontribute setup --all-clients --yes          # configure every supported client
+gitcontribute setup --codex --mcp-version latest --yes
+gitcontribute setup --token-source env \
+  --token-source-key GITHUB_TOKEN --yes
+gitcontribute setup --codex --dry-run --json     # inspect without writing
+gitcontribute remove --all-clients --yes         # remove only MCP registrations
+gitcontribute upgrade --check                    # compare with the latest npm release
+gitcontribute upgrade --yes                      # update a global npm installation
+```
+
+When setup runs through `npx`, client configuration launches a released npm
+version rather than recording an ephemeral npm-cache path. `remove` never
+deletes the corpus or GitContribute application configuration. See
+[the onboarding design](docs/onboarding.md) for the complete contract.
+
 `gitcontribute init` creates the default corpus database and directories if they
 do not exist. It does not fetch anything from GitHub.
 

cmd/gitcontribute/main.go

@@ -16,7 +16,8 @@ import (
 	"github.com/morluto/gitcontribute/internal/tui"
 )
 
-const version = "dev"
+// version is replaced from the release tag with -ldflags.
+var version = "dev"
 
 func main() {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)

docs/onboarding.md

@@ -0,0 +1,59 @@
+# Onboarding and npm distribution
+
+The primary installation and onboarding entry point is:
+
+```sh
+npx gitcontribute@latest setup
+```
+
+GitContribute remains a native Go application. The `gitcontribute` npm package
+contains a small Node.js launcher and precompiled binaries for macOS ARM64/x64,
+Linux ARM64/x64, and Windows x64. Installation has no lifecycle script
+and performs no binary download. The launcher chooses the host binary at run
+time and forwards standard streams, arguments, signals, and its exit status.
+
+## Setup contract
+
+Setup is a local capability. It may create the GitContribute configuration and
+corpus, register the MCP server with selected coding clients, and add an
+explicit repository source. It does not synchronize a repository, access
+GitHub, execute repository-controlled code, or mutate GitHub.
+
+The setup engine plans and applies only GitContribute-owned entries:
+
+- `[mcp_servers.gitcontribute]` in Codex TOML configuration;
+- `mcpServers.gitcontribute` in Claude JSON configuration.
+
+Unrelated configuration is preserved. Repeated setup is idempotent. `remove`
+deletes only those entries; it never removes the GitContribute corpus or its
+application configuration. `--dry-run` performs validation without writes,
+and `--json` exposes per-step results for automation.
+
+When invoked through npm, setup records an npm launcher such as:
+
+```text
+npx --yes --package=gitcontribute@0.1.0 -- gitcontribute mcp
+```
+
+It never records a temporary executable from the npm cache. Development builds
+use `gitcontribute@latest`; released builds use their exact version so a client
+configuration is reproducible. Re-running setup with a newer release updates
+the registration. `--mcp-version latest` opts into following the latest npm
+release instead.
+
+## Release contract
+
+One tag version controls the Go binaries and npm package. Release automation:
+
+1. cross-compiles all supported native binaries with `CGO_ENABLED=0`;
+2. injects the tag version into the Go executable;
+3. assembles one npm package containing every binary;
+4. verifies the package has no install lifecycle;
+5. installs the tarball with `--ignore-scripts` and runs a smoke test;
+6. enforces a 100 MB compressed-package ceiling;
+7. publishes the npm package with provenance;
+8. creates a matching GitHub release.
+
+The npm environment must be configured for trusted publishing before the first
+release. Package publication is an external mutation and is performed only by
+the tag-triggered release workflow.

internal/app/control.go

@@ -15,6 +15,7 @@ import (
 	"github.com/morluto/gitcontribute/internal/cli"
 	"github.com/morluto/gitcontribute/internal/config"
 	"github.com/morluto/gitcontribute/internal/github"
+	clientsetup "github.com/morluto/gitcontribute/internal/setup"
 )
 
 // Metadata reports deterministic application and local capability metadata.
@@ -172,7 +173,7 @@ func (s *Service) ControlStatus(ctx context.Context) (*cli.ControlStatusResult,
 // Doctor performs bounded local diagnostics. It reports authentication source
 // availability but never returns credential values or command output.
 func (s *Service) Doctor(ctx context.Context) (*cli.DoctorResult, error) {
-	checks := make([]cli.DoctorCheck, 0, 7)
+	checks := make([]cli.DoctorCheck, 0, 9)
 	add := func(name string, required bool, err error, success string) {
 		check := cli.DoctorCheck{Name: name, Required: required, Status: "ok", Message: success}
 		if err != nil {
@@ -216,6 +217,16 @@ func (s *Service) Doctor(ctx context.Context) (*cli.DoctorResult, error) {
 
 	add("rg", false, lookPathError("rg"), "ripgrep is available")
 
+	if home := s.paths.HomeDir(); home != "" {
+		for _, client := range clientsetup.Detect(home) {
+			registered, _, checkErr := clientsetup.CheckRegistration(client, home)
+			if checkErr == nil && !registered {
+				checkErr = errors.New("client detected but GitContribute MCP registration is absent")
+			}
+			add("mcp_"+string(client), false, checkErr, "GitContribute MCP registration is present")
+		}
+	}
+
 	healthy := true
 	for _, check := range checks {
 		if check.Required && check.Status == "error" {