create-openibm 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# `create-openibm`
+
+Scaffold a new IBM i application in seconds — interactive CLI that asks what you need and wires everything up.
+
+```bash
+npm create openibm@latest
+# or
+npx create-openibm
+# or pass the project name directly
+npx create-openibm my-ibmi-app
+```
+
+---
+
+## What it does
+
+```
+◆ create-openibm
+
+◇ Project name
+│  my-ibmi-app
+
+◇ Framework
+│  Express
+
+◇ IBM i transport
+│  HTTP  (SSH tunnel — recommended for development)
+
+◇ Starter examples  (space to toggle, enter to confirm)
+│  ◼ Program call
+│  ◼ Table query
+
+◇ Package manager
+│  npm
+
+◇ Initialize a git repository?
+│  Yes
+
+◇ Install dependencies now?
+│  Yes
+
+◆ Done! Next steps:
+
+  cd my-ibmi-app
+  cp .env.example .env
+  # fill in IBMI_SYSTEM, IBMI_USER, IBMI_PASS
+  npm run generate
+  npm run dev
+```
+
+---
+
+## Options
+
+| Question | Choices |
+|---|---|
+| Framework | **None** (plain Node.js), **Express**, **NestJS** |
+| Transport | **HTTP** (SSH tunnel), **HTTPS**, **SSH** (direct), **ODBC** (native DB2) |
+| Starter examples | **Program call** (XMLSERVICE *PGM), **Table query** (DB2 query builder) |
+| Package manager | **npm**, **pnpm**, **Yarn** |
+| Git init | Yes / No |
+| Install deps | Yes / No |
+
+---
+
+## Generated structure
+
+### None (plain Node.js)
+
+```
+my-ibmi-app/
+├── schema.ibmi          ← define your programs and tables here
+├── src/
+│   ├── index.ts         ← connect, call, query, disconnect
+│   └── generated/ibmi/  ← created by: npm run generate
+├── .env.example
+├── tsconfig.json
+└── package.json
+```
+
+### Express
+
+```
+my-ibmi-app/
+├── schema.ibmi
+├── src/
+│   ├── index.ts         ← Express server with IBM i routes
+│   └── generated/ibmi/
+├── .env.example
+├── tsconfig.json
+└── package.json
+```
+
+### NestJS
+
+```
+my-ibmi-app/
+├── schema.ibmi
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── ibmi/
+│   │   ├── ibmi.module.ts      ← provides IBMiService
+│   │   ├── ibmi.service.ts     ← wraps generated client, auto connect/disconnect
+│   │   └── ibmi.controller.ts  ← HTTP endpoints
+│   └── generated/ibmi/
+├── .env.example
+├── tsconfig.json
+└── package.json
+```
+
+---
+
+## After scaffolding
+
+```bash
+cp .env.example .env
+```
+
+Fill in your IBM i credentials:
+
+```bash
+IBMI_TRANSPORT=http
+IBMI_SYSTEM=your-ibmi-host
+IBMI_USER=your-username
+IBMI_PASS=your-password
+IBMI_PORT=57700
+IBMI_DATABASE=*LOCAL
+```
+
+Then generate the typed client from your schema:
+
+```bash
+npm run generate
+```
+
+This reads `schema.ibmi` and writes a fully typed TypeScript client to `src/generated/ibmi/`.
+
+---
+
+## Transport notes
+
+| Transport | Notes |
+|---|---|
+| **HTTP** | Recommended for development. Requires an SSH tunnel: `ssh -L 57700:localhost:57700 user@ibmi-host` |
+| **HTTPS** | Same as HTTP but TLS. Default port 47700. |
+| **SSH** | Direct connection. Install the `ssh2` peer dep: `npm install ssh2`. Also install `xmlservice-utils` on IBM i. |
+| **ODBC** | Native DB2 pool. Best for production. Install `odbc` and the IBM i Access ODBC Driver. |
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { scaffold } from './scaffold.js';
+async function main() {
+    // Accept project name as positional arg: npx create-openibm my-app
+    const argName = process.argv[2];
+    console.log();
+    p.intro(' ◆ create-openibm ');
+    // ── Project name ──────────────────────────────────────────────────────────
+    let projectName;
+    if (argName && !argName.startsWith('-')) {
+        projectName = argName;
+    }
+    else {
+        const res = await p.text({
+            message: 'Project name',
+            placeholder: 'my-ibmi-app',
+            validate: v => (v.trim() ? undefined : 'Project name is required'),
+        });
+        if (p.isCancel(res)) {
+            p.cancel('Cancelled.');
+            process.exit(0);
+        }
+        projectName = res.trim();
+    }
+    const dir = resolve(process.cwd(), projectName);
+    if (existsSync(dir)) {
+        const overwrite = await p.confirm({
+            message: `Directory "${projectName}" already exists. Continue anyway?`,
+            initialValue: false,
+        });
+        if (p.isCancel(overwrite) || !overwrite) {
+            p.cancel('Aborted.');
+            process.exit(0);
+        }
+    }
+    // ── Framework ─────────────────────────────────────────────────────────────
+    const framework = await p.select({
+        message: 'Framework',
+        options: [
+            { value: 'basic', label: 'None', hint: 'plain Node.js script' },
+            { value: 'express', label: 'Express', hint: 'lightweight HTTP server' },
+            { value: 'nestjs', label: 'NestJS', hint: 'enterprise-grade framework with DI' },
+        ],
+    });
+    if (p.isCancel(framework)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    // ── Transport ─────────────────────────────────────────────────────────────
+    const transport = await p.select({
+        message: 'IBM i transport',
+        options: [
+            { value: 'http', label: 'HTTP', hint: 'SSH tunnel — recommended for development' },
+            { value: 'https', label: 'HTTPS', hint: 'secure HTTP, port 47700' },
+            { value: 'ssh', label: 'SSH', hint: 'direct connection — install ssh2 peer dep' },
+            { value: 'odbc', label: 'ODBC', hint: 'native DB2 pool — recommended for production' },
+        ],
+    });
+    if (p.isCancel(transport)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    // ── Starter examples ──────────────────────────────────────────────────────
+    const features = await p.multiselect({
+        message: 'Starter examples  (space to toggle, enter to confirm)',
+        options: [
+            { value: 'program', label: 'Program call', hint: 'XMLSERVICE *PGM example in schema.ibmi' },
+            { value: 'table', label: 'Table query', hint: 'DB2 query builder example in schema.ibmi' },
+        ],
+        required: false,
+    });
+    if (p.isCancel(features)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    // ── Package manager ───────────────────────────────────────────────────────
+    const pkgManager = await p.select({
+        message: 'Package manager',
+        options: [
+            { value: 'npm', label: 'npm' },
+            { value: 'pnpm', label: 'pnpm' },
+            { value: 'yarn', label: 'Yarn' },
+        ],
+    });
+    if (p.isCancel(pkgManager)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    // ── Extras ────────────────────────────────────────────────────────────────
+    const gitInit = await p.confirm({ message: 'Initialize a git repository?' });
+    if (p.isCancel(gitInit)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    const install = await p.confirm({ message: 'Install dependencies now?' });
+    if (p.isCancel(install)) {
+        p.cancel('Cancelled.');
+        process.exit(0);
+    }
+    // ── Scaffold ──────────────────────────────────────────────────────────────
+    const answers = {
+        projectName,
+        framework: framework,
+        transport: transport,
+        features: features,
+        pkgManager: pkgManager,
+        gitInit: gitInit,
+        install: install,
+    };
+    const s = p.spinner();
+    s.start('Scaffolding project…');
+    scaffold(answers, dir);
+    s.stop('Files written.');
+    // ── Git init ──────────────────────────────────────────────────────────────
+    if (answers.gitInit) {
+        try {
+            execSync('git init', { cwd: dir, stdio: 'ignore' });
+            execSync('git add -A', { cwd: dir, stdio: 'ignore' });
+        }
+        catch { /* git not available */ }
+    }
+    // ── Install deps ──────────────────────────────────────────────────────────
+    if (answers.install) {
+        const is = p.spinner();
+        is.start(`Installing with ${pkgManager}…`);
+        try {
+            const cmd = pkgManager === 'yarn' ? 'yarn' : `${pkgManager} install`;
+            execSync(cmd, { cwd: dir, stdio: 'pipe' });
+            is.stop('Dependencies installed.');
+        }
+        catch {
+            is.stop('Install failed — run it manually.');
+        }
+    }
+    // ── Done ──────────────────────────────────────────────────────────────────
+    const pm = answers.pkgManager;
+    const run = pm === 'npm' ? 'npm run' : pm;
+    p.outro([
+        'Done! Next steps:',
+        '',
+        `  cd ${dir}`,
+        `  cp .env.example .env`,
+        `  # fill in IBMI_SYSTEM, IBMI_USER, IBMI_PASS`,
+        ...(answers.install ? [] : [`  ${pm} install`]),
+        `  ${run} generate`,
+        `  ${run} dev`,
+    ].join('\n'));
+}
+main().catch(e => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/scaffold.d.ts

@@ -0,0 +1,12 @@
+export interface Answers {
+    projectName: string;
+    framework: 'basic' | 'express' | 'nestjs';
+    transport: 'http' | 'https' | 'ssh' | 'odbc';
+    features: ('program' | 'table')[];
+    pkgManager: 'npm' | 'pnpm' | 'yarn';
+    gitInit: boolean;
+    install: boolean;
+}
+/** Relative file path → file content */
+export type FileMap = Record<string, string>;
+export declare function scaffold(answers: Answers, outDir: string): void;

package/dist/scaffold.js

@@ -0,0 +1,22 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { baseFiles } from './templates/base.js';
+import { basicFiles } from './templates/basic.js';
+import { expressFiles } from './templates/express.js';
+import { nestjsFiles } from './templates/nestjs.js';
+const frameworkFiles = {
+    basic: basicFiles,
+    express: expressFiles,
+    nestjs: nestjsFiles,
+};
+export function scaffold(answers, outDir) {
+    const files = {
+        ...baseFiles(answers),
+        ...frameworkFiles[answers.framework](answers),
+    };
+    for (const [relPath, content] of Object.entries(files)) {
+        const abs = join(outDir, relPath);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content, 'utf8');
+    }
+}

package/dist/templates/base.d.ts

@@ -0,0 +1,2 @@
+import type { Answers, FileMap } from '../scaffold.js';
+export declare function baseFiles(a: Answers): FileMap;

package/dist/templates/base.js

@@ -0,0 +1,58 @@
+export function baseFiles(a) {
+    return {
+        'schema.ibmi': schemaIbmi(a),
+        '.env.example': envExample(a),
+        '.gitignore': gitignore(),
+    };
+}
+// ── schema.ibmi ───────────────────────────────────────────────────────────────
+function schemaIbmi(a) {
+    const blocks = [
+        `datasource ibmi {`,
+        `    transport = env("IBMI_TRANSPORT")`,
+        `    system    = env("IBMI_SYSTEM")`,
+        `}`,
+        ``,
+        `generator client {`,
+        `    output = "./src/generated/ibmi"`,
+        `}`,
+    ];
+    if (a.features.includes('program')) {
+        blocks.push(``, `// RPG/COBOL program — JS name maps to actual IBM i program via @map`, `program SimpleCalc @map("SIMPLECALC") {`, `    library = "MYLIB"`, `    input   PackedDecimal(15, 0) @in`, `    output  PackedDecimal(16, 0) @out`, `}`);
+    }
+    if (a.features.includes('table')) {
+        blocks.push(``, `// DB2 table — JS field names map to real column names via @map`, `table Customer @map("QIWS.QCUSTCDT") {`, `    customerId  Int          @id  @map("CUSNUM")`, `    lastName    Char(8)           @map("LSTNAM")`, `    initials    Char(3)           @map("INIT")`, `    city        Char(6)           @map("CITY")`, `    state       Char(2)           @map("STATE")`, `    creditLimit Decimal(6, 0)     @map("CDTLMT")`, `    balanceDue  Decimal(6, 2)     @map("BALDUE")`, `}`);
+    }
+    return blocks.join('\n') + '\n';
+}
+// ── .env.example ──────────────────────────────────────────────────────────────
+function envExample(a) {
+    const lines = [
+        `IBMI_TRANSPORT=${a.transport}`,
+        `IBMI_SYSTEM=your-ibmi-host`,
+        `IBMI_USER=your-username`,
+        `IBMI_PASS=your-password`,
+    ];
+    if (a.transport === 'http' || a.transport === 'https') {
+        const defaultPort = a.transport === 'https' ? '47700' : '57700';
+        lines.push(`IBMI_PORT=${defaultPort}`);
+        lines.push(`IBMI_DATABASE=*LOCAL`);
+    }
+    return lines.join('\n') + '\n';
+}
+// ── .gitignore ────────────────────────────────────────────────────────────────
+function gitignore() {
+    return [
+        'node_modules/',
+        'dist/',
+        '.env',
+        '*.tsbuildinfo',
+        '',
+        '# Generated IBM i client — re-create with: npm run generate',
+        'src/generated/',
+        '',
+        '# OS',
+        '.DS_Store',
+        'Thumbs.db',
+    ].join('\n') + '\n';
+}

package/dist/templates/basic.d.ts

@@ -0,0 +1,11 @@
+import type { Answers, FileMap } from '../scaffold.js';
+export declare function basicFiles(a: Answers): FileMap;
+export declare function clientConfigBlock(a: Answers): string;
+/**
+ * scripts/link-dev.mjs — shared by all templates.
+ * Uses `pnpm add file:...` so pnpm installs ALL deps in one shot while
+ * pulling @openibm/* from the globally linked monorepo packages.
+ */
+export declare function linkDevScriptMjs(): string;
+/** Zod-based IBM i data-type validators — shared by basic + express templates */
+export declare function ibmiValidatorsTs(): string;