finos/morphir-scala / .claude/skills/squire
squire
VerifiedUse when morphir-scala work needs environment diagnostics or build/network/sandbox unblocking; reference repository management; branch lifecycle refresh after squash-merging a target branch into main; Morphir IR spec/schema sync or export; or task-tracking configuration and beads mode resolution.
references/doctor.md
View on GitHub# Squire Doctor — Diagnostic Reference
Full catalogue of known environment blockers and the step-by-step diagnostic procedure for `/squire doctor`.
---
## Diagnostic Workflow
Run the unified diagnostic and report each finding as ✅ (no action needed) or ⚠️ (blocker present) with the specific fix to apply:
```bash
${CLAUDE_PLUGIN_ROOT}/squire doctor
```
The command prints blocked findings as `ISSUE - <CODE> - <message>` and exits 1 when any finding is blocked.
Healthy findings, `NO_DAEMON`, and `REFUSED` are informational and do not make the command fail; when those are the
only findings, it exits 0.
### 1. Mill daemon TCP connectivity
- `PORT_OPEN` → daemon port responds to the same JVM socket mechanism Mill uses.
- `SANDBOX` → the JVM socket is blocked; use `--no-server`.
- `REFUSED` or `NO_DAEMON` → daemon not running; plain `./mill` will start one, or use `./mill --no-server`.
### 2. Effective JVM temp write access (cellar)
- `OK` → cellar can write temp files under the reported `java.io.tmpdir`.
- `BLOCKED` → see [cellar temp file error](#3-cellar-temp-file-permission-error).
- `UNAVAILABLE` → Java is missing or its bounded property query failed; no path was assumed.
### 3. Project configuration checks
Checks:
- Mill-owned Morphir Elm setup
- the Elm MEP YAML-owned `mainClass` setting
- Mill Morphir plugin and local-repository wiring
- machine acquisition cache state
- metabuild freshness
- effective JVM temp writability
`ISSUE` lines identify which fixes are needed.
---
## Known Issues & Resolutions
### 1. Mill daemon TCP socket blocked (Sandbox)
**Symptom:**
```text
java.net.SocketException: Operation not permitted
at mill.client.ServerLauncher$.connectToServer
Mill launcher failed.
```
**Cause:** The Claude Code sandbox *may* block JVM TCP socket connections (`java.net.Socket.connect`) depending on the active sandbox configuration in `~/.claude/settings.json` or managed settings. Even when `localhost`/`127.0.0.1` are in the allowed hosts list, raw JVM NIO sockets can be blocked at the OS level by the sandbox policy. This is not a universal restriction — it depends on how Claude Code is configured for your environment.
**Fix:** Use `--no-server` with Mill:
```bash
./mill --no-server <target>
```
**Do NOT** try to fix this by adding `allowLocalBinding: true` to sandbox settings — it allows *binding* but not *connecting*.
---
### 2. Elm MEP main class missing
The process extension declares its entry point in
`morphir/langkit/elm/compiler/mep/package.mill.yaml`:
```yaml
mainClass: morphir.langkit.elm.compiler.mep.Main
```
Restore that declaration if the doctor reports `main_class_task: NOT_FOUND`.
The root `morphir/package.mill.yaml` contains libraries only; the general Scala CLI has retired.
---
### 3. `cellar` temp file permission error
**Symptom:**
```text
/var/folders/hc/.../cellar-*.tasty: Operation not permitted
```
**Cause:** Cellar writes temp `.tasty` files to the JVM's active `java.io.tmpdir`. On macOS this is normally a user-specific directory below `/var/folders`, not the `/var/folders` root.
**Fix:** Probe a writable path, then pass it directly to the native Cellar process:
```bash
JAVA_TOOL_OPTIONS="-Djava.io.tmpdir=<writable-temp>" .claude/skills/squire/squire ai env info --check var-folders
.claude/skills/squire/squire cellar CELLAR_COMMAND CELLAR_COORDINATE CELLAR_ARGUMENTS --temp-directory "<writable-temp>"
```
`JAVA_TOOL_OPTIONS` configures the Java probe. Cellar is a native executable, so its wrapper passes the temp setting as a native runtime option.
---
### 4. `mise run setup` must not provision Morphir Elm
**Symptom:**
```text
curl: (22) The requested URL returned error: 504
error: postinstall script from "@morphir-examples/finance" exited with 1
```
**Cause:** Workspace postinstall hooks download Elm binaries, and legacy workspace dependencies installed a second
Morphir Elm CLI outside Mill's verified toolchain.
**Fix:** `mise run setup` always uses `bun install --ignore-scripts`; Morphir Elm dependencies and make scripts are
absent from the root workspace manifests. Mill provisions the locked compiler and owns fixture generation. Optional
Elm editor/formatting tooling remains a developer-local concern and is not part of the build contract.
---
### 5. Scalafmt lint failures
**Symptom:** CI `lint` job fails with `Found N misformatted files`
**Fix:**
```bash
./mill format
```
Prefer `./mill format --paths …` or `./mill format --changed` when only a few files drifted. Use `./mill format --kind scala` or `./mill format --kind elm` to narrow the sweep.
### 6. Mill Morphir plugin workflow
Read [mill-morphir.md](mill-morphir.md) for the fast and dogfood routes.
The project check may report:
- **Missing plugin module:** verify the plugin tree with `./mill resolve 'mill-plugins.morphir.__'`.
- **Broken local repository wiring:** run `./mill mill-plugins.morphir.integration.test`.
- **Corrupt cache entry:** rerun `./mill toolchains.node.runtimeHome` online. Verified acquisition replaces bad bytes.
- **Disabled machine cache:** generation remains correct but downloads stay task-local. Set `MORPHIR_NODE_DISABLE_MACHINE_CACHE=false` when reuse is wanted.
- **Stale metabuild:** run `./mill resolve 'mill-plugins.morphir.__'` to recompile it.
Squire only diagnoses these states. Mill owns acquisition, generation, and fresh-consumer acceptance.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |