Harden local-first setup, add CI verify gate, and align commit skill by myucordero · Pull Request #270 · OpenWhispr/openwhispr

myucordero · 2026-02-12T19:50:37Z

Summary

add a verify CI job in build-and-notarize.yml that runs npm ci, npm run lint, and npm test, then gate platform packaging jobs on that verification
harden local-first developer defaults and docs (local transcription default, port consistency on 5191, private-by-default .env.example, deterministic setup guidance, and local preflight doctor command)
add contract tests for local setup expectations and include OpenWhispr-specific commit-skill assets with non-destructive git safety and repo-appropriate verification checks

Validation

npm test (9/9 passing)
npm run lint
npm run build
npm run doctor:local

Adopt local-first defaults, deterministic setup docs, and a local doctor command with TDD contract coverage. Add a verify job to build-and-notarize so lint and tests pass before platform packaging.

Retarget commit guidance and workflow checks to npm lint/test/build with non-destructive git safety and local-first defaults.

Copilot

Pull request overview

This PR hardens OpenWhispr’s local-first developer experience by standardizing dev port defaults, making local transcription the default, adding a local “doctor” preflight script, and introducing contract tests + a CI verify gate to prevent packaging jobs from running when lint/tests fail.

Changes:

Add a verify CI job (lint + tests) and gate platform packaging jobs on it.
Standardize local-first defaults (local transcription, port 5191, private-by-default .env.example) and update setup/docs accordingly.
Add contract tests + a doctor:local script plus OpenWhispr-specific “commit skill” assets.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/contracts/setup-docs-contract.test.cjs	Contract tests ensuring docs/setup script no longer promote legacy `npm run setup` path and enforce `.env.example` bootstrapping.
tests/contracts/local-first-defaults.test.cjs	Contract tests enforcing local transcription defaults and removing “cloud-first” wording.
tests/contracts/env-template-privacy.test.cjs	Contract tests ensuring `.env.example` keeps cloud keys commented and ports pinned.
tests/contracts/env-port-consistency.test.cjs	Contract tests enforcing `5191` consistency across Vite/main-process and Neon auth fallback.
src/vite.config.mjs	Change default dev server port to `5191` and read port from `VITE_DEV_SERVER_PORT` / `OPENWHISPR_DEV_SERVER_PORT`.
src/lib/neonAuth.ts	Update file:// OAuth callback port fallback and default to `5191`.
src/hooks/useSettings.ts	Default local transcription setting to enabled (`useLocalWhisper = true`).
src/helpers/devServerManager.js	Align main-process dev server default port to `5191`.
src/components/OnboardingFlow.tsx	Adjust signed-in onboarding copy to avoid “cloud-first” phrasing and emphasize local dictation.
setup.js	Bootstrap `.env` from `.env.example` (or fallback template) and update setup guidance to local-first flow.
scripts/local-doctor.js	Add `doctor:local` script to validate binaries/model caches and port/env consistency.
package.json	Add `doctor:local`, define `test`/`test:watch` via `node --test`, and pin Node engine to `>=22 <23`.
TROUBLESHOOTING.md	Update troubleshooting steps and replace FFmpeg check guidance with `doctor:local`.
README.md	Update setup guidance, environment variable docs, script list, and add local hardening notes.
LOCAL_SETUP_HARDENING_PLAN.md	Add tracking doc describing scope, TDD plan, and verification steps.
LOCAL_PERSONAL_SETUP.md	Add personal-use playbook for reproducible local-first setup and safe fork syncing.
.opencode/skills/commit/scripts/commit-workflow.ps1	Add PowerShell commit workflow with lint/test/build verification gate and safety checks.
.opencode/skills/commit/references/REFERENCE.md	Add OpenWhispr-specific commit guidance, scopes, and verification gate docs.
.opencode/skills/commit/SKILL.md	Define the commit “skill” metadata, rules, and workflow instructions.
.nvmrc	Pin local Node version to 22.
.github/workflows/build-and-notarize.yml	Add `verify` job and make linux/windows/macos build jobs depend on it.
.env.example	Make template private-by-default (comment cloud keys), and pin dev ports to `5191`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-12T19:55:30Z

README.md

 2. **Install dependencies**:
+
   ```bash
   npm install


README’s primary setup path still uses npm install, while the rest of this PR (setup.js output, LOCAL_PERSONAL_SETUP.md, and the stated goal of deterministic setup) pushes npm ci. Consider switching the README install step to npm ci (or explicitly explaining when npm install is preferred) to keep guidance consistent.

Suggested change

npm install

npm ci

Copilot · 2026-02-12T19:55:30Z

src/lib/neonAuth.ts

+  const port =
+    import.meta.env.VITE_DEV_SERVER_PORT || import.meta.env.OPENWHISPR_DEV_SERVER_PORT || "5191";


import.meta.env.OPENWHISPR_DEV_SERVER_PORT will not be available in renderer code with Vite's default envPrefix (only VITE_ variables are exposed). As a result, setting only OPENWHISPR_DEV_SERVER_PORT won’t affect this callback URL and it will fall back to VITE_DEV_SERVER_PORT/5191. Either rely solely on VITE_DEV_SERVER_PORT here, or update Vite config to expose OPENWHISPR_ via envPrefix/define and ensure it’s actually injected into the renderer build.

Suggested change

const port =

import.meta.env.VITE_DEV_SERVER_PORT || import.meta.env.OPENWHISPR_DEV_SERVER_PORT || "5191";

const port = import.meta.env.VITE_DEV_SERVER_PORT || "5191";

Copilot · 2026-02-12T19:55:30Z

.opencode/skills/commit/scripts/commit-workflow.ps1

+Pop-Location
+
+$stagedFiles = & git diff --cached --name-only
+if ($stagedFiles -match '(^|[\\/])\.env($|\.|[\\/])') {


The staged-file secret guard will also match .env.example (because the regex matches .env followed by a .), which will block committing the template file that the repo intentionally tracks. Update the pattern to allow .env.example (and other intended templates) while still blocking real .env* secret files.

Suggested change

if ($stagedFiles -match '(^|[\\/])\.env($|\.|[\\/])') {

if ($stagedFiles -match '(^|[\\/])\.env(?!\.example)($|\.|[\\/])') {

Copilot · 2026-02-12T19:55:31Z

.opencode/skills/commit/SKILL.md

+---
+name: commit
+description: Generate concise OpenWhispr commit messages and run a safe local-only commit workflow. Validate with npm lint/test/build checks and never use destructive git commands.
+compatibility: Requires git 2.35+, Node.js 22.x, npm 10+, PowerShell 5.1+ (Windows) or bash 3.x+ (macOS/Linux)


compatibility claims bash support on macOS/Linux, but this skill currently only ships a PowerShell workflow script (scripts/commit-workflow.ps1). Either add a bash equivalent or adjust the compatibility statement so users on macOS/Linux aren’t misled.

Suggested change

compatibility: Requires git 2.35+, Node.js 22.x, npm 10+, PowerShell 5.1+ (Windows) or bash 3.x+ (macOS/Linux)

compatibility: Requires git 2.35+, Node.js 22.x, npm 10+, PowerShell 5.1+ (workflow script currently provided for Windows environments)

myucordero added 2 commits February 12, 2026 15:35

feat(local): harden local-first setup and CI verification

f0e568f

Adopt local-first defaults, deterministic setup docs, and a local doctor command with TDD contract coverage. Add a verify job to build-and-notarize so lint and tests pass before platform packaging.

chore(skill): align commit skill with openwhispr workflow

cea89bd

Retarget commit guidance and workflow checks to npm lint/test/build with non-destructive git safety and local-first defaults.

Copilot AI review requested due to automatic review settings February 12, 2026 19:50

Copilot started reviewing on behalf of myucordero February 12, 2026 19:51 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Harden local-first setup, add CI verify gate, and align commit skill#270

Harden local-first setup, add CI verify gate, and align commit skill#270
myucordero wants to merge 2 commits intoOpenWhispr:mainfrom
myucordero:personal/dev-local-hardening-20260212

myucordero commented Feb 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		const port =
		import.meta.env.VITE_DEV_SERVER_PORT \|\| import.meta.env.OPENWHISPR_DEV_SERVER_PORT \|\| "5191";

	const port =
	import.meta.env.VITE_DEV_SERVER_PORT \|\| import.meta.env.OPENWHISPR_DEV_SERVER_PORT \|\| "5191";
	const port = import.meta.env.VITE_DEV_SERVER_PORT \|\| "5191";

	if ($stagedFiles -match '(^\|[\\/])\.env($\|\.\|[\\/])') {
	if ($stagedFiles -match '(^\|[\\/])\.env(?!\.example)($\|\.\|[\\/])') {

	compatibility: Requires git 2.35+, Node.js 22.x, npm 10+, PowerShell 5.1+ (Windows) or bash 3.x+ (macOS/Linux)
	compatibility: Requires git 2.35+, Node.js 22.x, npm 10+, PowerShell 5.1+ (workflow script currently provided for Windows environments)

Uh oh!

Conversation

myucordero commented Feb 12, 2026

Summary

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants