@gjsify/create-app 0.39.0 → 0.41.0

package/lib/runtimes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Package managers a scaffolded project can be installed with. npm/yarn/pnpm/
+ * gjsify all work on a Node host — templates declare every dependency explicitly,
+ * `@gjsify/rolldown-native` included, which the three would otherwise skip as an
+ * optional peer of `@gjsify/cli`. `gjsify` is the only one of the six that works
+ * on a host with no Node.js.
+ */
+export declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm", "gjsify", "bun", "deno"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+/**
+ * The `install` argv per manager, each read off the tool's own `--help` rather
+ * than assumed: `bun install` and a BARE `deno install` mean "install what
+ * package.json lists" — `deno install --global` is the unrelated
+ * install-a-script mode.
+ */
+export declare const INSTALL_ARGV: Record<PackageManager, readonly string[]>;
+/** The command prefix that runs a package script under `manager`. */
+export declare function runScriptCommand(manager: PackageManager): string;
+/**
+ * Which managers can install a project the user intends to RUN on `<runtime>` —
+ * not taste, but the module layout each runtime resolves against. `gjs` is the
+ * Node-free column, where npm/yarn/pnpm are not discouraged but ABSENT; bun writes
+ * its own layout; `deno install` populates the `node_modules` that
+ * `--node-modules-dir=manual` (how `gjsify run --runtime deno` launches) reads
+ * without re-resolving. The KEYS double as "runtimes this scaffolder has an
+ * installer for", and the spec asserts they equal the CLI's `EXAMPLE_RUNTIMES`, so
+ * a runtime added upstream fails loudly instead of vanishing from every prompt.
+ */
+export declare const RUNTIME_PACKAGE_MANAGERS: Readonly<Record<string, readonly PackageManager[]>>;
+/** One-line label for each runtime, shown beside it in the picker. */
+export declare const RUNTIME_DESCRIPTIONS: Readonly<Record<string, string>>;
+/**
+ * The managers that install for `runtime`, `undefined` when unmapped — not a
+ * permissive fallback: unmapped means the template is newer than the scaffolder,
+ * and guessing an installer buries the cause.
+ */
+export declare function packageManagersForRuntime(runtime: string): readonly PackageManager[] | undefined;
+/** `true` when this scaffolder knows how to install for `runtime`. */
+export declare function isKnownRuntime(runtime: string): boolean;
+/**
+ * The JS runtime this scaffolder is itself executing on. A LOCAL implementation,
+ * kept for the two measured reasons in the file header and held to the canonical
+ * one by `runtimes.spec.ts`, which runs on all four runtimes and compares against
+ * `@gjsify/rolldown-plugin-gjsify/runtime`.
+ *
+ * Probe order is load-bearing: **Bun and Deno first**, because both fake
+ * `process.versions.node` for npm compatibility and GJS's `@gjsify/process` shim
+ * does too, making that read a false Node positive on three of the four hosts.
+ */
+export declare function hostRuntime(): string;
+/**
+ * Which runtime to start on: the host when the template supports it — "whatever
+ * you are already running" needs no second toolchain — else the template's own
+ * first declaration, which is the canonical one.
+ *
+ * `manager` OVERRIDES that, because a pinned manager already names a runtime.
+ * Without it, `create-app x -t cli -p bun` resolved to the host (`node`), found
+ * bun illegal there and refused a combination the user had spelled out. "First
+ * declared runtime this manager installs for" needs no per-manager table: bun and
+ * deno serve one each, npm/yarn/pnpm only node, and `gjsify` — legal on gjs and
+ * node — lands on gjs, the column it was written for.
+ *
+ * `undefined` for an empty list, or when nothing declared installs with
+ * `manager`; the caller decides whether that is an error.
+ */
+export declare function defaultRuntimeFor(runtimes: readonly string[], manager?: PackageManager): string | undefined;
+/**
+ * The script that launches the project on `runtime`. Template convention: `start`
+ * is the gjs entry (what `gjsify.main` points at), every other runtime a suffixed
+ * sibling — `start:node`, `start:bun`, `start:deno`.
+ */
+export declare function startScriptFor(runtime: string): string;

package/lib/runtimes.js

@@ -0,0 +1,141 @@
+// Runtime ↔ package-manager model for `gjsify create` / `npm create @gjsify/app`.
+// gjsify targets four runtimes and each has its own installer, so assuming `npm`
+// printed next steps a `deno` user cannot run and, with `--install`, ran the wrong
+// installer for the layout their runtime resolves against.
+//
+// WHY THE RUNTIME LIST IS NOT IMPORTED FROM `@gjsify/cli`, which owns
+// `EXAMPLE_RUNTIMES`: nothing here twins it. The runtimes OFFERED come from the
+// template's own manifest, and the table below is a different fact (which
+// installer serves which runtime) whose key set `runtimes.spec.ts` asserts
+// against `EXAMPLE_RUNTIMES`. A runtime import was measured and rejected twice —
+// `@gjsify/cli` as a `dependency` closes the loop cli → create-app → cli, and
+// `@gjsify/workspace`'s `topologicalSort` throws on a prod cycle ("dependency
+// cycle detected involving @gjsify/cli, @gjsify/create-app"), taking `build:infra`
+// with it; while `@gjsify/rolldown-plugin-gjsify/runtime`, the cycle-free leaf
+// owning `hostRuntime()`, drags typescript + deepkit + sass + lightningcss into a
+// scaffolder whose whole runtime dependency set is `yargs`. Both are
+// devDependencies, and the spec cross-checks against them.
+/**
+ * Package managers a scaffolded project can be installed with. npm/yarn/pnpm/
+ * gjsify all work on a Node host — templates declare every dependency explicitly,
+ * `@gjsify/rolldown-native` included, which the three would otherwise skip as an
+ * optional peer of `@gjsify/cli`. `gjsify` is the only one of the six that works
+ * on a host with no Node.js.
+ */
+export const PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'gjsify', 'bun', 'deno'];
+/**
+ * The `install` argv per manager, each read off the tool's own `--help` rather
+ * than assumed: `bun install` and a BARE `deno install` mean "install what
+ * package.json lists" — `deno install --global` is the unrelated
+ * install-a-script mode.
+ */
+export const INSTALL_ARGV = {
+    npm: ['install', '--no-audit', '--no-fund'],
+    yarn: ['install'],
+    pnpm: ['install'],
+    gjsify: ['install'],
+    bun: ['install'],
+    deno: ['install'],
+};
+/**
+ * How each manager spells "run the package script `<name>`" — six managers, four
+ * spellings. Printing the one the user's manager accepts is why the choice is
+ * threaded this far: `npm run dev` is a dead end for someone who installed with
+ * deno.
+ */
+const RUN_SCRIPT_PREFIX = {
+    npm: 'npm run',
+    yarn: 'yarn',
+    pnpm: 'pnpm',
+    gjsify: 'gjsify run',
+    bun: 'bun run',
+    deno: 'deno task',
+};
+/** The command prefix that runs a package script under `manager`. */
+export function runScriptCommand(manager) {
+    return RUN_SCRIPT_PREFIX[manager];
+}
+/**
+ * Which managers can install a project the user intends to RUN on `<runtime>` —
+ * not taste, but the module layout each runtime resolves against. `gjs` is the
+ * Node-free column, where npm/yarn/pnpm are not discouraged but ABSENT; bun writes
+ * its own layout; `deno install` populates the `node_modules` that
+ * `--node-modules-dir=manual` (how `gjsify run --runtime deno` launches) reads
+ * without re-resolving. The KEYS double as "runtimes this scaffolder has an
+ * installer for", and the spec asserts they equal the CLI's `EXAMPLE_RUNTIMES`, so
+ * a runtime added upstream fails loudly instead of vanishing from every prompt.
+ */
+export const RUNTIME_PACKAGE_MANAGERS = {
+    gjs: ['gjsify'],
+    node: ['npm', 'yarn', 'pnpm', 'gjsify'],
+    bun: ['bun'],
+    deno: ['deno'],
+};
+/** One-line label for each runtime, shown beside it in the picker. */
+export const RUNTIME_DESCRIPTIONS = {
+    gjs: 'GNOME JavaScript — no Node.js needed at runtime.',
+    node: 'Node.js — gi:// via the @gjsify/node-gi bridge.',
+    bun: 'Bun — runs the same --app node bundle.',
+    deno: 'Deno — runs the same --app node bundle.',
+};
+/**
+ * The managers that install for `runtime`, `undefined` when unmapped — not a
+ * permissive fallback: unmapped means the template is newer than the scaffolder,
+ * and guessing an installer buries the cause.
+ */
+export function packageManagersForRuntime(runtime) {
+    return RUNTIME_PACKAGE_MANAGERS[runtime];
+}
+/** `true` when this scaffolder knows how to install for `runtime`. */
+export function isKnownRuntime(runtime) {
+    return packageManagersForRuntime(runtime) !== undefined;
+}
+/**
+ * The JS runtime this scaffolder is itself executing on. A LOCAL implementation,
+ * kept for the two measured reasons in the file header and held to the canonical
+ * one by `runtimes.spec.ts`, which runs on all four runtimes and compares against
+ * `@gjsify/rolldown-plugin-gjsify/runtime`.
+ *
+ * Probe order is load-bearing: **Bun and Deno first**, because both fake
+ * `process.versions.node` for npm compatibility and GJS's `@gjsify/process` shim
+ * does too, making that read a false Node positive on three of the four hosts.
+ */
+export function hostRuntime() {
+    const g = globalThis;
+    if (typeof g.Bun !== 'undefined')
+        return 'bun';
+    if (typeof g.Deno !== 'undefined')
+        return 'deno';
+    if (typeof g.imports?.gi !== 'undefined')
+        return 'gjs';
+    return 'node';
+}
+/**
+ * Which runtime to start on: the host when the template supports it — "whatever
+ * you are already running" needs no second toolchain — else the template's own
+ * first declaration, which is the canonical one.
+ *
+ * `manager` OVERRIDES that, because a pinned manager already names a runtime.
+ * Without it, `create-app x -t cli -p bun` resolved to the host (`node`), found
+ * bun illegal there and refused a combination the user had spelled out. "First
+ * declared runtime this manager installs for" needs no per-manager table: bun and
+ * deno serve one each, npm/yarn/pnpm only node, and `gjsify` — legal on gjs and
+ * node — lands on gjs, the column it was written for.
+ *
+ * `undefined` for an empty list, or when nothing declared installs with
+ * `manager`; the caller decides whether that is an error.
+ */
+export function defaultRuntimeFor(runtimes, manager) {
+    if (manager)
+        return runtimes.find((rt) => packageManagersForRuntime(rt)?.includes(manager));
+    const host = hostRuntime();
+    return runtimes.includes(host) ? host : runtimes[0];
+}
+/**
+ * The script that launches the project on `runtime`. Template convention: `start`
+ * is the gjs entry (what `gjsify.main` points at), every other runtime a suffixed
+ * sibling — `start:node`, `start:bun`, `start:deno`.
+ */
+export function startScriptFor(runtime) {
+    return runtime === 'gjs' ? 'start' : `start:${runtime}`;
+}

package/lib/select.d.ts

@@ -0,0 +1,63 @@
+import { type PackageManager } from './runtimes.js';
+/** What the caller should do about a choice. */
+export type Selection<T> = 
+/** Settled, and the user already knows why (they said so on the command line). */
+{
+    kind: 'value';
+    value: T;
+}
+/** Settled without being asked — print `notice` so it is not a silent default. */
+ | {
+    kind: 'auto';
+    value: T;
+    notice: string;
+}
+/** Ask, opening on `initial`. */
+ | {
+    kind: 'prompt';
+    choices: readonly T[];
+    initial: T;
+}
+/** Refuse, with a message that says what to pass instead. */
+ | {
+    kind: 'error';
+    message: string;
+};
+export interface RuntimeQuestion {
+    flag?: string;
+    /** The runtimes the chosen template declares AND this scaffolder can serve. */
+    offered: readonly string[];
+    /** `--package-manager`, when given — it narrows the runtime. */
+    manager?: PackageManager;
+    /** Whether stdin is a TTY, i.e. whether a prompt is possible at all. */
+    interactive: boolean;
+}
+/**
+ * Settle which runtime the project is set up for.
+ *
+ * `--runtime` is deliberately NOT mandatory on a non-TTY the way `--template` is:
+ * a template is a choice of WHAT gets written and has no defensible default, while
+ * the runtime changes not one scaffolded byte (every template ships a bundle for
+ * every runtime it declares) and only names the start script. So it defaults —
+ * announced, not assumed.
+ */
+export declare function selectRuntime(question: RuntimeQuestion): Selection<string>;
+export interface PackageManagerQuestion {
+    flag?: PackageManager;
+    /** The runtime already settled by {@link selectRuntime}. */
+    runtime: string;
+    /** Whether `--install` is set — i.e. whether this choice actually runs something. */
+    install: boolean;
+    interactive: boolean;
+}
+/**
+ * Settle which package manager installs the project.
+ *
+ * Two rules differ from the runtime above, both because a manager DOES something.
+ * A runtime offering exactly one is not a question — bun and deno install for
+ * themselves, the gjs column has no Node to run npm with — so it is taken and
+ * named rather than prompted. And with `--install` on a non-TTY, the flag is
+ * REQUIRED: this is the one default that would reach the user's disk, picking the
+ * installer that writes their node_modules and lockfile.
+ */
+export declare function selectPackageManager(question: PackageManagerQuestion): Selection<PackageManager>;

package/lib/select.js

@@ -0,0 +1,113 @@
+// The runtime / package-manager decision, as data. These functions decide;
+// `index.ts` is the shell that prints, prompts and exits. Each answer depends on a
+// flag, on what the template declares, on the other question's answer, and on
+// whether there is a TTY — deciding that inline in the yargs handler made it
+// reachable only by spawning the binary, so the half that matters most, the
+// non-TTY one, was covered by nothing but an end-to-end scaffold.
+import { defaultRuntimeFor, packageManagersForRuntime } from './runtimes.js';
+/**
+ * Settle which runtime the project is set up for.
+ *
+ * `--runtime` is deliberately NOT mandatory on a non-TTY the way `--template` is:
+ * a template is a choice of WHAT gets written and has no defensible default, while
+ * the runtime changes not one scaffolded byte (every template ships a bundle for
+ * every runtime it declares) and only names the start script. So it defaults —
+ * announced, not assumed.
+ */
+export function selectRuntime(question) {
+    const { flag, offered, manager, interactive } = question;
+    if (flag !== undefined) {
+        if (offered.length > 0 && !offered.includes(flag)) {
+            return {
+                kind: 'error',
+                message: `this template does not run on "${flag}". Declared runtimes: ${offered.join(', ')}.`,
+            };
+        }
+        return { kind: 'value', value: flag };
+    }
+    // One declared runtime is not a choice — take it without asking.
+    if (offered.length === 1)
+        return { kind: 'value', value: offered[0] };
+    // None at all means the template declares runtimes this build has no
+    // installer mapping for (`supportedRuntimes` drops the ones it cannot serve),
+    // i.e. the template is newer than the scaffolder. Refuse rather than fall
+    // back to the host: picking a runtime the template never claimed buries the
+    // real cause under whatever fails next. `--runtime` above still overrides,
+    // which is the escape hatch for a template that declares nothing at all.
+    if (offered.length === 0) {
+        return { kind: 'error', message: 'this template declares no runtime this scaffolder can install for.' };
+    }
+    const fallback = defaultRuntimeFor(offered, manager);
+    if (fallback === undefined) {
+        return {
+            kind: 'error',
+            message: `no runtime this template declares installs with "${manager}". ` +
+                `Declared runtimes: ${offered.join(', ')}.`,
+        };
+    }
+    // A pinned manager has ALREADY answered this question — bun installs for bun
+    // and nothing else — so prompting would pose a question with one honest
+    // answer. It is still reported, because the user did not name a runtime.
+    if (manager !== undefined) {
+        return {
+            kind: 'auto',
+            value: fallback,
+            notice: `Setting up for ${fallback} — the runtime ${manager} installs for.`,
+        };
+    }
+    if (interactive)
+        return { kind: 'prompt', choices: offered, initial: fallback };
+    return {
+        kind: 'auto',
+        value: fallback,
+        notice: `--runtime not given, using "${fallback}". Runs on: ${offered.join(', ')}.`,
+    };
+}
+/**
+ * Settle which package manager installs the project.
+ *
+ * Two rules differ from the runtime above, both because a manager DOES something.
+ * A runtime offering exactly one is not a question — bun and deno install for
+ * themselves, the gjs column has no Node to run npm with — so it is taken and
+ * named rather than prompted. And with `--install` on a non-TTY, the flag is
+ * REQUIRED: this is the one default that would reach the user's disk, picking the
+ * installer that writes their node_modules and lockfile.
+ */
+export function selectPackageManager(question) {
+    const { flag, runtime, install, interactive } = question;
+    const managers = packageManagersForRuntime(runtime);
+    if (managers === undefined || managers.length === 0) {
+        return { kind: 'error', message: `no package manager known for runtime "${runtime}".` };
+    }
+    if (flag !== undefined) {
+        if (!managers.includes(flag)) {
+            return {
+                kind: 'error',
+                message: `"${flag}" cannot install a project you intend to run on ${runtime}. ` +
+                    `Package managers for ${runtime}: ${managers.join(', ')}.`,
+            };
+        }
+        return { kind: 'value', value: flag };
+    }
+    if (managers.length === 1) {
+        return {
+            kind: 'auto',
+            value: managers[0],
+            notice: `Using ${managers[0]} — the only package manager that installs for ${runtime}.`,
+        };
+    }
+    if (interactive)
+        return { kind: 'prompt', choices: managers, initial: managers[0] };
+    if (install) {
+        return {
+            kind: 'error',
+            message: '--package-manager is required with --install in non-interactive mode. ' +
+                `Package managers for ${runtime}: ${managers.join(', ')}.`,
+        };
+    }
+    return {
+        kind: 'auto',
+        value: managers[0],
+        notice: `--package-manager not given, using "${managers[0]}" for ${runtime}.`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/create-app",
-    "version": "0.39.0",
+    "version": "0.41.0",
     "description": "Create a new Gjsify project",
     "type": "module",
     "main": "lib/create.js",
@@ -18,10 +18,18 @@
     },
     "bin": "./lib/index.js",
     "scripts": {
-        "clear": "gjsify clear lib tsconfig.tsbuildinfo",
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
         "check": "gjsify tsc --noEmit",
         "build": "node scripts/process-template.mjs && gjsify tsc && node scripts/set-bin-mode.mjs",
-        "test": "echo 'nothing to do'"
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:test && gjsify run test:gjs && gjsify run test:node",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "test:node": "node test.node.mjs",
+        "test:bun": "bun test.node.mjs",
+        "test:deno": "deno run -A --no-lock --node-modules-dir=none test.node.mjs",
+        "test:cross-runtime": "gjsify run build:test && gjsify run test:gjs && gjsify run test:node && gjsify run test:bun && gjsify run test:deno"
     },
     "keywords": [
         "gjs",
@@ -38,6 +46,9 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
+        "@gjsify/cli": "^0.41.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.41.0",
+        "@gjsify/unit": "^0.41.0",
         "@types/node": "^25.9.2",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"