@notur/sdk 1.4.4 → 1.4.6

package/README.md

@@ -94,7 +94,56 @@ import type {
 
 ## CLI Tools
 
-The SDK ships two CLI tools, available via `npx`, `yarn dlx`, `pnpm dlx`, or `bunx`.
+The SDK ships local development CLI tools, available via `npx`, `yarn dlx`, `pnpm dlx`, or `bunx`.
+
+You can use the dispatcher:
+
+```bash
+npx @notur/sdk create acme/red-button
+npx @notur/sdk pack
+npx @notur/sdk push --host https://panel.example.com --key notur_xxx
+```
+
+Or the standalone bins:
+
+```bash
+npx notur-create acme/red-button
+npx notur-pack
+npx notur-push --host https://panel.example.com --key notur_xxx
+```
+
+### `notur-create` — Scaffold extensions locally
+
+Creates a Notur extension folder without requiring Pterodactyl, Laravel, or `php artisan`.
+
+Run without arguments to start the interactive wizard:
+
+```bash
+npx notur-create
+```
+
+Scripted usage stays non-interactive:
+
+```bash
+npx notur-create acme/red-button --slot server.header
+cd red-button
+npm install
+npm run build
+npx notur-pack
+```
+
+Options:
+- `--path <dir>` — parent directory for the generated extension.
+- `--preset <name>` — `frontend`, `backend`, `full`, or `minimal`.
+- `--name <name>` — display name for `extension.yaml`.
+- `--description <text>` — description for `extension.yaml`.
+- `--slot <slot>` — initial frontend slot, default `dashboard.widgets`.
+- `--package-manager <name>` — `npm`, `pnpm`, `yarn`, or `bun`.
+- `--install` / `--no-install` — install frontend dependencies after scaffolding.
+- `--env` / `--no-env` — create `.env` from `.env.example`.
+- `--no-frontend` — generate only `extension.yaml` and the PHP entrypoint.
+- `--with-api-routes` — include a client API route stub.
+- `--force` — allow writing into an existing empty directory.
 
 ### `notur-pack` — Package extensions
 
@@ -137,6 +186,48 @@ This additionally produces:
 
 The `.sig` format is compatible with PHP's `SignatureVerifier::verify()`.
 
+### `notur-push` — Push to a remote Notur panel
+
+Packages the local extension and uploads it to a Notur-enabled Pterodactyl panel using a remote push key.
+
+```bash
+npx notur-push --host https://panel.example.com --key notur_xxx
+```
+
+Equivalent values can be provided by the shell or by a local `.env` file in the extension directory:
+
+```dotenv
+NOTUR_HOST=https://panel.example.com
+NOTUR_PUSH_KEY=notur_xxx
+```
+
+Then run:
+
+```bash
+npm run push
+```
+
+or:
+
+```bash
+npx notur-push
+```
+
+Remote setup on the panel:
+
+```bash
+php artisan notur:remote-key
+```
+
+Add the printed `NOTUR_REMOTE_PUSH_ENABLED=true` and `NOTUR_REMOTE_PUSH_KEYS=...` values to the panel `.env`.
+
+Options:
+- `--archive <file>` — upload an existing `.notur` archive instead of packing.
+- `--env-file <file>` — load host/key values from a custom env file.
+- `--no-build` — skip running the local `build` script before packing.
+- `--no-force` — do not overwrite an already installed extension.
+- `--keep-archive` — keep the temporary archive generated for the push.
+
 ### `notur-keygen` — Generate signing keypair
 
 Generates a new Ed25519 keypair for extension signing.

package/bin/notur-create.js

@@ -0,0 +1,580 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { spawnSync } = require('child_process');
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {
+        id: null,
+        path: process.cwd(),
+        preset: null,
+        displayName: null,
+        description: null,
+        withFrontend: true,
+        withApiRoutes: false,
+        force: false,
+        slot: 'dashboard.widgets',
+        packageManager: null,
+        install: null,
+        createEnv: null,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--path') {
+            options.path = args[++i];
+        } else if (arg === '--preset') {
+            options.preset = args[++i];
+        } else if (arg === '--name' || arg === '--display-name') {
+            options.displayName = args[++i];
+        } else if (arg === '--description') {
+            options.description = args[++i];
+        } else if (arg === '--with-frontend') {
+            options.withFrontend = true;
+        } else if (arg === '--no-frontend') {
+            options.withFrontend = false;
+        } else if (arg === '--with-api-routes') {
+            options.withApiRoutes = true;
+        } else if (arg === '--no-api-routes') {
+            options.withApiRoutes = false;
+        } else if (arg === '--force') {
+            options.force = true;
+        } else if (arg === '--slot') {
+            options.slot = args[++i];
+        } else if (arg === '--package-manager') {
+            options.packageManager = args[++i];
+        } else if (arg === '--install') {
+            options.install = true;
+        } else if (arg === '--no-install') {
+            options.install = false;
+        } else if (arg === '--env') {
+            options.createEnv = true;
+        } else if (arg === '--no-env') {
+            options.createEnv = false;
+        } else if (arg === '--help' || arg === '-h') {
+            usage(0);
+        } else if (!arg.startsWith('-') && !options.id) {
+            options.id = arg;
+        } else {
+            console.error(`Unknown argument: ${arg}`);
+            usage(1);
+        }
+    }
+
+    if (options.preset && !['frontend', 'backend', 'full', 'minimal'].includes(options.preset)) {
+        console.error('Error: preset must be one of frontend, backend, full, or minimal.');
+        process.exit(1);
+    }
+
+    if (options.packageManager && !['npm', 'pnpm', 'yarn', 'bun'].includes(options.packageManager)) {
+        console.error('Error: package manager must be one of npm, pnpm, yarn, or bun.');
+        process.exit(1);
+    }
+
+    return options;
+}
+
+function usage(code) {
+    console.log(`Usage:
+  npx notur-create acme/red-button [options]
+  npx @notur/sdk create acme/red-button [options]
+
+Options:
+  --path <dir>        Parent directory for the generated extension
+  --preset <name>     frontend, backend, full, or minimal
+  --name <name>       Display name for extension.yaml
+  --description <txt> Description for extension.yaml
+  --slot <slot>       Initial frontend slot (default: dashboard.widgets)
+  --package-manager   npm, pnpm, yarn, or bun
+  --install           Install frontend dependencies after scaffolding
+  --env               Create .env from .env.example
+  --no-frontend       Generate PHP/manifest only
+  --with-api-routes   Include a client API route stub
+  --force             Allow writing into an existing empty directory`);
+    process.exit(code);
+}
+
+function isInteractive() {
+    return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+function prompt(question, defaultValue = '') {
+    const suffix = defaultValue ? ` (${defaultValue})` : '';
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise(resolve => {
+        rl.question(`${question}${suffix}: `, answer => {
+            rl.close();
+            resolve(answer.trim() || defaultValue);
+        });
+    });
+}
+
+async function select(question, choices, defaultChoice) {
+    const labels = choices.map(choice => choice.value).join('/');
+    while (true) {
+        const answer = await prompt(`${question} [${labels}]`, defaultChoice);
+        const match = choices.find(choice => choice.value === answer);
+        if (match) {
+            return match.value;
+        }
+        console.log(`Choose one of: ${labels}`);
+    }
+}
+
+async function confirm(question, defaultValue = false) {
+    const answer = await prompt(`${question} [${defaultValue ? 'Y/n' : 'y/N'}]`, defaultValue ? 'y' : 'n');
+    return ['y', 'yes'].includes(answer.toLowerCase());
+}
+
+function validateId(id) {
+    return /^[a-z0-9-]+\/[a-z0-9-]+$/.test(id);
+}
+
+function applyPreset(options) {
+    const preset = options.preset || 'frontend';
+    const features = {
+        frontend: true,
+        apiRoutes: false,
+    };
+
+    if (preset === 'minimal') {
+        features.frontend = false;
+        features.apiRoutes = false;
+    } else if (preset === 'backend') {
+        features.frontend = false;
+        features.apiRoutes = true;
+    } else if (preset === 'full') {
+        features.frontend = true;
+        features.apiRoutes = true;
+    }
+
+    if (options.withFrontend === false) {
+        features.frontend = false;
+    } else if (options.withFrontend === true && options.preset === null) {
+        features.frontend = true;
+    }
+
+    if (options.withApiRoutes === true) {
+        features.apiRoutes = true;
+    } else if (options.withApiRoutes === false && options.preset === null) {
+        features.apiRoutes = false;
+    }
+
+    options.withFrontend = features.frontend;
+    options.withApiRoutes = features.apiRoutes;
+    options.preset = preset;
+
+    return options;
+}
+
+async function resolveOptions(options) {
+    if (!options.id && !isInteractive()) {
+        console.error('Error: extension id is required in non-interactive mode.');
+        usage(1);
+    }
+
+    if (options.id && !validateId(options.id)) {
+        console.error('Error: extension id must use vendor/name format with lowercase letters, numbers, and hyphens.');
+        process.exit(1);
+    }
+
+    if (!options.id) {
+        console.log('Notur extension setup');
+        while (!options.id) {
+            const id = await prompt('Extension id', 'acme/red-button');
+            if (validateId(id)) {
+                options.id = id;
+            } else {
+                console.log('Use vendor/name format with lowercase letters, numbers, and hyphens.');
+            }
+        }
+    }
+
+    const [, name] = options.id.split('/');
+    if (!options.displayName && isInteractive()) {
+        options.displayName = await prompt('Display name', displayName(name));
+    }
+    if (!options.description && isInteractive()) {
+        options.description = await prompt('Description', 'A Notur extension');
+    }
+    if (!options.preset && isInteractive()) {
+        options.preset = await select('Preset', [
+            { value: 'frontend' },
+            { value: 'backend' },
+            { value: 'full' },
+            { value: 'minimal' },
+        ], 'frontend');
+    }
+    if (isInteractive() && ['frontend', 'full'].includes(options.preset) && options.withFrontend !== false) {
+        options.slot = await prompt('Initial frontend slot', options.slot);
+    }
+    if (!options.packageManager && isInteractive() && options.withFrontend !== false && options.preset !== 'minimal' && options.preset !== 'backend') {
+        options.packageManager = await select('Package manager', [
+            { value: 'npm' },
+            { value: 'pnpm' },
+            { value: 'yarn' },
+            { value: 'bun' },
+        ], 'npm');
+    }
+    if (options.createEnv === null && isInteractive()) {
+        options.createEnv = await confirm('Create .env from .env.example?', false);
+    }
+    if (options.install === null && isInteractive() && options.withFrontend !== false && options.preset !== 'minimal' && options.preset !== 'backend') {
+        options.install = await confirm('Install frontend dependencies now?', false);
+    }
+
+    return applyPreset(options);
+}
+
+function studly(value) {
+    return value
+        .split('-')
+        .filter(Boolean)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+
+function displayName(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 yamlString(value) {
+    return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+    console.log(`  created ${path.relative(process.cwd(), filePath)}`);
+}
+
+function ensureTarget(target, force) {
+    if (!fs.existsSync(target)) {
+        fs.mkdirSync(target, { recursive: true });
+        return;
+    }
+
+    const entries = fs.readdirSync(target);
+    if (entries.length > 0 || !force) {
+        console.error(`Error: target directory already exists: ${target}`);
+        console.error('Use --force only for an existing empty directory.');
+        process.exit(1);
+    }
+}
+
+function manifestTemplate({ id, vendor, name, className, namespace, frontend, apiRoutes, display, description }) {
+    const frontendSection = frontend
+        ? `
+frontend:
+  bundle: "resources/frontend/dist/extension.js"
+`
+        : '';
+    const backendSection = apiRoutes
+        ? `
+backend:
+  routes:
+    api-client: "src/routes/api-client.php"
+`
+        : '';
+
+    return `notur: "1.0"
+id: "${id}"
+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/"
+${backendSection}
+${frontendSection}`;
+}
+
+function phpTemplate({ namespace, className }) {
+    return `<?php
+
+declare(strict_types=1);
+
+namespace ${namespace};
+
+use Notur\\Support\\NoturExtension;
+
+class ${className} extends NoturExtension
+{
+}
+`;
+}
+
+function apiRouteTemplate() {
+    return `<?php
+
+use Illuminate\\Support\\Facades\\Route;
+
+Route::get('/ping', function () {
+    return response()->json([
+        'message' => 'pong',
+    ]);
+});
+`;
+}
+
+function frontendTemplate({ id, slot }) {
+    return `import * as React from 'react';
+import { createExtension } from '@notur/sdk';
+
+const ExampleButton: React.FC = () => {
+    return (
+        <button
+            style={{
+                background: '#dc2626',
+                color: '#fff',
+                border: 0,
+                borderRadius: '6px',
+                padding: '8px 12px',
+                fontWeight: 600,
+                cursor: 'pointer',
+            }}
+            onClick={() => alert('Hello from Notur')}
+        >
+            Red Button
+        </button>
+    );
+};
+
+createExtension({
+    id: '${id}',
+    slots: [
+        {
+            slot: '${slot}',
+            component: ExampleButton,
+            order: 10,
+        },
+    ],
+});
+`;
+}
+
+function packageTemplate(id) {
+    return `${JSON.stringify({
+        name: id.replace('/', '-'),
+        version: '1.0.0',
+        private: true,
+        scripts: {
+            build: 'webpack-cli --mode production --config webpack.config.js',
+            dev: 'webpack-cli --mode development --watch --config webpack.config.js',
+            pack: 'notur-pack',
+            push: 'notur-push',
+        },
+        peerDependencies: {
+            react: '^16.14.0',
+            'react-dom': '^16.14.0',
+        },
+        devDependencies: {
+            '@notur/sdk': '^1.4.5',
+            '@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',
+        },
+    }, null, 2)}
+`;
+}
+
+function tsconfigTemplate() {
+    return `{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "jsx": "react",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["resources/frontend/src/**/*"]
+}
+`;
+}
+
+function webpackTemplate(libName) {
+    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: 'extension.js',
+        path: path.resolve(__dirname, 'resources/frontend/dist'),
+        library: {
+            ...base.output.library,
+            name: '__NOTUR_EXT_${libName}__',
+            type: 'umd',
+        },
+    },
+};
+`;
+}
+
+function readmeTemplate(id) {
+    return `# ${id}
+
+Development:
+
+\`\`\`bash
+npm install
+npm run build
+npx notur-pack
+\`\`\`
+
+Remote push to a Notur-enabled panel:
+
+\`\`\`bash
+cp .env.example .env
+npm run push
+\`\`\`
+
+Or pass values directly:
+
+\`\`\`bash
+npx notur-push --host https://panel.example.com --key notur_xxx
+\`\`\`
+`;
+}
+
+function installCommand(packageManager) {
+    if (packageManager === 'pnpm') return ['pnpm', ['install']];
+    if (packageManager === 'yarn') return ['yarn', ['install']];
+    if (packageManager === 'bun') return ['bun', ['install']];
+    return ['npm', ['install']];
+}
+
+function runScriptCommand(packageManager, script) {
+    if (packageManager === 'bun') return `bun run ${script}`;
+    if (packageManager === 'pnpm') return `pnpm run ${script}`;
+    if (packageManager === 'yarn') return `yarn ${script}`;
+    return `npm run ${script}`;
+}
+
+function runInstall(target, packageManager) {
+    const [command, args] = installCommand(packageManager || 'npm');
+    console.log(`\nRunning ${command} ${args.join(' ')}...`);
+    const result = spawnSync(command, args, {
+        cwd: target,
+        stdio: 'inherit',
+    });
+
+    if (result.status !== 0) {
+        console.warn(`Dependency install failed. Run ${command} ${args.join(' ')} manually in ${target}.`);
+    }
+}
+
+async function main() {
+    const options = await resolveOptions(parseArgs());
+    const [vendor, name] = options.id.split('/');
+    const namespace = `${studly(vendor)}\\${studly(name)}`;
+    const className = `${studly(name)}Extension`;
+    const target = path.resolve(options.path, name);
+
+    ensureTarget(target, options.force);
+
+    console.log(`Scaffolding ${options.id} in ${target}`);
+
+    writeFile(path.join(target, 'extension.yaml'), manifestTemplate({
+        id: options.id,
+        vendor,
+        name,
+        namespace,
+        className,
+        frontend: options.withFrontend,
+        apiRoutes: options.withApiRoutes,
+        display: options.displayName || displayName(name),
+        description: options.description || 'A Notur extension',
+    }));
+    writeFile(path.join(target, 'src', `${className}.php`), phpTemplate({ namespace, className }));
+    if (options.withApiRoutes) {
+        writeFile(path.join(target, 'src/routes/api-client.php'), apiRouteTemplate());
+    }
+    writeFile(path.join(target, 'README.md'), readmeTemplate(options.id));
+    writeFile(path.join(target, '.env.example'), `NOTUR_HOST=https://panel.example.com
+NOTUR_PUSH_KEY=notur_xxx
+`);
+    if (options.createEnv) {
+        writeFile(path.join(target, '.env'), `NOTUR_HOST=https://panel.example.com
+NOTUR_PUSH_KEY=notur_xxx
+`);
+    }
+    writeFile(path.join(target, '.gitignore'), `node_modules/
+vendor/
+resources/frontend/dist/
+.env
+*.notur
+*.notur.sha256
+*.notur.sig
+`);
+
+    if (options.withFrontend) {
+        writeFile(path.join(target, 'resources/frontend/src/index.tsx'), frontendTemplate({
+            id: options.id,
+            slot: options.slot,
+        }));
+        writeFile(path.join(target, 'package.json'), packageTemplate(options.id));
+        writeFile(path.join(target, 'tsconfig.json'), tsconfigTemplate());
+        writeFile(path.join(target, 'webpack.config.js'), webpackTemplate(libraryName(options.id)));
+    }
+
+    if (options.install && options.withFrontend) {
+        runInstall(target, options.packageManager);
+    }
+
+    console.log('\nNext steps:');
+    if (options.withFrontend) {
+        console.log(`  cd ${target}`);
+        if (!options.install) {
+            const [command, args] = installCommand(options.packageManager || 'npm');
+            console.log(`  ${command} ${args.join(' ')}`);
+        }
+        console.log(`  ${runScriptCommand(options.packageManager || 'npm', 'build')}`);
+        console.log('  npx notur-pack');
+    } else {
+        console.log(`  cd ${target}`);
+        console.log('  npx notur-pack');
+    }
+}
+
+main().catch(error => {
+    console.error(error?.message || String(error));
+    process.exit(1);
+});

package/bin/notur-push.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {
+        path: '.',
+        archive: null,
+        host: null,
+        key: null,
+        envFile: null,
+        endpoint: '/api/notur/dev/push',
+        force: true,
+        noBuild: false,
+        keepArchive: false,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--archive') {
+            options.archive = args[++i];
+        } else if (arg === '--host') {
+            options.host = args[++i];
+        } else if (arg === '--key') {
+            options.key = args[++i];
+        } else if (arg === '--env-file') {
+            options.envFile = args[++i];
+        } else if (arg === '--endpoint') {
+            options.endpoint = args[++i];
+        } else if (arg === '--no-force') {
+            options.force = false;
+        } else if (arg === '--no-build') {
+            options.noBuild = true;
+        } else if (arg === '--keep-archive') {
+            options.keepArchive = 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-push [path] --host https://panel.example.com --key notur_xxx
+  npx @notur/sdk push [path] --host https://panel.example.com --key notur_xxx
+
+Options:
+  --archive <file>    Upload an existing .notur archive instead of packing
+  --host <url>        Remote Pterodactyl panel URL
+  --key <token>       Notur remote push token
+  --env-file <file>   Load values from a custom env file
+  --endpoint <path>   Remote push endpoint (default: /api/notur/dev/push)
+  --no-build          Skip npm/yarn/pnpm/bun build before packing
+  --no-force          Do not overwrite an already installed extension
+  --keep-archive      Keep the temporary archive generated for this push`);
+    process.exit(code);
+}
+
+function loadManifest(dir) {
+    const manifestPath = path.join(dir, 'extension.yaml');
+    if (!fs.existsSync(manifestPath)) {
+        return { id: path.basename(dir), version: 'dev' };
+    }
+
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    const id = raw.match(/^id:\s*["']?([^"'\n]+)["']?/m)?.[1]?.trim();
+    const version = raw.match(/^version:\s*["']?([^"'\n]+)["']?/m)?.[1]?.trim();
+
+    return {
+        id: id || path.basename(dir),
+        version: version || 'dev',
+    };
+}
+
+function detectPackageManager(dir) {
+    if (fs.existsSync(path.join(dir, 'bun.lockb')) || fs.existsSync(path.join(dir, 'bun.lock'))) return 'bun';
+    if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+    if (fs.existsSync(path.join(dir, 'package-lock.json')) || fs.existsSync(path.join(dir, 'package.json'))) return 'npm';
+    return null;
+}
+
+function buildCommand(packageManager) {
+    switch (packageManager) {
+        case 'bun':
+            return ['bun', ['run', 'build']];
+        case 'pnpm':
+            return ['pnpm', ['run', 'build']];
+        case 'yarn':
+            return ['yarn', ['run', 'build']];
+        case 'npm':
+            return ['npm', ['run', 'build']];
+        default:
+            return null;
+    }
+}
+
+function maybeBuild(dir, noBuild) {
+    if (noBuild || !fs.existsSync(path.join(dir, 'package.json'))) {
+        return;
+    }
+
+    const packageJson = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    if (!packageJson.scripts || !packageJson.scripts.build) {
+        return;
+    }
+
+    const packageManager = detectPackageManager(dir);
+    const command = buildCommand(packageManager);
+    if (!command) {
+        console.warn('No supported package manager found; skipping build.');
+        return;
+    }
+
+    console.log(`Running ${command[0]} ${command[1].join(' ')}...`);
+    const result = spawnSync(command[0], command[1], {
+        cwd: dir,
+        stdio: 'inherit',
+    });
+
+    if (result.status !== 0) {
+        console.error('Build failed; aborting push.');
+        process.exit(result.status ?? 1);
+    }
+}
+
+function packArchive(dir) {
+    const manifest = loadManifest(dir);
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'notur-push-'));
+    const archiveName = `${manifest.id.replace('/', '-')}-${manifest.version}.notur`;
+    const archivePath = path.join(tmpDir, archiveName);
+    const packScript = path.join(__dirname, 'notur-pack.js');
+
+    const result = spawnSync(process.execPath, [packScript, dir, '--output', archivePath], {
+        stdio: 'inherit',
+    });
+
+    if (result.status !== 0) {
+        console.error('Packaging failed; aborting push.');
+        process.exit(result.status ?? 1);
+    }
+
+    return { archivePath, tmpDir };
+}
+
+function resolveUrl(host, endpoint, force) {
+    const base = host.replace(/\/+$/, '');
+    const pathPart = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    const url = new URL(`${base}${pathPart}`);
+    if (!force) {
+        url.searchParams.set('force', '0');
+    }
+    return url;
+}
+
+async function pushArchive(options, archivePath) {
+    if (typeof fetch !== 'function' || typeof FormData !== 'function' || typeof Blob !== 'function') {
+        console.error('Error: notur-push requires Node.js 18+ for fetch/FormData support.');
+        process.exit(1);
+    }
+
+    const url = resolveUrl(options.host, options.endpoint, options.force);
+    const data = fs.readFileSync(archivePath);
+    const form = new FormData();
+    form.append('extension', new Blob([data]), path.basename(archivePath));
+
+    const signaturePath = `${archivePath}.sig`;
+    if (fs.existsSync(signaturePath)) {
+        const signature = fs.readFileSync(signaturePath);
+        form.append('signature', new Blob([signature]), path.basename(signaturePath));
+    }
+
+    console.log(`Uploading ${path.basename(archivePath)} to ${url.origin}...`);
+
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${options.key}`,
+            Accept: 'application/json',
+        },
+        body: form,
+    });
+
+    const text = await response.text();
+    let payload = null;
+    try {
+        payload = text ? JSON.parse(text) : null;
+    } catch {
+        payload = null;
+    }
+
+    if (!response.ok) {
+        console.error(`Remote push failed (${response.status}).`);
+        if (payload?.message) {
+            console.error(payload.message);
+        } else if (text) {
+            console.error(text);
+        }
+        process.exit(1);
+    }
+
+    if (payload) {
+        console.log(`Pushed ${payload.id || 'extension'} v${payload.version || 'unknown'}.`);
+        if (payload.output) {
+            console.log(payload.output.trim());
+        }
+    } else {
+        console.log('Push completed.');
+    }
+}
+
+function parseEnvValue(value) {
+    let parsed = value.trim();
+    if (
+        (parsed.startsWith('"') && parsed.endsWith('"')) ||
+        (parsed.startsWith("'") && parsed.endsWith("'"))
+    ) {
+        parsed = parsed.slice(1, -1);
+    }
+    return parsed;
+}
+
+function loadEnvFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+
+    const values = {};
+    const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+
+    for (const line of lines) {
+        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]] = parseEnvValue(match[2]);
+    }
+
+    return values;
+}
+
+function resolvePushConfig(options, extensionPath) {
+    const envFile = options.envFile
+        ? path.resolve(options.envFile)
+        : path.join(extensionPath, '.env');
+    const fileEnv = loadEnvFile(envFile);
+
+    return {
+        ...options,
+        host: options.host || process.env.NOTUR_HOST || fileEnv.NOTUR_HOST || null,
+        key:
+            options.key ||
+            process.env.NOTUR_API_KEY ||
+            process.env.NOTUR_PUSH_KEY ||
+            fileEnv.NOTUR_API_KEY ||
+            fileEnv.NOTUR_PUSH_KEY ||
+            null,
+        endpoint: options.endpoint || fileEnv.NOTUR_ENDPOINT || '/api/notur/dev/push',
+    };
+}
+
+async function main() {
+    let 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);
+    }
+
+    options = resolvePushConfig(options, extensionPath);
+
+    if (!options.host) {
+        console.error('Error: --host is required, or set NOTUR_HOST in the environment or local .env.');
+        process.exit(1);
+    }
+
+    if (!options.key) {
+        console.error('Error: --key is required, or set NOTUR_PUSH_KEY / NOTUR_API_KEY in the environment or local .env.');
+        process.exit(1);
+    }
+
+    if (!options.archive) {
+        maybeBuild(extensionPath, options.noBuild);
+    }
+
+    let archivePath = options.archive ? path.resolve(options.archive) : null;
+    let tmpDir = null;
+    if (!archivePath) {
+        const packed = packArchive(extensionPath);
+        archivePath = packed.archivePath;
+        tmpDir = packed.tmpDir;
+    }
+
+    if (!fs.existsSync(archivePath)) {
+        console.error(`Error: archive does not exist: ${archivePath}`);
+        process.exit(1);
+    }
+
+    try {
+        await pushArchive(options, archivePath);
+    } finally {
+        if (tmpDir && !options.keepArchive) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        } else if (tmpDir) {
+            console.log(`Kept archive at ${archivePath}`);
+        }
+    }
+}
+
+main().catch(error => {
+    console.error(error?.message || String(error));
+    process.exit(1);
+});

package/bin/notur.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const commands = {
+    create: 'notur-create.js',
+    pack: 'notur-pack.js',
+    keygen: 'notur-keygen.js',
+    push: 'notur-push.js',
+};
+
+const [command, ...args] = process.argv.slice(2);
+
+if (!command || command === '--help' || command === '-h') {
+    console.log(`Notur SDK CLI
+
+Usage:
+  notur create <vendor/name> [options]
+  notur pack [path] [options]
+  notur push [path] --host <url> --key <token>
+  notur keygen
+
+Standalone bins are also available:
+  notur-create, notur-pack, notur-push, notur-keygen`);
+    process.exit(command ? 0 : 1);
+}
+
+const script = commands[command];
+if (!script) {
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "notur --help" for usage.');
+    process.exit(1);
+}
+
+const result = spawnSync(process.execPath, [path.join(__dirname, script), ...args], {
+    stdio: 'inherit',
+});
+
+process.exit(result.status ?? 1);

package/examples/red-button/.env.example

@@ -0,0 +1,2 @@
+NOTUR_HOST=https://panel.example.com
+NOTUR_PUSH_KEY=notur_xxx

package/examples/red-button/README.md

@@ -0,0 +1,30 @@
+# Red Button Example
+
+A minimal Notur frontend extension that renders a red button in the server header.
+
+## Local Build
+
+```bash
+npm install
+npm run build
+```
+
+## Package
+
+```bash
+npx notur-pack
+```
+
+## Push To A Remote Panel
+
+Create `.env` from `.env.example`, then run:
+
+```bash
+npm run push
+```
+
+The remote panel must have Notur remote push enabled:
+
+```bash
+php artisan notur:remote-key
+```

package/examples/red-button/extension.yaml

@@ -0,0 +1,19 @@
+notur: "1.0"
+id: "acme/red-button"
+name: "Red Button"
+version: "1.0.0"
+description: "Adds a red button to the server header"
+license: "MIT"
+
+requires:
+  notur: "^1.0"
+  pterodactyl: "^1.12"
+  php: "^8.2"
+
+entrypoint: "Acme\\RedButton\\RedButtonExtension"
+autoload:
+  psr-4:
+    "Acme\\RedButton\\": "src/"
+
+frontend:
+  bundle: "resources/frontend/dist/extension.js"

package/examples/red-button/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "acme-red-button",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "webpack-cli --mode production --config webpack.config.js",
+    "dev": "webpack-cli --mode development --watch --config webpack.config.js",
+    "pack": "notur-pack",
+    "push": "notur-push"
+  },
+  "peerDependencies": {
+    "react": "^16.14.0",
+    "react-dom": "^16.14.0"
+  },
+  "devDependencies": {
+    "@notur/sdk": "^1.4.5",
+    "@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"
+  }
+}

package/examples/red-button/resources/frontend/src/index.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { createExtension } from '@notur/sdk';
+
+const RedButton: React.FC = () => {
+    return (
+        <button
+            style={{
+                background: '#dc2626',
+                color: '#fff',
+                border: 0,
+                borderRadius: '6px',
+                padding: '8px 12px',
+                fontWeight: 600,
+                cursor: 'pointer',
+            }}
+            onClick={() => alert('Hello from Notur')}
+        >
+            Red Button
+        </button>
+    );
+};
+
+createExtension({
+    id: 'acme/red-button',
+    slots: [
+        {
+            slot: 'server.header',
+            component: RedButton,
+            order: 10,
+        },
+    ],
+});

package/examples/red-button/src/RedButtonExtension.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Acme\RedButton;
+
+use Notur\Support\NoturExtension;
+
+class RedButtonExtension extends NoturExtension
+{
+}

package/examples/red-button/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "jsx": "react",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["resources/frontend/src/**/*"]
+}

package/examples/red-button/webpack.config.js

@@ -0,0 +1,17 @@
+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: 'extension.js',
+        path: path.resolve(__dirname, 'resources/frontend/dist'),
+        library: {
+            ...base.output.library,
+            name: '__NOTUR_EXT_AcmeRedButton__',
+            type: 'umd',
+        },
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notur/sdk",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Notur Extension Developer SDK",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -15,8 +15,12 @@
     "access": "public"
   },
   "bin": {
+    "sdk": "./bin/notur.js",
+    "notur": "./bin/notur.js",
+    "notur-create": "./bin/notur-create.js",
     "notur-pack": "./bin/notur-pack.js",
-    "notur-keygen": "./bin/notur-keygen.js"
+    "notur-keygen": "./bin/notur-keygen.js",
+    "notur-push": "./bin/notur-push.js"
   },
   "keywords": [
     "notur",
@@ -29,7 +33,8 @@
     "dist/",
     "bin/",
     "webpack.extension.config.js",
-    "templates/"
+    "templates/",
+    "examples/"
   ],
   "scripts": {
     "build": "tsc",