Devian v10 — Workspace Manager

Enforces single workspace structure and npm policies for Devian TypeScript projects (v10). Ensures proper dependency installation, workspace configuration, and build script execution.

What This Skill Does

This skill helps you maintain a strict monorepo workspace structure for Devian TypeScript projects. It prevents common mistakes like installing dependencies in subfolders, ensures the correct workspace root is used, and provides centralized npm script execution for builds, archives, and development servers.

Hard Rules (MUST Follow)

1. Single Workspace Root

2. Subfolder Install Prohibition

NEVER run `npm install` directly in subfolders (`module/*`, `apps/*`, `tools/*`). Always execute from `framework-ts/` root.

Step-by-Step Instructions

1. Verify Workspace Structure

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

```bash

Check that workspace root exists

test -f framework-ts/package.json && echo "✓ Workspace root found" || echo "✗ Missing workspace root"

Check for invalid node_modules in subfolders

find framework-ts/{module,apps,tools} -name "node_modules" -type d 2>/dev/null && echo "✗ Invalid node_modules found" || echo "✓ Clean structure"

Check for invalid lockfiles in subfolders

find framework-ts/{module,apps,tools} -name "package-lock.json" 2>/dev/null && echo "✗ Invalid lockfiles found" || echo "✓ Clean lockfiles"

```

2. Install Dependencies (Root Only)

Always install dependencies from the workspace root:

```bash

cd framework-ts

npm install

```

For CI/CD environments, use `npm ci`:

```bash

cd framework-ts

npm ci

```

3. Execute Workspace Scripts

Use the centralized scripts defined in root `package.json`:

**Build with Builder Tool:**

```bash

cd framework-ts

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

```

**Archive Project:**

```bash

cd framework-ts

npm run archive -- <archive-args>

```

**Start Client Development Server:**

```bash

cd framework-ts

npm run dev:client

```

**Start Game Server:**

```bash

cd framework-ts

npm run start:server

```

4. Add New Dependencies

When adding dependencies to any workspace package:

```bash

From workspace root

cd framework-ts

Add to specific workspace

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

Examples:

npm install lodash -w game-client

npm install express -w game-server

npm install typescript -D -w builder

```

5. Recovery from Lockfile Corruption

If `package-lock.json` becomes corrupted or out of sync:

```bash

cd framework-ts

rm -rf node_modules package-lock.json

npm install

```

Root package.json Structure

The workspace root must have this 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` should configure module resolution with path aliases:

```json

{

"compilerOptions": {

"target": "ES2020",

"module": "ESNext",

"moduleResolution": "node",

"baseUrl": ".",

"paths": {

"@devian/core": ["./module/devian/src"]

}

}

}

```

Common Workspace Commands Reference

| Command | Purpose |

|---------|---------|

| `npm run builder -- ../input/input_common.json` | Execute build with input JSON |

| `npm run archive -- <args>` | Create project archive |

| `npm run dev:client` | Start client dev server |

| `npm run start:server` | Launch game server |

| `npm install <pkg> -w <workspace>` | Add dependency to specific workspace |

| `npm ci` | Clean install (CI/CD) |

Validation Checklist

Before committing changes or running builds, verify:

Important Notes

Related Skills