feat(create-app): add --starter flag to set CUSTOM_STARTER_URL for local Docker instance

[fmontes]

Summary

• Adds --starter <url> CLI option to dotcms-create-app for local Docker deployments
• When provided, sets the CUSTOM_STARTER_URL environment variable when running docker compose up
• Validates the starter URL using the existing validateUrl helper (must be a valid http/https URL)
• Fixes sdk-create-app ESM build/runtime packaging: bundles ts-results via a local Result helper and publishes a CLI-only npm artifact
• libs/sdk/create-app/project.json now uses @nx/esbuild with format: [\"esm\"], bundle: true, and thirdParty: true so the CLI ships as a single ESM entrypoint
• The external list keeps true runtime deps external (chalk/ora/inquirer/execa/etc.) while avoiding fragile package-internal imports in the emitted bundle

Build/Pack Key Properties

• project.json: executor switched to @nx/esbuild; platform: "node" + format: ["esm"] targets Node ESM CLI output
• project.json: bundle: true and thirdParty: true generate a single bundled runtime entrypoint
• project.json: external keeps runtime deps external while internal utility/result code is bundled
• project.json: production banner adds the Node shebang and assets copies README.md + package.json into dist
• package.json: set as CLI-only (type: "module", main: "./index.js", bin.create-dotcms-app: "./index.js")
• package.json: removed types and declaration/source publish entries (*.d.ts, src) to keep npm payload minimal
• package.json: removed ts-results/tslib runtime dependency entries after replacing with local result helper

Test plan

• Run dotcms-create-app my-app --local --starter https://repo.example.com/my-starter.zip and verify CUSTOM_STARTER_URL is passed to Docker
• Run without --starter and verify existing behavior is unchanged
• Pass an invalid URL (e.g. --starter not-a-url) and verify validation error is shown
• Run yarn nx build sdk-create-app --skip-nx-cache && node dist/libs/sdk/create-app/index.js --help and verify no ERR_MODULE_NOT_FOUND or dynamic require runtime errors

[github-actions]

❌ Issue Linking Required

This PR could not be linked to an issue. All PRs must be linked to an issue for tracking purposes.

How to fix this:

Option 1: Add keyword to PR body (Recommended - auto-removes this comment)
Edit this PR description and add one of these lines:

• This PR fixes #123 or Fixes: #123

• This PR closes #123 or Closes: #123

• This PR resolves #123 or Resolves: #123

• Other supported keywords: fix, fixed, close, closed, resolve, resolved
  Option 2: Link via GitHub UI (Note: won't clear the failed check)

1. Go to the PR → Development section (right sidebar)

2. Click "Link issue" and select an existing issue

3. Push a new commit or re-run the workflow to clear the failed check
   Option 3: Use branch naming
   Create a new branch with one of these patterns:

• 123-feature-description (number at start)

• issue-123-feature-description (issue-number at start)

• feature-issue-123 (issue-number anywhere)

Why is this required?

Issue linking ensures proper tracking, documentation, and helps maintain project history. It connects your code changes to the problem they solve.---

This comment was automatically generated by the issue linking workflow

[claude]

Claude finished @fmontes's task in 1m 19s —— View job

---

PR Review: feat(create-app): add --starter flag

• Read changed files
• Analyze code for issues
• Post review

---

Issues Found

1. --starter is silently ignored when used without --local (medium risk)

In src/index.ts:94, validateUrl(options.starter) runs before the local/cloud branch decision. If the user provides --starter <url> alongside --url <cloud-instance> (no --local), the starter URL is validated successfully but then silently dropped — it never reaches runDockerCompose since that's only in the local path.

validateConflictingParameters at line 95 only warns when --local is set alongside cloud params — it doesn't warn when --starter is set without --local. A user running:

dotcms-create-app my-app --url https://demo.dotcms.com --starter https://my-starter.zip

...gets no warning that --starter was ignored. Fix this →

2. --starter without --local is not semantically blocked

The flag description says "Custom starter URL for the local dotCMS Docker instance" but there's no enforcement. Minor, but consistent with point 1.

3. result.ts re-implements ts-results — no issue with the pattern itself, but the never types may be too strict in practice

Ok<T> returns Result<T, never> and Err<E> returns Result<never, E>. This works fine for the current usages, but callers that accumulate results across branches (e.g., mixing Ok and Err) can hit type inference issues without explicit type annotations. Not a bug here, just something to watch if usage grows.

4. esbuildOptions trailing comma in project.json:46

"esbuildOptions": {
    "sourcemap": true,
    "outExtension": {
        ".js": ".js"
    },   // <-- trailing comma
}

JSON doesn't allow trailing commas. This may work if Nx parses it tolerantly, but it's technically invalid JSON and will break standard parsers. Fix this →

5. docker ps call in runDockerCompose has no clear purpose

src/index.ts:446:

await execa('docker', ['compose', 'up', '-d'], { cwd: directory, env });
await execa('docker', ['ps'], { cwd: directory });

docker ps output is captured but discarded. It doesn't affect the return value. This looks like leftover debug code. Fix this →

6. package.json missing source-map-support or equivalent

The production build disables sourcemaps ("sourcemap": false) but the dev build enables them. When sourcemaps are present, Node won't show mapped stack traces unless a source map loader is in place. Not a blocker, just a DX note.

---

No Issues With

• The result.ts local helper replacing ts-results is clean and appropriate for the bundling strategy.
• The runDockerCompose environment spreading ({ ...process.env, CUSTOM_STARTER_URL: starterUrl }) is correct — it doesn't mutate process.env.
• The esbuild bundling config (bundle: true, thirdParty: true, explicit external list) is sound.
• tsconfig.lib.json changes (moduleResolution: "bundler", declaration: false) are appropriate for a CLI-only output.
• The DotCmsCliOptions type extension with starter?: string is correct.