infra Role Design: Commands, Semantics, and Parameters Specification

[deepracticexs]

Overview

Define the complete command structure for the infra (Infrastructure Engineer) role following the four-layer semantic structure from Issue #12.

Role Definition: infra represents the Infrastructure/Platform Engineer responsible for:

• Project scaffolding and initialization
• Monorepo structure management
• Workspace setup (apps, services, packages)
• Development environment configuration

Command Pattern:

nodespec infra [domain] [action] [object?] [...args]

---

Domain: monorepo

Monorepo-level operations, working at project root (./)

Commands

nodespec infra monorepo init [name?]

Initialize a new monorepo in current directory or create a new directory

Parameters:

• [name] - Optional project name. If provided, creates new directory
• --template <template> - Template to use (default: basic)
• --package-manager <pm> - Package manager (default: pnpm)

Examples:

nodespec infra monorepo init                    # Init in current dir
nodespec infra monorepo init my-project         # Create my-project/
nodespec infra monorepo init --template full    # Use full template

---

nodespec infra monorepo info

Display monorepo information

Parameters:

• --verbose, -v - Show detailed information

Examples:

nodespec infra monorepo info
nodespec infra monorepo info --verbose

---

nodespec infra monorepo validate

Validate monorepo structure and configuration

Parameters:

• --fix - Auto-fix issues if possible

Examples:

nodespec infra monorepo validate
nodespec infra monorepo validate --fix

---

Domain: app

Application workspace operations, working in apps/ directory

Commands

nodespec infra app add <name>

Add a new application to the monorepo

Parameters:

• <name> - Required app name (will be used as directory name if no scope)
• --package-name <name> - Full package name with scope (e.g., @myproject/cli)
• --template <template> - Template to use (default: cli)

Examples:

nodespec infra app add my-cli
nodespec infra app add my-cli --package-name @myproject/cli
nodespec infra app add web --template react

---

nodespec infra app list

List all applications in the monorepo

Parameters:

• --verbose, -v - Show detailed information (location, version, dependencies)

Examples:

nodespec infra app list
nodespec infra app list --verbose

---

nodespec infra app remove <name>

Remove an application from the monorepo

Parameters:

• <name> - Required app name or package name
• --force, -f - Skip confirmation prompt

Examples:

nodespec infra app remove my-cli
nodespec infra app remove @myproject/cli --force

---

nodespec infra app validate <name?>

Validate application structure and configuration

Parameters:

• <name> - Optional app name. If omitted, validates all apps
• --fix - Auto-fix issues if possible

Examples:

nodespec infra app validate              # Validate all apps
nodespec infra app validate my-cli       # Validate specific app
nodespec infra app validate my-cli --fix

---

Domain: service

Service workspace operations, working in services/ directory

Commands

nodespec infra service add <name>

Add a new service to the monorepo

Parameters:

• <name> - Required service name
• --package-name <name> - Full package name with scope
• --template <template> - Template to use (default: express)
• --port <port> - Default port number

Examples:

nodespec infra service add api-gateway
nodespec infra service add api-gateway --package-name @myproject/api-gateway
nodespec infra service add auth --template fastify --port 3001

---

nodespec infra service list

List all services in the monorepo

Parameters:

• --verbose, -v - Show detailed information

Examples:

nodespec infra service list
nodespec infra service list --verbose

---

nodespec infra service remove <name>

Remove a service from the monorepo

Parameters:

• <name> - Required service name or package name
• --force, -f - Skip confirmation prompt

Examples:

nodespec infra service remove api-gateway
nodespec infra service remove @myproject/api-gateway --force

---

nodespec infra service validate <name?>

Validate service structure and configuration

Parameters:

• <name> - Optional service name. If omitted, validates all services
• --fix - Auto-fix issues if possible

Examples:

nodespec infra service validate
nodespec infra service validate api-gateway --fix

---

Domain: package

Package workspace operations, working in packages/ directory

Commands

nodespec infra package add <name>

Add a new package to the monorepo

Parameters:

• <name> - Required package name
• --package-name <name> - Full package name with scope
• --template <template> - Template to use (default: lib)

Examples:

nodespec infra package add my-lib
nodespec infra package add utils --package-name @myproject/utils
nodespec infra package add config --template tsconfig

---

nodespec infra package list

List all packages in the monorepo

Parameters:

• --verbose, -v - Show detailed information

Examples:

nodespec infra package list
nodespec infra package list --verbose

---

nodespec infra package remove <name>

Remove a package from the monorepo

Parameters:

• <name> - Required package name or package name
• --force, -f - Skip confirmation prompt

Examples:

nodespec infra package remove my-lib
nodespec infra package remove @myproject/utils --force

---

nodespec infra package validate <name?>

Validate package structure and configuration

Parameters:

• <name> - Optional package name. If omitted, validates all packages
• --fix - Auto-fix issues if possible

Examples:

nodespec infra package validate
nodespec infra package validate my-lib --fix

---

Domain: config

Configuration workspace operations, working in packages/ directory (config packages)

Commands

nodespec infra config init <type>

Initialize a configuration package

Parameters:

• <type> - Required config type: eslint, prettier, typescript, vitest, tsup, etc.
• --package-name <name> - Full package name with scope

Examples:

nodespec infra config init eslint
nodespec infra config init typescript --package-name @myproject/typescript-config

---

nodespec infra config list

List all configuration packages

Parameters:

• --verbose, -v - Show detailed information

Examples:

nodespec infra config list
nodespec infra config list --verbose

---

nodespec infra config validate <type?>

Validate configuration package

Parameters:

• <type> - Optional config type. If omitted, validates all config packages
• --fix - Auto-fix issues if possible

Examples:

nodespec infra config validate
nodespec infra config validate eslint --fix

---

Design Principles

Following Issue #12:

1. Four-layer semantic structure: [role] [domain] [action] [object?] [...args]
2. Domain maps to directory structure: Clear workspace boundaries
3. Consistent action verbs: Same action means same behavior across domains
4. Optional object parameter: Depends on action semantics
5. AI-first design: Predictable patterns, explicit semantics

Related Issues

• CLI Design Principles: Four-Layer Semantic Structure for AI-First Development #12 - CLI Design Principles: Four-Layer Semantic Structure
• Three-layer CLI command structure: optimized for AI pattern recognition #11 - Original CLI structure discussion

Implementation Notes

• All commands should be implemented with corresponding BDD feature files
• Feature file structure: features/infra/[domain]/[action]/[action].feature
• Validate monorepo context before executing domain commands
• Consistent error messages and user feedback

[deepracticexs]

Semantic Corrections Required

During feature refactoring, two semantic discrepancies were identified that need to be resolved:

1. Add monorepo create Command

Add this command to the Domain: monorepo section, after the init command:

---

nodespec infra monorepo create <name>

Create a new monorepo in a new directory

Parameters:

• <name> - Required project name. Creates new directory with this name
• --template <template> - Template to use (default: basic)
• --package-manager <pm> - Package manager (default: pnpm)

Examples:
```bash
nodespec infra monorepo create my-project
nodespec infra monorepo create my-project --template full
```

Note: This command creates a new directory and initializes the monorepo inside it. Use init to initialize in the current directory.

---

2. Update config init Command

Replace the existing config init command specification with:

---

nodespec infra config init [preset?]

Initialize all configuration packages at once

Parameters:

• [preset] - Optional preset type: basic, strict, recommended (default: recommended)
• --skip-eslint - Skip ESLint configuration
• --skip-prettier - Skip Prettier configuration
• --skip-typescript - Skip TypeScript configuration
• --skip-editorconfig - Skip EditorConfig
• --skip-gitignore - Skip .gitignore

Examples:
```bash
nodespec infra config init # Init all configs with recommended preset
nodespec infra config init strict # Init all configs with strict preset
nodespec infra config init --skip-eslint # Init all except ESLint
```

Note: This command initializes all configuration files at once. Use --skip-* flags to selectively exclude specific tools.

---

Rationale

1. monorepo create: Separates the "create new directory" semantics from init (which works in current directory). This makes the command intent clearer and follows common CLI patterns.

2. config init: Changes from initializing a single config type to initializing all configs at once with preset support. This is more aligned with typical monorepo setup workflows where all configurations are initialized together.