Add safe upgrades, prunable rules, and target validation; publish 0.3.0

[KingEmma7]

Summary

This release adds safe, ownership-aware upgrades, stronger target validation and doctor diagnostics, project detection, template fixes, and a GitHub Pages demo.

Safe upgrade contract

init --update now treats .cursor/.cursor-os-manifest.json as an ownership ledger rather than a snapshot of everything found on disk.

• Cursor OS only records files it actually creates, restores, or refreshes.
• Files that existed before Cursor OS remain unmanaged and are never silently adopted, even if they happen to match the current template byte-for-byte.
• --update may refresh a managed file only when its current hash still matches the hash Cursor OS previously recorded.
• Local edits are preserved and reported as customized.
• Optional managed rules deleted during localization are persisted as pruned and are not recreated by later init or init --update runs.
• Missing required managed files are restored.
• Symlinks and other non-regular destination paths are reported as conflicts and are never followed or replaced.
• Malformed ownership manifests fail closed instead of being treated as a fresh install. Manifest writes are atomic.
• Managed files removed from a newer template are reported as obsolete; --update removes them only when they are still unchanged. Customized obsolete files are preserved.

doctor now reports ownership/update health in addition to install/localization health: stale managed files, customized files, unmanaged files, pruned optional rules, filesystem conflicts, obsolete paths, and manifest validity.

Other correctness fixes

• init, doctor, and detect validate the target directory. init may create one final directory level when its parent exists, but refuses a mistyped missing tree.
• OS/editor artifacts such as .DS_Store are ignored when enumerating the template.
• frontend.mdc uses Cursor's comma-separated glob form.
• The CLI keeps its established doctor output phrases for compatibility with scripts while adding richer diagnostics.
• Version is 0.3.0, matching the CLI documented by the README.

Demo

• demo/hero.svg renders the comparison inline on GitHub.
• demo/index.html adds playback controls and a clean recording mode.
• GitHub Pages deployment uses the current upload-pages-artifact@v4 action.
• README leads with the comparison and a step-by-step npm quick start.

Regression coverage

The existing smoke suite remains in place. A separate upgrade-safety suite now covers the state transitions most likely to cause user data loss:

• pre-existing file -> install -> future template change -> --update preserves it;
• optional managed rule -> localization deletion -> future init/update preserves pruning;
• missing required managed file -> restored;
• malformed manifest -> update refused and doctor reports it;
• missing/legacy manifest -> existing files remain unmanaged;
• destination symlink -> conflict, linked target untouched;
• obsolete unchanged managed file -> only --update removes it;
• obsolete customized managed file -> preserved.

Verification

• npm test
• package.json parses
• npm tarball packaging/E2E install succeeds
• Node 20 and 22 smoke suites pass on Ubuntu and Windows
• Installer does not silently adopt pre-existing files
• Pruned optional rules remain pruned across upgrades
• Symlink/non-regular destinations are never followed or overwritten
• Invalid manifests fail closed

CI run #15 is green across the packaging/E2E job and all four Node/OS smoke-matrix jobs.

Contribution bar

• This improves concrete agent behavior and upgrade safety.
• This does not duplicate another layer.
• Core installer behavior remains framework-neutral.

Template impact

• Template files changed; README, CHANGELOG, and smoke expectations are part of the release diff.

Notes for reviewers

The most important invariant to review is ownership: a path must never become eligible for automatic overwrite merely because Cursor OS observed its contents. Only paths Cursor OS can prove it wrote are managed by --update.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.