feat(cli): help agents keep Hunk skills in sync

[benvinegar]

Summary

• add hunk skill path so agents can resolve the bundled Hunk review skill from source and installed packages
• show a one-time startup notice after version changes that points users with copied skills to hunk skill path
• include the bundled skill in the prebuilt npm package and verify it through pack/install smoke coverage
• document the recommended load-or-symlink workflow in the README and changelog

Testing

• bun run typecheck
• bun test src/core/cli.test.ts src/core/updateNotice.test.ts src/core/paths.test.ts test/cli/entrypoint.test.ts
• bun run build:prebuilt:npm
• bun run check:prebuilt-pack
• bun run smoke:prebuilt-install

This PR description was generated by Pi using OpenAI o3

[greptile-apps]

Greptile Summary

This PR adds hunk skill path to resolve and print the bundled Hunk review skill path, a one-time startup notice that fires after version upgrades to help users with copied skills stay in sync, and includes the skill file in the prebuilt npm package with smoke-test verification.

The implementation is clean and well-tested. All three delivery paths (source layout via import.meta.dir ancestor-walking, prebuilt npm binary via process.execPath ancestor-walking, and the Node-only CJS wrapper fast-path) are covered by tests.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style suggestions.

The feature is well-scoped and thoroughly tested across source, npm, and compiled binary layouts. The skill path resolution, version-change notice, and prebuilt smoke tests all look correct. The only finding is a minor inconsistency in the CJS wrapper's lack of an existence guard, which won't cause real-world failures because the skill file is verified to be present in the package via check-prebuilt-pack.

bin/hunk.cjs — minor existence-check inconsistency in the skill path fast-path; all other files look clean.

Important Files Changed

Filename	Overview
src/core/paths.ts	Adds resolveBundledHunkReviewSkillPath with multi-root, multi-candidate ancestor-walking to locate the skill across source, npm, and prebuilt binary layouts.
src/core/updateNotice.ts	Adds resolveStartupSkillRefreshNotice that persists lastSeenCliVersion on each startup and shows a one-time notice when the version changes; integrates cleanly before the npm dist-tag fetch.
bin/hunk.cjs	Adds a Node-only fast-path for skill path before the prebuilt binary lookup; bundledSkillPath() returns the path without verifying existence, unlike the Bun runtime which throws.
scripts/smoke-prebuilt-install.ts	New end-to-end smoke test: packs, installs, and verifies hunk skill path resolves to an existing file on a sanitized PATH without Bun available.
scripts/stage-prebuilt-npm.ts	Copies the skills/ tree into the staged meta-package and declares it in the files field.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["hunk skill path"] --> B{via bin/hunk.cjs?}
    B -- Yes --> C["bundledSkillPath()\npath.join(__dirname, '..', 'skills/hunk-review/SKILL.md')"]
    C --> D["stdout.write + exit(0)"]
    B -- No --> E["parseCli → parseSkillCommand"]
    E --> F["renderHunkReviewSkillPath()"]
    F --> G["resolveBundledHunkReviewSkillPath()"]
    G --> H{searchRoots}
    H --> I["import.meta.dir\n(source / npm bundle)"]
    H --> J["process.execPath\n(compiled binary)"]
    I --> K["findRelativePathFromAncestors\nwalk up ancestors"]
    J --> K
    K --> L{found?}
    L -- Yes --> M["return path → help output"]
    L -- No --> N["throw 'Could not locate...'"]

    subgraph Version Change Notice
    O["resolveStartupUpdateNotice"] --> P{HUNK_DISABLE_UPDATE_NOTICE=1?}
    P -- Yes --> Q["return null"]
    P -- No --> R["resolveStartupSkillRefreshNotice"]
    R --> S{version changed?}
    S -- No / first run --> T["fetch npm dist-tags → update notice or null"]
    S -- Yes --> U["return skill:VERSION notice\nskip npm fetch"]
    end

Loading

_{Reviews (1): Last reviewed commit: "feat(cli): help agents keep Hunk skills ..." | Re-trigger Greptile}