neutrinos-cli 2.0.0-beta.2 → 2.0.0-beta.3

package/README.md

@@ -40,6 +40,7 @@ neutrinos <command> [options]
 | `publish [name]` | Bundle and publish a package |
 | `deprecate [name]` | Deprecate a published package |
 | `auth` | Login or check auth state |
+| `doctor` | Check workspace health (`--fix` to auto-repair) |
 | `completion <shell>` | Output shell completion script (`bash` or `zsh`) |
 
 ### `new <name>`
@@ -106,6 +107,28 @@ neutrinos deprecate [name] [-y] [--all]
 
 Marks a published package as deprecated. Prompts for confirmation unless `-y` is passed.
 
+### `doctor`
+
+```sh
+neutrinos doctor        # Run all health checks
+neutrinos doctor --fix  # Auto-fix what it can
+```
+
+Runs 10 workspace health checks and reports pass/warn/fail for each:
+
+- `node_modules` — Dependencies installed
+- `plugin.json` — Exists with required fields (`name`, `components.selectorPrefix`, `modules.idPrefix`)
+- `package.json` — Has `workspaces`, `type: "module"`, expected dependencies
+- `tsconfig.json` — Exists and is valid (verified via `tsc --showConfig`)
+- `plugins-server/` — Directory exists with `index.js`
+- Package `alpha` block — Each package has `alpha.component` or `alpha.module`
+- Component entry file — Component packages have a matching `<name>.ts` file
+- Node version — Meets `>=22` requirement
+- Auth state — Token file exists and is not expired
+- Lock file sync — Lock file is up to date with `package.json`
+
+`--fix` auto-repairs: missing `node_modules` (runs install), `plugin.json` defaults, `workspaces`/`type` in `package.json`, `plugins-server/` from template, missing `alpha` blocks, stale lock files.
+
 ### `auth`
 
 ```sh

package/dist/src/bin/cli.js

@@ -27,6 +27,7 @@ import { createWorkspace } from '../commands/new-workspace.js';
 import { publish } from '../commands/publish.js';
 import { startPluginsServer } from '../commands/serve.js';
 import { completion } from '../commands/completion.js';
+import { doctor } from '../commands/doctor.js';
 import { getPackages } from '../utils/get-packages.js';
 import { validateWorkspace } from '../utils/check-valid-ws.js';
 import { done, failed, inprogress, log } from '../utils/logger.js';
@@ -192,6 +193,13 @@ export const createProgram = () => {
         .action((shell) => {
         completion(program, shell);
     });
+    program
+        .command('doctor')
+        .description('Check workspace health')
+        .option('--fix', 'Auto-fix issues where possible')
+        .action((options) => {
+        doctor(cwd(), options);
+    });
     program
         .command('__list-packages', { hidden: true })
         .description('List workspace package names (used by shell completion)')
@@ -209,7 +217,7 @@ export const createProgram = () => {
     });
     program.hook('preAction', async (_thisCmd, actionCmd) => {
         const cmd = actionCmd.name();
-        if (cmd === 'new' || cmd === 'login' || cmd === 'completion' || cmd === '__list-packages') {
+        if (cmd === 'new' || cmd === 'login' || cmd === 'completion' || cmd === '__list-packages' || cmd === 'doctor') {
             return;
         }
         if (!validateWorkspace(cwd())) {

package/dist/src/commands/doctor.js

@@ -0,0 +1,69 @@
+import { bold, greenBright, red, yellowBright } from 'colorette';
+import { log as _log } from 'node:console';
+import { checks } from '../utils/doctor-checks.js';
+const SYMBOLS = {
+    pass: greenBright('✔'),
+    warn: yellowBright('⚠'),
+    fail: red('✖'),
+};
+const colorize = {
+    pass: greenBright,
+    warn: yellowBright,
+    fail: red,
+};
+function printResult(result) {
+    const sym = SYMBOLS[result.status];
+    const color = colorize[result.status];
+    _log(`  ${sym} ${color(`${result.name} — ${result.message}`)}`);
+}
+function printFixedResult(before, after) {
+    _log(`  ${red('✖')} → ${greenBright('✔')} ${greenBright(`${after.name} — Fixed: ${after.message}`)}`);
+}
+export function doctor(wsPath, opts) {
+    _log('\nWorkspace Health Check');
+    _log('──────────────────────\n');
+    let results = [];
+    for (const check of checks) {
+        const checkResults = check.run(wsPath);
+        results.push(...checkResults);
+    }
+    for (const r of results) {
+        printResult(r);
+    }
+    if (opts.fix) {
+        const fixableFailures = results.filter((r) => r.status === 'fail' && r.fixable);
+        if (fixableFailures.length > 0) {
+            _log('');
+            for (const check of checks) {
+                if (!check.fix)
+                    continue;
+                const checkResults = check.run(wsPath);
+                const hasFixableFailure = checkResults.some((r) => r.status === 'fail' && r.fixable);
+                if (!hasFixableFailure)
+                    continue;
+                check.fix(wsPath);
+                const afterResults = check.run(wsPath);
+                for (let i = 0; i < checkResults.length; i++) {
+                    const before = checkResults[i];
+                    const after = afterResults[i];
+                    if (before.status === 'fail' && after && after.status === 'pass') {
+                        printFixedResult(before, after);
+                        const idx = results.findIndex((r) => r.name === before.name && r.status === 'fail');
+                        if (idx !== -1) {
+                            results[idx] = after;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const passed = results.filter((r) => r.status === 'pass').length;
+    const warned = results.filter((r) => r.status === 'warn').length;
+    const failed = results.filter((r) => r.status === 'fail').length;
+    _log('\n──────────────────────');
+    _log(bold(`Summary: ${greenBright(`${passed} passed`)}, ${yellowBright(`${warned} warnings`)}, ${red(`${failed} failed`)}`));
+    _log('');
+    if (failed > 0) {
+        process.exit(1);
+    }
+}

package/dist/src/types/doctor.js

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/doctor-checks.js

@@ -0,0 +1,357 @@
+import { execSync } from 'node:child_process';
+import { cpSync, existsSync, globSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { authConfigJson, pluginJsonPath, pluginServerRoot, pluginServerTemplatesPath } from './path-utils.js';
+import { getGeneratedComponentName } from './path-utils.js';
+// ── Check 0: node_modules ──────────────────────────────────────────────
+const nodeModulesCheck = {
+    name: 'node_modules',
+    run(wsPath) {
+        if (!existsSync(join(wsPath, 'node_modules'))) {
+            return [{ name: 'node_modules', status: 'fail', message: 'Not installed. Run "npm install" or "pnpm install"', fixable: true }];
+        }
+        return [{ name: 'node_modules', status: 'pass', message: 'Dependencies installed', fixable: false }];
+    },
+    fix(wsPath) {
+        const pnpmLock = join(wsPath, 'pnpm-lock.yaml');
+        const manager = existsSync(pnpmLock) ? 'pnpm' : 'npm';
+        execSync(`${manager} install`, { cwd: wsPath, stdio: 'inherit' });
+    },
+};
+// ── Check 1: plugin.json ───────────────────────────────────────────────
+const pluginJsonCheck = {
+    name: 'plugin.json',
+    run(wsPath) {
+        const path = pluginJsonPath(wsPath);
+        if (!existsSync(path)) {
+            return [{ name: 'plugin.json', status: 'fail', message: 'File is missing', fixable: true }];
+        }
+        let json;
+        try {
+            json = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            return [{ name: 'plugin.json', status: 'fail', message: 'File is not valid JSON', fixable: false }];
+        }
+        const missing = [];
+        if (!json.name)
+            missing.push('name');
+        if (!json.components?.selectorPrefix)
+            missing.push('components.selectorPrefix');
+        if (!json.modules?.idPrefix)
+            missing.push('modules.idPrefix');
+        if (missing.length > 0) {
+            return [{ name: 'plugin.json', status: 'fail', message: `Missing required fields: ${missing.join(', ')}`, fixable: true }];
+        }
+        return [{ name: 'plugin.json', status: 'pass', message: 'All required fields present', fixable: false }];
+    },
+    fix(wsPath) {
+        const path = pluginJsonPath(wsPath);
+        const defaults = {
+            name: basename(wsPath),
+            components: { selectorPrefix: 'comp' },
+            modules: { idPrefix: 'mod' },
+        };
+        if (!existsSync(path)) {
+            writeFileSync(path, JSON.stringify(defaults, null, 4) + '\n');
+            return;
+        }
+        let existing = {};
+        try {
+            existing = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            writeFileSync(path, JSON.stringify(defaults, null, 4) + '\n');
+            return;
+        }
+        existing.name ??= defaults.name;
+        existing.components ??= {};
+        existing.components.selectorPrefix ??= defaults.components.selectorPrefix;
+        existing.modules ??= {};
+        existing.modules.idPrefix ??= defaults.modules.idPrefix;
+        writeFileSync(path, JSON.stringify(existing, null, 4) + '\n');
+    },
+};
+// ── Check 2: Root package.json ─────────────────────────────────────────
+const rootPackageJsonCheck = {
+    name: 'Root package.json',
+    run(wsPath) {
+        const path = join(wsPath, 'package.json');
+        if (!existsSync(path)) {
+            return [{ name: 'Root package.json', status: 'fail', message: 'File is missing', fixable: false }];
+        }
+        let json;
+        try {
+            json = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            return [{ name: 'Root package.json', status: 'fail', message: 'File is not valid JSON', fixable: false }];
+        }
+        const issues = [];
+        if (!json['workspaces'])
+            issues.push('workspaces');
+        if (json['type'] !== 'module')
+            issues.push('type: "module"');
+        const deps = (json['dependencies'] ?? {});
+        if (!deps['@jatahworx/alpha-annotations-lib'])
+            issues.push('dependency @jatahworx/alpha-annotations-lib');
+        const devDeps = (json['devDependencies'] ?? {});
+        if (!devDeps['lit'])
+            issues.push('devDependency lit');
+        if (!devDeps['typescript'])
+            issues.push('devDependency typescript');
+        if (issues.length > 0) {
+            const fixable = issues.includes('workspaces') || issues.includes('type: "module"');
+            return [{ name: 'Root package.json', status: 'fail', message: `Missing: ${issues.join(', ')}`, fixable }];
+        }
+        return [{ name: 'Root package.json', status: 'pass', message: 'workspaces, dependencies, and type configured', fixable: false }];
+    },
+    fix(wsPath) {
+        const path = join(wsPath, 'package.json');
+        if (!existsSync(path))
+            return;
+        let json;
+        try {
+            json = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            return;
+        }
+        json['workspaces'] ??= ['packages/*'];
+        json['type'] ??= 'module';
+        writeFileSync(path, JSON.stringify(json, null, 4) + '\n');
+    },
+};
+// ── Check 3: tsconfig.json ─────────────────────────────────────────────
+const tsconfigCheck = {
+    name: 'tsconfig.json',
+    run(wsPath) {
+        const path = join(wsPath, 'tsconfig.json');
+        if (!existsSync(path)) {
+            return [{ name: 'tsconfig.json', status: 'fail', message: 'File is missing. Create a tsconfig.json', fixable: false }];
+        }
+        try {
+            execSync('npx tsc --showConfig', { cwd: wsPath, stdio: 'pipe', timeout: 15_000 });
+        }
+        catch (err) {
+            const stderr = err instanceof Error && 'stderr' in err
+                ? String(err.stderr).trim()
+                : '';
+            if (stderr.includes('ENOENT') || stderr.includes('not found') || !stderr) {
+                return [{ name: 'tsconfig.json', status: 'warn', message: 'File exists but could not run tsc to validate. Ensure typescript is installed', fixable: false }];
+            }
+            return [{ name: 'tsconfig.json', status: 'fail', message: `Invalid config: ${stderr}`, fixable: false }];
+        }
+        return [{ name: 'tsconfig.json', status: 'pass', message: 'Valid configuration', fixable: false }];
+    },
+};
+// ── Check 4: plugins-server/ ───────────────────────────────────────────
+const pluginsServerCheck = {
+    name: 'plugins-server/',
+    run(wsPath) {
+        const serverDir = pluginServerRoot(wsPath);
+        if (!existsSync(serverDir)) {
+            return [{ name: 'plugins-server/', status: 'fail', message: 'Directory is missing', fixable: true }];
+        }
+        if (!existsSync(join(serverDir, 'index.js'))) {
+            return [{ name: 'plugins-server/', status: 'fail', message: 'Directory exists but index.js is missing', fixable: true }];
+        }
+        return [{ name: 'plugins-server/', status: 'pass', message: 'Directory exists with index.js', fixable: false }];
+    },
+    fix(wsPath) {
+        const serverDir = pluginServerRoot(wsPath);
+        const templateDir = pluginServerTemplatesPath();
+        cpSync(templateDir, serverDir, { recursive: true });
+    },
+};
+// ── Check 5: Package alpha block ───────────────────────────────────────
+function getPackagesSafe(wsPath) {
+    try {
+        const packageJsonContent = readFileSync(join(wsPath, 'package.json'), 'utf-8');
+        const parsed = JSON.parse(packageJsonContent);
+        const packagesDir = parsed.workspaces ?? [];
+        const packageNames = globSync(packagesDir, { cwd: wsPath });
+        return packageNames
+            .map((name) => join(wsPath, name))
+            .filter((p) => existsSync(join(p, 'package.json')));
+    }
+    catch {
+        return null;
+    }
+}
+const packageAlphaBlockCheck = {
+    name: 'Package alpha block',
+    run(wsPath) {
+        const packages = getPackagesSafe(wsPath);
+        if (packages === null) {
+            return [{ name: 'Package alpha block', status: 'fail', message: 'Could not discover packages (missing package.json or workspaces)', fixable: false }];
+        }
+        if (packages.length === 0) {
+            return [{ name: 'Package alpha block', status: 'pass', message: 'No packages found (nothing to check)', fixable: false }];
+        }
+        const results = [];
+        for (const pkgPath of packages) {
+            const pkgJsonPath = join(pkgPath, 'package.json');
+            const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const pkgName = pkgJson.name || basename(pkgPath);
+            if (!pkgJson.alpha) {
+                results.push({
+                    name: `Package "${pkgName}" alpha block`,
+                    status: 'fail',
+                    message: 'No alpha block found. Add alpha.component or alpha.module',
+                    fixable: true,
+                });
+            }
+            else if (!pkgJson.alpha.component && !pkgJson.alpha.module) {
+                results.push({
+                    name: `Package "${pkgName}" alpha block`,
+                    status: 'warn',
+                    message: 'alpha block exists but neither component nor module is true',
+                    fixable: true,
+                });
+            }
+            else {
+                const type = pkgJson.alpha.component ? 'alpha.component' : 'alpha.module';
+                results.push({
+                    name: `Package "${pkgName}" alpha block`,
+                    status: 'pass',
+                    message: `${type} is set`,
+                    fixable: false,
+                });
+            }
+        }
+        return results;
+    },
+    fix(wsPath) {
+        const packages = getPackagesSafe(wsPath);
+        if (!packages)
+            return;
+        for (const pkgPath of packages) {
+            const pkgJsonPath = join(pkgPath, 'package.json');
+            const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const alpha = (pkgJson['alpha'] ?? {});
+            if (!alpha['component'] && !alpha['module']) {
+                alpha['component'] = true;
+            }
+            pkgJson['alpha'] = alpha;
+            writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 4) + '\n');
+        }
+    },
+};
+// ── Check 6: Component entry file ──────────────────────────────────────
+const componentEntryFileCheck = {
+    name: 'Component entry file',
+    run(wsPath) {
+        const packages = getPackagesSafe(wsPath);
+        if (packages === null) {
+            return [{ name: 'Component entry file', status: 'fail', message: 'Could not discover packages', fixable: false }];
+        }
+        const results = [];
+        for (const pkgPath of packages) {
+            const pkgJsonPath = join(pkgPath, 'package.json');
+            const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            if (!pkgJson.alpha?.component)
+                continue;
+            const pkgName = pkgJson.name || basename(pkgPath);
+            const entryName = getGeneratedComponentName(basename(pkgPath));
+            const entryFile = join(pkgPath, `${entryName}.ts`);
+            if (!existsSync(entryFile)) {
+                results.push({
+                    name: `Package "${pkgName}" entry file`,
+                    status: 'fail',
+                    message: `${entryName}.ts is missing`,
+                    fixable: false,
+                });
+            }
+            else {
+                results.push({
+                    name: `Package "${pkgName}" entry file`,
+                    status: 'pass',
+                    message: `${entryName}.ts exists`,
+                    fixable: false,
+                });
+            }
+        }
+        return results;
+    },
+};
+// ── Check 7: Node version ──────────────────────────────────────────────
+const nodeVersionCheck = {
+    name: 'Node version',
+    run() {
+        const [major] = process.versions.node.split('.').map(Number);
+        if (major < 22) {
+            return [{ name: 'Node version', status: 'fail', message: `v${process.versions.node} does not meet requirement (>=22). Install Node.js 22+`, fixable: false }];
+        }
+        return [{ name: 'Node version', status: 'pass', message: `v${process.versions.node} meets requirement (>=22)`, fixable: false }];
+    },
+};
+// ── Check 8: Auth state ────────────────────────────────────────────────
+const authStateCheck = {
+    name: 'Auth state',
+    run() {
+        const authPath = authConfigJson();
+        if (!existsSync(authPath)) {
+            return [{ name: 'Auth state', status: 'fail', message: `${authPath} not found. Run "neutrinos auth login"`, fixable: false }];
+        }
+        try {
+            const tokenSet = JSON.parse(readFileSync(authPath, 'utf-8'));
+            if (tokenSet.expires_at && tokenSet.expires_at < Date.now() / 1000) {
+                return [{ name: 'Auth state', status: 'warn', message: 'Token expired. Run "neutrinos auth login"', fixable: false }];
+            }
+        }
+        catch {
+            return [{ name: 'Auth state', status: 'warn', message: 'Could not parse auth.json', fixable: false }];
+        }
+        return [{ name: 'Auth state', status: 'pass', message: 'Token present and valid', fixable: false }];
+    },
+};
+// ── Check 9: Lock file sync ───────────────────────────────────────────
+const lockFileSyncCheck = {
+    name: 'Lock file sync',
+    run(wsPath) {
+        const packageJsonPath = join(wsPath, 'package.json');
+        if (!existsSync(packageJsonPath)) {
+            return [{ name: 'Lock file sync', status: 'fail', message: 'No package.json to compare against', fixable: false }];
+        }
+        const pnpmLock = join(wsPath, 'pnpm-lock.yaml');
+        const npmLock = join(wsPath, 'package-lock.json');
+        let lockPath = null;
+        let manager = 'npm';
+        if (existsSync(pnpmLock)) {
+            lockPath = pnpmLock;
+            manager = 'pnpm';
+        }
+        else if (existsSync(npmLock)) {
+            lockPath = npmLock;
+            manager = 'npm';
+        }
+        if (!lockPath) {
+            return [{ name: 'Lock file sync', status: 'fail', message: 'No lock file found. Run "npm install" or "pnpm install"', fixable: true }];
+        }
+        const lockMtime = statSync(lockPath).mtimeMs;
+        const pkgMtime = statSync(packageJsonPath).mtimeMs;
+        if (pkgMtime > lockMtime) {
+            return [{ name: 'Lock file sync', status: 'warn', message: `package.json is newer than lock file. Run "${manager} install"`, fixable: true }];
+        }
+        return [{ name: 'Lock file sync', status: 'pass', message: 'Lock file is up to date', fixable: false }];
+    },
+    fix(wsPath) {
+        const pnpmLock = join(wsPath, 'pnpm-lock.yaml');
+        const manager = existsSync(pnpmLock) ? 'pnpm' : 'npm';
+        execSync(`${manager} install`, { cwd: wsPath, stdio: 'inherit' });
+    },
+};
+// ── Export all checks ──────────────────────────────────────────────────
+export const checks = [
+    nodeModulesCheck,
+    pluginJsonCheck,
+    rootPackageJsonCheck,
+    tsconfigCheck,
+    pluginsServerCheck,
+    packageAlphaBlockCheck,
+    componentEntryFileCheck,
+    nodeVersionCheck,
+    authStateCheck,
+    lockFileSyncCheck,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neutrinos-cli",
-    "version": "2.0.0-beta.2",
+    "version": "2.0.0-beta.3",
     "type": "module",
     "bin": {
         "neutrinos": "./dist/src/bin/cli.js"