New file (2026-08-12), started while investigating the payout/ledger work. See also
learning/09-devops.md (deployment, env vars, server logs) and
learning/backend/06-money-ledger-and-payouts.md (the Prisma CLI commands used to generate
migration SQL safely).

This file covers: searching a codebase with grep and the zsh glob gotcha that silently
breaks it, find with pruning, sizing up an unfamiliar codebase quickly, loading .env
into a shell session, how ordinary commands leak credentials, and using curl status codes to
check what a deployed server is actually running.


Part 1 — grep -r for Codebase Investigation

The workhorse for “does this code actually do what the schema claims”:

grep -rni "withdrawal" --include='*.ts' . | grep -v "modules/withdrawals"

Flag by flag:

FlagMeaning
-rrecursive — walk directories
-nprint line numbers (so you can jump straight to it)
-icase-insensitive
--include='*.ts'only search files matching this pattern

Piping to grep -v <pattern> excludes matches — here, “show me every mention of
withdrawal outside its own module.” That single command is what proved the withdrawal
system was dead code: the only hit was one import line in app.module.ts, meaning nothing in
the entire codebase ever approved or paid a withdrawal.

The zsh gotcha that will bite you

This fails in zsh:

grep -rn "withdrawal" --include=*.ts .
# zsh: no matches found: --include=*.ts

Why: zsh expands globs before the command runs. It tries to expand *.ts against the
current directory, finds no .ts files there, and — unlike bash, which would pass the
pattern through unchanged — zsh treats “no matches” as a hard error and refuses to run the
command at all.

Fix: quote it, so the shell passes the literal string to grep and lets grep do the
matching:

grep -rn "withdrawal" --include='*.ts' .

The general rule: any glob meant for the program rather than the shell must be quoted.
Same applies to find -name '*.ts'.

Searching for several things at once

Alternation with \| (basic regex) finds any of a set of terms — useful for “does this
concept exist anywhere under any of its likely names”:

grep -rni "platformFee\|commission\|serviceFee\|netAmount" --include='*.ts' .

Empty output here was the actual finding: no platform-fee logic existed anywhere.

Beware echo "(exit: $?)" after a pipeline — $? reports the exit status of the last
command in the pipe, not the grep you cared about. To test whether grep matched, check its
status directly, or just look at whether output appeared.


Part 2 — find with Pruning

find . -path ./node_modules -prune -o -name "*.prisma" -print

Reads as: “for the path ./node_modules, prune it (don’t descend); otherwise (-o), if the
name matches *.prisma, print it.”

-prune is what makes find fast in a JS project. Without it, find walks every one of the
tens of thousands of files under node_modules. The -print at the end is required here
— once you use -o, the implicit “print everything” behaviour goes away, and without it the
command silently outputs nothing.


Part 3 — Sizing Up an Unfamiliar Codebase

wc -l *.prisma | sort -n

wc -l counts lines; sort -n sorts numerically (not lexically — without -n, “100” sorts
before “20”). Run over a schema directory it immediately shows where the complexity lives:

   21 withdrawals.prisma
   79 billing.prisma
  136 tickets.prisma
  237 enums.prisma
 1296 total

A 21-line file for the entire payout system next to a 136-line ticketing file is a strong
signal about which one was actually finished.

Related, for structure rather than size:

ls */ -d          # list only directories
ls -R modules/payments   # recurse one subtree

Part 4 — Loading .env Into Your Shell

Some CLI tools need env vars present in the shell, not just loaded by the app:

set -a && source .env; set +a
  • set -a — auto-export: every variable assigned from now on is exported to child
    processes automatically.
  • source .env — run the file in the current shell (so the assignments stick). ./ would
    run it in a subshell and the variables would vanish when it exited.
  • set +a — turn auto-export back off, so you don’t accidentally export everything else you
    define later.

Without set -a, source .env defines the variables as shell-local only, and the command you
run next won’t see them.

Caution: this puts secrets into your shell environment for the rest of the session, where
any process you launch can read them. Prefer letting the tool load .env itself when it can.


Part 5 — Credentials Leaking Through Ordinary Commands

Running npx prisma validate printed this:

DEBUG: DATABASE_URL = postgres://avnadmin:AVNS_KfQ...@pg-....aivencloud.com:18220/defaultdb

The cause was a leftover line in prisma.config.ts:

console.log('DEBUG: DATABASE_URL =', process.env.DATABASE_URL); // ← Add this temporary line

Two lessons:

  1. A console.log of a connection string leaks the password to every log that captures
    stdout
    — your terminal scrollback, CI build logs, deployment logs. CI logs in particular
    are often readable by more people than the database itself.

  2. A comment saying “temporary” is not a mechanism. If you add a debug line that prints a
    secret, delete it in the same session. Grep for it before committing:

    grep -rn "console.log.*process.env" --include='*.ts' .

Once a credential has been printed, rotating it is the only real fix — you cannot un-print it
from logs you don’t control.


Part 6 — curl for Checking What a Server Actually Returns

Often you don’t want a response body — you want to know whether an endpoint exists, or is up,
or how slow it is. This prints only the status code:

curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/v1/some/route
FlagMeaning
-ssilent — suppress the progress meter, which otherwise pollutes output
-o /dev/nullthrow the response body away
-w "..."write-out: print this template after the request completes
--max-time 60give up after 60s (essential against cold-starting free-tier hosts)

-w understands a set of variables, and the useful ones beyond %{http_code} are:

curl -s -o /dev/null -w "%{http_code} in %{time_total}s\n" "$URL"
curl -s -o /dev/null -w "connect %{time_connect}s  ttfb %{time_starttransfer}s\n" "$URL"

%{time_starttransfer} (time to first byte) is the one that separates “the server is slow” from
“the network is slow” — a high TTFB with a fast connect means the server is thinking.

Looping over several endpoints

Checking a whole set at once, formatted so it’s readable:

B=https://api.example.com
for p in /v1/earnings/balance /v1/payouts /v1/admin/payouts; do
  printf "%-34s -> HTTP %s\n" "$p" "$(curl -s -o /dev/null -w '%{http_code}' "$B$p" --max-time 60)"
done

Two things worth stealing from that snippet:

  • printf with %-34s left-aligns in a 34-character column, so the output lines up into a
    readable table instead of ragged text. echo can’t do this.
  • $(...) command substitution inside the printf argument runs curl and drops its output
    straight into the string.

Watch the quoting: -w '%{http_code}' uses single quotes so the shell doesn’t try to expand
{http_code} as a variable before curl sees it.

Always run a control

When using status codes to infer something, verify the codes actually discriminate. Hit a route
you know doesn’t exist and confirm it returns something different:

curl -s -o /dev/null -w "%{http_code}\n" "$B/v1/definitely-not-a-route"   # expect 404

Without this you can’t tell “404 means not deployed” from “this server returns 404 for
everything.” A test with no control isn’t evidence. (Applied to verifying deployments in
learning/09-devops.md Part 58.)


Editing source files from a heredoc script (2026-08-21)

Most of this session’s edits were applied by piping a Python script into
python3 from the shell, rather than opening an editor:

python3 - <<'PY'
import pathlib
p = pathlib.Path("backend/src/modules/social/likes.service.ts")
s = p.read_text()
assert old in s, "pattern not found"   # fail loudly rather than silently no-op
p.write_text(s.replace(old, new, 1))
PY

Reading the pieces:

  • python3 - — the - means read the program from stdin instead of from a
    file. Same convention as cat -, tar -f -.
  • <<'PY' ... PY — a heredoc: everything up to the closing PY is fed to
    the command’s stdin. PY is just a chosen delimiter; any word works.
  • The quotes around <<'PY' are the part that matters. Quoted, the body is
    passed through literally. Unquoted (<<PY), the shell first expands $vars,
    backticks and \ escapes inside the body — which mangles code containing
    $ or \. Default to the quoted form unless you specifically want
    interpolation.

Why this over sed -i: sed works line-by-line, so multi-line replacements are
awkward, and it silently does nothing when the pattern doesn’t match. The
assert old in s above turns “my edit didn’t apply” into an immediate error
instead of a change you believe happened but didn’t.

The failure this actually caused, worth learning from. One script inserted
an import after “the last line starting with import ”:

last_import = max(i for i, l in enumerate(lines) if l.startswith("import "))

In a file ending with a multi-line import, that heuristic picked the opening
import { line and inserted the new import between the brace and its members —
a syntax error:

import {
import { resetAuthRefreshState } from "@/app/provider/api/baseQuery";
  Laptop, Music, ...
} from "lucide-react";

Line-oriented edits assume line-oriented structure. When the target is nested
syntax, anchor on something unambiguous (here, the closing } from "lucide-react";)
— and run the typechecker afterwards, which is exactly what caught it.

grep -ril — locating files by content (2026-08-21)

grep -ril "postcard" backend/src frontend --include="*.ts" --include="*.tsx"
  • -r recurse into directories
  • -i case-insensitive
  • -l print only the filenames with a match, not the matching lines —
    turns grep from “show me the matches” into “show me which files to open”
  • --include=GLOB restrict to matching filenames; repeatable, which is how both
    .ts and .tsx are covered above

Pair -l with a later grep -n on the narrowed set: find the files, then find
the lines. -n prints line numbers, and -A N / -B N print N lines after /
before each match, which is usually faster than opening the file:

grep -n "model Like" -A 20 backend/prisma/schema/social.prisma

npx tsc --noEmit — typecheck without building (2026-08-21)

npx tsc --noEmit          # uses ./tsconfig.json
npx tsc --noEmit -p backend/tsconfig.json    # -p picks a specific project

--noEmit runs the full typechecker and writes no output files — you get
the errors without a build directory. It’s the cheapest possible “did I break
anything” check and the natural thing to run after edits.

Reading its output honestly matters: this run reported errors in
app.controller.spec.ts (missing @types/jest) and reminders.service.ts
(missing csv-parse) that had nothing to do with the change in flight. Check
whether a reported file is one you actually touched before assuming you caused
it — and equally, don’t wave away errors in files you did touch. Filtering
generated noise keeps the real signal visible:

npx tsc --noEmit 2>&1 | grep -v "^\.next/" | head -30

Reading a video with ffmpeg / ffprobe (2026-08-21)

Used to diagnose a mobile bug from a screen recording that couldn’t be
reproduced locally.

# What am I dealing with? -v error suppresses the banner, leaving just the data.
ffprobe -v error \
  -show_entries format=duration,size \
  -show_entries stream=width,height,r_frame_rate,codec_name \
  -of default=noprint_wrappers=1 clip.mp4
 
# Frames at 3/sec, numbered, tiled 6x4 into contact sheets
ffmpeg -i clip.mp4 -vf "fps=3,scale=176:-1,\
drawtext=text='%{n}':x=4:y=4:fontsize=16:fontcolor=yellow:box=1:boxcolor=black,\
tile=6x4" sheet_%d.png
  • -vf is the video filter chain; commas separate stages and each feeds the
    next. Order matters — scale before tile, or you tile full-size frames.
  • fps=3 resamples to 3 frames per second of video. It isn’t playback speed;
    it’s how many frames get emitted.
  • scale=176:-1 sets width and lets -1 compute the height to preserve aspect
    ratio. -2 instead rounds to an even number, which some codecs require.
  • %{n} inside drawtext is the frame counter — a per-frame expression, not a
    shell variable, which is why it’s inside single quotes.
  • sheet_%d.png — %d is filled in by ffmpeg per output file, the same
    convention as frame_%03d.png (zero-padded to 3 digits so they sort correctly).

Tiling is the part that does the actual work: 24 frames in one image shows the
pattern across an interaction, which is what a bug usually is, rather than any
single moment.

Note -v error on both commands. ffmpeg’s default output is a wall of build
configuration; suppressing it leaves only what was asked for — worth doing
whenever the output is being read rather than watched.


Part N — git log -L: following a function through history (2026-08-22)

While diagnosing the word puzzle scoring bug, the first question was “when did
this function last change?” — not “what does it do now”.

git log --oneline -L 628,690:src/modules/games/games.service.ts

-L <start>,<end>:<file> follows a range of lines through history and shows
only the commits that touched it, each with the diff of just that range. Unlike
git log -- <file>, which drowns you in every commit that touched a 1800-line
service, this answers a question about one function.

Git tracks the range as edits above it shift it up and down, so the line numbers
you give are the ones in your current working tree.

Two variants worth knowing:

# By regex instead of line numbers — follows the function even as it moves
git log -L :calculateScore:src/modules/games/games.service.ts
 
# Suppress the diffs, just list the commits
git log --oneline -L 628,690:src/file.ts -s

The :funcname:file form is usually what you want — it finds the function by
name and doesn’t go stale when you edit the file.

Why this mattered here: it proved the scoring function hadn’t changed since
an old commit, which redirected the whole investigation away from the code that
looked guilty and toward the data. Cheap question, large saving.


Part N+1 — Heredocs, and the nested-delimiter trap that bit me writing this

The read-only DB diagnostic was written to a file, run once, and removed:

cat > prisma/_tmp-diagnose.ts <<'SCRIPT'
...typescript...
SCRIPT
npx tsx prisma/_tmp-diagnose.ts 2>&1 | tail -70
rm prisma/_tmp-diagnose.ts

<<'SCRIPT' with the delimiter quoted. Unquoted <<SCRIPT makes the shell
expand $variables and backticks inside the heredoc before writing it, which
mangles any script containing ${...} template literals. Quoting the delimiter
turns off all expansion and writes the text literally. For anything containing
code, always quote it.

It lives in prisma/, not /tmp. The script imports
../src/generated/prisma/client and needs dotenv/config to find .env — both
resolve relative to where the file sits. A script that depends on a project’s
module resolution has to run from inside that project.

The _tmp- prefix and the rm are the discipline part: a diagnostic that
outlives its diagnosis becomes a file nobody dares delete two years later.

The trap: a heredoc ends at the first line equal to its delimiter

Writing this very section failed the first time. The command was:

cat >> notes.md <<'EOF'
...prose containing an example that itself used <<'EOF' ... EOF ...
EOF

The shell doesn’t understand nesting. It scans line by line for the first line
that is exactly the delimiter, and the EOF inside my example ended the
heredoc early. Everything after it stopped being data and became commands — so
the shell cheerfully ran the npx tsx and rm lines from my own example text,
and the notes file was left truncated mid-sentence.

Three ways out, in rough order of preference:

# 1. Pick a delimiter the content cannot contain
cat >> notes.md <<'END_OF_NOTE'
... text that mentions EOF freely ...
END_OF_NOTE
 
# 2. Write the file from a language with real string literals
python3 - <<'PY'
pathlib.Path('notes.md').write_text(...)
PY
 
# 3. Indent the body and use <<- (only strips TABS, not spaces — awkward)

The general lesson: a heredoc is not a quoting construct that nests. The
moment the content is itself shell-flavoured, prefer writing the file from
Python/Node, where a string is a genuine value with an unambiguous end.

The failure mode is nastier than a syntax error, too: instead of refusing to
run, the shell silently reinterprets your data as instructions. Anything
destructive sitting in an example (rm, git reset) would have executed for
real. Check what actually ran after a heredoc misbehaves.

Piping to tail to survive a wall of output

npx tsx prisma/_tmp-diagnose.ts 2>&1 | tail -70

2>&1 redirects stderr into stdout before the pipe, so errors reach tail
too — without it a crash prints to the terminal unpiped while tail shows
nothing useful. Order matters here: the redirection has to come before the |.


Part N+2 — Reading parts of a file: sed -n as a surgical cat (2026-08-28)

cat on a 600-line service file is mostly waste. sed -n prints only what you
ask for. The -n means “don’t auto-print every line”; the p command then does
all the printing, so you get exactly the selected range.

By line number:

sed -n '235,420p' src/modules/auth/auth.service.ts   # lines 235–420
sed -n '1,140p'  src/modules/auth/auth.controller.ts # the first 140 (= head -140)
sed -n '268,$p'  DECISIONS.md                        # line 268 to end of file

By pattern range — far more useful, because you usually know the name of
the thing you want, not its line number. An address can be a /regex/, and
start,end works with regexes on either side:

# print one method, from its signature to the closing brace at its indent level
sed -n '/private async upsertGoogleUser/,/^  }/p' src/modules/auth/auth.service.ts

/^ }/ is doing real work there: anchored to a closing brace at exactly two
spaces of indentation, i.e. the end of a class method, not the end of every
nested if inside it. Pattern ranges end at the first match after the start,
so the anchor has to be specific or you get three lines instead of forty.

Several ranges in one call — separate commands with ;:

sed -n '/private sanitizeUser/,/^  }/p;/private async generateTokens/,/^  }/p' file.ts

That pulled three unrelated helper methods out of one file in a single command,
which beats three round trips through grep -n and line arithmetic.

The pairing to remember: grep -n to find, sed -n to read. grep gives
you the line number or the pattern, sed -n gives you the surrounding block.

Part N+3 — node -e to check a behaviour instead of arguing about it (2026-08-28)

Writing the mobile OAuth guide, the question came up: does JS’s URL parser
handle a custom scheme like nextvibe://auth?code=abc, or does it treat it as
opaque and lose the query string? There was a code comment in the repo asserting
one answer and a memory of the spec asserting another.

Rather than pick a side:

node -e "const u=new URL('nextvibe://auth?code=abc123'); console.log(u.host, u.searchParams.get('code'));"
# → auth abc123

node -e runs a one-liner and exits. python3 -c is the same idea; for anything
multi-line, graduate to the python3 - << 'PY' heredoc pattern from the earlier
section.

The habit is the point: a claim about runtime behaviour is cheap to test and
expensive to get wrong in documentation.
Ten seconds settled it — and it also
surfaced the real caveat worth documenting, which is that Node’s answer is not
React Native’s: RN ships a partial URL polyfill with no searchParams, so the
same line that works here returns undefined on a device. Testing the assumption
is what turned a vague worry into a specific warning worth writing down.


Part N+4 — Swapping a dependency, and the pipe that ate the exit code (2026-09-02)

Replacing expo-server-sdk with firebase-admin on the backend. Three things
worth keeping from it.

pnpm remove / pnpm add

pnpm remove expo-server-sdk        # drops it from package.json, node_modules AND the lockfile
pnpm add firebase-admin            # the reverse

remove is the one people skip — deleting the import and leaving the package
installed means the lockfile keeps pinning a dependency nothing uses, and it
still gets downloaded on every CI install.

The trap: cmd | tail throws away cmd’s exit code

This actually bit me. The install was run as:

pnpm remove expo-server-sdk && pnpm add firebase-admin 2>&1 | tail -20

pnpm add failed — npm registry timeouts — and the command still reported
exit code 0. Nothing looked wrong until grep firebase package.json came
back empty.

The reason: a pipeline’s exit status is the exit status of its last
command.
tail succeeded at tailing the error output, so the pipeline
succeeded. pnpm’s failure was invisible to anything checking $?.

Three fixes, depending on what you need:

set -o pipefail                 # pipeline fails if ANY stage fails — the usual answer
cmd | tail -20; echo "${PIPESTATUS[0]}"   # bash: exit code of the first stage
cmd | tail -20; echo "${pipestatus[1]}"   # zsh: same idea, 1-indexed array

In a script, set -euo pipefail at the top is the standard opening line and this
is exactly the bug it exists to prevent. Interactively, the lesson is simpler:
after piping a command’s output through anything, verify the effect, not the
exit code.
grep firebase package.json was the real check.

Reading the installed types instead of trusting your memory of an API

firebase-admin was at v14, newer than anything I could recall reliably. Rather
than write the send call from memory:

grep -n "sendEachForMulticast" node_modules/firebase-admin/lib/messaging/messaging.d.ts
grep -n "interface BatchResponse" -A 20 node_modules/firebase-admin/lib/messaging/messaging-api.d.ts
grep -rn "registration-token-not-registered" node_modules/firebase-admin/lib/messaging/*.js

This caught two things a from-memory version would have got wrong: the
token-based MulticastMessage is deprecated in v14 in favour of FIDs, and
the exact error-code strings (which are prefixed messaging/ only at throw time
— visible in error.js, not in the constant list).

node_modules is primary source. It’s the exact version you’re compiling
against, which is more than the library’s own docs site can say — those describe
whatever version is current. .d.ts files for the API surface, the .js for
the constants and behaviour the types don’t capture.

pnpm approve-builds

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: @firebase/util, protobufjs

Not an error. pnpm refuses to run packages’ postinstall scripts by default —
arbitrary code execution on install is a real supply-chain vector. pnpm approve-builds lets you allow specific ones. Only needed if a package genuinely
requires its postinstall (native compilation, downloading a binary); these two
don’t for the messaging path, so it was left alone.


Part N+5 — Inspecting config without printing secrets (2026-09-02)

Question: are the FIREBASE_* values in .env real yet, or still the
placeholders from .env.example? The lazy answer is cat .env, which dumps a
private key into the terminal (and into scrollback, and into any transcript).
Better to ask a narrower question:

val=$(grep -E "^FIREBASE_PROJECT_ID=" .env | cut -d= -f2- | tr -d '"')
 
if [ -z "$val" ]; then echo "EMPTY"
elif echo "$val" | grep -qi "your-\|xxx"; then echo "still a placeholder"
else echo "set (${#val} chars)"; fi

Three things worth keeping:

  • cut -d= -f2- — split on =, take field 2 to the end. The - is the
    point: -f2 alone would truncate at the first = inside the value, which
    base64 and PEM data are full of.
  • ${#var} — the length of a variable. Reports “is it plausibly a real
    key” without revealing the key. Same family as ${var:-default} and
    ${var#prefix}.
  • grep -q — quiet: no output, just an exit status for the if. The right
    tool whenever you’re testing rather than displaying.

The habit: when you only need a yes/no about a secret, compute the yes/no.
Printing the value to read it yourself puts it somewhere you didn’t intend.

command -v over which

command -v firebase >/dev/null && firebase --version || echo "not installed"

command -v is a shell builtin and POSIX; which is an external binary that
isn’t guaranteed present and whose exit status is inconsistent across systems.
command -v is the portable check for “is this on PATH”. Redirect to
/dev/null when you want only the exit status.

Part N+6 — Auditing a whole class of files instead of eyeballing them (2026-09-09)

Three agent skills silently failed to load with “Invalid YAML frontmatter”.
Eleven SKILL.md files existed. The tempting move is to open the one named in
the error and stare at it — which finds nothing, because the offending
character looks completely ordinary.

The better move is to stop reading and make the parser answer:

cd ~/.agents/skills && python3 - << 'PY'
import re, os, yaml
for d in sorted(os.listdir('.')):
    f = os.path.join(d, 'SKILL.md')
    if not os.path.exists(f): continue
    raw = open(f, 'rb').read()
    s   = raw.decode('utf-8-sig')
    m   = re.match(r'---\n(.*?)\n---\n', s, re.S)
    if not m:
        print(f, 'NO FRONTMATTER'); continue
    try:
        y = yaml.safe_load(m.group(1))
        print(f"{d:32s} OK   keys={list(y.keys())}")
    except Exception as e:
        print(f"{d:32s} FAIL {str(e).splitlines()[0]}")
PY

This is the heredoc pattern from Part 8, pointed at a different job: not editing files, but interrogating them. Worth separating in your head — the same tool does bulk diagnosis, and diagnosis across a set is where it earns the most.

What makes the output useful rather than a wall of text:

  • Every file reports, not just the failures. Eight OK lines are what tell you the three failures share something the others don’t — the diagnosis came from the contrast, not from the error.
  • f"{d:32s}" — pad to a fixed width so the statuses line up in a column. Scannable output is a real feature when you’re comparing rows.
  • str(e).splitlines()[0] — YAML errors are multi-line with a caret diagram. The first line is the classification; the detail only matters once you know which files to look at.

open(f, 'rb') — check the bytes before blaming the content

Note the file is read as bytes first, then decoded. That is deliberate: a
whole class of “but it looks fine!” bugs lives in bytes you can’t see.

raw.startswith(b'\xef\xbb\xbf')   # UTF-8 BOM — invisible, breaks strict parsers
b'\r\n' in raw                     # CRLF line endings from a Windows editor

open(f, encoding='utf-8-sig') decodes and strips a BOM if present — the
-sig suffix is the one to remember. From the shell, file <path> reports the
same things (“with BOM”, “with CRLF line terminators”) without any Python.

Here both were clean, which is itself progress: it ruled out the invisible
causes and left only the visible one.

The actual bug — and it’s a YAML rule worth internalising

description: ... not a one-time lookup. Triggers: starting a new project, ...
#                                       ^^^^^^^^^

A colon followed by a space inside an unquoted YAML scalar starts a nested
mapping.
The parser reads Triggers: as a key, finds it where a key cannot
go, and reports “mapping values are not allowed here” — an error message that
points at YAML’s grammar rather than at “your sentence contains a colon”.

Every vendor-written skill in the same directory already quoted its
description. That’s the tell: the ones written by hand broke, the ones written
by people who’d hit this before did not.

Characters that force quoting in YAML: : anywhere, a trailing :, and a
leading #, &, *, !, |, >, %, @, `, {, [. The
cheapest habit is to quote every prose value and stop thinking about it.

Let the library do the quoting

Fixing it by hand means deciding between ' and " and escaping whatever the
text already contains — one description held apostrophes, another held double
quotes. Don’t:

quoted = yaml.dump(val, default_style="'", width=10**9,
                   allow_unicode=True).rstrip('\n').rstrip('...').strip()
  • default_style="'" — force single-quoted style; internal ' becomes ''
    automatically.
  • width=10**9 — PyYAML line-wraps at 80 columns by default, which would
    split a 700-character description across lines. An absurd width disables it.
  • allow_unicode=True — keep — as — rather than escaping it to —.

The general principle: when a format has an escaping rule, use its own
serialiser rather than reimplementing the rule.
The same reasoning as
json.dumps over string concatenation, or parameterised SQL over quoting user
input yourself.

Verify in the same script that fixed it

The fix script re-ran yaml.safe_load over every file it touched and printed
the parsed keys. A rewrite that reports “wrote 3 files” tells you nothing about
whether they’re correct now — reparsing does. Cheap, and it turns a hopeful
edit into a checked one.

The skills live in ~/.agents/skills/ and are surfaced through symlinks in
~/.claude/skills/. Adding one:

ln -sfn ../../.agents/skills/mentor-mode ~/.claude/skills/mentor-mode

Plain ln -s fails outright if the link name already exists, so the flags are
what make this idempotent — safe to re-run:

  • -f (force) — remove an existing destination first, so the command
    updates a link instead of erroring.
  • -n (no-dereference) — the one that matters, and the classic footgun.
    If the destination is already a symlink to a directory, ln -sf follows it
    and creates the new link inside the target directory. You wanted to
    re-point skills/mentor-mode; you got
    skills/mentor-mode/mentor-mode and the original untouched. -n treats the
    existing symlink as a plain file to be replaced.

Remember them together as -sfn: symbolic, force, no-dereference.

Two checks worth knowing:

ls -l ~/.claude/skills/          # arrows show every link's target
readlink -f ~/.claude/skills/mentor-mode   # resolve fully; empty = broken link

A relative target (../../.agents/...) rather than an absolute one keeps
the link valid if the home directory is ever moved or the tree is copied
elsewhere — the same reasoning as relative imports inside a project.

→ general: symbolic links

Part N+8 — When the editor and the compiler disagree, the compiler wins (2026-09-21)

Zed reported Cannot find module '@/components/ui/skeleton'. The file existed.
Every other @/… import in the same file was flagged too — but lucide-react
resolved fine.

That asymmetry is the whole diagnosis. lucide-react resolves through
node_modules, which needs no config. @/* resolves through the paths block
in tsconfig.json. So: node_modules resolution working while aliases fail
means the language server never loaded the tsconfig.

The arbiter is the compiler, not the editor (see npx tsc --noEmit above):

cd frontend && npx tsc --noEmit 2>&1 | grep 'components/ui'   # → nothing

Zero alias errors from tsc, many from the editor → the code is fine and the
LSP is wrong. Never start “fixing” imports on the editor’s word alone.

The actual cause: one syntax error poisons the whole project

tsc reported exactly one error, in a different file:

attendee-postcard-creator.tsx(32,10): error TS1005: ',' expected.

A find-and-replace had dropped a string literal into the middle of an
identifier — Attend"pre-event"eePostcardLeaderboardProps.

When the TS server can’t parse a file in the program, vtsls can fall back to
an inferred project for open files, and inferred projects don’t apply
tsconfig.json — so paths stops working everywhere, not just in the broken
file. The phantom import errors were a symptom two files away from the cause.

Debugging order that follows from this:

  1. Run tsc --noEmit. It sees the real program, the editor sees a cache.
  2. Fix syntax errors first — they cascade into fake semantic errors.
  3. Only then restart the language server
    (Zed: editor: restart language server).
  4. Still broken? Check the project root. vtsls looks for a tsconfig near
    the worktree root; open frontend/ and backend/ as their own worktrees
    rather than the parent folder that contains neither tsconfig.

Counting errors before reading them

npx tsc --noEmit 2>&1 | grep -c 'error TS'

grep -c prints a count instead of the lines. One number tells you whether
you’re looking at a clean tree, a handful of real errors, or a cascade — worth
knowing before you scroll.

find to test a relative import by hand

A failing relative import is worth resolving manually rather than trusting the
path as written:

find frontend/src -name 'postcard-grid*'

It turned up the file in a different route group than the import assumed —
which is why the import could never have worked.

→ general: grep and friends


Part N+9 — Finding every env var the app reads (2026-09-25)

Goal: a complete list of env var names the backend reads, to build startup validation and
to compare against production.

My first attempt

grep -rni "process.env" src/
grep -rni "configService.get" src/

Good: caught both access patterns (process.env.X in src/config/*.ts, and
configService.get('X') in services). Problems:

  • -i (ignore case) isn’t needed — process.env is always lowercase. Don’t add flags “just
    in case”; each one should have a reason.
  • In grep patterns . means any character, so process.env also matches processXenv.
    -F = treat the pattern as a fixed string (plain text, no regex).
  • The real gap: it assumes every service names its variable configService.

Checking the assumption

My command:

grep -rnF ": ConfigService" backend/src/

-F applied, and ": ConfigService" (colon + space) targets type annotations — the
constructor parameters — rather than every mention of the word (imports etc.). The output
showed two names in use: configService (most files) and config (games.service.ts,
push.service.ts, payouts.service.ts, the reminders and birthday-campaign files, and
the useFactory in auth.module.ts). My first grep would have silently missed every env
var those files read.

Lesson: when a search depends on a naming convention, verify the convention before
trusting the search. A search that returns results looks complete — that’s what makes a
partial one dangerous.


Part N+10 — Two techniques from the Stripe handoff (2026-09-25)

Used while wiring Stripe in “take control” mode — worth knowing even though you didn’t type them.

Generating a migration without touching a database

mkdir -p /tmp/old-schema
for f in $(git ls-files prisma/schema); do git show HEAD:$f > /tmp/old-schema/$(basename $f); done
npx prisma migrate diff --from-schema /tmp/old-schema --to-schema prisma/schema --script
  • git show HEAD:<path> prints a file as it was in the last commit, without checking
    anything out. Looping over git ls-files rebuilds the whole old schema folder.
  • prisma migrate diff --from-schema A --to-schema B --script prints the SQL to turn A into
    B. Comparing two schema files needs no database at all (unlike migrate dev).
  • Bonus check: if the output contains only your change, the schema was otherwise in sync
    with the last commit.

”Did I make lint worse?” — compare against a baseline

A file with 115 pre-existing lint errors hides whether you added any. Lint the committed
version too, and diff the counts:

git show HEAD:src/x.ts | npx eslint --stdin --stdin-filename src/x.ts -f json > old.json
npx eslint src/x.ts -f json > new.json

--stdin-filename makes ESLint apply the same config as if the text were that file. Then
compare (rule, message) counts between the two JSON files. It’s the same idea as the
grep | grep -v completeness check: measure the difference, don’t eyeball the total.

↑ Back to nextvibe — Learning Notes