ScrapyardIO Installer

Composer-based installer for new ScrapyardIO applications (scrapyard-io/installer 0.7).

Logic path

scrapyard-io new is PocketFlow plan-then-execute. Interactive CLI runs also hit a Packagist release-channel watcher before any command.

Flow overview (mermaid)

flowchart TD
  bin["bin/scrapyard-io"] --> app["Console Application doRun"]
  app --> watch["PackagistReleaseWatcher"]
  watch -->|skip / decline / fail| cmd["new command"]
  watch -->|confirm yes| require["composer global require installer:^latest"]
  require --> reexec["re-exec scrapyard-io + argv"]
  cmd --> flow["NewApplicationFlow"]
  flow --> resolve["ResolveDirectory"]
  resolve --> os["DetectOs"]
  os --> darwin["EnsureDarwinHostTools"]
  darwin --> linux["EnsureLinuxHostTools"]
  linux --> promptGpio["PromptIntegratedCircuits"]
  promptGpio -->|skip| cudaDetect["DetectCudaToolkit"]
  promptGpio -->|configure| gpioImpl["Select GPIO implementations"]
  gpioImpl --> gpioExt["Ensure posi / ftdi extensions"]
  gpioExt --> gpioProto["Select POSIX / FTDI protocols"]
  gpioProto --> queueGpio["QueueGpioPackages"]
  queueGpio --> cudaDetect
  cudaDetect --> tubes["PromptTubesPackage"]
  tubes -->|skip| planCreate["PlanCreateProject"]
  tubes -->|configure| provider["PromptTubesProvider"]
  provider -->|metal| metal["EnsureMetalExtension"]
  provider -->|sdl3| sdl3["SDL3 lib → ext"]
  provider -->|open-gl| ogl["OpenGL + GLFW libs/exts"]
  provider -->|vulkan| vk["Vulkan + GLFW libs/exts"]
  provider -->|cuda| cuda["GLFW → CUDA ext → GLFW ext"]
  metal --> queue["QueueTubesPackages"]
  sdl3 --> queue
  ogl --> queue
  vk --> queue
  cuda --> queue
  queue --> addons["Prompt / Select Tubes add-ons"]
  addons --> planCreate
  planCreate --> planPkgs["PlanAdditionalPackages"]
  planPkgs --> planCfg["PlanConfigureTubesDefaults"]
  planCfg --> exec["ExecuteActionsNode"]

Loading

Interactive canvas (git checkout only): open docs/canvases/installer-logic-path.canvas.tsx in Cursor. That folder is export-ignore and is not shipped in Composer dist packages.

Manual install sources

Prefer scrapyard-io new when you can. These are the upstream / docs sources the installer uses (or detects) so you can install pieces by hand.

Site base: https://scrapyard-io.projectsaturnstudios.com · ecosystem pattern /ecosystem/{family}/{package}/0.7.x/{page}.

Host tools

Tool	Manual source
Homebrew (macOS)	https://brew.sh
PIE	https://github.com/php/pie · curl -L https://github.com/php/pie/releases/... (installer downloads latest release)
Zephir (Herd path)	https://zephir-lang.com / Composer phalcon/zephir
CUDA Toolkit ≥ 12 (Linux, detect-only)	NVIDIA CUDA Toolkit — installer never installs this

Native libraries

The installer does not install every library up front. It requires (or detects) them as needed, depending on the modules and Tubes provider you add during scrapyard-io new (for example OpenGL + GLFW for the OpenGL provider, SDL3 for SDL3, Vulkan loader for Vulkan, CUDA Toolkit only when the CUDA provider is selectable).

Library	Minimum	Manual sources
CUDA Toolkit	≥ 12.0 (detect-only)	NVIDIA CUDA Toolkit — never installed by this CLI; Linux host must already have Toolkit ≥ 12 for the CUDA Tubes provider
OpenGL	platform GL	Darwin: Xcode CLT / OpenGL.framework · Linux: distro libgl1-mesa-dev (+ EGL as needed)
GLFW	3.4.0	glfw/glfw (installer clones 3.4) · Homebrew glfw · Linux apt libglfw3-dev
SDL3	3.4.0	libsdl-org/SDL release-3.4.x · Homebrew sdl3 · Linux apt libsdl3-dev (often too old → source)
Vulkan	loader + headers	Darwin: Homebrew molten-vk + vulkan-loader · Linux: apt libvulkan-dev · Vulkan SDK

PHP extensions (php-io-extensions/*)

Install via pie install <package> (or Herd install-macos-herd.sh from the git ref). Docs: ecosystem overview pages below.

Extension	PIE / Composer	Ecosystem docs	Source
metal	php-io-extensions/metal	overview	GitHub
sdl3	php-io-extensions/sdl3	overview	GitHub
open-gl	php-io-extensions/open-gl	overview	GitHub
vulkan	php-io-extensions/vulkan	overview	GitHub
cuda	php-io-extensions/cuda	overview	GitHub
glfw	php-io-extensions/glfw	Family hub: php-io-extensions (package page when published)	GitHub
posi	php-io-extensions/posi	overview	GitHub
ftdi	php-io-extensions/ftdi	overview	GitHub

Composer companions (post create-project)

Package	Ecosystem docs	Packagist / source
scrapyard-io/gpio-framework	overview	Packagist
microscrap/posix	overview	Packagist
microscrap/uart	overview	Packagist
microscrap/i2c	overview	Packagist
microscrap/spi	overview	Packagist
microscrap/gpio	overview	Packagist
microscrap/ftdi	overview	Packagist
microscrap/mpsse	overview	Packagist
scrapyard-io/tubes	overview	Packagist
microscrap/metal-gfx	overview	Packagist
microscrap/sdl3-gfx	overview	Packagist
microscrap/ogx	overview	Packagist
microscrap/vulkan-gfx	overview	Packagist
microscrap/cuda-gfx	overview	Packagist
scrapyard-io/autopen	overview	Packagist
scrapyard-io/ux	overview	Packagist
scrapyard-io/scrapyard-io (skeleton)	Ecosystem hub	Packagist

Installation

composer global require scrapyard-io/installer

Ensure Composer's global bin directory is on your PATH.

Usage

scrapyard-io new some-app

This plans, then executes:

1. OS host bootstrap (Darwin: Homebrew → Herd/Zephir or PIE; Linux: build deps → PIE — always runs)
2. Optional Tubes/native/extension actions when features need them
3. composer create-project scrapyard-io/scrapyard-io:^0.7.0 some-app --remove-vcs --prefer-dist
4. Optional composer require for companion packages queued during the interview

Darwin host tools (before Tubes)

On macOS, after OS detection and before the Tubes interview:

1. Ensure Homebrew (Auto / Manual / No if missing)
2. Detect Laravel Herd (herd on PATH)
   • If Herd → require Zephir (hard stop if missing) and skip PIE
   • If not Herd → ensure PIE (Auto / Manual / No if missing)

Linux host tools (before Tubes)

On Linux, after OS detection:

1. Require PHP extension build dependencies (phpize, php-config, make, pkg-config, curl, C compiler). If missing → show apt guidance, wait for Enter, exit.
2. Ensure PIE (same Auto / Manual / No as macOS)

Tubes (macOS + Linux)

On macOS and Linux the installer asks whether to install scrapyard-io/tubes.

OS	Selectable providers
macOS	Metal, SDL3, OpenGL, Vulkan
Linux	OpenGL, Vulkan, SDL3; CUDA only if Toolkit >= 12 detected (Metal never listed)

--tubes defaults to Metal on macOS and OpenGL on Linux.

Tubes providers (shared graph)

On macOS and Linux the installer asks whether to install the Display Rendering Framework (scrapyard-io/tubes), then chooses a provider (OS-gated — see table above).

PHP extensions (metal, sdl3, opengl, vulkan, glfw, cuda) install via:

• macOS + Herd: clone php-io-extensions/* 0.7.x into a temp dir and run install-macos-herd.sh
• Otherwise (macOS without Herd, or Linux): pie install php-io-extensions/…

Metal (macOS only)

1. If ext-metal is not loaded → install via Herd script or PIE before create-project
2. create-project skeleton
3. composer require scrapyard-io/tubes:^0.7.0 microscrap/metal-gfx:^0.7.0

SDL3 (macOS + Linux)

1. Ensure SDL3 >= 3.4.0 (pkg-config sdl3)
   • Darwin: Homebrew sdl3, source fallback if too old
   • Linux: try apt libsdl3-dev; if missing or < 3.4.0 → cmake build libsdl-org/SDL release-3.4.x into /usr/local (X11 deps, SDL_X11_XTEST=OFF, SDL_WAYLAND=OFF)
2. If ext-sdl3 missing → Herd script (macOS Herd) or PIE
3. create-project skeleton
4. composer require scrapyard-io/tubes:^0.7.0 microscrap/sdl3-gfx:^0.7.0
5. Write config/tubes.php + WINDOW_DRIVER so canvas-window-demo / MagicAlias default use sdl3

OpenGL (macOS + Linux)

Each library/extension is its own plan node:

1. Ensure OpenGL (Darwin: OpenGL.framework / Xcode CLT; Linux: apt libgl1-mesa-dev / related when missing)
2. Ensure GLFW >= 3.4 (Darwin: Homebrew or source; Linux: apt / source fallback)
3. If ext-opengl missing → Herd script (macOS Herd) or PIE
4. If ext-glfw missing → Herd script (macOS Herd) or PIE
5. create-project skeleton
6. composer require scrapyard-io/tubes:^0.7.0 microscrap/ogx:^0.7.0
7. Write config/tubes.php + WINDOW_DRIVER so canvas-window-demo / MagicAlias default use open-gl

Vulkan (macOS + Linux)

Same GLFW pairing as OpenGL:

1. Ensure Vulkan (Darwin: Homebrew molten-vk + vulkan-loader; Linux: apt libvulkan-dev + vulkan-tools when pkg-config vulkan is missing)
2. Ensure GLFW >= 3.4
3. If ext-vulkan missing → Herd script (macOS Herd) or PIE
4. If ext-glfw missing → Herd script (macOS Herd) or PIE
5. create-project skeleton
6. composer require scrapyard-io/tubes:^0.7.0 microscrap/vulkan-gfx:^0.7.0
7. Write config/tubes.php + WINDOW_DRIVER so canvas-window-demo / MagicAlias default use vulkan

CUDA (Linux only, detect-only toolkit)

Shown only when NVIDIA CUDA Toolkit >= 12 is already on the host (CUDA_HOME / /usr/local/cuda with headers + libcudart). The installer never installs the CUDA Toolkit.

1. Ensure GLFW >= 3.4 (cuda-gfx windows need it)
2. If ext-cuda missing → PIE php-io-extensions/cuda
3. If ext-glfw missing → PIE
4. create-project skeleton
5. composer require scrapyard-io/tubes:^0.7.0 microscrap/cuda-gfx:^0.7.0
6. Write config/tubes.php + WINDOW_DRIVER=cuda

Metal / CUDA installs also write those defaults to their driver slug.

Optional Tubes add-ons (only when Tubes is selected), before create-project:

1. Ask whether to add Tubes Framework add-ons
2. If yes → multiselect Extended Font Package (scrapyard-io/autopen) and/or UX Components (scrapyard-io/ux)
3. Selected packages join the post-skeleton composer require list

Automated flags:

scrapyard-io new some-app --tubes
scrapyard-io new some-app --tubes --tubes-provider=metal
scrapyard-io new some-app --tubes --tubes-provider=sdl3
scrapyard-io new some-app --tubes --tubes-provider=open-gl
scrapyard-io new some-app --tubes --tubes-provider=vulkan
scrapyard-io new some-app --tubes --tubes-provider=cuda
scrapyard-io new some-app --tubes --tubes-addons=autopen,ux
scrapyard-io new some-app --tubes --no-tubes-addons
scrapyard-io new some-app --no-tubes

Non-interactive runs without flags skip Tubes.

Development

composer install
composer test

From a checkout: php bin/scrapyard-io (after composer install).

Open Knowledge Format (.okf/)

This repository includes an Open Knowledge Format bundle at .okf/ for development in source — not for end users of the Composer dist package.

Path	Role
.okf/index.md	Progressive-disclosure entry: start here before changing installer architecture or CLI behavior
.okf/orientation/	What the package is / console entrypoint / logic-path canvas
.okf/core/	new command, PocketFlow orchestration, release-channel watcher
.okf/conventions/	Command lifecycle and contributor conventions
.okf/traps/	Known failure modes (SDL3 apt, CUDA detect-only, Composer constraint widen, …)
.okf/log.md	Chronological knowledge updates

Purpose: give humans and coding agents a durable, linkable map of decisions and traps so changes stay aligned with how scrapyard-io new is supposed to work. Prefer status: stable concepts; treat draft as unverified until a human signs off. When you learn something durable about this package, update the matching concept and append log.md.

The .okf/ tree (and AGENTS.md) are listed in .gitattributes as export-ignore, so they do not ship in Packagist/Composer dist archives — clone the git repo to use them.

Related source-only artifacts:

• AGENTS.md — short agent/contributor rules that point at .okf/
• docs/canvases/installer-logic-path.canvas.tsx — interactive flow canvas (export-ignore)