@lenne.tech/cli 1.34.0 → 1.35.0

package/README.md

@@ -170,13 +170,14 @@ $ lt fullstack update
 
 ### Vendor-mode housekeeping
 
-Vendor-mode projects ship three maintenance scripts under `scripts/vendor/`:
+Vendor-mode projects carry no separate maintenance scripts under
+`scripts/vendor/` anymore. The vendor-specific surface is now:
 
-| Script | Purpose | Invocation |
+| Concern | Where | Invocation |
 |---|---|---|
-| `check-vendor-freshness.mjs` | Non-blocking warning when upstream has a newer release than the current baseline | `pnpm run check:vendor-freshness` (auto-invoked by `pnpm run check` / `check:fix` / `check:naf`) |
-| `sync-from-upstream.ts` | Diff generator consumed by the `nest-server-core-updater` Claude Code agent | `pnpm run vendor:sync` |
-| `propose-upstream-pr.ts` | Patch-list generator consumed by the `nest-server-core-contributor` agent | `pnpm run vendor:propose-upstream` |
+| Upstream freshness | Inline `check:vendor-freshness` script in `package.json` — reads the `src/core/VENDOR.md` baseline, compares against the npm registry, non-blocking | auto-invoked by `pnpm run check` / `check:fix` / `check:naf`, or `pnpm run check:vendor-freshness` |
+| Sync from upstream | `nest-server-core-updater` Claude Code agent | `/lt-dev:backend:update-nest-server-core` |
+| Propose local changes upstream | `nest-server-core-contributor` Claude Code agent | `/lt-dev:backend:contribute-nest-server-core` |
 
 The vendor-mode baseline (upstream version + commit SHA) is recorded in
 `src/core/VENDOR.md`. Log any substantial local patch there so the updater

package/build/commands/config/validate.js

@@ -30,11 +30,7 @@ const KNOWN_KEYS = {
         },
         deployment: {
             domain: 'string',
-            gitHub: 'boolean',
-            gitLab: 'boolean',
             noConfirm: 'boolean',
-            prodRunner: 'string',
-            testRunner: 'string',
         },
         directus: {
             dockerSetup: {

package/build/commands/deployment/create.js

@@ -9,276 +9,281 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.help = void 0;
 const path_1 = require("path");
+const angular_environments_1 = require("../../lib/angular-environments");
+const turboops_config_1 = require("../../lib/turboops-config");
+const workspace_integration_1 = require("../../lib/workspace-integration");
 /**
- * Create a new deployment for mono repository
+ * Create the TurboOps deployment config for a fullstack monorepo.
+ *
+ * The generic deployment files already ship with the monorepo template:
+ *   - projects/api/Dockerfile + projects/app/Dockerfile (from the starters)
+ *   - docker-compose.yml + .gitlab-ci.yml (TurboOps build + `turbo deploy`)
+ * so this command only writes the project-specific `.turboops.json` and prints the
+ * one-time TurboOps setup checklist (project, stages, CI/CD vars, DNS, stage env).
+ *
+ * The file is MERGED, never clobbered: any keys a user added by hand survive a
+ * re-run, and an unchanged file is left untouched.
+ *
+ * Angular apps additionally get their `environment.{prod,develop,test}.ts`
+ * rewritten to the deployed stage URLs (see lib/angular-environments.ts) — a
+ * Nuxt app reads those from the stage env at runtime, an Angular bundle bakes
+ * them in at build time. No-op for Nuxt projects.
+ *
+ * Legacy note: this used to generate a Docker-Swarm deployment (root
+ * Dockerfile/Dockerfile.app, docker-compose.{dev,test,prod}.yml, manual Traefik
+ * labels). That is obsolete on the TurboOps stack and has been removed. GitLab
+ * is the only supported pipeline — the lt-monorepo template ships
+ * `.gitlab-ci.yml`, not a GitHub deploy workflow.
  */
+exports.help = {
+    configuration: 'commands.deployment.domain, commands.deployment.noConfirm, defaults.domain, defaults.noConfirm',
+    description: 'Create the TurboOps deployment config (.turboops.json) for a fullstack monorepo',
+    examples: [
+        'deployment create',
+        'deployment create MyProject --domain myproject.lenne.tech --noConfirm',
+        'deployment create MyProject --domain myproject.lenne.tech --project myproject',
+    ],
+    features: [
+        'Writes `.turboops.json` to the workspace root (merges into an existing file)',
+        'Prints the one-time TurboOps setup checklist (project, stages, CI/CD vars, DNS, stage env)',
+    ],
+    name: 'create',
+    options: [
+        {
+            description: 'Main domain of the project (e.g. myproject.lenne.tech)',
+            flag: '--domain',
+            required: false,
+            type: 'string',
+        },
+        {
+            description: 'TurboOps project slug (registry namespace + login user). Default: kebab-case project name',
+            flag: '--project',
+            required: false,
+            type: 'string',
+        },
+        {
+            default: false,
+            description: 'Skip confirmation prompts; resolve every value from CLI flags, lt.config, or defaults',
+            flag: '--noConfirm',
+            required: false,
+            type: 'boolean',
+        },
+    ],
+};
 const NewCommand = {
     alias: ['dc'],
-    description: 'Create deployment config',
+    description: 'Create TurboOps config',
     hidden: false,
     name: 'create',
     run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
-        // Retrieve the tools we need
-        const { config, filesystem, helper, parameters, patching, print: { info, spin, success }, prompt: { confirm }, strings: { camelCase, kebabCase, pascalCase }, system, template, } = toolbox;
+        var _a, _b, _c, _d, _e, _f, _g;
+        const { config, filesystem, helper, parameters, print: { error, info, spin, success, warning }, prompt: { confirm }, strings: { kebabCase, pascalCase }, system, template, } = toolbox;
+        const fail = (message, result) => {
+            error(message);
+            if (!parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return result;
+        };
         // Load configuration
         const ltConfig = config.loadConfig();
         const configDomain = (_b = (_a = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _a === void 0 ? void 0 : _a.deployment) === null || _b === void 0 ? void 0 : _b.domain;
-        const configGitHub = (_d = (_c = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _c === void 0 ? void 0 : _c.deployment) === null || _d === void 0 ? void 0 : _d.gitHub;
-        const configGitLab = (_f = (_e = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _e === void 0 ? void 0 : _e.deployment) === null || _f === void 0 ? void 0 : _f.gitLab;
-        const configTestRunner = (_h = (_g = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _g === void 0 ? void 0 : _g.deployment) === null || _h === void 0 ? void 0 : _h.testRunner;
-        const configProdRunner = (_k = (_j = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _j === void 0 ? void 0 : _j.deployment) === null || _k === void 0 ? void 0 : _k.prodRunner;
-        // Load global defaults
         const globalDomain = config.getGlobalDefault(ltConfig, 'domain');
-        // Parse CLI arguments
-        const cliDomain = parameters.options.domain;
-        const cliGitHub = parameters.options.gitHub;
-        const cliGitLab = parameters.options.gitLab;
-        const cliTestRunner = parameters.options.testRunner;
-        const cliProdRunner = parameters.options.prodRunner;
-        const cliNoConfirm = parameters.options.noConfirm;
-        // Determine noConfirm with priority: CLI > command > parent > global > default
+        const cliDomain = (0, turboops_config_1.optionString)(parameters.options.domain);
+        const cliProject = (0, turboops_config_1.optionString)(parameters.options.project);
+        // Priority: CLI > command config > global default > false. When set, every
+        // value must resolve from a flag, lt.config, or a default — no prompts, so
+        // AI agents and CI never block on an interactive question.
         const noConfirm = config.getNoConfirm({
-            cliValue: cliNoConfirm,
-            commandConfig: (_l = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _l === void 0 ? void 0 : _l.deployment,
+            cliValue: parameters.options.noConfirm,
+            commandConfig: (_c = ltConfig === null || ltConfig === void 0 ? void 0 : ltConfig.commands) === null || _c === void 0 ? void 0 : _c.deployment,
             config: ltConfig,
         });
         // Start timer
         const timer = system.startTimer();
-        // Info
-        info('Create a new deployment');
-        // Get default project name
+        info('Create TurboOps deployment config');
+        // `.turboops.json` must sit in the repo root — `.gitlab-ci.yml` reads it
+        // from there. Resolve the workspace root so running this from inside
+        // `projects/api/` still writes to the right place.
+        const cwd = filesystem.cwd();
+        const subProject = (0, workspace_integration_1.detectSubProjectContext)(cwd, filesystem);
+        const projectRoot = (_e = (_d = subProject === null || subProject === void 0 ? void 0 : subProject.workspaceRoot) !== null && _d !== void 0 ? _d : (0, workspace_integration_1.findWorkspaceRoot)(cwd, filesystem)) !== null && _e !== void 0 ? _e : cwd;
+        if (projectRoot !== cwd) {
+            info(`Using workspace root: ${projectRoot}`);
+        }
+        // Default project name from lt.json / package.json. Read-only: `patching.update`
+        // would re-serialize and rewrite the file just to look at one field. A
+        // malformed file is tolerated (best-effort default), never fatal.
         let projectName = '';
-        const hasLtJson = yield filesystem.exists('lt.json');
-        if (hasLtJson) {
-            yield patching.update('lt.json', (data) => {
-                projectName = data.name;
-                return data;
-            });
+        const ltName = (_f = (0, turboops_config_1.readJsonObject)(filesystem, (0, path_1.join)(projectRoot, 'lt.json')).value) === null || _f === void 0 ? void 0 : _f.name;
+        if (typeof ltName === 'string' && ltName) {
+            projectName = ltName;
         }
         if (!projectName) {
-            yield patching.update('package.json', (data) => {
-                projectName = pascalCase(data.name);
-                return data;
-            });
+            const pkgName = (_g = (0, turboops_config_1.readJsonObject)(filesystem, (0, path_1.join)(projectRoot, 'package.json')).value) === null || _g === void 0 ? void 0 : _g.name;
+            if (typeof pkgName === 'string' && pkgName) {
+                projectName = pascalCase(pkgName);
+            }
         }
-        // Get name
-        const name = yield helper.getInput(parameters.first, {
-            initial: projectName,
-            name: `project name (e.g. ${projectName ? projectName : 'My new project'})`,
-        });
+        // Project name (CLI arg > detected name > interactive)
+        const cliName = (0, turboops_config_1.optionString)(parameters.first);
+        const name = cliName !== null && cliName !== void 0 ? cliName : (noConfirm
+            ? projectName
+            : yield helper.getInput('', {
+                initial: projectName,
+                name: `project name (e.g. ${projectName || 'My new project'})`,
+            }));
         if (!name) {
-            return;
+            return fail(noConfirm
+                ? 'No project name: pass it as the first argument (no lt.json / package.json "name" found).'
+                : 'No project name given.', 'deployment create: no name');
         }
-        // Determine domain with priority: CLI > config > global > interactive
+        const slug = kebabCase(name);
+        // Main domain (priority: CLI > config > global > interactive/default)
         let domain;
         if (cliDomain) {
             domain = cliDomain;
         }
         else if (configDomain) {
-            domain = configDomain.replace('{name}', kebabCase(name));
+            domain = configDomain.replace('{name}', slug);
             info(`Using domain from lt.config commands.deployment: ${domain}`);
         }
         else if (globalDomain) {
-            domain = globalDomain.replace('{name}', kebabCase(name));
+            domain = globalDomain.replace('{name}', slug);
             info(`Using domain from lt.config defaults: ${domain}`);
         }
+        else if (noConfirm) {
+            // Honour the documented `[domain]` positional; only then fall back to the
+            // default — otherwise a `--noConfirm` caller's explicit domain is dropped.
+            const argDomain = (0, turboops_config_1.optionString)(parameters.second);
+            domain = argDomain !== null && argDomain !== void 0 ? argDomain : `${slug}.lenne.tech`;
+            info(argDomain ? `Using domain: ${domain}` : `Using default domain: ${domain}`);
+        }
         else {
             domain = yield helper.getInput(parameters.second, {
-                initial: `${kebabCase(name)}.lenne.tech`,
-                name: `main domain of the project (e.g. ${kebabCase(name)}.lenne.tech)`,
+                initial: `${slug}.lenne.tech`,
+                name: `main domain of the project (e.g. ${slug}.lenne.tech)`,
             });
         }
         if (!domain) {
-            return;
+            return fail('No domain given.', 'deployment create: no domain');
         }
-        // Determine gitHub with priority: CLI > config > noConfirm > interactive
-        let gitHub;
-        if (cliGitHub !== undefined) {
-            gitHub = cliGitHub === true || cliGitHub === 'true';
+        // `domain` is written verbatim into generated Angular environment.*.ts (baked
+        // into the browser bundle) and into copy-paste checklist lines, so validate it
+        // as a hostname — a stray quote / `$` / whitespace would inject into the
+        // generated source or emit a non-compiling config. Mirrors the slug check below.
+        if (!(0, turboops_config_1.isValidDomain)(domain)) {
+            return fail(`Invalid domain "${domain}" — expected a hostname like ${slug}.lenne.tech (letters, digits, dashes, dots).`, 'deployment create: invalid domain');
         }
-        else if (configGitHub !== undefined) {
-            gitHub = configGitHub;
-            if (gitHub) {
-                info('Using GitHub pipeline setting from lt.config: enabled');
-            }
+        // TurboOps project slug (registry namespace + login user). Defaults to the kebab name.
+        const rawProject = cliProject !== null && cliProject !== void 0 ? cliProject : (noConfirm ? slug : yield helper.getInput('', { initial: slug, name: `TurboOps project slug (e.g. ${slug})` }));
+        if (!rawProject) {
+            return fail('No TurboOps project slug given.', 'deployment create: no project');
         }
-        else if (noConfirm) {
-            gitHub = false; // Default to false when noConfirm
-        }
-        else {
-            gitHub = yield confirm('Add GitHub pipeline?');
+        // `docker login -u "$TURBOOPS_PROJECT"` and `registry.turbo-ops.de/<project>`
+        // only accept a lowercase dash-separated slug.
+        const project = kebabCase(rawProject);
+        if (!(0, turboops_config_1.isValidProjectSlug)(project)) {
+            return fail(`Invalid TurboOps project slug "${rawProject}" — expected lowercase letters, digits and dashes.`, 'deployment create: invalid project slug');
         }
-        // Determine gitLab with priority: CLI > config > noConfirm > interactive
-        let gitLab;
-        if (cliGitLab !== undefined) {
-            gitLab = cliGitLab === true || cliGitLab === 'true';
+        if (project !== rawProject) {
+            warning(`Normalized TurboOps project slug "${rawProject}" → "${project}".`);
         }
-        else if (configGitLab !== undefined) {
-            gitLab = configGitLab;
-            if (gitLab) {
-                info('Using GitLab pipeline setting from lt.config: enabled');
+        // Write `.turboops.json`. Merge instead of overwrite: the file is committed
+        // and a user may have added keys by hand; a re-run must not silently drop them.
+        const target = (0, path_1.join)(projectRoot, '.turboops.json');
+        const generateSpinner = spin('Generate .turboops.json');
+        const current = (0, turboops_config_1.readJsonObject)(filesystem, target);
+        const existing = current.value;
+        // File exists but did not parse into a usable object (malformed JSON, or a
+        // bare null/number/array). Don't silently clobber it.
+        if (current.found && !existing) {
+            generateSpinner.fail('.turboops.json exists but is not a usable JSON object');
+            if (noConfirm || !(yield confirm(`Replace the unusable ${target}?`, false))) {
+                return fail(`Refusing to overwrite unusable ${target}.`, 'deployment create: unusable config');
             }
         }
-        else if (noConfirm) {
-            gitLab = false; // Default to false when noConfirm
-        }
-        else {
-            gitLab = yield confirm('Add GitLab pipeline?');
-        }
-        // GitLab test runner
-        let testRunner;
-        let prodRunner;
-        if (gitLab) {
-            // Determine testRunner with priority: CLI > config > interactive
-            if (cliTestRunner) {
-                testRunner = cliTestRunner;
-            }
-            else if (configTestRunner) {
-                testRunner = configTestRunner;
-                info(`Using test runner from lt.config: ${testRunner}`);
-            }
-            else {
-                testRunner = yield helper.getInput('', {
-                    initial: 'docker-swarm',
-                    name: 'runner for test (tag in .gitlab-ci.yml, e.g. docker-swarm)',
-                });
-            }
-            if (!testRunner) {
-                return;
-            }
-            // Determine prodRunner with priority: CLI > config > interactive
-            if (cliProdRunner) {
-                prodRunner = cliProdRunner;
-            }
-            else if (configProdRunner) {
-                prodRunner = configProdRunner;
-                info(`Using prod runner from lt.config: ${prodRunner}`);
+        if (existing) {
+            const merged = (0, turboops_config_1.mergeTurboOpsConfig)(existing, project);
+            if (!merged.changed) {
+                generateSpinner.succeed('.turboops.json already up to date');
             }
             else {
-                prodRunner = yield helper.getInput('', {
-                    initial: 'docker-landing',
-                    name: 'runner for production (tag in .gitlab-ci.yml, e.g. docker-landing)',
-                });
-            }
-            if (!prodRunner) {
-                return;
+                if (merged.previousProject && merged.previousProject !== project) {
+                    warning(`Changing TurboOps project "${merged.previousProject}" → "${project}".`);
+                }
+                // Trailing newline matches the template-generated form, so re-runs stay
+                // byte-stable and never produce a whitespace-only diff.
+                filesystem.write(target, `${JSON.stringify(merged.config, null, 2)}\n`);
+                generateSpinner.succeed('.turboops.json updated (existing keys preserved)');
             }
         }
-        // Set up initial props (to pass into templates)
-        const nameCamel = camelCase(name);
-        const nameKebab = kebabCase(name);
-        const namePascal = pascalCase(name);
-        // Check if directory
-        const cwd = filesystem.cwd();
-        const generateSpinner = spin('Generate files');
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'scripts', 'build-push.sh'),
-            template: 'deployment/scripts/build-push.sh.ejs',
-        });
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'scripts', 'deploy.sh'),
-            template: 'deployment/scripts/deploy.sh.ejs',
-        });
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'Dockerfile'),
-            template: 'deployment/Dockerfile.ejs',
-        });
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'Dockerfile.app'),
-            template: 'deployment/Dockerfile.app.ejs',
-        });
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'docker-compose.dev.yml'),
-            template: 'deployment/docker-compose.dev.yml.ejs',
-        });
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'docker-compose.test.yml'),
-            template: 'deployment/docker-compose.test.yml.ejs',
-        });
-        yield template.generate({
-            props: { nameCamel, nameKebab, namePascal },
-            target: (0, path_1.join)(cwd, 'docker-compose.prod.yml'),
-            template: 'deployment/docker-compose.prod.yml.ejs',
-        });
-        if (gitHub) {
-            yield template.generate({
-                props: { nameCamel, nameKebab, namePascal, url: domain },
-                target: (0, path_1.join)(cwd, '.github', 'workflows', 'pre-release.yml'),
-                template: 'deployment/.github/workflows/pre-release.yml.ejs',
-            });
-            yield template.generate({
-                props: { nameCamel, nameKebab, namePascal, url: domain },
-                target: (0, path_1.join)(cwd, '.github', 'workflows', 'release.yml'),
-                template: 'deployment/.github/workflows/release.yml.ejs',
-            });
-        }
-        if (gitLab) {
-            yield template.generate({
-                props: { nameCamel, nameKebab, namePascal, prodRunner, testRunner, url: domain },
-                target: (0, path_1.join)(cwd, '.gitlab-ci.yml'),
-                template: 'deployment/.gitlab-ci.yml.ejs',
-            });
-        }
-        generateSpinner.succeed('Files generated');
-        const environmentsSpinner = spin('Update app environment files');
-        const prodEnv = yield filesystem.exists('projects/app/src/environments/environment.prod.ts');
-        if (prodEnv) {
-            yield patching.patch('projects/app/src/environments/environment.prod.ts', {
-                insert: `https://api.${domain}`,
-                replace: new RegExp('http://127.0.0.1:3000', 'g'),
-            });
-            yield patching.patch('projects/app/src/environments/environment.prod.ts', {
-                insert: `wss://api.${domain}`,
-                replace: new RegExp('ws://127.0.0.1:3000', 'g'),
-            });
-            yield patching.patch('projects/app/src/environments/environment.prod.ts', {
-                insert: `https://${domain}`,
-                replace: new RegExp('http://127.0.0.1:4200', 'g'),
-            });
-        }
         else {
-            info('Missing projects/app/src/environments/environment.prod.ts');
-        }
-        const testEnv = yield filesystem.exists('projects/app/src/environments/environment.test.ts');
-        if (testEnv) {
-            yield patching.patch('projects/app/src/environments/environment.test.ts', {
-                insert: `https://api.test.${domain}`,
-                replace: new RegExp('http://127.0.0.1:3000', 'g'),
-            });
-            yield patching.patch('projects/app/src/environments/environment.test.ts', {
-                insert: `wss://api.test.${domain}`,
-                replace: new RegExp('ws://127.0.0.1:3000', 'g'),
-            });
-            yield patching.patch('projects/app/src/environments/environment.test.ts', {
-                insert: `https://test.${domain}`,
-                replace: new RegExp('http://127.0.0.1:4200', 'g'),
+            yield template.generate({
+                props: { project },
+                target,
+                template: 'deployment/turboops.json.ejs',
             });
+            generateSpinner.succeed('.turboops.json generated');
         }
-        else {
-            info('Missing projects/app/src/environments/environment.test.ts');
+        // Angular bakes its API URL into the bundle at build time, so the deployed
+        // stage URLs must be written into `environment.*.ts`. No-op for Nuxt, which
+        // reads them from the TurboOps stage env at runtime. Detect Angular from the
+        // presence of the environments dir, NOT from the patch count — a project
+        // using non-standard env filenames would otherwise be misread as Nuxt and
+        // ship a bundle that still calls localhost.
+        const isAngular = (0, angular_environments_1.findAngularEnvironmentsDir)(projectRoot) !== null;
+        if (isAngular) {
+            const envPatches = (0, angular_environments_1.patchAngularEnvironments)({ domain, projectRoot });
+            const changed = envPatches.filter((r) => r.patched);
+            if (changed.length > 0) {
+                for (const r of changed) {
+                    success(`patched ${r.replacements}× in ${(0, path_1.relative)(projectRoot, r.file)} (deployed URLs)`);
+                }
+            }
+            else if (envPatches.some((r) => r.recognized)) {
+                info('Angular environment files already point at the deployed URLs.');
+            }
+            else {
+                warning('Angular project detected but no environment.{prod,develop,test}.ts with a rewritable URL was found — ' +
+                    'set the deployed API/app URLs manually so the bundle does not call localhost.');
+            }
         }
-        environmentsSpinner.succeed('App environment files updated');
-        // We're done, so show what to do next
+        // One-time setup checklist
         info('');
-        success(`Generated deployment for ${namePascal} in ${helper.msToMinutesAndSeconds(timer())}m.`);
+        success(`TurboOps deployment wired for "${name}" in ${helper.msToMinutesAndSeconds(timer())}m.`);
         info('');
-        // Hint for CI/CD
-        const subDomains = ['www', 'api', 'test', 'www.test', 'api.test'];
-        let urlStr = `\n- ${domain}`;
-        for (const sub of subDomains) {
-            urlStr += `\n- ${sub}.${domain}`;
+        info('One-time setup:');
+        info(`  1. TurboOps: create project "${project}" with stages "dev" and "production" on your server.`);
+        info(`     - production domains: ${domain} (app) + api.${domain} (api)`);
+        info(`     - dev domains:        dev.${domain} (app) + api.dev.${domain} (api)`);
+        info(`  2. CI/CD variables: TURBOOPS_PROJECT=${project} and TURBOOPS_TOKEN=<token> (masked).`);
+        info('     GitLab: Settings > CI/CD > Variables. GitHub: a repo variable + a repo secret.');
+        info('  3. DNS A/AAAA records -> your server IP. A wildcard matches exactly ONE label, so:');
+        info(`     - ${domain}          (apex — NOT covered by a wildcard)`);
+        info(`     - *.${domain}        (covers api.${domain} and dev.${domain})`);
+        info(`     - *.dev.${domain}    (covers api.dev.${domain})`);
+        info('  4. Set the stage env vars in TurboOps (per stage), e.g. for production:');
+        info(`       NODE_ENV=production, NSC__BASE_URL=https://api.${domain},`);
+        info('       NSC__MONGOOSE__URI, NSC__BETTER_AUTH__SECRET, NSC__AI__ENCRYPTION_SECRET,');
+        if (isAngular) {
+            info('       NSC__EMAIL__SMTP__*, NSC__EMAIL__DEFAULT_SENDER__EMAIL');
+            info('     The Angular app needs no URL env vars — they are baked into');
+            info('     environment.prod.ts / environment.develop.ts (patched above).');
+        }
+        else {
+            info('       NSC__EMAIL__SMTP__*, NSC__EMAIL__DEFAULT_SENDER__EMAIL,');
+            info(`       NUXT_PUBLIC_API_URL=https://api.${domain}, NUXT_API_URL=https://api.${domain},`);
+            info(`       NUXT_PUBLIC_SITE_URL=https://${domain}`);
         }
-        success(`HINT: please initialize following Domains before running the CI/CD pipeline:${urlStr}`);
+        info(isAngular
+            ? '  5. Commit `.turboops.json` (read by `turbo deploy`) AND the patched environment.*.ts (baked into the build).'
+            : '  5. Commit `.turboops.json` — `turbo deploy` reads it from the repo root in CI.');
         info('');
-        if (!toolbox.parameters.options.fromGluegunMenu) {
+        info('Then: push `dev` -> the dev stage, push `main` -> the production stage');
+        info('(.gitlab-ci.yml, or .github/workflows/deploy.yml on GitHub). Tests gate the deploy.');
+        if (!parameters.options.fromGluegunMenu) {
             process.exit();
         }
         // For tests

package/build/commands/dev/init.js

@@ -47,7 +47,8 @@ const InitCommand = {
         const { filesystem, parameters, print: { colors, error, info, success, warning }, } = toolbox;
         const layout = (0, dev_project_1.resolveLayout)(filesystem.cwd(), filesystem);
         if (!layout.apiDir && !layout.appDir) {
-            error('No API (src/config.env.ts) or App (nuxt.config.ts) project detected at this path.');
+            error('No lt project detected at this path. Expected an API (src/config.env.ts or nest-cli.json), ' +
+                'an App (nuxt.config.ts), or a monorepo with projects/api and/or projects/app.');
             if (!parameters.options.fromGluegunMenu)
                 process.exit(1);
             return 'dev init: not a project';

package/build/commands/dev/status.js

@@ -128,6 +128,8 @@ const StatusCommand = {
             const port = sub === 'api' ? entry.internalPorts.api : entry.internalPorts.app;
             info(`  ${sub.padEnd(6)} https://${host}${port ? colors.dim(`  →  127.0.0.1:${port}`) : ''}`);
         }
+        // `loadRegistry` strips dbName from API-less (App-only) entries, so its
+        // presence alone means there is a database to advertise.
         if (entry.dbName)
             info(`  db     mongodb://127.0.0.1/${entry.dbName}`);
         // Patch status — quick view whether legacy ports are still in source.

package/build/commands/dev/test.js

@@ -224,9 +224,9 @@ const TestCommand = {
         let exitCode = 1;
         try {
             const ctx = yield (0, dev_test_session_1.bringUpTestSession)(layout, identity, log, { devDbName });
-            const env = Object.assign(Object.assign(Object.assign({}, process.env), readBridgeEnv(layout.root)), { 
+            const env = Object.assign(Object.assign(Object.assign(Object.assign({}, process.env), readBridgeEnv(layout.root)), { 
                 // Playwright global-setup resets THIS db (allow-listed) before the suite.
-                MONGO_URI: `mongodb://127.0.0.1/${ctx.dbName}` });
+                MONGO_URI: `mongodb://127.0.0.1/${ctx.dbName}` }), (ctx.apiLogPath ? { NEST_SERVER_LOG: ctx.apiLogPath } : {}));
             if (debug) {
                 env.PWDEBUG = '1';
                 env.HEADED = '1';

package/build/commands/dev/up.js

@@ -86,7 +86,8 @@ const UpCommand = {
         const { filesystem, parameters, print: { colors, error, info, success, warning }, } = toolbox;
         const layout = (0, dev_project_1.resolveLayout)(filesystem.cwd(), filesystem);
         if (!layout.apiDir && !layout.appDir) {
-            error('No API or App project detected at this path. Run `lt dev init` first.');
+            error('No lt project detected at this path. Expected an API (src/config.env.ts or nest-cli.json), ' +
+                'an App (nuxt.config.ts), or a monorepo with projects/api and/or projects/app.');
             if (!parameters.options.fromGluegunMenu)
                 process.exit(1);
             return 'dev up: not a project';
@@ -271,7 +272,9 @@ const UpCommand = {
                 apiUpstreamPort: existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.internalPorts.api,
                 appHostname: (_d = identity.subdomains.app) === null || _d === void 0 ? void 0 : _d.hostname,
                 appUpstreamPort: existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.internalPorts.app,
-                dbName: (_e = existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.dbName) !== null && _e !== void 0 ? _e : dbName,
+                // App-only projects have no database — don't advertise a Mongo URL
+                // that nothing listens on.
+                dbName: identity.subdomains.api ? ((_e = existingEntry === null || existingEntry === void 0 ? void 0 : existingEntry.dbName) !== null && _e !== void 0 ? _e : dbName) : undefined,
             });
             info('Run `lt dev down` first to force a full restart.');
             if (!parameters.options.fromGluegunMenu)
@@ -317,7 +320,8 @@ const UpCommand = {
             info(`  app: https://${identity.subdomains.app.hostname}  →  127.0.0.1:${appPort}`);
         if (identity.subdomains.api)
             info(`  api: https://${identity.subdomains.api.hostname}  →  127.0.0.1:${apiPort}`);
-        info(`  db:  mongodb://127.0.0.1/${dbName}`);
+        if (identity.subdomains.api)
+            info(`  db:  mongodb://127.0.0.1/${dbName}`);
         info('');
         // Build env per process.
         const devEnv = (0, dev_env_1.buildDevEnv)({
@@ -414,7 +418,7 @@ const UpCommand = {
             apiUpstreamPort: apiPort,
             appHostname: (_l = identity.subdomains.app) === null || _l === void 0 ? void 0 : _l.hostname,
             appUpstreamPort: appPort,
-            dbName,
+            dbName: identity.subdomains.api ? dbName : undefined,
         });
         info(colors.dim('Logs: <root>/.lt-dev/api.log, <root>/.lt-dev/app.log'));
         for (const note of rotationNotes)