mod8-cli 0.2.0

package/specs/behavior/bare-name-routing.yaml

@@ -0,0 +1,223 @@
+name: behavior — bare name & greeting routing
+description: |
+  Pins the fix for "user names a provider but mod8 only lectures" — the
+  intent router now catches:
+    - bare provider name        ("codex")
+    - first word + remainder    ("codex tell me a joke")
+    - greeting + name           ("hi codex", "hey gpt how are you")
+  …all locally, before the host LLM gets a chance to lecture.
+
+  Strict resolution (id or configured display-name only) for bare/first-word
+  prevents false positives like "haiku" or "claude alone is great".  Greeting
+  matching is more permissive because the greeting itself signals intent.
+
+tests:
+  # --- bare name ---
+
+  - name: 'bare "codex" (configured display name) routes to openai'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {
+              "apiKey": "sk-fake",
+              "apiType": "openai-compat",
+              "name": "codex",
+              "baseUrl": "https://api.openai.com/v1",
+              "defaultModel": "gpt-4o",
+              "color": "#10B981"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'mod8 dev:resolve "codex"'
+    expect:
+      stdout_contains: "route id=codex resolved=openai"
+
+  - name: 'bare "Codex" (capitalized) is case-insensitive'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {
+              "apiKey": "sk-fake",
+              "apiType": "openai-compat",
+              "name": "codex",
+              "baseUrl": "https://api.openai.com/v1",
+              "defaultModel": "gpt-4o",
+              "color": "#10B981"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'mod8 dev:resolve "Codex"'
+    expect:
+      stdout_contains: "route id=codex resolved=openai"
+
+  - name: 'bare built-in id "deepseek" routes (even when not configured)'
+    shell: 'mod8 dev:resolve "deepseek"'
+    expect:
+      stdout_contains: "route id=deepseek resolved=deepseek"
+
+  # --- first-word + rest ---
+
+  - name: '"codex tell me a joke" routes + carries rest="tell me a joke"'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {
+              "apiKey": "sk-fake",
+              "apiType": "openai-compat",
+              "name": "codex",
+              "baseUrl": "https://api.openai.com/v1",
+              "defaultModel": "gpt-4o",
+              "color": "#10B981"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'mod8 dev:resolve "codex tell me a joke"'
+    expect:
+      stdout_contains: "route id=codex resolved=openai"
+      stdout_matches: 'rest="tell me a joke"'
+
+  - name: '"codex codex" switches once, sends "codex" as rest (no double-route)'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {
+              "apiKey": "sk-fake",
+              "apiType": "openai-compat",
+              "name": "codex",
+              "baseUrl": "https://api.openai.com/v1",
+              "defaultModel": "gpt-4o",
+              "color": "#10B981"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'mod8 dev:resolve "codex codex"'
+    expect:
+      stdout_contains: "route id=codex resolved=openai"
+      stdout_matches: 'rest="codex"'
+
+  # --- greeting + name (full resolution including synonyms) ---
+
+  - name: '"hi codex" routes + forwards "hi" as the first message'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {
+              "apiKey": "sk-fake",
+              "apiType": "openai-compat",
+              "name": "codex",
+              "baseUrl": "https://api.openai.com/v1",
+              "defaultModel": "gpt-4o",
+              "color": "#10B981"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'mod8 dev:resolve "hi codex"'
+    expect:
+      stdout_contains: "route id=codex resolved=openai"
+      stdout_matches: 'rest="hi"'
+
+  - name: '"hey codex how are you" routes + forwards "hey how are you"'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {
+              "apiKey": "sk-fake",
+              "apiType": "openai-compat",
+              "name": "codex",
+              "baseUrl": "https://api.openai.com/v1",
+              "defaultModel": "gpt-4o",
+              "color": "#10B981"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'mod8 dev:resolve "hey codex how are you"'
+    expect:
+      stdout_contains: "route id=codex resolved=openai"
+      stdout_matches: 'rest="hey how are you"'
+
+  - name: '"yo gpt" routes via greeting + synonym (gpt → openai)'
+    shell: 'mod8 dev:resolve "yo gpt"'
+    expect:
+      stdout_contains: "route id=gpt resolved=openai"
+      stdout_matches: 'rest="yo"'
+
+  - name: '"hello claude" routes via greeting + synonym (claude → anthropic)'
+    shell: 'mod8 dev:resolve "hello claude"'
+    expect:
+      stdout_contains: "route id=claude resolved=anthropic"
+
+  # --- false-positive avoidance ---
+
+  - name: 'bare "haiku" does NOT route (synonym, but bare-mode is strict)'
+    shell: 'mod8 dev:resolve "haiku"'
+    expect:
+      stdout_contains: "none"
+
+  - name: 'bare "claude" routes to anthropic (high-confidence brand alias)'
+    shell: 'mod8 dev:resolve "claude"'
+    expect:
+      stdout_contains: "route id=claude resolved=anthropic"
+
+  - name: 'bare "gpt" routes to openai (high-confidence brand alias)'
+    shell: 'mod8 dev:resolve "gpt"'
+    expect:
+      stdout_contains: "route id=gpt resolved=openai"
+
+  - name: 'bare "grok" routes to xai (high-confidence brand alias)'
+    shell: 'mod8 dev:resolve "grok"'
+    expect:
+      stdout_contains: "route id=grok resolved=xai"
+
+  - name: '"claude please" routes + carries rest="please"'
+    shell: 'mod8 dev:resolve "claude please"'
+    expect:
+      stdout_contains: "route id=claude resolved=anthropic"
+      stdout_matches: 'rest="please"'
+
+  - name: '"gpt help me with this" routes + carries rest'
+    shell: 'mod8 dev:resolve "gpt help me with this"'
+    expect:
+      stdout_contains: "route id=gpt resolved=openai"
+      stdout_matches: 'rest="help me with this"'
+
+  - name: '"hello world" does NOT route ("world" is not a provider)'
+    shell: 'mod8 dev:resolve "hello world"'
+    expect:
+      stdout_contains: "none"
+
+  - name: '"hi there" does NOT route ("there" is not a provider)'
+    shell: 'mod8 dev:resolve "hi there"'
+    expect:
+      stdout_contains: "none"
+
+  - name: 'multi-word non-route message stays plain ("write me a haiku")'
+    shell: 'mod8 dev:resolve "write me a haiku"'
+    expect:
+      stdout_contains: "none"
+
+  # --- priority: host-back still wins over bare-name ---
+
+  - name: 'bare "mod8" goes to host-back, not provider routing'
+    shell: 'mod8 dev:resolve "mod8"'
+    expect:
+      stdout_contains: "host-back"
+      stdout_omits:
+        - "route id="

package/specs/behavior/bare-paste-confirm.yaml

@@ -0,0 +1,125 @@
+name: behavior — bare-paste auto-detect (no consent first)
+description: |
+  When the user pastes a recognizable API key into chat WITHOUT first saying
+  "add a key", mod8 should NOT pass the message to the host LLM (which then
+  lectures about `mod8 keys set <id>`).  Instead:
+
+    1. Detect the key locally (sk-ant-/sk-or-/AIza/etc.).
+    2. Mask it for display.
+    3. Cache the raw key in memory only (NEVER session JSON).
+    4. Ask "Save it as `<id>`? (yes / no)".
+    5. Affirmative → save to providers.json, confirm.
+       Negative → discard, acknowledge.
+       Anything else → discard, fall through to normal dispatch (no trap).
+
+  Specs cover the happy path, the broadened paste-key intent regex (which
+  now accepts "this/that/these/those/it/them" as articles and the bare-
+  pronoun forms "save this", "use it", etc.), and the cancellation paths.
+
+tests:
+  - name: 'bare paste of anthropic key → asks "save as anthropic?"'
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      sk-ant-api03-FAKE-TEST-AAAAAAAAAAAAAAAAAAAAAAAA
+      yes
+      INPUTS
+      echo "---providers.json---"
+      cat $MOD8_CONFIG_DIR/providers.json
+    expect:
+      stdout_contains:
+        # Step 1: bare paste detected, key masked in stdout, pending state armed.
+        - 'step=1 input="sk-ant-…AAAA" mode=host provider=host action=paste-pending id=anthropic'
+        # Step 2: user confirms with "yes" → key is saved.
+        - 'step=2 input="yes" mode=host provider=host action=paste-saved id=anthropic'
+        # And the full key DOES land in providers.json.
+        - '"apiKey": "sk-ant-api03-FAKE-TEST-AAAAAAAAAAAAAAAAAAAAAAAA"'
+      stdout_omits:
+        # The raw key must never appear in stdout (only providers.json).
+        - 'step=1 input="sk-ant-api03-FAKE'
+
+  - name: '"save it" / "save this" / "use it" all trigger save in pendingKey state'
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      sk-ant-api03-FAKE-KEY-1-AAAAAAAAAAAAAAAAAAAA
+      save it
+      INPUTS
+      echo "---providers.json---"
+      cat $MOD8_CONFIG_DIR/providers.json
+    expect:
+      stdout_contains:
+        - 'step=1 input="sk-ant-…AAAA" mode=host provider=host action=paste-pending id=anthropic'
+        - 'step=2 input="save it" mode=host provider=host action=paste-saved id=anthropic'
+        - '"apiKey": "sk-ant-api03-FAKE-KEY-1-AAAAAAAAAAAAAAAAAAAA"'
+
+  - name: 'broadened intent — "add this key!" triggers consent (was rejected before)'
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      add this key!
+      INPUTS
+    expect:
+      stdout_contains:
+        - 'step=1 input="add this key!" mode=host provider=host action=paste-consent'
+
+  - name: '"no" cancels the bare paste and discards the key'
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      AIzaSyFAKE-TEST-NOT-REAL-AAAAAAAAAAAAAAAAAAAAAA
+      no
+      INPUTS
+      echo "---providers.json---"
+      cat $MOD8_CONFIG_DIR/providers.json 2>/dev/null || echo "no providers.json"
+    expect:
+      stdout_contains:
+        - 'step=1 input="AIzaSy…AAAA" mode=host provider=host action=paste-pending id=google'
+        - 'step=2 input="no" mode=host provider=host action=paste-cancelled'
+        - 'no providers.json'
+
+  - name: 'unrelated input cancels paste and falls through (no trap)'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "openai": {"apiKey":"x","apiType":"openai-compat","name":"codex","baseUrl":"https://api.openai.com/v1","defaultModel":"gpt-4o","color":"#10B981"}
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      sk-ant-api03-FAKE-2-AAAAAAAAAAAAAAAAAAAAAAAAAAAA
+      use codex
+      INPUTS
+    expect:
+      stdout_contains:
+        - 'step=1 input="sk-ant-…AAAA" mode=host provider=host action=paste-pending id=anthropic'
+        # "use codex" is NOT an affirmative → cancel + fall through to normal
+        # routing (which switches to codex).
+        - 'step=2 input="use codex" mode=work provider=openai action=route'
+
+  - name: 'broadened article list — "let me add this anthropic key" triggers consent'
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      let me add this anthropic key
+      INPUTS
+    expect:
+      stdout_contains:
+        - 'step=1 input="let me add this anthropic key" mode=host provider=host action=paste-consent'
+
+  - name: 'multiple bare pastes back-to-back each get saved'
+    shell: |
+      mod8 dev:simulate <<'INPUTS'
+      sk-ant-api03-CLAUDE-FAKE-AAAAAAAAAAAAAAAAAAAAAAAA
+      yes
+      AIzaSyFAKE-TEST-NOT-REAL-AAAAAAAAAAAAAAAAAAAAAA
+      save it
+      INPUTS
+      echo "---providers.json---"
+      cat $MOD8_CONFIG_DIR/providers.json
+    expect:
+      stdout_contains:
+        - 'step=1 input="sk-ant-…AAAA" mode=host provider=host action=paste-pending id=anthropic'
+        - 'step=2 input="yes" mode=host provider=host action=paste-saved id=anthropic'
+        - 'step=3 input="AIzaSy…AAAA" mode=host provider=host action=paste-pending id=google'
+        - 'step=4 input="save it" mode=host provider=host action=paste-saved id=google'
+        - '"apiKey": "sk-ant-api03-CLAUDE-FAKE-AAAAAAAAAAAAAAAAAAAAAAAA"'
+        - '"apiKey": "AIzaSyFAKE-TEST-NOT-REAL-AAAAAAAAAAAAAAAAAAAAAA"'

package/specs/behavior/env-var-respected.yaml

@@ -0,0 +1,108 @@
+name: behavior — MOD8_<ID>_MODEL env var is respected
+description: |
+  Bug: the env var advertised in the "model not available" error message
+  was silently ignored.  The dead code in src/providers/google.ts honored
+  MOD8_GOOGLE_MODEL but no one imports it; the live path in generic.ts
+  used `opts.model ?? entry.defaultModel` and never read the env.
+
+  Fix: every provider call goes through `resolveModel()` which checks
+  opts.model → MOD8_<ID>_MODEL → providers.json defaultModel.  These specs
+  prove the env var beats the providers.json default (no allowlist is
+  consulted along the way; whatever string the env sets is what the SDK
+  receives).
+
+tests:
+  - name: 'MOD8_GOOGLE_MODEL beats providers.json default'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "google": {
+              "apiKey": "x",
+              "apiType": "gemini",
+              "name": "Google (Gemini)",
+              "defaultModel": "gemini-2.0-flash",
+              "color": "#06B6D4"
+            }
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'MOD8_GOOGLE_MODEL=gemini-2.5-flash mod8 dev:resolve-model google'
+    expect:
+      stdout_contains:
+        - 'model="gemini-2.5-flash"'
+        - 'source=env'
+        - 'envVar=MOD8_GOOGLE_MODEL'
+
+  - name: 'env var passes through unchanged — even an arbitrary string'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "google": {"apiKey":"x","apiType":"gemini","name":"Google (Gemini)","defaultModel":"x","color":"#06B6D4"}
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'MOD8_GOOGLE_MODEL=this-could-be-any-string-mod8-does-not-allowlist mod8 dev:resolve-model google'
+    expect:
+      stdout_contains:
+        - 'model="this-could-be-any-string-mod8-does-not-allowlist"'
+        - 'source=env'
+
+  - name: 'env var name is built from id — works for non-google providers'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "anthropic": {"apiKey":"x","apiType":"anthropic","name":"Anthropic","defaultModel":"claude-sonnet-4-6","color":"#A78BFA"}
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'MOD8_ANTHROPIC_MODEL=claude-opus-4-7 mod8 dev:resolve-model anthropic'
+    expect:
+      stdout_contains:
+        - 'model="claude-opus-4-7"'
+        - 'source=env'
+        - 'envVar=MOD8_ANTHROPIC_MODEL'
+
+  - name: 'empty env var is ignored, falls through to providers.json'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "google": {"apiKey":"x","apiType":"gemini","name":"Google (Gemini)","defaultModel":"gemini-2.0-flash","color":"#06B6D4"}
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    shell: 'MOD8_GOOGLE_MODEL= mod8 dev:resolve-model google'
+    expect:
+      stdout_contains:
+        - 'model="gemini-2.0-flash"'
+        - 'source=providers.json'
+
+  - name: 'env-resolved model lands in the SDK URL the provider is about to hit'
+    setup:
+      - shell: |
+          mkdir -p $MOD8_CONFIG_DIR
+          cat > $MOD8_CONFIG_DIR/providers.json <<JSON
+          {
+            "google": {"apiKey":"AIzaSy-FAKE-NOT-REAL-AAAAAAAAAAAAAAAAAAAAAAA","apiType":"gemini","name":"Google (Gemini)","defaultModel":"gemini-2.0-flash","color":"#06B6D4"}
+          }
+          JSON
+          chmod 600 $MOD8_CONFIG_DIR/providers.json
+    # No network — dev:debug-call runs the same resolution + URL builder as
+    # the actual provider call path.  The URL we print here is identical
+    # to what the SDK will request.
+    shell: 'MOD8_GOOGLE_MODEL=gemini-2.5-flash mod8 dev:debug-call google'
+    expect:
+      stdout_contains:
+        - 'providerId=google'
+        - 'model="gemini-2.5-flash"'
+        - 'modelSource=env'
+        - 'models/gemini-2.5-flash:streamGenerateContent'
+        # API key is masked — never the raw value.
+        - 'key=AIzaSy…AAAA'

package/specs/behavior/error-fidelity.yaml

@@ -0,0 +1,92 @@
+name: behavior — provider error message fidelity (verbatim quote)
+description: |
+  Bug: when a provider returned a specific error, mod8 dropped the message
+  and printed something generic ("model not available — set MOD8_..." for
+  what was actually a 400 / API_KEY_INVALID; "free-tier quota / billing"
+  for what was actually a 403 project block).
+
+  Fix: every error preserves the provider's raw human-readable message in
+  the short summary, with prefix noise (`[GoogleGenerativeAI Error]:`,
+  `Error fetching from <url>:`, structured-detail JSON tail) stripped.
+  The user can copy the quoted message and search for it.
+
+  These specs feed synthetic SDK-shape errors through dev:explain-error
+  and assert the verbatim quote survives + the diagnosis matches reality.
+
+tests:
+  - name: 'Google "no longer available" model error → kind=model + verbatim quote'
+    shell: |
+      mod8 dev:explain-error google "[GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-pro-vision:generateContent: [404 Not Found] The model gemini-pro-vision is no longer available."
+    expect:
+      stdout_contains:
+        - 'kind=model'
+        - 'no longer available'
+        # The quoted raw text — survives extractRawMessage and stays
+        # search-friendly.  Must NOT include the SDK wrapper prefix.
+        - "'The model gemini-pro-vision is no longer available.'"
+      stdout_omits:
+        - 'rate limited'
+        - 'set MOD8_GOOGLE_MODEL'
+        - 'GoogleGenerativeAI Error'
+
+  - name: 'Google "API key not valid" → kind=auth (NOT kind=model)'
+    # The exact misclassification the user reported: URL contains "models/<name>"
+    # AND message contains "valid", and the old `model.*invalid` regex matched.
+    shell: |
+      mod8 dev:explain-error google "[GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent: [400 Bad Request] API key not valid. Please pass a valid API key."
+    expect:
+      stdout_contains:
+        - 'kind=auth'
+        - "'API key not valid. Please pass a valid API key.'"
+      stdout_omits:
+        - 'kind=model'
+        - 'set MOD8_GOOGLE_MODEL'
+
+  - name: '403 project denied → kind=forbidden + verbatim quote (no fake billing diagnosis)'
+    shell: |
+      mod8 dev:explain-error google "[403 Forbidden] Your project has been denied access. Please contact support."
+    expect:
+      stdout_contains:
+        - 'kind=forbidden'
+        - "'Your project has been denied access. Please contact support.'"
+      stdout_omits:
+        - 'kind=no-credit'
+        - 'free-tier quota'
+        - 'Top up at'
+
+  - name: '429 with retry-after preserves the delay AND quotes the raw message'
+    shell: |
+      mod8 dev:explain-error anthropic "rate_limit_exceeded: please retry after 30 seconds"
+    expect:
+      stdout_contains:
+        - 'kind=rate-limit'
+        - 'retry in 30s'
+        - "'rate_limit_exceeded: please retry after 30 seconds'"
+
+  - name: 'unknown shape → kind=other, raw preserved (no fabricated diagnosis)'
+    shell: |
+      mod8 dev:explain-error openai "Some completely surprising message we have not seen before"
+    expect:
+      stdout_contains:
+        - 'kind=other'
+        - 'Some completely surprising message we have not seen before'
+      stdout_omits:
+        - 'kind=auth'
+        - 'kind=forbidden'
+        - 'kind=rate-limit'
+        - 'kind=model'
+
+  - name: 'extractRawMessage strips Google SDK wrapper prefix'
+    # Specifically: "[GoogleGenerativeAI Error]: Error fetching from <url>: "
+    # must be removed so the user sees just the meaningful summary.
+    shell: |
+      mod8 dev:explain-error google "[GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent: [400 Bad Request] API key not valid. Please pass a valid API key. [{\"@type\":\"type.googleapis.com/google.rpc.ErrorInfo\",\"reason\":\"API_KEY_INVALID\"}]"
+    expect:
+      stdout_contains:
+        - "'API key not valid. Please pass a valid API key.'"
+      stdout_omits:
+        # The wrapper noise must NOT survive into the user-facing quote.
+        - 'GoogleGenerativeAI Error'
+        - 'Error fetching from'
+        - '@type'
+        - 'type.googleapis.com/google.rpc.ErrorInfo'