shutro-erp 0.2.1 → 0.3.0

package/dist/cli/init.js

@@ -15,11 +15,13 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { base, createServer, DEMO_PASSWORD, FRAMEWORK_TABLES, installBase, installDemo, KOSH_VERSION, migrate, pg, recordInstalledApps, } from '../server/index.js';
+import { launch } from './launch.js';
 import { seed } from './project.js';
-import { defaultsPrompter, terminalPrompter } from './prompt.js';
+import { choose, chooseMany, defaultsPrompter, terminalPrompter } from './prompt.js';
 import * as templates from './templates.js';
-import { APPS, bridgesFor, SELECTABLE_APPS } from './templates.js';
-import { createUi, PLAIN_TERMINAL } from './ui.js';
+import { APPS, bridgesFor, COUNTRY_NAMES, LOCALIZED_COUNTRIES, SELECTABLE_APPS, } from './templates.js';
+import { CancelledError, interactivePrompter } from './tui.js';
+import { createUi, PLAIN_TERMINAL, railed } from './ui.js';
 /**
  * The version of the `shutro-erp` package this CLI runs from: new projects depend on it. In the workspace (no such
  * package around the CLI) the framework version stands in.
@@ -48,6 +50,8 @@ Options (each also answers its question; with --yes the rest take their defaults
   --docker-db               start PostgreSQL in Docker (compose.yaml) instead
   --create-database         create the database when it does not exist
   --company <name>          the first company        --currency <code>   its currency (ISO 4217)
+  --country <code>          the company's country (ISO 3166): ${LOCALIZED_COUNTRIES.join(', ')} install its localization
+                            with Accounting (default: BD for BDT, IN for INR, none otherwise; "none" for none)
   --lang <en|bn>            language                 --tz <zone>         time zone (IANA)
   --admin-login <login>     --admin-name <name>      --admin-email <email>
   --admin-password <pw>     (or KOSH_ADMIN_PASSWORD; at least 12 characters)
@@ -55,10 +59,13 @@ Options (each also answers its question; with --yes the rest take their defaults
   --storage-dir <dir>       attachments in a folder (default ./var/attachments)
   --s3-endpoint <url> --s3-bucket <name> --s3-access-key <key> --s3-secret-key <secret> [--s3-region <r>]
   --valkey-url <url>        optional: rate limits and caches shared across servers
-  --port <port>             the API's port (default 3000)
+  --port <port>             the API's port (default 3000, or the next free one)
+  --web-port <port>         the back-office's port in development (default 5173, or the next free one)
   --demo                    load demo data: a sample company with contacts, products, orders, invoices and
                             projects, made by demo users (dina, rahim, karim, sumi; one shared password)
   --no-2fa                  skip the authenticator enrolment (administrator rights wait for it)
+  --no-start                do not install, start and open the installation at the end (in a terminal it
+                            installs the dependencies, starts the API and the back-office, opens the browser)
   --yes                     do not ask; use flags and defaults
 `;
 const dockerAvailable = () => spawnSync('docker', ['version', '--format', '{{.Server.Version}}'], { encoding: 'utf8' })
@@ -228,9 +235,19 @@ async function ask(prompter, flags, cwd, positional, ui) {
     if (flag('database-url') === undefined) {
         const docker = flags['docker-db'] === true ||
             (dockerAvailable() && flags['yes'] !== true
-                ? (await q(null, 'PostgreSQL: (1) a server I already have, or (2) start one in Docker for me', '2', {
-                    validate: (v) => (v === '1' || v === '2' ? null : '1 or 2'),
-                })) === '2'
+                ? (await choose(prompter, {
+                    message: 'Which PostgreSQL?',
+                    fallback: 'PostgreSQL: (1) a server I already have, or (2) start one in Docker for me',
+                    choices: [
+                        { value: 'server', label: 'A server I already have', hint: 'host, port, user' },
+                        {
+                            value: 'docker',
+                            label: 'Start one in Docker for me',
+                            hint: 'PostgreSQL 18, its own volume',
+                        },
+                    ],
+                    default: 'docker',
+                })) === 'docker'
                 : false);
         if (docker) {
             if (!dockerAvailable())
@@ -312,9 +329,41 @@ async function ask(prompter, flags, cwd, positional, ui) {
     const currency = (await q('currency', 'Currency (ISO code)', 'BDT', {
         validate: (v) => (/^[A-Za-z]{3}$/.test(v) ? null : 'Three letters, e.g. BDT, USD, EUR'),
     })).toUpperCase();
-    const lang = await q('lang', 'Language (en, bn)', 'en', {
-        validate: (v) => (['en', 'bn'].includes(v) ? null : 'en or bn'),
-    });
+    const countryFlag = flag('country');
+    if (countryFlag !== undefined && !/^([A-Za-z]{2}|none)$/i.test(countryFlag))
+        throw new Error('--country: Two letters, e.g. BD, or none');
+    const countryAnswer = (countryFlag ??
+        (await choose(prompter, {
+            message: 'Country (taxes, chart of accounts, fiscal year)',
+            fallback: `Country (ISO code; ${LOCALIZED_COUNTRIES.join(', ')} set up taxes and the chart; "none" for none)`,
+            choices: [
+                ...LOCALIZED_COUNTRIES.map((c) => ({
+                    value: c,
+                    label: COUNTRY_NAMES[c] ?? c,
+                    hint: 'its taxes, chart and returns',
+                })),
+                {
+                    value: 'none',
+                    label: 'Another country',
+                    hint: 'the generic chart; taxes are yours to add',
+                },
+            ],
+            default: currency === 'BDT' ? 'BD' : currency === 'INR' ? 'IN' : 'none',
+        }))).toUpperCase();
+    const country = countryAnswer === 'NONE' ? '' : countryAnswer;
+    const langFlag = flag('lang');
+    if (langFlag !== undefined && !['en', 'bn'].includes(langFlag))
+        throw new Error('--lang: en or bn');
+    const lang = langFlag ??
+        (await choose(prompter, {
+            message: 'Language',
+            fallback: 'Language (en, bn)',
+            choices: [
+                { value: 'en', label: 'English' },
+                { value: 'bn', label: 'বাংলা', hint: 'Bangla' },
+            ],
+            default: 'en',
+        }));
     const tz = await q('tz', 'Time zone', Intl.DateTimeFormat().resolvedOptions().timeZone, {
         validate: (v) => {
             try {
@@ -355,36 +404,43 @@ async function ask(prompter, flags, cwd, positional, ui) {
             ui.warn('The passwords differ; try again.');
         }
     ui.step('apps', 'Apps', 'All are selected; remove the ones you do not need');
-    for (const key of SELECTABLE_APPS) {
-        const app = APPS[key];
-        ui.write(`  ${ui.terminal.emoji ? app.icon : ui.style('cyan', '•')}  ${ui.style('bold', key.padEnd(12))} ${ui.style('gray', app.label)}\n`);
-    }
-    const appList = await q('apps', 'Apps to install (comma-separated)', SELECTABLE_APPS.join(','), {
-        validate: (v) => {
-            const unknown = v
-                .split(',')
-                .map((s) => s.trim())
-                .filter((s) => s !== '' && !(s in APPS));
-            return unknown.length === 0 ? null : `Unknown: ${unknown.join(', ')}`;
-        },
-    });
-    const chosen = [
-        ...new Set(appList
-            .split(',')
-            .map((s) => s.trim())
-            .filter((s) => s in APPS)),
-    ];
-    // The bridges of the chosen apps come along (RFC 0008 §5.1).
-    const apps = [...chosen, ...bridgesFor(chosen).filter((b) => !chosen.includes(b))];
+    const appsFlag = flag('apps');
+    if (appsFlag === undefined && prompter.multiselect === undefined)
+        for (const key of SELECTABLE_APPS) {
+            const app = APPS[key];
+            ui.write(`  ${ui.terminal.emoji ? app.icon : ui.style('cyan', '•')}  ${ui.style('bold', key.padEnd(12))} ${ui.style('gray', app.label)}\n`);
+        }
+    const unknownApps = (appsFlag ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s !== '' && !(s in APPS));
+    if (unknownApps.length > 0)
+        throw new Error(`--apps: Unknown: ${unknownApps.join(', ')}`);
+    const appList = appsFlag?.split(',').map((s) => s.trim()) ??
+        (await chooseMany(prompter, {
+            message: 'Apps to install',
+            fallback: 'Apps to install (comma-separated)',
+            choices: SELECTABLE_APPS.map((key) => ({ value: key, label: key, hint: APPS[key].label })),
+            defaults: SELECTABLE_APPS,
+        }));
+    const chosen = [...new Set(appList.filter((s) => s in APPS))];
+    // The bridges of the chosen apps come along (RFC 0008 §5.1), and the country's localization (RFC 0016).
+    const apps = [...chosen, ...bridgesFor(chosen, country).filter((b) => !chosen.includes(b))];
     const demo = flags['demo'] === true ||
         (await prompter.confirm('  Load demo data (a sample company with orders, invoices and projects; not for production)?', false));
     ui.step('storage', 'File storage', 'Where attachments and generated documents are kept');
     let storage;
     const s3 = flag('s3-endpoint') !== undefined ||
         (flag('storage-dir') === undefined &&
-            (await q(null, 'Store files in (1) a folder or (2) S3-compatible storage', '1', {
-                validate: (v) => (v === '1' || v === '2' ? null : '1 or 2'),
-            })) === '2');
+            (await choose(prompter, {
+                message: 'Where are files kept?',
+                fallback: 'Store files in (1) a folder or (2) S3-compatible storage',
+                choices: [
+                    { value: 'dir', label: 'A folder on this server', hint: './var/attachments' },
+                    { value: 's3', label: 'S3-compatible storage', hint: 'AWS S3, MinIO, SeaweedFS, R2' },
+                ],
+                default: 'dir',
+            })) === 's3');
     if (s3)
         storage = {
             kind: 's3',
@@ -407,17 +463,20 @@ async function ask(prompter, flags, cwd, positional, ui) {
         };
     else
         storage = { kind: 'dir', dir: await q('storage-dir', 'Folder', './var/attachments') };
-    ui.step('server', 'Server', 'The API port and an optional shared cache');
-    const valkeyUrl = await q('valkey-url', 'Valkey/Redis URL (optional, Enter to skip)', '');
-    const port = Number(await q('port', 'API port', '3000', {
-        validate: (v) => /^\d+$/.test(v) && Number(v) > 0 && Number(v) < 65536 ? null : 'A port number',
+    ui.step('server', 'Server', 'The ports of the API and the back-office, and an optional shared cache');
+    const portNumber = (v) => /^\d+$/.test(v) && Number(v) > 0 && Number(v) < 65536 ? null : 'A port number (1–65535)';
+    const port = Number(await q('port', 'API port', String(await freePort(3000)), { validate: portNumber }));
+    const webPort = Number(await q('web-port', 'Back-office (web) port', String(await freePort(port === 5173 ? 5174 : 5173)), {
+        validate: (v) => portNumber(v) ?? (Number(v) === port ? 'Another port than the API' : null),
     }));
+    const valkeyUrl = await q('valkey-url', 'Valkey/Redis URL (optional, Enter to skip)', '');
     return {
         dir,
         name,
         databaseUrl,
         company,
         currency,
+        country,
         lang,
         tz,
         admin: { login, name: adminName, email, password: password },
@@ -426,6 +485,7 @@ async function ask(prompter, flags, cwd, positional, ui) {
         storage,
         valkeyUrl,
         port,
+        webPort,
         postgres,
         dockerDb,
         vapid: (await import('../notify/index.js')).generateVapidKeys(),
@@ -444,6 +504,7 @@ async function modulesFor(apps) {
         (await import('../mail/index.js')).mail,
         (await import('../automation/index.js')).automation,
         (await import('../studio/index.js')).studio,
+        (await import('../import/index.js')).dataImport,
     ];
     for (const app of apps) {
         if (app === 'permissions')
@@ -471,6 +532,10 @@ async function modulesFor(apps) {
             modules.push((await import('../project/index.js')).project);
         if (app === 'sale_project')
             modules.push((await import('../sale_project/index.js')).saleProject);
+        if (app === 'l10n_bd')
+            modules.push((await import('../l10n_bd/index.js')).l10nBd);
+        if (app === 'l10n_in')
+            modules.push((await import('../l10n_in/index.js')).l10nIn);
     }
     return modules;
 }
@@ -486,7 +551,7 @@ function envFile(a) {
         lines.push(`S3_ENDPOINT=${a.storage.endpoint}`, `S3_BUCKET=${a.storage.bucket}`, `S3_ACCESS_KEY=${a.storage.accessKey}`, `S3_SECRET_KEY=${a.storage.secretKey}`, `S3_REGION=${a.storage.region}`);
     if (a.valkeyUrl !== '')
         lines.push(`VALKEY_URL=${a.valkeyUrl}`);
-    lines.push('', '# Where users open the back-office (links in emails and notifications).', 'KOSH_BASE_URL=http://localhost:5173', '# Email notifications: an SMTP server (Mailpit in development: smtp://localhost:1025, inbox on :8025).', '# SMTP_URL=smtp://user:password@smtp.example.com:587', '# MAIL_FROM=Kosh <no-reply@example.com>', '# Replies by email (RFC 0006 part 7): the inbound mailbox domain, and the webhook secret your provider sends.', `MAIL_INBOUND_SECRET=${a.inboundSecret}`, '# MAIL_INBOUND_DOMAIN=mail.example.com', '# MAIL_INBOUND_ALIAS=reply', `MAIL_INBOUND_WEBHOOK_SECRET=${a.inboundWebhookSecret}`, '# Without a webhook provider, a mailbox read every 30 s: IMAP_URL=imaps://user:password@host:993/INBOX', '', '# Kosh Studio (RFC 0012): propose (default: changes become patches) or write (development, one server: Studio', '# writes src/modules/<name>/ and applies at once). KOSH_STUDIO_DIR: the project folder (default: the working one).', '# KOSH_STUDIO=write', '# Proposals as pull requests (GitHub) or merge requests (GitLab): the repository and a token with the rights', '# to push branches and open them. Without them, proposals are patches to download.', '# KOSH_STUDIO_GIT_URL=https://github.com/acme/erp', '# KOSH_STUDIO_GIT_TOKEN=', '# KOSH_STUDIO_GIT_BASE=main', '', '# The AI assistant (RFC 0013): off until an administrator switches it on in Settings → AI assistant.', '# ANTHROPIC_API_KEY=', '# KOSH_ASSISTANT_MODEL=claude-opus-5-5', '# KOSH_ASSISTANT_MONTHLY_TOKENS=2000000', '', '# SMS and WhatsApp through Twilio (opt-in per user; a phone number on the user).', '# TWILIO_ACCOUNT_SID=', '# TWILIO_AUTH_TOKEN=', '# TWILIO_SMS_FROM=+1...', '# TWILIO_WHATSAPP_FROM=+1...', '', '# Web push (generated by kosh init; keep them, browsers subscribed with the public key stay subscribed).', `VAPID_PUBLIC_KEY=${a.vapid.publicKey}`, `VAPID_PRIVATE_KEY=${a.vapid.privateKey}`, `VAPID_SUBJECT=${a.admin.email === '' ? 'mailto:admin@localhost' : `mailto:${a.admin.email}`}`);
+    lines.push('', '# Where users open the back-office (links in emails and notifications).', `KOSH_BASE_URL=http://localhost:${a.webPort}`, '# Email notifications: an SMTP server (Mailpit in development: smtp://localhost:1025, inbox on :8025).', '# SMTP_URL=smtp://user:password@smtp.example.com:587', '# MAIL_FROM=Kosh <no-reply@example.com>', '# Replies by email (RFC 0006 part 7): the inbound mailbox domain, and the webhook secret your provider sends.', `MAIL_INBOUND_SECRET=${a.inboundSecret}`, '# MAIL_INBOUND_DOMAIN=mail.example.com', '# MAIL_INBOUND_ALIAS=reply', `MAIL_INBOUND_WEBHOOK_SECRET=${a.inboundWebhookSecret}`, '# Without a webhook provider, a mailbox read every 30 s: IMAP_URL=imaps://user:password@host:993/INBOX', '', '# Kosh Studio (RFC 0012): propose (default: changes become patches) or write (development, one server: Studio', '# writes src/modules/<name>/ and applies at once). KOSH_STUDIO_DIR: the project folder (default: the working one).', '# KOSH_STUDIO=write', '# Proposals as pull requests (GitHub) or merge requests (GitLab): the repository and a token with the rights', '# to push branches and open them. Without them, proposals are patches to download.', '# KOSH_STUDIO_GIT_URL=https://github.com/acme/erp', '# KOSH_STUDIO_GIT_TOKEN=', '# KOSH_STUDIO_GIT_BASE=main', '', '# The AI assistant (RFC 0013): off until an administrator switches it on in Settings → AI assistant.', '# ANTHROPIC_API_KEY=', '# KOSH_ASSISTANT_MODEL=claude-opus-5-5', '# KOSH_ASSISTANT_MONTHLY_TOKENS=2000000', '', '# SMS and WhatsApp through Twilio (opt-in per user; a phone number on the user).', '# TWILIO_ACCOUNT_SID=', '# TWILIO_AUTH_TOKEN=', '# TWILIO_SMS_FROM=+1...', '# TWILIO_WHATSAPP_FROM=+1...', '', '# Web push (generated by kosh init; keep them, browsers subscribed with the public key stay subscribed).', `VAPID_PUBLIC_KEY=${a.vapid.publicKey}`, `VAPID_PRIVATE_KEY=${a.vapid.privateKey}`, `VAPID_SUBJECT=${a.admin.email === '' ? 'mailto:admin@localhost' : `mailto:${a.admin.email}`}`);
     lines.push('', '# PostgreSQL in Docker (compose.yaml): docker compose up -d db, or everything with docker compose up -d --build', `POSTGRES_USER=${a.postgres.user}`, `POSTGRES_PASSWORD=${a.postgres.password}`, `POSTGRES_DB=${a.postgres.db}`, `POSTGRES_PORT=${a.postgres.port}`);
     return `${lines.join('\n')}\n`;
 }
@@ -496,6 +561,7 @@ async function writeProject(a, ui) {
         name: a.name,
         apps: a.apps,
         port: a.port,
+        webPort: a.webPort,
         koshVersion: releaseVersion(),
         dockerDb: a.postgres.db,
         fileStorage: a.storage.kind === 'dir',
@@ -694,6 +760,7 @@ export async function runInit(argv, io) {
             'create-database': { type: 'boolean' },
             company: { type: 'string' },
             currency: { type: 'string' },
+            country: { type: 'string' },
             lang: { type: 'string' },
             tz: { type: 'string' },
             'admin-login': { type: 'string' },
@@ -709,7 +776,9 @@ export async function runInit(argv, io) {
             's3-region': { type: 'string' },
             'valkey-url': { type: 'string' },
             port: { type: 'string' },
+            'web-port': { type: 'string' },
             'no-2fa': { type: 'boolean' },
+            'no-start': { type: 'boolean' },
             demo: { type: 'boolean' },
             'docker-db': { type: 'boolean' },
             yes: { type: 'boolean', short: 'y' },
@@ -723,15 +792,34 @@ export async function runInit(argv, io) {
     const terminal = io.terminal ?? PLAIN_TERMINAL;
     const interactive2fa = values['no-2fa'] !== true && values.yes !== true;
     // Six question steps, then the project files and the database, then (interactively) the second factor.
-    const ui = createUi(io.write, terminal, { steps: interactive2fa ? 9 : 8 });
+    // At the end, in a terminal: install, start and open the installation (not for scripts, CI and tests).
+    const autoStart = values['no-start'] !== true && io.prompter === undefined && process.stdout.isTTY === true;
+    const ui = createUi(io.write, terminal, {
+        steps: (interactive2fa ? 9 : 8) + (autoStart ? 1 : 0),
+    });
+    const interactive = io.prompter === undefined &&
+        values.yes !== true &&
+        process.stdin.isTTY === true &&
+        railed(terminal);
     const asked = io.prompter ??
         (values.yes === true
             ? defaultsPrompter()
-            : terminalPrompter(process.stdin, process.stdout, {
-                marker: ui.style('cyan', '? '),
-                fallback: (t) => ui.style('gray', t),
-                problem: (t) => ui.style('yellow', `${terminal.unicode ? '▲' : '!'} ${t}`),
-            }));
+            : interactive
+                ? interactivePrompter(process.stdin, process.stdout, terminal)
+                : terminalPrompter(process.stdin, process.stdout, {
+                    marker: ui.style('cyan', '? '),
+                    fallback: (t) => ui.style('gray', t),
+                    problem: (t) => ui.style('yellow', `${terminal.unicode ? '▲' : '!'} ${t}`),
+                }));
+    const paused = async (work) => {
+        ui.pause();
+        try {
+            return await work();
+        }
+        finally {
+            ui.resume();
+        }
+    };
     // A question stops the spinner while it is asked (the prompter writes to the terminal itself).
     const prompter = {
         async ask(q) {
@@ -752,13 +840,23 @@ export async function runInit(argv, io) {
                 ui.resume();
             }
         },
+        ...(asked.select === undefined
+            ? {}
+            : { select: (q) => paused(() => asked.select(q)) }),
+        ...(asked.multiselect === undefined
+            ? {}
+            : {
+                multiselect: (q) => paused(() => asked.multiselect(q)),
+            }),
         close: () => asked.close(),
     };
     let server;
     const started = Date.now();
     try {
         await ui.banner(`The ERP framework on Shutro · v${releaseVersion()}`);
-        ui.write(`  ${ui.style('gray', 'Kosh setup: press Enter to keep the value in [brackets].')}\n`);
+        ui.intro('Kosh setup', interactive
+            ? 'Enter keeps the default · ↑ ↓ choose · Space ticks · Ctrl+C quits'
+            : 'Kosh setup: press Enter to keep the value in [brackets].');
         const answers = await ask(prompter, values, io.cwd, positionals[0], ui);
         ui.step('files', 'Project files', answers.dir);
         await ui.task('Writing the project', async () => {
@@ -803,7 +901,10 @@ export async function runInit(argv, io) {
         else if (values.yes === true && values['no-2fa'] !== true)
             ui.info('The authenticator app is enrolled interactively: run npx kosh init again (without --yes).');
         const rows = [
-            ['Company', `${answers.company} (${answers.currency})`],
+            [
+                'Company',
+                `${answers.company} (${answers.currency}${answers.country === '' ? '' : `, ${answers.country}`})`,
+            ],
             [
                 'Administrator',
                 `${answers.admin.login} ${ui.style(enrolled ? 'green' : 'yellow', enrolled ? '· 2FA on' : '· 2FA pending')}`,
@@ -818,6 +919,7 @@ export async function runInit(argv, io) {
                     'mail',
                     'automation',
                     'studio',
+                    'import',
                     ...answers.apps,
                 ].join(', '),
             ],
@@ -825,20 +927,42 @@ export async function runInit(argv, io) {
                 ? [['Demo users', `dina, rahim, karim, sumi · password "${DEMO_PASSWORD}"`]]
                 : []),
             ['Database', answers.dockerDb ? `Docker (port ${answers.postgres.port})` : 'your server'],
+            ['Back-office', `http://localhost:${answers.webPort}`],
             ['API', `http://localhost:${answers.port}`],
             ['Took', `${((Date.now() - started) / 1000).toFixed(1)}s`],
         ];
+        if (!autoStart)
+            ui.outro(ui.style('green', 'Kosh is set up'));
         ui.card(`${terminal.emoji ? '🚀 ' : ''}Kosh is set up`, rows, enrolled || values['no-2fa'] === true ? 'green' : 'yellow');
+        if (autoStart) {
+            if (!enrolled)
+                ui.warn('Administrator rights need a second factor: run `kosh init` again to enrol the authenticator app.');
+            ui.step('rocket', 'Starting Kosh', 'Dependencies, the API, the back-office, then your browser');
+            // The installer's own connection is not needed any more: the API has its own.
+            await server?.close();
+            server = undefined;
+            await launch({
+                dir: answers.dir,
+                port: answers.port,
+                webPort: answers.webPort,
+                login: answers.admin.login,
+            }, ui);
+            return 0;
+        }
         const relative = answers.dir === resolve(io.cwd) ? '' : `cd ${positionals[0] ?? answers.dir}\n  `;
         const cmd = (c) => ui.style('cyan', c);
         ui.write(`\n  ${ui.style('bold', 'Next')}\n  ${relative}${cmd('npm install')}\n  ${cmd('npm start')}          ${ui.style('gray', `# the API on http://localhost:${answers.port}`)}\n` +
-            `  ${cmd('npm run web')}        ${ui.style('gray', '# the back-office on http://localhost:5173')}\n\n` +
+            `  ${cmd('npm run web')}        ${ui.style('gray', `# the back-office on http://localhost:${answers.webPort}`)}\n\n` +
             `  Sign in as "${answers.admin.login}"${enrolled ? ' with your password and a code from the authenticator app' : ''}.\n`);
         if (!enrolled)
             ui.warn('Administrator rights need a second factor: run `kosh init` again to enrol the authenticator app.');
         return 0;
     }
     catch (error) {
+        if (error instanceof CancelledError) {
+            ui.outro(ui.style('red', 'Setup cancelled: nothing more was done.'));
+            return 130;
+        }
         ui.write('\n');
         ui.fail(`kosh init stopped: ${error instanceof Error ? error.message : String(error)}`);
         return 1;

package/dist/cli/launch.d.ts

@@ -0,0 +1,16 @@
+import type { Ui } from './ui.js';
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+/** The package manager that ran the CLI (`npx`, `pnpm dlx`, `yarn dlx`, `bunx`), from its user agent; npm otherwise. */
+export declare function packageManager(env?: NodeJS.ProcessEnv): PackageManager;
+/** The command that opens `url` in the default browser on `platform`. */
+export declare function browserCommand(url: string, platform?: string): readonly [string, readonly string[]];
+export interface LaunchOptions {
+    readonly dir: string;
+    readonly port: number;
+    readonly webPort: number;
+    readonly login: string;
+}
+/**
+ * Installs, starts and opens the installation; returns when the user stops it (Ctrl+C) or a server stops by itself.
+ */
+export declare function launch(o: LaunchOptions, ui: Ui): Promise<void>;

package/dist/cli/launch.js

@@ -0,0 +1,138 @@
+/**
+ * After `kosh init`: the project's dependencies installed with the package manager that ran the installer, the API
+ * and the back-office started, each waited for until it answers, and the back-office opened in the default browser.
+ * Both keep running in this terminal until Ctrl+C, which stops them together. Their output is kept, and shown when
+ * one of them fails to start.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+/** The package manager that ran the CLI (`npx`, `pnpm dlx`, `yarn dlx`, `bunx`), from its user agent; npm otherwise. */
+export function packageManager(env = process.env) {
+    const agent = env['npm_config_user_agent'] ?? '';
+    for (const pm of ['pnpm', 'yarn', 'bun'])
+        if (agent.startsWith(`${pm}/`))
+            return pm;
+    return 'npm';
+}
+/** The command that opens `url` in the default browser on `platform`. */
+export function browserCommand(url, platform = process.platform) {
+    if (platform === 'win32')
+        return ['cmd', ['/c', 'start', '""', url]];
+    if (platform === 'darwin')
+        return ['open', [url]];
+    return ['xdg-open', [url]];
+}
+const windows = process.platform === 'win32';
+/** A child process running `pm args` in `cwd`, its output kept (the last 200 lines). */
+function start(pm, args, cwd) {
+    const child = spawn(pm, args, {
+        cwd,
+        env: { ...process.env, FORCE_COLOR: '0' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // npm, pnpm… are .cmd scripts on Windows; elsewhere a process group, stopped as a whole.
+        shell: windows,
+        detached: !windows,
+    });
+    const lines = [];
+    const keep = (chunk) => {
+        lines.push(...chunk
+            .toString()
+            .split(/\r?\n/)
+            .filter((l) => l.trim() !== ''));
+        lines.splice(0, Math.max(0, lines.length - 200));
+    };
+    child.stdout?.on('data', keep);
+    child.stderr?.on('data', keep);
+    const exited = new Promise((done) => child.on('close', (code) => done(code ?? 1)));
+    return { child, lines, exited };
+}
+/** Stops a started process and what it started. */
+function stop(child) {
+    if (child.pid === undefined || child.exitCode !== null)
+        return;
+    try {
+        if (windows)
+            spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+        else
+            process.kill(-child.pid, 'SIGTERM');
+    }
+    catch {
+        // already gone
+    }
+}
+/** Resolves when `url` answers (any HTTP status below 500); rejects when `exited` settles first or on timeout. */
+async function answers(url, exited, seconds) {
+    let gone = null;
+    void exited.then((code) => {
+        gone = code;
+    });
+    for (let i = 0; i < seconds * 2; i++) {
+        if (gone !== null)
+            throw new Error(`it stopped (exit code ${gone})`);
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
+            if (res.status < 500)
+                return;
+        }
+        catch {
+            // not yet
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    throw new Error(`no answer at ${url} within ${seconds}s`);
+}
+/**
+ * Installs, starts and opens the installation; returns when the user stops it (Ctrl+C) or a server stops by itself.
+ */
+export async function launch(o, ui) {
+    const pm = packageManager();
+    await ui.task(`Installing the dependencies (${pm} install)`, async (task) => {
+        task.update('the first run downloads them');
+        const run = start(pm, ['install'], o.dir);
+        const code = await run.exited;
+        if (code !== 0)
+            throw new Error(`${pm} install failed:\n${run.lines.slice(-15).join('\n')}`);
+    });
+    const api = start(pm, ['run', 'start'], o.dir);
+    const web = start(pm, ['run', 'web'], o.dir);
+    const stopAll = () => {
+        stop(api.child);
+        stop(web.child);
+    };
+    process.once('exit', stopAll);
+    const failed = (name, run) => (error) => {
+        stopAll();
+        const tail = run.lines.slice(-15).join('\n');
+        throw new Error(`The ${name} did not start: ${error instanceof Error ? error.message : String(error)}${tail === '' ? '' : `\n${tail}`}`);
+    };
+    const apiUrl = `http://localhost:${o.port}`;
+    const webUrl = `http://localhost:${o.webPort}`;
+    await ui
+        .task(`Starting the API on ${apiUrl}`, () => answers(`${apiUrl}/health/ready`, api.exited, 90))
+        .catch(failed('API', api));
+    await ui
+        .task(`Starting the back-office on ${webUrl}`, () => answers(webUrl, web.exited, 90))
+        .catch(failed('back-office', web));
+    const [command, args] = browserCommand(webUrl);
+    const opened = spawn(command, args, { stdio: 'ignore', detached: true, shell: false });
+    opened.on('error', () => ui.info(`Open ${webUrl} in your browser.`));
+    opened.unref();
+    ui.ok(`Opened ${ui.style('cyan', webUrl)} in your browser · sign in as "${o.login}"`);
+    ui.outro(`${ui.style('green', 'Kosh is running')}  ${ui.style('gray', `back-office ${webUrl} · API ${apiUrl} · Ctrl+C stops both`)}`);
+    // Until Ctrl+C, or until one of them stops by itself (its last lines are shown).
+    const which = await Promise.race([
+        new Promise((done) => {
+            process.once('SIGINT', () => done('stopped'));
+            process.once('SIGTERM', () => done('stopped'));
+        }),
+        api.exited.then(() => 'api'),
+        web.exited.then(() => 'web'),
+    ]);
+    stopAll();
+    if (which === 'stopped') {
+        ui.write(`\n  ${ui.style('gray', `Stopped. Start again with: ${pm} start  and  ${pm} run web`)}\n`);
+        return;
+    }
+    const run = which === 'api' ? api : web;
+    ui.fail(`The ${which === 'api' ? 'API' : 'back-office'} stopped:`);
+    ui.write(`${run.lines.slice(-15).join('\n')}\n`);
+}

package/dist/cli/prompt.d.ts

@@ -7,11 +7,46 @@ export interface Question {
     /** An error message for an invalid answer (asked again), or `null`. */
     readonly validate?: (value: string) => string | null;
 }
+/** One option of a choice: what is answered, what is shown, an optional hint beside it. */
+export interface Choice {
+    readonly value: string;
+    readonly label: string;
+    readonly hint?: string;
+}
+export interface SelectQuestion {
+    readonly message: string;
+    readonly choices: readonly Choice[];
+    /** The value chosen when Enter is pressed at once. */
+    readonly default?: string;
+}
+export interface MultiQuestion {
+    readonly message: string;
+    readonly choices: readonly Choice[];
+    /** The values ticked to begin with. */
+    readonly defaults?: readonly string[];
+    /** At least one. */
+    readonly required?: boolean;
+}
 export interface Prompter {
     ask(question: Question): Promise<string>;
     confirm(message: string, fallback: boolean): Promise<boolean>;
+    /** One of several (a list chosen with the keyboard); without it, {@link choose} asks a question instead. */
+    select?(question: SelectQuestion): Promise<string>;
+    /** Several of several; without it, {@link chooseMany} asks for a comma-separated list. */
+    multiselect?(question: MultiQuestion): Promise<string[]>;
     close(): void;
 }
+/**
+ * One of `choices`: the prompter's list when it has one, otherwise the question `fallback` (pipes, scripts, tests),
+ * answered with an option's number, value or label.
+ */
+export declare function choose(prompter: Prompter, q: SelectQuestion & {
+    readonly fallback: string;
+}): Promise<string>;
+/** Several of `choices`: the prompter's list, or a comma-separated answer to `fallback`. */
+export declare function chooseMany(prompter: Prompter, q: MultiQuestion & {
+    readonly fallback: string;
+}): Promise<string[]>;
 /** Thrown when the input ends before every question is answered (piped answers ran out, Ctrl+D). */
 export declare class InputEndedError extends Error {
     constructor(question: string);