0
# Project Management
1

2
Comprehensive project management capabilities for workspace organization, dependency analysis, and project health monitoring.
3

4
## Capabilities
5

6
### Project Health Checking
7

8
Run all build and test tasks to verify project health and readiness.
9

10
```bash { .api }
11
/**
12
 * Run all build and test tasks for one or many projects
13
 * Convenience command for verifying project state
14
 */
15
moon check [...projects]
16

17
# Alias:
18
moon c [...projects]
19

20
# Arguments:
21
# [...projects]    List of project names or aliases (optional)
22

23
# Options:
24
--all              Run check for all projects in workspace
25
-u, --updateCache  Bypass cache and force update existing items
26
--summary          Display summary and stats of current run
27
```
28

29
**Usage Examples:**
30

31
```bash
32
# Check project at current working directory
33
moon check
34

35
# Check specific project by name
36
moon check app
37

38
# Check multiple projects
39
moon check client server admin
40

41
# Check all projects (may be costly)
42
moon check --all
43

44
# Force cache update during check
45
moon check app --updateCache
46

47
# Show summary statistics
48
moon check --all --summary
49
```
50

51
### Project Information
52

53
Display detailed information about projects in the workspace.
54

55
```bash { .api }
56
/**
57
 * Display comprehensive information about a specific project
58
 * Shows configuration, tasks, dependencies, and metadata
59
 */
60
moon project <id>
61
# Alias: moon p
62

63
# Arguments:
64
# <id>    Project ID, name, or alias
65

66
# Options:
67
--json    Output information in JSON format
68
```
69

70
**Usage Examples:**
71

72
```bash
73
# Get project information
74
moon project app
75

76
# JSON output for scripting
77
moon project app --json
78

79
# Using project alias
80
moon project frontend-app
81
```
82

83
### Project Graph Analysis
84

85
Visualize and analyze project dependencies and relationships.
86

87
```bash { .api }
88
/**
89
 * Display dependency graph showing project relationships
90
 * Reveals dependencies and dependents between projects
91
 */
92
moon project-graph [ids...]
93
# Alias: moon pg
94

95
# Arguments:
96
# [ids...]    Optional list of project IDs to include in graph
97

98
# Options:
99
--dot     Output in DOT format for Graphviz visualization
100
--json    Output in JSON format for programmatic processing
101
```
102

103
**Usage Examples:**
104

105
```bash
106
# Show graph for all projects
107
moon project-graph
108

109
# Show graph for specific projects
110
moon project-graph app server
111

112
# Generate visualization file
113
moon project-graph --dot > projects.dot
114
dot -Tpng projects.dot -o projects.png
115

116
# JSON for analysis
117
moon project-graph --json | jq '.nodes[] | .id'
118
```
119

120
### Project Query System
121

122
Query and filter projects using advanced criteria.
123

124
```bash { .api }
125
/**
126
 * Query projects using flexible filter criteria
127
 * Supports complex logical expressions and patterns
128
 */
129
moon query projects <statement>
130

131
# Query Statement Syntax:
132
# Logical Operators:
133
# &&               AND operation
134
# ||               OR operation  
135
# !                NOT operation
136
# ()               Grouping
137

138
# Filter Criteria:
139
# language=<lang>       Programming language (javascript, typescript, rust, etc.)
140
# projectType=<type>    Project type (application, library, tool, etc.)
141
# tag=<tag>            Project tag
142
# project~<pattern>     Project name pattern matching
143
# projectSource~<path>  Source path pattern matching
144
# hasTask=<task>       Projects that define specific task
145
# dependsOn=<project>   Projects that depend on specified project
146
```
147

148
**Query Examples:**
149

150
```bash
151
# Find all TypeScript applications  
152
moon query projects "language=typescript && projectType=application"
153

154
# Find projects with specific tag
155
moon query projects "tag=frontend"
156

157
# Find projects matching name pattern
158
moon query projects "project~*-api"
159

160
# Complex query with multiple criteria
161
moon query projects "(language=javascript || language=typescript) && projectType=library"
162

163
# Find projects in specific directory
164
moon query projects "projectSource~packages/*"
165

166
# Find projects with build task
167
moon query projects "hasTask=build"
168

169
# Find projects depending on shared library
170
moon query projects "dependsOn=shared-lib"
171
```
172

173
### Task Query System
174

175
Query tasks across the workspace.
176

177
```bash { .api }
178
/**
179
 * Query tasks across projects using filter criteria
180
 * Find tasks matching specific patterns or properties
181
 */
182
moon query tasks <statement>
183

184
# Task Query Criteria:
185
# task=<name>          Task name
186
# project=<name>       Project containing task
187
# platform=<platform>  Target platform
188
# type=<type>          Task type (build, test, lint, etc.)
189
# hasInput=<pattern>   Tasks with input files matching pattern
190
# hasOutput=<pattern>  Tasks with output files matching pattern
191
```
192

193
**Task Query Examples:**
194

195
```bash
196
# Find all build tasks
197
moon query tasks "task=build"
198

199
# Find test tasks in frontend projects
200
moon query tasks "type=test && project~*frontend*"
201

202
# Find tasks with TypeScript inputs
203
moon query tasks "hasInput=*.ts"
204
```
205

206
### Touched Files Analysis
207

208
Analyze which files have been modified and their impact.
209

210
```bash { .api }
211
/**
212
 * Query touched files and their relationships to projects/tasks
213
 * Useful for understanding change impact
214
 */
215
moon query touched-files
216

217
# Shows:
218
# - Modified files
219
# - Affected projects
220
# - Impacted tasks
221
# - Change status
222
```
223

224
### Project Synchronization
225

226
Sync workspace configuration and project states.
227

228
```bash { .api }
229
/**
230
 * Sync workspace and projects with up-to-date configuration
231
 * Updates project graphs, dependencies, and toolchain state
232
 */
233
moon sync
234

235
# Subcommands:
236
moon sync projects     # Sync all project configurations
237
moon sync hooks       # Sync git hooks for workspace
238
moon sync codeowners  # Sync CODEOWNERS file based on project ownership
239
```
240

241
**Usage Examples:**
242

243
```bash
244
# Sync all configurations
245
moon sync
246

247
# Sync only project configurations
248
moon sync projects
249

250
# Setup git hooks
251
moon sync hooks
252

253
# Update code ownership files
254
moon sync codeowners
255
```
256

257
### Workspace Templates
258

259
Manage code generation templates for scaffolding.
260

261
```bash { .api }
262
/**
263
 * Manage workspace templates for code generation
264
 * Templates enable consistent project scaffolding
265
 */
266
moon templates
267

268
# Template operations:
269
# - List available templates
270
# - Validate template configurations
271
# - Create new templates
272
```
273

274
### Generation and Scaffolding
275

276
Generate new projects and code using templates.
277

278
```bash { .api }
279
/**
280
 * Scaffold new code using configured templates
281
 * Creates projects, components, or other code structures
282
 */
283
moon generate <template> [dest]
284

285
# Arguments:
286
# <template>    Name of template to use
287
# [dest]        Destination path (optional)
288

289
# Options:
290
--dryRun           Show what would be generated without creating files
291
--force            Overwrite existing files if they exist
292
--template <path>  Use template from specific path instead of workspace templates
293
```
294

295
**Usage Examples:**
296

297
```bash
298
# Generate new project using template
299
moon generate react-app apps/new-app
300

301
# Preview generation without creating files
302
moon generate node-lib --dryRun
303

304
# Generate from custom template path
305
moon generate custom --template ./templates/my-template
306

307
# Force overwrite existing files
308
moon generate component --force
309
```
310

311
## Project Configuration
312

313
### Workspace Configuration
314

315
Projects are discovered and configured through workspace settings:
316

317
```yaml
318
# .moon/workspace.yml
319
projects:
320
  - 'apps/*'           # Glob patterns for project discovery
321
  - 'packages/*'
322
  - 'tools/*'
323

324
# Project aliases for easier reference
325
aliases:
326
  fe: 'frontend-app'
327
  be: 'backend-api'
328
```
329

330
### Project Metadata
331

332
Individual projects can define metadata and configuration:
333

334
```yaml
335
# moon.yml (in project directory)
336
type: 'application'      # Project type
337
language: 'typescript'   # Primary language
338

339
# Project dependencies
340
dependsOn:
341
  - 'shared-lib'
342
  - 'common-utils'
343

344
# Project tags for grouping
345
tags:
346
  - 'frontend'
347
  - 'customer-facing'
348

349
# Task definitions
350
tasks:
351
  build:
352
    command: 'tsc'
353
    inputs: ['src/**/*']
354
    outputs: ['dist/**/*']
355
```
356

357
## Error Handling
358

359
Common project management scenarios and solutions:
360

361
- **Project Discovery Issues**: Check workspace.yml patterns and ensure projects have moon.yml files
362
- **Circular Dependencies**: Use project-graph to identify and resolve circular references
363
- **Missing Dependencies**: Sync command updates project dependencies based on actual code imports
364
- **Configuration Conflicts**: Check for conflicting task definitions or project settings
365
- **Performance Issues**: Use --summary to identify slow projects and optimize configurations