sorcery-go/docs/SPELL_SPEC.md

Spell Specification (SPELL.md)

Every spell in the Grimoire is a directory containing Bash scripts:

grimoire/
└── libs/
    └── openssl/
        ├── DETAILS       # Metadata: SPELL, VERSION, SOURCE_URL, etc.
        ├── DEPENDS       # Direct dependencies + sub-depends
        ├── BUILD         # Compilation script (runs inside the sandbox)
        ├── CONFIGURE     # Interactive y/n queries (consumed by ICE)
        ├── PRE_BUILD     # Optional pre-build steps
        └── INSTALL       # Optional install override

DETAILS Fields

Field	Required	Example
SPELL	yes	openssl
VERSION	yes	3.2.1
SOURCE	yes	${SPELL}-${VERSION}.tar.gz
SOURCE_URL[0]	yes	https://www.openssl.org/source/...
SOURCE_HASH	yes	sha512:abc123...
SOURCE_DIRECTORY	yes	${BUILD_DIRECTORY}/${SPELL}-${VERSION}
WEB_SITE	no	https://www.openssl.org/
ENTERED	no	20260317
LICENSE[0]	yes	Apache-2.0
SHORT	yes	"The Open Source toolkit for SSL/TLS"

DEPENDS Format

# Runtime dependency
depends glibc ""

# Build-only dependency
depends pkg-config "" build

# Optional dependency (toggled via ICE)
depends zlib "--with-zlib" optional

# Sub-dependency: requires openssl to be built with ssl3
sub_depends openssl ssl3

CONFIGURE Format

The Interactive Configuration Engine (ICE) intercepts config_query calls:

config_query OPENSSL_SSL3  "Enable SSLv3 (insecure)?" n
config_query OPENSSL_IPV6  "Enable IPv6 support?"     y
config_query OPENSSL_ASM   "Use assembly optimisations?" y

Answers are persisted in the Tablet (BoltDB). Subsequent casts reuse the answers unless --reconfigure is passed.

BUILD Script

The BUILD script runs inside the OverlayFS sandbox. Standard pattern:

#!/bin/bash
cd "$SOURCE_DIRECTORY" &&
./configure --prefix=/usr "$@" &&
make &&
make install

The sandbox's upper directory captures every file make install writes — this becomes the Essence manifest. No installwatch / LD_PRELOAD needed.

Spell Generation via Quill

quill new zlib
# → launches the interview wizard
# → emits DETAILS, DEPENDS, BUILD, CONFIGURE
# → auto-hashes the upstream source via the "Smart Quill" mode

The WebUI provides a modal form that drives the same quill.GenerateSpell code path so CLI and WebUI produce identical output.