Tinker Quest

Tracks

1. 01🔨The Hands

   0/4 lessons

   What Tinker is, which jobs it refuses, and why hiding apps came first

   Before any code: what kind of thing Tinker is. The family already had eyes (Watchfire), a house (Haven) and a brain (Pippa); what it lacked was a pair of hands that could change something on a Mac and then take it back. This track places Tinker among its siblings, walks the editing session that gave it its first job, explains why that job — hiding apps — is the first child of a broader idea rather than the idea itself, and shows why every Mac that takes Tinker runs its own copy with its own state.

   Lesson list (4)

   • 01
     What Tinker Is — and What It Refuses to Be~11 min · tinker, boundaries, actuator, siblings
   • 02
     The Editing Preset — Where the First Job Came From~12 min · presets, origin, final-cut, hide-not-quit, watchfire
   • 03
     Hide Is a Child, Not the Root~12 min · oop, inheritance, capability-root, abstraction
   • 04
     One Tinker per Mac — Hands Don't Reach Across the Room~12 min · per-mac, registry, enrollment, state, accessibility

   ✓Quiz · 4 questions→

2. 02🌳The Root Class

   0/5 lessons

   An open Capability with three verbs, and the first child that fills it in

   Tinker's engine depends on exactly one abstraction: an open Capability class whose children validate their own input, prepare a list of planned changes, apply each one, and undo each one. This track reads that root line by line, walks HideApplications as the worked example, and spends a whole lesson on the most subtle idea in the design — the difference between a change that failed and a change that provably never happened.

   Lesson list (5)

   • 01
     Reading the Open Capability Class~13 min · swift, open-class, main-actor, jsonvalue, capability
   • 02
     Prepare, Apply, Undo — the Lifecycle of One Change~14 min · lifecycle, changeplan, engine, undo
   • 03
     HideApplications — the First Child, Line by Line~15 min · hideapplications, subclass, protocol-seam, testing
   • 04
     Proving a Non-Attempt — Failed Versus Never Happened~14 min · change-not-attempted, uncertainty, error-types, review-pass
   • 05
     What a New Child Pays — and What It Gets for Free~13 min · obligations, complete-bindings, protection-policy, extensibility

   ✓Quiz · 4 questions→

3. 03🪪Owning a Change

   0/5 lessons

   Three facts make an owner — and a change someone else made is never yours

   'Undo only what you can prove you did' needs a precise idea of 'what you did'. This track builds it: an app is identified by bundle ID, process ID and launch time together; an app that was already hidden is never acquired; a hide is confirmed by watching the process's own state rather than trusting a return value; two presets that hide the same app share it; and when Dad shows an app by hand, his choice beats Tinker's receipt.

   Lesson list (5)

   • 01
     Identity Is Three Facts, Not One Number~13 min · process-identity, pid, launch-date, bundle-id
   • 02
     Never Acquire What Was Already Hidden~12 min · pre-hidden, needs-apply, restore, user-intent
   • 03
     Trust the State, Not the Return Value~14 min · confirmation, isHidden, run-loop, appkit, lab-finding
   • 04
     Shared Ownership — Two Presets, One Hidden App~13 min · shared-ownership, owners, reference-counting, overlap
   • 05
     A Manual Show Wins — Actions, Not Enforcement~12 min · user-intent, no-enforcement, manual-show, noLongerApplicable

   ✓Quiz · 4 questions→

4. 04📒The Journal

   0/5 lessons

   Receipt first, effect second — and what to do when you cannot tell which happened

   Everything Tinker promises after a crash, a forced quit or a bad file rests on one document: the change journal. This track follows a receipt from prepared to applied, shows how a failure part-way through a preset rolls back only what was confirmed, explains why an uncertain or unreadable journal holds the engine instead of letting it guess, and separates the three files Tinker keeps — settings, journal, activity — by what losing each one would cost.

   Lesson list (5)

   • 01
     Receipt Before Effect~13 min · write-ahead, journal, atomic-write, durability
   • 02
     Prepared and Applied — Two Phases, Two Meanings~12 min · phases, uncertain, recovery, resume
   • 03
     A Failure Restores What Was Confirmed~13 min · rollback, atomicity, emergency-release, partial-failure
   • 04
     Held, Not Guessed — Corrupt Files and the Forget Button~13 min · corruption, held-state, forget, two-click, consistency
   • 05
     Three Files, Three Fates~13 min · settings, journal, activity, independent-loads, health

   ✓Quiz · 4 questions→

5. 05🚪One Engine, Many Doors

   0/5 lessons

   Menu, shortcut, link, Stream Deck, Settings — every trigger is a saved command

   Tinker can be asked to act in six ways: from its menu, with a global shortcut, through a tinker:// link (which is how a Stream Deck key reaches it), from the Settings window, from Pippa's app door, and by Tinker itself when it quits. None of them owns its own path to the engine. This track shows how commands and presets are plain data, how every preset and capability gets its commands automatically, how a global chord is registered and how its collisions are reported, why a link may name only a saved command, and how the Activity history records who asked.

   Lesson list (5)

   • 01
     Commands Are Data~13 min · command-binding, presets, configuration, validation
   • 02
     Bindings Complete Themselves — and Respect the Names People Write~12 min · complete-bindings, rename, delete, generated-names
   • 03
     The Chord — Shared Hotkeys, Visible Collisions~14 min · global-hotkeys, carbon, cwkkitmac, collisions, observation
   • 04
     Links and the Stream Deck — a URL That Can Only Name~12 min · url-scheme, stream-deck, input-validation, info-plist
   • 05
     Who Asked — Triggers, Activity and the Dropped Second Press~12 min · trigger, activity, busy, status-line

   ✓Quiz · 4 questions→

6. 06🔌The App Door

   0/5 lessons

   How Pippa asks — a worker that never touches the Mac, and a request that runs once

   Pippa reaches Tinker through the family's app-action contract: a loopback HTTP door that lists what an app lets her do and runs one action per request. This track opens that door. A short-lived Python worker speaks the shared contract while the resident Swift agent does every native effect; a request ID makes a retried toggle impossible even if the worker dies at the worst moment; requests take turns instead of failing; only a local, non-browser, unproxied caller is admitted; and Pippa must always say which Mac she means.

   Lesson list (5)

   • 01
     A Worker That Never Touches the Mac~15 min · python-worker, pipes, json-lines, code-signing, watchdog
   • 02
     A Request Runs Once — Even When the Worker Dies~15 min · idempotency, request-id, fsync, execute-once, retries
   • 03
     Taking Turns Instead of Saying Busy~13 min · swift-actor, continuations, queueing, flock, backpressure
   • 04
     Loopback Only — Who May Knock~14 min · loopback, host-header, origin, x-forwarded-for, defense-in-depth
   • 05
     Pippa Names the Mac — and Has No Resume Button~13 min · per-mac, forwarding, manifest, paged-reads, no-resume

   ✓Quiz · 4 questions→

7. 07🛑Stopping and Leaving

   0/4 lessons

   Emergency release, secure input, Quit and logout — every exit restores first

   An actuator is judged by how it stops. This track covers the four ways Tinker's work ends abnormally or on purpose: the emergency command that stops everything and restores what it owns; the standing refusal while secure keyboard entry is active; a Quit that restores first and explains itself when it cannot; and the logout, restart or shutdown that Tinker must never block, answered with a deferred reply and an eight-second deadline.

   Lesson list (4)

   • 01
     Stop and Restore Everything~12 min · emergency-release, resume, stopped-state, safety
   • 02
     Secure Input Refuses the Whole Command~12 min · secure-event-input, standing-refusal, passwords, prepare
   • 03
     Quit Restores First — and Explains When It Can't~14 min · quit, applicationShouldTerminate, two-step, main-actor, updates
   • 04
     Never Cancel a Logout~14 min · apple-events, logout, terminateLater, deadline, run-loop-timer

   ✓Quiz · 4 questions→

8. 08🧪Proof and Delivery

   0/6 lessons

   Measure without waiting, test on disposable apps, sign once, and let Dad make the first live hide

   The last track is about evidence. How Tinker reports whether a preset helped without making a key press wait for the measurement, and why a missing reading is never shown as zero. How a lab of disposable fixture apps on Pippa's home Mac proves hide, restore, refusals and the quit path — and why the Accessibility grant there follows the code hash. How the signed app reaches each enrolled Mac without anyone signalling a running copy. And, as a capstone, how you would design Tinker's second capability.

   Lesson list (6)

   • 01
     Changes Never Wait for the Eyes~14 min · latency, watchfire, before-after, shared-requests
   • 02
     Unknown Is Not Zero~12 min · optionals, staleness, observation, honest-ui
   • 03
     The Lab and Its Fixtures~15 min · lab, fixtures, integration-tests, gui-testing, fail-closed
   • 04
     The Grant Follows the Hash~14 min · tcc, accessibility, code-signing, designated-requirement, war-story
   • 05
     Signed Once, Delivered Everywhere — Without a Single Signal~15 min · code-signing, deployment, launchd, rollback, stable-identity
   • 06
     Capstone — Designing the Second Child~18 min · capstone, capability-design, key-design, shared-ownership, testing

   ✓Quiz · 4 questions→