Skip to main content
Glama
pantry-pulse

pantry-pulse

by aranlucas
README.md
# Pantry Pulse

[![CI](https://img.shields.io/github/actions/workflow/status/aranlucas/pantry-pulse/ci.yml?branch=main&label=CI)](https://github.com/aranlucas/pantry-pulse/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Pantry Pulse is a private household RFID pantry station with a React dashboard,
Cloudflare Worker, D1 inventory, and guarded MCP access. It is designed for one
household rather than a hosted multi-tenant service.

For product priorities and acceptance goals, see [the roadmap](ROADMAP.md).
[Design direction and concept artwork](docs/design/spec.md) guide the interface;
the images are concepts, not deployment screenshots.

## Linking and stock corrections

`POST /api/items/:id/link` changes only supplied metadata fields. Omitted fields are preserved; a `null` RFID or catalog field clears that link, while `null` `unit`, `target`, or `onHand` leaves the existing value unchanged. Catalog provider and item ID must form a complete pair after the update.

A non-null `onHand` is an absolute stock correction. Send `expectedQuantity` with the count the editor originally displayed to reject stale edits with `409 inventory_conflict`. If it is omitted, the command checks the count read when the request starts. The stock change, metadata, and inventory event commit together, or none do. On conflict, refresh the pantry and reopen the item before retrying. The dashboard sends a correction only when its on-hand field changed; MCP metadata linking never changes stock.

Any non-null `onHand`, including one equal to the current count, also records `countedAt`: the last time someone stated the absolute count. An unchanged count updates `countedAt` only and adds no inventory event. Item creation records the initial count. Station scans and +/- adjustments are relative changes and never confirm a total. The shopping queue's **Count is right** button sends `{ "onHand": n, "expectedQuantity": n }`, so a count that changed since the page loaded gets the same `409 inventory_conflict`.

## Shopping queue

Each queue line in `/api/snapshot`, MCP `pantry_snapshot`, and MCP `shopping_queue_export` explains why the item is on the list:

- `quantity` and `targetQuantity`: the item is queued because it has `quantity` of `targetQuantity`. `quantityNeeded` is the difference.
- `lastChange`: the most recent applied inventory event (`delta`, `source`, `reason`, `createdAt`), or `null` once the item's history has passed the 90-day retention window.
- `countedAt` and `countStatus`: `counted` when the count was stated within the last 14 days, otherwise `needs_check`, including items that have never been counted.

The markdown export appends `(have 1 of 2; counted 2026-11-03)` or `(have 1 of 2; count needs a check)` to each checklist line. The JSON export contains the full queue lines.

## Local development

Requirements:

- Node.js 24.8 or newer.
- The pnpm version pinned by `packageManager` in `package.json`. Cloudflare CLI (`cf`) and the Cloudflare Vite plugin are installed by the project.

Install dependencies and create untracked local Worker credentials:

```bash
corepack enable
pnpm install --frozen-lockfile
cp .dev.vars.example .dev.vars
```

Replace every token in `.dev.vars` with a high-entropy value. Apply the local D1 migration and seed the sample pantry before starting the development server:

```bash
pnpm db:migrate:local
pnpm db:seed:local
pnpm dev
```

`pnpm dev` starts Vite with the Cloudflare plugin through [Portless](https://github.com/vercel-labs/portless) (a dev dependency); its first run may ask for `sudo` to bind port 443 and trust a local certificate. Open `https://pantry-pulse.localhost`; the same server serves the dashboard and runs `/api`, `/health`, and `/mcp` in the Workers runtime. The dashboard asks for `ADMIN_TOKEN` from `.dev.vars`.

The Cloudflare plugin and local D1 scripts share `.cloudflare/state/`, configured with `persistState` in `vite.config.ts`. The scripts pass `--persist-to .cloudflare/state` because `cf` resource commands otherwise use a machine-wide state directory.

For a deployed D1 database, review the migration and run the remote commands explicitly:

```bash
pnpm db:migrate:remote
pnpm db:seed:remote
```

The remote commands require `pnpm cf auth login` or a `CLOUDFLARE_API_TOKEN` and operate on the database UUID declared in `cloudflare.config.ts`. `cf` D1 commands default to remote resources; the local scripts explicitly pass `--local`. If you provision a different database, update its ID in both the config and the database scripts in `package.json`.

## Firmware

See the [ESP32 station guide](firmware/esp32-rfid/README.md) for wiring,
configuration, flashing, and scan recovery behavior. PlatformIO is required only
for firmware work.

## Checks and deployment

```bash
pnpm check
pnpm test
```

`pnpm check` runs formatting, linting, type checking, and `cf deploy --dry-run`,
which builds the application and validates the upload without sending it.
`pnpm test` runs the `client` (Node) and `worker` (Workers runtime) Vitest
projects. Type checking generates ignored Worker declarations under
`.cloudflare/types/` first.

To deploy, run `pnpm cf deploy`; it builds the Worker and dashboard into `.cloudflare/output/` and uploads them. `pnpm build` runs only the build step. Use `pnpm cf deploy`, not `pnpm deploy`, which is pnpm's built-in workspace command.

The project uses the [Cloudflare CLI](https://developers.cloudflare.com/cf/) and Cloudflare Vite plugin 2.0 beta. `cloudflare.config.ts` owns Worker settings and bindings; `vite.config.ts` configures development, bundling, and both Vitest projects. `cf` is currently in beta.

## Security and retention

See [SECURITY.md](SECURITY.md) for token scopes, credential handling, and private
vulnerability reporting.

The daily scheduled Worker task removes detailed inventory events after 90 days.
Compact tombstones remain to prevent late hardware retries from applying twice;
retain them when maintaining the database. `/health` checks the D1 binding.