Skip to content

AGENTS.md

Latest commit

 

History

History
122 lines (101 loc) · 5.24 KB

AGENTS.md

File metadata and controls

122 lines (101 loc) · 5.24 KB

Repository Guidelines

Project Overview

PodNotes is an Obsidian community plugin for listening to podcasts, tracking playback progress, creating podcast notes, capturing timestamps, downloading episodes, using local audio files, and exposing a small API for workflow plugins.

Project Structure

Source code lives in src/. Core plugin registration and lifecycle wiring live in src/main.ts; public API code is under src/API/; parsing code is under src/parser/; stores and controllers are under src/store*; utility functions are under src/utility/; Svelte UI lives under src/ui/; shared types live in src/types/.

Tests are colocated with source files as *.test.ts where practical. Shared test mocks live in tests/mocks/. User-facing documentation lives in docs/ and is built with MkDocs.

Generated plugin artifacts such as main.js and source maps are ignored by git and should not be hand-edited. Production builds write main.js at the repo root for release packaging; development builds write into build/ and maintain root symlinks for local Obsidian loading.

Tooling

  • Use Node 22. The repo has .nvmrc, .npmrc, and package.json engines for this.
  • Use npm for package management and scripts. Do not introduce another package manager unless the migration is intentional and removes the old lockfile.
  • Use Conventional Commits (feat:, fix:, test:, docs:, chore:) so semantic-release can determine versions.
  • If work resolves a GitHub issue, prefer an issue-linked branch workflow before implementation.

Common Commands

  • npm install: install dependencies for local development.
  • npm run dev: watch-mode development build via Vite.
  • npm run typecheck: run tsc --noEmit.
  • npm run lint: run ESLint against TypeScript sources.
  • npm run format:check: run the configured Biome check.
  • npm run check:a11y: run svelte-check --fail-on-warnings.
  • npm run test: run Svelte checks and the Vitest suite.
  • npm run build: type-check and produce the production plugin bundle.
  • npm run docs:build: build the MkDocs documentation.
  • npm run docs:deploy: build docs and deploy docs/site to Cloudflare Pages.

Before opening a PR or cutting a release, run the CI-equivalent checks locally:

npm run lint
npm run format:check
npm run typecheck
npm run build
npm run test
npm run docs:build

Testing

Vitest runs in jsdom and aliases obsidian to tests/mocks/obsidian.ts. Prefer unit tests for pure utility, parser, store, API, and component behavior. Use Testing Library for Svelte component behavior instead of asserting on implementation details.

When a bug depends on real Obsidian runtime behavior, reproduce it in Obsidian before changing code and verify it there after the fix. Timestamp links, URI handling, playback restore, downloaded/local media, file writes, settings migrations, and workspace/view behavior are runtime-sensitive and should not be trusted to jsdom alone.

For runtime verification, record the exact Obsidian version, platform, vault setup, feed or local file used, command or URI invoked, console/runtime errors, and observed plugin state before and after the action.

Obsidian Runtime Workflow

Use a dedicated development vault for manual or scripted Obsidian checks. Ensure the vault's PodNotes plugin folder points at this checkout's generated plugin artifacts before trusting runtime evidence.

Typical local loop:

npm run dev
# reload or re-enable PodNotes in the development vault
# trigger the relevant command, UI flow, or obsidian://podnotes URI
# inspect console/errors and plugin state

If using the obsidian CLI, pass the vault selector consistently and prefer scripted, repeatable checks for non-trivial flows. For bugs involving commands or URIs, test both the user-facing path and the direct command/URI path when possible.

Documentation

Docs live in docs/docs/ and are configured by docs/mkdocs.yml. Update docs with user-facing behavior changes, new commands, API changes, template syntax, transcript behavior, local-file behavior, or import/export changes.

Use npm run docs:build to validate docs locally. The Cloudflare Pages output directory is docs/site, configured in wrangler.jsonc.

Release Notes

The release setup is semantic-release based. npm version runs version-bump.mjs, which keeps manifest.json and versions.json in sync with the package version and Obsidian minAppVersion.

Release assets are main.js and manifest.json. Keep version metadata changes generated by the release process with the release commit, and treat unexpected diffs in package.json, package-lock.json, manifest.json, or versions.json as blockers until understood.

PR Expectations

Pull requests should include:

  • a concise summary of the user-facing change;
  • linked issues when relevant;
  • screenshots or short recordings for visible UI changes;
  • feed URLs, local file details, or transcript setup for podcast-specific fixes;
  • exact commands run and whether Obsidian runtime verification was performed;
  • release or migration impact, especially for settings, storage, API, or URI behavior.

Keep changes scoped to the touched behavior. Do not mix unrelated formatting, dependency churn, docs rewrites, or generated artifact changes into feature and bug-fix commits.