Pairs with: course preamble (no lecture). Time: ~30 min. Difficulty: Basic. Prerequisites: none.

Module 00. Onboarding

Why this module

Before you can build a harness, you need a working CLI to wrap. This module gets your Node.js + TypeScript toolchain installed, scaffolds an empty noted-cli/ repository, and confirms your terminal can produce a deterministic exit code from your code. Every later module assumes the checkpoint at the end of this one.

We also use this module to make a point: the empty scaffold you finish with here is exactly the kind of repository where agent failures begin. There is no AGENTS.md, no feature_list.json, no verification script — only code. Module 01 will exploit that.

Concepts

A coding agent's reliability hinges on five things outside the model: clear instructions, the right tools, a sane execution environment, durable state, and verification feedback. Lecture 02 calls these the five subsystems. In this module we set up exactly one of them — the execution environment — and intentionally leave the other four absent. That gap is the failure surface that the rest of the course closes.

→ Skim Lecture 02 — What a Harness Actually Is for the long-form treatment.

Lab

Step 1 — Install Node 20 and pnpm

Check what you already have:

node --version
pnpm --version

You need Node v20.x or newer and any recent pnpm. If either is missing, install via nvm and npm install -g pnpm. (If you prefer npm, the AUTHORING.md notes the one-line substitution.)

Expected:

v20.11.1
9.7.0

Step 2 — Scaffold the repo

Pick a working directory anywhere outside this course tree:

mkdir -p ~/code/noted-cli && cd ~/code/noted-cli
git init -q
echo "node_modules/\n.noted/\nlogs/" > .gitignore
pnpm init

pnpm init creates a default package.json. Replace its contents with this minimal version (overwrite the file completely):

{
  "name": "noted-cli",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "bin": { "noted": "./bin/noted" },
  "scripts": {
    "dev": "tsx src/cli.ts",
    "test": "tsx --test src/**/*.test.ts"
  },
  "devDependencies": {
    "tsx": "^4.7.0",
    "typescript": "^5.4.0"
  }
}

Install:

pnpm install

Step 3 — Add a TypeScript config

cat > tsconfig.json <<'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src/**/*", "bin/**/*"]
}
EOF

Step 4 — Write the first version of the CLI

mkdir -p src bin

Create src/cli.ts:

const args = process.argv.slice(2);

if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
  console.log("noted - a tiny notes CLI");
  console.log("");
  console.log("Usage:");
  console.log("  noted --help        Print this help.");
  process.exit(0);
}

console.error(`unknown command: ${args.join(" ")}`);
process.exit(2);

Create bin/noted (no .ts extension — this is the executable shim):

#!/usr/bin/env -S npx tsx
import("../src/cli.ts");

Make it executable:

chmod +x bin/noted

Step 5 — Confirm the CLI runs

./bin/noted --help
echo "exit: $?"

Expected:

noted - a tiny notes CLI

Usage:
  noted --help        Print this help.
exit: 0

And the unknown-command path:

./bin/noted whatever
echo "exit: $?"

Expected:

unknown command: whatever
exit: 2

Step 6 — Commit the checkpoint

git add .
git commit -q -m "module-00: scaffold noted-cli"

Verification

Run this single line. It must exit 0 and print exactly the marker shown.

./bin/noted --help | grep -q "^noted - a tiny notes CLI$" && echo "M00 OK"

Expected:

M00 OK

If you do not see M00 OK, do not move on. Either the help text is wrong, the shebang is not finding tsx, or the binary is not executable.

Common pitfalls

• ./bin/noted: Permission denied — you forgot chmod +x bin/noted.
• Cannot use import statement outside a module — your package.json is missing "type": "module". Step 2's snippet has it; double-check yours.
• tsx: command not found — pnpm install did not run, or you are running bin/noted from outside the project root. The shebang uses npx tsx which resolves from the local node_modules.
• Mac Gatekeeper warning on the binary — fine, you wrote it; one-time xattr -d com.apple.quarantine bin/noted clears it.
• Skipped git init — Module 06 onward expects a working git repo.

Next

Module 01 — Why Models Need Harnesses. You will keep this exact repo and intentionally try to extend it without a harness, then with one.