Samaya

Samaya is a local-first desktop planning workspace. Its React/Vite interface runs in Tauri, while planner data remains user-owned in an Org directory that can also be edited from Emacs. The planner index is rebuilt in memory from those files; Samaya has no planner database or annex. Only local identity and the last open date live outside Org, in one atomically replaced JSON state document. No account, network service, fake production integration, or loopback listener is required.

Prerequisites

The supported development environment is the committed Nix flake on NixOS. Enter it before installing dependencies or using the native host:

nix develop
pnpm install --frozen-lockfile

The lock-pinned flake provides Node.js, pnpm, Rust, Cargo, pkg-config, WebKitGTK 4.1, Chromium and WebKit for Playwright, actionlint, and the native libraries needed by Tauri on Linux.

Commands

Run every command from the repository root.

• pnpm dev starts the browser-only Vite preview at http://localhost:5173.
• pnpm check runs formatting, linting, TypeScript, frontend tests/build, the Org fidelity corpus through the Rust suite, all Rust format/clippy/test gates, and strict validation of every OpenSpec change and spec. It intentionally does not require a locally launchable browser binary.
• pnpm browser:test runs the small real-browser smoke suite in Chromium and WebKit. Use it from nix develop so the pinned browsers are available.
• pnpm check:ci composes workflow lint, the repository gate, and browser smoke checks. CI performs the frozen install separately first.
• pnpm test:coverage writes advisory HTML/JSON/text coverage reports. Coverage is trend information and has no threshold gate.
• pnpm format applies Biome formatting.
• pnpm lint runs Biome linting.
• pnpm typecheck type-checks the shared UI and desktop workspaces.
• pnpm test runs the browser-focused Vitest and Testing Library suite.
• npx react-doctor@latest --verbose runs an optional advisory React health scan without adding another committed lint dependency.
• pnpm build builds the frontend assets for Tauri.
• pnpm org:fidelity verifies that every supported Org mutation changes only its owned field across the committed fixture corpus.
• cargo run -p samaya-sync -- <command> runs the calendar synchronization binary. It connects Google accounts and keeps calendar.org current independently of the desktop application; see docs/google-calendar.md. It is the one crate with a version of its own, recorded in crates/samaya-sync/CHANGELOG.org.
• pnpm native:dev starts Vite and launches Samaya in a native Tauri window.
• pnpm native:build compiles the release host with Tauri bundling disabled. It does not produce an installer.

Repository layout

apps/
  desktop/                 React, TypeScript, Tailwind, and Vite frontend
    src/modules/planning/  Planner model and focused views
    src/modules/integrations/  Catalog seam and test/demo adapter
    src-tauri/             Standalone Tauri/Rust host and capabilities
crates/
  samaya-planner-core/     Org parser/writer, in-memory index, and watcher
  samaya-sync/             Provider synchronization binary (`samaya-sync`)
    CHANGELOG.org          Its release history; the only versioned crate
packages/
  ui/                      Owned UI primitives, icons, and control styling
openspec/                  Product-change planning artifacts
flake.nix                  Reproducible NixOS development shell
package.json               pnpm workspace commands
pnpm-workspace.yaml        apps/* and packages/* workspace locations

The root is a Cargo workspace containing the Tauri host and samaya-planner-core. The core has no desktop or webview dependencies; the Tauri adapter owns IPC and desktop event emission. @samaya/ui remains intentionally narrow and owns reusable accessible controls.

Org directory

On the supported Linux configuration, create:

${XDG_CONFIG_HOME:-$HOME/.config}/app.samaya.desktop/planner.json

with this exact shape:

{ "orgDirectory": "/absolute/path/to/org" }

Samaya reads that one file during native startup; it does not discover a config by walking parent directories and has no environment-variable override. The orgDirectory value must be an absolute path to a readable directory. A missing file produces the controlled unconfigured screen; an unreadable or malformed file prevents native startup with an error.

The Org directory contains one top-level <project>.org file per project, calendar.org as a read-only generated projection, and archive/ for archived project files. Samaya-created project files declare their category, display tone, task/event keyword sequences, and stable headline IDs. Top-level project files and calendar.org are discovered directly; matching project files below archive/ are scanned recursively. No legacy database import or schema migration path remains.

For Emacs, use archive/%s:: as the project archive location convention. A project file resolves to the identically named file below archive/; automatic archiving is intentionally not implemented in this change.

A fresh installation starts empty—there is no fixture seed generator or sample data written into user files.

Production also starts with no integration sources. The planning shell receives an empty integration catalog at composition, so it does not show demo Jira, GitHub, Forgejo, Linear, or Google Tasks work or simulate refreshes. Frontend tests inject the explicitly named deterministic demo catalog when they exercise integration behavior.

Deliberate deferrals

• Next.js is reserved for a future browser application. Tauri needs static Vite output today; adding Next.js would introduce server-oriented concerns without a web app to serve.
• Turborepo is deferred until multiple workspaces make task graph orchestration and caching worthwhile.
• Additional shared product packages are deferred until a second consumer establishes a real seam. Domain types and planner behavior remain local.
• Effect v4 is deferred until a concrete asynchronous workflow needs typed failures, cancellation, retries, or dependency construction.
• External calendar synchronization, automatic archiving, routing, drag-and-drop libraries, and packaging remain deferred. calendar.org is indexed read-only but is not populated by this change.

When any of those needs becomes concrete, introduce it through a focused change instead of maintaining placeholder architecture.

Verification scope

Browser rendering, Org fidelity, planner-core, strict OpenSpec, and Forgejo workflow syntax are automated. Chromium/WebKit smoke behavior is not: the suite is kept and passes, but it runs from nix develop on demand rather than as a gate, because the browsers it needs are only usable inside that shell. Native launch and release no-bundle compilation are verified from nix develop on the supported NixOS host when WebKitGTK/display support is available. Browser smoke tests are not native Tauri IPC tests; their injected deterministic transport/catalog harness exercises composition and supported UI behavior without pretending to contact an integration provider. This does not claim installer, signing, updater, Windows, or macOS support.