@tulipes/cli 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TulipesJS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+<div align="center">
+
+<img src="https://cdn.jsdelivr.net/npm/@tulipes/core@0.7.1/assets/tulipesjs-logo.png" alt="TulipesJs" width="340">
+
+</div>
+
+# @tulipes/cli
+
+The `tulipes` command line for [Tulipes](https://www.npmjs.com/package/@tulipes/core)
+apps: scaffold, sync generated types, validate the environment, inspect routes,
+generate OpenAPI/Postman documents, run in watch mode, add modules and upgrade.
+It is separate from the runtime on purpose — a running app installs
+`@tulipes/core` alone, without this package, its templates or the TypeScript
+loader it carries.
+
+```sh
+npm install -g @tulipes/cli@next
+tulipes init my-api            # minimal preset; --preset production for the full app
+cd my-api && corepack enable && yarn install && yarn dev
+```
+
+Generated apps also list `@tulipes/cli` in `devDependencies`, so `yarn dev`,
+`yarn sync`, `yarn spec` and `yarn tulipes new module <name>` work without a
+global install and always match the app.
+
+| Command | What it does |
+|---|---|
+| `tulipes init [dir] [--minimal \| --preset minimal \| --preset production] [--no-queues] [--no-sockets]` | scaffold an application; no services. The two opt-outs apply to the production preset and leave that provider, its files, dependencies and worker process out |
+| `tulipes dev [entry]` | regenerate types, then run under tsx watch |
+| `tulipes sync` | regenerate `types/config.d.ts` and `.env.example` |
+| `tulipes env:check` | validate the environment without booting |
+| `tulipes routes [--offline \| --runtime]` | list declared endpoints |
+| `tulipes spec [--offline \| --runtime] [--openapi file] [--postman file] [--url base]` | generate documents (needs `@tulipes/spec` in the app) |
+| `tulipes new module <name> [--model\|--no-model] [--queues\|--no-queues] [--sockets\|--no-sockets]` | scaffold a module for the providers the app declares |
+| `tulipes update` | upgrade the global CLI and, inside an app, its core and CLI ranges |
+| `tulipes -v` | print the CLI version, its bundled core, and the app's core when they differ |
+
+Every command that touches an app boots or inspects it through **the app's
+own** `@tulipes/core`, so there is one copy of every framework singleton; the
+bundled core is only a fallback for directories with no install. Generated
+dependency ranges follow the core this CLI bundles.
+
+## Versions
+
+`0.1.0-rc.1` bundles core `0.10.0-rc.3` and scaffolds for it. See core's
+[MIGRATING.md](https://github.com/kemora13conf/bp-backend-express/blob/master/packages/core/MIGRATING.md#unreleased--install-the-cli-package).

package/dist/app-core.d.ts

@@ -0,0 +1,33 @@
+import type { BootHandle, BootOptions } from "@tulipes/core/boot";
+export type BootFn = (options: BootOptions) => Promise<BootHandle>;
+/**
+ * Resolves a module **from the app**, not from wherever this CLI lives.
+ *
+ * `tulipes` is normally installed globally, so a bare `import(...)` inside
+ * the CLI resolves against the CLI's own node_modules. For anything the
+ * app also depends on, that yields a *second* copy — and two copies of a
+ * library that uses `instanceof` do not recognise each other's objects.
+ */
+export declare function importFromApp<T>(rootDir: string, specifier: string): Promise<T | undefined>;
+/**
+ * The `boot` belonging to the app, falling back to this CLI's own.
+ *
+ * Booting through the app's own `@tulipes/core` is what keeps every shared
+ * singleton to ONE copy, and what makes the app's
+ * declared providers (`tulipes.providers`) resolve from the app rather than
+ * from wherever the CLI happens to be installed.
+ *
+ * The fallback covers an app with no local install, where the CLI's copy
+ * is the only one there is. A version skew between the two is reported by
+ * `tulipes -v`.
+ */
+export declare function appBoot(rootDir: string): Promise<BootFn>;
+/**
+ * Registers the TypeScript loader before any app file is imported.
+ *
+ * The published CLI runs as plain node while an app's modules are
+ * TypeScript, so without this every dynamic import of a `.ts` file fails
+ * to resolve. The hook is process-wide, so it also covers imports the
+ * app's own core makes afterwards. Harmless when the app is compiled.
+ */
+export declare function registerTypeScript(): Promise<void>;

package/dist/app-core.js

@@ -0,0 +1,58 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { boot as bundledBoot } from "@tulipes/core/boot";
+/**
+ * Resolves a module **from the app**, not from wherever this CLI lives.
+ *
+ * `tulipes` is normally installed globally, so a bare `import(...)` inside
+ * the CLI resolves against the CLI's own node_modules. For anything the
+ * app also depends on, that yields a *second* copy — and two copies of a
+ * library that uses `instanceof` do not recognise each other's objects.
+ */
+export async function importFromApp(rootDir, specifier) {
+    try {
+        // Anchored on the app's package.json so resolution starts in the app,
+        // whatever directory the CLI itself was installed into.
+        const requireFromApp = createRequire(join(rootDir, "package.json"));
+        const entry = requireFromApp.resolve(specifier);
+        return (await import(pathToFileURL(entry).href));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `boot` belonging to the app, falling back to this CLI's own.
+ *
+ * Booting through the app's own `@tulipes/core` is what keeps every shared
+ * singleton to ONE copy, and what makes the app's
+ * declared providers (`tulipes.providers`) resolve from the app rather than
+ * from wherever the CLI happens to be installed.
+ *
+ * The fallback covers an app with no local install, where the CLI's copy
+ * is the only one there is. A version skew between the two is reported by
+ * `tulipes -v`.
+ */
+export async function appBoot(rootDir) {
+    const module = await importFromApp(rootDir, "@tulipes/core/boot");
+    return module?.boot ?? bundledBoot;
+}
+/**
+ * Registers the TypeScript loader before any app file is imported.
+ *
+ * The published CLI runs as plain node while an app's modules are
+ * TypeScript, so without this every dynamic import of a `.ts` file fails
+ * to resolve. The hook is process-wide, so it also covers imports the
+ * app's own core makes afterwards. Harmless when the app is compiled.
+ */
+export async function registerTypeScript() {
+    try {
+        const tsx = (await import("tsx/esm/api"));
+        tsx.register?.();
+    }
+    catch {
+        // No tsx available: a compiled app still boots fine without it.
+    }
+}
+//# sourceMappingURL=app-core.js.map

package/dist/app-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-core.js","sourceRoot":"","sources":["../src/app-core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKzD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,OAAe,EAAE,SAAiB;IACvE,IAAI,CAAC;QACH,sEAAsE;QACtE,wDAAwD;QACxD,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChD,OAAO,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAM,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAe;IAC3C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAoB,OAAO,EAAE,oBAAoB,CAAC,CAAC;IACrF,OAAO,MAAM,EAAE,IAAI,IAAI,WAAW,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,CAA8B,CAAC;QACvE,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;AACH,CAAC"}

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Published bin entry — compiled to dist/bin.js. The dev workspace uses
+// bin/tulipes.js (a tsx shim over the same main) instead; publishConfig.bin
+// swaps this one in at pack time.
+import { main } from "./main.js";
+await main(process.argv.slice(2));
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,wEAAwE;AACxE,4EAA4E;AAC5E,kCAAkC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/dev.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `tulipes dev [entry]` — sync first (generated types must never be stale
+ * when the dev server starts), then hand off to tsx in watch mode.
+ *
+ * tsx is resolved from core's own dependencies rather than trusting PATH,
+ * so the command works in any workspace layout.
+ */
+export declare function runDev(rootDir: string, entry: string): Promise<void>;

package/dist/dev.js

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { runSync } from "./sync.js";
+/**
+ * `tulipes dev [entry]` — sync first (generated types must never be stale
+ * when the dev server starts), then hand off to tsx in watch mode.
+ *
+ * tsx is resolved from core's own dependencies rather than trusting PATH,
+ * so the command works in any workspace layout.
+ */
+export async function runDev(rootDir, entry) {
+    await runSync(rootDir);
+    const require = createRequire(import.meta.url);
+    const tsxPackage = require.resolve("tsx/package.json");
+    const tsxCli = join(dirname(tsxPackage), "dist", "cli.mjs");
+    const child = spawn(process.execPath, [tsxCli, "watch", "--clear-screen=false", entry], { cwd: rootDir, stdio: "inherit" });
+    child.on("exit", (code) => {
+        process.exitCode = code ?? 0;
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAe,EAAE,KAAa;IACzD,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAE5D,MAAM,KAAK,GAAG,KAAK,CACjB,OAAO,CAAC,QAAQ,EAChB,CAAC,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,KAAK,CAAC,EAChD,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CACnC,CAAC;IACF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,OAAO,CAAC,QAAQ,GAAG,IAAI,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/env-check.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `tulipes env:check` — boot phases 1–3 and nothing else: validate the
+ * current environment against every module's declared contract, print the
+ * verdict, exit accordingly. Built for CI gates and deploy preflights.
+ */
+export declare function runEnvCheck(rootDir: string): Promise<void>;

package/dist/env-check.js

@@ -0,0 +1,28 @@
+import { Environment } from "@tulipes/core/env";
+import { TulipesBootError } from "@tulipes/core/errors";
+/**
+ * `tulipes env:check` — boot phases 1–3 and nothing else: validate the
+ * current environment against every module's declared contract, print the
+ * verdict, exit accordingly. Built for CI gates and deploy preflights.
+ */
+export async function runEnvCheck(rootDir) {
+    let env;
+    try {
+        env = Environment.load({ rootDir });
+    }
+    catch (error) {
+        if (error instanceof TulipesBootError) {
+            console.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+    const snapshot = env.store.snapshot(); // secrets redacted
+    const names = Object.keys(snapshot);
+    console.log(`APP_ENV=${env.appEnv} — ${names.length} variable(s) resolved:`);
+    for (const name of names) {
+        console.log(`  ✔ ${name}=${String(snapshot[name])}`);
+    }
+}
+//# sourceMappingURL=env-check.js.map

package/dist/env-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-check.js","sourceRoot":"","sources":["../src/env-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAe;IAC/C,IAAI,GAAG,CAAC;IACR,IAAI,CAAC;QACH,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;YACtC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,mBAAmB;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,MAAM,MAAM,KAAK,CAAC,MAAM,wBAAwB,CAAC,CAAC;IAC7E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `tulipes init [dir]` — scaffold a complete application.
+ *
+ * Three modules ship: core (sys 0 — env contract, roles, request ids),
+ * security (sys 10 — helmet, cors, logging, body parsing) and hello, a
+ * worked example of EVERY module contract: config with lifecycle hooks,
+ * ACL grants, routes, a controller, a helper, a model, a bootstrap task,
+ * a queue with its processor, and a socket namespace.
+ *
+ * The generated app therefore needs mongo and redis running — models and
+ * queues cannot work without them, and the boot refuses rather than
+ * degrading quietly.
+ */
+export type InitPreset = "minimal" | "production";
+/**
+ * What the production preset composes. Models are not optional there: auth,
+ * users and settings own models, so the preset without a database is a
+ * different application, not a feature toggle. Queues and sockets are.
+ */
+export interface InitFeatures {
+    queues: boolean;
+    sockets: boolean;
+}
+export declare const FULL_FEATURES: InitFeatures;
+export declare function runInit(rootDir: string, target?: string, preset?: InitPreset, features?: InitFeatures): Promise<void>;