Craft on Alfero Chingono

Fixing Deep Nesting in TypeScript: A Real Refactor From CueMarshal

Tue, 10 Feb 2026 09:00:00 +0000

There’s a point in the lifecycle of any project where the “quick fix” logic starts to pile up. For the Gitea MCP server in CueMarshal, that point was the get_pr_diff tool.

What started as a simple API call had grown into a 150-line function with four levels of nested if/else statements. It was classic “Arrow Code”: the logic was pointed so far to the right that it was getting hard to read on a standard monitor.

Here’s how I refactored it and the TypeScript patterns I used to make it maintainable.

The Problem: The “Arrow Code” Trap

The original function had to handle multiple failure modes:

Check if the repository exists.
Check if the pull request exists.
Check if the diff is too large for the LLM’s context.
Handle the Gitea API’s specific error formats.

If any of these failed, I had to return a structured error message. This led to a pattern of:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


if (repoExists) {
 if (prExists) {
 const diff = await getDiff();
 if (diff.length < LIMIT) {
 // Success!
 } else {
 // Error: Too large
 }
 } else {
 // Error: PR missing
 }
} else {
 // Error: Repo missing
}

This is hard to follow because the “Success” case is buried in the middle, and the “Error” cases are disconnected from their triggers.

The Solution: Guard Clauses and “Return Early”

The first step was to flip the logic. Instead of nesting for success, I used Guard Clauses to return early on failure.

1
2
3
4
5
6
7
8


if (!repoExists) return { error: "Repo missing" };
if (!prExists) return { error: "PR missing" };

const diff = await getDiff();
if (diff.length >= LIMIT) return { error: "Diff too large" };

// Success! (Now at the top-level indentation)
return { diff };

This immediately flattened the function and made it much more readable.

Leveling Up with TypeScript’s `Result` Type

To make this even more reliable, I introduced a Result type pattern (inspired by Rust or F#). Instead of returning null or throwing an error, every step of the process returns an object that explicitly states if it succeeded or failed.

1
2
3


type Result<T, E = string> =
 | { ok: true; value: T }
 | { ok: false; error: E };

Using this pattern, I could chain the operations together. If any step returns { ok: false }, the whole chain stops and returns that error.

The “Functional” Refactor

The final version of the get_pr_diff tool now looks like this:

Validate Inputs: A clean, typed function that ensures the repo and PR IDs are valid.
Fetch PR Data: A separate function that handles the Gitea API call and maps the error codes to human-readable messages.
Process Diff: A dedicated function for the logic of truncation and formatting.

By splitting these into small, testable functions, the main execute method for the tool became a simple 10-line orchestrator.

Why This Matters for Agentic AI

Refactoring for “Clean Code” isn’t just for human developers anymore. When you are building Agentic Orchestras, your code is the environment the agent has to reason about.

If your codebase is full of deep nesting and “spaghetti” logic, the AI is more likely to make mistakes when trying to refactor or extend it. Clean, flat, typed code makes your system more “agent-friendly.”

The refactor of the Gitea MCP server didn’t just make my life easier; it made CueMarshal’s agents faster and more reliable.

Related reading:

Sandboxed Code Execution for Kids: How Judge0 and Python sys.settrace Power FireFly

Thu, 15 Jan 2026 09:00:00 +0000

When you build a platform for kids to learn to code, like FireFly, the hard problem is safety.

Letting a developer run arbitrary code in a container is one thing. Letting a 7-year-old, who might accidentally or intentionally write an infinite loop or a memory-hogging script, run code on your servers is another.

For FireFly, I needed a solution that was:

Secure: No “breakouts” to the host machine.
Fast: Near-instant execution so the learning flow isn’t broken.
Traceable: I needed to know exactly which line was running at any moment so the AI tutor could give grounded feedback.

The solution ended up being a combination of Judge0 and Python’s sys.settrace().

Layer 1: The Hard Sandbox (Judge0)

The first line of defense is Judge0, an open-source online code execution system. I run Judge0 in a set of Docker containers. When a student in FireFly clicks “Run,” their code is sent to the Judge0 API, which:

Creates a temporary, isolated worker.
Enforces strict CPU and memory limits.
Limits the execution time to a few seconds.
Returns the output (or the error).

This handles the outer safety boundary. Even if a student tries to import os; os.system('rm -rf /'), Judge0 catches it or confines the damage to a disposable container.

Layer 2: The Soft Sandbox (Python `sys.settrace`)

Judge0 keeps the system safe, but it does not tell me why a student got stuck. To power a Socratic AI Tutor, the system needs to see the internal state of execution: which variables change, and which lines get hit.

To do that, I wrap the student’s Python code in a tracer script that uses sys.settrace(). It is a built-in Python hook that lets you run a function for each executed line.

How the Tracer Works:

Line-by-line tracking: As the code runs, the tracer records the current line number and the values of local variables.
Instruction limit: If the code takes too many steps, as in an infinite loop, the tracer raises a custom exception and stops execution before Judge0 has to step in.
State snapshot: At the end of the run, the tracer returns a breadcrumb trail of the execution.

Layer 3: The AI Tutor Feedback Loop

The “breadcrumb” from the tracer is what makes the FireFly AI Tutor so effective. Instead of just seeing “Error: NameError: name ‘x’ is not defined,” the AI can see: “The student defined x on line 2, but they are trying to use it on line 5 inside a function where it’s not in scope.”

This level of detail allows the AI to ask much better Socratic questions.

Why This Matters for EdTech

We often think of “sandboxing” as a security feature for protecting servers. In EdTech, it is also a pedagogical feature. A safe, observable environment gives kids room to experiment, break things, and learn from their mistakes without real-world consequences.

Building this part of FireFly has been one of the most satisfying engineering problems in the project. It sits right where security requirements and teaching goals meet.

Related reading:

Building a Multi-Currency App: The Edge Cases Nobody Warns You About

Wed, 22 Oct 2025 09:00:00 +0000

When I started building Famorize, I thought multi-currency support would be a weekend feature. “Just store the currency code and multiply by the exchange rate, right?”

Wrong.

Dealing with money in software is a masterclass in edge cases, data integrity, and precision. If you’re building an app that handles more than one currency, especially one designed for families across borders, the complexity stacks up fast.

Here are the four big lessons I learned from building Famorize’s multi-currency engine.

1. Never, Ever Use Floating Point Numbers

This is the “Day 1” rule for financial software, yet I still see it in production. Floating point numbers (like double or float in most languages) are inherently imprecise for decimals. $0.1 + 0.2$ in IEEE 754 floating point is not $0.3$; it’s $0.30000000000000004$.

In Famorize, everything is stored as integers in the smallest unit (e.g., cents for USD, yen for JPY, satoshis for BTC). If a transaction is $10.50, it is stored as 1050. This eliminates rounding errors at the database and application levels.

2. Exchange Rate “Drift” and Historic Validity

Exchange rates are not static. If a user recorded a $50 CAD transaction today, it might be worth $37 USD. If they look at that same transaction next year, it should still be $50 CAD. But what was its USD value at the time?

To handle this, Famorize doesn’t just store the transaction. It stores:

The Base Amount (in the user’s home currency).
The Original Amount (in the transaction currency).
The Exchange Rate Used (at the time of the transaction).

This “Snapshot Pattern” ensures that reports are accurate to the moment the money actually moved, not the current market rate.

3. The “Yen Problem” (Zero-Decimal Currencies)

Most developers assume a currency always has two decimal places. This is a trap.

While USD, CAD, and EUR have two (cents), currencies like JPY (Japanese Yen) have zero, and others like BHD (Bahraini Dinar) have three. If your UI or database assumes integer / 100 is the decimal value, you will break for users in Japan or Bahrain.

Famorize uses a Currency Metadata table that defines the “Scale” (decimal places) for every supported currency. The display layer is responsible for formatting based on this scale.

4. The UX of “Which Currency?”

If a user in Toronto is sending money to a family member in Nairobi, which currency should the input field show?

The UX pattern that worked best for me was to always let the user select the Transaction Currency while showing a real-time “estimated conversion” into their Home Currency. That gives them a clearer sense of how much they are spending in the units they understand.

The Result

Building a multi-currency app taught me that “precision” is not just a technical requirement; it is a trust requirement. If a financial app is off by even one cent, the user’s trust is broken.

Famorize now handles dozens of currencies with an integer-based engine that I can trust with real family finances. It took more than a weekend, but the lessons were worth the effort.

Related reading:

OAuth2 and OIDC for Solo Developers: A Practical Setup With Docker

Mon, 15 Sep 2025 09:00:00 +0000

Authentication is the classic “black hole” of side projects. You start with a simple idea, and four days later you’re still reading RFC 6749 and wondering if you should just use a password in a plain text file (don’t).

For my personal projects like Famorize and FireFly, I needed something standards-compliant and easy to manage across multiple services. It also had to be dependable. I didn’t want to pay $50/month for a managed identity provider (IdP) for projects that were still in development, but I also didn’t want to roll my own crypto.

The solution was a self-hosted OIDC setup using Docker.

Why OIDC?

If you’re building a “modern” app, you’re likely using a decoupled architecture: a frontend (React/Next.js/Hugo) and one or more backend APIs. You need a way to:

Log a user in.
Prove to the API that the user is who they say they are.
Do it securely without sharing passwords everywhere.

OpenID Connect (OIDC) is the standard way to do this. It sits on top of OAuth2 and provides the “identity” layer.

The Stack

For my local and production environments, I settled on a “trio” of tools that play very well together in Docker Compose.

Authelia: A lightweight, self-hosted IdP. It’s fast, has a great UI, and supports multi-factor authentication (MFA) out of the box.
Redis: For session storage and rate-limiting.
Nginx Proxy Manager (or Traefik): To handle the routing and SSL termination.

The “Local First” Workflow

The biggest pain point with OIDC is setting it up locally. Most managed services require a public redirect URI, which is a nightmare for localhost development.

With a self-hosted setup, I can use a local domain (like auth.local.chingono.com) and point it to my Docker container. This means my local development environment is identical to production. If it works on my machine, the OIDC flow will work in the cloud.

Key Lessons Learned

Building this into my projects taught me a few hard-won lessons:

Scopes and Claims are everything. Spend the time to understand the difference. Don’t just request openid profile email and hope for the best. Define only what your app actually needs.
HTTPS is non-negotiable. Even for local development, OIDC requires secure cookies. Use mkcert to generate local SSL certificates and save yourself the headache of “Insecure Connection” errors.
Token rotation matters. If you’re building a long-lived app (like a mobile client for Famorize), you need to handle refresh tokens correctly. Don’t just set a 30-day expiration on your access tokens.

Why Not Just Use Auth0 or Clerk?

Managed services are great for teams with a budget and no time. But as a solo developer who enjoys the “Build in Public” ethos, I find that owning my identity layer is worth the extra effort. It gives me complete control over the user experience, total data sovereignty, and a much deeper understanding of the security architecture.

If you’re interested in the specific Docker Compose configurations I use, stay tuned for the next post in this “Craft” series.

Related reading:

Craft on Alfero Chingono

Fixing Deep Nesting in TypeScript: A Real Refactor From CueMarshal

The Problem: The “Arrow Code” Trap

The Solution: Guard Clauses and “Return Early”

Leveling Up with TypeScript’s Result Type

The “Functional” Refactor

Why This Matters for Agentic AI

Sandboxed Code Execution for Kids: How Judge0 and Python sys.settrace Power FireFly

Layer 1: The Hard Sandbox (Judge0)

Layer 2: The Soft Sandbox (Python sys.settrace)

How the Tracer Works:

Layer 3: The AI Tutor Feedback Loop

Why This Matters for EdTech

Building a Multi-Currency App: The Edge Cases Nobody Warns You About

1. Never, Ever Use Floating Point Numbers

2. Exchange Rate “Drift” and Historic Validity

3. The “Yen Problem” (Zero-Decimal Currencies)

4. The UX of “Which Currency?”

The Result

OAuth2 and OIDC for Solo Developers: A Practical Setup With Docker

Why OIDC?

The Stack

The “Local First” Workflow

Key Lessons Learned

Why Not Just Use Auth0 or Clerk?

Leveling Up with TypeScript’s `Result` Type

Layer 2: The Soft Sandbox (Python `sys.settrace`)