catalyst-core 1.0.2-canary.1 → 1.0.2

package/bin/catalyst.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process"
+import { createRequire } from "node:module"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
@@ -19,6 +20,103 @@ const platformScripts = {
 }
 const validCommands = new Set([...webCommands, "buildApp", "setupEmulator", ...Object.keys(platformScripts)])
 
+const require = createRequire(import.meta.url)
+const pkg = require("../package.json")
+
+// The house style when the built CLI layer is present; plain text otherwise,
+// so help still works from a source checkout that has not been built.
+let theme = null
+try {
+    theme = require("../dist/cli/theme.js")
+} catch {
+    // Unbuilt checkout.
+}
+const paint = (name, text) => (theme ? theme.t[name](text) : text)
+const GUTTER = "  "
+
+const HELP = [
+    [
+        "Web",
+        [
+            ["start", "Start the development server"],
+            ["build", "Build the app for production"],
+            ["serve", "Serve the production build"],
+        ],
+    ],
+    [
+        "Native",
+        [
+            ["setupEmulator:android", "Configure and boot the Android emulator"],
+            ["setupEmulator:ios", "Configure and boot the iOS simulator"],
+            ["buildApp:android", "Build and install the Android app"],
+            ["buildApp:ios", "Build and install the iOS app"],
+        ],
+    ],
+    [
+        "More",
+        [
+            ["serve:inspect", "Serve with the Node inspector attached"],
+            ["plugins", "Turn native plugins on or off"],
+        ],
+    ],
+]
+
+function printHelp() {
+    const width = 24
+    const lines = [""]
+    lines.push(`${GUTTER}${paint("bold", paint("accent", "catalyst"))}${paint("dim", ` v${pkg.version}`)}`)
+    lines.push(`${GUTTER}${paint("dim", "─".repeat(46))}`)
+    lines.push(`${GUTTER}${paint("dim", "Usage")}  catalyst <command> [options]`)
+    for (const [group, commands] of HELP) {
+        lines.push("", `${GUTTER}${paint("bold", group)}`)
+        for (const [name, text] of commands)
+            lines.push(`${GUTTER}  ${paint("accent", name.padEnd(width))}${paint("dim", text)}`)
+    }
+    lines.push("", `${GUTTER}${paint("bold", "Options")}`)
+    lines.push(
+        `${GUTTER}  ${"--verbose".padEnd(width)}${paint("dim", "Show every step and the full tool output")}`
+    )
+    lines.push(
+        `${GUTTER}  ${"--debug".padEnd(width)}${paint("dim", "Also print stacks and the environment")}`
+    )
+    lines.push(`${GUTTER}  ${"-h, --help".padEnd(width)}${paint("dim", "Show this help")}`)
+    lines.push(`${GUTTER}  ${"-v, --version".padEnd(width)}${paint("dim", "Print the version")}`)
+    console.log(`${lines.join("\n")}\n`)
+}
+
+/** Edit distance, for suggesting the command someone meant. */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0]
+        row[0] = i
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j]
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1))
+            previous = current
+        }
+    }
+    return row[b.length]
+}
+
+function closestCommand(input) {
+    let best = null
+    for (const command of validCommands) {
+        const d = distance(input.toLowerCase(), command.toLowerCase())
+        if (d <= Math.max(2, Math.floor(command.length / 3)) && (!best || d < best.d)) best = { command, d }
+    }
+    return best?.command ?? null
+}
+
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    printHelp()
+    process.exit(0)
+}
+if (args[0] === "--version" || args[0] === "-v") {
+    console.log(pkg.version)
+    process.exit(0)
+}
+
 const scriptIndex = args.findIndex((arg) => validCommands.has(arg))
 const script = scriptIndex === -1 ? args[0] : args[scriptIndex]
 const nodeArgs = scriptIndex > 0 ? args.slice(0, scriptIndex) : []
@@ -68,5 +166,11 @@ if (webCommands.has(script)) {
     handleProcessResult(runScript(`../dist/scripts/${scriptName}.js`, extraArgs))
 }
 
-console.error(`Unknown script "${script}".`)
+const suggestion = closestCommand(script)
+console.error(
+    `\n${GUTTER}${paint("bad", paint("bold", "error"))}\n${GUTTER}${paint("bold", `Unknown command "${script}"`)}\n\n` +
+        `${GUTTER}${paint("accent", "hint")}  ${
+            suggestion ? `Did you mean ${paint("accent", `catalyst ${suggestion}`)}? ` : ""
+        }Run ${paint("accent", "catalyst --help")} for the list.\n`
+)
 process.exit(1)

package/changelog.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.0.2] - unreleased
+
+This release adds two opt-in features, an animated HTML splash screen for universal apps and experimental WebMCP support, and gives every CLI command the same terminal output. There are no breaking API changes.
+
+### HTML splash screen
+
+A universal app can ship `public/splashscreen.html`. When `WEBVIEW_CONFIG.splashScreen` is set, the native splash image hands over to that page, which stays up until the app's first page has loaded. The new optional `splashScreen.minDuration` keeps it on screen for at least that many milliseconds, and it is dismissed after 10 seconds regardless. The file must be self-contained, and on Android it cannot make network requests. Without the file, the splash works as before.
+
+### WebMCP (experimental)
+
+The new `catalyst-core/webmcp` subpath lets an app expose its actions to AI agents running in the browser. `useTool()` registers a tool from a component, a `tool` field on a route derives one from the route, and `WebMcpProvider` adds the built-in `navigate`, `get_current_route` and `get_page_info` tools. `catalyst-core/webmcp/shim` installs an opt-in `document.modelContext` shim. The API may change in a minor release.
+
+### New root export
+
+The root entry of `catalyst-core` adds `useRouterState`, which returns `{ location, params, navigate, matchedRoutes }` through Catalyst's router context. `catalyst-core/webmcp` uses it to read router state without importing `react-router` from a subpath. The root entry now exports nine names; nothing was removed.
+
+### CLI output
+
+`catalyst start`, `build`, `serve`, the native build and setup commands, and `create-catalyst-app` now print a short header, one line per step with its timing, and one diagnostic block on failure with the error code, location, hint and docs link. The full bundler and native build output moved behind `--verbose`, and `--debug` adds stacks and the environment. `catalyst --help`, `--version` and a "did you mean" suggestion for mistyped commands are new. Once `catalyst serve` has started the production server, the app's own output passes through unchanged.
+
+### Fixes
+
+- `catalyst serve` refuses to serve a build whose inlined values (`PUBLIC_STATIC_ASSET_URL`, `PUBLIC_STATIC_ASSET_PATH`, `CLIENT_ENV_VARIABLES`) differ from the current `config/config.json`, with `PREFLIGHT-022`. It also reports a missing build or a taken port before starting.
+- Fast Refresh now works for components written as JSX in `.js` files instead of reloading the page.
+- `MetaTag` no longer depends on `react-helmet-async`, which is removed from the dependencies. Route metadata from `setMetaData` renders through React 19's `<head>` support, and server-rendered head tags no longer outlive their page after client navigation.
+- `catalyst-core` no longer imports `prop-types` at runtime without declaring it.
+- `Otel.init()` no longer throws `ReferenceError: logger is not defined` when the app has not called `configureLogger()`. It logs to `console` until a global logger is set.
+- Signing passwords are redacted from the output of a failed signed build or `keytool` run.
+- File logs written by `configureLogger()` keep structured fields for plain objects again.
+
+### create-catalyst-app
+
+New apps declare `"type": "module"`, and the Tailwind template's config is `postcss.config.cjs`. `catalyst-core` loads either `postcss.config.cjs` or `postcss.config.js`, so existing apps need no change. `create-catalyst-app` declares `node >= 20.12.0` and runs across that range.
+
 ## [1.0.0] - 2026-09-29
 
 This release freezes the public API. The root entry of `catalyst-core` now exports exactly eight names and nothing else: `RouterDataProvider`, `useCurrentRouteData`, `useRouterData`, `MetaTag`, `split`, `hydrationReady`, `Head`, and `Body`. Anything previously reachable through the root entry but not in that list is no longer public. Applications that import a removed name will fail at build time rather than silently resolving to `undefined`.

package/dist/cli/README.md

@@ -0,0 +1,119 @@
+# CLI output
+
+Every Catalyst command prints through this layer, so the whole CLI reads as one
+program rather than a dozen scripts that happen to ship together.
+
+## The rule
+
+Every command opens with `header("catalyst <command>", subject)` and prints
+nothing at column 0 — every line starts with the two-space gutter, which means
+child processes are always **piped, never inherited**. Progress is append-only:
+each step is one `✓`/`✗` line, the only moving thing is the one-line spinner,
+and anything printed while it spins goes through `progress.log` (it becomes a
+dim `│` sub-line — only if it says something the `✓` line will not). Blank lines
+separate _kinds_, not lines: steps stick together; a titled block (`Output`,
+`Config`, `Notices`), the summary, and a diagnostic each get one blank line
+before them. End with `✓ <result> in <time>` plus a dim line naming the next
+command in cyan. Cyan marks the one thing to act on, green/red/yellow mark
+state, dim marks structure, and the only glyphs are `✓ ✗ ▲ • › ├ └ │ ─`. Fail
+through `diagnostic()`/`buildFailure()` on stderr with a non-zero exit, never a
+raw stack.
+
+## Why piped, never inherited
+
+With `stdio: "inherit"` a child writes straight to the terminal at column 0.
+The parent cannot indent it, cannot suppress it, cannot deduplicate it — and,
+worst of all, never sees the text, so it cannot find the compiler error inside
+it. Two parallel children with inherited stdio also interleave
+non-deterministically.
+
+Piping is what makes `extractBuildErrors` and `codeFrame` reachable. It is the
+difference between:
+
+```
+  error  Command failed with exit code 1
+```
+
+and:
+
+```
+  error  gradle build
+  Unresolved reference: viewBinding
+  at MainActivity.kt:9:25
+
+      8 │         super.onCreate(savedInstanceState)
+  >   9 │         setContentView(viewBinding.root)
+        │                        ^
+```
+
+When you pipe, forward `FORCE_COLOR` if the parent is a TTY — otherwise the
+child sees a pipe and strips its own colour.
+
+## The modules
+
+| File             | What it owns                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| `theme.js`       | Colours, glyphs, gutter, `header()`, `step()`, `row()`, `displayPath()`, `isVerbose()`   |
+| `spinner.js`     | The single live line, plus `withSpinnersPaused()` for anything that must write or ask    |
+| `diagnostic.js`  | `diagnostic()` for one failure, `buildFailure()`, `runtimeFailure()`, `verboseOutput()`  |
+| `buildErrors.js` | Mines real errors out of gradle/xcodebuild/Vite output, incl. gradle's "What went wrong" |
+| `hints.js`       | The short list of failures we can give real advice for                                   |
+| `devOutput.js`   | Classifies a dev/production server's lines; `superviseServer()`, `ensurePortFree()`      |
+
+## Default and --verbose
+
+The default view keeps what someone acts on: steps, results, warnings, errors
+and the one next command. Everything else -- a native build's narration
+("Package.swift already up to date"), Vite's dependency bookkeeping, Node's
+typeless-package warning -- is still produced, and `--verbose` prints it.
+
+In the native builds that split is the `progress.log` level. `info` and
+`success` are narration: they replace the spinner's detail text and leave no
+line behind. `warning`, `error` and `note` always print; use `note` for the rare
+line a person must act on or keep (a manual launch step, where a keystore was
+written). On failure, `--verbose` adds the tool's full output, and `--debug`
+adds stacks and the environment.
+
+## Runtime errors
+
+An error while the server is up -- a component that throws, a fetcher that
+rejects -- is reported once per request through `runtimeFailure()`: the
+registry code and route as the label, the first frame in the app's own code as
+the location with its source, and no library frames unless `--verbose`. The
+SSR handler is bundled into the app, so it cannot import this layer; the server
+exposes the reporter as `globalThis.__catalystReportRuntimeError`. A repeat of
+the same error prints one `✗ Same error again` line.
+
+## Adding a hint
+
+`hints.js` is deliberately short. A hint that guesses is worse than no hint —
+it sends people down the wrong path with confidence. Add one only when the
+pattern reliably implies the cause, and say what to **do**, not what went wrong;
+the message above it already said that.
+
+## Error codes
+
+Codes come from the error registry, not from here. This layer decides only how
+one looks: dim, beside the `error` label, ahead of the scope.
+
+Advice has a precedence. A code we own carries an authored `suggestedAction`,
+and that always beats a pattern guess from `hints.js`. The per-stage wrapper
+codes (`BUNDLE-000`, `IOS-000`, `ANDROID-000`) are the exception: their action
+only says to read the upstream error, which is the text `extractBuildErrors`
+just recovered, so the mined hint wins instead.
+
+That mining stays load-bearing. A wrapped toolchain error preserves the child
+process object, whose message is `Command failed with exit code 1` -- the real
+compiler error lives in the captured transcript, and nothing else recovers it.
+So never add a `hints.js` entry for a failure that has an owned code; that
+advice belongs in the registry.
+
+## Prompts
+
+A prompt and a progress sequence are opposite contracts: progress is output you
+watch, a prompt is a region you drive. They must never overlap. Stop the spinner
+before asking, and collapse the answered prompt to a single settled line
+(`✓ Simulator  iPhone 15 Pro`) so the transcript reads as if it had always been
+a step. In a non-TTY, never prompt — print a diagnostic naming the config key
+and exit 1, because a prompt that waits forever in CI is the worst possible
+output.

package/dist/cli/appConfig.js

@@ -0,0 +1,51 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const { diagnostic } = require("./diagnostic.js")
+
+/**
+ * Read the app's config/config.json with an actionable error.
+ *
+ * The native entry points used to `require()` this at module load, so a missing
+ * or malformed config threw a raw MODULE_NOT_FOUND / SyntaxError stack before
+ * any of the build output appeared.
+ *
+ * Lives here because this layer is CJS and is consumed from both sides: the
+ * native builds require() it directly, the ESM scripts via createRequire.
+ *
+ * @param {string} [cwd] - app root; defaults to the current working directory
+ */
+function loadAppConfig(cwd = process.cwd()) {
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - cwd is the local project directory; the file name is a fixed literal.
+    const configPath = path.join(cwd, "config", "config.json")
+
+    let raw
+    try {
+        raw = fs.readFileSync(configPath, "utf8")
+    } catch (error) {
+        process.stderr.write(
+            diagnostic({
+                message:
+                    error.code === "ENOENT"
+                        ? "Config file not found"
+                        : `Could not read config file: ${error.message}`,
+                file: configPath,
+                hint: "Every Catalyst app needs a config/config.json at its root.",
+            })
+        )
+        process.exit(1)
+    }
+
+    try {
+        return JSON.parse(raw)
+    } catch (error) {
+        process.stderr.write(
+            diagnostic({ message: `Config file is not valid JSON: ${error.message}`, file: configPath })
+        )
+        process.exit(1)
+    }
+}
+
+module.exports = { loadAppConfig }

package/dist/cli/buildErrors.js

@@ -0,0 +1,170 @@
+"use strict"
+
+const { ANSI } = require("./theme.js")
+
+/**
+ * Pull the real errors out of a native build's output.
+ *
+ * A failed gradle or xcodebuild run ends with "Command failed with exit code 1",
+ * which tells you nothing -- the Kotlin or Swift error that actually caused it
+ * is somewhere in the middle of hundreds of lines. Without this you have to
+ * open Android Studio or Xcode to find out what broke.
+ *
+ * Deliberately pattern-matching rather than parsing: both tools change their
+ * output between releases, and a parser that breaks silently is worse than a
+ * matcher that occasionally misses a line. Everything is still on screen and in
+ * the tail we print, so a miss costs nothing.
+ */
+
+// e/ and error: are Kotlin; the file:line:col form covers javac, swiftc and
+// clang. `> Task :app:x FAILED` and `FAILURE:` are gradle's own markers.
+const ERROR_PATTERNS = [
+    // Kotlin: e: file:///path/Foo.kt:12:5 Unresolved reference: bar
+    /^e:\s+(?:file:\/\/)?(?<file>[^\s:]+):(?<line>\d+):(?<column>\d+)\s+(?<message>.+)$/,
+    // Swift / clang / javac: /path/Foo.swift:12:5: error: cannot find 'bar'
+    /^(?<file>[^\s:][^:]*):(?<line>\d+):(?<column>\d+):\s*(?:fatal\s+)?error:\s*(?<message>.+)$/i,
+    // javac without a column
+    /^(?<file>[^\s:][^:]*):(?<line>\d+):\s*error:\s*(?<message>.+)$/i,
+    // Gradle/AGP: "> Task :app:compileDebugKotlin FAILED" then a bare message
+    /^\s*(?:>\s*)?(?:error|FAILURE):\s*(?<message>.+)$/i,
+    // Xcode linker and codesign failures carry no file
+    /^(?<message>(?:ld|clang|codesign|xcodebuild): error:.+)$/i,
+]
+
+// Lines that look like errors but are summary noise, not the cause.
+const NOISE = [
+    /^FAILURE: Build failed with an exception/i,
+    /^\*\s*(What went wrong|Try|Exception is|Get more help)/i,
+    /^Execution failed for task/i,
+    /error: Compilation failed; see the compiler error output/i,
+    /^\s*>\s*Compilation error\. See log for more details/i,
+    /^The following build commands failed:/i,
+    /^\(\d+ failures?\)$/i,
+]
+
+// Vite/rollup errors. Kept separate from the native patterns: a Vite build
+// can never emit Kotlin or Xcode markers, and one flat list would become a
+// junk drawer where every toolchain's noise matches every other's.
+const VITE_ERROR_PATTERNS = [
+    // [plugin:name] Could not load /path (imported by other/path): ENOENT...
+    /\[(?:vite|plugin)[^\]]*\]\s*(?<message>Could not (?:load|resolve)[^:]*)(?::.*)?$/i,
+    // Failed to resolve import "x" from "y"
+    /^(?<message>Failed to resolve (?:import|entry)[^.]*)\.?$/i,
+    // file.js:12:3: error: message   (esbuild transform failures)
+    /^(?<file>[^\s:][^:]*):(?<line>\d+):(?<column>\d+):\s*ERROR:\s*(?<message>.+)$/i,
+    // Bare "error during build:" is a header, not a message -- see NOISE.
+]
+
+// "imported by <file>" tells us which of the user's files to point at, which
+// is far more useful than the missing path they typed.
+const IMPORTED_BY = /\(imported by ([^)]+)\)/
+
+const MAX_ERRORS = 5
+
+/**
+ * @param {string} output - everything the build printed
+ * @returns {Array<{file?: string, line?: number, column?: number, message: string}>}
+ */
+function extractBuildErrors(output, { toolchain = "native" } = {}) {
+    if (!output) return []
+
+    const patterns = toolchain === "vite" ? VITE_ERROR_PATTERNS : ERROR_PATTERNS
+
+    const found = []
+    const seen = new Set()
+
+    for (const raw of String(output).split("\n")) {
+        const line = raw.replace(ANSI, "").trimEnd()
+        if (!line.trim()) continue
+        if (NOISE.some((pattern) => pattern.test(line.trim()))) continue
+
+        for (const pattern of patterns) {
+            const match = pattern.exec(line.trim())
+            if (!match) continue
+
+            const { file, line: lineNo, column, message } = match.groups
+            const importedBy = IMPORTED_BY.exec(line)
+            const key = `${file || ""}:${lineNo || ""}:${message}`
+            if (seen.has(key)) break
+            seen.add(key)
+
+            found.push({
+                file: file || (importedBy ? importedBy[1].trim() : undefined),
+                line: lineNo ? Number(lineNo) : undefined,
+                column: column ? Number(column) : undefined,
+                // The "(imported by x)" clause becomes the `file` above, so
+                // repeating it in the message is noise.
+                message: message.replace(IMPORTED_BY, "").replace(/\s+/g, " ").trim(),
+            })
+            break
+        }
+
+        if (found.length >= MAX_ERRORS) break
+    }
+
+    if (found.length === 0 && toolchain !== "vite") {
+        const wrong = gradleWhatWentWrong(output)
+        if (wrong) found.push(wrong)
+    }
+
+    return found
+}
+
+/**
+ * Gradle's own explanation, for failures that are not compiler errors (a
+ * missing SDK, a dependency that will not resolve, a bad plugin version):
+ *
+ *     * What went wrong:
+ *     Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'.
+ *     > SDK location not found. Define a valid SDK location with ...
+ *
+ * The innermost "> " line is the cause; the line above it is context.
+ */
+function gradleWhatWentWrong(output) {
+    const lines = String(output).replace(ANSI, "").split("\n")
+    const start = lines.findIndex((line) => /^\*\s*What went wrong:/.test(line.trim()))
+    if (start === -1) return null
+
+    const block = []
+    for (const line of lines.slice(start + 1)) {
+        const trimmed = line.trim()
+        if (!trimmed || /^\*\s/.test(trimmed)) break
+        block.push(trimmed)
+    }
+    if (block.length === 0) return null
+
+    const causes = block.filter((line) => line.startsWith(">")).map((line) => line.replace(/^>+\s*/, ""))
+    const message = (causes.length ? causes[causes.length - 1] : block[0])
+        // Gradle's sentences run long; the first one carries the meaning.
+        .replace(/^(.+?\.)\s+[A-Z].*$/, "$1")
+    return { message }
+}
+
+/**
+ * The tail of a build's output, for when no error could be recognised.
+ * Better to show the last thing the tool said than to say nothing.
+ */
+// Advice every gradle failure prints regardless of cause. It crowds out the
+// real message, which is worse than useless here: the tail exists precisely
+// because nothing was recognised, so every line it spends must be evidence.
+const TAIL_NOISE = [
+    /^>?\s*Run with --(stacktrace|info|debug|scan)/i,
+    /^>?\s*Get more help at/i,
+    /^Deprecated Gradle features were used/i,
+    /^You can use '--warning-mode all'/i,
+    /^For more on this, please refer to/i,
+    /^BUILD FAILED in /i,
+    /^\*\s*(Try|Get more help)/i,
+]
+
+function outputTail(output, lines = 12) {
+    if (!output) return ""
+    return String(output)
+        .replace(ANSI, "")
+        .split("\n")
+        .filter((line) => line.trim() && !TAIL_NOISE.some((pattern) => pattern.test(line.trim())))
+        .slice(-lines)
+        .join("\n")
+}
+
+module.exports = { extractBuildErrors, outputTail, MAX_ERRORS }

package/dist/cli/buildWarnings.js

@@ -0,0 +1,28 @@
+"use strict"
+
+const { ANSI } = require("./theme.js")
+
+/**
+ * Warnings worth showing from a bundle that otherwise succeeded.
+ *
+ * The vite configs already drop the advisories nobody can act on; anything
+ * still here is a real signal (circular dependency, oversized chunk) that was
+ * previously captured and discarded.
+ */
+function bundleWarnings(output, label) {
+    if (!output) return []
+    const seen = new Set()
+    const found = []
+    for (const raw of String(output).split("\n")) {
+        const line = raw.replace(ANSI, "").trim()
+        if (!line) continue
+        if (!/^(warning|\(!\))/i.test(line) && !/^\[plugin/.test(line)) continue
+        const message = line.replace(/^\(!\)\s*/, "").replace(/^warning:?\s*/i, "")
+        if (!message || seen.has(message)) continue
+        seen.add(message)
+        found.push(`${label} ${message}`)
+    }
+    return found
+}
+
+module.exports = { bundleWarnings }