diff --git a/README.md b/README.md index 27eb23a..f225f59 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Capture the window you’re building, mark what should change, and hand the resu
-[**Download for macOS**](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1)  ·  [**Install with Homebrew**](#install)  ·  [**Get started**](#get-started) +[**Download for macOS**](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.1-preview.2)  ·  [**Install with Homebrew**](#install)  ·  [**Get started**](#get-started)

Native Swift app @@ -153,7 +153,7 @@ ContextLens prepares the context. Your agent makes the change in your codebase, ### Download -**[Download ContextLens for macOS](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1)**. Unzip it, move **ContextLens** into your Applications folder, and open it from there. +**[Download ContextLens for macOS](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.1-preview.2)**. Unzip it, move **ContextLens** into your Applications folder, and open it from there. ContextLens is in public preview. @@ -163,9 +163,20 @@ ContextLens is in public preview. brew install --cask Brendan-Lim/tap/contextlens-preview ``` +### Build from source + +If you have Xcode, you can build ContextLens yourself. macOS doesn’t show the first-launch prompt below for an app you built on your own Mac. + +```sh +git clone https://github.com/bstack-tools/ContextLens.git && cd ContextLens +scripts/build-app.sh && open dist/ContextLens.app +``` + +More detail: [Building](docs/building.md) + ### First launch -ContextLens is free and open source, and it isn’t notarized by Apple yet, so macOS asks you to confirm the first time you open it: +ContextLens is free and open source, but it isn’t notarized by Apple yet. Notarization needs a paid Apple Developer membership (US$99 a year), and this is a student project. The signing and notarization pipeline is ready for when it is. Until then, macOS asks you to confirm the first time you open a downloaded copy: 1. Open ContextLens from Applications. If macOS says it can’t verify the app, close the message. 2. Open **System Settings → Privacy & Security**, scroll down, click **Open Anyway**, and confirm. diff --git a/docs/beta-acceptance.md b/docs/beta-acceptance.md index e437e9f..822b6c7 100644 --- a/docs/beta-acceptance.md +++ b/docs/beta-acceptance.md @@ -2,7 +2,7 @@ **Reusable test matrix.** For the official baseline, 14 native engineering cases passed and five human security cases remain pending; see [release preparation](official-release-preparation.md). Rows below are blank result slots for a new isolated run, not a claim that the baseline was never tested. Use a disposable interactive macOS VM or separate Apple Silicon test Mac. Do not execute this checklist on the owner's working ContextLens installation. A new user alone does not isolate `/Applications`, Homebrew's Caskroom/CLI links or shared installations; use it only on a dedicated test machine or with a separately verified isolated installation. A custom `--appdir` alone is insufficient. -The published Homebrew `0.3.0-preview.1` and the **0.3.1/build 6 source candidate** are different binaries. Record the version/build, source commit and executable hash for each test. Do not claim the 0.3.1 lifecycle fixes were tested by running the older installed preview. For genuinely fresh consent, restore a clean VM snapshot or use another clean test environment for each binary; carrying consent across an update is an upgrade test. No owner's TCC reset is allowed. +The published Homebrew `0.3.1-preview.2` (source `dc751a7`), the older `0.3.0-preview.1` and any later 0.3.1 source candidate are different binaries. Record the version/build, source commit and executable hash for each test. Do not claim fixes made after `dc751a7` were tested by running the installed preview. For genuinely fresh consent, restore a clean VM snapshot or use another clean test environment for each binary; carrying consent across an update is an upgrade test. No owner's TCC reset is allowed. Record the test date, macOS version, architecture, Homebrew version, preview tag and checksum. Record each case as **pass**, **fail** or **pending**, with the exact action and safe evidence location. Keep raw logs, screenshots and session data local, outside tracked documentation. Use synthetic content only; review any proposed public image before adding its approval hash. No model calls are needed. diff --git a/docs/official-release-preparation.md b/docs/official-release-preparation.md index a38fbd1..d8ca1c5 100644 --- a/docs/official-release-preparation.md +++ b/docs/official-release-preparation.md @@ -1,6 +1,6 @@ # Official unnotarized release preparation -The published download is [v0.3.0-preview.1](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1). v0.3.1/build 6 is an **unpublished candidate**, with ad-hoc signatures, no Developer ID and no Apple notarization. No installable stable Homebrew cask exists. The separate [Developer ID workflow](releasing.md) keeps its signing, notarization and Gatekeeper requirements. +The published download is the preview [v0.3.1-preview.2](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.1-preview.2), built from 0.3.1/build 6 source. A stable v0.3.1 is **not yet published**; candidates and previews have ad-hoc signatures, no Developer ID and no Apple notarization. No installable stable Homebrew cask exists. The separate [Developer ID workflow](releasing.md) keeps its signing, notarization and Gatekeeper requirements. ## Candidate baseline diff --git a/docs/preview-releases.md b/docs/preview-releases.md index 4e8a568..7a25872 100644 --- a/docs/preview-releases.md +++ b/docs/preview-releases.md @@ -1,8 +1,10 @@ # Unnotarized preview distribution -ContextLens 0.3.0 has a separate preview channel for Apple Silicon Macs running macOS 14+. It needs no paid Apple Developer membership or Apple credentials. Builds use optimized arm64 Swift products and ad-hoc signatures for code integrity. They have **no Developer ID signature, Apple notarization or promised Gatekeeper acceptance**. These prereleases are never marked latest/stable. macOS 14 is the deployment target; hosted runtime checks use macOS 15. +ContextLens has a separate preview channel for Apple Silicon Macs running macOS 14+. It needs no paid Apple Developer membership or Apple credentials. Builds use optimized arm64 Swift products and ad-hoc signatures for code integrity. They have **no Developer ID signature, Apple notarization or promised Gatekeeper acceptance**. These prereleases are never marked latest/stable. macOS 14 is the deployment target; hosted runtime checks use macOS 15. -Published: [v0.3.0-preview.1 — Unnotarized Preview](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1), after [all preview workflow checks passed](https://github.com/bstack-tools/ContextLens/actions/runs/42469995205). The public ZIP was downloaded independently and verified. The separate cask is published in the [tap](https://github.com/Brendan-Lim/homebrew-tap) after [all candidate checks passed](https://github.com/Brendan-Lim/homebrew-tap/actions/runs/42471268060), including online audit, download, installation and uninstallation. The interactive installed-preview workflow remains pending. The stable `contextlens` template and signed `release.yml` remain separate. [Official candidate and release gates](official-release-preparation.md). +Published: [v0.3.1-preview.2 — Unnotarized Preview](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.1-preview.2), built from source commit `dc751a7` (0.3.1/build 6) after [all preview workflow checks passed](https://github.com/bstack-tools/ContextLens/actions/runs/44920094837). The public ZIP was downloaded independently and its checksum verified. The cask in the [tap](https://github.com/Brendan-Lim/homebrew-tap) was regenerated from it after [all candidate checks passed](https://github.com/Brendan-Lim/homebrew-tap/actions/runs/44920664666), including online audit, download, installation and uninstallation. The interactive installed-preview workflow remains pending. The stable `contextlens` template and signed `release.yml` remain separate. [Official candidate and release gates](official-release-preparation.md). + +`v0.3.1-preview.1` was also published, from `93c3dfc`, but its receipt records the repository's pre-transfer URL, so the tap gate correctly rejected it and the next preview number was used. The earlier [v0.3.0-preview.1](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1) remains available. ```sh brew install --cask Brendan-Lim/tap/contextlens-preview @@ -10,15 +12,15 @@ brew install --cask Brendan-Lim/tap/contextlens-preview Verified on a disposable arm64 macOS 15.8.2 runner with Homebrew 7.0.12. After installation, follow the first-launch instructions below, then try `contextlens-cli --help`. Do not install over your working copy just to test the preview. -Public archive SHA-256: `1cd84d6b15fc7aed7346ff1fd27382d5d2cd5a51637c7358861ddf55ebe0da45`. +Public archive SHA-256: `42373a29db99f592583d5dcaff1574ae6d75b34481b1fb8a3fa44e1217ea2a2d`. -During verification GitHub's browser asset URL returned HTTP 504, while the official public asset API served the identical ZIP without credentials. The preview cask uses that immutable asset ID with `Accept: application/octet-stream` and the same SHA-256. Its Homebrew version combines preview version and asset ID as `0.3.0-preview.1,723563642`. No account, token or compiler is required. If the release page download fails, this credential-free download was tested: +During verification GitHub's browser asset URL returned HTTP 504, while the official public asset API served the identical ZIP without credentials. The preview cask uses that immutable asset ID with `Accept: application/octet-stream` and the same SHA-256. Its Homebrew version combines preview version and asset ID as `0.3.1-preview.2,776028347`. No account, token or compiler is required. If the release page download fails, this credential-free download was tested: ```sh curl --fail --location --header 'Accept: application/octet-stream' \ - --output ContextLens-0.3.0-preview.1-arm64.zip \ - https://api.github.com/repos/bstack-tools/ContextLens/releases/assets/723563642 -shasum -a 256 ContextLens-0.3.0-preview.1-arm64.zip + --output ContextLens-0.3.1-preview.2-arm64.zip \ + https://api.github.com/repos/bstack-tools/ContextLens/releases/assets/776028347 +shasum -a 256 ContextLens-0.3.1-preview.2-arm64.zip ``` Compare the output with the full checksum above before extracting and authorizing the app. This downloads files only; it does not alter macOS security. @@ -26,7 +28,7 @@ Compare the output with the full checksum above before extracting and authorizin ## For a first-time user 1. Review the source and the release at the official [ContextLens repository](https://github.com/bstack-tools/ContextLens). Use only an explicitly labeled **Unnotarized Preview**. Confirm its version, source commit and published checksum. Ad-hoc signing does not authenticate the developer; neither a checksum nor passing tests makes it Apple-verified. -2. Download the versioned ZIP and its `.zip.sha256` from that release. In the download directory run `shasum -a 256 -c ContextLens-0.3.0-preview.1-arm64.zip.sha256`. The checksum should report `OK`. Stop if it differs. A checksum obtained from the same release protects against mismatched downloads, not compromise of the release account. +2. Download the versioned ZIP and its `.zip.sha256` from that release. In the download directory run `shasum -a 256 -c ContextLens-0.3.1-preview.2-arm64.zip.sha256`. The checksum should report `OK`. Stop if it differs. A checksum obtained from the same release protects against mismatched downloads, not compromise of the release account. 3. For a direct download, extract the ZIP and drag `ContextLens.app` into Applications. If you already have a copy, quit it and deliberately back it up before switching. Do not overwrite your working app just to try the preview. The channels share a bundle ID, session location and CLI name; they are not isolated side-by-side installations. 4. Try opening ContextLens. If macOS blocks it because the developer cannot be verified or Apple cannot check it, dismiss the alert. Only if you trust the origin and intact download, open **System Settings → Privacy & Security**, scroll to the blocked-app notice, choose **Open Anyway**, and confirm **Open**. Follow [Apple's instructions](https://support.apple.com/en-us/102445). This is your decision for this app; do not disable Gatekeeper or remove quarantine. If macOS reports malware, corruption or a revoked app, stop and investigate. Managed Mac policies may prevent authorization. 5. Grant Screen Recording to this copy in System Settings → Privacy & Security → Screen & System Audio Recording (Screen Recording on older macOS), then relaunch if requested. Accessibility is optional for clicked-control captions. Preview updates can require fresh consent because ad-hoc signatures change. Do not reset existing permissions to test installation. @@ -41,14 +43,14 @@ Uninstalling the preview with Homebrew removes its app and CLI link. It does not brew uninstall --cask Brendan-Lim/tap/contextlens-preview ``` -Uninstallation and preserved synthetic sessions/exports were verified. Upgrades remain untested because there is only one published preview; verify them when a second preview exists. +Uninstallation and preserved synthetic sessions/exports were verified. Upgrades from 0.3.0-preview.1 to 0.3.1-preview.2 have not been tested yet; verify them on a disposable Mac. ## Maintainer workflow -The published cask above remains 0.3.0-preview.1. Source now targets **0.3.1/build 6**; [capture reliability](native-capture-reliability.md) separates candidate tests from the older binary. From clean, current `main`, choose an unused preview matching `config/version.json`; the next candidate is: +The published cask above is 0.3.1-preview.2, built from **0.3.1/build 6** source; [capture reliability](native-capture-reliability.md) separates candidate tests from the older binary. From clean, current `main`, choose an unused preview matching `config/version.json`; the next unused preview is: ```sh -gh workflow run preview-release.yml --repo bstack-tools/ContextLens --ref main -f version=0.3.1-preview.1 +gh workflow run preview-release.yml --repo bstack-tools/ContextLens --ref main -f version=0.3.1-preview.3 gh run list --repo bstack-tools/ContextLens --workflow preview-release.yml ``` @@ -62,7 +64,7 @@ Generate the cask only from the actual published prerelease: ```sh gh repo clone Brendan-Lim/homebrew-tap /tmp/contextlens-preview-tap -python3 scripts/preview-release.py update-tap 0.3.1-preview.1 /tmp/contextlens-preview-tap +python3 scripts/preview-release.py update-tap 0.3.1-preview.3 /tmp/contextlens-preview-tap ``` This checks official browser/API URLs and asset IDs, uploaded assets, downloaded checksum, preview trust label, signatures, portable arm64 bundle, receipt and matching source tag before rendering `Casks/contextlens-preview.rb`. It cannot generate a cask for a draft or stable release or a fabricated checksum. It never changes `Casks/contextlens.rb` or its template. Run tap validation, `brew style`, online audit, download verification and the disposable hosted installation check on a candidate branch before publishing the tap's main branch. Then update the status here with evidence. No cross-repository secret is needed; use existing maintainer authorization. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 45dfa84..56a5031 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,7 +2,7 @@ ## Binary downloads and Homebrew -The current download is the preview [`v0.3.0-preview.1`](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1) (ZIP), also installable with `brew install --cask Brendan-Lim/tap/contextlens-preview`. Both are ad-hoc signed and not notarized by Apple. The stable DMG and the `contextlens` cask appear only after v0.3.1 passes [interactive acceptance](release-acceptance/README.md) and is published; until then, any stable cask template is not an installable package. [Homebrew channels](homebrew.md). +The current download is the preview [`v0.3.1-preview.2`](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.1-preview.2) (ZIP), also installable with `brew install --cask Brendan-Lim/tap/contextlens-preview`. Both are ad-hoc signed and not notarized by Apple. The stable DMG and the `contextlens` cask appear only after v0.3.1 passes [interactive acceptance](release-acceptance/README.md) and is published; until then, any stable cask template is not an installable package. [Homebrew channels](homebrew.md). ContextLens is built for macOS 14 Sonoma and later on Apple Silicon. Automated checks run on macOS 15 and macOS 26; macOS 14 itself has not been tested at runtime yet, so please [report](https://github.com/bstack-tools/ContextLens/issues) anything that breaks there.