Skip to content

README.md

Latest commit

 

History

History
223 lines (154 loc) · 7.7 KB

README.md

File metadata and controls

223 lines (154 loc) · 7.7 KB
Raw

Lunor

A calm, local-first command center for every repository on your machine.

License: MIT Node.js 22+ pnpm 9

Lunor discovers Git repositories inside folders you choose, indexes them locally, and gives you a fast way to understand, open, annotate, archive, and clean them up.

It is built for developers who have outgrown a terminal full of paths but do not want another cloud service in the middle of their workflow.

Project status

Lunor is in active early development. The core scanner, local index, dashboard, cleanup flow, and repository actions are working; packaging and distribution are still evolving.

Why Lunor?

Large codebases tend to accumulate locally long before they are organized. Lunor gives that collection a quiet, searchable home without requiring an account, a hosted backend, or a full-machine scan.

  • Local-first — repository metadata and activity stay on your machine.
  • Explicit scope — Lunor only scans folders that you add.
  • Storage visibility — see which repositories and generated folders consume space.
  • Fast actions — open a repo in your editor, terminal, or file manager.
  • Safe cleanup — remove regenerable dependency folders without deleting source code.

Features

  • Discover Git repositories recursively inside selected scan folders.
  • Search, filter, sort, pin, archive, and inspect repositories.
  • View repository state, path, branch, size, dependency size, and activity.
  • Add private notes to repositories.
  • Open repositories through configurable local commands.
  • Detect common dependency, build, cache, and virtual-environment folders.
  • Review cleanup candidates based on staleness and dependency weight.
  • Delete selected generated folders while preserving source code.
  • Track repository actions in a local activity log.
  • Use a responsive dashboard with list and grid views.

Safety model

Lunor separates index-only actions from actions that touch files on disk.

Action Effect
Archive Changes the repository's visibility inside Lunor. Files are untouched.
Remove from index Removes Lunor's record. The repository directory is untouched.
Clean dependencies Deletes only selected regenerable dependency folders from disk.
Scan Searches only the folders explicitly added to Lunor.

Lunor does not scan your whole machine by default, upload repository metadata, or require a cloud account.

Quick start

Requirements

  • Node.js 22 or newer
  • pnpm 9
  • Git

VS Code, a terminal emulator, and a file manager are optional but useful for repository actions.

Install

pnpm install

Start development

pnpm dev

This starts the local API server and Vite web application in parallel. Open the URL printed by Vite, add a scan folder, and start indexing.

Build and run

pnpm start

This builds the web application and starts the local server. The server serves packages/web/dist when the build output exists.

Deployment

Public landing page on Vercel

The public landing page can be deployed as a static Vite site at trylunor.vercel.app.

In Vercel, create a project for this repository with:

Setting Value
Framework preset Vite
Install command pnpm install --frozen-lockfile
Build command pnpm --filter @lunor/web build
Output directory packages/web/dist

The deployment includes the landing page, metadata, manifest, robots.txt, and sitemap. The dashboard routes are not a hosted multi-user service; they require the local Lunor server and access to the machine's repositories.

Run the full app locally

For the complete experience, run Lunor on the machine that contains your repositories:

pnpm install
pnpm start

Vercel cannot safely provide the full local workflow because the server needs local filesystem access, a local SQLite database, and permission to launch the user's editor, terminal, and file manager. Hosting those pieces would require a separate remote backend and a different security model.

Configuration and CLI

Run the server directly during development:

pnpm --filter @lunor/server dev -- --no-open

The local server listens on http://localhost:3333 by default.

Common options:

# Change the port
pnpm --filter @lunor/server dev -- --port 4000

# Use a custom database path
pnpm --filter @lunor/server dev -- --db /tmp/lunor.db

# Prevent the browser from opening
pnpm --filter @lunor/server dev -- --no-open

Lunor stores its SQLite database locally:

  • Windows: %APPDATA%/lunor/lunor.db
  • Linux, macOS, and WSL-like environments: ~/.config/lunor/lunor.db

Use --db to override the location.

Development commands

Command Purpose
pnpm dev Run the API server and web app in parallel
pnpm start Build the web app and start the server
pnpm build Build the web app
pnpm test Run the workspace test suites
pnpm typecheck Run TypeScript checks across packages
pnpm lint Run Biome formatting and lint checks

Architecture

Lunor is a pnpm workspace with a local Fastify service, a React client, and shared validation contracts.

packages/
├── server/
│   ├── src/
│   │   ├── app.ts          Fastify app and route registration
│   │   ├── cli.ts          Local server entrypoint
│   │   ├── db/             SQLite schema and bootstrap
│   │   ├── routes/         Local HTTP API
│   │   └── services/       Scanner, sizing, actions, and queue logic
│   └── test/               Server and integration tests
├── web/
│   └── src/
│       ├── components/     Reusable interface components
│       ├── screens/        Dashboard, cleanup, and onboarding
│       ├── api/            Browser API client
│       └── lib/            Formatting and UI helpers
└── shared/
    └── src/                Shared DTOs and Zod schemas

Technology

  • TypeScript
  • React 19 and Vite
  • Tailwind CSS v4 with project-specific design tokens
  • TanStack Router, Query, and Virtual
  • Fastify
  • SQLite through better-sqlite3 and Drizzle ORM
  • Vitest
  • Biome

Scan scope

Lunor recursively searches repositories inside the scan roots you add. Discovery depth is bounded, and common dependency, build, cache, and Git-internal folders are skipped to keep scans predictable.

Repository sizing uses cached metadata when roots and lockfiles are unchanged. Where available, POSIX du provides a fast sizing path; environments without it use the TypeScript walker.

Contributing

Issues, design feedback, and pull requests are welcome.

Before opening a pull request:

pnpm install
pnpm typecheck
pnpm test
pnpm lint
pnpm build

Keep changes focused, preserve local-first behavior, and include tests for new server behavior or data contracts.

Security and privacy

Lunor is designed to run locally. It stores its database on the local machine and does not upload repository metadata as part of its normal operation.

If you discover a security issue, please avoid posting sensitive details in a public issue. Contact the maintainers privately first so the issue can be assessed responsibly.

Roadmap

The current development focus is improving the core local workflow, packaging, and distribution. The project will continue to prioritize predictable scans, safe cleanup, and a low-friction developer experience.

License

Lunor is available under the MIT License.