Devian v10 Workspace Management

A skill for managing Devian TypeScript projects with strict single workspace root architecture and npm workspace policies.

Overview

This skill enforces the workspace structure for Devian v10 TypeScript projects, ensuring proper dependency management, preventing fragmented installations, and maintaining a single source of truth for package management at the framework root level.

When to Use This Skill

Core Principles

Single Workspace Root Rule

The project MUST maintain exactly one workspace root:

Installation Policy

**CRITICAL**: Never run `npm install` in subdirectories (`module/*`, `apps/*`, `tools/*`). All npm commands MUST be executed from `framework-ts/` root.

Step-by-Step Instructions

1. Verify Workspace Structure

When working with a Devian v10 project, first verify the structure:

```bash

Check that you're in the framework-ts directory

pwd # Should end with /framework-ts

Verify workspace root package.json exists

cat package.json | grep '"workspaces"'

Confirm no rogue node_modules in subdirectories

find . -name "node_modules" -type d | grep -v "^\./node_modules$"

```

If any node_modules exist outside `./node_modules`, remove them immediately.

2. Install Dependencies (Clean Install)

For CI/CD or clean environments:

```bash

cd framework-ts

npm ci

```

For development or initial setup:

```bash

cd framework-ts

npm install

```

3. Run Workspace Scripts

Use the predefined workspace scripts from root:

**Build System**:

```bash

npm run builder -- ../input/input_common.json

```

**Archive Project**:

```bash

npm run archive -- <archive-args>

```

**Development Server (Client)**:

```bash

npm run dev:client

```

**Game Server**:

```bash

npm run start:server

```

4. Add Dependencies

Always add dependencies from the workspace root:

**For workspace package**:

```bash

cd framework-ts

npm install <package-name> -w <workspace-name>

```

**For root**:

```bash

cd framework-ts

npm install <package-name>

```

5. Recovery from Corrupted State

If lockfile or node_modules are corrupted:

```bash

cd framework-ts

rm -rf node_modules package-lock.json

npm install

```

After recovery, verify all workspace packages can resolve dependencies.

Configuration Reference

Root package.json Structure

```json

{

"name": "devian-framework-ts",

"version": "10.0.0",

"type": "module",

"private": true,

"workspaces": [

"module/*",

"apps/*",

"tools/*"

],

"scripts": {

"builder": "npm -w builder run build --",

"archive": "npm -w archive run archive --",

"dev:client": "npm -w game-client run dev",

"start:server": "npm -w game-server run start"

}

}

```

TypeScript Configuration

The root `tsconfig.json` uses these critical settings:

Common Issues and Solutions

**Issue**: "Cannot find module" errors

**Solution**: Verify you ran `npm install` from `framework-ts/`, not a subdirectory

**Issue**: Multiple lockfiles exist

**Solution**: Remove all lockfiles except `framework-ts/package-lock.json`, then run `npm install` from root

**Issue**: Workspace script fails

**Solution**: Check that the target workspace exists in the workspaces array and has the corresponding script defined

**Issue**: Path alias not resolving

**Solution**: Verify `tsconfig.json` baseUrl is `.` and paths are correctly defined relative to workspace root

Integration Points

This skill integrates with:

Best Practices

1. **Always work from root**: Execute all npm commands from `framework-ts/`

2. **Use workspace scripts**: Leverage predefined scripts rather than direct workspace commands

3. **Verify before install**: Check existing structure before running any npm operations

4. **Clean recovery**: When in doubt, use the full recovery process (rm + npm install)

5. **CI/CD consistency**: Always use `npm ci` in automated environments

Constraints