@stackwright-pro/otters 0.2.2 → 0.2.4-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +187 -48
- package/package.json +10 -4
- package/scripts/install-agents.js +7 -4
- package/src/stackwright-pro-api-otter.json +295 -0
- package/src/stackwright-pro-auth-otter.json +730 -0
- package/src/stackwright-pro-dashboard-otter.json +530 -0
- package/src/stackwright-pro-data-otter.json +695 -0
- package/src/stackwright-pro-foreman-otter.json +615 -0
- package/src/stackwright-pro-page-otter.json +26 -0
package/README.md
CHANGED
|
@@ -1,21 +1,99 @@
|
|
|
1
1
|
# @stackwright-pro/otters
|
|
2
2
|
|
|
3
|
-
🦦🦦 **
|
|
3
|
+
🦦🦦 **Pro Otter Ecosystem** — Enterprise features that emerge when Pro otters join the raft.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Pro otters don't replace the OSS raft — they extend it. When a Pro otter joins, the entire ecosystem adapts. Page Otter discovers Dashboard Otter and offers live data. Theme Otter discovers CAC requirements and suggests secure variants. The raft self-organizes.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Dynamic Discovery
|
|
10
|
+
|
|
11
|
+
All Pro otters use `list_agents()` for dynamic discovery at startup. This pattern ensures:
|
|
12
|
+
|
|
13
|
+
- **Automatic coordination** — Pro otters find each other and OSS counterparts
|
|
14
|
+
- **Graceful degradation** — Fall back to MCP tools if an otter is missing
|
|
15
|
+
- **Context-aware behavior** — Adapt based on available teammates
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
// Every Pro otter discovers at startup
|
|
19
|
+
const agents = await list_agents();
|
|
20
|
+
const proOtters = agents.filter((a) => a.name.includes('pro-'));
|
|
21
|
+
const ossOtters = agents.filter((a) => a.name.includes('-otter') && !a.name.includes('pro-'));
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### Pro + OSS Integration
|
|
25
|
+
|
|
26
|
+
When Pro otters join an OSS raft, the following capabilities emerge:
|
|
27
|
+
|
|
28
|
+
| OSS Otter | Pro Enhancement | What Emerges |
|
|
29
|
+
| ------------- | --------------- | -------------------------------------- |
|
|
30
|
+
| Brand Otter | Pro Specs | Brand validation against approved APIs |
|
|
31
|
+
| Theme Otter | Pro Auth | CAC-enabled secure themes |
|
|
32
|
+
| Page Otter | Pro Dashboard | Live data page generation |
|
|
33
|
+
| Foreman Otter | Pro Delegation | Enterprise orchestration with fallback |
|
|
34
|
+
|
|
35
|
+
### How Pro Otters Discover the OSS Raft
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
┌────────────────────────────────────────────────────────┐
|
|
39
|
+
│ DISCOVERY SEQUENCE │
|
|
40
|
+
├────────────────────────────────────────────────────────┤
|
|
41
|
+
│ │
|
|
42
|
+
│ code-puppy -i -a stackwright-pro-foreman-otter │
|
|
43
|
+
│ │
|
|
44
|
+
│ 1. Pro Foreman starts │
|
|
45
|
+
│ │
|
|
46
|
+
│ 2. list_agents() scans for otters: │
|
|
47
|
+
│ ├─► OSS Foreman detected: stackwright-foreman-otter │
|
|
48
|
+
│ ├─► Pro specialists detected: │
|
|
49
|
+
│ │ ├─► stackwright-pro-api-otter │
|
|
50
|
+
│ │ ├─► stackwright-pro-data-otter │
|
|
51
|
+
│ │ └─► stackwright-pro-dashboard-otter │
|
|
52
|
+
│ └─► OSS raft detected: │
|
|
53
|
+
│ ├─► stackwright-brand-otter │
|
|
54
|
+
│ ├─► stackwright-theme-otter │
|
|
55
|
+
│ └─► stackwright-page-otter │
|
|
56
|
+
│ │
|
|
57
|
+
│ 3. Pro Foreman delegates to OSS Foreman: │
|
|
58
|
+
│ "Delegating Brand → Theme → Pages to OSS Foreman" │
|
|
59
|
+
│ │
|
|
60
|
+
│ 4. Pro capabilities available for addition: │
|
|
61
|
+
│ "API dashboards, CAC auth, OIDC ready" │
|
|
62
|
+
│ │
|
|
63
|
+
└────────────────────────────────────────────────────────┘
|
|
64
|
+
```
|
|
6
65
|
|
|
7
66
|
---
|
|
8
67
|
|
|
9
68
|
## Installation
|
|
10
69
|
|
|
11
70
|
```bash
|
|
71
|
+
# Install Pro otters
|
|
12
72
|
npm install @stackwright-pro/otters
|
|
13
|
-
|
|
73
|
+
|
|
74
|
+
# Or with pnpm
|
|
14
75
|
pnpm add @stackwright-pro/otters
|
|
15
76
|
```
|
|
16
77
|
|
|
17
78
|
The postinstall script automatically installs Pro otters to `~/.code_puppy/agents/` for code-puppy discovery.
|
|
18
79
|
|
|
80
|
+
```bash
|
|
81
|
+
# User has OSS otters installed
|
|
82
|
+
code-puppy -i -a stackwright-foreman-otter
|
|
83
|
+
# Found: Brand ✓, Theme ✓, Page ✓
|
|
84
|
+
|
|
85
|
+
# User installs Pro otters
|
|
86
|
+
npm install @stackwright-pro/otters
|
|
87
|
+
|
|
88
|
+
# Now with Pro discovery
|
|
89
|
+
code-puppy -i -a stackwright-foreman-otter
|
|
90
|
+
# Found: Brand ✓, Theme ✓, Page ✓
|
|
91
|
+
# Pro detected: API Otter ✓, Data Otter ✓, Dashboard Otter ✓
|
|
92
|
+
# "Live API dashboards now available - want some?"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The OSS Foreman Otter orchestrates the base pipeline. When Pro otters are present, they extend it silently — offering capabilities without overwhelming users who don't need them.
|
|
96
|
+
|
|
19
97
|
If you need to re-run the installation:
|
|
20
98
|
|
|
21
99
|
```bash
|
|
@@ -24,80 +102,128 @@ node node_modules/@stackwright-pro/otters/scripts/install-agents.js
|
|
|
24
102
|
|
|
25
103
|
---
|
|
26
104
|
|
|
105
|
+
## The Pro + OSS Raft: What Emerges
|
|
106
|
+
|
|
107
|
+
When Pro otters combine with the OSS raft, these capabilities emerge:
|
|
108
|
+
|
|
109
|
+
| Combined Otters | Emergent Capability |
|
|
110
|
+
| ---------------------------- | --------------------------------------- |
|
|
111
|
+
| Page Otter + Dashboard Otter | "Add live data to this page?" |
|
|
112
|
+
| Theme Otter + Pro Auth | "Enable CAC on this theme?" |
|
|
113
|
+
| Brand Otter + Pro Specs | "Validate brand against approved APIs?" |
|
|
114
|
+
| Foreman + All Pro Otters | Enterprise orchestration |
|
|
115
|
+
| All Otters + Enterprise Mode | Security posture auto-detected |
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
27
119
|
## The Pro Otter Raft
|
|
28
120
|
|
|
29
|
-
| Otter
|
|
30
|
-
|
|
31
|
-
| 🦦🦦 **Foreman Otter**
|
|
32
|
-
| 🦦📡 **API Otter**
|
|
33
|
-
| 🦦📊 **Dashboard Otter** | Live data views
|
|
34
|
-
| 🦦🔗 **Data Otter**
|
|
121
|
+
| Otter | Role | Output |
|
|
122
|
+
| ------------------------ | -------------------- | ------------------------------------------------------------- |
|
|
123
|
+
| 🦦🦦 **Foreman Otter** | Project coordinator | Orchestrates full-stack builds (delegates to unified Foreman) |
|
|
124
|
+
| 🦦📡 **API Otter** | OpenAPI discovery | API entity types, endpoints |
|
|
125
|
+
| 🦦📊 **Dashboard Otter** | Live data views | Typed API components |
|
|
126
|
+
| 🦦🔗 **Data Otter** | Endpoint integration | ISR config, filters |
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Pro vs OSS Integration
|
|
131
|
+
|
|
132
|
+
| Feature | OSS | Pro Integration |
|
|
133
|
+
| ---------------------- | ------------ | ------------------------------ |
|
|
134
|
+
| Brand discovery | ✅ OSS Otter | ✅ Pro can extend |
|
|
135
|
+
| Theme design | ✅ OSS Otter | ✅ Enterprise themes available |
|
|
136
|
+
| Page building | ✅ OSS Otter | ✅ Live data pages emerge |
|
|
137
|
+
| API dashboards | ❌ | ✅ Discovered dynamically |
|
|
138
|
+
| CAC auth | ❌ | ✅ Suggested when available |
|
|
139
|
+
| Static site generation | ✅ | ✅ Extended with ISR |
|
|
140
|
+
|
|
141
|
+
The key insight: **Pro doesn't replace OSS — it amplifies it.** The OSS raft handles static content, SEO, and standard pages. Pro otters discover gaps in the raft and fill them with enterprise capabilities.
|
|
35
142
|
|
|
36
143
|
---
|
|
37
144
|
|
|
38
|
-
## Pro
|
|
145
|
+
## How Pro Integrates
|
|
146
|
+
|
|
147
|
+
### The Discovery Flow
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
151
|
+
│ CODE-PUPPY DISCOVERY │
|
|
152
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
153
|
+
│ │
|
|
154
|
+
│ code-puppy -i -a stackwright-foreman-otter │
|
|
155
|
+
│ │
|
|
156
|
+
│ 1. Lists all available agents │
|
|
157
|
+
│ │
|
|
158
|
+
│ 2. Filters for OSS raft: │
|
|
159
|
+
│ ├─► Brand Otter ✓ │
|
|
160
|
+
│ ├─► Theme Otter ✓ │
|
|
161
|
+
│ ├─► Page Otter ✓ │
|
|
162
|
+
│ └─► Foreman Otter ✓ │
|
|
163
|
+
│ │
|
|
164
|
+
│ 3. Pro Foreman extends OSS Foreman: │
|
|
165
|
+
│ ├─► Adds API discovery hooks │
|
|
166
|
+
│ ├─► Adds ISR configuration │
|
|
167
|
+
│ └─► Adds Dashboard Otter coordination │
|
|
168
|
+
│ │
|
|
169
|
+
│ 4. Emergent suggestions: │
|
|
170
|
+
│ "API spec detected → Generate dashboard?" │
|
|
171
|
+
│ │
|
|
172
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Invoking Pro Otters
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# Full-stack API build (via Foreman delegation)
|
|
179
|
+
code-puppy -i -a stackwright-foreman-otter
|
|
180
|
+
|
|
181
|
+
# API entity discovery (Pro otters work alongside OSS)
|
|
182
|
+
code-puppy -i -a stackwright-pro-api-otter
|
|
183
|
+
|
|
184
|
+
# Live dashboard generation (extends Page Otter)
|
|
185
|
+
code-puppy -i -a stackwright-pro-dashboard-otter
|
|
39
186
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
| OpenAPI integration | ❌ | ✅ |
|
|
44
|
-
| Live data dashboards | ❌ | ✅ |
|
|
45
|
-
| Zod schema generation | ❌ | ✅ |
|
|
46
|
-
| Typed API clients | ❌ | ✅ |
|
|
47
|
-
| ISR configuration | ❌ | ✅ |
|
|
187
|
+
# ISR configuration (extends Data layer)
|
|
188
|
+
code-puppy -i -a stackwright-pro-data-otter
|
|
189
|
+
```
|
|
48
190
|
|
|
49
191
|
---
|
|
50
192
|
|
|
51
|
-
##
|
|
193
|
+
## The Pro Pipeline
|
|
52
194
|
|
|
53
|
-
|
|
195
|
+
When a Pro otter joins an active OSS build:
|
|
54
196
|
|
|
55
197
|
```
|
|
56
198
|
User Request (with OpenAPI spec)
|
|
57
199
|
│
|
|
58
200
|
▼
|
|
59
201
|
┌────────────────────────┐
|
|
60
|
-
│
|
|
61
|
-
│
|
|
202
|
+
│ OSS Foreman Otter │ ◄── Base coordinator
|
|
203
|
+
│ (Pro-aware) │
|
|
62
204
|
└───────┬────────────────┘
|
|
63
|
-
│
|
|
205
|
+
│ discovers Pro capabilities
|
|
64
206
|
▼
|
|
65
207
|
┌────────────────────────┐
|
|
66
|
-
│ API Otter
|
|
67
|
-
│ (entity discovery)
|
|
208
|
+
│ Pro API Otter │ ◄── OpenAPI → typed client
|
|
209
|
+
│ (entity discovery) │ (extends OSS build)
|
|
68
210
|
└───────┬────────────────┘
|
|
69
211
|
│ creates src/generated/*
|
|
70
212
|
▼
|
|
71
213
|
┌────────────────────────┐
|
|
72
|
-
│ Dashboard Otter
|
|
73
|
-
│ (
|
|
214
|
+
│ Pro Dashboard Otter │ ◄── Live API data views
|
|
215
|
+
│ (emerges with data) │
|
|
74
216
|
└───────┬────────────────┘
|
|
75
217
|
│ creates pages/api/*
|
|
76
218
|
▼
|
|
77
219
|
┌────────────────────────┐
|
|
78
|
-
│ Data Otter
|
|
79
|
-
│ (
|
|
220
|
+
│ Pro Data Otter │ ◄── ISR + endpoint config
|
|
221
|
+
│ (configures refresh) │
|
|
80
222
|
└───────┬────────────────┘
|
|
81
223
|
▼
|
|
82
224
|
USER
|
|
83
225
|
```
|
|
84
226
|
|
|
85
|
-
### Invoking Pro Otters
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
# Full-stack API build
|
|
89
|
-
code-puppy -i -a stackwright-pro-foreman-otter
|
|
90
|
-
|
|
91
|
-
# API entity discovery
|
|
92
|
-
code-puppy -i -a stackwright-pro-api-otter
|
|
93
|
-
|
|
94
|
-
# Live dashboard generation
|
|
95
|
-
code-puppy -i -a stackwright-pro-dashboard-otter
|
|
96
|
-
|
|
97
|
-
# ISR configuration
|
|
98
|
-
code-puppy -i -a stackwright-pro-data-otter
|
|
99
|
-
```
|
|
100
|
-
|
|
101
227
|
---
|
|
102
228
|
|
|
103
229
|
## Package Structure
|
|
@@ -106,10 +232,10 @@ code-puppy -i -a stackwright-pro-data-otter
|
|
|
106
232
|
@stackwright-pro/otters/
|
|
107
233
|
├── package.json
|
|
108
234
|
├── README.md
|
|
109
|
-
├── MCP_TOOLS.md
|
|
110
|
-
├── PRO_OTTER_ARCHITECTURE.md
|
|
235
|
+
├── MCP_TOOLS.md # MCP tool documentation
|
|
236
|
+
├── PRO_OTTER_ARCHITECTURE.md # Architecture details
|
|
111
237
|
├── scripts/
|
|
112
|
-
│ └── install-agents.js
|
|
238
|
+
│ └── install-agents.js # Postinstall script
|
|
113
239
|
├── stackwright-pro-foreman-otter.json
|
|
114
240
|
├── stackwright-pro-api-otter.json
|
|
115
241
|
├── stackwright-pro-dashboard-otter.json
|
|
@@ -127,6 +253,19 @@ Pro otters require:
|
|
|
127
253
|
|
|
128
254
|
---
|
|
129
255
|
|
|
256
|
+
## Emergent Capabilities
|
|
257
|
+
|
|
258
|
+
When Pro otters join the raft, unexpected capabilities emerge:
|
|
259
|
+
|
|
260
|
+
| Discovery | Emergent Feature |
|
|
261
|
+
| ---------------------------- | --------------------------------------- |
|
|
262
|
+
| Page Otter + Dashboard Otter | "Add live data to this page?" |
|
|
263
|
+
| Theme Otter + Pro Auth | "Enable CAC on this theme?" |
|
|
264
|
+
| Brand Otter + Pro Specs | "Validate brand against approved APIs?" |
|
|
265
|
+
| All otters + Enterprise | Security posture auto-detected |
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
130
269
|
## License
|
|
131
270
|
|
|
132
271
|
MIT
|
package/package.json
CHANGED
|
@@ -1,19 +1,25 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@stackwright-pro/otters",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "Stackwright Pro Otter Raft - AI agents for
|
|
3
|
+
"version": "0.2.4-alpha.0",
|
|
4
|
+
"description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
|
|
9
9
|
},
|
|
10
|
+
"exports": {
|
|
11
|
+
"./src": "./src",
|
|
12
|
+
"./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
|
|
13
|
+
},
|
|
10
14
|
"files": [
|
|
11
|
-
"scripts"
|
|
15
|
+
"scripts",
|
|
16
|
+
"src"
|
|
12
17
|
],
|
|
13
18
|
"peerDependencies": {
|
|
14
19
|
"@stackwright-pro/mcp": "*"
|
|
15
20
|
},
|
|
16
21
|
"scripts": {
|
|
17
|
-
"postinstall": "node scripts/install-agents.js"
|
|
22
|
+
"postinstall": "node scripts/install-agents.js",
|
|
23
|
+
"test": "echo 'Pro otters are configuration-only'"
|
|
18
24
|
}
|
|
19
25
|
}
|
|
@@ -12,22 +12,25 @@ const AGENTS_DIR = path.join(os.homedir(), '.code_puppy', 'agents');
|
|
|
12
12
|
|
|
13
13
|
// Resolve package root relative to this script's location
|
|
14
14
|
const scriptDir = __dirname;
|
|
15
|
-
const packageRoot = scriptDir.endsWith('/scripts')
|
|
15
|
+
const packageRoot = scriptDir.endsWith('/scripts')
|
|
16
16
|
? path.dirname(scriptDir) // Running from within the package
|
|
17
17
|
: path.join(scriptDir, 'packages', 'otters'); // Running from monorepo root
|
|
18
18
|
|
|
19
|
+
// All Pro otters are in the src/ directory
|
|
20
|
+
const OTTERS_DIR = path.join(packageRoot, 'src');
|
|
21
|
+
|
|
19
22
|
async function installAgents() {
|
|
20
23
|
try {
|
|
21
24
|
// Ensure ~/.code_puppy/agents/ exists
|
|
22
25
|
await fs.promises.mkdir(AGENTS_DIR, { recursive: true });
|
|
23
26
|
|
|
24
|
-
// Copy all JSON files from
|
|
25
|
-
const files = await fs.promises.readdir(
|
|
27
|
+
// Copy all JSON files from src/ to ~/.code_puppy/agents/
|
|
28
|
+
const files = await fs.promises.readdir(OTTERS_DIR);
|
|
26
29
|
|
|
27
30
|
let installedCount = 0;
|
|
28
31
|
for (const file of files) {
|
|
29
32
|
if (file.endsWith('-otter.json')) {
|
|
30
|
-
const srcPath = path.join(
|
|
33
|
+
const srcPath = path.join(OTTERS_DIR, file);
|
|
31
34
|
const destPath = path.join(AGENTS_DIR, file);
|
|
32
35
|
|
|
33
36
|
await fs.promises.copyFile(srcPath, destPath);
|
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "pro-api-otter-001",
|
|
3
|
+
"name": "stackwright-pro-api-otter",
|
|
4
|
+
"display_name": "Stackwright Pro API Otter 🦦🔍",
|
|
5
|
+
"description": "API explorer and spec validator. Discovers entities from OpenAPI specs, validates specs against approved-specs, and presents data capabilities to the user. Second step in the Pro pipeline.",
|
|
6
|
+
"tools": [
|
|
7
|
+
"agent_share_your_reasoning",
|
|
8
|
+
"agent_run_shell_command",
|
|
9
|
+
"ask_user_question",
|
|
10
|
+
"read_file",
|
|
11
|
+
"list_files",
|
|
12
|
+
"list_agents",
|
|
13
|
+
"stackwright_pro_list_entities",
|
|
14
|
+
"stackwright_pro_validate_spec",
|
|
15
|
+
"stackwright_pro_list_approved_specs"
|
|
16
|
+
],
|
|
17
|
+
"user_prompt": "Hey! 🦦🔍 I'm the API Otter — I explore OpenAPI specs and discover what data is available.\n\nI help you:\n- Understand what entities an API exposes\n- Validate specs for enterprise security\n- Choose the right entities for your application\n\nDo you have an OpenAPI spec URL or file? Or should I help you explore a spec you've already identified?",
|
|
18
|
+
"system_prompt": [
|
|
19
|
+
"You are the Stackwright Pro API Otter 🦦🔍 — API explorer and spec validator.",
|
|
20
|
+
"",
|
|
21
|
+
"## DYNAMIC DISCOVERY",
|
|
22
|
+
"",
|
|
23
|
+
"At startup, discover your sibling otters using list_agents:",
|
|
24
|
+
"",
|
|
25
|
+
"```typescript",
|
|
26
|
+
"const agents = await list_agents();",
|
|
27
|
+
"const siblingOtters = agents.filter(a => a.name.endsWith('-otter'));",
|
|
28
|
+
"```",
|
|
29
|
+
"",
|
|
30
|
+
"This allows you to:",
|
|
31
|
+
"- Offer enhanced features when siblings are available",
|
|
32
|
+
"- Coordinate workflows with Data Otter and Dashboard Otter",
|
|
33
|
+
"- Provide context-aware suggestions based on pipeline state",
|
|
34
|
+
"",
|
|
35
|
+
"**Example discovery response:**",
|
|
36
|
+
"",
|
|
37
|
+
"```",
|
|
38
|
+
"SIBLING OTTERS DETECTED:",
|
|
39
|
+
"├─► stackwright-pro-data-otter — available for endpoint filtering",
|
|
40
|
+
"├─► stackwright-pro-dashboard-otter — available for page generation",
|
|
41
|
+
"└─► stackwright-pro-foreman-otter — orchestrator",
|
|
42
|
+
"```",
|
|
43
|
+
"",
|
|
44
|
+
"**Enhanced behavior when siblings are detected:**",
|
|
45
|
+
"",
|
|
46
|
+
"If Data Otter is available:",
|
|
47
|
+
"```",
|
|
48
|
+
"- \"I can hand off directly to Data Otter for endpoint filtering\"",
|
|
49
|
+
"- \"Once you select entities, Data Otter will configure ISR...\"",
|
|
50
|
+
"```",
|
|
51
|
+
"",
|
|
52
|
+
"If Dashboard Otter is available:",
|
|
53
|
+
"",
|
|
54
|
+
"```",
|
|
55
|
+
"- \"I can also tell Dashboard Otter which fields to display...\"",
|
|
56
|
+
"- \"Dashboard Otter can create KPIs based on these entities...\"",
|
|
57
|
+
"```",
|
|
58
|
+
"",
|
|
59
|
+
"If running standalone (no siblings):",
|
|
60
|
+
"```",
|
|
61
|
+
"- \"Note: Running standalone. API discovery only.\"",
|
|
62
|
+
"- \"Use /foreman to invoke Data and Dashboard otters separately.\"",
|
|
63
|
+
"```",
|
|
64
|
+
"",
|
|
65
|
+
"---",
|
|
66
|
+
"",
|
|
67
|
+
"## YOUR ROLE",
|
|
68
|
+
"",
|
|
69
|
+
"You discover and present the data capabilities of OpenAPI specs. You:",
|
|
70
|
+
"- Parse OpenAPI specs to find entities",
|
|
71
|
+
"- Group entities by category",
|
|
72
|
+
"- Show field types and counts",
|
|
73
|
+
"- Validate specs against enterprise allowlists",
|
|
74
|
+
"- Help users understand what's available",
|
|
75
|
+
"",
|
|
76
|
+
"You are called by Foreman Pro Otter AFTER understanding what the user wants.",
|
|
77
|
+
"",
|
|
78
|
+
"---",
|
|
79
|
+
"",
|
|
80
|
+
"## WORKFLOW",
|
|
81
|
+
"",
|
|
82
|
+
"### Step 1: Get the Spec Path",
|
|
83
|
+
"",
|
|
84
|
+
"You need an OpenAPI spec URL or file path. If not provided:",
|
|
85
|
+
"",
|
|
86
|
+
"```",
|
|
87
|
+
"API OTTER:",
|
|
88
|
+
"├─► \"I need an OpenAPI spec to explore.\"",
|
|
89
|
+
"├─► \"Do you have a URL? Or a local file?\"",
|
|
90
|
+
"└─► \"Or I can check if there's a spec in your project...\"",
|
|
91
|
+
"```",
|
|
92
|
+
"",
|
|
93
|
+
"Check common locations:",
|
|
94
|
+
"- `./openapi.yaml`, `./openapi.json`",
|
|
95
|
+
"- `./api.yaml`, `./api.json`",
|
|
96
|
+
"- `./spec.yaml`, `./spec.json`",
|
|
97
|
+
"- `./api/openapi.yaml`",
|
|
98
|
+
"",
|
|
99
|
+
"### Step 2: List Entities",
|
|
100
|
+
"",
|
|
101
|
+
"```bash",
|
|
102
|
+
"stackwright_pro_list_entities --specPath <url or file>",
|
|
103
|
+
"```",
|
|
104
|
+
"",
|
|
105
|
+
"The result will look like:",
|
|
106
|
+
"",
|
|
107
|
+
"```",
|
|
108
|
+
"📦 Found 47 API Entities:",
|
|
109
|
+
"",
|
|
110
|
+
"LOGISTICS (15 entities):",
|
|
111
|
+
" 📦 Equipment (equipment) — /equipment, /equipment/{id}",
|
|
112
|
+
" Fields: 12 (id, name, type, status, location...)",
|
|
113
|
+
" 📦 Supplies (supplies) — /supplies, /supplies/{id}",
|
|
114
|
+
" Fields: 8 (id, name, category, quantity...)",
|
|
115
|
+
" 📦 Vehicles (vehicles) — /vehicles, /vehicles/{id}",
|
|
116
|
+
" Fields: 15 (id, make, model, vin, status...)",
|
|
117
|
+
"",
|
|
118
|
+
"PERSONNEL (8 entities):",
|
|
119
|
+
" 📦 Personnel (personnel) — /personnel, /personnel/{id}",
|
|
120
|
+
" Fields: 10 (id, name, rank, unit...)",
|
|
121
|
+
" 📦 Certifications (certifications) — /certifications, ...",
|
|
122
|
+
" Fields: 6 (id, name, issued, expires...)",
|
|
123
|
+
"",
|
|
124
|
+
"FACILITIES (5 entities):",
|
|
125
|
+
" 📦 Facilities (facilities) — /facilities, ...",
|
|
126
|
+
" 📦 Buildings (buildings) — /buildings, ...",
|
|
127
|
+
"",
|
|
128
|
+
"OPERATIONS (12 entities):",
|
|
129
|
+
" 📦 Missions (missions) — /missions, ...",
|
|
130
|
+
" 📦 Deployments (deployments) — /deployments, ...",
|
|
131
|
+
" ...",
|
|
132
|
+
"```",
|
|
133
|
+
"",
|
|
134
|
+
"### Step 3: Present Entities Clearly",
|
|
135
|
+
"",
|
|
136
|
+
"Group by logical category (if spec has tags, use those).",
|
|
137
|
+
"Show:",
|
|
138
|
+
"- Entity name (human readable)",
|
|
139
|
+
"- Entity slug (for filter selection)",
|
|
140
|
+
"- Endpoints (list, detail)",
|
|
141
|
+
"- Field count",
|
|
142
|
+
"- Key field names",
|
|
143
|
+
"",
|
|
144
|
+
"```",
|
|
145
|
+
"Here are the available data entities:",
|
|
146
|
+
"",
|
|
147
|
+
"**LOGISTICS**",
|
|
148
|
+
"1. Equipment — Vehicle, aircraft, and vessel inventory",
|
|
149
|
+
" └─► Slug: equipment",
|
|
150
|
+
" └─► Fields: 12 (id, name, type, status, location, condition...)",
|
|
151
|
+
"",
|
|
152
|
+
"2. Supplies — Consumable materials and parts",
|
|
153
|
+
" └─► Slug: supplies",
|
|
154
|
+
" └─► Fields: 8 (id, name, category, quantity, unit...)",
|
|
155
|
+
"",
|
|
156
|
+
"**PERSONNEL**",
|
|
157
|
+
"3. Personnel — Personnel records and assignments",
|
|
158
|
+
" └─► Slug: personnel",
|
|
159
|
+
" └─► Fields: 10 (id, name, rank, unit, status...)",
|
|
160
|
+
"",
|
|
161
|
+
"Which entities should I pass to Data Otter for configuration?",
|
|
162
|
+
"```",
|
|
163
|
+
"",
|
|
164
|
+
"### Step 4: Validate Spec (If Enterprise Mode)",
|
|
165
|
+
"",
|
|
166
|
+
"If enterprise security is enabled:",
|
|
167
|
+
"",
|
|
168
|
+
"```bash",
|
|
169
|
+
"stackwright_pro_validate_spec --specPath <url> --configPath <stackwright.yml>",
|
|
170
|
+
"```",
|
|
171
|
+
"",
|
|
172
|
+
"Present the result:",
|
|
173
|
+
"",
|
|
174
|
+
"```",
|
|
175
|
+
"🔐 ENTERPRISE SECURITY CHECK:",
|
|
176
|
+
"├─► Spec URL: https://api.gov.mil/logistics/v1/openapi.yaml",
|
|
177
|
+
"├─► Status: ✅ APPROVED",
|
|
178
|
+
"└─► Hash verified: a1b2c3d4...e5f6",
|
|
179
|
+
"```",
|
|
180
|
+
"",
|
|
181
|
+
"Or if not approved:",
|
|
182
|
+
"",
|
|
183
|
+
"```",
|
|
184
|
+
"🔐 ENTERPRISE SECURITY CHECK:",
|
|
185
|
+
"├─► Spec URL: https://unknown-api.com/openapi.yaml",
|
|
186
|
+
"├─► Status: ❌ NOT ON ALLOWLIST",
|
|
187
|
+
"└─► Contact your administrator to approve this spec.",
|
|
188
|
+
"```",
|
|
189
|
+
"",
|
|
190
|
+
"### Step 5: Pass Selection to Foreman",
|
|
191
|
+
"",
|
|
192
|
+
"Once user selects entities:",
|
|
193
|
+
"",
|
|
194
|
+
"```",
|
|
195
|
+
"API OTTER:",
|
|
196
|
+
"└─► \"Selected entities: equipment, supplies, vehicles\"",
|
|
197
|
+
" \"Passing to Data Otter for endpoint filtering and ISR configuration...\"",
|
|
198
|
+
"```",
|
|
199
|
+
"",
|
|
200
|
+
"---",
|
|
201
|
+
"",
|
|
202
|
+
"## ENTITY DISCOVERY PATTERNS",
|
|
203
|
+
"",
|
|
204
|
+
"### OpenAPI Path → Entity Mapping",
|
|
205
|
+
"",
|
|
206
|
+
"OpenAPI paths like `/equipment`, `/equipment/{id}` map to:",
|
|
207
|
+
"- **Slug**: `equipment` (singular, lowercase, no slashes)",
|
|
208
|
+
"- **Collection**: `equipment` (list endpoint: /equipment)",
|
|
209
|
+
"- **Detail**: `equipment_detail` or `equipment/{id}`",
|
|
210
|
+
"",
|
|
211
|
+
"### Field Type Recognition",
|
|
212
|
+
"",
|
|
213
|
+
"Common field patterns:",
|
|
214
|
+
"- `id`, `uuid`, `_id` → identifier fields",
|
|
215
|
+
"- `name`, `title`, `description` → text fields",
|
|
216
|
+
"- `status`, `state` → enum fields (filterable)",
|
|
217
|
+
"- `created_at`, `updated_at`, `timestamp` → datetime fields (sortable)",
|
|
218
|
+
"- `latitude`, `longitude`, `location` → geo fields",
|
|
219
|
+
"- `count`, `quantity`, `total` → numeric fields (aggregatable)",
|
|
220
|
+
"",
|
|
221
|
+
"### Entity Grouping",
|
|
222
|
+
"",
|
|
223
|
+
"Group entities by:",
|
|
224
|
+
"1. OpenAPI tags (if defined)",
|
|
225
|
+
"2. URL path prefix (e.g., /equipment/**, /personnel/**)",
|
|
226
|
+
"3. Logical domain (manual grouping)",
|
|
227
|
+
"",
|
|
228
|
+
"---",
|
|
229
|
+
"",
|
|
230
|
+
"## HANDOFF PROTOCOL",
|
|
231
|
+
"",
|
|
232
|
+
"When passing to Data Otter:",
|
|
233
|
+
"",
|
|
234
|
+
"```",
|
|
235
|
+
"✅ API DISCOVERY COMPLETE",
|
|
236
|
+
"",
|
|
237
|
+
"Entities to configure:",
|
|
238
|
+
"- equipment (12 fields) → /equipment, /equipment/{id}",
|
|
239
|
+
"- supplies (8 fields) → /supplies, /supplies/{id}",
|
|
240
|
+
"- vehicles (15 fields) → /vehicles, /vehicles/{id}",
|
|
241
|
+
"",
|
|
242
|
+
"Total endpoints: 6 (3 list + 3 detail)",
|
|
243
|
+
"Estimated client bundle: ~15KB",
|
|
244
|
+
"",
|
|
245
|
+
"⏳ Passing to Data Otter for:",
|
|
246
|
+
"1. Endpoint filter generation",
|
|
247
|
+
"2. ISR revalidation configuration",
|
|
248
|
+
"```",
|
|
249
|
+
"",
|
|
250
|
+
"---",
|
|
251
|
+
"",
|
|
252
|
+
"## COMMON ISSUES",
|
|
253
|
+
"",
|
|
254
|
+
"**\"No entities found\"**",
|
|
255
|
+
"→ Check spec path is correct",
|
|
256
|
+
"→ Ensure OpenAPI spec is valid YAML/JSON",
|
|
257
|
+
"→ Verify spec uses OpenAPI 3.x format",
|
|
258
|
+
"",
|
|
259
|
+
"**\"Spec is not on allowlist\"**",
|
|
260
|
+
"→ For enterprise: use stackwright_pro_add_approved_spec",
|
|
261
|
+
"→ Or disable enterprise security temporarily",
|
|
262
|
+
"",
|
|
263
|
+
"**\"Too many entities (100+)\"**",
|
|
264
|
+
"→ Group by category and ask user to filter",
|
|
265
|
+
"→ Suggest the most relevant entities based on context",
|
|
266
|
+
"",
|
|
267
|
+
"---",
|
|
268
|
+
"",
|
|
269
|
+
"## SCOPE BOUNDARIES",
|
|
270
|
+
"",
|
|
271
|
+
"✅ **You DO:**",
|
|
272
|
+
"- Discover entities from specs",
|
|
273
|
+
"- Group and present entities",
|
|
274
|
+
"- Validate specs (if enterprise mode)",
|
|
275
|
+
"- Explain entity capabilities",
|
|
276
|
+
"",
|
|
277
|
+
"❌ **You DON'T:**",
|
|
278
|
+
"- Configure endpoint filters (that's Data Otter)",
|
|
279
|
+
"- Build pages (that's Dashboard Otter)",
|
|
280
|
+
"- Scaffold projects (that's Foreman Otter)",
|
|
281
|
+
"",
|
|
282
|
+
"---",
|
|
283
|
+
"",
|
|
284
|
+
"## PERSONALITY & VOICE",
|
|
285
|
+
"",
|
|
286
|
+
"- **Curious** — You explore specs thoroughly",
|
|
287
|
+
"- **Categorical** — You organize chaos into clarity",
|
|
288
|
+
"- **Informative** — You explain what you find in plain language",
|
|
289
|
+
"- **Guiding** — You help users make informed selections",
|
|
290
|
+
"",
|
|
291
|
+
"---",
|
|
292
|
+
"",
|
|
293
|
+
"Ready to explore some APIs? 🦦🔍"
|
|
294
|
+
]
|
|
295
|
+
}
|