@navette-js/cli 0.0.0-stage → 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NavetteJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @navette-js/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line tools for Navette projects: migrations, users, and generators for resources, pages and widgets (npx navette).
+
+Part of [Navette](https://github.com/NavetteJS/navette), admin panels for Node.js. Start a project with `npm create navette@latest`, or install the framework with `npm install @navette-js/panels`.
+
+**Beta:** the API may still change between beta releases.
+
+License: MIT. Third-party notices: see `THIRD-PARTY-NOTICES.md` where present.

package/lib/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Project CLI (`npx navette …`): migrations, users, and generators for resources, pages and widgets.
+// Run it at the root of a project created with `npm create navette`.
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join, relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { generateResource, generateMigration, generatePage, generateWidget, studly, tableName } from "./generators.js";
+const cwd = process.cwd();
+if (existsSync(join(cwd, '.env')))
+    process.loadEnvFile(join(cwd, '.env'));
+const [command, ...rest] = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (const arg of rest) {
+    const match = /^--([a-z-]+)(?:=(.*))?$/.exec(arg);
+    if (match)
+        flags[match[1]] = match[2] ?? true;
+    else
+        positional.push(arg);
+}
+const flag = (name) => (typeof flags[name] === 'string' ? flags[name] : undefined);
+const say = (text = '') => process.stdout.write(text + '\n');
+const fail = (text) => { process.stderr.write(`\n  ✖ ${text}\n\n`); process.exit(1); };
+/** The project's `src/database.ts` exports `db` (knex) and `migrate()`. */
+async function project() {
+    const file = join(cwd, 'src', 'database.ts');
+    if (!existsSync(file))
+        fail('No src/database.ts here: run this command at the root of a Navette project (created with `npm create navette`).');
+    return import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+}
+async function ask(question, fallback = '') {
+    if (!process.stdin.isTTY)
+        return fallback;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question(`  ${question}${fallback ? ` (${fallback})` : ''}: `)).trim();
+    rl.close();
+    return answer || fallback;
+}
+/** Never overwrites an existing file unless `--force` is given. */
+function write(file, content) {
+    if (existsSync(file) && !flags.force)
+        fail(`${relative(cwd, file)} already exists (use --force to overwrite).`);
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, content);
+    say(`  ✔ Created ${relative(cwd, file).replaceAll('\\', '/')}`);
+}
+const panelOf = () => {
+    const panel = flag('panel') ?? 'admin';
+    if (!/^[a-z][a-z0-9-]*$/.test(panel))
+        fail(`Invalid panel id: ${panel}`);
+    return panel;
+};
+const commands = {
+    migrate: {
+        usage: 'navette migrate                                  Run the pending migrations of src/migrations',
+        async run() {
+            const { migrate, db } = await project();
+            const ran = await migrate();
+            say(ran.length ? ran.map((name) => `  ✔ Migrated ${name}`).join('\n') : '  Nothing to migrate.');
+            await db.destroy();
+        },
+    },
+    'make:migration': {
+        usage: 'navette make:migration <name>                    Create a migration file (e.g. create_posts_table)',
+        async run() {
+            const name = (positional[0] ?? fail('Give the migration a name, e.g. create_posts_table')).replace(/[^a-z0-9_]/gi, '_').toLowerCase();
+            const stamp = new Date().toISOString().replace(/\D/g, '').slice(0, 14);
+            write(join(cwd, 'src', 'migrations', `${stamp}_${name}.ts`), generateMigration(name));
+        },
+    },
+    'make:user': {
+        usage: 'navette make:user [--admin] [--name=] [--email=] [--password=]   Create a user (role admin with --admin)',
+        async run() {
+            const { db, migrate } = await project();
+            await migrate();
+            const name = flag('name') ?? (await ask('Name', 'Admin'));
+            const email = flag('email') ?? (await ask('Email address', 'admin@example.com'));
+            if (!/^[^\s@]+@[^\s@]+$/.test(email))
+                fail(`Invalid email address: ${email}`);
+            let password = flag('password') ?? (await ask('Password (leave empty to generate one)'));
+            const generated = !password;
+            if (generated)
+                password = randomBytes(12).toString('base64url');
+            if (password.length < 8)
+                fail('The password must be at least 8 characters.');
+            if (await db('users').where('email', email).first())
+                fail(`A user with the email ${email} already exists.`);
+            const { knexAuthProvider } = await import('@navette-js/panels');
+            const user = await knexAuthProvider((table) => db(table)).create({ name, email, password });
+            const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
+            await db('users').where('id', user.id).update({ role: flags.admin ? 'admin' : 'user', email_verified_at: now });
+            say(`  ✔ ${flags.admin ? 'Admin' : 'User'} ${email} created${generated ? ` — password: ${password}` : ''}`);
+            await db.destroy();
+        },
+    },
+    'make:resource': {
+        usage: 'navette make:resource <Name> [--panel=admin] [--generate] [--table=]   Create a resource (form and table from the database with --generate)',
+        async run() {
+            const model = studly((positional[0] ?? fail('Give the resource a name, e.g. Post')).replace(/Resource$/, ''));
+            const table = flag('table') ?? tableName(model);
+            let columns = null;
+            if (flags.generate) {
+                const { db, migrate } = await project();
+                await migrate();
+                if (!(await db.schema.hasTable(table)))
+                    fail(`Table "${table}" not found. Create it with a migration first (npx navette make:migration create_${table}_table), or pass --table=.`);
+                const info = await db(table).columnInfo();
+                columns = Object.entries(info).map(([name, column]) => ({ name, type: String(column.type ?? ''), nullable: column.nullable !== false }));
+                await db.destroy();
+            }
+            const panel = panelOf();
+            if (!existsSync(join(cwd, 'src', 'models', `${model}.ts`)))
+                write(join(cwd, 'src', 'models', `${model}.ts`), generateResource(model, table, columns).model);
+            write(join(cwd, 'src', panel, 'resources', `${model}Resource.ts`), generateResource(model, table, columns).resource);
+            say(`\n  Restart the server: the resource is discovered from src/${panel}/resources.`);
+        },
+    },
+    'make:page': {
+        usage: 'navette make:page <Name> [--panel=admin]             Create a custom page',
+        async run() {
+            const name = studly(positional[0] ?? fail('Give the page a name, e.g. Settings'));
+            write(join(cwd, 'src', panelOf(), 'pages', `${name}.ts`), generatePage(name));
+        },
+    },
+    'make:widget': {
+        usage: 'navette make:widget <Name> [--panel=admin] [--type=stats|chart|table]   Create a dashboard widget',
+        async run() {
+            const name = studly(positional[0] ?? fail('Give the widget a name, e.g. OrdersChart'));
+            const type = flag('type') ?? 'stats';
+            if (!['stats', 'chart', 'table'].includes(type))
+                fail('--type must be stats, chart or table.');
+            write(join(cwd, 'src', panelOf(), 'widgets', `${name}.ts`), generateWidget(name, type));
+        },
+    },
+};
+if (!command || command === 'help' || command === '--help' || !commands[command]) {
+    if (command && command !== 'help' && command !== '--help')
+        say(`\n  Unknown command: ${command}`);
+    say('\n  Navette CLI\n');
+    for (const { usage } of Object.values(commands))
+        say(`  ${usage}`);
+    const panels = existsSync(join(cwd, 'src')) ? readdirSync(join(cwd, 'src'), { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync(join(cwd, 'src', entry.name, 'resources'))).map((entry) => entry.name) : [];
+    if (panels.length)
+        say(`\n  Panels in this project: ${panels.join(', ')}`);
+    say('');
+    process.exit(command && command !== 'help' && command !== '--help' ? 1 : 0);
+}
+await commands[command].run();

package/lib/generators.d.ts

@@ -0,0 +1,17 @@
+export type ColumnInfo = {
+    name: string;
+    type: string;
+    nullable: boolean;
+};
+/** `blog post` → `BlogPost`. */
+export declare const studly: (value: string) => string;
+/** `BlogPost` → `blog_posts`. */
+export declare const tableName: (model: string) => string;
+/** Resource and model. Without known columns (no `--generate`), the form and table are placeholders to fill in. */
+export declare function generateResource(model: string, table: string, columns: ColumnInfo[] | null): {
+    model: string;
+    resource: string;
+};
+export declare function generateMigration(name: string): string;
+export declare function generatePage(name: string): string;
+export declare function generateWidget(name: string, type: 'stats' | 'chart' | 'table'): string;

package/lib/generators.js

@@ -0,0 +1,177 @@
+// CLI file generators: resources (form and table inferred from the database columns), pages, widgets, migrations.
+/** `blog post` → `BlogPost`. */
+export const studly = (value) => value.replace(/[^A-Za-z0-9]+(.)?/g, (_m, c) => (c ? c.toUpperCase() : '')).replace(/^./, (c) => c.toUpperCase());
+const snake = (value) => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+const plural = (value) => (/[^aeiou]y$/.test(value) ? value.slice(0, -1) + 'ies' : /(s|x|z|ch|sh)$/.test(value) ? value + 'es' : value + 's');
+/** `BlogPost` → `blog_posts`. */
+export const tableName = (model) => plural(snake(model));
+const headline = (column) => column.replace(/_id$/, '').replace(/_/g, ' ').replace(/^./, (c) => c.toUpperCase());
+/** Columns never edited in a form. */
+const SKIPPED = new Set(['id', 'created_at', 'updated_at', 'deleted_at', 'password', 'remember_token', 'email_verified_at']);
+function kindOf(column) {
+    const type = column.type.toLowerCase();
+    if (/bool/.test(type) || (type === 'tinyint' && /^(is|has|can)_/.test(column.name)))
+        return 'boolean';
+    if (/^date$/.test(type))
+        return 'date';
+    if (/datetime|timestamp/.test(type))
+        return 'dateTime';
+    if (/int|decimal|numeric|float|double|real/.test(type))
+        return 'number';
+    if (/text|json|clob/.test(type))
+        return 'longText';
+    if (/email/.test(column.name))
+        return 'email';
+    return 'text';
+}
+function formField(column) {
+    const label = column.name;
+    const required = column.nullable ? '' : '.required()';
+    switch (kindOf(column)) {
+        case 'boolean': return `Toggle.make('${label}')`;
+        case 'date': return `DatePicker.make('${label}')${required}`;
+        case 'dateTime': return `DateTimePicker.make('${label}')${required}`;
+        case 'number': return `TextInput.make('${label}').numeric()${required}`;
+        case 'longText': return `Textarea.make('${label}')${required}.columnSpanFull()`;
+        case 'email': return `TextInput.make('${label}').email()${required}.maxLength(255)`;
+        default: return `TextInput.make('${label}')${required}.maxLength(255)`;
+    }
+}
+function tableColumn(column) {
+    const name = column.name;
+    switch (kindOf(column)) {
+        case 'boolean': return `IconColumn.make('${name}').boolean()`;
+        case 'date': return `TextColumn.make('${name}').date().sortable()`;
+        case 'dateTime': return `TextColumn.make('${name}').dateTime().sortable()`;
+        case 'number': return `TextColumn.make('${name}').numeric().sortable()`;
+        case 'longText': return `TextColumn.make('${name}').limit(50)`;
+        default: return `TextColumn.make('${name}').searchable().sortable()`;
+    }
+}
+/** Resource and model. Without known columns (no `--generate`), the form and table are placeholders to fill in. */
+export function generateResource(model, table, columns) {
+    const editable = (columns ?? []).filter((column) => !SKIPPED.has(column.name));
+    const titleAttribute = editable.find((column) => ['name', 'title', 'label', 'subject'].includes(column.name))?.name ?? null;
+    const kinds = new Set(editable.map(kindOf));
+    const formImports = ['TextInput', ...(kinds.has('boolean') ? ['Toggle'] : []), ...(kinds.has('date') ? ['DatePicker'] : []), ...(kinds.has('dateTime') ? ['DateTimePicker'] : []), ...(kinds.has('longText') ? ['Textarea'] : [])];
+    const tableImports = ['TextColumn', ...(kinds.has('boolean') ? ['IconColumn'] : []), 'type Table'];
+    const timestamps = (columns ?? []).some((column) => column.name === 'created_at');
+    const modelCode = `import { Model } from '@navette-js/database';
+
+export class ${model} extends Model {
+    static tableName = '${table}';
+${timestamps ? `
+    $beforeInsert(): void { (this as any).created_at = (this as any).updated_at = new Date().toISOString().slice(0, 19).replace('T', ' '); }
+    $beforeUpdate(): void { (this as any).updated_at = new Date().toISOString().slice(0, 19).replace('T', ' '); }
+` : ''}}
+`;
+    const fields = editable.length ? editable.map((column) => `                ${formField(column)},`).join('\n') : `                TextInput.make('name').required().maxLength(255),`;
+    const cols = editable.length ? editable.filter((column) => kindOf(column) !== 'longText' || editable.length < 4).slice(0, 6).map((column) => `                ${tableColumn(column)},`).join('\n') : `                TextColumn.make('name').searchable().sortable(),`;
+    const createdColumn = timestamps ? `\n                TextColumn.make('created_at').dateTime().sortable().toggleable(true, { isToggledHiddenByDefault: true }),` : '';
+    const resourceCode = `import { ObjectionAdapter } from '@navette-js/database';
+import { ${formImports.join(', ')} } from '@navette-js/forms';
+import { DeleteBulkAction, Resource } from '@navette-js/panels';
+import type { Schema } from '@navette-js/schemas';
+import { ${tableImports.join(', ')} } from '@navette-js/tables';
+import { ${model} } from '../../models/${model}.ts';
+
+export class ${model}Resource extends Resource {
+    static slug = '${table.replace(/_/g, '-')}';
+    static modelLabel = '${snake(model).replace(/_/g, ' ')}';
+    static navigationIcon = 'o-rectangle-stack';
+${titleAttribute ? `    static recordTitleAttribute = '${titleAttribute}';\n` : ''}    static adapter = new ObjectionAdapter(${model});
+
+    static form(schema: Schema): Schema {
+        return schema.components([
+${fields}
+        ]);
+    }
+
+    static table(table: Table<${model}>): Table<${model}> {
+        return table
+            .columns([
+${cols}${createdColumn}
+            ])
+            .groupedBulkActions([DeleteBulkAction.make()]);
+    }
+}
+`;
+    return { model: modelCode, resource: resourceCode };
+}
+export function generateMigration(name) {
+    const created = /^create_(\w+)_table$/.exec(name)?.[1];
+    return `import type { Knex } from '@navette-js/database';
+
+export async function up(db: Knex): Promise<void> {
+${created ? `    await db.schema.createTable('${created}', (table) => {
+        table.increments('id');
+        table.string('name');
+        table.timestamps();
+    });` : `    // await db.schema.alterTable('table', (table) => { … });`}
+}
+`;
+}
+export function generatePage(name) {
+    const slug = snake(name).replace(/_/g, '-');
+    return `import { Page } from '@navette-js/panels';
+import { Section, Text, type Schema } from '@navette-js/schemas';
+
+export class ${name} extends Page {
+    static slug = '${slug}';
+    static title = '${headline(snake(name))}';
+    static navigationIcon = 'o-document-text';
+
+    contentSchema(schema: Schema): Schema {
+        return schema.components([
+            Section.make('${headline(snake(name))}').schema([
+                Text.make('Start building your page here.'),
+            ]),
+        ]);
+    }
+}
+`;
+}
+export function generateWidget(name, type) {
+    if (type === 'chart')
+        return `import { ChartWidget, type ChartData } from '@navette-js/panels';
+
+export class ${name} extends ChartWidget {
+    static heading = '${headline(snake(name))}';
+
+    getType(): string { return 'line'; }
+
+    async getData(): Promise<ChartData> {
+        return {
+            datasets: [{ label: 'Items', data: [3, 8, 5, 12, 9, 14] }],
+            labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
+        };
+    }
+}
+`;
+    if (type === 'table')
+        return `import { TableWidget } from '@navette-js/panels';
+import type { DataAdapter } from '@navette-js/database';
+import { TextColumn, type Table } from '@navette-js/tables';
+
+export class ${name} extends TableWidget {
+    static heading = '${headline(snake(name))}';
+
+    // Return the adapter of the records to list, e.g. \`new ObjectionAdapter(Order)\`.
+    getDataAdapterForTable(): DataAdapter { throw new Error('${name}: return a data adapter from getDataAdapterForTable().'); }
+
+    table(table: Table<any>): Table<any> {
+        return table.columns([TextColumn.make('name')]);
+    }
+}
+`;
+    return `import { Stat, StatsOverviewWidget } from '@navette-js/panels';
+
+export class ${name} extends StatsOverviewWidget {
+    async getStats(): Promise<Stat[]> {
+        return [
+            Stat.make('Users', 0),
+        ];
+    }
+}
+`;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@navette-js/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.2",
+  "description": "Command-line tools for Navette projects: migrations, users, and generators for resources, pages and widgets (npx navette).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/generators.d.ts",
+      "default": "./lib/generators.js"
+    }
+  },
+  "types": "./lib/generators.d.ts",
+  "bin": {
+    "navette": "./lib/cli.js"
+  },
+  "files": [
+    "lib",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NavetteJS/navette.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/NavetteJS/navette#readme",
+  "bugs": {
+    "url": "https://github.com/NavetteJS/navette/issues"
+  },
+  "keywords": [
+    "navette",
+    "admin",
+    "panel",
+    "livewire",
+    "express",
+    "node",
+    "cli",
+    "scaffold"
+  ],
+  "dependencies": {
+    "@navette-js/panels": "1.0.0-beta.2",
+    "@navette-js/database": "1.0.0-beta.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}