README

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"]

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:

OS host bootstrap (Darwin: Homebrew → Herd/Zephir or PIE; Linux: build deps → PIE — always runs)
Optional Tubes/native/extension actions when features need them
composer create-project scrapyard-io/scrapyard-io:^0.7.0 some-app --remove-vcs --prefer-dist
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:

Ensure Homebrew (Auto / Manual / No if missing)
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:

Require PHP extension build dependencies (phpize, php-config, make, pkg-config, curl, C compiler). If missing → show apt guidance, wait for Enter, exit.
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)

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

SDL3 (macOS + Linux)

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)
If ext-sdl3 missing → Herd script (macOS Herd) or PIE
create-project skeleton
composer require scrapyard-io/tubes:^0.7.0 microscrap/sdl3-gfx:^0.7.0
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:

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

Vulkan (macOS + Linux)

Same GLFW pairing as OpenGL:

Ensure Vulkan (Darwin: Homebrew molten-vk + vulkan-loader; Linux: apt libvulkan-dev + vulkan-tools when pkg-config vulkan is missing)
Ensure GLFW >= 3.4
If ext-vulkan missing → Herd script (macOS Herd) or PIE
If ext-glfw missing → Herd script (macOS Herd) or PIE
create-project skeleton
composer require scrapyard-io/tubes:^0.7.0 microscrap/vulkan-gfx:^0.7.0
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.

Ensure GLFW >= 3.4 (cuda-gfx windows need it)
If ext-cuda missing → PIE php-io-extensions/cuda
If ext-glfw missing → PIE
create-project skeleton
composer require scrapyard-io/tubes:^0.7.0 microscrap/cuda-gfx:^0.7.0
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:

Ask whether to add Tubes Framework add-ons
If yes → multiselect Extended Font Package (scrapyard-io/autopen) and/or UX Components (scrapyard-io/ux)
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)

scrapyard-io / installer

Maintainers

Package info

Statistics

Security

README

Logic path

Manual install sources

Host tools

Native libraries

PHP extensions (`php-io-extensions/*`)

Composer companions (post create-project)

Installation

Usage

Darwin host tools (before Tubes)

Linux host tools (before Tubes)

Tubes (macOS + Linux)

Tubes providers (shared graph)

Metal (macOS only)

SDL3 (macOS + Linux)

OpenGL (macOS + Linux)

Vulkan (macOS + Linux)

CUDA (Linux only, detect-only toolkit)

Development

Open Knowledge Format (`.okf/`)

scrapyard-io / installer

Maintainers

Package info

Statistics

Security

README

Logic path

Manual install sources

Host tools

Native libraries

PHP extensions (php-io-extensions/*)

Composer companions (post create-project)

Installation

Usage

Darwin host tools (before Tubes)

Linux host tools (before Tubes)

Tubes (macOS + Linux)

Tubes providers (shared graph)

Metal (macOS only)

SDL3 (macOS + Linux)

OpenGL (macOS + Linux)

Vulkan (macOS + Linux)

CUDA (Linux only, detect-only toolkit)

Development

Open Knowledge Format (.okf/)

PHP extensions (`php-io-extensions/*`)

Open Knowledge Format (`.okf/`)