Packaging and Release: a Global Command, a Config Directory, Versioning and Updates — a Twenty-One-Day Retrospective

The first obstacle: how TypeScript gets into the package

Every TS command-line tool hits this first, and the standard answer is usually dodged: declare a TS runner as a runtime dependency and point the entry at the TS source. That works, and it costs everyone who installs your tool a build toolchain of tens of megabytes — a sad way to break twenty days of zero-dependency discipline on the last one.

So the ruling is compile to JS and ship that: source in src, output in dist, only the output in the package. One more build step, in exchange for users installing plain JS that Node runs directly.

That step has a trap: the compiler only moves the files it compiles. Everything under src that is not TS — a subprocess script, a template, a static page, a data file — it ignores. And local development runs the source, never the output, so this failure cannot be reproduced on your own machine; it shows up on somebody else's, as one line saying a module was not found.

The fix is to copy them in the build script, and the copy must walk directories rather than read a hand-written list, which goes stale the day someone adds the first new file with nothing reporting it. This project's output happens to contain exactly two such files — day fifteen's notes-store subprocess and day eighteen's background task runner. Each appeared after the build script was written, and nobody changed a single character of that script for them. The same reasoning settles the manifest: files lists directories, not files.

"files": ["bin", "dist", "skills", "README.md", ".env.example"]

The moment you enumerate it file by file, that package starts its own expiry countdown.

Entry points: JS ships a file with a shebang, Python ships a function

A global command needs an entry point, and the two ecosystems divide the labor differently. On the Node side you name a file in the bin field and the installer symlinks to it. The shell executes that link, not node, so the first line must be a shebang; without it the error is a syntax error pointing nowhere near the cause. Python is the mirror image: you declare a callable in your packaging config and the installer generates the launcher — you never write a shebang, because you did not write that file.

#!/usr/bin/env node
// Three things: (1) the shebang on line one is not optional (2) the .mjs extension,
// so nothing depends on the package manifest's type field (3) not one line of logic —
// the bin path is part of the published contract and is painful to change afterwards
import '../dist/index.js'

import sys
# In pyproject.toml, under [project.scripts]: mca = "mca.cli:main"
# What you declare is a **function**. pip generates the launcher, which is why there is
# neither a shebang nor a main guard here.
def main() -> int:
    args = sys.argv[1:]
    if "--version" in args or "-v" in args:
        from importlib.metadata import version  # package metadata is the one source of truth
 
        print(f"mca {version('mca')}")
        return 0
    return run_repl(args)

Both sides share one discipline: the version number may have exactly one source of truth — the package manifest in Node, the package metadata in Python. Declare a second constant in code and some release updates one and forgets the other, after which every issue users file carries the wrong version. No test turns red for that.

Configuration layers: the narrower the scope, the higher it wins

For twenty days mca had one configuration layer: environment variables. That sufficed with one user, one repo, one terminal. Once installed elsewhere, four parties want the last word on one value.

flowchart TD
  A[built-in defaults<br/>the fallback when nothing is set] --> B[user config<br/>my personal default on this machine]
  B --> C[project config<br/>this repo's team convention, committed to git]
  C --> D[environment variables<br/>this terminal session]
  D --> E[command-line flags<br/>just this once]
  E --> F[the effective value<br/>which remembers which layer it came from]

That order is derived rather than tasteful: the narrower the scope, the higher it wins, because a narrower scope is the user saying "just this once" more explicitly. Reverse any pair and the symptom is the same — someone passes a flag, nothing happens, no error. Arrange the five as an ordered array applied in turn rather than a chain of conditionals, so adding a layer is inserting one element.

More interesting than the order: every value must remember where it came from. The common support question about layered config is not "the value is wrong," it is "I cannot tell why it is this." So each key carries its origin and a command lays them all out — not a debugging feature, but the precondition for anyone using the layering at all.

// Array order is override order: later entries win. Record the origin as you write the value.
for (const entry of stack) {
  for (const key of ['baseUrl', 'model']) {
    const value = entry.data[key]
    if (value === undefined) continue
    traced[key] = { value, layer: entry.layer, from: entry.from }
  }
}

from collections import ChainMap
 
# ChainMap is layered lookup by construction: earlier maps shadow later ones,
# so these are ordered highest priority first.
merged = ChainMap(flags, env, project, user, defaults)
labels = ["command-line flags", "environment variables", "project config", "user config", "built-in defaults"]
 
def trace(key: str) -> tuple[object, str]:
    # .maps keeps every layer, so "who supplied this value" needs no extra bookkeeping —
    # one walk answers it.
    for layer, label in zip(merged.maps, labels):
        if key in layer:
            return layer[key], label
    raise KeyError(key)

Since every earlier reader in this codebase reads an environment variable, three of them inside frozen files, the entry point writes the resolved values back into the environment rather than threading a config object through twenty files — fine on one condition: exactly one write point, before any provider is constructed.

What belongs in the config directory, and what must never

Config files live in two places: the user's home directory (personal defaults, never committed) and the project directory (the team convention, which does get committed). The project one is found by walking up to the first ancestor with a config directory, and stopping there — so nested repositories get a deterministic answer: the nearest wins.

Then today's line to remember above the others: secrets do not go in config files.

Not fastidiousness. Project config is committed to git; user config sits in plaintext in a home directory. Both get swept up by backup tools, sync folders, screenshots, and one casual "can you send me your config." An environment variable lives only inside this process.

One fork is easy to get wrong: when a secret turns up in a config file, do you ignore it or refuse and say so? It must be the second — ignoring silently means a user who did write a key keeps being told there is none, and concludes the tool is broken. Same for a misspelled key. And when printing configuration, mask secrets.

After a global install, three roots come apart for the first time

Locally, "where the code is," "which repo I am in," and "where my preferences live" are one directory, so one function returning the current directory covers all three. A global install separates them: the code sits in an install prefix that has nothing to do with the user.

One rule covers it: anything shipped with the package is located relative to the package; anything belonging to the user is never looked for inside the package. Locating the package means resolving upward from the module's own location, not hard-coding a count of relative levels — source and output sit at the same depth today, and a different build config changes that. Break the rule and the symptom is "works for me, missing files for everyone who installs it," again unreproducible locally, because locally those three roots are one directory.

The same rule widens the skills directory to three sources — shipped, the user's, the repo's — nearest wins a collision.

Two small things that must not get in the way: first run and update checks

The first time someone types a freshly installed command is the only attention it gets without earning it, and the worst answer is a stack trace. A decent message answers three things: what exactly is missing, which command fixes it (copyable as-is), and whether there is a way to look around without fixing it yet. That last escape hatch turns "I will look into this later" into "let me just run it."

The hard part of update checks is not the lookup, it is not getting in the way: done badly it adds two seconds to startup, prints red text offline, or takes the tool down when the registry misbehaves — each worse than upgrading a week late. Hence four rules: failures are always silent, there is always a timeout, check at most once a day, never check at all in offline mode.

export async function fetchLatestFromRegistry(name) {
  try {
    // The timeout is not an optimization; it is the precondition for this feature existing
    const response = await fetch(`${registry}/${name}/latest`, {
      signal: AbortSignal.timeout(1500),
    })
    if (!response.ok) return null
    const body = await response.json()
    return typeof body.version === 'string' ? body.version : null
  } catch {
    // "no answer this time" and "answered, no newer version" look identical to the user:
    // nothing extra on screen
    return null
  }
}

import json
import urllib.request
from contextlib import suppress
 
def fetch_latest(name: str) -> str | None:
    # suppress is the plainest way Python has to say "if this part fails, pretend it
    # never happened" — clearer than a bare except block that it was deliberate
    with suppress(Exception):
        url = f"https://pypi.org/pypi/{name}/json"
        with urllib.request.urlopen(url, timeout=1.5) as response:
            return json.load(response)["info"]["version"]
    return None

Non-interactive mode: the default answer to an approval prompt must be no

Once installed, this tool lands in places with no human in them: scripts, CI, git hooks. But a REPL is for people — on a non-interactive terminal standard input ends immediately, the program prints one line and exits with exit code 0. That is the false green this course has guarded against since day one, and today it becomes a product requirement: a run-once-and-exit mode.

That mode has its own discipline: the default answer to an approval prompt must be refusal. Interactively, "no answer" means hesitation; non-interactively it is the normal state, and treating it as consent hands every CI job an unlimited grant. Changing anything requires an explicit flag, and a blocked call's refusal should be written for the model to read, so it reroutes to a read-only path rather than retrying in place.

The last step: verifying is not "no errors," it is install it and run it again

The build succeeds, the package builds, not a line of red — and it dies in its first second on somebody else's machine. Same cause every time: locally you run the source, what you shipped is the output.

So the verification chain has to run, all four steps: build the package, install it into a temporary prefix, run the version command in a freshly created empty directory, then run one real task there. The temporary prefix keeps the user's global environment untouched; the empty directory exists because the current directory having nothing to do with the package is the thing under test. Afterwards, delete both.

In the lab this chain is five checks green, with a package of 192 KB containing 134 files — stable and reproducible for the same code. Install duration is not reproducible, depending on network and cache, so that script prints no timing number.

Source Reading

Hands-On Lab

All five exercises are the "green locally, explodes after install" family: a manifest enumerating files one by one, an entry point missing its first line, a build that compiles but copies nothing, layers ordered backwards with one missing, no secret gate, a stack trace on the first screen, an update check that takes startup down with it. The starter passes four of fourteen.

1. Switch the manifest to directory enumeration and add the entry point's first line, then watch checks 2 and 3 go green.
2. Add the directory walk copying non-TS assets, and watch check 4's missing-file list empty out.
3. Fix the layer order and add the flag layer, then see one value win at each of four layers, each time able to say where it came from.
4. Install the secret gate: a key in a config file is refused with a warning, and the printed configuration holds no plaintext.
5. Replace the first screen with the three-option message, swallow the update check's exception, run MOCK=1 SELFTEST=1 pnpm start for fourteen of fourteen, then pnpm verify:pack.

Acceptance is five ticks: all fourteen self-test checks pass; every source file has a counterpart in the output; the package holds output and entry point but no source and no dotenv file; without the authorization flag a write is refused and the file untouched; packaging verification is five for five with the temporary directory gone.

Interview Questions

Today's three questions test engineering judgment about distribution and configuration:

1. Publishing a command-line tool as a globally installable package, which traps are easy to overlook?
2. How do you decide the configuration layers and override order? Where do secrets belong?
3. Putting this project on your resume, how would you state its technical substance in three sentences?

Full prompts, analyses and key points are in this course's day-twenty-one question bank. Question one discriminates most — most answer "remember the bin and files fields," few say "locally you run the source, what you ship is the output, so install it and run it again" and name a failure that only surfaces after install.

Checklist and Tomorrow

• I can say why a TS project is compiled to JS for shipping, not shipped with a build tool as a runtime dependency
• I can state the trap that the compiler does not copy non-TS assets, and why it is unreproducible locally
• I can explain why the manifest and the asset copy both enumerate directories, not files
• I can derive the five layers' priority order rather than memorize it
• I can say why every value must remember its origin, and why printing origins is not a debugging feature
• I can explain why secrets stay out of config files, and why the response is "refuse and say so"
• I can name the three roots that come apart after a global install, and why this bug hides locally
• I can recite the update check's four rules and the consequence of no timeout
• I can explain why a non-interactive approval prompt defaults to refusal

What twenty-one days built

Go back to day one: a prompt on screen, and typing a sentence into it did nothing. Today it is a command installable anywhere that, in somebody else's repository, reads code, edits files, runs tests, stops to ask you, remembers last time, borrows other people's tools over MCP, works from the team's craft cards, splits work across parallel subagents, uses hooks to turn "read before you write" into a process it cannot route around, backgrounds long commands, understands a pasted screenshot, scores itself against a benchmark set, accounts for what a run cost — and can be rolled back at any point.

Each of those twenty layers did one small thing. The hardest was neither stream parsing nor compaction: it was approval, the first that forced you to answer "what is this allowed to do," which is not a technical question. The most valuable was probably the event log — once everything is an append-only sequence, resume, fork, rewind, evaluation and cost accounting become different readings of one dataset. And the layer most often skipped, most damaging when skipped, is today's.

How far this is from a production-grade Coding Agent

Honestly: quite far, and mostly not where you would guess.

• Editing: only exact replacement. Production handles patch formats, indentation drift, repeated edits to one region, partial rewrites of large files.
• Search: our grep is string matching; real repositories want semantic search and symbol indexes.
• Concurrency and isolation: our subagents are in-process. Production means real working-tree isolation, conflict merging, cleanup after a run is killed halfway.
• Robustness: we cover the error classes we knew about; the real world returns shapes you have never seen.
• Security: our approval gate guards local writes. Production also weighs prompt injection, over-broad reads, secret exfiltration.

That list is itself part of the payoff: you can now say specifically where the gap is, instead of vaguely feeling somebody else's is better.

Where to go next

Three directions, in increasing order of effort:

1. Make it a tool you use daily. Start with the trade-off today's README names (do not write the sandbox into the user's repo), then add two slash commands matching how you work. A week of daily use beats ten more articles.
2. Go deep on one area. Retrieval: the RAG course. Context budgeting: the context engineering course. Tool ecosystems and reusable experience: the MCP course and Skills course.
3. Turn it into presentable work. "Implemented a Coding Agent" carries no information on a resume. "Hand-wrote SSE parsing and tool-call fragment merging, an event log for session resume and forking, content-addressed snapshots for rollback" does. Today's packaging and README are the vehicle: one demo that runs beats a screenful of feature bullets.

Day one's sentence can be handed back to you now: the model has no memory and does not act on its own — it is the twenty-one layers you wrote that make it look as though it does.