Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 27 additions & 12 deletions .agents/run-e2e
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
#!/usr/bin/env bash
# Builds main.js and runs the native E2E suite in this worktree's isolated
# Obsidian instance. Arguments go to Vitest (a spec path, `-t <name>`).
# Builds main.js and runs the native E2E suite in a fresh isolated Obsidian
# instance and vault for this worktree. Arguments go to Vitest (spec paths,
# `-t <name>`).
#
# OBSIDIAN_E2E_TEMPLATER=1 also runs the Templater-only specs, against the
# Templater release pinned below. Run it that way for any change that touches
Expand All @@ -21,6 +22,13 @@ export COREPACK_HOME="${COREPACK_HOME:-$ORIGINAL_HOME/.cache/quickadd-corepack}"

cd "$REPO_ROOT"

# Vitest ignores everything after a `--`, so `run-e2e -- <spec>` (or
# `pnpm run test:e2e:orb -- <spec>`) would run the whole suite. Drop them.
for arg; do
shift
[[ "$arg" == "--" ]] || set -- "$@" "$arg"
done

# The runner loads whatever main.js is on disk. Build it from the checked-out
# source so a stale bundle can't pass or fail a run for code it doesn't hold.
pnpm run --silent build >/dev/null
Expand All @@ -41,6 +49,22 @@ trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM

# The physical path of an existing directory, or nothing (`realpath -e` is
# GNU-only). The printed paths must already be physical, so a `..` or a link
# can't point the run elsewhere. Only the profile root is resolved first: on
# macOS /tmp is a link to /private/tmp, and the runner prints the /tmp form.
physical_dir() { (cd -P -- "$1" 2>/dev/null && pwd -P) || true; }

# A running instance keeps its window size, modals and keymap scopes, and the
# vault keeps data.json and files from manual testing. Start from fresh ones.
pnpm run --silent stop:e2e-obsidian >/dev/null
stale_vault="$(pnpm run --silent provision:e2e-vault -- --print-env |
sed -n "s/^export OBSIDIAN_E2E_VAULT_PATH='\(.*\)'$/\1/p")"
if [[ "$(dirname -- "$stale_vault")" == "$REPO_ROOT/.obsidian-e2e-vaults" && \
"$(physical_dir "$stale_vault")" == "$stale_vault" ]]; then
rm -rf -- "$stale_vault"
fi

# Keep assignment and status checking separate from parsing. Command
# substitution inside `eval` would otherwise let eval's success mask a runner
# that printed plausible exports and then exited nonzero.
Expand Down Expand Up @@ -90,11 +114,6 @@ done
}
vault_path="${start_env[OBSIDIAN_E2E_VAULT_PATH]}"
obsidian_home="${start_env[OBSIDIAN_E2E_OBSIDIAN_HOME]}"
# The physical path of an existing directory, or nothing (`realpath -e` is
# GNU-only). The printed paths must already be physical, so a `..` or a link
# can't point the run elsewhere. Only the profile root is resolved first: on
# macOS /tmp is a link to /private/tmp, and the runner prints the /tmp form.
physical_dir() { (cd -P -- "$1" 2>/dev/null && pwd -P) || true; }
readonly PROFILE_ROOT=/tmp/quickadd-obsidian-e2e
expected_vault_root="$(physical_dir "$REPO_ROOT/.obsidian-e2e-vaults")"
profile_root="$(physical_dir "$PROFILE_ROOT")"
Expand Down Expand Up @@ -140,11 +159,8 @@ if [[ "${OBSIDIAN_E2E_TEMPLATER:-}" == "1" ]]; then
echo "${templater_sha256[$file]} $templater_cache/$file" | sha256sum --check --quiet -
cp "$templater_cache/$file" "$templater_dir/$file"
done
# A reused instance may already run a Templater, and enabling a loaded
# plugin keeps its code, so unload it first.
enabled="$(pnpm run --silent obsidian:e2e -- eval code='(async () => {
await app.plugins.loadManifests();
await app.plugins.disablePlugin("templater-obsidian");
await app.plugins.enablePlugin("templater-obsidian");
return app.plugins.plugins["templater-obsidian"]?.manifest.version ?? "missing";
})()')"
Expand All @@ -154,8 +170,7 @@ if [[ "${OBSIDIAN_E2E_TEMPLATER:-}" == "1" ]]; then
fi
fi

# No `--`: pnpm passes it through, and Vitest ignores everything after it, so
# file and `-t` filters would silently run the whole suite.
# No `--` before the arguments either: pnpm passes it through to Vitest.
# Vitest also exits 0 when a `-t` filter matches no test, so count what ran.
results="$(mktemp)"
pnpm run test:e2e "$@" --reporter=default --reporter=json --outputFile.json="$results"
Expand Down
40 changes: 26 additions & 14 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ QuickAdd is an Obsidian community plugin that provides four choice types:
templates, captures, macros, and multis.

## Project Structure & Module Organization
QuickAdd is an Obsidian community plugin. Source code lives in `src/`: core logic under `engine/`, `services/`, and `utils/`; Svelte UI in `src/gui`; shared types in `src/types`; settings entry in `src/quickAddSettingsTab.ts`. Bundled artifacts `main.js` and `styles.css` stay at the repo root and should be generated, not hand-edited. Place tests and stubs in `tests/`, and keep user-facing docs in `docs/`.
QuickAdd is an Obsidian community plugin. Source code lives in `src/`: core logic under `engine/`, `services/`, and `utils/`; Svelte UI in `src/gui`; shared types in `src/types`; settings entry in `src/quickAddSettingsTab.ts`. The build writes `main.js` and `styles.css` (from `src/styles.css`) to the repo root; both are gitignored, so edit the sources. Place tests and stubs in `tests/`, and keep user-facing docs in `docs/`.

## Tooling & GitHub
- Use `pnpm` for package management and scripts. Avoid npm/yarn/bun.
Expand All @@ -14,9 +14,11 @@ QuickAdd is an Obsidian community plugin. Source code lives in `src/`: core logi
create/link the working branch before implementation.
- GitHub does not allow approving your own PR from the same account; do not
block merge waiting for self-approval.
- Never merge a `release/*` PR from `quickadd-release-bot`; chhoumann
squash-merges those himself. After any other merge, the release workflow
refuses to publish, so `master` advertises a version with no GitHub release.
- Merge a `release/*` PR from `quickadd-release-bot` only when chhoumann
explicitly allows it. The bot opens it as a draft: `gh pr ready`, check that
the `base=` marker in its body is current `master`, then
`gh pr merge --squash`. Merging a stale release PR makes the release workflow
refuse to publish, so `master` advertises a version with no GitHub release.
Obsidian then fails to install QuickAdd and drops it from Community plugins
(#1763).

Expand All @@ -32,16 +34,16 @@ QuickAdd is an Obsidian community plugin. Source code lives in `src/`: core logi
The project uses tab indentation and LF endings (see `.editorconfig`); align editor settings. Use camelCase for variables and functions, PascalCase for classes and Svelte components, and kebab-case for directories and utilities. Preserve the hand-ordered imports in `src/main.ts`; disable auto-sorting there. Prefer type-only imports and route logging through the `logger` utilities for consistent output.

## Testing Guidelines
Vitest (configured in `vitest.config.mts`) runs in Node and cannot load real Obsidian modules. A test file that needs a DOM or loads Svelte code starts with `// @vitest-environment jsdom`; leave it off otherwise, because jsdom setup is the suite's largest cost. A Node test that loads Svelte code or reads `document` fails with that hint. Structure production code so Obsidian dependencies are injected behind interfaces; unit tests target pure logic and swap in adapters or `tests/obsidian-stub.ts`. Co-locate specs with their source or group them under `tests/feature-name`. Add regression coverage for bug fixes, and ensure `pnpm run test` passes before pushing.
Vitest (configured in `vitest.config.mts`) runs in Node and cannot load real Obsidian modules. A test file that needs a DOM or loads Svelte code starts with `// @vitest-environment jsdom`; leave it off otherwise, because jsdom setup is the suite's largest cost. A Node test that loads Svelte code or reads `document` fails with that hint. Structure production code so Obsidian dependencies are injected behind interfaces; unit tests target pure logic and swap in adapters or `tests/obsidian-stub.ts`. Co-locate specs with their source or group them under `tests/feature-name`. Add regression coverage for bug fixes and confirm the new test fails with the fix reverted, and ensure `pnpm run test` passes before pushing.

## Commit & Pull Request Guidelines
Follow Conventional Commits (`feat:`, `fix:`, `test:`, ...) so the shared release pipeline can determine versions from history. Keep generated files in the same commit as the changes that produced them. Pull requests must include a concise summary, reproduction steps or screenshots for UI changes, linked issues when relevant, and explicit notes on release or migration impact. Request review from maintainers closest to the touched area.
Follow Conventional Commits (`feat:`, `fix:`, `test:`, ...) so the shared release pipeline can determine versions from history. Pull requests must include a concise summary, reproduction steps or screenshots for UI changes, linked issues when relevant, and explicit notes on release or migration impact. Request review from maintainers closest to the touched area.

## Documentation
Docs live in `docs/` (Astro Starlight) and are single-version: pages in `docs/src/content/docs/docs/` serve at `/docs/` on quickadd.obsidian.guide, and edits go live when they land on `master` (deployed by Cloudflare Pages; only pushes touching `docs/` trigger a build, and the Cloudflare check is informational, not required for merge). Every page pins its URL with a `slug:` frontmatter field; keep slugs stable, and add a 301 in `docs/public/_redirects` if one must change.

## Agent Playbook
Automation or scripted work should surface disruptive operations in the PR description and rerun `pnpm run build-with-lint` to keep `main.js`, `manifest.json`, and `versions.json` synchronized. Treat unexpected diffs in those artifacts as blockers until a maintainer approves.
Automation or scripted work should surface disruptive operations in the PR description. Do not edit `manifest.json` or `versions.json`; the release PR bumps them.

## Obsidian Runtime Workflow
Agents with the `verify-in-obsidian` skill get the generic workflow there:
Expand All @@ -60,12 +62,9 @@ brief that a skill-less agent still needs.
configured by `obsidian-e2e.config.mjs` at the repo root (plugin id, the
symlinked artifacts, the `data.json` seed, and the `quickadd:list` ready
probe).
- Worktrees use the isolated vault (`.obsidian-e2e-vaults/quickadd-<worktree>`)
and must not race the shared `dev` vault. The main
`/Users/christian/Developer/quickadd` checkout uses the shared `dev` vault
(root `/Users/christian/Developer/dev_vault/dev`, plugin folder
`.obsidian/plugins/quickadd` symlinked to this checkout's `main.js`); only one
checkout can own those symlinks at a time. Run `pnpm run dev` to rebuild.
- Each checkout gets its own isolated vault
(`.obsidian-e2e-vaults/quickadd-<checkout dir>`) with the plugin artifacts
symlinked to that checkout's build. Run `pnpm run dev` to rebuild.
- Always pass the `vault=` selector as a **prefix** argument, never a suffix -
suffix form can resolve to the wrong vault.
- `pnpm run obsidian:e2e -- <cmd>` attaches to a running instance without
Expand All @@ -74,6 +73,19 @@ brief that a skill-less agent still needs.
load the new `main.js` with `pnpm run obsidian:e2e -- --reload <cmd>` (or
`start:e2e-obsidian`, which always reloads and verifies). If no instance is
running, `obsidian:e2e` launches one first.
- Run native specs with `.agents/run-e2e <spec paths...> [-t <name>]`. Each
run builds `main.js` and replaces any running instance and the vault with
fresh ones, so manual-testing state is gone afterwards. The full suite takes
several minutes; write its output to a file rather than piping it.
- Close modals with Escape or their close button (`closeOpenPrompts` in
`tests/e2e/uiHelpers.ts`), never by removing their DOM: the dead modal's
keymap scope stays on the stack and swallows keys. In manual probes, check
that no `.modal-container` is left before a scenario, or probes hit the
wrong modal.
- In specs, click with `clickWhenStill` from `tests/e2e/uiHelpers.ts`, not
`el.click()` in an eval. Settings pages and the phone menu slide in, and
Obsidian's Menu pushes its keymap scope a tick after showing, so an early
click misses or leaves a dead scope that eats the next modal's Enter.
- Specs that need Templater run only with `OBSIDIAN_E2E_TEMPLATER=1
.agents/run-e2e`, which installs a pinned Templater into the isolated vault.
A change that touches a Templater path must also pass that run: CI runs no
Expand Down Expand Up @@ -122,7 +134,7 @@ pass code via `code=...` from a heredoc/file to avoid shell-quoting corruption.

## CLI-Verifiable Development
- Verifiability is required: work is not complete until behavior can be checked
through the Obsidian CLI in the `dev` vault.
through the Obsidian CLI in the checkout's isolated vault.
- If a flow is UI-only (for example forms/modals), add a CLI-native verification
seam first (command/API entrypoint, inspectable state, and deterministic logs).
- Prefer verification paths that can run both manually and scripted:
Expand Down
3 changes: 1 addition & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,7 @@ as well as with automated tests. When working with the local dev vault, use the
obsidian vault=dev plugin:reload id=quickadd
```

Keep pull requests narrow. Include generated files such as `main.js` and
`styles.css` when the source change updates them.
Keep pull requests narrow.

TypeScript checks use Oxlint. Svelte compiler and type diagnostics fail on
warnings, and a small compiler-AST checker enforces template policies and the
Expand Down
4 changes: 2 additions & 2 deletions obsidian-e2e.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@
// sync); `migrations` is intentionally left empty rather than mirrored.
export default {
pluginId: "quickadd",
// QuickAdd ships a hand-written styles.css at the repo root alongside the
// compiled main.js, so all three plugin artifacts are symlinked into the vault.
// The build writes main.js and styles.css (from src/styles.css) to the repo
// root, so all three plugin artifacts are symlinked into the vault.
pluginArtifacts: ["manifest.json", "main.js", "styles.css"],
defaultData: {
choices: [],
Expand Down
4 changes: 2 additions & 2 deletions tests/e2e/e2eVault.ts
Original file line number Diff line number Diff line change
Expand Up @@ -83,8 +83,8 @@ export const createQuickAddE2EHarness = createPluginHarness({
obsidian.dev.evalJson<boolean>(
`Boolean(app.plugins.plugins.${PLUGIN_ID}?.api)`,
),
// QuickAdd ships a hand-written styles.css alongside the compiled main.js, so
// the provisioned dev vault symlinks all three plugin artifacts.
// The build writes main.js and styles.css (from src/styles.css) to the repo
// root, so the provisioned vault symlinks all three plugin artifacts.
symlinkArtifacts: ["main.js", "manifest.json", "styles.css"],
// QuickAdd debounces settings writes and flushes a pending one on unload
// without awaiting it, so that write could land after the harness restores
Expand Down
56 changes: 52 additions & 4 deletions tests/orb-setup.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,20 +111,24 @@ exit 0
expect(fs.readFileSync(log, "utf8")).not.toContain("test:e2e");
});

// Runs run-e2e against a mock pnpm whose start prints this instance's paths
// and whose Vitest run reports `ran` passed tests.
// Runs run-e2e against a mock pnpm whose provision and start print this
// instance's paths, whose start recreates the vault like the runner does, and
// whose Vitest run reports `ran` passed tests. The vault starts with a
// leftover note.
function runWithMockVitest(name: string, args: string[], ran: number) {
const instanceName = `${name}-${process.pid}-${Date.now()}`;
const initialRoot = prepareProfileRoot();
const home = path.join(profileRoot, instanceName, "home");
fs.mkdirSync(home, { recursive: true });
const vault = path.join(repoRoot, ".obsidian-e2e-vaults", instanceName);
fs.mkdirSync(vault, { recursive: true });
fs.writeFileSync(path.join(vault, "Leftover.md"), "");
const bin = temporaryDirectory("quickadd-mock-bin-args-");
const log = path.join(bin, "calls.log");
fs.writeFileSync(path.join(bin, "pnpm"), `#!/usr/bin/env bash
echo "$*" >> ${JSON.stringify(log)}
if [[ "$*" == *"start:e2e-obsidian"* ]]; then
if [[ "$*" == *"start:e2e-obsidian"* || "$*" == *"provision:e2e-vault"* ]]; then
[[ "$*" == *"start:e2e-obsidian"* ]] && mkdir -p '${vault}'
for prefix in OBSIDIAN QUICKADD; do
echo "export \${prefix}_E2E_VAULT='${instanceName}'"
echo "export \${prefix}_E2E_VAULT_PATH='${vault}'"
Expand All @@ -144,7 +148,7 @@ exit 0
env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
encoding: "utf8",
});
return { result, calls: fs.readFileSync(log, "utf8") };
return { result, calls: fs.readFileSync(log, "utf8"), vaultFiles: fs.readdirSync(vault) };
} finally {
fs.rmSync(vault, { recursive: true, force: true });
cleanProfileInstance(instanceName, initialRoot);
Expand All @@ -157,6 +161,50 @@ exit 0
expect(calls).toContain("\nrun test:e2e tests/e2e/field-label.test.ts -t label --reporter=default --reporter=json --outputFile.json=");
});

it("starts from a fresh instance and vault, and keeps other vaults", () => {
fs.mkdirSync(path.join(repoRoot, ".obsidian-e2e-vaults"), { recursive: true });
const sibling = fs.mkdtempSync(path.join(repoRoot, ".obsidian-e2e-vaults", "orb-sibling-"));
temporaryPaths.push(sibling);
fs.writeFileSync(path.join(sibling, "Note.md"), "");
const { result, calls, vaultFiles } = runWithMockVitest("orb-reset-test", ["tests/e2e/field-label.test.ts"], 1);
expect(result.status, result.stderr).toBe(0);
expect(calls.indexOf("stop:e2e-obsidian")).toBeLessThan(calls.indexOf("provision:e2e-vault"));
expect(calls.indexOf("provision:e2e-vault")).toBeLessThan(calls.indexOf("start:e2e-obsidian"));
expect(vaultFiles).toEqual([]);
expect(fs.readdirSync(sibling)).toEqual(["Note.md"]);
});

it("deletes no vault behind a linked vault directory", () => {
const root = fs.realpathSync(temporaryDirectory("quickadd-linked-root-"));
fs.mkdirSync(path.join(root, ".agents"));
fs.copyFileSync(runE2E, path.join(root, ".agents", "run-e2e"));
const outside = temporaryDirectory("quickadd-linked-outside-");
fs.mkdirSync(path.join(outside, "quickadd-linked"));
fs.writeFileSync(path.join(outside, "quickadd-linked", "Keep.md"), "");
fs.symlinkSync(outside, path.join(root, ".obsidian-e2e-vaults"));
const bin = temporaryDirectory("quickadd-mock-bin-linked-");
fs.writeFileSync(path.join(bin, "pnpm"), `#!/usr/bin/env bash
if [[ "$*" == *"provision:e2e-vault"* ]]; then
echo "export OBSIDIAN_E2E_VAULT_PATH='${root}/.obsidian-e2e-vaults/quickadd-linked'"
fi
exit 0
`, { mode: 0o755 });

const result = spawnSync(path.join(root, ".agents", "run-e2e"), [], {
env: { ...process.env, PATH: `${bin}:${process.env.PATH}` },
encoding: "utf8",
});

expect(result.status).toBe(1);
expect(fs.readdirSync(path.join(outside, "quickadd-linked"))).toEqual(["Keep.md"]);
});

it("drops -- so Vitest still applies the filters", () => {
const { result, calls } = runWithMockVitest("orb-dashdash-test", ["--", "tests/e2e/field-label.test.ts"], 1);
expect(result.status, result.stderr).toBe(0);
expect(calls).toContain("\nrun test:e2e tests/e2e/field-label.test.ts --reporter=default");
});

// Vitest exits 0 when a -t filter matches no test.
it("fails when its arguments match no test", () => {
const { result, calls } = runWithMockVitest("orb-no-spec-test", ["tests/e2e/field-label.test.ts", "-t", "no such test"], 0);
Expand Down
Loading