@kargojs/cli 0.1.0

package/bin/kargo.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Thin shebang wrapper — main logic lives in dist/ (compiled TypeScript).
+// This file exists so `tsc` doesn't need to produce a shebang line.
+import('../dist/index.js').then((m) => m.main()).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/commands/create.d.ts

@@ -0,0 +1,6 @@
+import type { DatabaseProvider } from '../templates/database.js';
+export declare function create(name: string, opts: {
+    force?: boolean;
+    database?: DatabaseProvider;
+}): Promise<void>;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAAE,iBAoDvD"}

package/dist/commands/create.js

@@ -0,0 +1,48 @@
+import { access } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import { log, banner } from '../utils/log.js';
+import { writeFiles } from '../utils/fs.js';
+import { projectFiles } from '../templates/project.js';
+export async function create(name, opts) {
+    banner('create', '0.1.0');
+    const target = resolve(name);
+    const database = opts.database ?? 'sqlite';
+    if (!['sqlite', 'mysql', 'postgres'].includes(database)) {
+        log.error(`Unknown database: ${pc.cyan(database)}. Use sqlite, mysql, or postgres.`);
+        process.exit(1);
+    }
+    if (!opts.force) {
+        try {
+            await access(target);
+            log.error(`Directory already exists: ${pc.cyan(name)}`);
+            log.info(`Use ${pc.bold('--force')} to overwrite existing files.`);
+            process.exit(1);
+        }
+        catch {
+            // directory doesn't exist — good
+        }
+    }
+    log.step(`Scaffolding project: ${pc.bold(pc.cyan(name))} ${pc.gray(`(${database})`)}`);
+    log.blank();
+    const files = projectFiles(name, database);
+    await writeFiles(files, { force: opts.force });
+    log.blank();
+    log.success(`Project ${pc.bold(name)} created!`);
+    log.blank();
+    console.log(`  ${pc.bold('Next steps:')}`);
+    console.log();
+    console.log(`    ${pc.gray('1.')} ${pc.cyan(`cd ${name}`)}`);
+    console.log(`    ${pc.gray('2.')} ${pc.cyan('npm install')}`);
+    if (database !== 'sqlite') {
+        console.log(`    ${pc.gray('   ')} ${pc.yellow(`Edit apps/api/.env with your ${database} connection details first.`)}`);
+    }
+    console.log(`    ${pc.gray('3.')} Create the database: ${pc.cyan('cd apps/api && npm run db:migrate')}`);
+    console.log(`    ${pc.gray('4.')} Seed example data:   ${pc.cyan('npm run db:seed')}`);
+    console.log(`    ${pc.gray('5.')} Start the API:        ${pc.cyan('npm run dev')}`);
+    console.log(`    ${pc.gray('6.')} Start the web:        ${pc.cyan('cd apps/web && npm run dev')}`);
+    console.log(`    ${pc.gray('7.')} Open:                 ${pc.cyan('http://localhost:3000/admin')}`);
+    console.log();
+    console.log(`  ${pc.gray('Tip:')} Add more resources with ${pc.cyan('kargo make:resource <Name>')} inside ${pc.cyan('apps/api')}.`);
+    console.log();
+}

package/dist/commands/make-panel.d.ts

@@ -0,0 +1,7 @@
+interface MakePanelOpts {
+    outDir?: string;
+    force?: boolean;
+}
+export declare function makePanel(id: string, opts?: MakePanelOpts): Promise<void>;
+export {};
+//# sourceMappingURL=make-panel.d.ts.map

package/dist/commands/make-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-panel.d.ts","sourceRoot":"","sources":["../../src/commands/make-panel.ts"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAmBD,wBAAsB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,iBAsBnE"}

package/dist/commands/make-panel.js

@@ -0,0 +1,39 @@
+import { resolve, join } from 'node:path';
+import pc from 'picocolors';
+import { log } from '../utils/log.js';
+import { writeGeneratedFile } from '../utils/fs.js';
+function panelTemplate(id, path) {
+    return `import { Panel, registerPanel } from '@kargojs/core';
+
+export const ${id.replace(/-/g, '_')}Panel = registerPanel(
+  Panel.make({
+    id: '${id}',
+    path: '${path}',
+    globalSearch: true,
+    databaseNotifications: false,
+  })
+    .colors({
+      primary: '#2563eb',
+    }),
+);
+`;
+}
+export async function makePanel(id, opts = {}) {
+    const cwd = process.cwd();
+    const outDir = opts.outDir ?? join(cwd, 'src');
+    const filePath = resolve(outDir, `${id}.panel.ts`);
+    const adminPath = id === 'admin' ? '/admin' : `/${id}`;
+    log.blank();
+    log.step(`Generating panel: ${pc.bold(pc.cyan(id))}`);
+    log.blank();
+    await writeGeneratedFile(filePath, panelTemplate(id, adminPath), { force: opts.force });
+    log.blank();
+    log.success(`Panel ${pc.bold(id)} generated!`);
+    log.blank();
+    console.log(`  ${pc.bold('Import it in your app.module.ts:')}`);
+    console.log();
+    console.log(pc.gray(`    import { ${id.replace(/-/g, '_')}Panel } from './${id}.panel.js';`));
+    console.log();
+    console.log(pc.gray(`    KargoModule.forRoot({ panel: ${id.replace(/-/g, '_')}Panel, resources: [] })`));
+    console.log();
+}

package/dist/commands/make-resource.d.ts

@@ -0,0 +1,14 @@
+interface MakeResourceOpts {
+    /** Directory to write resource folders into (default: src/resources) */
+    resourceDir?: string;
+    /** Directory to write service files into (default: src/services) */
+    serviceDir?: string;
+    /** Skip generating the companion service file */
+    noService?: boolean;
+    /** Generate an in-memory array-backed service stub instead of a Prisma-backed one */
+    inMemory?: boolean;
+    force?: boolean;
+}
+export declare function makeResource(rawName: string, opts?: MakeResourceOpts): Promise<void>;
+export {};
+//# sourceMappingURL=make-resource.d.ts.map

package/dist/commands/make-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-resource.d.ts","sourceRoot":"","sources":["../../src/commands/make-resource.ts"],"names":[],"mappings":"AAaA,UAAU,gBAAgB;IACxB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAcD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,iBAuF9E"}

package/dist/commands/make-resource.js

@@ -0,0 +1,101 @@
+import { access, appendFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import pc from 'picocolors';
+import { log } from '../utils/log.js';
+import { writeGeneratedFile } from '../utils/fs.js';
+import { resourceNames } from '../utils/strings.js';
+import { resourceTemplate } from '../templates/resource.js';
+import { formTemplate } from '../templates/form.js';
+import { tableTemplate } from '../templates/table.js';
+import { serviceTemplate } from '../templates/service.js';
+import { serviceInMemoryTemplate } from '../templates/service-in-memory.js';
+import { registerResource } from '../utils/register-resource.js';
+async function appendPrismaModel(cwd, pascalName) {
+    const schemaPath = resolve(cwd, 'prisma', 'schema.prisma');
+    try {
+        await access(schemaPath);
+    }
+    catch {
+        return false;
+    }
+    const block = `\nmodel ${pascalName} {\n  id        Int      @id @default(autoincrement())\n  name      String\n  createdAt DateTime @default(now())\n}\n`;
+    await appendFile(schemaPath, block, 'utf8');
+    return true;
+}
+export async function makeResource(rawName, opts = {}) {
+    const n = resourceNames(rawName);
+    const cwd = process.cwd();
+    const resourceDir = opts.resourceDir ?? join(cwd, 'src', 'resources');
+    const serviceDir = opts.serviceDir ?? join(cwd, 'src', 'services');
+    const resourceFolder = join(resourceDir, n.kebab);
+    const resourcePath = resolve(resourceFolder, `${n.kebab}.resource.ts`);
+    const formPath = resolve(resourceFolder, `${n.kebab}.form.ts`);
+    const tablePath = resolve(resourceFolder, `${n.kebab}.table.ts`);
+    const servicePath = resolve(serviceDir, `${n.kebab}.service.ts`);
+    log.blank();
+    log.step(`Generating ${pc.bold(n.pascal)}Resource`);
+    log.blank();
+    await writeGeneratedFile(resourcePath, resourceTemplate(n), { force: opts.force });
+    await writeGeneratedFile(formPath, formTemplate(n), { force: opts.force });
+    await writeGeneratedFile(tablePath, tableTemplate(n), { force: opts.force });
+    if (!opts.noService) {
+        const content = opts.inMemory ? serviceInMemoryTemplate(n) : serviceTemplate(n);
+        await writeGeneratedFile(servicePath, content, { force: opts.force });
+    }
+    let modelAppended = false;
+    if (!opts.noService && !opts.inMemory) {
+        modelAppended = await appendPrismaModel(cwd, n.pascal);
+        if (modelAppended)
+            log.file(`prisma/schema.prisma (appended ${n.pascal} model)`);
+    }
+    log.blank();
+    log.success(`${pc.bold(n.pascal)}Resource generated!`);
+    log.blank();
+    let registered = false;
+    let registerReason;
+    if (!opts.noService) {
+        const appModulePath = resolve(cwd, 'src', 'app.module.ts');
+        try {
+            await access(appModulePath);
+            const result = registerResource({
+                appModulePath,
+                pascalName: n.pascal,
+                resourcePath,
+                servicePath,
+            });
+            registered = result.success;
+            registerReason = result.reason;
+        }
+        catch {
+            registerReason = 'src/app.module.ts not found';
+        }
+    }
+    if (registered) {
+        log.success(`Registered ${pc.bold(n.pascal)}Resource in ${pc.cyan('src/app.module.ts')}`);
+    }
+    else {
+        if (registerReason)
+            log.warn(`Could not auto-register: ${registerReason}`);
+        console.log(`  ${pc.bold('Register it in your app.module.ts:')}`);
+        console.log();
+        console.log(pc.gray(`    import { ${n.pascal}Resource } from './resources/${n.kebab}/${n.kebab}.resource.js';`));
+        if (!opts.noService) {
+            console.log(pc.gray(`    import { ${n.pascal}Service } from './services/${n.kebab}.service.js';`));
+        }
+        console.log();
+        console.log(pc.gray(`    KargoModule.forRoot({`));
+        console.log(pc.gray(`      panel: adminPanel,`));
+        console.log(pc.gray(`      resources: [`));
+        console.log(pc.gray(`        // ... existing resources`));
+        if (!opts.noService) {
+            console.log(pc.cyan(`        { resource: ${n.pascal}Resource, service: ${n.pascal}Service },`));
+        }
+        console.log(pc.gray(`      ],`));
+        console.log(pc.gray(`    })`));
+    }
+    if (modelAppended) {
+        console.log();
+        console.log(`  ${pc.gray('Tip:')} Run ${pc.cyan('npm run db:migrate')} to apply the new ${n.pascal} model.`);
+    }
+    console.log();
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare function main(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,wBAAsB,IAAI,kBA2DzB"}

package/dist/index.js

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import { create } from './commands/create.js';
+import { makeResource } from './commands/make-resource.js';
+import { makePanel } from './commands/make-panel.js';
+const VERSION = '0.1.0';
+export async function main() {
+    const program = new Command();
+    program
+        .name('kargo')
+        .description('Kargo admin framework CLI')
+        .version(VERSION, '-v, --version');
+    // ── kargo create <name> ──────────────────────────────────────────────
+    program
+        .command('create <name>')
+        .description('Scaffold a new Kargo project (NestJS API + Next.js web)')
+        .option('-f, --force', 'Overwrite existing files', false)
+        .option('--database <provider>', 'sqlite, mysql, or postgres', 'sqlite')
+        .action((name, opts) => create(name, opts));
+    // ── kargo make:resource <Name> ───────────────────────────────────────
+    program
+        .command('make:resource <name>')
+        .description('Generate a Resource class and its companion Service')
+        .option('--resource-dir <dir>', 'Directory for resource files', 'src/resources')
+        .option('--service-dir <dir>', 'Directory for service files', 'src/services')
+        .option('--no-service', 'Skip generating the service file')
+        .option('--in-memory', 'Generate an in-memory array-backed service stub instead of Prisma-backed', false)
+        .option('-f, --force', 'Overwrite existing files', false)
+        .action((name, opts) => makeResource(name, {
+        resourceDir: opts.resourceDir,
+        serviceDir: opts.serviceDir,
+        noService: !opts.service,
+        inMemory: opts.inMemory,
+        force: opts.force,
+    }));
+    // ── kargo make:panel [id] ────────────────────────────────────────────
+    program
+        .command('make:panel [id]')
+        .description('Generate a Panel configuration file')
+        .option('--out-dir <dir>', 'Directory to write the panel file', 'src')
+        .option('-f, --force', 'Overwrite existing files', false)
+        .action((id, opts) => makePanel(id ?? 'admin', { outDir: opts.outDir, force: opts.force }));
+    await program.parseAsync(process.argv);
+}

package/dist/templates/database.d.ts

@@ -0,0 +1,13 @@
+export type DatabaseProvider = 'sqlite' | 'mysql' | 'postgres';
+interface DbConfig {
+    /** schema.prisma datasource provider value */
+    prismaProvider: 'sqlite' | 'mysql' | 'postgresql';
+    adapterPackage: string;
+    adapterClass: string;
+    envContent: string;
+    /** Code that constructs the adapter instance, assigned to `const adapter = ...` */
+    adapterConstructor: string;
+}
+export declare function getDbConfig(database: DatabaseProvider): DbConfig;
+export {};
+//# sourceMappingURL=database.d.ts.map

package/dist/templates/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/templates/database.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE/D,UAAU,QAAQ;IAChB,8CAA8C;IAC9C,cAAc,EAAE,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,QAAQ,CA4ChE"}

package/dist/templates/database.js

@@ -0,0 +1,43 @@
+export function getDbConfig(database) {
+    switch (database) {
+        case 'postgres':
+            return {
+                prismaProvider: 'postgresql',
+                adapterPackage: '@prisma/adapter-pg',
+                adapterClass: 'PrismaPg',
+                envContent: 'DATABASE_URL="postgresql://user:password@localhost:5432/mydb"\n',
+                adapterConstructor: "new PrismaPg({ connectionString: process.env['DATABASE_URL']! })",
+            };
+        case 'mysql':
+            return {
+                prismaProvider: 'mysql',
+                adapterPackage: '@prisma/adapter-mariadb',
+                adapterClass: 'PrismaMariaDb',
+                envContent: [
+                    '# PrismaMariaDb takes discrete connection fields, not a single URL',
+                    'MYSQL_HOST=localhost',
+                    'MYSQL_PORT=3306',
+                    'MYSQL_USER=root',
+                    'MYSQL_PASSWORD=',
+                    'MYSQL_DATABASE=mydb',
+                    '',
+                ].join('\n'),
+                adapterConstructor: `new PrismaMariaDb({
+  host: process.env['MYSQL_HOST'] ?? 'localhost',
+  port: Number(process.env['MYSQL_PORT']) || 3306,
+  user: process.env['MYSQL_USER'],
+  password: process.env['MYSQL_PASSWORD'],
+  database: process.env['MYSQL_DATABASE'],
+})`,
+            };
+        case 'sqlite':
+        default:
+            return {
+                prismaProvider: 'sqlite',
+                adapterPackage: '@prisma/adapter-better-sqlite3',
+                adapterClass: 'PrismaBetterSqlite3',
+                envContent: 'DATABASE_URL="file:./dev.db"\n',
+                adapterConstructor: "new PrismaBetterSqlite3({ url: process.env['DATABASE_URL'] ?? 'file:./dev.db' })",
+            };
+    }
+}

package/dist/templates/form.d.ts

@@ -0,0 +1,3 @@
+import type { ResourceNames } from '../utils/strings.js';
+export declare function formTemplate(n: ResourceNames): string;
+//# sourceMappingURL=form.d.ts.map

package/dist/templates/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/templates/form.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAUrD"}

package/dist/templates/form.js

@@ -0,0 +1,11 @@
+export function formTemplate(n) {
+    return `import { FormSchema } from '@kargojs/core';
+import { TextInput } from '@kargojs/forms';
+
+export function ${n.camel}Form(): FormSchema {
+  return FormSchema.make([
+    TextInput.make('name').label('Name').required(),
+  ]);
+}
+`;
+}

package/dist/templates/project.d.ts

@@ -0,0 +1,7 @@
+import { type DatabaseProvider } from './database.js';
+/** All files generated by `kargo create <name>`. Returns an array of {path, content}. */
+export declare function projectFiles(name: string, database?: DatabaseProvider): Array<{
+    path: string;
+    content: string;
+}>;
+//# sourceMappingURL=project.d.ts.map

package/dist/templates/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/templates/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEnE,yFAAyF;AACzF,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,gBAA2B,GACpC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAge1C"}