@memberjunction/cli 6.1.2 → 6.2.0-edge.0

package/dist/init-templates/citizen-builder/.agents/skills/package-agent/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: package-agent
+description: Validates, packages, and exports an agent into a promotion bundle with an AGENT_MANIFEST.md for admin review.
+---
+
+# Skill: `package-agent` (Exporting for Promotion)
+
+Use this skill when the user is satisfied with their agent and wants to share, export, or submit it for promotion to staging or production.
+
+## Step 1: Pre-Flight Safety Validation
+Inspect the agent's files and verify against the security rules:
+- [ ] `ModelSelectionMode: "Agent Type"` is set (no pinned provider models).
+- [ ] `ExposeAsAction: false` (or explicitly documented if true).
+- [ ] No hardcoded record IDs or personal names in prompts.
+- [ ] No API keys, credentials, or secrets embedded in metadata.
+- [ ] If Tier 2 Runtime Actions are included, ensure an explicit `allowedEntities` list is specified.
+
+## Step 2: Extract Last Successful Execution Receipt
+Run `./scripts/query-run-history.sh` to grab the ID and metrics of the latest successful run:
+```bash
+# List recent runs for the agent
+./scripts/query-run-history.sh "<Agent Name>"
+
+# Fetch structured JSON audit for the target RunID
+./scripts/query-run-history.sh <RunID> --format json
+```
+Record:
+- Timestamp of test run
+- Total tokens consumed
+- Verified actions executed (`actionsUsed`)
+- Sample input and generated output summary
+
+## Step 3: Generate `AGENT_MANIFEST.md`
+Create a clean manifest file documenting:
+1. **Agent Metadata**:
+   - Name & Description
+   - Author (User name) & Creation Date
+   - Agent Type (Flow vs Loop)
+2. **Tier Classification**:
+   - **Tier 1 (Declarative)**: Safe for immediate auto-approval.
+   - **Tier 2 (Runtime Action)**: Highlight any custom JavaScript files that require admin review.
+3. **Data Footprint**:
+   - Entities Read (e.g. `Orders`, `Customers`)
+   - Entities Written (e.g. `None` or `Invoices`)
+   - Actions and Tools Bound
+4. **Sample Test Results**:
+   - The verified test inputs and outputs from Step 2.
+
+## Step 4: Bundle into Archive
+Create the `dist/` directory and package the agent's files:
+```bash
+mkdir -p dist
+AGENT_SLUG="<agent-slug>"
+PACKAGE_NAME="${AGENT_SLUG}-package.zip"
+
+# Create archive containing the manifest, metadata files, and prompt templates
+zip -r "dist/${PACKAGE_NAME}" \
+  AGENT_MANIFEST.md \
+  metadata/agents/.*"${AGENT_SLUG}"*.json \
+  metadata/prompts/.*"${AGENT_SLUG}"*.json \
+  metadata/prompts/templates/"${AGENT_SLUG}"*.md \
+  2>/dev/null || tar -czf "dist/${AGENT_SLUG}-package.tar.gz" AGENT_MANIFEST.md metadata/
+```
+
+## Step 5: Inform the User
+Provide the user with:
+1. The path to the export package (`dist/<package-name>`).
+2. A summary of `AGENT_MANIFEST.md`.
+3. Instructions on sharing the bundle with their organization's platform team or administrator.

package/dist/init-templates/citizen-builder/.agents/skills/test-agent/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: test-agent
+description: Executes tests for MemberJunction agents, queries database run traces, and diagnoses issues.
+---
+
+# Skill: `test-agent` (Testing & Run Trace Diagnostics)
+
+Use this skill whenever the user wants to test an agent, reports an error, or asks why an agent produced unexpected output.
+
+## Method A: Headless Execution (Automated Verification)
+You can invoke the agent directly via the CLI to test basic functionality and input handling:
+
+```bash
+docker compose exec -T mj mj ai agents run -a "<Agent Name>" -p "<Test Prompt or Input>" --format json
+```
+
+Options:
+- `--format json`: Machine-readable structured JSON result.
+- `-v` / `--verbose`: Detailed diagnostic logging.
+
+## Method B: User Interactive Testing (Explorer UI)
+Instruct the user to open their browser at `http://localhost:4202` to test interactively.
+
+---
+
+## Diagnosing Failures: Execution Trace Auditing
+
+When an execution fails, stalls, or behaves unexpectedly, **do not ask the user for console logs**. Audit the run trace via CLI:
+
+```bash
+# List recent runs for the agent
+./scripts/query-run-history.sh "<Agent Name>"
+
+# Audit a specific run with full JSON trace
+./scripts/query-run-history.sh <RunID> --format json
+
+# Or inspect individual step details or errors
+./scripts/query-run-history.sh <RunID> --step 1 --detail full
+./scripts/query-run-history.sh <RunID> --errors
+```
+
+### Trace Verification Assertions:
+1. **Action Verification**:
+   - Confirm `actionsUsed` matches expected actions for the flow/loop.
+   - Confirm `actionsNotUsed` contains any restricted or sensitive actions.
+2. **Step Inspection**:
+   - Check input and output snippets for prompt drift or malformed arguments.
+   - Check error messages on individual failed steps.
+3. **Resource Consumption**:
+   - Check token consumption and duration to prevent runaway loops.
+
+---
+
+## Iterating and Refining
+1. If the LLM misunderstood instructions, edit `metadata/prompts/templates/<slug>.template.md` to clarify formatting, edge cases, or instructions.
+2. If parameter mapping failed, update `ActionInputMapping` / `ActionOutputMapping` in `metadata/agents/.<slug>-agent.json`.
+3. Push changes:
+   ```bash
+   ./scripts/sync-metadata.sh
+   ```
+4. Re-run or ask the user to re-test.

package/dist/init-templates/citizen-builder/.claude/skills/new-agent/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: new-agent
+description: Guides the coding agent to author a new MemberJunction agent and prompt metadata from user business intent.
+---
+
+# Skill: `new-agent` (Authoring Declarative Agents)
+
+Use this skill whenever the user asks to build, create, or modify a MemberJunction AI Agent.
+
+## Step 1: Elicit & Scope Business Intent
+Ask clarifying questions if the requirement is ambiguous:
+1. **Goal**: What specific business problem does the agent solve?
+2. **Inputs & Subjects**: What input does the user provide (e.g. an account ID, order number, or topic)?
+3. **Data Sources**: Which entities does it read or check? (Cross-reference against `CAPABILITIES.md`).
+4. **Output / Action**: Does it produce an answer, a formatted summary, a notification, or trigger a downstream action?
+
+## Step 2: Determine Tier & Agent Type
+- **Tier 1 (Preferred)**:
+  - If the agent follows a predictable sequence of steps, use **`TypeID: "@lookup:MJ: AI Agent Types.Name=Flow"`**.
+  - If the agent needs dynamic problem solving or open-ended tool calling, use **`TypeID: "@lookup:MJ: AI Agent Types.Name=Loop"`**.
+  - Always keep **`ModelSelectionMode: "Agent Type"`** and **`ExposeAsAction: false`**.
+- **Tier 2 (Only if custom code is strictly necessary)**:
+  - If custom JavaScript formatting or computation is required that no existing action supports, create a sandboxed Runtime Action.
+  - Define an explicit `allowedEntities` list (never wildcards).
+
+## Step 3: Author Prompt Template & Metadata
+1. **Markdown Prompt Template**:
+   Save to: `metadata/prompts/templates/<agent-slug>.template.md`
+   Structure:
+   - Clear persona and objective.
+   - Exact instructions and step sequence.
+   - Business rules and edge-case handling.
+   - Explicit Markdown output formatting guidelines.
+
+2. **Prompt Metadata JSON**:
+   Save to: `metadata/prompts/.<agent-slug>-prompt.json`
+   ```json
+   [
+     {
+       "fields": {
+         "Name": "<Agent Name> Prompt",
+         "Description": "...",
+         "CategoryID": "@lookup:MJ: AI Prompt Categories.Name=Agent Type System Prompts",
+         "TypeID": "@lookup:MJ: AI Prompt Types.Name=Chat",
+         "Status": "Active",
+         "TemplateText": "@file:templates/<agent-slug>.template.md"
+       },
+       "primaryKey": { "ID": "<GENERATE-UUID-UPPERCASE>" }
+     }
+   ]
+   ```
+
+3. **Agent Metadata JSON**:
+   Save to: `metadata/agents/.<agent-slug>-agent.json`
+   Wire `MJ: AI Agent Prompts`, `MJ: AI Agent Steps`, and optional `MJ: AI Agent Actions`.
+
+## Step 4: Sync to Database
+Run:
+```bash
+./scripts/sync-metadata.sh
+```
+Verify that the sync command outputs success.
+
+## Step 5: Hand off to Testing
+Inform the user that the agent has been created and synced:
+*"I've created your agent '**<Agent Name>**' and synced it to your local environment. You can test it now in Explorer or ask me to run a test execution."*

package/dist/init-templates/citizen-builder/.claude/skills/package-agent/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: package-agent
+description: Validates, packages, and exports an agent into a promotion bundle with an AGENT_MANIFEST.md for admin review.
+---
+
+# Skill: `package-agent` (Exporting for Promotion)
+
+Use this skill when the user is satisfied with their agent and wants to share, export, or submit it for promotion to staging or production.
+
+## Step 1: Pre-Flight Safety Validation
+Inspect the agent's files and verify against the security rules:
+- [ ] `ModelSelectionMode: "Agent Type"` is set (no pinned provider models).
+- [ ] `ExposeAsAction: false` (or explicitly documented if true).
+- [ ] No hardcoded record IDs or personal names in prompts.
+- [ ] No API keys, credentials, or secrets embedded in metadata.
+- [ ] If Tier 2 Runtime Actions are included, ensure an explicit `allowedEntities` list is specified.
+
+## Step 2: Extract Last Successful Execution Receipt
+Run `./scripts/query-run-history.sh` to grab the ID and metrics of the latest successful run:
+```bash
+# List recent runs for the agent
+./scripts/query-run-history.sh "<Agent Name>"
+
+# Fetch structured JSON audit for the target RunID
+./scripts/query-run-history.sh <RunID> --format json
+```
+Record:
+- Timestamp of test run
+- Total tokens consumed
+- Verified actions executed (`actionsUsed`)
+- Sample input and generated output summary
+
+## Step 3: Generate `AGENT_MANIFEST.md`
+Create a clean manifest file documenting:
+1. **Agent Metadata**:
+   - Name & Description
+   - Author (User name) & Creation Date
+   - Agent Type (Flow vs Loop)
+2. **Tier Classification**:
+   - **Tier 1 (Declarative)**: Safe for immediate auto-approval.
+   - **Tier 2 (Runtime Action)**: Highlight any custom JavaScript files that require admin review.
+3. **Data Footprint**:
+   - Entities Read (e.g. `Orders`, `Customers`)
+   - Entities Written (e.g. `None` or `Invoices`)
+   - Actions and Tools Bound
+4. **Sample Test Results**:
+   - The verified test inputs and outputs from Step 2.
+
+## Step 4: Bundle into Archive
+Create the `dist/` directory and package the agent's files:
+```bash
+mkdir -p dist
+AGENT_SLUG="<agent-slug>"
+PACKAGE_NAME="${AGENT_SLUG}-package.zip"
+
+# Create archive containing the manifest, metadata files, and prompt templates
+zip -r "dist/${PACKAGE_NAME}" \
+  AGENT_MANIFEST.md \
+  metadata/agents/.*"${AGENT_SLUG}"*.json \
+  metadata/prompts/.*"${AGENT_SLUG}"*.json \
+  metadata/prompts/templates/"${AGENT_SLUG}"*.md \
+  2>/dev/null || tar -czf "dist/${AGENT_SLUG}-package.tar.gz" AGENT_MANIFEST.md metadata/
+```
+
+## Step 5: Inform the User
+Provide the user with:
+1. The path to the export package (`dist/<package-name>`).
+2. A summary of `AGENT_MANIFEST.md`.
+3. Instructions on sharing the bundle with their organization's platform team or administrator.

package/dist/init-templates/citizen-builder/.claude/skills/test-agent/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: test-agent
+description: Executes tests for MemberJunction agents, queries database run traces, and diagnoses issues.
+---
+
+# Skill: `test-agent` (Testing & Run Trace Diagnostics)
+
+Use this skill whenever the user wants to test an agent, reports an error, or asks why an agent produced unexpected output.
+
+## Method A: Headless Execution (Automated Verification)
+You can invoke the agent directly via the CLI to test basic functionality and input handling:
+
+```bash
+docker compose exec -T mj mj ai agents run -a "<Agent Name>" -p "<Test Prompt or Input>" --format json
+```
+
+Options:
+- `--format json`: Machine-readable structured JSON result.
+- `-v` / `--verbose`: Detailed diagnostic logging.
+
+## Method B: User Interactive Testing (Explorer UI)
+Instruct the user to open their browser at `http://localhost:4202` to test interactively.
+
+---
+
+## Diagnosing Failures: Execution Trace Auditing
+
+When an execution fails, stalls, or behaves unexpectedly, **do not ask the user for console logs**. Audit the run trace via CLI:
+
+```bash
+# List recent runs for the agent
+./scripts/query-run-history.sh "<Agent Name>"
+
+# Audit a specific run with full JSON trace
+./scripts/query-run-history.sh <RunID> --format json
+
+# Or inspect individual step details or errors
+./scripts/query-run-history.sh <RunID> --step 1 --detail full
+./scripts/query-run-history.sh <RunID> --errors
+```
+
+### Trace Verification Assertions:
+1. **Action Verification**:
+   - Confirm `actionsUsed` matches expected actions for the flow/loop.
+   - Confirm `actionsNotUsed` contains any restricted or sensitive actions.
+2. **Step Inspection**:
+   - Check input and output snippets for prompt drift or malformed arguments.
+   - Check error messages on individual failed steps.
+3. **Resource Consumption**:
+   - Check token consumption and duration to prevent runaway loops.
+
+---
+
+## Iterating and Refining
+1. If the LLM misunderstood instructions, edit `metadata/prompts/templates/<slug>.template.md` to clarify formatting, edge cases, or instructions.
+2. If parameter mapping failed, update `ActionInputMapping` / `ActionOutputMapping` in `metadata/agents/.<slug>-agent.json`.
+3. Push changes:
+   ```bash
+   ./scripts/sync-metadata.sh
+   ```
+4. Re-run or ask the user to re-test.

package/dist/init-templates/citizen-builder/.env.example

@@ -0,0 +1,30 @@
+# ==============================================================================
+# MemberJunction Citizen Agent Builder Environment Configuration
+# ==============================================================================
+
+# Database Configuration
+DB_PASSWORD=TestPassword123!
+DB_PORT=1433
+DB_DATABASE=MemberJunction
+API_PORT=4000
+# Explorer port (use 4202 if 4200 is in use, as 4202 is an authorized redirect URI for Auth0/MSAL)
+EXPLORER_PORT=4202
+
+# Security
+MJ_BASE_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef
+
+# LLM Provider API Keys (Provide at least one)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+GROQ_API_KEY=
+MISTRAL_API_KEY=
+
+# Business Context / Open App Configuration
+# Default: More Cheese (public reference app with 9 business packages + synthetic data)
+OPEN_APP_INSTALL_URL=https://github.com/MemberJunction/more-cheese
+
+# Enterprise Private Repository Access (e.g., Blue Cypress / BC)
+# If your organization uses private Open Apps, specify a read-only GitHub token:
+# GITHUB_TOKEN=ghp_yourOrgReadTokenHere
+# OPEN_APP_INSTALL_URL=https://github.com/BlueCypress/bc-sampledata