Skip to content

finos/morphir-scala / .claude/skills/squire

squire

Verified

Use 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.

FileKindSize
.gitignoreother180 B
.mill-versionother19 B
README.mdmarkdown7.6 KB
SKILL.mdskill md6.7 KB
SquireBranch.scalaother6.4 KB
SquireCellar.scalaother7.4 KB
SquireChangelog.scalaother20.6 KB
SquireDoctor.scalaother13.9 KB
SquireEnv.scalaother16.2 KB
SquireModel.scalaother4.9 KB
SquireProcess.scalaother1.5 KB
SquireRepo.scalaother30.4 KB
SquireSchemas.scalaother25.2 KB
SquireSpec.scalaother35.6 KB
SquireTests.scalaother323.1 KB
SquireTracking.scalaother16.4 KB
SquireVersionCorpus.scalaother3.3 KB
millexecutablescript6.5 KB
mill.batscript9.7 KB
references/branch.mdmarkdown4.4 KB
references/cellar.mdmarkdown4.4 KB
references/doctor.mdmarkdown5.3 KB
references/env.mdmarkdown3.9 KB
references/mill-morphir.mdmarkdown1.6 KB
references/repo.mdmarkdown7.6 KB
references/spec-sync.mdmarkdown10.6 KB
references/tracking.mdmarkdown10.9 KB
squireexecutablescript1.2 KB
squire.batscript1.8 KB
squire.scalaother36.8 KB
test-resources/META-INF/services/kyo.test.Testother275 B
test-resources/schemas/morphir-ir-v4.jsonconfig107.1 KB
test-resources/schemas/morphir-ir-v4.yamlconfig74.2 KB

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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall