Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Capture the window you’re building, mark what should change, and hand the resu

<br>

[**Download for macOS**](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1) &nbsp;·&nbsp; [**Install with Homebrew**](#install) &nbsp;·&nbsp; [**Get started**](#get-started)
[**Download for macOS**](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.1-preview.2) &nbsp;·&nbsp; [**Install with Homebrew**](#install) &nbsp;·&nbsp; [**Get started**](#get-started)

<p>
<a href="Package.swift"><img src="https://img.shields.io/badge/Swift-native-F05138?style=flat&amp;logo=swift&amp;logoColor=white" alt="Native Swift app"></a>
Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/beta-acceptance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/official-release-preparation.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
26 changes: 14 additions & 12 deletions docs/preview-releases.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,34 @@
# 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
```

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.

## 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.
Expand All @@ -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
```

Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading