minima-cli 0.4.9__tar.gz → 0.5.0__tar.gz

{minima_cli-0.4.9 → minima_cli-0.5.0}/.github/workflows/prod.yml

@@ -156,3 +156,36 @@ jobs:
             --region ${{ env.REGION }} \
             --format 'value(status.url)')
           echo "::notice::Minima docs (prod) deployed to: $URL"
+
+  # ── 3. Publish minima-cli to PyPI ────────────────────────────────────────────
+  # Builds the sdist+wheel at the release tag and uploads to PyPI (the dist bundles the
+  # `minima_client` SDK). --skip-existing makes a manual re-deploy of an already-published
+  # version a no-op instead of an error. Needs no GCP — only the PYPI_API_TOKEN secret.
+  publish-pypi:
+    name: Publish → PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout @ release tag
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+
+      - name: Check metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload --skip-existing dist/*

minima_cli-0.5.0/.github/workflows/release-cli.yml

@@ -0,0 +1,140 @@
+name: Release — CLI binaries + Homebrew
+
+# On a published release, cross-compile the TypeScript/Bun CLI for macOS + Linux,
+# ad-hoc codesign the macOS arches, attach the tarballs to the release, and open
+# a PR to the Homebrew tap (mubit-ai/homebrew-minima) bumping the binary formula.
+# PyPI publishing of the Python `minima-cli` (SDK + server tooling) stays in prod.yml.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Git tag to build (e.g. v0.5.0)"
+        required: true
+        type: string
+
+concurrency:
+  group: release-cli
+  cancel-in-progress: false
+
+env:
+  RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+  BUN_VERSION: "1.3.14"
+
+permissions:
+  contents: write # upload release assets
+
+jobs:
+  build-macos:
+    name: Build + sign macOS binaries
+    runs-on: macos-14 # Apple Silicon; cross-compiles darwin-x64 too, codesign is arch-agnostic
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - name: Install deps
+        working-directory: packages/tui
+        run: bun install --frozen-lockfile
+      - name: Cross-compile darwin arm64 + x64
+        working-directory: packages/tui
+        run: bun run scripts/build-all.ts bun-darwin-arm64 bun-darwin-x64
+      - name: Ad-hoc codesign (required for Apple Silicon to run the binary)
+        working-directory: packages/tui
+        run: |
+          for b in dist/minima-darwin-arm64 dist/minima-darwin-x64; do
+            codesign -s - --force --timestamp=none "$b"
+            codesign --verify --verbose=1 "$b"
+          done
+      - name: Package tarballs
+        working-directory: packages/tui
+        run: |
+          VER="${RELEASE_TAG#v}"
+          for slug in darwin-arm64 darwin-x64; do
+            tmp="$(mktemp -d)"; cp "dist/minima-$slug" "$tmp/minima"
+            tar -czf "dist/minima-$VER-$slug.tar.gz" -C "$tmp" minima
+          done
+      - uses: actions/upload-artifact@v4
+        with:
+          name: darwin
+          path: packages/tui/dist/minima-*.tar.gz
+
+  build-linux:
+    name: Build Linux binaries
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - name: Install deps
+        working-directory: packages/tui
+        run: bun install --frozen-lockfile
+      - name: Cross-compile linux x64 + arm64
+        working-directory: packages/tui
+        run: bun run scripts/build-all.ts bun-linux-x64 bun-linux-arm64
+      - name: Package tarballs
+        working-directory: packages/tui
+        run: |
+          VER="${RELEASE_TAG#v}"
+          for slug in linux-x64 linux-arm64; do
+            tmp="$(mktemp -d)"; cp "dist/minima-$slug" "$tmp/minima"
+            tar -czf "dist/minima-$VER-$slug.tar.gz" -C "$tmp" minima
+          done
+      - uses: actions/upload-artifact@v4
+        with:
+          name: linux
+          path: packages/tui/dist/minima-*.tar.gz
+
+  publish-and-bump:
+    name: Attach assets + open tap PR
+    needs: [build-macos, build-linux]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      - name: Collect tarballs
+        run: |
+          mkdir -p dist
+          find artifacts -name 'minima-*.tar.gz' -exec cp {} dist/ \;
+          ls -la dist
+      - name: Attach binaries to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$RELEASE_TAG" dist/minima-*.tar.gz --clobber --repo "${{ github.repository }}"
+      - name: Render binary formula
+        run: |
+          VER="${RELEASE_TAG#v}"
+          python3 packaging/homebrew/render_formula.py --version "$VER" --dist dist --out minima.rb
+          echo "----- rendered formula -----"; cat minima.rb
+      - name: Open Homebrew tap PR
+        env:
+          GH_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          VER="${RELEASE_TAG#v}"
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/mubit-ai/homebrew-minima.git" tap
+          cp minima.rb tap/Formula/minima.rb
+          cd tap
+          git config user.name "mubit-release-bot"
+          git config user.email "release-bot@mubit.ai"
+          branch="bump-minima-${VER}"
+          git checkout -b "$branch"
+          if git diff --quiet Formula/minima.rb; then
+            echo "formula already up to date for ${VER}; nothing to do"; exit 0
+          fi
+          git add Formula/minima.rb
+          git commit -m "minima ${VER} (prebuilt binary)"
+          git push -u origin "$branch" --force-with-lease
+          gh pr create --repo mubit-ai/homebrew-minima --base main --head "$branch" \
+            --title "minima ${VER}" \
+            --body "Automated bump to the prebuilt TypeScript/Bun binary for \`${RELEASE_TAG}\`. Replaces the Python virtualenv formula. \`brew test-bot\` validates install + \`test do\` on macOS + Linux before merge." \
+            || echo "PR already exists for ${branch}"

{minima_cli-0.4.9 → minima_cli-0.5.0}/.gitignore

@@ -21,3 +21,7 @@ docs-site/dist/
 
 # PLAN
 docs/PLAN/
+
+# Meta files
+.codaph 
+.claude

{minima_cli-0.4.9 → minima_cli-0.5.0}/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to Minima are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.4.10] - 2026-06-26
+
+### Changed
+- **`minima-cli` is now published to PyPI automatically on every release** — `pip install minima-cli`
+  is the official install (it bundles the `minima_client` SDK). A new CI job builds + uploads the
+  sdist/wheel alongside the GitHub release and prod deploy.
+
+### Fixed
+- **Docs (API reference):** corrected the `GET /v1/health` response example (it returns `mubit`
+  not `memory`, `version 0.4.9`, plus `auth`/`reasoner` blocks and `catalog.cost_source`) and
+  clarified `status` is only `degraded` on a key-bearing probe; documented the real
+  `summary.realized` field set (it differs from `summary.estimated`); and fixed the `days`
+  parameter bound (`>0–365`) on `/v1/savings` and `/v1/calibration`. Added a PyPI install link to
+  the Client SDK page.
+
 ## [0.4.9] - 2026-06-26
 
 ### Fixed

{minima_cli-0.4.9 → minima_cli-0.5.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install run test lint fmt live eval seed refresh-catalog harness-demo harness-live harness-test harness
+.PHONY: install run test lint fmt live eval seed refresh-catalog harness-demo harness-live harness-test harness tui-install tui-test tui-check tui-build tui tui-dev
 
 install:
 	uv sync --extra dev   # dev pulls server + harness + tui for the full test suite
@@ -39,3 +39,32 @@ harness-test:
 
 harness:
 	uv run --extra harness --extra tui --env-file .env.harness minima-harness $(ARGS)
+
+# --- TS TUI (packages/tui) — run from the repo root so .env.harness auto-loads --------
+
+TUI := packages/tui
+TUI_BIN := $(TUI)/dist/minima
+
+tui-install:
+	cd $(TUI) && bun install
+
+tui-test:
+	cd $(TUI) && bun test
+
+tui-check:
+	cd $(TUI) && bun run check && bun run lint
+
+tui-build:
+	cd $(TUI) && bun run build
+
+# Run the compiled binary (build first with `make tui-build`). Passes ARGS through, so:
+#   make tui ARGS='-p "hello"'          # one-shot
+#   make tui ARGS='--offline --model gpt-4o-mini -p "hi"'
+#   make tui                             # interactive TUI
+tui:
+	@test -x $(TUI_BIN) || { echo "Run 'make tui-build' first"; exit 1; }
+	./$(TUI_BIN) $(ARGS)
+
+# Run from source via Bun (no compile step) — fastest dev loop.
+tui-dev:
+	cd $(TUI) && bun run src/cli/main.ts $(ARGS)

{minima_cli-0.4.9 → minima_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.4.9
+Version: 0.5.0
 Summary: Minima CLI: cost-aware LLM model routing — recommend cheaper models, backed by Mubit memory.
 Project-URL: Homepage, https://docs.minima.sh
 Project-URL: Documentation, https://docs.minima.sh

{minima_cli-0.4.9 → minima_cli-0.5.0}/docs-site/src/content/docs/api-reference.mdx

@@ -310,7 +310,7 @@ Two baselines are always reported side by side, explicitly labeled: **`vs premiu
 | Param | Type | Default | Notes |
 |-------|------|---------|-------|
 | `namespace` | string | — | Restrict to one namespace. |
-| `days` | float `0–365` | `30` | Lookback window. |
+| `days` | float `>0–365` | `30` | Lookback window (must be greater than 0). |
 | `group_by` | enum | — | `cluster` \| `task_type` \| `lane` — optional breakdown. |
 
 ### Response
@@ -318,7 +318,7 @@ Two baselines are always reported side by side, explicitly labeled: **`vs premiu
 | Field | Type | Notes |
 |-------|------|-------|
 | `summary.estimated` | object | `n`, `cost_recommended_usd`, `cost_premium_usd`, `savings_vs_premium_usd`, plus `n_declared` / `cost_declared_usd` / `savings_vs_declared_usd` over the declared-baseline subset. |
-| `summary.realized` | object | Same shape over the **reconciled** subset (feedback received with `actual_cost_usd`), using your realized cost against the estimated baselines. |
+| `summary.realized` | object | A **different** field set over the **reconciled** subset (feedback received with `actual_cost_usd`): `n_reconciled`, `realized_cost_usd`, `est_cost_recommended_usd`, `est_cost_premium_usd`, `savings_vs_premium_est_usd`, plus `n_declared` / `est_cost_declared_usd` / `savings_vs_declared_est_usd` — your realized cost measured against the estimated baselines. |
 | `health` | object | `recommendations`, `feedback_coverage` (share of recommendations that ever got feedback — the number that decides how much to trust `realized`), `late_feedback_share`, `escalation_rate`, `exploration_share`, `epsilon_policy_share`. |
 | `groups` | array | Per-`group_by` key: the same `summary` + `health`. |
 
@@ -342,7 +342,7 @@ Is `predicted_success` telling the truth for your traffic? Compares each recomme
 | Param | Type | Default | Notes |
 |-------|------|---------|-------|
 | `namespace` | string | — | Restrict to one namespace. |
-| `days` | float `0–365` | `30` | Lookback window. |
+| `days` | float `>0–365` | `30` | Lookback window (must be greater than 0). |
 
 ### Response
 
@@ -366,10 +366,12 @@ Always returns `200`; reports degraded state in the body. The only endpoint that
 ```json
 {
   "status": "ok",
-  "memory": {"reachable": true, "latency_ms": 12},
-  "catalog": {"version": "…", "stale": false, "models": 42},
-  "version": "0.1.0"
+  "mubit": {"reachable": true, "latency_ms": 12, "endpoint": "https://api.mubit.ai", "org_id": "…"},
+  "auth": "passthrough",
+  "catalog": {"version": "…", "cost_source": "litellm", "stale": false, "models": 42},
+  "reasoner": {"provider": "gemini", "configured": true},
+  "version": "0.4.9"
 }
 ```
 
-`status` is `degraded` when the memory backend is unreachable. In that state `/recommend` still serves prior-only recommendations.
+An unauthenticated probe (no key) returns `"mubit": {"reachable": null, "scope": "unauthenticated"}` and `status: "ok"` — liveness only. `status` is `degraded` only when a **key-bearing** probe finds your memory backend unreachable (`mubit.reachable == false`); in that state `/recommend` still serves prior-only recommendations.

{minima_cli-0.4.9 → minima_cli-0.5.0}/docs-site/src/content/docs/client-sdk.mdx

@@ -9,6 +9,14 @@ import { Aside, Code } from '@astrojs/starlight/components';
 
 The `minima_client` package is the official thin, typed Python client for the hosted Minima API, plus an optional zero-code intake helper.
 
+## Install
+
+```bash
+pip install minima-cli
+```
+
+The SDK is published on PyPI as part of [**`minima-cli`**](https://pypi.org/project/minima-cli/) — one package that ships both the CLI agent and the `minima_client` SDK (also available via `brew install mubit-ai/minima/minima`). Import it as `minima_client`:
+
 ```python
 from minima_client import MinimaClient, AsyncMinimaClient, MinimaError, autocapture
 ```

minima_cli-0.5.0/maybe.js

@@ -0,0 +1,64 @@
+"use strict";
+class Maybe {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    static some(value) {
+        if (value === null || value === undefined) {
+            throw new Error("Cannot create 'some' with null or undefined");
+        }
+        return new Maybe(value);
+    }
+    static none() {
+        return new Maybe(null);
+    }
+    // Functor: map applies a function to the value if it exists
+    map(fn) {
+        if (this.value === null || this.value === undefined) {
+            return Maybe.none();
+        }
+        return Maybe.some(fn(this.value));
+    }
+    // Monad: flatMap applies a function that returns a Maybe, and flattens the result
+    flatMap(fn) {
+        if (this.value === null || this.value === undefined) {
+            return Maybe.none();
+        }
+        return fn(this.value);
+    }
+    get() {
+        return this.value;
+    }
+}
+// --- Functor Example (map) ---
+const maybeName = Maybe.some("Alice");
+const upperName = maybeName.map(name => name.toUpperCase());
+console.log("Functor (map) result:", upperName.get()); // ALICE
+const maybeEmpty = Maybe.none();
+const upperEmpty = maybeEmpty.map(name => name.toUpperCase());
+console.log("Functor (map) on empty result:", upperEmpty.get()); // null
+const users = {
+    1: { id: 1, name: "Bob", email: "bob@example.com" },
+    2: { id: 2, name: "Charlie" }
+};
+function findUserById(id) {
+    const user = users[id];
+    return user ? Maybe.some(user) : Maybe.none();
+}
+function getUserEmail(user) {
+    return user.email ? Maybe.some(user.email) : Maybe.none();
+}
+// Chaining with flatMap
+const user1Email = findUserById(1)
+    .flatMap(getUserEmail)
+    .map(email => `Email: ${email}`);
+console.log("Monad (flatMap) user 1 email:", user1Email.get()); // Email: bob@example.com
+const user2Email = findUserById(2)
+    .flatMap(getUserEmail)
+    .map(email => `Email: ${email}`);
+console.log("Monad (flatMap) user 2 email:", user2Email.get()); // null (because user 2 has no email)
+const user3Email = findUserById(3) // Non-existent user
+    .flatMap(getUserEmail)
+    .map(email => `Email: ${email}`);
+console.log("Monad (flatMap) user 3 email:", user3Email.get()); // null

minima_cli-0.5.0/maybe.ts

@@ -0,0 +1,84 @@
+
+type Mapper<T, U> = (value: T) => U;
+type MonadicMapper<T, U> = (value: T) => Maybe<U>;
+
+class Maybe<T> {
+    private constructor(private value: T | null | undefined) {}
+
+    static some<T>(value: T): Maybe<T> {
+        if (value === null || value === undefined) {
+            throw new Error("Cannot create 'some' with null or undefined");
+        }
+        return new Maybe(value);
+    }
+
+    static none<T>(): Maybe<T> {
+        return new Maybe<T>(null);
+    }
+
+    // Functor: map applies a function to the value if it exists
+    map<U>(fn: Mapper<T, U>): Maybe<U> {
+        if (this.value === null || this.value === undefined) {
+            return Maybe.none<U>();
+        }
+        return Maybe.some(fn(this.value));
+    }
+
+    // Monad: flatMap applies a function that returns a Maybe, and flattens the result
+    flatMap<U>(fn: MonadicMapper<T, U>): Maybe<U> {
+        if (this.value === null || this.value === undefined) {
+            return Maybe.none<U>();
+        }
+        return fn(this.value);
+    }
+
+    get(): T | null | undefined {
+        return this.value;
+    }
+}
+
+// --- Functor Example (map) ---
+const maybeName = Maybe.some("Alice");
+const upperName = maybeName.map(name => name.toUpperCase());
+console.log("Functor (map) result:", upperName.get()); // ALICE
+
+const maybeEmpty = Maybe.none<string>();
+const upperEmpty = maybeEmpty.map(name => name.toUpperCase());
+console.log("Functor (map) on empty result:", upperEmpty.get()); // null
+
+// --- Monad Example (flatMap) ---
+interface User {
+    id: number;
+    name: string;
+    email?: string;
+}
+
+const users: Record<number, User> = {
+    1: { id: 1, name: "Bob", email: "bob@example.com" },
+    2: { id: 2, name: "Charlie" }
+};
+
+function findUserById(id: number): Maybe<User> {
+    const user = users[id];
+    return user ? Maybe.some(user) : Maybe.none();
+}
+
+function getUserEmail(user: User): Maybe<string> {
+    return user.email ? Maybe.some(user.email) : Maybe.none();
+}
+
+// Chaining with flatMap
+const user1Email = findUserById(1)
+    .flatMap(getUserEmail)
+    .map(email => `Email: ${email}`);
+console.log("Monad (flatMap) user 1 email:", user1Email.get()); // Email: bob@example.com
+
+const user2Email = findUserById(2)
+    .flatMap(getUserEmail)
+    .map(email => `Email: ${email}`);
+console.log("Monad (flatMap) user 2 email:", user2Email.get()); // null (because user 2 has no email)
+
+const user3Email = findUserById(3) // Non-existent user
+    .flatMap(getUserEmail)
+    .map(email => `Email: ${email}`);
+console.log("Monad (flatMap) user 3 email:", user3Email.get()); // null

minima_cli-0.5.0/packages/tui/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

minima_cli-0.5.0/packages/tui/README.md

@@ -0,0 +1,73 @@
+# minima-tui
+
+The TypeScript/Ink harness + TUI for **Minima** — a cost-aware model-routing coding
+agent. This package is the runtime that lives in your terminal; it talks to the Python
+FastAPI recommender service (`src/minima/`) over the `/v1/*` HTTP contract and never
+proxies LLM calls itself.
+
+```
+recommend  ->  run the model yourself  ->  judge quality  ->  feedback
+```
+
+## What's here
+
+A faithful port of `src/minima_harness/` (Python) → TypeScript:
+
+- **`src/minima/`** — typed async client for the recommender service (every `/v1/*`
+  endpoint) + the integration layer (`config`, `mapping`, `meter`, `judge`, `router`,
+  `MinimaAgent` route→run→judge→feedback loop).
+- **`src/ai/`** — the LLM layer: types, streaming, provider registry, and three real
+  providers — `openai-compat` (raw `fetch` SSE), `anthropic` (`@anthropic-ai/sdk`),
+  `google` (`@google/genai`) — plus a hermetic `faux` provider for tests.
+- **`src/agent/`** — the agent core: PI event taxonomy, `agentLoop` (parallel tool
+  execution, before/afterToolCall hooks, max_turns, steering), and the `Agent` class.
+- **`src/tools/`** — `read`/`write`/`edit`/`bash`/`ls` + an `objectSchema` helper.
+- **`src/tui/`** — the Ink app (conversation + status bar + model picker) and the
+  credential store (OS keychain via `keytar`, else a 0600 file).
+- **`src/session/`** — append-only JSONL session tree + `SessionManager`.
+- **`src/cli/main.ts`** — the `minima` entry point (`--print`, `--mode json`, interactive
+  TUI, `minima config`).
+
+## Develop
+
+```bash
+cd packages/tui
+bun install
+bun test          # 75 hermetic tests
+bun run check     # tsc --noEmit
+bun run lint      # biome
+bun run build     # -> dist/minima (a self-contained native binary)
+./dist/minima --help
+```
+
+Tests are fully hermetic: the client injects a mock `fetch`, the faux provider scripts
+LLM replies, and the Minima integration runs the full loop against an in-process mock
+service — no network, no keys.
+
+## Use
+
+```bash
+# set credentials (keychain, else ~/.minima-harness/config.env at 0600)
+minima config set MUBIT_API_KEY ...
+minima config set OPENAI_API_KEY ...
+
+# one-shot
+minima -p "explain this repo"
+
+# event stream for scripts
+minima --mode json "refactor foo" | jq .
+
+# interactive TUI
+minima
+```
+
+Routing auth (`MUBIT_API_KEY`) + one provider key is enough to start. `--offline`
+bypasses the recommender; `--model`/`--provider` pin a model and skip routing.
+
+## Status
+
+Phases 0–7 complete: scaffold → client → AI layer (3 providers) → agent core → tools →
+Minima integration → Ink TUI + CLI → compiled native binary (`bun build --compile`).
+Remaining for full parity with the Python TUI: the rest of the overlays (session picker,
+diff-approval gating, themes, goals), mouse capture, and `keytar`-bundled keychain in the
+compiled binary (it falls back to the file store today).

minima_cli-0.5.0/packages/tui/biome.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
+  "organizeImports": { "enabled": true },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "useImportType": "error",
+        "useExportType": "error",
+        "noNonNullAssertion": "off"
+      },
+      "suspicious": { "noExplicitAny": "off", "noAssignInExpressions": "off" },
+      "performance": { "noDelete": "off" },
+      "correctness": { "noUnusedVariables": "warn" }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": { "formatter": { "quoteStyle": "double", "semicolons": "always" } }
+}