nutrilog 0.1.0__tar.gz

nutrilog-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Run test suite
+        run: uv run --python ${{ matrix.python-version }} --extra dev pytest --cov=nutrilog

nutrilog-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Test & Verify Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Run test suite
+        run: uv run --extra dev pytest --cov=nutrilog
+
+  build-and-publish:
+    name: Build & Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nutrilog
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publishing (OIDC)
+      contents: write  # Required for GitHub Release creation
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build distributions (sdist & wheel)
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

nutrilog-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Local credentials & secrets
+tokens.json
+credentials.json
+client_secrets*.json
+client_secret*.json
+*.token
+
+# IDE & OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store

nutrilog-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nutrilog Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nutrilog-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: nutrilog
+Version: 0.1.0
+Summary: A standalone, privacy-first CLI tool for logging meals, macronutrients, and calories directly to Google Health.
+Author: Nutrilog Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calories,cli,fitbit,google-health,health,macros,nutrition
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: google-auth-oauthlib>=1.2.0
+Requires-Dist: google-auth>=2.28.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nutrilog
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Built with Typer & Rich](https://img.shields.io/badge/CLI-Typer%20%26%20Rich-green.svg)](https://typer.tiangolo.com)
+[![uvx ready](https://img.shields.io/badge/uvx-ready-purple.svg)](https://github.com/astral-sh/uv)
+
+A fast, privacy-first CLI tool for logging meals, macronutrients, and calories directly to the **Google Health API (`health.googleapis.com/v4`)** from any terminal. Syncs live with your **Google Health app**, **Fitbit**, and **Pixel Watch**.
+
+---
+
+```
+                       Today's Nutrition Summary (Mon, Aug 17)
+┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
+┃ Time       ┃ Meal Type    ┃ Food                     ┃ Protein ┃ Calories ┃   Carbs ┃    Fat ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
+│ 12:30 PM   │ Lunch        │ Tofu Edamame Soba Bowl   │   38.5g │ 580 kcal │   54.0g │  18.0g │
+│ 04:00 PM   │ Snack        │ Protein Shake            │   25.0g │ 180 kcal │    4.0g │   2.0g │
+└━━━━━━━━━━━━┴━━━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━┴━━━━━━━━━━┴━━━━━━━━━┴━━━━━━━━┘
+╭──────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Daily Total: 63.5g / 120g Protein (53%) | 760 / 2,000 kcal (38%)                             │
+│ Remaining:   56.5g Protein | 1,240 kcal                                                      │
+╰──────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+---
+
+## ⚡ Quickstart
+
+### 1. Run Instantly with `uvx` (No Installation Required)
+
+```bash
+# Log a meal using intuitive shorthand syntax (in dry-run preview)
+uvx --from . nutrilog "38p 18f 54c 580k Tofu Edamame Soba Bowl" --dry-run
+
+# View today's summary & daily target progress
+uvx --from . nutrilog today
+
+# View command help
+uvx --from . nutrilog --help
+```
+
+### 2. Install Globally with `uv` or `pip`
+
+```bash
+# Install globally via uv
+uv tool install .
+
+# Or via standard pip
+pip install .
+```
+
+---
+
+## 🏗️ Architecture & Cloud Sync
+
+```mermaid
+graph LR
+    User["User Terminal"] --> CLI["nutrilog CLI<br/>(Typer + Rich)"]
+    CLI --> Parser["Macro & Shorthand<br/>Regex Parser"]
+    CLI --> Auth["OAuth 2.0 Auth Manager<br/>(PKCE / Loopback)"]
+    Auth --> Keyring["Local Token Store<br/>(~/.config/nutrilog/tokens.json)"]
+    CLI --> Client["Google Health Client<br/>(health.googleapis.com/v4)"]
+    Client --> GoogleHealth["Google Health Platform<br/>(Pixel Watch / Fitbit / Mobile App)"]
+```
+
+- **Zero-Friction Logging:** Log any meal in $<2$ seconds directly from your command line.
+- **Hardware & Cloud Sync:** Data writes directly to Google Health API and syncs to your Pixel Watch, Fitbit, and phone dashboard.
+- **Local & Private:** Auth tokens are stored locally on your machine with strict `0600` permissions.
+
+---
+
+## 🚀 Usage & Commands
+
+### 1. Shorthand Meal Logging
+
+Macros and calorie tokens can appear anywhere in the string in any order:
+
+```bash
+# Shorthand notation (protein 'p', fat 'f', carbs 'c', calories 'k' or 'cal')
+nutrilog "38p 18f 54c 580k Tofu Edamame Soba Bowl"
+
+# Explicit units and labels
+nutrilog "Grilled Salmon protein: 35g, fat: 12g, carbs: 5g, calories: 280, fiber: 2g"
+
+# Prefix notation
+nutrilog "p30 f10 c45 390cal Chicken Burrito Bowl"
+
+# Automatic calorie calculation if calories are omitted (4*P + 4*C + 9*F)
+nutrilog "30p 40c 10f Oatmeal"
+```
+
+#### Shorthand Syntax Cheat-Sheet
+
+| Nutrient | Recognized Formats |
+| :--- | :--- |
+| **Protein** | `38p`, `p38`, `38g protein`, `protein: 38g`, `pro: 38` |
+| **Fat** | `18f`, `f18`, `18g fat`, `fat: 18g`, `total_fat: 18` |
+| **Carbohydrates** | `54c`, `c54`, `54g carbs`, `carbs: 54g`, `carb: 54` |
+| **Calories / Energy**| `580k`, `580cal`, `580kcal`, `cal: 580`, `calories: 580` |
+| **Fiber** | `9fib`, `9g fiber`, `fiber: 9g` |
+| **Sugar** | `5sug`, `5g sugar`, `sugar: 5g` |
+| **Sodium** | `500mg sod`, `sodium: 0.5g` |
+
+---
+
+### 2. Flag-Based Logging
+
+```bash
+# Explicit flags
+nutrilog log "Grilled Barramundi & Veggies" \
+  --protein 36 \
+  --calories 480 \
+  --fat 14 \
+  --carbs 12 \
+  --meal lunch
+
+# Quick macro top-up (e.g. protein shake, snack)
+nutrilog quick --protein 25 --calories 180 --name "Post-Workout Protein Shake"
+
+# Dry run (preview payload without sending)
+nutrilog "35p 450k Protein Shake" --dry-run
+
+# Output raw JSON payload
+nutrilog "35p 450k Protein Shake" --json
+```
+
+---
+
+### 3. Reviewing Today's Totals, History & Listing Meals
+
+```bash
+# View today's rollup vs daily targets
+nutrilog today
+
+# List recent meals with their Data Point IDs
+nutrilog list --days 3
+
+# View past week's meal history
+nutrilog history --days 7 --ids
+```
+
+---
+
+### 4. Deleting Meals
+
+Delete mistakenly logged or duplicate meals using their Data Point ID:
+
+```bash
+# Delete with confirmation prompt
+nutrilog delete <DATA_POINT_ID>
+
+# Delete immediately (skip prompt)
+nutrilog delete <DATA_POINT_ID> --yes
+# Or alias
+nutrilog rm <DATA_POINT_ID> -y
+```
+
+---
+
+### 5. Configuring Daily Nutrition Targets
+
+```bash
+# Display active daily targets
+nutrilog config show
+
+# Set custom daily macro and calorie targets
+nutrilog config set --calories 2200 --protein 140 --carbs 220 --fat 65
+```
+
+---
+
+## 🤖 AI Agent Skill Integration
+
+Nutrilog includes a packaged **Agent Skill** (`SKILL.md`) that allows AI coding assistants (Gemini, Claude Code, Cursor, Antigravity) to discover and run Nutrilog commands autonomously.
+
+```bash
+# Check skill status across detected AI tools
+nutrilog skill status
+
+# Install into default shared location (~/.agents/skills)
+nutrilog skill install
+
+# Install into all detected agent tool directories
+nutrilog skill install --all
+
+# Symlink instead of copying (for live package updates)
+nutrilog skill install --all --link
+```
+
+---
+
+## 🔑 Google Cloud Authentication (`nutrilog auth`)
+
+Nutrilog connects directly to the Google Health API using OAuth 2.0.
+
+### Step 1: GCP Project Setup (Free, 1-time)
+
+1. Create or select a project in [Google Cloud Console](https://console.cloud.google.com).
+2. Enable the **Google Health API** (*APIs & Services $\rightarrow$ Library $\rightarrow$ Google Health API $\rightarrow$ Enable*).
+3. Under **OAuth consent screen**, select **External**, and add your email to **Test Users**.
+4. Under **Credentials**, create an **OAuth client ID** of type **Desktop App**, and download the JSON credentials.
+
+### Step 2: Configure & Log In
+
+```bash
+# Option A: Import client_secrets.json file
+nutrilog auth setup --file path/to/client_secrets.json
+
+# Option B: Pass credentials via CLI flags
+nutrilog auth setup --client-id "<YOUR_CLIENT_ID>" --client-secret "<YOUR_CLIENT_SECRET>"
+
+# Option C: Use environment variables
+export NUTRILOG_CLIENT_ID="<YOUR_CLIENT_ID>"
+export NUTRILOG_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
+
+# Complete browser OAuth login
+nutrilog auth login
+
+# Check authentication status & token expiry
+nutrilog auth status
+
+# Sign out & clear local tokens
+nutrilog auth logout
+```
+
+---
+
+## 🧪 Development & Testing
+
+Each Python module has a corresponding `_test.py` unit test suite alongside it:
+
+```bash
+# Set up virtual environment and install dependencies
+uv venv
+uv pip install -e ".[dev]"
+
+# Run full test suite (57 tests)
+uv run pytest
+
+# Run tests with coverage report
+uv run pytest --cov=nutrilog
+```
+
+---
+
+## 📄 License
+MIT License. See [LICENSE](LICENSE) for details.

nutrilog-0.1.0/PLAN.md

@@ -0,0 +1,241 @@
+# Nutrilog: End-to-End Implementation & Publishing Plan
+
+A standalone, privacy-first CLI tool for logging meals, macronutrients, and calories directly to the **Google Health API (`health.googleapis.com/v4`)** from any terminal, usable with any standard `@gmail.com` or Google Workspace account.
+
+---
+
+## 1. Executive Architecture Overview
+
+```mermaid
+graph LR
+    User["User Terminal"] --> CLI["nutrilog CLI<br/>(Click / Typer)"]
+    CLI --> Parser["Macro & Timestamp<br/>Parser"]
+    CLI --> Auth["OAuth 2.0 Auth Manager<br/>(PKCE / Local Loopback)"]
+    Auth --> Keyring["Local Token Store<br/>(~/.config/nutrilog/tokens.json)"]
+    CLI --> Client["Google Health Client<br/>(health.googleapis.com/v4)"]
+    Client --> GoogleHealth["Google Health Platform<br/>(Google Health App / Pixel Watch / Fitbit)"]
+```
+
+### Core Goals:
+1. **Zero-Friction Logging:** Log any meal (cafe, restaurant, home-cooked) in $<2$ seconds via shorthand or natural flags.
+2. **True Cloud Sync:** Syncs natively with the user's Pixel Watch, Fitbit, and Google Health mobile app.
+3. **Works Anywhere:** Completely decoupled from internal corporate tooling (`google3`), packaged as a clean open-source Python tool (`pip` / `pipx`).
+4. **Google Cloud Publishing Path:** Clear roadmap from personal developer mode ("Testing" state) to verified published OAuth app.
+
+---
+
+## 2. Google Cloud & OAuth 2.0 Setup (Prerequisites & Publishing)
+
+Because health and nutrition data is categorized under Google's **Sensitive / Restricted Scopes**, Google applies specific verification tiers for OAuth applications.
+
+### Phase 2.1: Google Cloud Project Creation
+1. Create a project in [Google Cloud Console](https://console.cloud.google.com): `nutrilog-cli-app`.
+2. Enable the **Google Health API**:
+   * Navigate to *APIs & Services > Library*.
+   * Search for **Google Health API** and click **Enable**.
+
+### Phase 2.2: OAuth 2.0 Consent Screen Configuration
+1. **User Type:** Select **External** (allows any `@gmail.com` account to sign in).
+2. **App Information:**
+   * App Name: `Nutrilog CLI`
+   * User support email: Developer email.
+   * App logo (optional, 120x120px).
+3. **Scopes Requested:**
+   * `https://www.googleapis.com/auth/health.nutrition.writeonly` (Required: write meals, calories, macros)
+   * `https://www.googleapis.com/auth/health.nutrition.readonly` (Optional: view meal history)
+4. **OAuth Client Credentials:**
+   * Create Credentials > **OAuth Client ID**.
+   * Application Type: **Desktop App**.
+   * Name: `Nutrilog Desktop Client`.
+   * Download `client_secrets.json`.
+
+---
+
+### Phase 2.3: The Verification & Publishing Roadmap
+
+Google enforces specific trust states for OAuth applications accessing Health APIs:
+
+```
+[ State A: Local Developer Mode ]
+       │  (Self-use & Test Users)
+       ▼
+[ State B: Pre-Launch / Test Track ] ──► Up to 100 explicit test Gmail accounts
+       │                                  (Instant access, zero review required)
+       ▼
+[ State C: Public Production App ]  ──► Cloud Verification + CASA Assessment
+                                          (Publicly usable by anyone on the internet)
+```
+
+| Deployment Tier | Who Can Sign In | Requirements | Best For |
+| :--- | :--- | :--- | :--- |
+| **Tier 1: Developer / Testing** *(Fastest)* | You + up to 100 explicitly added test Gmail accounts. | • Add test emails in GCP Console.<br/>• Users see a one-time *"Google hasn't verified this app"* warning screen. | **Immediate personal use, pair programming, beta testers.** |
+| **Tier 2: Publicly Verified App** | Any Google account worldwide without warning dialogs. | • Public domain with verified ownership.<br/>• Privacy Policy & Terms of Service URLs.<br/>• YouTube demo video showing OAuth flow.<br/>• Cloud Application Security Assessment (CASA Tier 2). | **Public PyPI release for widespread distribution.** |
+
+> [!TIP]
+> **Recommended Strategy:** Start in **Tier 1 (Testing Mode)** with your personal Gmail added to the Test Users list. This allows full, unrestricted API access within 5 minutes while working towards Tier 2 verification for public PyPI distribution.
+
+---
+
+## 3. Google Health API (v4) Technical Specification
+
+### 3.1 Endpoint Schema
+* **URL:** `POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints`
+* **HTTP Method:** `POST`
+* **Headers:**
+  ```http
+  Authorization: Bearer <ACCESS_TOKEN>
+  Content-Type: application/json
+  ```
+
+### 3.2 Canonical JSON Request Payload
+```json
+{
+  "nutritionLog": {
+    "foodDisplayName": "Tofu & Edamame Soba Bowl",
+    "mealType": "LUNCH",
+    "interval": {
+      "startTime": "2026-08-17T12:30:00Z",
+      "endTime": "2026-08-17T13:00:00Z"
+    },
+    "energy": {
+      "kcal": 580
+    },
+    "totalCarbohydrate": {
+      "grams": 54.0
+    },
+    "totalFat": {
+      "grams": 18.0
+    },
+    "nutrients": [
+      {
+        "nutrient": "PROTEIN",
+        "quantity": {
+          "grams": 38.5
+        }
+      },
+      {
+        "nutrient": "FIBER",
+        "quantity": {
+          "grams": 9.0
+        }
+      },
+      {
+        "nutrient": "SODIUM",
+        "quantity": {
+          "grams": 0.650
+        }
+      }
+    ],
+    "serving": {
+      "amount": 1.0,
+      "unit": "bowl"
+    }
+  }
+}
+```
+
+### 3.3 Supported Nutrients & Enums
+* **Meal Types:** `MEAL_TYPE_UNSPECIFIED`, `BREAKFAST`, `LUNCH`, `DINNER`, `SNACK`.
+* **Nutrient Enums:** `PROTEIN`, `TOTAL_FAT`, `TOTAL_CARBOHYDRATE`, `FIBER`, `SUGAR`, `SODIUM`, `POTASSIUM`, `CALCIUM`, `IRON`, `SATURATED_FAT`, `CHOLESTEROL`.
+
+---
+
+## 4. Local CLI Implementation Architecture
+
+```
+~/Sandbox/nutrilog/
+├── pyproject.toml              # Build & dependency metadata (Hatchling / Flit)
+├── README.md                   # Quickstart, setup guide & documentation
+├── nutrilog/
+│   ├── __init__.py
+│   ├── cli.py                  # CLI command dispatch & argument parsing (Typer/Click)
+│   ├── auth.py                 # OAuth 2.0 PKCE local loopback flow & token refresh
+│   ├── client.py               # Google Health API v4 HTTP client
+│   ├── parser.py               # Shorthand & natural language macro parser
+│   ├── storage.py              # Local secure token & cache management
+│   └── models.py               # Pydantic data schemas for meals & nutrients
+└── tests/
+    ├── test_parser.py          # Unit tests for shorthand macro syntax
+    ├── test_client.py          # Mocked HTTP tests for API payloads
+    └── test_auth.py            # Token refresh & keyring tests
+```
+
+---
+
+## 5. User Experience & CLI Command Design
+
+### 5.1 Initial Setup (`nutrilog auth`)
+```bash
+# Authenticate with Google OAuth via browser loopback
+nutrilog auth login
+
+# Check authentication status & token expiry
+nutrilog auth status
+
+# Discard tokens & sign out
+nutrilog auth logout
+```
+
+### 5.2 Fast Shorthand Logging (`nutrilog log` / `nutrilog quick`)
+```bash
+# 1. Shorthand notation (macros + name)
+nutrilog "38p 18f 54c 580k Tofu Edamame Soba Bowl"
+
+# 2. Flag-based explicit logging
+nutrilog log "Grilled Barramundi & Veggies" \
+  --protein 36 \
+  --calories 480 \
+  --fat 14 \
+  --carbs 12 \
+  --meal lunch
+
+# 3. Quick calorie/protein top-up
+nutrilog quick --protein 25 --calories 180 --name "Post-workout Protein Shake"
+```
+
+### 5.3 Meal History & Daily Targets (`nutrilog today` / `nutrilog history`)
+```bash
+# View today's total logged macros vs daily targets
+nutrilog today
+
+# Output:
+# ━━━━━━━━━━━━━━━━ Today's Nutrition Summary (Mon, Aug 17) ━━━━━━━━━━━━━━━━
+# Meals Logged: 2
+# • 12:30 PM [Lunch]  Tofu & Edamame Bowl  38.5g P | 580 kcal | 54g C | 18g F
+# • 04:00 PM [Snack]  Protein Shake        25.0g P | 180 kcal |  4g C |  2g F
+# ──────────────────────────────────────────────────────────────────────────
+# Daily Total:        63.5g / 120g Protein (53%) | 760 / 2,000 kcal (38%)
+# Remaining:          56.5g Protein | 1,240 kcal
+```
+
+---
+
+## 6. Detailed Step-by-Step Implementation Roadmap
+
+### Step 1: GCP Project & OAuth Setup
+* [ ] Create GCP Project: `nutrilog-prod`.
+* [ ] Enable `Google Health API` in API Library.
+* [ ] Configure OAuth Consent Screen (External, Test mode).
+* [ ] Add personal Gmail to **Test Users**.
+* [ ] Download Desktop OAuth Client JSON to `~/.config/nutrilog/credentials.json`.
+
+### Step 2: Core Python Engine (`nutrilog/`)
+* [ ] **`auth.py`**: Implement `InstalledAppFlow.run_local_server(port=0)` with automatic token refresh via `google.auth.transport.requests.Request`.
+* [ ] **`storage.py`**: Secure token persistence in `~/.config/nutrilog/tokens.json` with strict `0600` permissions.
+* [ ] **`models.py`**: Define `MealLog`, `NutrientEntry`, and `MacroSummary` dataclasses.
+* [ ] **`parser.py`**: Implement regex parser for shorthand macro strings (e.g. `35p 600k 20f 40c`).
+* [ ] **`client.py`**: Build resilient `GoogleHealthClient` handling retry logic, ISO timestamp formatting, and payload serialization.
+
+### Step 3: CLI Interface & Rich Terminal UI
+* [ ] Build Typer CLI commands in `cli.py` (`login`, `log`, `today`, `history`, `config`).
+* [ ] Format terminal tables and progress bars using `rich`.
+
+### Step 4: Verification & Integration Testing
+* [ ] Run end-to-end integration test: log a test meal from terminal.
+* [ ] Open **Google Health App on phone / Pixel Watch / Fitbit** and confirm live synchronization.
+* [ ] Verify accurate calorie rollup and macronutrient calculation on mobile dashboard.
+
+### Step 5: Packaging & Open-Source Distribution
+* [ ] Configure `pyproject.toml` with entry point `nutrilog = "nutrilog.cli:app"`.
+* [ ] Author comprehensive `README.md` with GCP setup walkthrough and visual examples.
+* [ ] Publish package to PyPI (`pip install nutrilog`).