@moda-ai/cli 1.1.1 → 1.2.0

package/hooks/moda-snapshot.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Moda shadow workspace hook for coding agents.
+# Triggered by Claude Code, Codex, and Cursor lifecycle/tool matchers.
+#
+# Claude Code passes hook context as a JSON object on stdin (per the Claude
+# Code hooks reference): session_id, tool_use_id, prompt, hook_event_name,
+# etc. We forward that stdin straight through to `moda workspace snapshot
+# --hook-stdin`, which parses it server-side so the CLI sees the same
+# correlation keys (session_id, tool_use_id, prompt_sha) the ingest worker
+# will later join on. The previous version read $CLAUDE_SESSION_ID and
+# $CLAUDE_PROMPT_HASH env vars, but Claude never sets those — so session_id
+# and prompt-level joins were unrecoverable. Reading stdin fixes that.
+#
+# Runs `moda workspace snapshot` in the background so the hook never blocks
+# Claude; redirects all output to /dev/null so user-visible output stays
+# clean; always exits 0 so a transient failure can't break the user session.
+
+set +e
+case "${1:-}" in
+  claude|claude_code|codex|cursor)
+    PROVIDER="$1"
+    EVENT="${2:-UserPromptSubmit}"
+    ;;
+  *)
+    PROVIDER="claude_code"
+    EVENT="${1:-UserPromptSubmit}"
+    ;;
+esac
+MODA_SNAPSHOT_BIN="${MODA_BIN:-moda}"
+
+# Buffer the hook JSON once so the background subshell sees it after this
+# script's stdin is closed by Claude.
+PAYLOAD="$(cat)"
+
+(
+  printf '%s' "$PAYLOAD" \
+    | "$MODA_SNAPSHOT_BIN" workspace snapshot --provider "$PROVIDER" --event "$EVENT" --json --hook-stdin \
+    > /dev/null 2>&1
+) &
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "!dist/__tests__",
+    "hooks/**",
     "skills/**/SKILL.md",
     "README.md",
     ".env.example"
@@ -20,16 +21,16 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "tsc",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:ci": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lint": "eslint ."
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ModaLabs/moda-cli.git"
+    "url": "https://github.com/ModaLabs/modaobservability.git",
+    "directory": "apps/moda-cli"
   },
   "keywords": [
     "moda",
@@ -43,7 +44,7 @@
   "license": "MIT",
   "homepage": "https://docs.moda.dev/data-api/cli",
   "bugs": {
-    "url": "https://github.com/ModaLabs/moda-cli/issues"
+    "url": "https://github.com/ModaLabs/ModaObservability/issues"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.1",
@@ -51,9 +52,11 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
+    "@moda/eslint-config": "*",
     "@types/node": "^22.10.5",
+    "eslint": "^9.17.0",
     "typescript": "^5.7.2",
-    "vitest": "^3.0.0"
+    "vitest": "^4.0.14"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-description: Query Moda's AI agent conversation analytics from the terminal — overview KPIs, topic clusters, conversation search, message context, user frustration detections, tool failures, agent jobs (per-run outcomes), recurring workflows, and active loop detections. Use when the user asks about moda, modaflows, conversation analytics, user frustrations, agent observability, tool failure debugging, why an agent run partially completed or looped, or wants to investigate how their AI agent is performing.
+description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — overview KPIs, topic clusters, conversation search, message context, user frustration detections, tool failures, agent jobs, recurring workflows, active loop detections, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, why an agent run partially completed or looped, or wants to investigate how their AI agent is performing.
 ---
 
 # Moda CLI
@@ -9,7 +9,9 @@ description: Query Moda's AI agent conversation analytics from the terminal —
 
 Wraps the `moda` CLI so the agent can query a Moda tenant's conversation
 analytics directly. Every command returns JSON on stdout; pipe to `jq` to
-filter. Read-only — no command in this skill modifies data.
+filter. Analytics commands are read-only. Prompt management includes both
+read-only commands (`prompts status`, `prompts diff`) and commands that sync
+or promote remote state (`prompts sync`, `prompts promote`).
 
 ## When to use
 
@@ -20,10 +22,13 @@ Activate this skill when the user wants to:
 - Investigate which tools are failing and why
 - Browse conversation topics (clusters)
 - Search conversations by content, user, environment, or time range
+- Manage code-first prompt versions when the user explicitly asks for prompt
+  sync, prompt status, or prompt promotion
 
 **Do not** activate for: writing code that calls the Moda Data API directly
-(use the API docs instead), instrumenting an app with the Moda SDK (different
-skill / docs), or any modification action — this CLI is read-only.
+(use the API docs instead), changing application instrumentation unless the
+user explicitly asks for SDK setup, or modifying prompt registry state unless
+the user specifically asked for `moda prompts sync` or `moda prompts promote`.
 
 ## Required inputs
 
@@ -196,6 +201,41 @@ agent re-ran the same action 378 times. Use the `loop_signature_human`
 field to recognize cross-conversation patterns (one tool definition bug
 will produce identical signatures across many users).
 
+### 10. Prompt management
+
+Use these only when working on the code-first prompt registry.
+
+```bash
+moda prompts init                               # create .moda/prompts.yml
+moda prompts status                             # read-only local status
+moda prompts diff                               # read-only local diff/status
+moda prompts sync                               # upload changed prompt versions
+moda prompts sync --watch                       # sync when local prompt hashes change
+moda prompts promote support.triage --label=prod --version=pver_abc123
+```
+
+`status` and `diff` are read-only. `sync` uploads prompt versions and writes
+`.moda/prompts.lock.json`. `promote` moves a remote `dev`, `staging`, or
+`prod` label to an existing version.
+
+Runtime code should render synced prompts through the SDK:
+
+```typescript
+const rendered = Moda.prompt("support.triage").render({
+  ticket: { text: userMessage },
+});
+```
+
+```python
+rendered = moda.prompt("support.triage").render({
+    "ticket": {"text": user_message},
+})
+```
+
+Do not copy prompt text from the dashboard into source code. The repo prompt
+files are the source of truth; the dashboard is for visibility, usage, labels,
+and future evals.
+
 ## Common workflow recipes
 
 ### Daily health check
@@ -314,6 +354,10 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda run <run_id>` | One execution + its side-effect receipts |
 | `moda loops` | Currently-active loop detections |
 | `moda loop <detection_id>` | One loop signature with blast radius |
+| `moda prompts status` | Read-only local prompt status |
+| `moda prompts diff` | Read-only local prompt diff/status |
+| `moda prompts sync` | Upload changed prompt versions and update lockfile |
+| `moda prompts promote <key>` | Move a remote prompt label |
 
 Common flags across most commands: `--days-back=N` (1–90), `--limit=N`,
 `--offset=N`, `--time-range=<range>`. Runs commands also accept

package/skills/integrate-moda/SKILL.md

@@ -1,63 +0,0 @@
----
-name: integrate-moda
-description: Integrate the Moda SDK into this project for LLM observability. Use when the user asks to add Moda, set up observability, or instrument LLM calls.
----
-
-# Integrate Moda SDK
-
-Moda auto-instruments LLM calls (OpenAI, Anthropic) via OpenTelemetry.
-After `Moda.init()`, all LLM calls are captured automatically — no wrappers needed.
-
-## Steps
-
-1. Install the SDK: `npm install moda-ai` (or bun/yarn/pnpm equivalent)
-2. Ensure `MODA_API_KEY` is set in the environment
-3. Initialize once at app startup, before any LLM client is created:
-
-```typescript
-import { Moda } from 'moda-ai';
-await Moda.init(process.env.MODA_API_KEY!);
-```
-
-Python: `import moda; moda.init()`
-
-4. Set conversation ID before LLM calls to group multi-turn conversations.
-   Without this, each call appears as a separate conversation in the dashboard.
-
-```typescript
-Moda.conversationId = sessionId;
-Moda.userId = userId; // optional but recommended
-```
-
-For concurrent requests, use scoped context:
-```typescript
-import { withConversationId } from 'moda-ai';
-await withConversationId(sessionId, async () => {
-  await openai.chat.completions.create({ ... });
-});
-```
-
-Python: `moda.conversation_id = session_id` or `with moda.set_conversation_id(session_id):`
-
-5. Flush pending traces before process exit: `await Moda.flush();`
-
-## Vercel AI SDK
-
-When using the `ai` package, auto-instrumentation does not cover it. Pass telemetry config:
-```typescript
-const result = await generateText({
-  model: openai('gpt-4o'),
-  prompt: 'Hello',
-  experimental_telemetry: Moda.getVercelAITelemetry(),
-});
-```
-
-## Rules
-
-- Initialize Moda before creating any LLM client instances
-- Place `Moda.init()` in the app entry point, not in individual route handlers
-- Set `conversationId` per request/session, not globally
-- Use `withConversationId` in server environments handling concurrent requests
-- Call `Moda.flush()` in graceful shutdown handlers and before `process.exit()`
-- Do not wrap LLM calls — auto-instrumentation handles OpenAI and Anthropic automatically
-- Do not import or configure OpenTelemetry manually — Moda manages its own provider