harborOn this page
Porthole
Development
Clone the repository, install Flox, then run:
flox activate -- bun install --frozen-lockfile
flox activate -- bun run checkThe committed Flox manifest and lock pin Bun, Git, GitHub CLI, ShellCheck,
Actionlint and pre-commit, plus Tart on Apple silicon Macs. Activation sets the repository's .githooks path.
The hook runs the complete CI gate. Alternatively run
flox activate -- pre-commit run --all-files using the included configuration.
Install dependencies before your first commit. Updating dependencies means
reviewing both bun.lock and .flox/env/manifest.lock.
The gate validates Markdown, parses every Mermaid block, checks local document
links, enforces budget.json, lints shell and Actions, runs tests and builds the
static site. It also builds the universal native app.
Porthole requires macOS 15+ and Xcode 26+ (Swift 6.2+). Apple SDKs come from Xcode; Flox supplies repository tools and does not replace Xcode.
budget.json caps the total maintained code and individual source files.
Generated assets, dependencies and documentation prose do not count. Existing
large upstream files have explicit ceilings; do not split or compress code just
to evade review. Prefer deleting duplication before increasing a budget.
The test suites use fixtures and do not start VMs or interact with your desktop. Real VM verification is a separate, opt-in integration step: create a disposable VM, launch a sample build, list its controls, screenshot it, and confirm the run appears in Porthole. Never capture private desktop content for site artwork.
Run bun run build:site to produce dist/site. Serve that directory with any
static HTTP server. The site has no framework, external fonts or runtime service.
Edit on GitHub%2C%20then%20run%3A%0A%0A%60%60%60sh%0Aflox%20activate%20--%20bun%20install%20--frozen-lockfile%0Aflox%20activate%20--%20bun%20run%20check%0A%60%60%60%0A%0AThe%20committed%20Flox%20manifest%20and%20lock%20pin%20Bun%2C%20Git%2C%20GitHub%20CLI%2C%20ShellCheck%2C%0AActionlint%20and%20pre-commit%2C%20plus%20Tart%20on%20Apple%20silicon%20Macs.%20Activation%20sets%20the%20repository's%20%60.githooks%60%20path.%0AThe%20hook%20runs%20the%20complete%20CI%20gate.%20Alternatively%20run%0A%60flox%20activate%20--%20pre-commit%20run%20--all-files%60%20using%20the%20included%20configuration.%0AInstall%20dependencies%20before%20your%20first%20commit.%20Updating%20dependencies%20means%0Areviewing%20both%20%60bun.lock%60%20and%20%60.flox%2Fenv%2Fmanifest.lock%60.%0A%0AThe%20gate%20validates%20Markdown%2C%20parses%20every%20Mermaid%20block%2C%20checks%20local%20document%0Alinks%2C%20enforces%20%60budget.json%60%2C%20lints%20shell%20and%20Actions%2C%20runs%20tests%20and%20builds%20the%0Astatic%20site.%20It%20also%20builds%20the%20universal%20native%20app.%0A%0APorthole%20requires%20macOS%2015%2B%20and%20Xcode%2026%2B%20(Swift%206.2%2B).%20Apple%20SDKs%20come%20from%0AXcode%3B%20Flox%20supplies%20repository%20tools%20and%20does%20not%20replace%20Xcode.%0A%0A%60budget.json%60%20caps%20the%20total%20maintained%20code%20and%20individual%20source%20files.%0AGenerated%20assets%2C%20dependencies%20and%20documentation%20prose%20do%20not%20count.%20Existing%0Alarge%20upstream%20files%20have%20explicit%20ceilings%3B%20do%20not%20split%20or%20compress%20code%20just%0Ato%20evade%20review.%20Prefer%20deleting%20duplication%20before%20increasing%20a%20budget.%0A%0AThe%20test%20suites%20use%20fixtures%20and%20do%20not%20start%20VMs%20or%20interact%20with%20your%20desktop.%0AReal%20VM%20verification%20is%20a%20separate%2C%20opt-in%20integration%20step%3A%20create%20a%20disposable%0AVM%2C%20launch%20a%20sample%20build%2C%20list%20its%20controls%2C%20screenshot%20it%2C%20and%20confirm%20the%20run%0Aappears%20in%20Porthole.%20Never%20capture%20private%20desktop%20content%20for%20site%20artwork.%0A%0ARun%20%60bun%20run%20build%3Asite%60%20to%20produce%20%60dist%2Fsite%60.%20Serve%20that%20directory%20with%20any%0Astatic%20HTTP%20server.%20The%20site%20has%20no%20framework%2C%20external%20fonts%20or%20runtime%20service.%0A%0A%23%23%20Social%20artwork%0A%0A%60assets%2Fog.svg%60%20is%20the%20editable%201200%20%C3%97%20630%20share%20card.%20Export%20it%20at%20its%20native%0Asize%20to%20%60assets%2Fog.png%60%20after%20artwork%20changes.%20The%20README%20and%20site%20social%20metadata%0Ause%20the%20PNG%3B%20the%20metadata%20uses%20its%20public%20GitHub%20URL%20until%20a%20site%20domain%20is%20chosen.%0A%0A%0ASource%3A%20https%3A%2F%2Fgithub.com%2Fsmeltery%2Fporthole%2Fblob%2Fdb29c8332874abff650af109fb9e7920fe9b6f1d%2Fdocs%2Fdevelopment.md%0A){kind=small}
%2C%20then%20run%3A%0A%0A%60%60%60sh%0Aflox%20activate%20--%20bun%20install%20--frozen-lockfile%0Aflox%20activate%20--%20bun%20run%20check%0A%60%60%60%0A%0AThe%20committed%20Flox%20manifest%20and%20lock%20pin%20Bun%2C%20Git%2C%20GitHub%20CLI%2C%20ShellCheck%2C%0AActionlint%20and%20pre-commit%2C%20plus%20Tart%20on%20Apple%20silicon%20Macs.%20Activation%20sets%20the%20repository's%20%60.githooks%60%20path.%0AThe%20hook%20runs%20the%20complete%20CI%20gate.%20Alternatively%20run%0A%60flox%20activate%20--%20pre-commit%20run%20--all-files%60%20using%20the%20included%20configuration.%0AInstall%20dependencies%20before%20your%20first%20commit.%20Updating%20dependencies%20means%0Areviewing%20both%20%60bun.lock%60%20and%20%60.flox%2Fenv%2Fmanifest.lock%60.%0A%0AThe%20gate%20validates%20Markdown%2C%20parses%20every%20Mermaid%20block%2C%20checks%20local%20document%0Alinks%2C%20enforces%20%60budget.json%60%2C%20lints%20shell%20and%20Actions%2C%20runs%20tests%20and%20builds%20the%0Astatic%20site.%20It%20also%20builds%20the%20universal%20native%20app.%0A%0APorthole%20requires%20macOS%2015%2B%20and%20Xcode%2026%2B%20(Swift%206.2%2B).%20Apple%20SDKs%20come%20from%0AXcode%3B%20Flox%20supplies%20repository%20tools%20and%20does%20not%20replace%20Xcode.%0A%0A%60budget.json%60%20caps%20the%20total%20maintained%20code%20and%20individual%20source%20files.%0AGenerated%20assets%2C%20dependencies%20and%20documentation%20prose%20do%20not%20count.%20Existing%0Alarge%20upstream%20files%20have%20explicit%20ceilings%3B%20do%20not%20split%20or%20compress%20code%20just%0Ato%20evade%20review.%20Prefer%20deleting%20duplication%20before%20increasing%20a%20budget.%0A%0AThe%20test%20suites%20use%20fixtures%20and%20do%20not%20start%20VMs%20or%20interact%20with%20your%20desktop.%0AReal%20VM%20verification%20is%20a%20separate%2C%20opt-in%20integration%20step%3A%20create%20a%20disposable%0AVM%2C%20launch%20a%20sample%20build%2C%20list%20its%20controls%2C%20screenshot%20it%2C%20and%20confirm%20the%20run%0Aappears%20in%20Porthole.%20Never%20capture%20private%20desktop%20content%20for%20site%20artwork.%0A%0ARun%20%60bun%20run%20build%3Asite%60%20to%20produce%20%60dist%2Fsite%60.%20Serve%20that%20directory%20with%20any%0Astatic%20HTTP%20server.%20The%20site%20has%20no%20framework%2C%20external%20fonts%20or%20runtime%20service.%0A%0A%23%23%20Social%20artwork%0A%0A%60assets%2Fog.svg%60%20is%20the%20editable%201200%20%C3%97%20630%20share%20card.%20Export%20it%20at%20its%20native%0Asize%20to%20%60assets%2Fog.png%60%20after%20artwork%20changes.%20The%20README%20and%20site%20social%20metadata%0Ause%20the%20PNG%3B%20the%20metadata%20uses%20its%20public%20GitHub%20URL%20until%20a%20site%20domain%20is%20chosen.%0A%0A%0ASource%3A%20https%3A%2F%2Fgithub.com%2Fsmeltery%2Fporthole%2Fblob%2Fdb29c8332874abff650af109fb9e7920fe9b6f1d%2Fdocs%2Fdevelopment.md%0A){kind=small}
%2C%20then%20run%3A%0A%0A%60%60%60sh%0Aflox%20activate%20--%20bun%20install%20--frozen-lockfile%0Aflox%20activate%20--%20bun%20run%20check%0A%60%60%60%0A%0AThe%20committed%20Flox%20manifest%20and%20lock%20pin%20Bun%2C%20Git%2C%20GitHub%20CLI%2C%20ShellCheck%2C%0AActionlint%20and%20pre-commit%2C%20plus%20Tart%20on%20Apple%20silicon%20Macs.%20Activation%20sets%20the%20repository's%20%60.githooks%60%20path.%0AThe%20hook%20runs%20the%20complete%20CI%20gate.%20Alternatively%20run%0A%60flox%20activate%20--%20pre-commit%20run%20--all-files%60%20using%20the%20included%20configuration.%0AInstall%20dependencies%20before%20your%20first%20commit.%20Updating%20dependencies%20means%0Areviewing%20both%20%60bun.lock%60%20and%20%60.flox%2Fenv%2Fmanifest.lock%60.%0A%0AThe%20gate%20validates%20Markdown%2C%20parses%20every%20Mermaid%20block%2C%20checks%20local%20document%0Alinks%2C%20enforces%20%60budget.json%60%2C%20lints%20shell%20and%20Actions%2C%20runs%20tests%20and%20builds%20the%0Astatic%20site.%20It%20also%20builds%20the%20universal%20native%20app.%0A%0APorthole%20requires%20macOS%2015%2B%20and%20Xcode%2026%2B%20(Swift%206.2%2B).%20Apple%20SDKs%20come%20from%0AXcode%3B%20Flox%20supplies%20repository%20tools%20and%20does%20not%20replace%20Xcode.%0A%0A%60budget.json%60%20caps%20the%20total%20maintained%20code%20and%20individual%20source%20files.%0AGenerated%20assets%2C%20dependencies%20and%20documentation%20prose%20do%20not%20count.%20Existing%0Alarge%20upstream%20files%20have%20explicit%20ceilings%3B%20do%20not%20split%20or%20compress%20code%20just%0Ato%20evade%20review.%20Prefer%20deleting%20duplication%20before%20increasing%20a%20budget.%0A%0AThe%20test%20suites%20use%20fixtures%20and%20do%20not%20start%20VMs%20or%20interact%20with%20your%20desktop.%0AReal%20VM%20verification%20is%20a%20separate%2C%20opt-in%20integration%20step%3A%20create%20a%20disposable%0AVM%2C%20launch%20a%20sample%20build%2C%20list%20its%20controls%2C%20screenshot%20it%2C%20and%20confirm%20the%20run%0Aappears%20in%20Porthole.%20Never%20capture%20private%20desktop%20content%20for%20site%20artwork.%0A%0ARun%20%60bun%20run%20build%3Asite%60%20to%20produce%20%60dist%2Fsite%60.%20Serve%20that%20directory%20with%20any%0Astatic%20HTTP%20server.%20The%20site%20has%20no%20framework%2C%20external%20fonts%20or%20runtime%20service.%0A%0A%23%23%20Social%20artwork%0A%0A%60assets%2Fog.svg%60%20is%20the%20editable%201200%20%C3%97%20630%20share%20card.%20Export%20it%20at%20its%20native%0Asize%20to%20%60assets%2Fog.png%60%20after%20artwork%20changes.%20The%20README%20and%20site%20social%20metadata%0Ause%20the%20PNG%3B%20the%20metadata%20uses%20its%20public%20GitHub%20URL%20until%20a%20site%20domain%20is%20chosen.%0A%0A%0ASource%3A%20https%3A%2F%2Fgithub.com%2Fsmeltery%2Fporthole%2Fblob%2Fdb29c8332874abff650af109fb9e7920fe9b6f1d%2Fdocs%2Fdevelopment.md%0A){kind=small}
%2C%20then%20run%3A%0A%0A%60%60%60sh%0Aflox%20activate%20--%20bun%20install%20--frozen-lockfile%0Aflox%20activate%20--%20bun%20run%20check%0A%60%60%60%0A%0AThe%20committed%20Flox%20manifest%20and%20lock%20pin%20Bun%2C%20Git%2C%20GitHub%20CLI%2C%20ShellCheck%2C%0AActionlint%20and%20pre-commit%2C%20plus%20Tart%20on%20Apple%20silicon%20Macs.%20Activation%20sets%20the%20repository's%20%60.githooks%60%20path.%0AThe%20hook%20runs%20the%20complete%20CI%20gate.%20Alternatively%20run%0A%60flox%20activate%20--%20pre-commit%20run%20--all-files%60%20using%20the%20included%20configuration.%0AInstall%20dependencies%20before%20your%20first%20commit.%20Updating%20dependencies%20means%0Areviewing%20both%20%60bun.lock%60%20and%20%60.flox%2Fenv%2Fmanifest.lock%60.%0A%0AThe%20gate%20validates%20Markdown%2C%20parses%20every%20Mermaid%20block%2C%20checks%20local%20document%0Alinks%2C%20enforces%20%60budget.json%60%2C%20lints%20shell%20and%20Actions%2C%20runs%20tests%20and%20builds%20the%0Astatic%20site.%20It%20also%20builds%20the%20universal%20native%20app.%0A%0APorthole%20requires%20macOS%2015%2B%20and%20Xcode%2026%2B%20(Swift%206.2%2B).%20Apple%20SDKs%20come%20from%0AXcode%3B%20Flox%20supplies%20repository%20tools%20and%20does%20not%20replace%20Xcode.%0A%0A%60budget.json%60%20caps%20the%20total%20maintained%20code%20and%20individual%20source%20files.%0AGenerated%20assets%2C%20dependencies%20and%20documentation%20prose%20do%20not%20count.%20Existing%0Alarge%20upstream%20files%20have%20explicit%20ceilings%3B%20do%20not%20split%20or%20compress%20code%20just%0Ato%20evade%20review.%20Prefer%20deleting%20duplication%20before%20increasing%20a%20budget.%0A%0AThe%20test%20suites%20use%20fixtures%20and%20do%20not%20start%20VMs%20or%20interact%20with%20your%20desktop.%0AReal%20VM%20verification%20is%20a%20separate%2C%20opt-in%20integration%20step%3A%20create%20a%20disposable%0AVM%2C%20launch%20a%20sample%20build%2C%20list%20its%20controls%2C%20screenshot%20it%2C%20and%20confirm%20the%20run%0Aappears%20in%20Porthole.%20Never%20capture%20private%20desktop%20content%20for%20site%20artwork.%0A%0ARun%20%60bun%20run%20build%3Asite%60%20to%20produce%20%60dist%2Fsite%60.%20Serve%20that%20directory%20with%20any%0Astatic%20HTTP%20server.%20The%20site%20has%20no%20framework%2C%20external%20fonts%20or%20runtime%20service.%0A%0A%23%23%20Social%20artwork%0A%0A%60assets%2Fog.svg%60%20is%20the%20editable%201200%20%C3%97%20630%20share%20card.%20Export%20it%20at%20its%20native%0Asize%20to%20%60assets%2Fog.png%60%20after%20artwork%20changes.%20The%20README%20and%20site%20social%20metadata%0Ause%20the%20PNG%3B%20the%20metadata%20uses%20its%20public%20GitHub%20URL%20until%20a%20site%20domain%20is%20chosen.%0A%0A%0ASource%3A%20https%3A%2F%2Fgithub.com%2Fsmeltery%2Fporthole%2Fblob%2Fdb29c8332874abff650af109fb9e7920fe9b6f1d%2Fdocs%2Fdevelopment.md%0A){kind=small}
%2C%20then%20run%3A%0A%0A%60%60%60sh%0Aflox%20activate%20--%20bun%20install%20--frozen-lockfile%0Aflox%20activate%20--%20bun%20run%20check%0A%60%60%60%0A%0AThe%20committed%20Flox%20manifest%20and%20lock%20pin%20Bun%2C%20Git%2C%20GitHub%20CLI%2C%20ShellCheck%2C%0AActionlint%20and%20pre-commit%2C%20plus%20Tart%20on%20Apple%20silicon%20Macs.%20Activation%20sets%20the%20repository's%20%60.githooks%60%20path.%0AThe%20hook%20runs%20the%20complete%20CI%20gate.%20Alternatively%20run%0A%60flox%20activate%20--%20pre-commit%20run%20--all-files%60%20using%20the%20included%20configuration.%0AInstall%20dependencies%20before%20your%20first%20commit.%20Updating%20dependencies%20means%0Areviewing%20both%20%60bun.lock%60%20and%20%60.flox%2Fenv%2Fmanifest.lock%60.%0A%0AThe%20gate%20validates%20Markdown%2C%20parses%20every%20Mermaid%20block%2C%20checks%20local%20document%0Alinks%2C%20enforces%20%60budget.json%60%2C%20lints%20shell%20and%20Actions%2C%20runs%20tests%20and%20builds%20the%0Astatic%20site.%20It%20also%20builds%20the%20universal%20native%20app.%0A%0APorthole%20requires%20macOS%2015%2B%20and%20Xcode%2026%2B%20(Swift%206.2%2B).%20Apple%20SDKs%20come%20from%0AXcode%3B%20Flox%20supplies%20repository%20tools%20and%20does%20not%20replace%20Xcode.%0A%0A%60budget.json%60%20caps%20the%20total%20maintained%20code%20and%20individual%20source%20files.%0AGenerated%20assets%2C%20dependencies%20and%20documentation%20prose%20do%20not%20count.%20Existing%0Alarge%20upstream%20files%20have%20explicit%20ceilings%3B%20do%20not%20split%20or%20compress%20code%20just%0Ato%20evade%20review.%20Prefer%20deleting%20duplication%20before%20increasing%20a%20budget.%0A%0AThe%20test%20suites%20use%20fixtures%20and%20do%20not%20start%20VMs%20or%20interact%20with%20your%20desktop.%0AReal%20VM%20verification%20is%20a%20separate%2C%20opt-in%20integration%20step%3A%20create%20a%20disposable%0AVM%2C%20launch%20a%20sample%20build%2C%20list%20its%20controls%2C%20screenshot%20it%2C%20and%20confirm%20the%20run%0Aappears%20in%20Porthole.%20Never%20capture%20private%20desktop%20content%20for%20site%20artwork.%0A%0ARun%20%60bun%20run%20build%3Asite%60%20to%20produce%20%60dist%2Fsite%60.%20Serve%20that%20directory%20with%20any%0Astatic%20HTTP%20server.%20The%20site%20has%20no%20framework%2C%20external%20fonts%20or%20runtime%20service.%0A%0A%23%23%20Social%20artwork%0A%0A%60assets%2Fog.svg%60%20is%20the%20editable%201200%20%C3%97%20630%20share%20card.%20Export%20it%20at%20its%20native%0Asize%20to%20%60assets%2Fog.png%60%20after%20artwork%20changes.%20The%20README%20and%20site%20social%20metadata%0Ause%20the%20PNG%3B%20the%20metadata%20uses%20its%20public%20GitHub%20URL%20until%20a%20site%20domain%20is%20chosen.%0A%0A%0ASource%3A%20https%3A%2F%2Fgithub.com%2Fsmeltery%2Fporthole%2Fblob%2Fdb29c8332874abff650af109fb9e7920fe9b6f1d%2Fdocs%2Fdevelopment.md%0A){kind=small}
%2C%20then%20run%3A%0A%0A%60%60%60sh%0Aflox%20activate%20--%20bun%20install%20--frozen-lockfile%0Aflox%20activate%20--%20bun%20run%20check%0A%60%60%60%0A%0AThe%20committed%20Flox%20manifest%20and%20lock%20pin%20Bun%2C%20Git%2C%20GitHub%20CLI%2C%20ShellCheck%2C%0AActionlint%20and%20pre-commit%2C%20plus%20Tart%20on%20Apple%20silicon%20Macs.%20Activation%20sets%20the%20repository's%20%60.githooks%60%20path.%0AThe%20hook%20runs%20the%20complete%20CI%20gate.%20Alternatively%20run%0A%60flox%20activate%20--%20pre-commit%20run%20--all-files%60%20using%20the%20included%20configuration.%0AInstall%20dependencies%20before%20your%20first%20commit.%20Updating%20dependencies%20means%0Areviewing%20both%20%60bun.lock%60%20and%20%60.flox%2Fenv%2Fmanifest.lock%60.%0A%0AThe%20gate%20validates%20Markdown%2C%20parses%20every%20Mermaid%20block%2C%20checks%20local%20document%0Alinks%2C%20enforces%20%60budget.json%60%2C%20lints%20shell%20and%20Actions%2C%20runs%20tests%20and%20builds%20the%0Astatic%20site.%20It%20also%20builds%20the%20universal%20native%20app.%0A%0APorthole%20requires%20macOS%2015%2B%20and%20Xcode%2026%2B%20(Swift%206.2%2B).%20Apple%20SDKs%20come%20from%0AXcode%3B%20Flox%20supplies%20repository%20tools%20and%20does%20not%20replace%20Xcode.%0A%0A%60budget.json%60%20caps%20the%20total%20maintained%20code%20and%20individual%20source%20files.%0AGenerated%20assets%2C%20dependencies%20and%20documentation%20prose%20do%20not%20count.%20Existing%0Alarge%20upstream%20files%20have%20explicit%20ceilings%3B%20do%20not%20split%20or%20compress%20code%20just%0Ato%20evade%20review.%20Prefer%20deleting%20duplication%20before%20increasing%20a%20budget.%0A%0AThe%20test%20suites%20use%20fixtures%20and%20do%20not%20start%20VMs%20or%20interact%20with%20your%20desktop.%0AReal%20VM%20verification%20is%20a%20separate%2C%20opt-in%20integration%20step%3A%20create%20a%20disposable%0AVM%2C%20launch%20a%20sample%20build%2C%20list%20its%20controls%2C%20screenshot%20it%2C%20and%20confirm%20the%20run%0Aappears%20in%20Porthole.%20Never%20capture%20private%20desktop%20content%20for%20site%20artwork.%0A%0ARun%20%60bun%20run%20build%3Asite%60%20to%20produce%20%60dist%2Fsite%60.%20Serve%20that%20directory%20with%20any%0Astatic%20HTTP%20server.%20The%20site%20has%20no%20framework%2C%20external%20fonts%20or%20runtime%20service.%0A%0A%23%23%20Social%20artwork%0A%0A%60assets%2Fog.svg%60%20is%20the%20editable%201200%20%C3%97%20630%20share%20card.%20Export%20it%20at%20its%20native%0Asize%20to%20%60assets%2Fog.png%60%20after%20artwork%20changes.%20The%20README%20and%20site%20social%20metadata%0Ause%20the%20PNG%3B%20the%20metadata%20uses%20its%20public%20GitHub%20URL%20until%20a%20site%20domain%20is%20chosen.%0A%0A%0ASource%3A%20https%3A%2F%2Fgithub.com%2Fsmeltery%2Fporthole%2Fblob%2Fdb29c8332874abff650af109fb9e7920fe9b6f1d%2Fdocs%2Fdevelopment.md%0A){kind=small}
Social artwork
assets/og.svgis the editable 1200 × 630 share card. Export it at its native size toassets/og.pngafter artwork changes. The README and site social metadata use the PNG; the metadata uses its public GitHub URL until a site domain is chosen.