Merge remote-tracking branch 'origin/main' into quality/basic-cli-ci-hygiene

# Conflicts:
#	.github/workflows/ci-tests.yml
#	README.md
#	spore.toml

Co-authored-by: zrr1999 <46243324+zrr1999@users.noreply.github.com>

Author: Copilot

.github/workflows/ci-static-checks.yml

@@ -13,13 +13,6 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  actionlint:
-    name: actionlint
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: rhysd/actionlint@v1.7.12
-
   prek:
     name: prek
     runs-on: ubuntu-latest

.github/workflows/ci-tests.yml

@@ -36,97 +36,38 @@ jobs:
   spore:
     name: spore
     runs-on: ubuntu-latest
-    env:
-      SPORE_REPOSITORY: spore-lang/spore
-      SPORE_REF: d96212aa5a4cfe24759c21d8690642adfd357018
     steps:
       - uses: actions/checkout@v6
 
-      - uses: actions/checkout@v6
-        with:
-          repository: ${{ env.SPORE_REPOSITORY }}
-          ref: ${{ env.SPORE_REF }}
-          path: _spore
+      - uses: astral-sh/setup-uv@v6
 
       - uses: dtolnay/rust-toolchain@stable
         with:
-          toolchain: stable
-
-      - uses: Swatinem/rust-cache@v2
-        with:
-          workspaces: _spore
+          toolchain: 1.95
 
-      - name: Build spore compiler
-        run: cargo build --release --manifest-path _spore/Cargo.toml --bin spore
+      - name: Install spore CLI
+        run: uv tool install spore-lang==0.0.3
 
       - name: Format Spore files
-        run: |
-          # `src/host.sp` is a legacy compatibility shim; validate package-backed behavior
-          # via the example and platform modules rather than standalone file-mode checks.
-          # Standalone file examples
-          find examples -maxdepth 1 -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
-          # Project-mode examples (format their src files)
-          if [ -d examples/hello-app/src ]; then
-            find examples/hello-app/src -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
-          fi
-          # Platform API modules
-          find src/basic_cli -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
-          # Check tests if they exist
-          if [ -d tests ]; then
-            find tests -name '*.sp' -type f | sort | xargs _spore/target/release/spore format
-          fi
-          git diff --exit-code
+        run: spore format --check
 
       - name: Check Spore files
         run: |
-          # `src/host.sp` is a legacy compatibility shim; validate package-backed behavior
-          # via the example and platform modules rather than standalone file-mode checks.
-          # Standalone file examples
-          find examples -maxdepth 1 -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
-          # Platform API modules
-          find src/basic_cli -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
-          # Project-mode examples: validate with spore check
-          if [ -d examples/hello-app ]; then
-            echo "✓ Checking project-mode example examples/hello-app/src/main.sp"
-            _spore/target/release/spore check examples/hello-app/src/main.sp
-          fi
-          # Check tests if they exist
-          if [ -d tests ]; then
-            find tests -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore check
-          fi
+          find src/basic_cli -name '*.sp' -type f | sort | xargs -n 1 spore check
+          spore check examples/hello-app/src/main.sp
 
       - name: Build Spore files
         run: |
-          # `src/host.sp` is a legacy compatibility shim; validate package-backed behavior
-          # via the example and platform modules rather than standalone file-mode builds.
-          # Standalone file examples
-          find examples -maxdepth 1 -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
-          # Platform API modules
-          find src/basic_cli -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
-          # Project-mode examples: validate with spore build
-          if [ -d examples/hello-app ]; then
-            echo "✓ Building project-mode example examples/hello-app/src/main.sp"
-            _spore/target/release/spore build examples/hello-app/src/main.sp
-          fi
-          # Check tests if they exist
-          if [ -d tests ]; then
-            find tests -name '*.sp' -type f | sort | xargs -n 1 _spore/target/release/spore build
-          fi
-
-      - name: Run standalone hello example
-        run: _spore/target/release/spore run examples/hello.sp
+          find src/basic_cli -name '*.sp' -type f | sort | xargs -n 1 spore build
+          spore build examples/hello-app/src/main.sp
 
       - name: Run project-mode hello-app example
         run: |
-          if [ -d examples/hello-app ]; then
-            echo "✓ Running project-mode example examples/hello-app/src/main.sp"
-            _spore/target/release/spore run examples/hello-app/src/main.sp
-          fi
+          (
+            cd examples/hello-app
+            echo "✓ Running project-mode example (default entry)"
+            spore run src/main.sp
+          )
 
       - name: Run Spore spec tests
-        run: |
-          if [ ! -d tests ]; then
-            echo "No Spore spec tests yet; skipping spore test."
-            exit 0
-          fi
-          find tests -name '*.sp' -type f | sort | xargs -r -n 1 _spore/target/release/spore test
+        run: spore test

.learnings/README.md

@@ -0,0 +1,4 @@
+# Project Learnings
+
+## Gotchas
+- [Spore CI should target project-mode files explicitly](gotchas/spore-ci-project-mode.md) — spore, ci, project-mode

.learnings/gotchas/spore-ci-project-mode.md

@@ -0,0 +1,27 @@
+---
+title: "Spore CI should target project-mode files explicitly"
+category: gotchas
+tags: [spore, ci, project-mode, basic-cli]
+created: 2026-04-28
+context: "basic-cli CI needed to validate a package-backed example with the shipped compiler"
+---
+
+## Problem
+
+The current `spore` CLI validates package-backed examples reliably when given the explicit entry file, but bare directory invocations and standalone file assumptions can fail depending on current compiler surface and imports.
+
+## Solution
+
+Use explicit file targets for project-mode checks:
+
+```bash
+spore check examples/hello-app/src/main.sp
+spore build examples/hello-app/src/main.sp
+cd examples/hello-app && spore run src/main.sp
+```
+
+## Key points
+
+- Keep CI focused on the canonical package-backed entry file.
+- Treat standalone `.sp` examples as separate from project-mode validation.
+- Re-run `spore format --check`, `spore check`, and `spore build` against explicit files when compiler behavior is in flux.

README.md

@@ -1,13 +1,13 @@
 # basic-cli
 
-Basic CLI platform for [Spore](https://github.com/spore-lang/spore) — provides file I/O, process execution, environment variables, and standard I/O capabilities.
+Basic CLI platform for [Spore](https://github.com/spore-lang/spore) — provides file I/O, process execution, environment variables, and standard I/O effects.
 
 ## Overview
 
-In Spore, a **platform** bridges the pure, capability-tracked language with real-world side effects. `basic-cli` is the standard platform for command-line applications.
+In Spore, a **platform** bridges the pure, effect-tracked language with real-world side effects. `basic-cli` is the standard platform for command-line applications.
 
 ```
-Your Spore App (pure, capability-checked)
+Your Spore App (pure, effect-checked)
      ↕  (effect dispatch)
 basic-cli Platform API (.sp modules)
      ↕  (foreign fn)
@@ -18,7 +18,7 @@ Operating System
 
 ## Modules
 
-| Module | Capabilities | Description |
+| Module | Effects | Description |
 |--------|-------------|-------------|
 | `basic_cli.stdout` | `uses [Console]` | Standard output |
 | `basic_cli.stdin` | `uses [Console]` | Standard input |
@@ -46,9 +46,6 @@ default-entry = "app"
 [entries.app]
 path = "main.sp"
 
-[capabilities]
-allow = ["Compute"]
-
 [dependencies]
 basic-cli = { path = "../.." }
 ```
@@ -100,19 +97,19 @@ basic-cli/
 
 The current Platform contract MVP is intentionally split across two artifacts:
 
-1. `spore.toml` `[platform]` metadata names the contract module, the startup contract symbol, the adapter function, and the handled capabilities.
+1. `spore.toml` `[platform]` metadata names the contract module, the startup contract symbol, the adapter function, and the handled effects.
 2. `src/platform_contract.sp` owns the startup contract itself:
    - a hole-backed `main` function carries the authoritative startup signature
    - `main_for_host` is the Platform-owned adapter that receives the application startup function
 
-Applications targeting `basic-cli` must implement the same startup function name/signature in their entry module. The current compiler already resolves the package's `[platform]` metadata and `src/platform_contract.sp` to validate that startup shape. Runtime support is currently specialized to package-backed `basic-cli`: imported `basic_cli.*` foreign functions route through the built-in basic-cli host profile, while generic `[platform].handled-effects` enforcement and startup `spec` stacking are still follow-up work.
+Applications targeting `basic-cli` must implement the same startup function name/signature in their entry module. The current compiler already resolves the package's `[platform]` metadata and `src/platform_contract.sp` to validate that startup shape. Runtime support is currently specialized to package-backed `basic-cli`: imported `basic_cli.*` foreign functions route through the built-in basic-cli host profile, while generic handled-effects enforcement and startup `spec` stacking are still follow-up work.
 
 `src/host.sp` remains as a compatibility copy of the adapter for older references; current manifest-backed projects use `src/platform_contract.sp`.
 
 ## Tutorial Contract
 
 - `examples/hello-app/` is the **canonical project-mode example** — it is formatted, checked, built, and run in CI.
-- `examples/hello.sp` is a minimal standalone file for quick experiments (also validated in CI).
+- `examples/hello.sp` is a minimal standalone file for quick experiments.
 - `src/basic_cli/` is the API surface for the platform modules themselves.
 - `src/platform_contract.sp` is the package-owned startup contract surface.
 - Only add `tests/` when the repo has real Spore-side regression coverage worth running with `spore test`.
@@ -125,9 +122,9 @@ If you want to add a new tutorial/example, treat this as the bar:
 
 ## Design Philosophy
 
-Following Spore's [SEP-0003 (Effect Capability System)](https://github.com/spore-lang/spore-evolution/blob/main/seps/SEP-0003-effect-capability-system.md):
+Following Spore's [SEP-0003 (Effect System)](https://github.com/spore-lang/spore-evolution/blob/main/seps/SEP-0003-effect-system.md):
 
-- **Capability-gated**: Every I/O function declares its required capabilities via `uses [Cap]`
+- **Effect-gated**: Every I/O function declares its required effects via `uses [Effect]`
 - **Cost-annotated**: Platform functions can carry `cost [c, a, i, p]` budgets where meaningful
 - **Error-typed**: Functions declare error sets via `! ErrorType`
 - **Pure by default**: The platform boundary is the only place side effects occur
@@ -138,7 +135,7 @@ Following Spore's [SEP-0003 (Effect Capability System)](https://github.com/spore
 
 The canonical example is the **package-backed project-mode** `examples/hello-app/` application. It already validates and runs with `[project].platform = "basic-cli"`, an in-repo path dependency, and `import basic_cli.stdout`.
 
-The standalone file example (`examples/hello.sp`) stays around for quick experiments. The main remaining platform gaps are generic `[platform].handled-effects` enforcement, startup `spec` stacking, and lifting the runtime from its current explicit `basic-cli` host profile to a more general package-backed mechanism.
+The standalone file example (`examples/hello.sp`) stays around for quick experiments. The main remaining platform gaps are generic handled-effects enforcement, startup `spec` stacking, and lifting the runtime from its current explicit `basic-cli` host profile to a more general package-backed mechanism.
 
 ## License
 

examples/hello-app/spore.toml

@@ -11,8 +11,5 @@ default-entry = "app"
 [entries.app]
 path = "main.sp"
 
-[capabilities]
-allow = ["Compute"]
-
 [dependencies]
 basic-cli = { path = "../.." }

examples/hello-app/src/main.sp

@@ -1,12 +1,12 @@
-/// Canonical package-backed application example for basic-cli.
-///
-/// This mirrors the formatted `spore new` scaffold: import the
-/// platform module explicitly and call `println` directly from the
-/// imported basic-cli surface.
-/// Application entry point matching the platform contract.
+// Canonical package-backed application example for basic-cli.
+//
+// This mirrors the formatted `spore new` scaffold: import the
+// platform module explicitly and call `println` from the imported
+// basic-cli surface.
 import basic_cli.stdout as stdout
 
+/// Application entry point matching the platform contract.
 fn main() -> () uses [Console] {
-    println("Hello from a project-mode Spore application!")
+    println("Hello from a project-mode Spore application!");
     return
 }

prek.toml

@@ -22,6 +22,13 @@ hooks = [
   { id = "tombi-lint" },
 ]
 
+[[repos]]
+repo = "https://github.com/rhysd/actionlint"
+rev = "v1.7.12"
+hooks = [
+  { id = "actionlint" },
+]
+
 [[repos]]
 repo = "https://github.com/crate-ci/typos"
 rev = "v1.33.1"

spore.toml

@@ -10,7 +10,4 @@ startup-contract = "main"
 adapter-function = "main_for_host"
 handled-effects = ["Console", "FileRead", "FileWrite", "Env", "Spawn", "Exit"]
 
-[capabilities]
-allow = ["Compute"]
-
 [dependencies]

src/basic_cli/cmd.sp

@@ -1,6 +1,6 @@
 /// basic-cli platform — Process execution
 ///
-/// Run external commands with capability tracking.
+/// Run external commands with effect tracking.
 
 /// Run a command and capture its stdout as a string.
 /// Returns the full stdout output on success.