Verify Changes

Verify Changes Skill

Purpose

After modifying quartz-syncer source code, build the plugin, reload it in a running Obsidian instance, and verify it works correctly using the operability facade (window.__QS__). This replaces manual "open Obsidian and click around" verification.

When to Activate

Activate after any code change that affects runtime behavior — source files in src/, settings, CLI handlers, views, services. NOT needed for test-only changes or documentation.

Prerequisites

• Obsidian must be running with the test vault open.
• Plugin must be built with npm run build:dev (copies to test vault, enables facade via __DEV__ flag).
• The Obsidian CLI must be registered and working (obsidian eval code="1+1" 2>/dev/null should return => 2).
• Console capture requires the debugger: run obsidian dev:debug on 2>/dev/null once per Obsidian session before using dev:console.

Important: CLI Patterns

Suppress GTK warnings. Always append 2>/dev/null to every obsidian CLI command. Linux produces GTK/Electron warnings that clutter output.

Async eval needs the IIFE + console.log pattern. Top-level await produces no output:

# WRONG — returns nothing:
obsidian eval code="await window.__QS__.act({name:'pub.open'})" 2>/dev/null

# CORRECT — prints the result:
obsidian eval code="(async()=>{const r=await window.__QS__.act({name:'pub.open'});console.log(JSON.stringify(r))})()" 2>/dev/null

Synchronous calls return values directly:

obsidian eval code="typeof window.__QS__" 2>/dev/null
# => object

obsidian eval only captures output emitted within ~5–15 ms. The limit is duration, not asynchrony: microtasks and sub-frame timers resolve in time, real waits do not. Output logged after eval returns is silently lost — an empty result, not an error.

Actions that do real work may or may not print depending on cache warmth, so never read missing output as failure. Confirm with a follow-up synchronous query instead:

obsidian eval code="(async()=>{const r=await window.__QS__.act({name:'pub.open'});console.log(JSON.stringify(r))})()" 2>/dev/null
sleep 2
obsidian dev:dom selector='[data-qs="pub-center"]' total 2>/dev/null   # this is the real check

For anything that deliberately waits, stash the result and read it back synchronously:

obsidian eval code="window.__probe='pending';(async()=>{/* ...slow work... */ window.__probe=JSON.stringify(result)})()" 2>/dev/null
sleep 5
obsidian eval code="window.__probe" 2>/dev/null

JSON.stringify throws on status.refresh. Its data is a live PublishStatus holding PublishFile objects with circular references. Log a projection, not the whole result. snapshot() is always safe to stringify.

Workflow

Step 1: Build and deploy to test vault

npm run build:dev

This builds with __DEV__=true (facade mounts automatically), includes sourcemaps, and copies main.js to test-vault/.obsidian/plugins/quartz-syncer/. If the build fails, fix the build error first.

Do NOT use npm run build (production) for verification — it does not copy to the test vault and strips the __DEV__ flag.

Step 2: Reload plugin

Build alone does NOT update the running instance. You must reload:

obsidian eval code="(async()=>{await app.plugins.disablePlugin('quartz-syncer');await new Promise(r=>setTimeout(r,1000));await app.plugins.enablePlugin('quartz-syncer')})()" 2>/dev/null

Wait 3 seconds after this command, then verify the plugin loaded:

sleep 3 && obsidian eval code="typeof window.__QS__" 2>/dev/null

Expected: => object. If => undefined, the facade didn't mount — check that the dev build was used.

Step 3: Health check

obsidian eval code="JSON.stringify(window.__QS__.assert('health.core'))" 2>/dev/null

Expected: {"pass":true,"details":{...}}. If pass is false, the plugin failed to initialize — check details for the reason.

Step 4: Snapshot

obsidian eval code="JSON.stringify(window.__QS__.snapshot())" 2>/dev/null

Inspect the snapshot for anomalies:

• plugin.loaded should be true
• engine.running should be true
• statusBar.state should be "ready" or "compiling" (not "error")
• errors.count should be 0