0
# Extensions & Integration
1

2
Commands for working with plugins, extensions, and external integrations including Docker, migration tools, and protocol servers.
3

4
## Capabilities
5

6
### Execute Extension Plugin
7

8
Run an extension plugin with optional arguments passed through.
9

10
```bash { .api }
11
moon ext <id> [-- args...]
12
```
13

14
**Arguments:**
15
- `id` (required) - ID of the extension plugin to execute
16
- `args` (optional) - Arguments to pass through to the extension (after `--`)
17

18
**Usage Examples:**
19

20
```bash
21
# Execute an extension
22
moon ext deploy
23

24
# Execute extension with arguments
25
moon ext deploy -- --environment production --verbose
26

27
# Pass complex arguments
28
moon ext custom-tool -- --config ./custom.json --output ./dist
29
```
30

31
### MCP Server
32

33
Start a Model Context Protocol (MCP) server for AI agent integration.
34

35
```bash { .api }
36
moon mcp
37
```
38

39
This command starts an MCP server that allows AI agents to:
40
- Query project information
41
- Execute moon commands
42
- Analyze workspace structure
43
- Access build and test results
44

45
**Usage Examples:**
46

47
```bash
48
# Start MCP server
49
moon mcp
50

51
# Use in AI agent configuration
52
# Add to your agent's MCP server list
53
```
54

55
### Docker Integration
56

57
Commands for integrating moon projects with Docker and containerization.
58

59
```bash { .api }
60
moon docker <subcommand>
61
```
62

63
**Subcommands:**
64

65
#### Generate Dockerfile
66

67
Generate a default Dockerfile for a project based on its configuration and dependencies.
68

69
```bash { .api }
70
moon docker file <project> [--multi-stage] [--template <TEMPLATE>]
71
```
72

73
**Arguments:**
74
- `project` (required) - Project ID to generate Dockerfile for
75

76
**Options:**
77
- `--multi-stage` - Generate multi-stage Dockerfile for optimized builds
78
- `--template <TEMPLATE>` - Use a specific Dockerfile template
79

80
**Usage Examples:**
81

82
```bash
83
# Generate basic Dockerfile
84
moon docker file my-app
85

86
# Generate multi-stage Dockerfile
87
moon docker file my-app --multi-stage
88

89
# Use custom template
90
moon docker file my-app --template node-alpine
91
```
92

93
#### Prune Docker Context
94

95
Remove extraneous files and folders from Docker build context to optimize build performance.
96

97
```bash { .api }
98
moon docker prune [--dry-run]
99
```
100

101
**Options:**
102
- `--dry-run` - Preview what would be removed without making changes
103

104
**Usage Examples:**
105

106
```bash
107
# Remove unnecessary files from Docker context
108
moon docker prune
109

110
# Preview what would be removed
111
moon docker prune --dry-run
112
```
113

114
#### Scaffold Docker Repository
115

116
Create a repository skeleton optimized for Docker builds with moon.
117

118
```bash { .api }
119
moon docker scaffold <name> [--template <TEMPLATE>]
120
```
121

122
**Arguments:**
123
- `name` (required) - Name for the new repository
124

125
**Options:**
126
- `--template <TEMPLATE>` - Template to use for scaffolding
127

128
**Usage Examples:**
129

130
```bash
131
# Create Docker-optimized repository
132
moon docker scaffold my-docker-app
133

134
# Use specific template
135
moon docker scaffold my-app --template microservice
136
```
137

138
#### Setup Docker Environment
139

140
Setup Dockerfile by installing dependencies for necessary projects.
141

142
```bash { .api }
143
moon docker setup [--projects <PROJECTS>]
144
```
145

146
**Options:**
147
- `--projects <PROJECTS>` - Comma-separated list of projects to setup
148

149
**Usage Examples:**
150

151
```bash
152
# Setup all project dependencies
153
moon docker setup
154

155
# Setup specific projects
156
moon docker setup --projects my-app,shared-utils
157
```
158

159
### Migration Tools
160

161
Commands for migrating existing projects to use moon.
162

163
```bash { .api }
164
moon migrate <subcommand> [--skip-touched-files-check]
165
```
166

167
**Global Options:**
168
- `--skip-touched-files-check` - Disable the check for modified/dirty files
169

170
**Subcommands:**
171

172
#### Migrate from package.json
173

174
Convert `package.json` scripts and dependencies to moon task configuration.
175

176
```bash { .api }
177
moon migrate from-package-json [--projects <PROJECTS>] [--skip-scripts <SCRIPTS>] [--task-prefix <PREFIX>]
178
```
179

180
**Options:**
181
- `--projects <PROJECTS>` - Comma-separated list of projects to migrate
182
- `--skip-scripts <SCRIPTS>` - Scripts to skip during migration
183
- `--task-prefix <PREFIX>` - Prefix to add to generated task names
184

185
**Usage Examples:**
186

187
```bash
188
# Migrate all package.json files
189
moon migrate from-package-json
190

191
# Migrate specific projects
192
moon migrate from-package-json --projects web-app,api-server
193

194
# Skip certain scripts
195
moon migrate from-package-json --skip-scripts "postinstall,prepare"
196

197
# Add prefix to task names
198
moon migrate from-package-json --task-prefix "npm-"
199

200
# Skip dirty file check
201
moon migrate from-package-json --skip-touched-files-check
202
```
203

204
#### Migrate from Turborepo
205

206
Convert `turbo.json` configuration to moon configuration files.
207

208
```bash { .api }
209
moon migrate from-turborepo [--config <CONFIG>]
210
```
211

212
**Options:**
213
- `--config <CONFIG>` - Path to turbo.json file (default: ./turbo.json)
214

215
**Usage Examples:**
216

217
```bash
218
# Migrate from default turbo.json
219
moon migrate from-turborepo
220

221
# Migrate from custom config file
222
moon migrate from-turborepo --config ./custom-turbo.json
223

224
# Skip dirty file check
225
moon migrate from-turborepo --skip-touched-files-check
226
```
227

228
## Extension Development
229

230
### Creating Extensions
231

232
Extensions are standalone executables that integrate with moon:
233

234
```bash
235
# Extension directory structure
236
~/.moon/extensions/
237
├── deploy/
238
│   ├── extension.yml      # Extension metadata
239
│   └── bin/
240
│       └── deploy         # Executable
241
└── custom-tool/
242
    ├── extension.yml
243
    └── deploy.js          # Node.js script
244
```
245

246
### Extension Configuration
247

248
Extensions are configured using `extension.yml`:
249

250
```yaml
251
# extension.yml
252
name: "Deploy Extension"
253
description: "Deploy applications to cloud providers"
254
version: "1.0.0"
255
author: "Development Team"
256

257
executable:
258
  command: "./bin/deploy"
259
  
260
arguments:
261
  - name: "environment"
262
    description: "Target environment"
263
    required: true
264
    
265
  - name: "verbose"
266
    description: "Enable verbose output"
267
    type: "boolean"
268
    
269
permissions:
270
  - "workspace:read"
271
  - "project:read"
272
  - "task:execute"
273
```
274

275
### Extension API access
276

277
Extensions can access moon data through environment variables:
278

279
```bash
280
# Available in extension environment
281
MOON_WORKSPACE_ROOT=/path/to/workspace
282
MOON_PROJECT_ROOT=/path/to/project  
283
MOON_CACHE_DIR=/path/to/cache
284
MOON_LOG_LEVEL=info
285
```
286

287
## Docker Best Practices
288

289
### Multi-stage Builds
290

291
Moon-generated Dockerfiles support optimized multi-stage builds:
292

293
```dockerfile
294
# Generated by moon docker file
295
FROM node:18-alpine AS dependencies
296
WORKDIR /app
297
COPY package*.json ./
298
RUN npm ci --only=production
299

300
FROM node:18-alpine AS build  
301
WORKDIR /app
302
COPY . .
303
RUN moon run build
304

305
FROM node:18-alpine AS runtime
306
WORKDIR /app  
307
COPY --from=dependencies /app/node_modules ./node_modules
308
COPY --from=build /app/dist ./dist
309
CMD ["node", "dist/index.js"]
310
```
311

312
### Build Context Optimization
313

314
Use `moon docker prune` to optimize build contexts:
315

316
```bash
317
# Before pruning
318
.dockerignore
319
node_modules/
320
.git/
321
docs/
322
*.md
323

324
# After moon docker prune
325
# Additional patterns added:
326
.moon/cache/
327
tmp/
328
*.log
329
coverage/
330
```
331

332
## Migration Strategies
333

334
### Gradual Migration
335

336
Migrate projects incrementally:
337

338
```bash
339
# Start with a single project
340
moon migrate from-package-json --projects my-app
341

342
# Validate the migration
343
moon check my-app
344

345
# Migrate additional projects
346
moon migrate from-package-json --projects shared-utils
347
```
348

349
### Script Mapping
350

351
Common package.json scripts map to moon tasks:
352

353
- `build` → `build` task
354
- `test` → `test` task  
355
- `lint` → `lint` task
356
- `start` → `dev` or `start` task
357
- `dev` → `dev` task
358

359
### Dependency Handling
360

361
Moon automatically handles workspace dependencies:
362

363
```json
364
// Before migration (package.json)
365
{
366
  "scripts": {
367
    "build": "tsc",
368
    "test": "jest"
369
  },
370
  "dependencies": {
371
    "shared-utils": "workspace:*"
372
  }
373
}
374
```
375

376
```yaml
377
# After migration (moon.yml)
378
tasks:
379
  build:
380
    command: "tsc"
381
    deps: ["shared-utils:build"]
382
    
383
  test:
384
    command: "jest"  
385
    deps: ["~:build"]
386
```