Vault Intelligence

Appearance

Contributing ​

Thanks for your interest in contributing to this Obsidian plugin. This project relies on modern tooling (Node.js 22+, Vitest, ESLint Flat Config) and follows an "Agentic AI" architecture.

To view or raise a bug or feature request, please use the GitHub Issues page.

Iterative development ​

We follow an Open Development model. All development work is conducted iteratively in public feature branches. This means:

  • We push "interim" work as it happens (granular commits), rather than giant monolithic dumps.
  • All code is available for collaborative review throughout the development cycle, not just at release time.
  • This approach ensures maximum transparency and security auditing.

Getting started ​

Prerequisites ​

  • Node.js: v22.x or higher (Verified in .github/workflows/release.yml)
  • npm: v10+

Installation ​

Use npm ci to install dependencies deterministically.

bash
npm ci

Development ​

Read devs/ARCHITECTURE_AND_STANDARDS.md FIRST before doing any work on the plugin: it contains detailed information on the development process and architecture.

Running locally ​

To start the development build in watch mode:

bash
npm run dev

This uses esbuild to compile changes instantly.

To test your changes in Obsidian:

  1. Install the Hot Reload plugin in a test vault.
  2. Symlink this repository into your vault's .obsidian/plugins/ directory.
  3. Add an empty .hotreload file to the root of this repo.

Linting and testing ​

We maintain high code quality standards. Please run these before pushing:

Linting ​

We use ESLint with a flat config (eslint.config.mts).

bash
npm run lint

Fixes can often be applied automatically with --fix.

Testing ​

We use Vitest for unit and UI testing.

bash
# Run all tests
npm test

# Run tests with UI
npm run test:ui

Testing policy ​

We follow a strict Test-Driven Development (TDD) friendly policy:

  • New Functionality: All major new features must be accompanied by automated tests in the tests/ directory.
  • Bug Fixes: Every bug fix should include a regression test to ensure the issue does not return.
  • Continuous Verification: All tests must pass before a Pull Request is merged. Our CI pipeline enforces this automatically.

Project structure ​

  • src/: Source code (modularized, avoiding a monolithic main.ts).
  • devs/: Developer documentation and guides.
    • devs/adr/: Architecture Decision Records. Please review these to understand key design choices.
    • devs/RELEASE_WORKFLOW.md/: Details on our automated release process.
  • manifest.json: Plugin metadata.

Publishing changes ​

All changes must be submitted via Pull Request. Direct pushes to the main branch are disabled by branch protection rules.

  1. Create a feature branch for your work.

  2. Push your branch frequently to allow for "interim" feedback.

  3. When ready, use our automation script to publish your PR:

    bash
    npm run publish-pr

    This script handles CI verification and follows the project's security policies.

Code review ​

All PRs must be reviewed by at least one maintainer. We look for:

  • Adherence to Architecture and Standards.
  • Passing CI checks (Lint, Build, Test).
  • Meaningful commit messages and signed commits (where possible).

Release process ​

We use a "Zero Memory" automated workflow. Do not manually tag releases.

To prepare a release:

bash
npm run release:prep <patch|minor|major>

See devs/RELEASE_WORKFLOW.md for the complete guide.

Security and privacy ​

We take security seriously. Please refer to our SECURITY.md for our full security policy and instructions on how to report a vulnerability.

  • Local first: The plugin must function offline.
  • Consent: No network calls without explicit user action.
  • Secrets: Securely handle API keys; warn users about where they are stored.

Thank you for helping us build specific, intelligent tools for Obsidian!