catalyst-core 1.0.1 → 1.0.2-canary.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/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,50 @@
+"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()) {
+    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 }