@gjsify/create-app 0.40.0 → 0.42.0

package/dist-templates/web-server-express/package.json

@@ -14,13 +14,13 @@
         "start:node": "gjsify run dist/index.node.mjs --runtime node",
         "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
         "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
-        "dev": "gjsify run build:gjs && gjsify run start"
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/node-globals": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
-        "@gjsify/runtime": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/node-globals": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
+        "@gjsify/runtime": "^0.42.0",
         "@types/express": "^5.0.6",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"

package/dist-templates/web-server-hono/README.md

@@ -17,7 +17,7 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev            # build for GJS + run
+npm run dev            # watch, rebuild + relaunch on GJS
 npm run build          # bundle for every runtime (dist/index.gjs.js + dist/index.node.mjs)
 npm start              # run on GJS
 npm run start:node     # run on Node.js

package/dist-templates/web-server-hono/package.json

@@ -14,13 +14,13 @@
         "start:node": "gjsify run dist/index.node.mjs --runtime node",
         "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
         "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
-        "dev": "gjsify run build:gjs && gjsify run start"
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/node-globals": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
-        "@gjsify/runtime": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/node-globals": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
+        "@gjsify/runtime": "^0.42.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },

package/lib/create.d.ts

@@ -1,16 +1,9 @@
+import { type TemplateInfo } from './discover-templates.js';
+import { type PackageManager } from './runtimes.js';
 export { discoverTemplates, findTemplate } from './discover-templates.js';
 export type { TemplateInfo } from './discover-templates.js';
-/**
- * Package managers a scaffolded project can be installed with. All four work:
- * the templates declare every dependency they need explicitly — including
- * `@gjsify/rolldown-native`, which npm/yarn/pnpm would otherwise skip as an
- * optional peer of `@gjsify/cli`.
- *
- * `gjsify` is gjsify's own installer and the only one of the four that works on
- * a host with no Node.js at all.
- */
-export declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm", "gjsify"];
-export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+export { PACKAGE_MANAGERS, INSTALL_ARGV, RUNTIME_PACKAGE_MANAGERS, RUNTIME_DESCRIPTIONS, packageManagersForRuntime, isKnownRuntime, hostRuntime, defaultRuntimeFor, runScriptCommand, startScriptFor, type PackageManager, } from './runtimes.js';
+export { selectRuntime, selectPackageManager, type Selection } from './select.js';
 export interface CreateProjectOptions {
     projectName: string;
     /** Template short name, e.g. "gtk-minimal". If omitted, the caller is responsible for providing one via prompt. */
@@ -21,7 +14,34 @@ export interface CreateProjectOptions {
     install?: boolean;
     /** Which package manager to install with, and to name in the printed next steps. */
     packageManager?: PackageManager;
+    /**
+     * Which of the template's declared runtimes the user intends to run on.
+     *
+     * It changes no scaffolded byte — a template ships every runtime it declares
+     * — but it decides which package manager is legal and which of the `start:*`
+     * scripts the next steps name. Omitted, it resolves the same way the
+     * non-interactive path does: the host runtime when the template supports it.
+     */
+    runtime?: string;
 }
+/**
+ * The bus name a project scaffolded as `projectName` announces. A D-Bus element
+ * holds only `[A-Za-z0-9_-]` and may not begin with a digit where an npm name may
+ * hold `.` and begin with one, and `Gtk.Application` refuses to construct with an
+ * invalid id — so `npm create @gjsify/app 2048` would fail at startup, the one
+ * place only a launched app can see.
+ */
+export declare function applicationIdFor(projectName: string): string;
 /** npm package names: lowercase, digits, -, _, .; no leading . or _. */
 export declare function sanitizeProjectName(raw: string): string;
 export declare function createProject(options: CreateProjectOptions): Promise<void>;
+/**
+ * The runtimes a template can actually be scaffolded for: what it DECLARES in
+ * `gjsify.example.runtimes`, minus any name this scaffolder has no installer
+ * mapping for.
+ *
+ * Filtering rather than trusting the declaration wholesale keeps an older
+ * scaffolder usable against a newer template: it offers the runtimes it can
+ * serve instead of listing one in the picker and then failing on the install.
+ */
+export declare function supportedRuntimes(template: TemplateInfo): string[];

package/lib/create.js

@@ -2,26 +2,36 @@ import { spawnSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, cpSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { discoverTemplates, findTemplate } from './discover-templates.js';
+import { INSTALL_ARGV, defaultRuntimeFor, hostRuntime, packageManagersForRuntime, runScriptCommand, startScriptFor, } from './runtimes.js';
 export { discoverTemplates, findTemplate } from './discover-templates.js';
+export { PACKAGE_MANAGERS, INSTALL_ARGV, RUNTIME_PACKAGE_MANAGERS, RUNTIME_DESCRIPTIONS, packageManagersForRuntime, isKnownRuntime, hostRuntime, defaultRuntimeFor, runScriptCommand, startScriptFor, } from './runtimes.js';
+// Re-exported through the package's `.` entry (which is this file, not
+// `index.ts`) so `gjsify create` can reach the same decisions the standalone bin
+// makes instead of re-deriving them — a second derivation is a second answer.
+export { selectRuntime, selectPackageManager } from './select.js';
+/** Sentinel replaced by the user's project name in every text file under the template. */
+const PROJECT_NAME_SENTINEL = 'new-gjsify-app';
 /**
- * Package managers a scaffolded project can be installed with. All four work:
- * the templates declare every dependency they need explicitly — including
- * `@gjsify/rolldown-native`, which npm/yarn/pnpm would otherwise skip as an
- * optional peer of `@gjsify/cli`.
+ * Sentinel replaced by the scaffolded project's own application id.
  *
- * `gjsify` is gjsify's own installer and the only one of the four that works on
- * a host with no Node.js at all.
+ * A GApplication id is a session-bus NAME and the first app to claim it owns it.
+ * Every scaffolded project shipped this same literal, so starting a second one
+ * while the first ran made GTK treat it as a REMOTE INSTANCE: it forwarded
+ * `activate` to the other project's window and exited 0, with no window and no
+ * error of its own (measured on `gtk-minimal` + `adw-canvas2d`).
  */
-export const PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'gjsify'];
-/** The `install` argv for each package manager. */
-const INSTALL_ARGV = {
-    npm: ['install', '--no-audit', '--no-fund'],
-    yarn: ['install'],
-    pnpm: ['install'],
-    gjsify: ['install'],
-};
-/** Sentinel replaced by the user's project name in every text file under the template. */
-const PROJECT_NAME_SENTINEL = 'new-gjsify-app';
+const APPLICATION_ID_SENTINEL = 'org.gjsify.example';
+/**
+ * The bus name a project scaffolded as `projectName` announces. A D-Bus element
+ * holds only `[A-Za-z0-9_-]` and may not begin with a digit where an npm name may
+ * hold `.` and begin with one, and `Gtk.Application` refuses to construct with an
+ * invalid id — so `npm create @gjsify/app 2048` would fail at startup, the one
+ * place only a launched app can see.
+ */
+export function applicationIdFor(projectName) {
+    const element = projectName.replace(/[^A-Za-z0-9_-]/g, '-');
+    return `org.gjsify.${/^[0-9]/.test(element) ? `app-${element}` : element}`;
+}
 /** File extensions we treat as text and scan for the sentinel. */
 const TEXT_FILE_EXT = new Set([
     '.json',
@@ -60,7 +70,7 @@ function isDirEmpty(path) {
 }
 export async function createProject(options) {
     const projectName = sanitizeProjectName(options.projectName);
-    const { template, force = false, install = false, packageManager = 'npm' } = options;
+    const { template, force = false, install = false } = options;
     const info = findTemplate(template);
     if (!info) {
         const available = discoverTemplates()
@@ -68,6 +78,25 @@ export async function createProject(options) {
             .join(', ');
         throw new Error(`Unknown template "${template}". Available templates: ${available || '(none — run "yarn build" first)'}`);
     }
+    // Resolve the runtime BEFORE the manager: which managers are legal is a
+    // function of the runtime, so a caller passing neither must not land on npm
+    // for a template that only runs on gjs. A template that declares NOTHING is
+    // unconstrained — the reading `@gjsify/cli`'s `readDeclaredRuntimes` gives a
+    // null declaration — so it falls through to the host rather than to an
+    // arbitrary first entry.
+    const offered = supportedRuntimes(info);
+    const runtime = options.runtime ?? defaultRuntimeFor(offered, options.packageManager) ?? hostRuntime();
+    const managers = packageManagersForRuntime(runtime);
+    if (!managers) {
+        throw new Error(`Template "${info.name}" was asked for runtime "${runtime}", which this version of ` +
+            '@gjsify/create-app has no installer mapping for. Upgrade it, or pick one of: ' +
+            `${offered.join(', ') || '(none)'}.`);
+    }
+    const packageManager = options.packageManager ?? managers[0];
+    if (!managers.includes(packageManager)) {
+        throw new Error(`"${packageManager}" cannot install a project you intend to run on ${runtime}. ` +
+            `Package managers for ${runtime}: ${managers.join(', ')}.`);
+    }
     const targetDir = resolve(process.cwd(), projectName);
     if (existsSync(targetDir) && !isDirEmpty(targetDir) && !force) {
         console.error(`Error: Directory "${projectName}" exists and is not empty. Use --force to scaffold into it anyway.`);
@@ -79,9 +108,9 @@ export async function createProject(options) {
     console.log(`Creating new Gjsify project in ${targetDir} (template: ${info.name})...`);
     mkdirSync(targetDir, { recursive: true });
     cpSync(info.path, targetDir, { recursive: true });
-    substituteProjectName(targetDir, projectName);
+    substituteTemplateSentinels(targetDir, projectName);
     if (install) {
-        const argv = INSTALL_ARGV[packageManager];
+        const argv = [...INSTALL_ARGV[packageManager]];
         console.log(`Running ${packageManager} ${argv[0]}...`);
         // `shell: true` is what makes this work on Windows, where `npm` is
         // `npm.cmd`: `CreateProcess` appends only `.exe` when it searches PATH
@@ -91,7 +120,9 @@ export async function createProject(options) {
         // my-app` therefore scaffolded a project, never installed anything, and
         // blamed npm for it. `shell: true` is the exemption the invariant in
         // `@gjsify/cli`'s `utils/spawn.ts` sanctions for exactly this case. It
-        // applies to all four managers, which all ship as `.cmd` shims there.
+        // applies to every manager here: npm/yarn/pnpm/gjsify ship as `.cmd`
+        // shims on Windows, and bun/deno as `.exe`, which the bare-name search
+        // finds — but the shell path is correct for both and costs nothing.
         const result = spawnSync(packageManager, argv, {
             cwd: targetDir,
             stdio: 'inherit',
@@ -107,13 +138,17 @@ export async function createProject(options) {
             console.warn(`${packageManager} install failed; re-run it manually in the project directory.`);
         }
     }
-    printNextSteps(projectName, info, install, packageManager);
+    printNextSteps(projectName, info, install, packageManager, runtime);
 }
 /**
- * Walk the scaffolded tree and replace the sentinel in every text file.
+ * Walk the scaffolded tree and replace every template sentinel in every text file.
  * Skips node_modules / dist / lib and non-text files by extension.
  */
-function substituteProjectName(rootDir, projectName) {
+function substituteTemplateSentinels(rootDir, projectName) {
+    const sentinels = [
+        [PROJECT_NAME_SENTINEL, projectName],
+        [APPLICATION_ID_SENTINEL, applicationIdFor(projectName)],
+    ];
     const skipDirs = new Set(['node_modules', 'dist', 'lib']);
     const stack = [rootDir];
     while (stack.length > 0) {
@@ -132,49 +167,79 @@ function substituteProjectName(rootDir, projectName) {
             if (!TEXT_FILE_EXT.has(ext))
                 continue;
             const content = readFileSync(full, 'utf-8');
-            if (!content.includes(PROJECT_NAME_SENTINEL))
-                continue;
-            writeFileSync(full, content.replaceAll(PROJECT_NAME_SENTINEL, projectName));
+            let replaced = content;
+            for (const [sentinel, value] of sentinels)
+                replaced = replaced.replaceAll(sentinel, value);
+            if (replaced !== content)
+                writeFileSync(full, replaced);
         }
     }
 }
-function printNextSteps(projectName, template, installed, packageManager) {
-    // `npm run <script>` / `yarn <script>` / `pnpm <script>` / `gjsify run
-    // <script>` — the same script, four spellings. Printing the one that
-    // matches the manager the user actually chose is the whole point of
-    // threading it this far.
-    const run = packageManager === 'npm' ? 'npm run' : packageManager === 'gjsify' ? 'gjsify run' : packageManager;
+function printNextSteps(projectName, template, installed, packageManager, runtime) {
+    const run = runScriptCommand(packageManager);
+    const scripts = templateScripts(template);
+    const start = startScriptFor(runtime);
     console.log('');
-    console.log(`Project created from template "${template.name}".`);
+    console.log(`Project created from template "${template.name}", set up for ${runtime}.`);
     console.log('');
     console.log('Next steps:');
     console.log(`  cd ${projectName}`);
     if (!installed)
         console.log(`  ${packageManager} install`);
-    console.log(`  ${run} dev`);
-    console.log('');
-    // The runtimes the template DECLARES, not a fixed list: a GJS-only template
-    // must not advertise `start:node`, and a portable one must not hide it.
-    const runtimes = declaredRuntimes(template);
-    if (runtimes.length > 1) {
-        console.log(`Runs on ${runtimes.join(', ')}:`);
+    // `dev` is the gjs one-liner (build the gjs bundle, then launch it); every
+    // other runtime consumes the `--app node` bundle, which `dev` does not
+    // produce. Printing `dev` for a `--runtime deno` user sent them to a script
+    // that rebuilds the wrong target and starts the wrong file.
+    if (runtime === 'gjs' && scripts['dev']) {
+        console.log(`  ${run} dev`);
+    }
+    else {
         console.log(`  ${run} build`);
-        for (const runtime of runtimes) {
-            console.log(`  ${run} ${runtime === 'gjs' ? 'start' : `start:${runtime}`}`);
-        }
+        console.log(`  ${run} ${start}`);
+    }
+    console.log('');
+    // The OTHER runtimes the template DECLARES, not a fixed list: a GJS-only
+    // template must not advertise `start:node`, and a portable one must not hide
+    // it. Only those whose launch script the template actually ships are listed —
+    // a declaration with no script behind it is not a runnable offer.
+    const alternatives = supportedRuntimes(template).filter((rt) => rt !== runtime && scripts[startScriptFor(rt)]);
+    if (alternatives.length > 0) {
+        console.log(`Also runs on ${alternatives.join(', ')}:`);
+        for (const rt of alternatives)
+            console.log(`  ${run} ${startScriptFor(rt)}`);
         console.log('');
     }
 }
-/** `gjsify.example.runtimes` from the template's manifest; `[]` when unstated. */
-function declaredRuntimes(template) {
+/** The template manifest, or `{}` when it cannot be read. */
+function templateManifest(template) {
     try {
-        const pkg = JSON.parse(readFileSync(join(template.path, 'package.json'), 'utf-8'));
-        const runtimes = pkg.gjsify?.example?.runtimes;
-        return Array.isArray(runtimes) ? runtimes.filter((r) => typeof r === 'string') : [];
+        return JSON.parse(readFileSync(join(template.path, 'package.json'), 'utf-8'));
     }
     catch {
         // A template with no readable manifest cannot be scaffolded at all —
         // `createProject` already failed by here. Nothing to advertise.
-        return [];
+        return {};
     }
 }
+/** The template's package scripts, keyed by name. */
+function templateScripts(template) {
+    const scripts = templateManifest(template).scripts;
+    if (!scripts)
+        return {};
+    return Object.fromEntries(Object.entries(scripts).filter((entry) => typeof entry[1] === 'string'));
+}
+/**
+ * The runtimes a template can actually be scaffolded for: what it DECLARES in
+ * `gjsify.example.runtimes`, minus any name this scaffolder has no installer
+ * mapping for.
+ *
+ * Filtering rather than trusting the declaration wholesale keeps an older
+ * scaffolder usable against a newer template: it offers the runtimes it can
+ * serve instead of listing one in the picker and then failing on the install.
+ */
+export function supportedRuntimes(template) {
+    const declared = templateManifest(template).gjsify?.example?.runtimes;
+    if (!Array.isArray(declared))
+        return [];
+    return declared.filter((rt) => typeof rt === 'string' && packageManagersForRuntime(rt) !== undefined);
+}

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-export { createProject, sanitizeProjectName, PACKAGE_MANAGERS, type CreateProjectOptions, type PackageManager, } from './create.js';
+export { createProject, sanitizeProjectName, applicationIdFor, supportedRuntimes, PACKAGE_MANAGERS, RUNTIME_PACKAGE_MANAGERS, packageManagersForRuntime, isKnownRuntime, hostRuntime, defaultRuntimeFor, runScriptCommand, startScriptFor, type CreateProjectOptions, type PackageManager, } from './create.js';
+export { selectRuntime, selectPackageManager, type Selection } from './select.js';
 export { discoverTemplates, findTemplate, type TemplateInfo } from './discover-templates.js';

package/lib/index.js

@@ -1,11 +1,21 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { createProject, PACKAGE_MANAGERS } from './create.js';
+import { createProject, supportedRuntimes } from './create.js';
 import { discoverTemplates } from './discover-templates.js';
-import { promptTemplate } from './prompt-template.js';
+import { isCancelled, promptSetup, promptTemplate } from './prompt-template.js';
+import { PACKAGE_MANAGERS } from './runtimes.js';
 const templates = discoverTemplates();
 const templateChoices = templates.map((t) => t.name);
+/**
+ * The `--runtime` values this build can actually serve: every runtime any shipped
+ * template declares, in first-declaration order.
+ *
+ * DERIVED, never a second copy of the CLI's `EXAMPLE_RUNTIMES`. Accepting
+ * `--runtime deno` is a claim that some template runs there, and the templates
+ * are the only thing that can make that claim.
+ */
+const runtimeChoices = [...new Set(templates.flatMap((t) => supportedRuntimes(t)))];
 void yargs(hideBin(process.argv))
     .scriptName('@gjsify/create-app')
     .usage('$0 [project-name]', 'Create a new Gjsify project', (yargs) => {
@@ -20,6 +30,12 @@ void yargs(hideBin(process.argv))
         describe: 'Template to scaffold from',
         type: 'string',
         choices: templateChoices.length > 0 ? templateChoices : undefined,
+    })
+        .option('runtime', {
+        alias: 'r',
+        describe: 'Runtime to set the project up for. Decides which package managers are offered and which start script the next steps name.',
+        type: 'string',
+        choices: runtimeChoices.length > 0 ? runtimeChoices : undefined,
     })
         .option('force', {
         alias: 'f',
@@ -34,33 +50,55 @@ void yargs(hideBin(process.argv))
     })
         .option('package-manager', {
         alias: 'p',
-        describe: 'Package manager to install with, and to name in the printed next steps. `gjsify` is the only one that works on a host with no Node.js.',
+        describe: 'Package manager to install with, and to name in the printed next steps. Must be one the chosen runtime can install for. `gjsify` is the only one that works on a host with no Node.js.',
         type: 'string',
         choices: PACKAGE_MANAGERS,
-        default: 'npm',
     });
 }, async (argv) => {
     const projectName = argv['project-name'];
+    const interactive = Boolean(process.stdin.isTTY);
     let template = argv['template'];
     if (!template) {
-        if (!process.stdin.isTTY) {
+        if (!interactive) {
             const list = templateChoices.join(', ');
             console.error(`Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`);
             // `return` — the deferred GJS exit otherwise fell through
             // into the interactive template prompt on a non-TTY.
             return process.exit(1);
         }
-        const picked = await promptTemplate(templates);
+        // Ctrl+C here is an abort, not a crash. Without the guard the
+        // rejection escapes into yargs, which answers it with a stack
+        // trace and the whole `--help`.
+        const picked = await promptTemplate(templates).catch((error) => {
+            if (!isCancelled(error))
+                throw error;
+            console.error('Cancelled.');
+            return undefined;
+        });
+        if (picked === undefined)
+            return process.exit(1);
         template = picked.name;
     }
+    const info = templates.find((t) => t.name === template);
+    const setup = await promptSetup({
+        offered: info ? supportedRuntimes(info) : [],
+        runtime: argv['runtime'],
+        packageManager: argv['package-manager'],
+        install: argv['install'],
+        interactive,
+    });
+    if (setup === undefined)
+        return process.exit(1);
     await createProject({
         projectName,
         template,
+        runtime: setup.runtime,
         force: argv['force'],
         install: argv['install'],
-        packageManager: argv['package-manager'],
+        packageManager: setup.packageManager,
     });
 })
     .help().argv;
-export { createProject, sanitizeProjectName, PACKAGE_MANAGERS, } from './create.js';
+export { createProject, sanitizeProjectName, applicationIdFor, supportedRuntimes, PACKAGE_MANAGERS, RUNTIME_PACKAGE_MANAGERS, packageManagersForRuntime, isKnownRuntime, hostRuntime, defaultRuntimeFor, runScriptCommand, startScriptFor, } from './create.js';
+export { selectRuntime, selectPackageManager } from './select.js';
 export { discoverTemplates, findTemplate } from './discover-templates.js';

package/lib/prompt-template.d.ts

@@ -1,6 +1,60 @@
 import type { TemplateInfo } from './discover-templates.js';
+import { type PackageManager } from './runtimes.js';
+/** `true` when `error` is a picker the user aborted with Ctrl+C. */
+export declare function isCancelled(error: unknown): boolean;
+/** One selectable row: the value returned, plus how it is drawn. */
+export interface Choice<T> {
+    value: T;
+    label: string;
+    /** Dimmed text after the label. Empty string draws nothing. */
+    description: string;
+}
 /**
- * Interactive template picker. Returns the selected TemplateInfo.
+ * Interactive arrow-key picker. Returns the selected value.
  * Throws if stdin is not a TTY — caller should check process.stdin.isTTY first.
+ *
+ * `initial` is the index the cursor starts on, so a prompt can open on the
+ * answer the tool would have picked anyway (the host runtime, say) and Enter
+ * alone is a valid response.
  */
+export declare function promptChoice<T>(title: string, choices: readonly Choice<T>[], initial?: number): Promise<T>;
+/** Interactive template picker. Returns the selected TemplateInfo. */
 export declare function promptTemplate(templates: TemplateInfo[]): Promise<TemplateInfo>;
+/**
+ * Interactive runtime picker, offering only what the chosen template declares.
+ *
+ * `initial` is the runtime `defaultRuntimeFor()` resolved to; it is passed in
+ * rather than recomputed so the prompt opens on exactly the value the non-TTY
+ * path would have used.
+ */
+export declare function promptRuntime(runtimes: readonly string[], initial: string): Promise<string>;
+/** Interactive package-manager picker for the runtime already chosen. */
+export declare function promptPackageManager(managers: readonly PackageManager[], initial: PackageManager): Promise<PackageManager>;
+/** The two answers `createProject` needs beyond the template. */
+export interface Setup {
+    runtime: string;
+    packageManager: PackageManager;
+}
+export interface SetupQuestion {
+    /** The runtimes the chosen template declares AND this scaffolder can serve. */
+    offered: readonly string[];
+    /** `--runtime`, when given. */
+    runtime?: string;
+    /** `--package-manager`, when given. */
+    packageManager?: PackageManager;
+    /** Whether `--install` is set — i.e. whether the manager choice runs something. */
+    install: boolean;
+    /** Whether stdin is a TTY, i.e. whether a prompt is possible at all. */
+    interactive: boolean;
+}
+/**
+ * Settle runtime and package manager: flags, then prompts, then announced
+ * defaults — the runtime first, because it decides which managers are legal.
+ *
+ * `undefined` means "exit non-zero, the reason is printed". Lives here rather
+ * than in either bin because BOTH surfaces ask these two questions — `npm create
+ * @gjsify/app` and `gjsify create`. A copy in one of them is a second answer to
+ * the same question, which is exactly what let `gjsify create --install` reach
+ * for npm on its own while the standalone bin refused to guess.
+ */
+export declare function promptSetup(question: SetupQuestion): Promise<Setup | undefined>;