@notur/sdk 1.4.6 → 1.4.7

package/README.md

@@ -145,6 +145,50 @@ Options:
 - `--with-api-routes` — include a client API route stub.
 - `--force` — allow writing into an existing empty directory.
 
+Frontend-only extensions are manifest-only by default. They do not need a PHP entrypoint unless you choose backend features such as API routes.
+
+### `notur-sync` — Sync generated metadata
+
+Reads `extension.yaml` and updates derived local development files.
+
+```bash
+npx notur-sync
+npx @notur/sdk sync
+```
+
+It keeps `package.json` name/version/scripts aligned, creates `.env.example` if missing, and creates `webpack.config.js` for frontend extensions that do not already have one.
+
+Options:
+- `--force-webpack` — regenerate `webpack.config.js` from `extension.yaml`.
+
+### `notur-validate` — Validate extension structure
+
+Runs local checks before packaging or pushing:
+
+```bash
+npx notur-validate
+npx @notur/sdk validate
+```
+
+Checks include manifest shape, id format, route file paths, bundle path, package metadata drift, missing scripts, `createExtension()` usage, and unknown slot IDs.
+
+Options:
+- `--strict` — treat warnings as errors.
+
+### `notur-doctor` — Diagnose local and remote setup
+
+Summarizes whether the local extension is buildable and ready to push:
+
+```bash
+npx notur-doctor
+npx @notur/sdk doctor
+```
+
+It checks manifest/package/build files, runs `notur-validate`, and verifies local `.env` or shell variables for remote push.
+
+Options:
+- `--no-remote` — skip remote host/key checks.
+
 ### `notur-pack` — Package extensions
 
 Creates a `.notur` archive (tar.gz) from your extension directory, ready to upload to the Pterodactyl admin panel.

package/bin/notur-create.js

@@ -281,11 +281,19 @@ function ensureTarget(target, force) {
     }
 }
 
-function manifestTemplate({ id, vendor, name, className, namespace, frontend, apiRoutes, display, description }) {
+function manifestTemplate({ id, className, namespace, frontend, apiRoutes, display, description, phpEntrypoint }) {
     const frontendSection = frontend
         ? `
 frontend:
   bundle: "resources/frontend/dist/extension.js"
+`
+        : '';
+    const phpSection = phpEntrypoint
+        ? `
+entrypoint: "${namespace.replace(/\\/g, '\\\\')}\\\\${className}"
+autoload:
+  psr-4:
+    "${namespace.replace(/\\/g, '\\\\')}\\\\": "src/"
 `
         : '';
     const backendSection = apiRoutes
@@ -302,16 +310,7 @@ name: "${yamlString(display)}"
 version: "1.0.0"
 description: "${yamlString(description)}"
 license: "MIT"
-
-requires:
-  notur: "^1.0"
-  pterodactyl: "^1.12"
-  php: "^8.2"
-
-entrypoint: "${namespace.replace(/\\/g, '\\\\')}\\\\${className}"
-autoload:
-  psr-4:
-    "${namespace.replace(/\\/g, '\\\\')}\\\\": "src/"
+${phpSection}
 ${backendSection}
 ${frontendSection}`;
 }
@@ -390,13 +389,16 @@ function packageTemplate(id) {
             dev: 'webpack-cli --mode development --watch --config webpack.config.js',
             pack: 'notur-pack',
             push: 'notur-push',
+            sync: 'notur-sync',
+            validate: 'notur-validate',
+            doctor: 'notur-doctor',
         },
         peerDependencies: {
             react: '^16.14.0',
             'react-dom': '^16.14.0',
         },
         devDependencies: {
-            '@notur/sdk': '^1.4.5',
+            '@notur/sdk': '^1.4.7',
             '@types/react': '^16.14.0',
             '@types/react-dom': '^16.9.0',
             react: '^16.14.0',
@@ -507,6 +509,7 @@ async function main() {
     const namespace = `${studly(vendor)}\\${studly(name)}`;
     const className = `${studly(name)}Extension`;
     const target = path.resolve(options.path, name);
+    const needsPhpEntrypoint = options.withApiRoutes;
 
     ensureTarget(target, options.force);
 
@@ -522,8 +525,11 @@ async function main() {
         apiRoutes: options.withApiRoutes,
         display: options.displayName || displayName(name),
         description: options.description || 'A Notur extension',
+        phpEntrypoint: needsPhpEntrypoint,
     }));
-    writeFile(path.join(target, 'src', `${className}.php`), phpTemplate({ namespace, className }));
+    if (needsPhpEntrypoint) {
+        writeFile(path.join(target, 'src', `${className}.php`), phpTemplate({ namespace, className }));
+    }
     if (options.withApiRoutes) {
         writeFile(path.join(target, 'src/routes/api-client.php'), apiRouteTemplate());
     }

package/bin/notur-doctor.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = { path: '.', remote: true };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--no-remote') {
+            options.remote = false;
+        } else if (arg === '--help' || arg === '-h') {
+            usage(0);
+        } else if (!arg.startsWith('-')) {
+            options.path = arg;
+        } else {
+            console.error(`Unknown argument: ${arg}`);
+            usage(1);
+        }
+    }
+    return options;
+}
+
+function usage(code) {
+    console.log(`Usage:
+  npx notur-doctor [path]
+  npx @notur/sdk doctor [path]
+
+Options:
+  --no-remote   Skip remote host/key checks`);
+    process.exit(code);
+}
+
+function parseEnv(basePath) {
+    const envPath = path.join(basePath, '.env');
+    if (!fs.existsSync(envPath)) return {};
+    const values = {};
+    for (const line of fs.readFileSync(envPath, 'utf8').split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (!match) continue;
+        values[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, '');
+    }
+    return values;
+}
+
+function check(label, ok, detail = '') {
+    const mark = ok ? 'ok' : 'fail';
+    console.log(`${mark}: ${label}${detail ? ` - ${detail}` : ''}`);
+    return ok;
+}
+
+function warn(label, ok, detail = '') {
+    const mark = ok ? 'ok' : 'warn';
+    console.log(`${mark}: ${label}${detail ? ` - ${detail}` : ''}`);
+    return ok;
+}
+
+function commandExists(command) {
+    const result = spawnSync(command, ['--version'], { stdio: 'ignore' });
+    return !result.error && result.status === 0;
+}
+
+function main() {
+    const options = parseArgs();
+    const basePath = path.resolve(options.path);
+    let ok = true;
+
+    console.log(`Notur doctor for ${basePath}`);
+
+    ok = check('extension directory exists', fs.existsSync(basePath) && fs.statSync(basePath).isDirectory()) && ok;
+    ok = check('extension.yaml exists', fs.existsSync(path.join(basePath, 'extension.yaml')) || fs.existsSync(path.join(basePath, 'extension.yml'))) && ok;
+
+    const packagePath = path.join(basePath, 'package.json');
+    const hasPackage = fs.existsSync(packagePath);
+    check('package.json exists', hasPackage);
+    if (hasPackage) {
+        const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        ok = check('build script', Boolean(pkg.scripts?.build)) && ok;
+        check('push script', Boolean(pkg.scripts?.push));
+        check('@notur/sdk dependency', Boolean(pkg.dependencies?.['@notur/sdk'] || pkg.devDependencies?.['@notur/sdk']));
+    }
+
+    check('node available', Boolean(process.version), process.version);
+    check('npm available', commandExists('npm'));
+    check('webpack config exists', fs.existsSync(path.join(basePath, 'webpack.config.js')));
+
+    const bundleCandidates = [
+        'resources/frontend/dist/extension.js',
+        'resources/frontend/dist/bundle.js',
+        'dist/extension.js',
+        'dist/bundle.js',
+    ];
+    warn('frontend bundle exists', bundleCandidates.some(file => fs.existsSync(path.join(basePath, file))), 'run npm run build before packaging');
+
+    const validateResult = spawnSync(process.execPath, [path.join(__dirname, 'notur-validate.js'), basePath], {
+        stdio: 'pipe',
+        encoding: 'utf8',
+    });
+    ok = check('notur validate', validateResult.status === 0) && ok;
+    if (validateResult.stdout.trim()) console.log(validateResult.stdout.trim());
+    if (validateResult.stderr.trim()) console.log(validateResult.stderr.trim());
+
+    if (options.remote) {
+        const env = parseEnv(basePath);
+        const host = process.env.NOTUR_HOST || env.NOTUR_HOST;
+        const key = process.env.NOTUR_PUSH_KEY || process.env.NOTUR_API_KEY || env.NOTUR_PUSH_KEY || env.NOTUR_API_KEY;
+        check('remote host configured', Boolean(host), host ? new URL(host).origin : '');
+        check('remote push key configured', Boolean(key));
+    }
+
+    if (!ok) {
+        console.error('Notur doctor found blocking issues.');
+        process.exit(1);
+    }
+
+    console.log('Notur doctor completed.');
+}
+
+main();

package/bin/notur-pack.js

@@ -257,13 +257,19 @@ async function pack(sourceDir, outputPath, options = {}) {
     ];
 
     if (options.dryRun) {
-        console.log('\nDry run mode (no archive written).');
-        console.log(`Would create: ${outputFullPath}`);
-        console.log(`Would include: ${archiveEntries.length} files`);
-        if (deterministicArgs.length > 0) {
-            console.log('Deterministic archive mode: enabled (GNU tar flags).');
-        } else {
-            console.log('Deterministic archive mode: not available (GNU tar not detected).');
+        try {
+            console.log('\nDry run mode (no archive written).');
+            console.log(`Would create: ${outputFullPath}`);
+            console.log(`Would include: ${archiveEntries.length} files`);
+            if (deterministicArgs.length > 0) {
+                console.log('Deterministic archive mode: enabled (GNU tar flags).');
+            } else {
+                console.log('Deterministic archive mode: not available (GNU tar not detected).');
+            }
+        } finally {
+            if (!checksumsExisted && fs.existsSync(checksumsPath)) {
+                fs.unlinkSync(checksumsPath);
+            }
         }
         return;
     }

package/bin/notur-sync.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {
+        path: '.',
+        forceWebpack: false,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--force-webpack') {
+            options.forceWebpack = true;
+        } else if (arg === '--help' || arg === '-h') {
+            usage(0);
+        } else if (!arg.startsWith('-')) {
+            options.path = arg;
+        } else {
+            console.error(`Unknown argument: ${arg}`);
+            usage(1);
+        }
+    }
+
+    return options;
+}
+
+function usage(code) {
+    console.log(`Usage:
+  npx notur-sync [path]
+  npx @notur/sdk sync [path]
+
+Options:
+  --force-webpack   Regenerate webpack.config.js from extension.yaml`);
+    process.exit(code);
+}
+
+function readManifest(extensionPath) {
+    const manifestPath = ['extension.yaml', 'extension.yml']
+        .map(file => path.join(extensionPath, file))
+        .find(file => fs.existsSync(file));
+
+    if (!manifestPath) {
+        console.error(`Error: extension.yaml not found in ${extensionPath}`);
+        process.exit(1);
+    }
+
+    const manifest = yaml.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (!manifest?.id || !manifest?.version) {
+        console.error('Error: extension.yaml must contain id and version.');
+        process.exit(1);
+    }
+
+    return manifest;
+}
+
+function packageName(id) {
+    return id.replace('/', '-');
+}
+
+function studly(value) {
+    return value
+        .split('-')
+        .filter(Boolean)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+
+function libraryName(id) {
+    return id
+        .split(/[\/-]/)
+        .filter(Boolean)
+        .map(studly)
+        .join('');
+}
+
+function bundlePath(manifest) {
+    return manifest?.frontend?.bundle || 'resources/frontend/dist/extension.js';
+}
+
+function syncPackageJson(extensionPath, manifest) {
+    const packagePath = path.join(extensionPath, 'package.json');
+    const current = fs.existsSync(packagePath)
+        ? JSON.parse(fs.readFileSync(packagePath, 'utf8'))
+        : {};
+
+    const next = {
+        ...current,
+        name: packageName(manifest.id),
+        version: manifest.version,
+        private: current.private ?? true,
+        scripts: {
+            ...(current.scripts || {}),
+            build: current.scripts?.build || 'webpack-cli --mode production --config webpack.config.js',
+            dev: current.scripts?.dev || 'webpack-cli --mode development --watch --config webpack.config.js',
+            pack: current.scripts?.pack || 'notur-pack',
+            push: current.scripts?.push || 'notur-push',
+            sync: current.scripts?.sync || 'notur-sync',
+            validate: current.scripts?.validate || 'notur-validate',
+            doctor: current.scripts?.doctor || 'notur-doctor',
+        },
+        peerDependencies: {
+            react: '^16.14.0',
+            'react-dom': '^16.14.0',
+            ...(current.peerDependencies || {}),
+        },
+        devDependencies: {
+            '@notur/sdk': '^1.4.7',
+            '@types/react': '^16.14.0',
+            '@types/react-dom': '^16.9.0',
+            react: '^16.14.0',
+            'react-dom': '^16.14.0',
+            'ts-loader': '^9.5.0',
+            typescript: '^5.3.0',
+            webpack: '^5.90.0',
+            'webpack-cli': '^6.0.0',
+            ...(current.devDependencies || {}),
+        },
+    };
+
+    fs.writeFileSync(packagePath, JSON.stringify(next, null, 2) + '\n');
+    console.log(`  synced ${path.relative(process.cwd(), packagePath)}`);
+}
+
+function webpackTemplate(manifest) {
+    const bundle = bundlePath(manifest);
+    const filename = path.basename(bundle);
+    const outputDir = path.dirname(bundle);
+
+    return `const path = require('path');
+const base = require('@notur/sdk/webpack.extension.config');
+
+module.exports = {
+    ...base,
+    entry: './resources/frontend/src/index.tsx',
+    output: {
+        ...base.output,
+        filename: '${filename}',
+        path: path.resolve(__dirname, '${outputDir.replace(/\\/g, '/')}'),
+        library: {
+            ...base.output.library,
+            name: '__NOTUR_EXT_${libraryName(manifest.id)}__',
+            type: 'umd',
+        },
+    },
+};
+`;
+}
+
+function syncWebpack(extensionPath, manifest, force) {
+    if (!manifest.frontend) {
+        return;
+    }
+
+    const webpackPath = path.join(extensionPath, 'webpack.config.js');
+    if (fs.existsSync(webpackPath) && !force) {
+        return;
+    }
+
+    fs.writeFileSync(webpackPath, webpackTemplate(manifest));
+    console.log(`  synced ${path.relative(process.cwd(), webpackPath)}`);
+}
+
+function syncEnvExample(extensionPath) {
+    const envExamplePath = path.join(extensionPath, '.env.example');
+    if (fs.existsSync(envExamplePath)) {
+        return;
+    }
+
+    fs.writeFileSync(envExamplePath, `NOTUR_HOST=https://panel.example.com
+NOTUR_PUSH_KEY=notur_xxx
+`);
+    console.log(`  synced ${path.relative(process.cwd(), envExamplePath)}`);
+}
+
+function main() {
+    const options = parseArgs();
+    const extensionPath = path.resolve(options.path);
+    if (!fs.existsSync(extensionPath) || !fs.statSync(extensionPath).isDirectory()) {
+        console.error(`Error: extension path does not exist: ${extensionPath}`);
+        process.exit(1);
+    }
+
+    const manifest = readManifest(extensionPath);
+    console.log(`Syncing ${manifest.id} from extension.yaml`);
+
+    if (manifest.frontend) {
+        syncPackageJson(extensionPath, manifest);
+        syncWebpack(extensionPath, manifest, options.forceWebpack);
+        syncEnvExample(extensionPath);
+    }
+
+    console.log('Done.');
+}
+
+main();

package/bin/notur-validate.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+const KNOWN_SLOTS = new Set([
+    'navbar', 'navbar.left', 'navbar.before', 'navbar.after',
+    'server.subnav', 'server.subnav.before', 'server.subnav.after', 'server.header', 'server.page', 'server.footer',
+    'server.terminal.buttons', 'server.console.header', 'server.console.info.before', 'server.console.info.after',
+    'server.console.sidebar', 'server.console.command', 'server.console.footer', 'server.files.actions',
+    'server.files.header', 'server.files.footer', 'server.files.dropdown', 'server.files.edit.before',
+    'server.files.edit.after', 'server.databases.before', 'server.databases.after', 'server.schedules.before',
+    'server.schedules.after', 'server.schedules.edit.before', 'server.schedules.edit.after', 'server.users.before',
+    'server.users.after', 'server.backups.before', 'server.backups.after', 'server.backups.dropdown',
+    'server.network.before', 'server.network.after', 'server.startup.before', 'server.startup.after',
+    'server.settings.before', 'server.settings.after', 'dashboard.header', 'dashboard.widgets',
+    'dashboard.serverlist.before', 'dashboard.serverlist.after', 'dashboard.serverrow.name.before',
+    'dashboard.serverrow.name.after', 'dashboard.serverrow.description.before', 'dashboard.serverrow.description.after',
+    'dashboard.serverrow.limits', 'dashboard.footer', 'dashboard.page', 'account.header', 'account.page',
+    'account.footer', 'account.subnav', 'account.subnav.before', 'account.subnav.after',
+    'account.overview.before', 'account.overview.after', 'account.api.before', 'account.api.after',
+    'account.ssh.before', 'account.ssh.after', 'auth.container.before', 'auth.container.after',
+]);
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = { path: '.', strict: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--strict') {
+            options.strict = true;
+        } else if (arg === '--help' || arg === '-h') {
+            usage(0);
+        } else if (!arg.startsWith('-')) {
+            options.path = arg;
+        } else {
+            console.error(`Unknown argument: ${arg}`);
+            usage(1);
+        }
+    }
+    return options;
+}
+
+function usage(code) {
+    console.log(`Usage:
+  npx notur-validate [path]
+  npx @notur/sdk validate [path]
+
+Options:
+  --strict   Treat warnings as errors`);
+    process.exit(code);
+}
+
+function readManifest(basePath, result) {
+    const manifestPath = ['extension.yaml', 'extension.yml']
+        .map(file => path.join(basePath, file))
+        .find(file => fs.existsSync(file));
+    if (!manifestPath) {
+        result.errors.push('extension.yaml not found.');
+        return null;
+    }
+
+    try {
+        return yaml.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (error) {
+        result.errors.push(`extension.yaml could not be parsed: ${error.message}`);
+        return null;
+    }
+}
+
+function validateManifest(basePath, manifest, result) {
+    if (!manifest) return;
+
+    for (const field of ['id', 'name', 'version']) {
+        if (!manifest[field]) {
+            result.errors.push(`extension.yaml is missing required field: ${field}`);
+        }
+    }
+
+    if (manifest.id && !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(manifest.id)) {
+        result.errors.push(`extension id "${manifest.id}" must use vendor/name with lowercase letters, numbers, and hyphens.`);
+    }
+
+    if (manifest.frontend?.bundle) {
+        const bundlePath = path.join(basePath, manifest.frontend.bundle);
+        if (!fs.existsSync(bundlePath)) {
+            result.warnings.push(`frontend.bundle does not exist yet: ${manifest.frontend.bundle}. Run your build before packaging.`);
+        }
+    }
+
+    const routes = manifest.backend?.routes;
+    if (routes && typeof routes === 'object') {
+        for (const [group, routeFile] of Object.entries(routes)) {
+            if (typeof routeFile !== 'string') {
+                result.errors.push(`backend.routes.${group} must be a string path.`);
+                continue;
+            }
+            if (!fs.existsSync(path.join(basePath, routeFile))) {
+                result.errors.push(`backend.routes.${group} points to missing file: ${routeFile}`);
+            }
+        }
+    }
+}
+
+function readPackage(basePath, result) {
+    const packagePath = path.join(basePath, 'package.json');
+    if (!fs.existsSync(packagePath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+    } catch (error) {
+        result.errors.push(`package.json could not be parsed: ${error.message}`);
+        return null;
+    }
+}
+
+function validatePackage(manifest, pkg, result) {
+    if (!manifest || !pkg) return;
+
+    const expectedName = manifest.id?.replace('/', '-');
+    if (expectedName && pkg.name && pkg.name !== expectedName) {
+        result.warnings.push(`package.json name "${pkg.name}" differs from manifest-derived "${expectedName}". Run npx notur-sync.`);
+    }
+
+    if (manifest.version && pkg.version && pkg.version !== manifest.version) {
+        result.warnings.push(`package.json version "${pkg.version}" differs from extension.yaml version "${manifest.version}". Run npx notur-sync.`);
+    }
+
+    for (const script of ['build', 'pack', 'push', 'sync']) {
+        if (!pkg.scripts?.[script]) {
+            result.warnings.push(`package.json is missing "${script}" script.`);
+        }
+    }
+}
+
+function validateFrontendSource(basePath, manifest, result) {
+    const indexPath = path.join(basePath, 'resources/frontend/src/index.tsx');
+    if (!fs.existsSync(indexPath)) {
+        if (manifest?.frontend) {
+            result.warnings.push('frontend is configured but resources/frontend/src/index.tsx was not found.');
+        }
+        return;
+    }
+
+    const source = fs.readFileSync(indexPath, 'utf8');
+    if (!source.includes('createExtension')) {
+        result.warnings.push('frontend entry does not appear to call createExtension().');
+    }
+
+    if (manifest?.id && !source.includes(manifest.id)) {
+        result.warnings.push(`frontend entry does not appear to reference manifest id "${manifest.id}".`);
+    }
+
+    const slotMatches = source.matchAll(/slot:\s*['"`]([^'"`]+)['"`]/g);
+    for (const match of slotMatches) {
+        if (!KNOWN_SLOTS.has(match[1])) {
+            result.warnings.push(`unknown slot id "${match[1]}". Check docs/slot-reference.md or SDK SlotId.`);
+        }
+    }
+}
+
+function printResult(result, strict) {
+    for (const warning of result.warnings) {
+        console.warn(`warning: ${warning}`);
+    }
+    for (const error of result.errors) {
+        console.error(`error: ${error}`);
+    }
+
+    const failed = result.errors.length > 0 || (strict && result.warnings.length > 0);
+    if (failed) {
+        console.error(`Notur validation failed (${result.errors.length} errors, ${result.warnings.length} warnings).`);
+        process.exit(1);
+    }
+
+    console.log(`Notur validation passed (${result.warnings.length} warnings).`);
+}
+
+function main() {
+    const options = parseArgs();
+    const basePath = path.resolve(options.path);
+    const result = { errors: [], warnings: [] };
+
+    if (!fs.existsSync(basePath) || !fs.statSync(basePath).isDirectory()) {
+        result.errors.push(`path does not exist or is not a directory: ${basePath}`);
+        printResult(result, options.strict);
+        return;
+    }
+
+    const manifest = readManifest(basePath, result);
+    validateManifest(basePath, manifest, result);
+    const pkg = readPackage(basePath, result);
+    validatePackage(manifest, pkg, result);
+    validateFrontendSource(basePath, manifest, result);
+    printResult(result, options.strict);
+}
+
+main();