mela-cli 1.0.0__tar.gz

mela_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

mela_cli-1.0.0/PKG-INFO

@@ -0,0 +1,359 @@
+Metadata-Version: 2.4
+Name: mela-cli
+Version: 1.0.0
+Summary: Read-only CLI for browsing and exporting recipes from the Mela macOS app
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Mela CLI
+
+`mela` is a read-only macOS CLI for browsing and exporting recipes from the local Mela app catalog.
+
+It reads Mela's local Core Data SQLite store directly and never writes to the live database.
+
+## About Mela
+
+[Mela](https://mela.recipes/) is a recipe manager for iOS and macOS with iCloud sync. The
+official app supports collecting recipes from the web, feeds, and scans, then using them in
+cook mode, meal planning, and groceries workflows. See the official
+[Help](https://mela.recipes/help/) and [File Format Documentation](https://mela.recipes/fileformat/index.html)
+for product details and the `melarecipe` / `melarecipes` formats.
+
+## Project Relationship
+
+`mela` is an unofficial companion CLI for people who want shell access to their local Mela
+catalog. It is not the Mela app itself and it does not use an official Mela API.
+
+## Why Read-only
+
+Mela stores its live catalog in a local Core Data SQLite store inside its macOS app-group
+container, and syncing is handled through CloudKit-backed Core Data state rather than simple
+document files.
+
+That makes read access practical, but direct writes are risky:
+
+- raw SQLite writes would bypass the Core Data and CloudKit bookkeeping that Mela expects
+- the live store includes sync/history metadata in addition to recipe content
+- there is no documented public API for in-place catalog edits
+
+`mela` therefore treats the local store as read-only. It is designed to be safe for browsing,
+searching, diagnostics, and export. When you need a writable format, use `--format melarecipe`
+or `export-all` to generate importable files rather than mutating the live database.
+
+## Status
+
+- Platform: macOS only
+- Python: 3.11+
+- Scope: read-only
+- Primary install path: `pipx install mela-cli`
+
+## What It Does
+
+- Lists and searches recipes in your local Mela catalog as table, JSON, or CSV summaries
+- Shows individual recipes in terminal-friendly text, Markdown, or JSON
+- Exports recipes as `.melarecipe`, JSON, or Markdown
+- Reports tags, catalog stats, and discovery/runtime diagnostics
+
+## What It Does Not Do
+
+- It does not write to Mela's live SQLite database
+- It does not provide a supported import/write workflow yet
+- It does not target non-macOS platforms
+
+## Installation
+
+Recommended:
+
+```bash
+pipx install mela-cli
+```
+
+Development install:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Discovery
+
+By default, `mela` tries to discover the official installed Mela app and derive the live catalog paths from the app's bundle metadata and group container layout.
+
+Discovery precedence:
+
+1. CLI flags
+2. Environment variables
+3. Auto-discovery
+
+Supported overrides:
+
+- `--app-path`
+- `--db-path`
+- `--support-dir`
+- `--compression-tool`
+
+Environment variables:
+
+- `MELA_APP_PATH`
+- `MELA_DB_PATH`
+- `MELA_SUPPORT_DIR`
+- `MELA_COMPRESSION_TOOL`
+
+Use `mela doctor` to inspect what was discovered.
+
+## Commands
+
+```bash
+mela list [-q QUERY] [-f] [-w] [-t TAG] [-n N] [--format table|json|csv]
+mela search QUERY [-f] [-w] [-t TAG] [-n N] [--format table|json|csv]  # alias for list --query
+mela show SELECTOR [--format text|markdown|json]
+mela export SELECTOR [--format melarecipe|json|markdown] [-o DIR] [--filename-style slug|id|id-slug] [--compact]
+mela export-all [-q QUERY] [-f] [-w] [-t TAG] [-n N] [--format melarecipe|json|markdown] [-o DIR] [--filename-style slug|id|id-slug] [--compact]
+mela tags [--format table|json]
+mela stats [--format table|json]
+mela doctor [--format table|json]
+```
+
+Selector resolution order for single-recipe commands:
+
+1. Numeric primary key
+2. Exact Mela record ID
+3. Exact title
+4. Unique record-ID prefix
+5. Unique title fragment
+
+Ambiguous matches fail with a clear error and suggested PKs.
+
+## Option Reference
+
+Global options available before any subcommand:
+
+- `--app-path`: override auto-discovery and point directly at `Mela.app`
+- `--db-path`: use a specific `Curcuma.sqlite` file
+- `--support-dir`: use a specific Core Data external blob directory
+- `--compression-tool`: use a specific `compression_tool` path or command name
+
+`list` options (`search` is an alias that takes the query as a positional argument):
+
+- `-q`/`--query QUERY`: case-insensitive text search across recipe content
+- `-f`/`--favorite`: only include favorite recipes
+- `-w`/`--want-to-cook`: only include recipes marked want-to-cook
+- `-t`/`--tag TAG`: filter by tag; repeat the flag to require multiple tags
+- `-n`/`--limit N`: cap the number of returned recipes
+- `--format table|json|csv`: choose human-readable table output or machine-readable JSON/CSV
+
+`show` options:
+
+- `SELECTOR`: recipe PK, exact record ID, exact title, unique record-ID prefix, or unique title fragment
+- `--format text|markdown|json`: choose terminal text, Markdown, or full recipe JSON
+
+`export` options:
+
+- `SELECTOR`: same selector rules as `show`
+- `--format melarecipe|json|markdown`: choose Mela import JSON, full recipe JSON, or Markdown
+- `-o`/`--output DIR`: directory to write the exported file (default: current directory)
+- `--filename-style slug|id|id-slug`: filename style — title-based slug (default), record UUID, or UUID + slug
+- `--compact`: minify JSON output for `melarecipe` and `json` exports; ignored for `markdown`
+
+`export-all` options:
+
+- `-q`/`--query QUERY`: full-text filter across recipe content
+- `-f`/`--favorite`, `-w`/`--want-to-cook`, `-t`/`--tag TAG`, `-n`/`--limit N`: same filtering as `list`
+- `--format melarecipe|json|markdown`: output format for each exported recipe
+- `-o`/`--output DIR`: destination directory for bulk exports (default: current directory)
+- `--filename-style slug|id|id-slug`: filename style — title-based slug (default), record UUID, or UUID + slug
+- `--compact`: minify JSON output for `melarecipe` and `json` exports; ignored for `markdown`
+
+`tags`, `stats`, and `doctor` options:
+
+- `--format table|json`: choose human-readable table output or machine-readable JSON
+
+## Examples
+
+List favorite recipes:
+
+```bash
+mela list --favorite
+```
+
+Search for soup recipes as JSON:
+
+```bash
+mela list -q soup --format json
+```
+
+Export the current summary catalog as CSV:
+
+```bash
+mela list --format csv
+```
+
+Show one recipe in Markdown:
+
+```bash
+mela show 42 --format markdown
+```
+
+Export one recipe as a Mela import file to the current directory:
+
+```bash
+mela export "Instant Pot Chicken Adobo"
+```
+
+Export one recipe to a specific directory, named by record ID:
+
+```bash
+mela export "Instant Pot Chicken Adobo" --output ./exports --filename-style id
+```
+
+Export minified JSON and inspect it:
+
+```bash
+mela export 42 --format json --compact | jq .
+```
+
+Export matching recipes to a directory:
+
+```bash
+mela export-all --tag Dessert --output ./desserts
+```
+
+Inspect runtime discovery:
+
+```bash
+mela doctor
+```
+
+## Machine-readable Output
+
+JSON is the stable machine-readable interface for v1. CSV is the stable summary export
+format for `list` (and its `search` alias).
+
+- `list` returns an array of recipe summaries
+- `show` returns a full recipe object
+- `tags` returns an array of tag/count objects
+- `stats` returns a fixed stats object
+- `doctor` returns a structured discovery report
+
+Human-readable table/text/Markdown output may evolve.
+
+Summary fields for `list --format json` and `list --format csv`:
+
+- `pk`
+- `id`
+- `title`
+- `tags`
+- `favorite`
+- `wantToCook`
+- `link`
+- `createdAt`
+- `prepTime`
+- `cookTime`
+- `totalTime`
+- `yield`
+- `imageCount`
+
+CSV conventions:
+
+- fixed header order matching the field list above
+- `tags` serialized as a semicolon-delimited string
+- booleans serialized as `true` / `false`
+- missing values serialized as empty fields
+- `imageCount` serialized as an integer
+
+`tags --format json` returns:
+
+```json
+[
+  {"tag": "Breakfast", "count": 12}
+]
+```
+
+`stats --format json` returns:
+
+```json
+{
+  "recipes": 204,
+  "favorites": 10,
+  "wantToCook": 3,
+  "tags": 37,
+  "recipesWithImages": 166,
+  "recipesWithLinks": 170
+}
+```
+
+Export format differences:
+
+- `--format json` uses the full Mela CLI recipe schema. It includes fields like `pk`,
+  `createdAt`, and structured image objects with metadata plus base64 payloads.
+- `--format melarecipe` uses a Mela import-oriented schema. It omits CLI-only fields
+  like `pk` and `createdAt`, omits empty optional fields, and serializes `images` as
+  an array of base64 strings.
+- Both are JSON-encoded. Use `json` for automation against the CLI contract and
+  `melarecipe` when you want a file that Mela can import.
+
+`doctor --format json` returns:
+
+```json
+{
+  "ok": true,
+  "supportedPlatform": true,
+  "bundleId": "recipes.mela.appkit",
+  "applicationGroup": "TEAMID.recipes.mela",
+  "appPath": "/Applications/Mela.app",
+  "appPathSource": "auto-discovery",
+  "appExists": true,
+  "dbPath": "/Users/example/Library/Group Containers/TEAMID.recipes.mela/Data/Curcuma.sqlite",
+  "dbPathSource": "derived from app entitlement",
+  "dbExists": true,
+  "supportDir": "/Users/example/Library/Group Containers/TEAMID.recipes.mela/Data/.Curcuma_SUPPORT/_EXTERNAL_DATA",
+  "supportDirSource": "derived from app entitlement",
+  "supportDirExists": true,
+  "compressionTool": "compression_tool",
+  "compressionToolSource": "default",
+  "compressionToolResolvedPath": "/usr/bin/compression_tool",
+  "compressionToolAvailable": true,
+  "canReadCatalog": true,
+  "canDecodeExternalImages": true,
+  "recipeCount": 204,
+  "warnings": []
+}
+```
+
+`doctor` fields are intended for diagnostics and environment inspection. `ok` means the CLI
+can read the catalog and decode external image blobs with the currently discovered runtime.
+
+## Troubleshooting
+
+If discovery does not find your Mela install or live catalog:
+
+```bash
+mela doctor
+```
+
+If needed, override the paths explicitly:
+
+```bash
+mela --db-path "/path/to/Curcuma.sqlite" --support-dir "/path/to/_EXTERNAL_DATA" list
+```
+
+## Implementation Notes
+
+- The CLI is based on Mela's current local macOS schema and storage layout.
+- Image extraction supports:
+  - inline blobs
+  - raw Core Data external blobs
+  - LZFSE-compressed keyed-archive external blobs via macOS `compression_tool`
+- `.melarecipe` output is produced from reverse-engineered local data rather than an official Mela API.