Kanvibe Release Deploy

KanVibe Release Deploy

Overview

This skill coordinates the KanVibe desktop release workflow from version selection to DMG publication, Homebrew cask update, release PR creation, and automatic merge. It is intentionally release-operator focused and may only be invoked from a clean, up-to-date local dev checkout: read and report the current package.json version, ask the user for the target release version, update the package version, run the pnpm run deploy DMG build, launch the built app and confirm it actually starts, get explicit approval for the release notes, upload the exact DMG artifact to the rookedsysc/kanvibe GitHub release, update the separate Homebrew cask repository with the same version and SHA-256, create the KanVibe release PR, then merge the release and promotion PRs automatically once checks and review-thread gates pass.

The smoke test in step 3.5 is not optional. Signing, notarization, stapling, and checksum verification all pass on a bundle whose app cannot start, and shipping one of those is how KanVibe 1.0.4 reached users.

The only routine user gates are target-version selection and release-note approval. After those are approved, do not ask for additional confirmation for build, release publication, cask update, PR creation, auto-merge enablement, or merge completion unless a blocker or branch-policy violation appears.

Before touching the cask, read references/homebrew-cask-repository.md. The cask repository location and cask file path live there so this skill stays portable if the tap checkout moves.

When to Use

Use this skill when the user asks to:

• deploy or release KanVibe desktop;
• run pnpm run deploy for KanVibe release packaging;
• bump the KanVibe package version for a release;
• create release notes or a GitHub release that includes dist/KanVibe-<version>.dmg;
• create and merge the KanVibe release PR or pinned main-promotion PR after a desktop release;
• update the KanVibe Homebrew cask version or checksum;
• specifically release a version such as 1.0.2 where the expected DMG is dist/KanVibe-1.0.2.dmg.

Do not use this skill for docs-site deploys, Linux-only package checks, routine feature PRs that do not publish a desktop release, or any checkout that is not clean, up-to-date dev.

Release Invariants

• The GitHub release tag is the raw package version, for example 1.0.2, not v1.0.2.
• The DMG filename is KanVibe-<version>.dmg because electron-builder.yml sets dmg.artifactName: "KanVibe-${version}.${ext}".
• The cask URL expects the same raw version tag: https://github.com/rookedsysc/kanvibe/releases/download/#{version}/KanVibe-#{version}.dmg.
• Use the SHA-256 of the final DMG produced after the version bump and pnpm run deploy, not an earlier artifact.
• pnpm run deploy is the release build command for this workflow. It runs scripts/dist-deploy.cjs, which builds the DMG, codesigns, notarizes, staples, verifies the packaged dependencies, and prints the SHA-256.
• pnpm run deploy performs macOS signing/notarization, so it must run on macOS with Apple signing tools configured. Do not fabricate build, notarization, or checksum output from Linux.
• A signed, notarized, correctly-checksummed DMG can still be an app that cannot start. Signing and notarization say nothing about whether the bundle contains the dependencies it needs. Never publish without launching the built app (step 3.5).
• Never add a packageManager field to package.json. electron-builder resolves the package manager from that field before anything else, which selects a dependency collector that drops transitive dependencies from app.asar and ships an app that crashes on startup. Pin the pnpm version through pnpm/action-setup's version input in CI instead.
• Run the release under pnpm 10. Because there is no packageManager pin, corepack may resolve pnpm 11, which ignores pnpm.onlyBuiltDependencies and skips every native build script. Verify with pnpm --version during preflight.
• Invoke this skill only from a clean, up-to-date local dev checkout. Stop on main, feature branches, existing release branches, detached HEADs, dirty worktrees, or a local dev HEAD that differs from origin/dev.
• The release source is always origin/dev. Do not accept, infer, or ask about alternate source branches for this workflow.
• The user's target-version selection and release-note approval authorize the remaining release actions. After those two gates, the AI should continue through release publication, cask update, release PR creation, auto-merge enablement, and pinned release-branch promotion to main without asking for another confirmation.
• Stop instead of auto-merging only when checks fail, required review threads remain unresolved, the PR is not mergeable, GitHub permissions are missing, the checkout is not clean/up-to-date dev, or the visible PR diff contains files outside the expected release bump scope.

1. Preflight and Version Selection

Work from the KanVibe application repository, not the Homebrew tap.

pwd
git fetch origin --prune
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "dev" ]; then
  echo "KanVibe release deploy must start from the local dev branch; current branch is ${CURRENT_BRANCH:-detached}." >&2
  exit 1
fi
if [ -n "$(git status --short)" ]; then
  echo "KanVibe release deploy must start from a clean dev worktree." >&2
  git status --short
  exit 1
fi
git pull --ff-only origin dev
if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/dev)" ]; then
  echo "Local dev must match origin/dev before cutting a release branch." >&2
  exit 1
fi
git status --short --branch
node -p "process.version"
CURRENT_VERSION=$(node -p "require('./package.json').version")
printf 'Current KanVibe version: %s\n' "$CURRENT_VERSION"

# The release build must run under pnpm 10; pnpm 11 ignores pnpm.onlyBuiltDependencies
# and silently skips every native build script.
PNPM_VERSION=$(pnpm --version)
printf 'pnpm: %s\n' "$PNPM_VERSION"
case "$PNPM_VERSION" in
  10.*) ;;
  *) echo "Release build requires pnpm 10; found ${PNPM_VERSION}." >&2; exit 1 ;;
esac

# package.json must NOT carry a packageManager field: it forces electron-builder into a
# dependency collector that drops transitive dependencies from app.asar.
if node -p "require('./package.json').packageManager" | grep -qv undefined; then
  echo "package.json has a packageManager field; remove it before releasing." >&2
  exit 1
fi

gh auth status
gh release list --limit 5 --repo rookedsysc/kanvibe

If pnpm --version is not 10.x, do not silently continue and do not add a packageManager field to fix it. Install or select pnpm 10 for this shell, then rerun preflight.

After printing the current version, ask the user which version to release before editing files:

현재 KanVibe 버전은 <CURRENT_VERSION>입니다. 배포 버전을 몇으로 올릴까요? 예: 1.0.2

Only proceed after the user supplies the target version. If the original user prompt already supplied the exact target version, echo the current version and target version back to the user and proceed without asking again. This is the first of the two routine user gates; after the target version is selected, do not ask again until release-note review.

Validate these before proceeding:

1. The target version is a plain x.y.z value such as 1.0.2; do not include a leading v or any prerelease/build suffix (for example 1.0.3-beta.1). The desktop update checker (src/desktop/shared/releaseUpdates.ts) only parses ^v?\d+\.\d+\.\d+$, so a prerelease tag would be invisible to in-app updates.
2. The target version is different from the current package.json version unless the user explicitly wants to rebuild the same version.
3. Work from a clean local dev checkout before creating the release branch. If the current branch is not dev, stop and tell the user to rerun the skill from dev; do not silently proceed from main, a feature branch, or an existing release branch.
4. Confirm local dev matches origin/dev after git fetch/git pull --ff-only. The release source is always origin/dev; do not ask about or honor alternate source branches in this workflow.
5. The active GitHub account can create releases in rookedsysc/kanvibe.
6. If the release build requires macOS signing tools, the host is macOS:

uname -s

If the required host/tooling is unavailable, stop and report the blocker. Do not fake pnpm run deploy, DMG, notarization, or checksum output.

After the target version is selected, create a dedicated release branch from the current origin/dev SHA. Do not use an existing release branch as the invocation point; reuse an existing release branch only after the dev preflight passes and only when it is the same release version with no unrelated files. This keeps the release PR narrow and prevents dirty local feature work from leaking into the release.

TARGET_VERSION="<version supplied by user>"
BASE_BRANCH="dev"
RELEASE_BRANCH="release/${TARGET_VERSION}"
RELEASE_WT="/home/rookedsysc/Documents/kanvibe/kanvibe__worktrees/release-${TARGET_VERSION}"

git fetch origin --prune
SOURCE_SHA=$(git rev-parse "origin/${BASE_BRANCH}")
git worktree add -b "$RELEASE_BRANCH" "$RELEASE_WT" "$SOURCE_SHA"
cd "$RELEASE_WT"
printf 'Release source SHA: %s\n' "$SOURCE_SHA"
git status --short --branch

If the release worktree path or branch already exists, re-read its status and PR state before reusing it. Reuse only when it is the same release version and contains no unrelated files.

2. Update package.json Version

After the user chooses the target version, update package.json before running the build. Use a deterministic script instead of manually editing JSON punctuation.

The same script also keeps the tracked package-lock.json in sync, because its top-level version and root packages[""].version fields otherwise keep advertising the previous release and npm-based install/packaging paths would see conflicting metadata. The format check rejects prerelease/build suffixes so the published tag always matches the desktop update checker.

Both files contain several "version" lines, and only three of them belong to the release. The replacement therefore anchors on whole-line exact matches and, inside package-lock.json, on the packages[""] block boundary. It never matches substrings and never treats indentation as optional.

Every anchor is resolved in memory before the first writeFileSync, so a failed anchor leaves both files untouched. That ordering matters: a partial bump would leave package.json on the new version while package-lock.json stayed on the old one, and the already at ${version} guard would then reject the retry until someone manually ran git checkout -- package.json.

TARGET_VERSION="<version supplied by user>"
node -e '
const fs = require("node:fs");
const version = process.argv[1];
if (!/^\d+\.\d+\.\d+$/.test(version)) {
  throw new Error(`Invalid release version (expected plain x.y.z, no v/prerelease): ${version}`);
}

const current = JSON.parse(fs.readFileSync("package.json", "utf8")).version;
if (current === version) {
  throw new Error(`package.json is already at ${version}; pick a different target version`);
}

const rootNeedle = `  "version": "${current}",`;
const rootReplacement = `  "version": "${version}",`;

const findExactlyOneLine = (label, lines, needle) => {
  const matches = lines.reduce((indexes, line, index) => (line === needle ? [...indexes, index] : indexes), []);
  if (matches.length !== 1) {
    throw new Error(`${label}: expected exactly 1 line matching ${JSON.stringify(needle)}, got ${matches.length}`);
  }
  return matches[0];
};

// package.json: the release version is the only two-space-indented version line.
// devEngines.packageManager.version is indented deeper and must survive untouched.
const packageLines = fs.readFileSync("package.json", "utf8").split("\n");
packageLines[findExactlyOneLine("package.json top-level version", packageLines, rootNeedle)] = rootReplacement;

const hasLock = fs.existsSync("package-lock.json");
let lockLines = null;
if (hasLock) {
  lockLines = fs.readFileSync("package-lock.json", "utf8").split("\n");
  lockLines[findExactlyOneLine("package-lock.json top-level version", lockLines, rootNeedle)] = rootReplacement;

  // packages[""] is the root package block. Its six-space version line is textually identical
  // to the one in every dependency that happens to sit on the same version, so scan only
  // between the block opener and its closing brace.
  const blockStart = lockLines.indexOf(`    "": {`);
  if (blockStart === -1) {
    throw new Error("package-lock.json: packages[\"\"] block opener not found");
  }
  const innerNeedle = `      "version": "${current}",`;
  let innerIndex = -1;
  for (let i = blockStart + 1; i < lockLines.length; i++) {
    if (lockLines[i] === "    },") break;
    if (lockLines[i] === innerNeedle) {
      innerIndex = i;
      break;
    }
  }
  if (innerIndex === -1) {
    throw new Error("package-lock.json: packages[\"\"].version line not found inside the root package block");
  }
  lockLines[innerIndex] = `      "version": "${version}",`;
}

// Every anchor is resolved by this point, so the writes happen together or not at all.
// Writing package.json before the lock anchors were checked used to leave a half-bumped
// tree on a lock failure, and the "already at" guard above then refused the retry.
fs.writeFileSync("package.json", packageLines.join("\n"));
if (hasLock) {
  fs.writeFileSync("package-lock.json", lockLines.join("\n"));
}
' "$TARGET_VERSION"

node -p "require('./package.json').version"
node -p "require('./package.json').devEngines.packageManager.version"
test -f package-lock.json && node -e 'const lock = require("./package-lock.json"); console.log(lock.version, lock.packages[""].version);'
git diff --numstat -- package.json package-lock.json

The bump is correct only when all four hold:

1. package.json version and both package-lock.json versions print the user-selected target version. Re-reading them through require also proves the files still parse as JSON.
2. devEngines.packageManager.version still prints the pnpm pin, not the release version.
3. git diff --numstat reports 1 1 package.json and 2 2 package-lock.json. Any other count means the edit escaped its anchors.
4. Nothing else appears in git status.

Commit the version bump (including package-lock.json) with the release changes or ensure the release tag targets a commit that already contains the updated files.

Why the anchors look like this

Three earlier approaches were tried and discarded. Do not reintroduce them.

The third defect stayed invisible in 1.1.0 only by luck: the then-current version 1.0.10 happened to match no dependency. In 1.2.0 the current version was 1.1.0, a common value that twenty dependencies in package-lock.json also carried, and the two-space needle matched 22 places. The safety of that anchor depended on how rare the current version string happened to be — which is not a property a release procedure may rely on.

3. Build the Versioned DMG

KanVibe requires Node 24.x. If node -p "process.version" is not v24, switch to Node 24 with the local toolchain available on that Mac before running the release build.

Run the release build command after the version bump:

pnpm install --frozen-lockfile
pnpm run deploy

Expected artifact for version 1.0.2:

dist/KanVibe-1.0.2.dmg

For any version, derive and verify the artifact path from package.json:

VERSION=$(node -p "require('./package.json').version")
DMG="dist/KanVibe-${VERSION}.dmg"
test -f "$DMG"
shasum -a 256 "$DMG"

Keep the checksum from this final DMG for the cask update. If you rebuild for any reason, the checksum changes — always re-hash the artifact you are actually publishing.

scripts/dist-deploy.cjs prints the dependency-collection mode and a packaging guard result. Both lines must appear and must look like this:

• searching for node modules  pm=npm  searchDir=/Users/<user>/Documents/kanvibe/kanvibe
[kanvibe] packaged node_modules verified: 278 packages

If the collector reports pm=pnpm, the build is wrong even though it will succeed: that collector silently omits transitive dependencies. Check that package.json has no packageManager field and that the deploy script is invoking electron-builder directly, then rebuild. The guard aborts the deploy when required modules are missing, but treat pm=pnpm itself as a failure signal.

Notarization blocked by an Apple agreement

When pnpm run deploy fails with HTTP status code: 403. A required agreement is missing or has expired, this is an Apple account state problem, not a build problem. Do not rebuild to retry — check the credential cheaply instead:

xcrun notarytool history --key "$APPLE_API_KEY" --key-id "$APPLE_API_KEY_ID" --issuer "$APPLE_API_ISSUER"

If a previous release notarized successfully with the same key and team, the configuration is fine and only the agreement changed. The Account Holder must accept the pending agreement at developer.apple.com, and propagation to the notary service takes a few minutes. Poll the command above and resume the build once it returns history.

3.5. Smoke-Test the Built App (hard gate)

Do not publish a release without this step. Code signing, notarization, stapling, and checksum verification all pass on a bundle whose app cannot start. KanVibe 1.0.4 shipped exactly that way: the DMG was signed, notarized, stapled, and its checksum matched, but app.asar was missing seven transitive dependencies and the app died on launch with Cannot find module 'ms'.

Mount the DMG you are about to publish, copy the app out, launch it against a throwaway data directory, and read that run's own diagnostics log:

VERSION=$(node -p "require('./package.json').version")
SMOKE_DATA=$(mktemp -d /tmp/kanvibe-smoke-XXXXXX)
LOG="$SMOKE_DATA/logs/kanvibe-desktop.log"

hdiutil attach "dist/KanVibe-${VERSION}.dmg" -nobrowse -readonly -quiet
MOUNT="/Volumes/KanVibe ${VERSION}-arm64"
spctl -a -t exec -vv "$MOUNT/KanVibe.app"
rm -rf /tmp/KanVibe-smoke.app
cp -R "$MOUNT/KanVibe.app" /tmp/KanVibe-smoke.app
hdiutil detach "$MOUNT" -quiet

open -n --env "KANVIBE_APP_DATA_DIR=$SMOKE_DATA" -a /tmp/KanVibe-smoke.app
sleep 15

pgrep -f "KanVibe-smoke.app/Contents/MacOS/KanVibe" >/dev/null || { echo "app exited during startup" >&2; exit 1; }
wc -l "$LOG"
grep -icE "cannot find module|MODULE_NOT_FOUND|unhandled rejection" "$LOG"
grep -c "invoke-succeeded" "$LOG"

pkill -f "KanVibe-smoke.app"
rm -rf /tmp/KanVibe-smoke.app "$SMOKE_DATA"

The release may proceed only when all four hold:

1. spctl -a -t exec reports accepted and source=Notarized Developer ID.
2. The process is still alive after the sleep.
3. The module-error count is 0.
4. The invoke-succeeded count is greater than zero, which proves the database and IPC layer actually came up rather than the window merely opening.

Read the counts from $LOG inside $SMOKE_DATA, never from ~/Library/Application Support/kanvibe. Do not delete the user's log to get a clean read.

Why the smoke run is isolated

electron/main.js calls applyAppDataDirectoryOverride(app, process.env) at module load, well before app.whenReady(). That helper (electron/runtimeEnvironment.js) turns KANVIBE_APP_DATA_DIR into app.setPath("userData", ...), and the diagnostics log path is derived from userData (electron/diagnostics.js), so the smoke run's database and its log both follow the temporary directory. The user's installed instance, its data, and its existing log are left alone — during the 1.2.0 smoke the verdict came from a 43-line isolated log while /Applications/KanVibe.app kept running untouched.

open --env applies the variable to the launched app only and does not touch the shell, so this stays inside the repository's runtime-environment safety rules. open -n is required: without it macOS just focuses an already-running instance instead of starting the copy under test.

If the smoke test fails, stop. Do not publish, do not update the cask, and do not open PRs. Diagnose the bundle first; app.asar contents can be listed from its header:

# Run this twice: once for the candidate bundle, once for a build known to be good.
ASAR_PATH="dist/mac-arm64/KanVibe.app/Contents/Resources/app.asar"
# ASAR_PATH="/Applications/KanVibe.app/Contents/Resources/app.asar"
node -e '
const fs=require("fs");
const p=process.argv[1] || "dist/mac-arm64/KanVibe.app/Contents/Resources/app.asar";
const fd=fs.openSync(p,"r");
const b=Buffer.alloc(16); fs.readSync(fd,b,0,16,0);
const hb=Buffer.alloc(b.readUInt32LE(12)); fs.readSync(fd,hb,0,hb.length,16);
const h=JSON.parse(hb.toString("utf8").replace(/\0+$/,""));
fs.closeSync(fd);
const entries=Object.entries(h.files.node_modules.files);
const expanded=entries.reduce((n,[name,entry])=>n+(name.startsWith("@")?Object.keys(entry.files??{}).length:1),0);
console.log(`${entries.length} top-level entries (scopes counted once)`);
console.log(`${expanded} packages with scopes expanded  <-- matches the build guard`);
' "$ASAR_PATH"

The two numbers are both correct and they are not interchangeable. The build guard line packaged node_modules verified: N packages comes from readAsarNodeModuleNames() in scripts/dist-deploy.cjs, which expands @scope/name into one entry per scoped package, so it always reports the larger number. Counting the top-level keys instead reports the smaller one. Reading the smaller number as if it were the guard's makes a healthy build look like the 1.0.4 dependency-loss failure.

Do not judge either number against a remembered absolute value; package counts move whenever dependencies change. Judge by comparison: rerun the same snippet with ASAR_PATH pointed at a build known to be good — the installed /Applications/KanVibe.app/Contents/Resources/app.asar is the convenient one — and compare it with the candidate bundle. The || fallback rather than ?? is deliberate, because an unset ASAR_PATH still passes an empty-string argument that ?? would accept as a path.

4. Create or Update the GitHub Release

Draft release notes in a temporary markdown file. Match the existing release-note tone: concise sections such as ## New Features, ## Improvements and Stability, and ## Packaging Note. Include a packaging note naming the exact DMG artifact, for example:

## Packaging Note

- The version was updated from `1.0.1` to `1.0.2` before building.
- The DMG artifact is `KanVibe-1.0.2.dmg`.

Review release notes with the user before publishing

Publishing a GitHub release is outward-facing, so the release notes must be reviewed and approved by the user before any gh release create or gh release edit runs. This is the second and final routine user gate. After approval, continue through commit/push, release publication, cask update, release PR creation, and auto-merge without asking for more confirmation unless a blocker appears.

1. Keep the original English notes in the temporary markdown file ($RELEASE_NOTES).
2. Present both versions to the user in the same message:
   • the original English release notes, exactly as they will be published;
   • a Korean translation of the same notes, clearly labeled as a translation for review only.
3. Ask the user to approve or request changes. Treat this as a hard gate: do not proceed to create or edit the release until the user explicitly approves.
4. If the user requests edits, update $RELEASE_NOTES with the corrected English text, re-translate, and present both versions again. Repeat until approved.
5. Only the approved English notes file is published; the Korean translation is for the user's review and is not uploaded unless the user explicitly asks for bilingual release notes.
6. Once approved, do not ask separately about creating the release PR or merging it; those actions are part of the authorized release automation.

Create the release with the DMG asset only after the user approves the notes. Use the raw version tag and upload the generated DMG, not a directory or renamed copy.

After release-note approval, commit and push the release branch before deriving the tag target. The target SHA must already exist in GitHub, and the visible release PR diff must stay limited to the version bump files. If extra files appear, stop and report the blocker instead of tagging or merging.

VERSION=$(node -p "require('./package.json').version")
DMG="dist/KanVibe-${VERSION}.dmg"
RELEASE_NOTES="/tmp/kanvibe-release-${VERSION}.md"
BASE_BRANCH="dev"
RELEASE_BRANCH="${RELEASE_BRANCH:-release/${VERSION}}"

# Verify the release branch diff is only the expected version bump against the required dev base.
git fetch origin --prune
git diff --name-status "origin/${BASE_BRANCH}"
node -e '
const { execSync } = require("node:child_process");
const baseBranch = process.argv[1];
const allowed = new Set(["package.json", "package-lock.json"]);
const files = execSync(`git diff --name-only origin/${baseBranch}`, { encoding: "utf8" })
  .trim()
  .split(/\n/)
  .filter(Boolean);
const unexpected = files.filter((file) => !allowed.has(file));
if (unexpected.length > 0) {
  throw new Error(`Unexpected release PR files: ${unexpected.join(", ")}`);
}
' "$BASE_BRANCH"

git add package.json package-lock.json
if ! git diff --cached --quiet; then
  git commit -m "chore(release): publish KanVibe ${VERSION}"
fi
git push -u origin "$RELEASE_BRANCH"

# Fail fast if the committed release branch does not contain the selected version.
if ! git diff --quiet -- package.json package-lock.json || ! git diff --cached --quiet -- package.json package-lock.json; then
  echo "package.json/package-lock.json have uncommitted changes; commit the version bump before tagging the release." >&2
  exit 1
fi
HEAD_VERSION=$(git show HEAD:package.json | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")
if [ "$HEAD_VERSION" != "$VERSION" ]; then
  echo "HEAD package.json version ($HEAD_VERSION) does not match target ($VERSION); commit the bump onto the release commit first." >&2
  exit 1
fi
TARGET_SHA=$(git rev-parse HEAD)

gh release create "$VERSION" "$DMG" \
  --repo rookedsysc/kanvibe \
  --target "$TARGET_SHA" \
  --title "KanVibe ${VERSION} Release Notes" \
  --notes-file "$RELEASE_NOTES" \
  --latest

If the release already exists, do not create a duplicate. Update the notes/title if needed and upload the DMG with --clobber:

gh release edit "$VERSION" \
  --repo rookedsysc/kanvibe \
  --title "KanVibe ${VERSION} Release Notes" \
  --notes-file "$RELEASE_NOTES"

gh release upload "$VERSION" "$DMG" \
  --repo rookedsysc/kanvibe \
  --clobber

Verify the release and asset URL:

gh release view "$VERSION" --repo rookedsysc/kanvibe --json tagName,name,assets,url
curl -I -L "https://github.com/rookedsysc/kanvibe/releases/download/${VERSION}/KanVibe-${VERSION}.dmg"