@evref-bl/pharo-mcp 0.0.0-stage → 1.4.0

package/templates/pharo-skills/pharo-ci-repro/references/pharo-smalltalkci.md

@@ -0,0 +1,102 @@
+# Pharo smalltalkCI Log Reading Notes
+
+Use this reference after a local Docker/smalltalkCI run has produced logs.
+
+## Phase Boundaries
+
+smalltalkCI logs usually split into:
+
+1. Preparing folders.
+2. Starting Pharo build.
+3. Downloading image and VM.
+4. Preparing image and loading SmalltalkCI.
+5. Loading project.
+6. Testing project.
+7. Coverage/upload/teardown.
+
+If the crash happens after `Testing project...`, project code loaded. If it
+happens during `Loading project...`, inspect the last Metacello package loaded
+and the first missing global/class/selector.
+
+## Useful Evidence To Extract
+
+- `Image Information`, including `Pharo13.1.0SNAPSHOT` or similar.
+- Build information SHA.
+- VM version, when printed.
+- The first test class/method named before a failure.
+- The first Smalltalk exception, before any secondary cleanup failure.
+- For segfaults, both the native C frames and the Smalltalk frames immediately
+  above the crash.
+
+## Focused Config Pattern
+
+To narrow a failing class while preserving the same load path, create a
+temporary config next to `.smalltalk.ston`:
+
+```ston
+SmalltalkCISpec {
+  #loading : [
+    SCIMetacelloLoadSpec {
+      #baseline : 'MyProject',
+      #directory : 'src',
+      #ignoreImage : true,
+      #onConflict : #useIncoming,
+      #onUpgrade : #useIncoming
+    }
+  ],
+  #testing : {
+    #classes : [
+      #MyProjectSuspectTest
+    ],
+    #hidePassingTests : true,
+    #failOnZeroTests : true
+  }
+}
+```
+
+Adjust the baseline, directory, and class for the project under test.
+
+## Pharo 13 / Iceberg / libgit2 Pattern
+
+In a Pharo MCP investigation on 2026-05-16, a P13 flaky CI crash reproduced
+locally inside Docker. It was not a dependency download issue: loading
+completed and testing had started.
+
+Crash signatures included:
+
+- C stack in `libgit2.so.1.4.4`
+- `git_repository_head_unborn`
+- `git_commit_lookup`
+- Smalltalk frames through `IceLibgitRepository`, `IceRepository>>headCommit`,
+  or `IceRepository>>validateCanCommit`
+- Test frames in a repository-management test
+
+The practical mitigation was to avoid unnecessary test-side `repository
+headCommit` reads and skip a P13 test that deliberately forced empty libgit2
+config values for a P12-only fallback path.
+
+General lesson: if a Pharo 13 Linux CI segfault points into libgit2 while
+testing fresh temporary repositories, treat it as a native stability surface.
+Avoid poking Iceberg head/commit metadata in tests unless the assertion is
+essential.
+
+## Interpreting Common Noise
+
+- `fatal: not a git repository`: often harmless when running smalltalkCI from a
+  scratch copy without `.git`. It matters only if the failing behavior depends
+  on Git metadata.
+- Metacello SSH authentication warnings followed by HTTPS fallback: often
+  harmless in Docker if the dependency eventually loads.
+- `StackOverflow` after a segfault: often VM aftermath, not the root cause.
+- `NewUndeclaredWarning`: can be benign during dependency load, but if it names
+  a project class/global required by the current package, investigate.
+
+## Verification Discipline
+
+After a fix:
+
+- Run the failing Pharo platform full suite.
+- Run adjacent supported platforms, usually P12 and P13 for MCP.
+- Run focused repeats for the flaky class/method if the original failure was
+  intermittent.
+- Keep the captured failing log path in the report.

package/templates/pharo-skills/pharo-ci-repro/scripts/run-smalltalkci-docker.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+set -u
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  run-smalltalkci-docker.sh --repo REPO_DIR [options]
+
+Options:
+  --repo DIR          Source repository or working tree to test.
+  --platform NAME    smalltalkCI platform, default Pharo64-13.
+  --spec FILE        smalltalkCI spec file, default .smalltalk.ston.
+  --attempts N       Number of attempts, default 1.
+  --out DIR          Scratch/log directory, default /tmp/pharo-ci-repro-<timestamp>.
+  --image IMAGE      Docker image, default hpiswa/smalltalkci:24.04.
+  --docker-platform PLATFORM
+                      Docker platform, default linux/amd64.
+  --include-git      Copy .git into each scratch tree.
+  --keep-going       Continue after failures instead of stopping at first one.
+  --help             Show this help.
+
+Each attempt gets a fresh copied work tree and a log at OUT/logs/attempt-N.log.
+USAGE
+}
+
+repo=""
+platform="Pharo64-13"
+spec=".smalltalk.ston"
+attempts="1"
+out=""
+image="hpiswa/smalltalkci:24.04"
+docker_platform="linux/amd64"
+include_git="false"
+keep_going="false"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --repo)
+      repo="${2:-}"
+      shift 2
+      ;;
+    --platform)
+      platform="${2:-}"
+      shift 2
+      ;;
+    --spec)
+      spec="${2:-}"
+      shift 2
+      ;;
+    --attempts)
+      attempts="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out="${2:-}"
+      shift 2
+      ;;
+    --image)
+      image="${2:-}"
+      shift 2
+      ;;
+    --docker-platform)
+      docker_platform="${2:-}"
+      shift 2
+      ;;
+    --include-git)
+      include_git="true"
+      shift
+      ;;
+    --keep-going)
+      keep_going="true"
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ -z "$repo" ]; then
+  echo "--repo is required" >&2
+  usage >&2
+  exit 2
+fi
+
+if [ ! -d "$repo" ]; then
+  echo "Repo directory does not exist: $repo" >&2
+  exit 2
+fi
+
+case "$attempts" in
+  ''|*[!0-9]*)
+    echo "--attempts must be a positive integer" >&2
+    exit 2
+    ;;
+esac
+
+if [ "$attempts" -lt 1 ]; then
+  echo "--attempts must be at least 1" >&2
+  exit 2
+fi
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "Docker CLI not found. Install a container runtime that provides the Docker CLI/API, or use a local smalltalkCI fallback." >&2
+  exit 69
+fi
+
+if ! docker info >/dev/null 2>&1; then
+  echo "Docker API is not reachable. Start or repair the local container runtime, then retry this command." >&2
+  echo "If container reproduction is not available and the failure is not OS/runtime-sensitive, use a local smalltalkCI fallback with isolated smalltalkCI homes for parallel jobs." >&2
+  exit 69
+fi
+
+if [ -z "$out" ]; then
+  out="/tmp/pharo-ci-repro-$(date +%Y%m%d%H%M%S)"
+fi
+
+mkdir -p "$out/logs"
+
+echo "Source: $repo"
+echo "Platform: $platform"
+echo "Spec: $spec"
+echo "Attempts: $attempts"
+echo "Output: $out"
+echo "Docker platform: $docker_platform"
+echo
+
+status=0
+i=1
+while [ "$i" -le "$attempts" ]; do
+  work="$out/work-$i"
+  log="$out/logs/attempt-$i.log"
+  rm -rf "$work"
+  mkdir -p "$work"
+
+  if [ "$include_git" = "true" ]; then
+    rsync -a --exclude coverage "$repo"/ "$work"/
+  else
+    rsync -a --exclude .git --exclude coverage "$repo"/ "$work"/
+  fi
+
+  echo "=== Attempt $i/$attempts ==="
+  echo "Log: $log"
+
+  docker run --rm --platform "$docker_platform" \
+    -v "$work:/work/project" \
+    -w /work/project \
+    "$image" \
+    smalltalkci -s "$platform" "$spec" 2>&1 | tee "$log"
+
+  attempt_status="${PIPESTATUS[0]}"
+  if [ "$attempt_status" -ne 0 ]; then
+    echo "Attempt $i failed with status $attempt_status"
+    echo "Failure log: $log"
+    status="$attempt_status"
+    if [ "$keep_going" != "true" ]; then
+      exit "$status"
+    fi
+  else
+    echo "Attempt $i passed"
+  fi
+
+  i=$((i + 1))
+done
+
+exit "$status"

package/templates/pharo-skills/pharo-image-git-handoff/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: pharo-image-git-handoff
+description: Reconcile live Pharo, Iceberg, Tonel, and Git state before exporting, reviewing, committing, or pushing image-side changes. Use for dirty or detached Iceberg state, linked worktrees, package-membership mismatches, and image-to-Git delivery.
+---
+
+# Pharo Image Git Handoff
+
+Image objects, Tonel files, Iceberg working copies, and Git refs are distinct.
+A clean Git worktree does not prove the image is clean, and an Iceberg diff does
+not prove files changed on disk.
+
+## Workflow
+
+1. Inspect the image repository with Pharo MCP tools: identity, location,
+   branch/head, source directory, package membership, and modified packages.
+2. Inspect disk with read-only Git commands: `git status --short --branch`,
+   `git diff`, and `git remote -v`.
+3. Export only for an intended Tonel/Git handoff. Verify repository identity and
+   inspect the image-side change list first.
+4. After export, recheck Iceberg and Git. Review every changed Tonel, project,
+   and documentation path.
+5. Commit only the intended diff. Push only when explicitly requested or
+   clearly approved.
+
+## Stop Before Mutation
+
+Stop and diagnose detached or missing heads, wrong branches/remotes, duplicate
+repository names, source-directory or package-membership mismatches, linked
+worktree confusion, and unexplained disagreement between Git and Iceberg.
+
+Adopt the current Git HEAD only when the image contents are known to match it.
+Ask the user before resolving real divergence or discarding image changes.
+
+## Report
+
+Report image repository state before and after export, why export was needed,
+Git branch/status and diff summary, checks run, and unresolved ambiguity.

package/templates/pharo-skills/pharo-image-git-handoff/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo Image Git Handoff"
+  short_description: "Export Pharo image changes safely"
+  default_prompt: "Use $pharo-image-git-handoff to turn these Pharo image changes into clean Tonel/Git changes safely."

package/templates/pharo-skills/pharo-mcp-recovery/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: pharo-mcp-recovery
+description: Recover an unreachable or crashed standalone Pharo MCP image while preserving logs, image files, changes, repository state, and Epicea history. Use for local MCP restart, replacement-image creation, and image-side change recovery.
+---
+
+# Pharo MCP Recovery
+
+Use project-managed lifecycle tools when they exist. This workflow is for a
+standalone image without a safer environment-specific recovery surface.
+
+## Workflow
+
+1. Determine whether the failure is the client route, MCP server, image, or
+   process.
+2. Preserve the image, changes, sources, VM logs, launch command, MCP URL, and
+   repository/Git facts before mutation.
+3. Restart the same image first. Inspect `isRunning`, `isListening`, and
+   `localUrlString`; restart the existing MCP instance when possible.
+4. Create a replacement image only after preserving the original. Use
+   `pharo-project-load` to restore MCP and the target project.
+5. Recover changes by inspecting Epicea history before confirmed application.
+   Use `pharo-image-git-handoff` before repository attachment or Tonel export.
+6. Verify the recovered behavior with focused inspection or tests.
+
+## Stop And Ask
+
+Ask before deleting images, resetting repositories, discarding changes,
+checking out a branch that changes loaded packages, or applying ambiguous
+history entries.
+
+## Report
+
+Report the failure boundary, evidence preserved, image used, restart/recovery
+actions, recovered behavior, checks run, and unrecovered state.

package/templates/pharo-skills/pharo-mcp-recovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo MCP Recovery"
+  short_description: "Recover a stopped Pharo MCP image"
+  default_prompt: "Use $pharo-mcp-recovery to restart Pharo MCP and recover image changes."

package/templates/pharo-skills/pharo-project-load/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pharo-project-load
+description: Load or smoke-test a Pharo project from Tonel, Metacello, or Iceberg and diagnose baseline, branch, source-directory, group, dependency, or version-specific load failures. Use for fresh-image loads and CI-equivalent project loading.
+---
+
+# Pharo Project Load
+
+## Context
+
+Before loading, read the project README, baseline, `.smalltalk.ston`, and any
+repository-specific agent guidance. Prefer dedicated Pharo MCP load tools when
+a live image is available.
+
+## Workflow
+
+1. Identify the Pharo version, repository URL/path, branch or commit, source
+   directory, baseline name, and required load group.
+2. Confirm that `BaselineOf<Name>` and the Tonel packages exist under the
+   selected source directory. Check that repository URLs and `.project` agree.
+3. Load the default baseline first. Specify a group only when project or CI
+   configuration requires it.
+4. Verify loaded packages/classes and run focused or project tests.
+5. Inspect Iceberg state when later edits or export are in scope.
+
+Minimal remote load:
+
+```smalltalk
+Metacello new
+  baseline: 'MyProject';
+  repository: 'github://Owner/MyProject:main/src';
+  load
+```
+
+For local Tonel, use an absolute `tonel:///.../src` URL.
+
+## Diagnose By Phase
+
+- Baseline/package not found: verify branch and source directory.
+- Missing global/class/selector: compare the project API surface with the
+  target Pharo version; use `pharo-version-compat` when appropriate.
+- Metacello conflict: reproduce the project's documented or CI conflict policy.
+- Native or CI-only failure: reproduce once, then use `pharo-ci-repro`.
+
+## Report
+
+Report the Pharo version, repository and revision, source directory, baseline,
+group, load result, verification result, and first meaningful failure.

package/templates/pharo-skills/pharo-project-load/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo Project Load"
+  short_description: "Load Pharo Tonel projects"
+  default_prompt: "Use $pharo-project-load to load this Pharo project into an image and diagnose any Metacello or Tonel load failures."

package/templates/pharo-skills/pharo-version-compat/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pharo-version-compat
+description: Use PharoCompatibility to load and test a project across supported Pharo versions. Use for missing or renamed Pharo globals, classes, selectors, packages, notices, or semantics; baseline surface selection; and reusable cross-version shims.
+---
+
+# Pharo Version Compatibility
+
+## Model
+
+`PharoCompatibility` handles Pharo-version differences, not library-specific
+workarounds. A project declares the Pharo API surface its source expects; the
+runtime loads the compatibility packages needed by the current image.
+
+Known source surfaces include `Pharo12Surface` and `Pharo13Surface`. Omit a
+surface only when the project needs the core helper API alone.
+
+## Workflow
+
+1. Read the project baseline, supported-version policy, and CI matrix.
+2. Identify the source Pharo surface and target runtime versions.
+3. Load the matching surface from the project baseline:
+
+```smalltalk
+spec
+  baseline: 'PharoCompatibility'
+  with: [
+    spec
+      repository: 'github://Evref-BL/PharoCompatibility:main/src';
+      loads: #( 'Pharo13Surface' ) ]
+```
+
+4. Reproduce on every affected Pharo version and classify the failure: missing
+   binding, missing selector, rename, semantic change, notice behavior, or
+   native/tooling failure.
+5. Choose the narrowest owner:
+   - transparent shim for equivalent APIs;
+   - explicit PharoCompatibility helper for reusable behavior;
+   - project abstraction for irreducible semantic differences;
+   - project-local fix for library-specific behavior.
+6. Verify both PharoCompatibility and the consuming project across the matrix.
+
+## Extending PharoCompatibility
+
+- Confirm the difference is general and assign it to a source surface and
+  runtime version.
+- Put runtime code in the matching conditional package and baseline group.
+- Use late lookup for optional globals.
+- Keep shims additive when possible and test the compatibility contract, not
+  only package loading.
+
+Use `pharo-project-load` for load-path failures and `pharo-ci-repro` for
+smalltalkCI or runner-specific failures.
+
+## Report
+
+Report source surface, runtimes tested, failure classification, shim owner,
+packages changed, and matrix results.

package/templates/pharo-skills/pharo-version-compat/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo Version Compatibility"
+  short_description: "Use PharoCompatibility surfaces"
+  default_prompt: "Use $pharo-version-compat to make this Pharo project compatible across supported Pharo versions with PharoCompatibility."

package/templates/pharo.AGENTS.md

@@ -0,0 +1,42 @@
+# Pharo MCP Agent Guide
+
+Use the configured `pharo` MCP server whenever a task depends on the running
+image. Preserve unrelated changes and report unavailable live checks instead of
+guessing from source.
+
+## Read First
+
+- Inspect the tools and schemas exposed by the current client; do not rely on
+  remembered names.
+- Prefer the least-mutating dedicated tool. Use `image_evaluate` only when no
+  dedicated tool fits.
+- Treat image, Tonel, Iceberg, and Git state as separate.
+- Successful mutating tools save the image; use a safe image boundary.
+
+## Context Loading
+
+- Before Pharo source changes: read the project's Pharo coding and testing
+  guidance. If none exists, use the local
+  [coding rules](pharo-references/pharo-coding-rules.md) and
+  [coding style](pharo-references/pharo-coding-style.md).
+- Before loading a project: use `skills/pharo-project-load/SKILL.md`.
+- Before cross-version work: use `skills/pharo-version-compat/SKILL.md`.
+- Before exporting image changes or changing Git state: use
+  `skills/pharo-image-git-handoff/SKILL.md`.
+- Before reproducing smalltalkCI or GitHub failures: use
+  `skills/pharo-ci-repro/SKILL.md`.
+- Before recovering a stopped standalone image: use
+  `skills/pharo-mcp-recovery/SKILL.md`.
+- Before debugger sessions or repairs: read the local
+  [debugging guide](pharo-references/debugging.md).
+
+## Workflow
+
+1. Discover the exact tool and inspect the target with read-only calls.
+2. Preview or verify identity before risky mutation.
+3. Make the narrowest image-side change.
+4. Run focused SUnit tests and inspect the result.
+5. Use the handoff skill before exporting or committing Tonel changes.
+
+For repository work, verify repository identity before mutation and inspect the
+image-side diff before export or commit.